From 5e6d708038ec7b99292edc12f11c00fa79020b28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dieter=20Schl=C3=BCter?= Date: Thu, 18 Jun 2026 16:30:46 +0200 Subject: [PATCH] docs: Betriebsprofile, Ollama, Web-UI und Startup-Hinweise dokumentieren - README: Ollama als LLM-Backend (Alternative zu llama.cpp) mit .env-Snippet - README: Warnung dass Gateway ohne LLM-Server startet, Fehler erst beim ersten Request - BEDIENUNGSANLEITUNG: Abschnitt 4 zu vollstaendiger Profilbeschreibung ausgebaut (cloud / hybrid / local-dev je mit Hardware, Software, Kosten, Latenz, Qualitaet, Einrichtungsbefehlen und Vergleichstabelle) - BEDIENUNGSANLEITUNG: neues Kapitel A0 Web-Interface (Oberflaeche, Ablaeufe, Fehlertabelle) Co-Authored-By: Claude Sonnet 4.6 --- BEDIENUNGSANLEITUNG.md | 230 +++++++++++++++++++++++++++++++++++++++-- README.md | 37 +++++++ 2 files changed, 261 insertions(+), 6 deletions(-) diff --git a/BEDIENUNGSANLEITUNG.md b/BEDIENUNGSANLEITUNG.md index 0047442..04250b5 100644 --- a/BEDIENUNGSANLEITUNG.md +++ b/BEDIENUNGSANLEITUNG.md @@ -60,13 +60,164 @@ echo ${OPENROUTER_API_KEY:0:8} # zeigt nur den Anfang zur Kontrolle ## 4. Profil (Betriebsart) wählen -| Profil | Bedeutung | Key nötig? | -|-------------|-----------------------------------------|------------| -| `local-dev` | alles lokal (eigene KI) | nein | -| `hybrid` | STT/TTS Cloud, Haupt-LLM lokal | ja | -| `cloud` | alles über OpenRouter (Standard) | ja | +Das Gateway kennt drei Betriebsprofile. Jedes Profil legt fest, welche der drei +Pipeline-Stufen **STT** (Sprache → Text), **LLM** (Antwort generieren) und **TTS** +(Text → Sprache) lokal oder in der Cloud laufen. -Dauerhaft in `.env`: `VA_PROFILE=cloud` — oder einmalig: `VA_PROFILE=cloud make run`. +Umschalten — dauerhaft in `.env`: +```bash +VA_PROFILE=cloud # Standard +VA_PROFILE=hybrid +VA_PROFILE=local-dev +``` +Oder einmalig für einen Start: `VA_PROFILE=cloud make run`. + +--- + +### Profil `cloud` — alles über OpenRouter (Empfehlung für den Einstieg) + +| Stufe | Läuft auf | Standard-Modell | +|-------|-----------|-----------------| +| STT | OpenRouter (remote) | `openai/whisper-large-v3` | +| LLM | OpenRouter (remote) | `openai/gpt-4.1-mini` | +| TTS | OpenRouter (remote) | `openai/gpt-4o-mini-tts` | + +**Was muss laufen?** Nur das Gateway (`make run`). Sonst nichts. + +**Hardware:** Beliebiger Rechner mit Internetzugang — keine GPU nötig. + +**Software:** Nur das Gateway (`pip install -e .[test]`). + +**API-Key:** `OPENROUTER_API_KEY` erforderlich. + +**Kosten:** ca. 1–2 ¢ pro Sprech-Runde (STT + TTS sind die Kostentreiber; LLM ist +nahezu kostenlos). Grob ~20–40 ¢ pro 10-Minuten-Gespräch. Genaue Zahlen: +OpenRouter-Dashboard → Activity/Usage. + +**Antwortgeschwindigkeit:** ~4 s Round-Trip (STT ~1,2 s + LLM ~0,7 s + TTS ~1,9 s, +gemessen gegen OpenRouter). Streaming (`audio_stream=true`) lässt die erste Silbe +früher kommen — subjektiv schneller. + +**Beste Modell-Kombination (bewährt, inkl. Plattdeutsch):** +```bash +OPENROUTER_STT_MODEL=openai/whisper-large-v3 +OPENROUTER_LLM_MODEL=google/gemini-3.1-flash-lite +OPENROUTER_TTS_MODEL=google/gemini-3.1-flash-tts-preview +OPENROUTER_TTS_VOICE=Zephyr +``` + +--- + +### Profil `hybrid` — STT/TTS Cloud, LLM lokal + +| Stufe | Läuft auf | Provider | +|-------|-----------|----------| +| STT | OpenRouter (remote) | `openrouter` | +| LLM | eigener Rechner | `local-openai-compatible` (llama.cpp oder Ollama) | +| TTS | OpenRouter (remote) | `openrouter` | + +**Was muss laufen?** Gateway + lokaler LLM-Server. + +**Hardware:** NVIDIA-GPU empfohlen (für llama.cpp-Modelle mit >7B Parametern praktisch +Pflicht); für Ollama mit kleinen Modellen auch ohne GPU möglich (langsamer). + +**Software:** +- llama.cpp: `make llm-up` (Docker, GPU) — erst warten bis `make llm-status` „HTTP OK" zeigt +- Ollama: `ollama serve` + `ollama pull ` (kein Docker nötig) + +**API-Key:** `OPENROUTER_API_KEY` erforderlich (für STT + TTS). + +**Kosten:** ~0,5–1,5 ¢/Runde (nur TTS remote — STT ist zwar auch remote, aber billig). +Ersparnis gegenüber `cloud` nur ~10–15 %; der echte Vorteil ist **Datenschutz** +(Spracheingabe + KI-Verarbeitung verlassen den Rechner nicht). + +**Antwortgeschwindigkeit:** STT und TTS wie `cloud`. LLM-Latenz hängt vom lokalen Modell +und GPU ab — mit `LOCAL_LLM_DISABLE_REASONING=true` und einem Sprach-System-Prompt sind +~0,7 s (Qwen3-35B auf RTX 3090) erreichbar. + +**Einrichten (llama.cpp):** +```bash +make llm-up # Docker-Container starten (GPU 1, Port 8001) +make llm-status # warten bis "HTTP OK" +VA_PROFILE=hybrid make run +``` + +**Einrichten (Ollama):** +```bash +# in .env: +LOCAL_LLM_BASE_URL=http://127.0.0.1:11434/v1 +LOCAL_LLM_API_KEY=ollama +LOCAL_LLM_MODEL=qwen3:30b-a3b # oder anderes Modell aus 'ollama list' +VA_PROFILE=hybrid make run +``` + +--- + +### Profil `local-dev` — alles lokal (kein API-Key, maximaler Datenschutz) + +| Stufe | Läuft auf | Provider | +|-------|-----------|----------| +| STT | eigener Rechner | `faster-whisper` | +| LLM | eigener Rechner | `local-openai-compatible` (llama.cpp oder Ollama) | +| TTS | eigener Rechner | `piper` | + +**Was muss laufen?** Gateway + lokaler LLM-Server. STT und TTS laufen im Gateway-Prozess. + +**Hardware:** +- NVIDIA-GPU für llama.cpp (35B-Modell braucht ~20 GB VRAM) +- Für Ollama mit kleinen Modellen (7B) geht auch CPU, aber langsam +- Kein Internetzugang nötig (vollständig offline betreibbar) + +**Software:** +```bash +pip install -e .[local] # faster-whisper + piper-tts installieren +# Piper-Stimmmodell bereitstellen (einmalig): +# .onnx + .onnx.json nach ~/.local/share/piper/voices/ kopieren +# llama.cpp: +make llm-up && make llm-status # warten auf "HTTP OK" +# oder Ollama: +ollama serve && ollama pull qwen3:30b-a3b +``` + +**API-Key:** keiner nötig. + +**Kosten:** keine API-Kosten — nur Strom (GPU-Betrieb). + +**Antwortgeschwindigkeit:** STT (`faster-whisper base` auf CPU) ~1–3 s; LLM wie bei +`hybrid`; TTS (`piper`, in-process) ~0,3–0,5 s für einen Satz. Gesamtlatenz +vergleichbar mit `cloud`, aber abhängig von der GPU-Auslastung. Erster Turn nach +Server-Start ist wärmer als früher (Modelle werden beim Start vorgeladen). + +**Sprach­qualität:** piper klingt synthetischer als Cloud-TTS (Gemini/Zephyr). +Whisper `base` ist schnell, aber schwächer bei Dialekt als `large-v3`. Für +bessere Qualität: `FASTER_WHISPER_MODEL=large-v3` + `FASTER_WHISPER_DEVICE=cuda`. + +**Einrichten:** +```bash +make llm-up # erst warten bis make llm-status "HTTP OK" zeigt +VA_PROFILE=local-dev make run +``` +> **Achtung:** Das Gateway startet auch ohne laufenden LLM-Server fehlerfrei hoch. +> Der Fehler „All connection attempts failed" erscheint erst beim ersten Request. +> Deshalb immer erst `make llm-up` vollständig abwarten. + +--- + +### Vergleich auf einen Blick + +| | `cloud` | `hybrid` | `local-dev` | +|---|---------|----------|-------------| +| **STT** | remote | remote | lokal | +| **LLM** | remote | **lokal** | **lokal** | +| **TTS** | remote | remote | **lokal** | +| **API-Key nötig** | ja | ja | nein | +| **GPU nötig** | nein | empfohlen | empfohlen | +| **Internetverbindung** | ja | ja | nein | +| **Kosten/Runde** | ~1–2 ¢ | ~0,5–1,5 ¢ | ~0 (nur Strom) | +| **Round-Trip** | ~4 s | ~3–5 s | ~3–6 s | +| **Sprachqualität TTS** | hoch | hoch | mittel (piper) | +| **Datenschutz** | gering | hoch | maximal | +| **Empfohlen für** | Einstieg, Senioren | Datenschutz + gutes TTS | Offline, kein API-Key | ## 5. Starten und Stoppen @@ -92,6 +243,73 @@ Port ändern: `PORT=8005 make run` (einmalig) bzw. `PORT=` in `.env` (dauerhaft) # Teil A — Mit dem Assistenten sprechen +## A0. Web-Interface im Browser (einfachster Einstieg) + +Das Gateway liefert unter `/` eine fertige Web-Oberfläche aus — kein zusätzliches +Programm nötig, nur ein Browser. + +### Aufrufen + +``` +http://localhost:8003/ ← am Server selbst (Mikrofon funktioniert) +http://:8003/ ← aus dem LAN (nur Text-Chat; Mikrofon braucht HTTPS) +``` + +> Mikrofon im Browser geht nur über `localhost` oder HTTPS. Für Sprache von einem +> anderen Gerät im Heimnetz: HTTPS-Zugang einrichten (siehe README → „Remote von +> unterwegs"). + +### Oberfläche auf einen Blick + +``` +┌─────────────────────────────────────────────────────┐ +│ Voice Assistant [☀️/🌙] Angemeldet als … │ +├─────────────────────────────────────────────────────┤ +│ │ +│ (Nachrichtenverlauf) │ +│ │ +├───────────────────────────────────┬─────────────────┤ +│ Texteingabe … [Senden] │ [🎤] [Stimme ▾] │ +└───────────────────────────────────┴─────────────────┘ +``` + +| Element | Bedeutung | +|---------|-----------| +| **Texteingabe + Senden** | Nachricht tippen, Enter oder „Senden" drücken | +| **🎤 Mikrofon-Button** | einmal tippen → Aufnahme startet (Button wird rot); erneut tippen → Aufnahme stoppt, Sprache wird verarbeitet | +| **Stimme ▾** | TTS-Anbieter wählen: leer = Server-Default (piper), `chatterbox` = neuronale Stimme, `openrouter` = Cloud-TTS | +| **☀️ / 🌙** | Tag-/Nacht-Modus umschalten (folgt sonst automatisch dem System) | +| **Angemeldet als …** | SSO-Identität; „Gast" wenn AUTH deaktiviert oder kein SSO-Cookie vorhanden | + +### Typischer Ablauf (Text) + +1. Seite aufrufen → Statuszeile ist leer, Eingabefeld aktiv. +2. Text eintippen (z. B. „Wie wird das Wetter morgen?") → **Enter** oder **Senden**. +3. Eigene Nachricht erscheint als blaue Blase rechts; Assistent antwortet (grau links), + Antwort wird gleichzeitig **vorgelesen**. +4. Nächste Frage eintippen — der Gesprächsverlauf bleibt erhalten (solange die + Seite offen ist). + +### Typischer Ablauf (Sprache) + +1. **🎤** antippen → Button wird rot, Statuszeile zeigt „Aufnahme …". +2. Sprechen. +3. **🎤** erneut antippen → Aufnahme stoppt; Statuszeile wechselt zu + „verarbeite Sprache …" → „denkt …". +4. Transkription erscheint als blaue Blase, Antwort als graue Blase — und wird + vorgelesen. + +### Fehlermeldungen im Chat verstehen + +| Meldung | Ursache | Abhilfe | +|---------|---------|---------| +| „Verbindungsfehler" | WebSocket-Verbindung konnte nicht aufgebaut werden | Seite neu laden; Gateway-Prozess prüfen (`make run`) | +| „Fehler: All connection attempts failed" | Konfigurierter LLM-/STT-/TTS-Dienst nicht erreichbar | Abhängigen Dienst starten (z. B. `make llm-up`) | +| „Mikrofon-Zugriff fehlgeschlagen" | Browser hat Mikrofon nicht freigegeben | Browser-Einstellungen → Mikrofon erlauben; oder HTTPS nutzen | +| „Aufnahme nicht unterstützt" | Sehr alter Browser / iOS < 14.3 | Browser / iOS aktualisieren | + +--- + ## A1. Sprech-Loop: sprechen → hören → erneut sprechen (empfohlen) Der mitgelieferte Helfer nimmt vom Mikrofon auf, schickt die Aufnahme an das Gateway diff --git a/README.md b/README.md index f8a47ee..46c0bc1 100644 --- a/README.md +++ b/README.md @@ -183,9 +183,46 @@ make llm-up # 35B-Modell laden; mit make llm-status auf "HTTP OK" warte make run # Gateway nutzt jetzt das lokale, unzensierte Modell als zentrale KI ``` +> **Wichtig:** Gateway und LLM-Server starten **unabhängig** voneinander — `make run` +> läuft auch ohne laufenden LLM-Container hoch, ohne Fehlermeldung. Der Fehler +> „All connection attempts failed" erscheint erst beim **ersten Request**. Daher immer +> zuerst `make llm-up` vollständig abwarten (Status „HTTP OK"), dann `make run`. + > `VA_PROFILE` ist in `.env` dauerhaft setzbar (aktuell `local-dev`) oder pro Lauf > voranstellbar (`VA_PROFILE=hybrid make run`). Prüfen: `curl http://localhost:8080/api/config`. +## Ollama als LLM-Backend (Alternative) + +Wer statt des llama.cpp-Docker-Containers lieber **Ollama** nutzt, braucht keinen +eigenen Start-Skript: Ollama verwaltet den Server-Prozess selbst und bietet eine +**OpenAI-kompatible API** — der Provider `local-openai-compatible` verbindet sich +direkt damit. + +**Voraussetzung:** Ollama ist installiert (`ollama --version`) und das gewünschte +Modell bereits heruntergeladen (`ollama pull qwen3:30b-a3b`). + +Drei Zeilen in `.env` anpassen (der Rest bleibt unverändert): + +```bash +LOCAL_LLM_BASE_URL=http://127.0.0.1:11434/v1 +LOCAL_LLM_API_KEY=ollama # Ollama erwartet einen beliebigen Wert +LOCAL_LLM_MODEL=qwen3:30b-a3b # exakter Name aus 'ollama list' +``` + +Danach Gateway starten — kein `make llm-up` nötig, Ollama läuft im Hintergrund: + +```bash +VA_PROFILE=local-dev make run # oder hybrid, wenn STT/TTS Cloud bleiben sollen +``` + +**Hinweise:** +- `LOCAL_LLM_DISABLE_REASONING=true` (Standard) schickt `chat_template_kwargs: + {enable_thinking: false}` — Ollama ignoriert dieses Feld; die Denkphase muss + im Modell-Alias selbst abgeschaltet werden (`qwen3:30b-a3b` statt + `qwen3:30b-a3b:thinking`) oder über den System-Prompt. +- `ollama list` zeigt alle lokal vorhandenen Modelle mit exaktem Namen. +- Verfügbare Modelle: `https://ollama.com/library` (Suche nach `qwen3`, `llama`, …). + ## API-Überblick | Methode & Pfad | Zweck |