audio-processing, laravel-support, skript, readme

2026-10-15 23:36:18 +02:00
1 parent 99517f483a
commit 2e2490c1bc
@@ -0,0 +1,164 @@
+# Laravel (laravel/ai) mit dem zentralen LocalAI-Server
+
+Das [Laravel AI SDK](https://laravel.com/docs/ai-sdk) spricht den Server wie einen OpenAI-kompatiblen Anbieter an. Damit gehen Agenten mit Tools, Streaming, Embeddings, Transkription (Spracheingabe) und Bildgenerierung.
+
+> Der Server-Teil ist getestet (Messwerte unten). Der Laravel-Code hier folgt der SDK-Doku, ist aber noch nicht in einer echten App gelaufen.
+
+## Was der Server bietet
+
+| Modell-ID (Aliase) | Endpoint | SDK-Funktion | Dauer (gemessen) |
+|---|---|---|---|
+| `qwen3.5-35b-a3b`, `glm-4.7-flash`, `qwen3.5-9b` | `/v1/chat/completions` | Agent, Text, Tools, Streaming | ~850 t/s Prompt, ~47 t/s Antwort |
+| `nomic-embed` | `/v1/embeddings` | `Embeddings` (768 Dimensionen) | |
+| `whisper` (`whisper-1`) | `/v1/audio/transcriptions` | `Transcription` | ~0,5 s für 7 s Sprache |
+| `z-image` (`gpt-image-1`, `dall-e-3`, `dall-e-2`) | `/v1/images/generations` | `Image` | 512²: ~11 s, 1024²: ~40 s, 1536×1024: ~65 s |
+
+**Bilder verdrängen das Chat-Modell.** Beide passen nicht gleichzeitig in die 16 GB VRAM. Der erste Bild-Request lädt das Bildmodell (+ einige Sekunden), der nächste Chat-Request lädt das Chat-Modell zurück (~5 s). Whisper, Autocomplete und Embeddings bleiben immer geladen.
+
+## 1. Netz und Zugang
+
+- Der Rechner, auf dem Laravel läuft, muss in `ALLOWED_NETS` (Server-`.env`) liegen: localhost, LAN `192.168.178.0/24` oder NetBird `100.73.0.0/16`. Ein öffentlicher Server braucht also einen NetBird-Peer.
+- Der API-Key ist `LLM_API_KEY` aus der Server-`.env` (`./scripts/start.sh --show-key`).
+
+## 2. Konfiguration
+
+`.env` der Laravel-App:
+```dotenv
+LOCAL_AI_URL=http://100.73.82.219:8800/v1
+LOCAL_AI_API_KEY=<KEY>
+```
+
+`config/ai.php`:
+```php
+'providers' => [
+    // Text, Agent, Embeddings, Transkription
+    'local' => [
+        'driver' => 'openai-compatible',
+        'url'    => env('LOCAL_AI_URL'),
+        'key'    => env('LOCAL_AI_API_KEY'),
+        'models' => [
+            'text'          => ['default' => 'qwen3.5-35b-a3b'],
+            'embeddings'    => ['default' => 'nomic-embed', 'dimensions' => 768],
+            'transcription' => ['default' => 'whisper'],
+        ],
+    ],
+
+    // Bilder: openai-compatible kann keine Bilder, der OpenAI-Treiber schon.
+    // Er schickt "gpt-image-1" & Co. – der Server kennt diese Namen als Aliase.
+    'local-images' => [
+        'driver' => 'openai',
+        'key'    => env('LOCAL_AI_API_KEY'),
+        'url'    => env('LOCAL_AI_URL'),
+    ],
+],
+```
+`local` in `config/ai.php` als Standard für Text, Embeddings und Transkription eintragen und `local-images` als Standard für Bilder. Die genauen Schlüssel für die Standard-Provider stehen in der veröffentlichten `config/ai.php`.
+
+## 3. Agent
+
+```bash
+php artisan make:agent Assistant
+```
+```php
+$response = (new Assistant)->prompt('Fasse die offenen Rechnungen zusammen', timeout: 300);
+
+// im Controller als Stream (SSE) an den Browser
+return (new Assistant)->stream($text);
+```
+- **Timeouts großzügig setzen.** Das Laden eines Modells kann einige Sekunden bis Minuten dauern. Längere Agent-Läufe besser als Queue-Job.
+- Tool-Calling klappt mit `qwen3.5-35b-a3b` und `glm-4.7-flash` zuverlässig, mit `qwen3.5-9b` bei mehrstufigen Aufgaben schlechter.
+- Alle Anwendungen sollten dasselbe Chat-Modell nutzen (opencode, Continue, Laravel). Ein anderes Modell löst bei jedem Wechsel einen Modellwechsel aus.
+
+## 4. Spracheingabe (Aufnahmetaste)
+
+Ablauf: Browser nimmt auf → `POST /voice/transcribe` → Text anzeigen und bestätigen → `POST /voice/ask` → Agent streamt die Antwort.
+
+```php
+use App\Ai\Agents\Assistant;
+use Illuminate\Http\Request;
+use Laravel\Ai\Transcription;
+
+Route::post('/voice/transcribe', function (Request $request) {
+    $request->validate(['audio' => 'required|file|max:20480']);
+
+    return ['text' => trim((string) Transcription::fromUpload($request->file('audio'))->generate())];
+});
+
+Route::post('/voice/ask', function (Request $request) {
+    $request->validate(['text' => 'required|string|max:4000']);
+
+    return (new Assistant)->stream($request->string('text'));
+});
+```
+
+```js
+let rec, chunks = [];
+const mime = MediaRecorder.isTypeSupported('audio/webm;codecs=opus') ? 'audio/webm;codecs=opus' : 'audio/mp4';
+
+async function startRecording() {
+  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+  rec = new MediaRecorder(stream, { mimeType: mime });
+  chunks = [];
+  rec.ondataavailable = e => chunks.push(e.data);
+  rec.onstop = async () => {
+    stream.getTracks().forEach(t => t.stop());
+    const fd = new FormData();
+    fd.append('audio', new Blob(chunks, { type: mime }), mime.includes('webm') ? 'voice.webm' : 'voice.m4a');
+    const res = await fetch('/voice/transcribe', {
+      method: 'POST', body: fd,
+      headers: { 'X-CSRF-TOKEN': document.querySelector('meta[name=csrf-token]').content },
+    });
+    const { text } = await res.json();
+    showForConfirmation(text);   // eigenes UI: Text anzeigen/bearbeiten, dann an /voice/ask senden
+  };
+  rec.start();
+}
+const stopRecording = () => rec?.stop();
+// Taste: pointerdown → startRecording(), pointerup → stopRecording()
+```
+
+- **HTTPS ist Pflicht.** Browser geben das Mikrofon nur auf `https://` oder `localhost` frei. Das betrifft die Laravel-App, nicht die Verbindung von Laravel zum KI-Server.
+- **Formate:** Chrome/Firefox liefern WebM/Opus, Safari MP4/AAC. Der Server wandelt alles per ffmpeg selbst um, Laravel muss nichts konvertieren (getestet: WAV, WebM, M4A).
+- **Sprache:** Der Server erkennt die Sprache automatisch.
+- **Bestätigung vor dem Absenden:** Whisper verhört sich manchmal bei Namen und Fachbegriffen. Bei Agenten, deren Tools etwas ausführen, den Text deshalb erst anzeigen.
+
+## 5. Bilder
+
+```php
+use Laravel\Ai\Image;
+
+$path = Image::of('Ein rotes Fahrrad vor einer gelben Hauswand')
+    ->landscape()
+    ->timeout(300)
+    ->generate()          // mit 'local-images' als Standard-Provider für Bilder
+    ->store();
+```
+- `square()` = 1024×1024 (~40 s), `landscape()`/`portrait()` = 1536×1024 (~65 s). `quality()` wird ignoriert.
+- Bilder am besten in einem Queue-Job erzeugen (`->queue()->then(...)`), nicht im Web-Request.
+- Als **Agent-Tool**: `php artisan make:tool GenerateImage`. In `handle()` das Bild erzeugen, speichern und die URL zurückgeben. Bedenken: Danach muss das Chat-Modell neu geladen werden (~5 s), bevor der Agent weiterantwortet.
+- Falls der OpenAI-Treiber in einer neueren SDK-Version Parameter schickt, die der Server ablehnt, geht es auch direkt:
+  ```php
+  $b64 = Http::withToken(config('ai.providers.local.key'))->timeout(300)
+      ->post(config('ai.providers.local.url').'/images/generations', [
+          'model' => 'z-image', 'prompt' => $prompt, 'size' => '1024x1024',
+      ])->json('data.0.b64_json');
+  Storage::put($path, base64_decode($b64));
+  ```
+
+## 6. Fehlersuche
+
+| Symptom | Ursache |
+|---|---|
+| 401 | API-Key falsch |
+| 403 | Laravel-Server nicht in `ALLOWED_NETS` |
+| Timeout beim ersten Request | Modell lädt noch → Timeout erhöhen |
+| Bild dauert > 1 min | normal bei 1536×1024 und nach einem Modellwechsel |
+| Mikrofon-Abfrage erscheint nicht | Seite läuft nicht über HTTPS |
+| Leeres Transkript | Aufnahme zu kurz/stumm. Mindestlänge im Frontend prüfen |
+
+Schnelltest vom Laravel-Server aus:
+```bash
+curl -H "Authorization: Bearer $KEY" http://<server>:8800/v1/audio/transcriptions -F model=whisper -F file=@test.webm
+curl -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' http://<server>:8800/v1/images/generations \
+  -d '{"model":"z-image","prompt":"a red bicycle","size":"512x512"}' | head -c 200
+```