docs: Dokumentation vollständig überarbeitet und neu strukturiert
README.md auf kompakte Landing Page reduziert (~84 Zeilen): Kurzbeschreibung, Features, 30-Sekunden-Quickstart, Dokumentenübersicht mit Zielgruppen-Einstiegspunkten, Projektstruktur. BEDIENUNGSANLEITUNG.md von Grund auf neu geschrieben (~1530 Zeilen): - Klickbares Inhaltsverzeichnis (14 Abschnitte + 4 Anhänge) - Zielgruppen-Labels je Abschnitt (👤 Endnutzer / 🔧 Admin / 💻 Entwickler) - Konsolidierte Profilbeschreibungen (cloud/hybrid/local-dev) mit Hardware, Software, Kosten, Latenz, Qualität, Einrichtungsbefehlen — alles an einer Stelle - Vollständige Querverweise zwischen Abschnitten - Anhang A: alle Umgebungsvariablen als vollständige Referenz - Anhang B: alle API-Endpunkte (REST + WebSocket) mit Event-Typen - Anhang C: Provider-Übersicht - Anhang D: Sachregister mit >40 Einträgen Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Dieter Schlüter
parent
5e6d708038
commit
5b9b9bbdcf
2 changed files with 1300 additions and 1034 deletions
File diff suppressed because it is too large
Load diff
495
README.md
495
README.md
|
|
@ -1,489 +1,84 @@
|
||||||
# Voice Assistant Gateway
|
# Voice Assistant Gateway
|
||||||
|
|
||||||
Modulares FastAPI-Gateway für einen **seniorengerechten Sprachassistenten** —
|
Modulares FastAPI-Gateway für einen **seniorengerechten Sprachassistenten** —
|
||||||
cloud-first, aber hybrid/lokal betreibbar, mit austauschbaren Audio-Endpunkten und
|
cloud-first, aber hybrid/lokal betreibbar, mit austauschbaren STT-/LLM-/TTS-Providern.
|
||||||
STT-/LLM-/TTS-Providern.
|
Jede Achse — Hardware, Betrieb, Software — ist frei konfigurierbar, ohne Code zu ändern.
|
||||||
|
|
||||||
Jede Achse — **Hardware** (Audio In/Out), **Betrieb** (lokal/cloud) und **Software**
|
---
|
||||||
(lokale/remote KI) — ist frei konfigurierbar, ohne Code zu ändern. Konzept und
|
|
||||||
Details: [`Docs/voice-assistant-architecture.md`](Docs/voice-assistant-architecture.md).
|
|
||||||
Praktische Bedienung: [`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md).
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- **Pipeline mit getrennter Semantik/Sprache:** STT → Input-Cleaner → LLM → Spoken-Adapter → TTS-Normalizer → TTS
|
- **Sprach-Pipeline:** STT → Input-Cleaner → LLM → Spoken-Adapter → TTS-Normalizer → TTS
|
||||||
- **Provider austauschbar** über Registry (OpenRouter remote; lokales STT via faster-whisper `.[local]`; **lokales TTS via piper** (schnell) **und chatterbox** (hohe Qualität + Voice-Cloning, eigener Dienst))
|
- **Provider austauschbar** über Registry: OpenRouter (Cloud), faster-whisper (STT lokal), piper (TTS lokal, schnell), chatterbox (TTS lokal, hohe Qualität + Voice-Cloning)
|
||||||
- **Aussprache-Normalisierung** vor dem TTS (Ordinalia/Einheiten/Abkürzungen + YAML-Lexikon, provider-abhängig `TTS_NORMALIZE_LEVEL`); Pflege per `scripts/add_pronunciation.py`
|
- **Geschichtete Konfiguration** mit Profilen (`cloud` / `hybrid` / `local-dev`)
|
||||||
- **Geschichtete Konfiguration** mit Profilen (`local-dev` / `hybrid` / `cloud`)
|
- **Routing auf jeder Ebene:** Global → Profil → Nutzer → Session → Request
|
||||||
- **Routing auf jeder Ebene:** Default → Profil → Nutzer → Session → Request
|
|
||||||
- **Authentifizierung** (Bearer-Token) + persistente Nutzer/Sessions (SQLite)
|
- **Authentifizierung** (Bearer-Token) + persistente Nutzer/Sessions (SQLite)
|
||||||
- **Resilienz:** Fallback-Ketten je Modul (Provider fällt aus → nächster) + Metriken
|
- **Resilienz:** Fallback-Ketten je Modul + In-Memory-Metriken (JSON + Prometheus)
|
||||||
- **Betrieb:** Tageskontingent pro Nutzer (`429`) + zweistufige Notfall-Eskalation (Stichwörter + LLM)
|
- **Gesprächsgedächtnis** pro Session (Verlauf) + Langzeit-Erinnerungen pro Nutzer (manuell + automatisch)
|
||||||
- **Gesprächsgedächtnis pro Session:** Verlauf wird gespeichert und fließt ins LLM
|
- **WebSocket-Streaming:** Token-Streaming (LLM), Audio-Streaming (satzweises TTS), Sprach-Eingang, VAD, Barge-in
|
||||||
- **Langzeit-Erinnerungen pro Nutzer:** dauerhafte Fakten/Vorlieben als LLM-Kontext
|
- **Notfall-Eskalation:** zweistufig (Stichwörter + LLM-Klassifikation im Hintergrund)
|
||||||
- **WebSocket-Streaming-Chat** (`/ws/chat`) als Echtzeit-Transport
|
- **Web-Interface** unter `/` (Tailwind, kein Build, mobiltauglich)
|
||||||
- **REST-API** für Chat, Transkription, Sprachausgabe, Geräte, Sessions, Config
|
- **Keine Secrets im Code** — API-Keys nur über die Umgebung
|
||||||
- **Ohne Secrets im Code** — API-Keys nur über die Umgebung
|
|
||||||
|
|
||||||
## Schnellstart
|
---
|
||||||
|
|
||||||
|
## Schnellstart (30 Sekunden)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python3 -m venv .venv
|
python3 -m venv .venv && source .venv/bin/activate
|
||||||
source .venv/bin/activate
|
pip install -U pip && pip install -e .[test]
|
||||||
pip install -U pip
|
|
||||||
pip install -e .[test]
|
|
||||||
|
|
||||||
cp config/voice-assistant.example.toml config/voice-assistant.toml
|
cp config/voice-assistant.example.toml config/voice-assistant.toml
|
||||||
export OPENROUTER_API_KEY=sk-or-v1-... # nur für Cloud-/Hybrid-Profile nötig
|
export OPENROUTER_API_KEY=sk-or-v1-... # für Cloud/Hybrid; bei local-dev nicht nötig
|
||||||
make run
|
make run
|
||||||
```
|
```
|
||||||
|
|
||||||
Fehlt `.env`, wird sie beim ersten `make run` aus `.env.example` erzeugt.
|
Fehlt `.env`, wird sie aus `.env.example` erzeugt. Gateway läuft auf `http://localhost:8080`
|
||||||
Die App läuft dann auf `http://localhost:8080` (bzw. dem in `.env` gesetzten `PORT`).
|
(oder dem in `.env` gesetzten `PORT`).
|
||||||
|
|
||||||
Kurztest:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl http://localhost:8080/health
|
curl http://localhost:8080/health # {"status":"ok"}
|
||||||
curl http://localhost:8080/api/config
|
curl http://localhost:8080/api/config # aktives Profil + aufgelöste Provider
|
||||||
```
|
```
|
||||||
|
|
||||||
**Sprechen → Antwort hören → erneut sprechen** (Mikrofon-Loop):
|
Sprechen → Antwort hören (CLI-Loop):
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python scripts/voice_loop.py --session mein-gespraech
|
python scripts/voice_loop.py --session mein-gespraech
|
||||||
```
|
```
|
||||||
|
|
||||||
Vollständige, copy-&-paste-fertige Schritt-für-Schritt-Anleitung (Bedienung,
|
Web-Interface: Browser → `http://localhost:8080/`
|
||||||
Einstellungen wechseln, Praxis-Tests & Reaktionszeiten): **[BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md)**.
|
|
||||||
|
|
||||||
## Konfiguration & Profile
|
---
|
||||||
|
|
||||||
Höhere Ebene gewinnt:
|
## Dokumentation
|
||||||
|
|
||||||
```
|
| Dokument | Zielgruppe | Inhalt |
|
||||||
eingebaute Defaults < config/voice-assistant.toml (inkl. aktivem Profil)
|
|----------|-----------|--------|
|
||||||
< ENV / .env < Session-Route < Request
|
| **[BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md)** | alle | Installation, Betriebsprofile, Bedienung, Konfiguration, Admin, Deployment, Fehlerbehebung, Referenz |
|
||||||
```
|
| **[Docs/voice-assistant-architecture.md](Docs/voice-assistant-architecture.md)** | Entwickler | Architekturprinzipien, Interfaces, Pipeline, Roadmap, Verzeichnisstruktur |
|
||||||
|
| **[deploy/README.md](deploy/README.md)** | Admin | Remote-Betrieb: nginx, YunoHost-SSO, systemd, Firewall, Chatterbox |
|
||||||
|
|
||||||
**Profile** umschalten per Umgebungsvariable (oder dauerhaft in `.env`):
|
**Einstiegspunkte je Zielgruppe:**
|
||||||
|
|
||||||
```bash
|
- 👤 **Endnutzer** → BEDIENUNGSANLEITUNG § 5 (Bedienung)
|
||||||
VA_PROFILE=local-dev make run # alles lokal (faster-whisper / lokales LLM / piper)
|
- 🔧 **Admin/Betreiber** → BEDIENUNGSANLEITUNG § 2–4 (Installation + Profile), § 7–11 (Betrieb)
|
||||||
VA_PROFILE=hybrid make run # STT/TTS remote, LLM lokal
|
- 💻 **Entwickler** → BEDIENUNGSANLEITUNG § 2 + Architektur-Dokument
|
||||||
VA_PROFILE=cloud make run # alles über OpenRouter
|
|
||||||
```
|
|
||||||
|
|
||||||
> Secrets gehören **nicht** in `config/*.toml` — nur in die Umgebung
|
---
|
||||||
> (`export OPENROUTER_API_KEY=…`). Gesetzte `DEFAULT_*_PROVIDER`-Werte in `.env`
|
|
||||||
> überschreiben ein `VA_PROFILE`.
|
|
||||||
|
|
||||||
**Pro Session:** `POST /api/sessions/{id}/route` (`input_endpoint`, `output_endpoint`,
|
|
||||||
`stt_provider`, `llm_provider`, `tts_provider`, `language`), dann Aufrufe mit `?session_id=…`.
|
|
||||||
|
|
||||||
**Pro Request:** dieselben Felder im Body von `/api/chat` bzw. `/api/speak`.
|
|
||||||
|
|
||||||
Aktive Konfiguration prüfen: `curl http://localhost:8080/api/config`.
|
|
||||||
|
|
||||||
## Lokales LLM (llama.cpp, unzensiert)
|
|
||||||
|
|
||||||
Die zentrale KI kann statt OpenRouter ein **lokales, unzensiertes Modell** über einen
|
|
||||||
llama.cpp-Server (OpenAI-kompatibel) sein. Der Provider `local-openai-compatible`
|
|
||||||
spricht direkt dagegen — kein Code, nur Server starten + Profil wählen.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
make llm-up # startet den llama.cpp-Container (Default: Port 8001, GPU 1)
|
|
||||||
make llm-status # Container- + HTTP-Status
|
|
||||||
make llm-down # stoppt den Container
|
|
||||||
```
|
|
||||||
|
|
||||||
Das Modell wird über das `--alias va_llm` angesprochen; die Defaults zeigen bereits
|
|
||||||
auf `http://127.0.0.1:8001/v1` mit Modell `va_llm`. Danach genügt ein lokales Profil:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
VA_PROFILE=hybrid make run # STT/TTS remote, Haupt-LLM lokal (unzensiert)
|
|
||||||
VA_PROFILE=local-dev make run # komplett lokal (faster-whisper / llama.cpp / piper)
|
|
||||||
```
|
|
||||||
|
|
||||||
Alle Server-Parameter sind per ENV überschreibbar (Defaults in Klammern):
|
|
||||||
|
|
||||||
| Variable | Bedeutung | Default |
|
|
||||||
|------------------|---------------------------------------------|---------|
|
|
||||||
| `HOST_PORT` | Host-Port des Servers | `8001` |
|
|
||||||
| `GPU_DEVICE` | GPU-Index (von 3 GPUs) | `1` |
|
|
||||||
| `MODEL_REL_PATH` | Modellpfad relativ zu `HF_HOME` | `models/qwen3/Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive-Q4_K_M.gguf` |
|
|
||||||
| `HF_HOME` | Wurzel der Modell-Sammlung | `~/nvme2n1p7_home/huggingface` |
|
|
||||||
| `MODEL_ALIAS` | API-Modellname (= `LOCAL_LLM_MODEL`) | `va_llm` |
|
|
||||||
| `CONTAINER_NAME` | Docker-Containername | `va_llm` |
|
|
||||||
|
|
||||||
Beispiel (andere GPU/Port/Modell):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
GPU_DEVICE=2 HOST_PORT=8101 MODEL_REL_PATH=models/qwen3/Qwopus3.6-35B-A3B-v1-Q4_K_M.gguf \
|
|
||||||
bash scripts/llm-server/start-llm-server.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
> Wird `HOST_PORT`/`MODEL_ALIAS` geändert, müssen `LOCAL_LLM_BASE_URL`/`LOCAL_LLM_MODEL`
|
|
||||||
> im Gateway (`.env`) entsprechend angepasst werden.
|
|
||||||
|
|
||||||
### Tempo im Sprach-Loop
|
|
||||||
|
|
||||||
Ein Reasoning-Modell (Qwen3) „denkt" per Default lang und antwortet ausführlich mit
|
|
||||||
Markdown/Emojis — schlecht zum Vorlesen und spürbar träge. Der Provider
|
|
||||||
`local-openai-compatible` stellt daher für **gesprochene** Antworten um:
|
|
||||||
|
|
||||||
| Setting | Default | Wirkung |
|
|
||||||
|---------|---------|---------|
|
|
||||||
| `LOCAL_LLM_DISABLE_REASONING` | `true` | schaltet die Qwen3-Denkphase ab (Time-to-first-word ~9× schneller) |
|
|
||||||
| `LOCAL_LLM_SYSTEM_PROMPT` | knapper Sprach-Prompt | kurze, vorlesbare Antworten in Fließtext (kein Markdown/Emoji) |
|
|
||||||
| `LOCAL_LLM_MAX_TOKENS` | `0` (Server-Limit) | optionaler harter Deckel, z. B. `256` |
|
|
||||||
| `LOCAL_LLM_TEMPERATURE` | `0.3` | Sampling-Temperatur |
|
|
||||||
|
|
||||||
> Gemessen am Modell `va_llm`: dieselbe Frage fällt von **5,5 s / 1433 Zeichen**
|
|
||||||
> (Reasoning an, ausführlich) auf **0,7 s / ~190 Zeichen** (Reasoning aus + Sprach-Prompt).
|
|
||||||
> Für unzensierte „freie" Gespräche bleibt der Prompt rein formal (nur Kürze/Format,
|
|
||||||
> keine inhaltlichen Einschränkungen); per `LOCAL_LLM_SYSTEM_PROMPT=` leerbar.
|
|
||||||
|
|
||||||
**Zweiter Hebel — STT:** `faster-whisper` läuft per Default auf `auto` (oft CPU) mit
|
|
||||||
Modell `base`. Auf einer RTX 3090 lohnt `FASTER_WHISPER_DEVICE=cuda` +
|
|
||||||
`FASTER_WHISPER_COMPUTE_TYPE=float16`; das verkürzt die Transkriptionszeit pro Turn.
|
|
||||||
|
|
||||||
**Dritter Hebel — lokales TTS (piper):** piper läuft **in-process** über die piper-Python-API
|
|
||||||
(im `.[local]`-Extra). Das Stimmmodell wird **einmal** geladen und prozessweit gecacht —
|
|
||||||
früher startete piper als Subprozess **pro Satz** und zahlte jedes Mal ~2 s Modell-Ladezeit.
|
|
||||||
Zusätzlich werden lokale Modelle **beim Serverstart vorgeladen** (Warm-up), sodass auch der
|
|
||||||
erste Nutzer keinen Kaltstart spürt. Messung (lokales Setup): erster Ton **5,8 s → ~1,6 s**.
|
|
||||||
|
|
||||||
**Höhere Sprachqualität — chatterbox (optional):** Für deutlich natürlichere, **klonbare**
|
|
||||||
Stimmen gibt es den Provider `chatterbox` (Resemble AI, eigener HTTP-Dienst auf GPU, siehe
|
|
||||||
`deploy/README.md`). Wählbar pro Request/Session via `tts_provider=chatterbox` (`piper` bleibt
|
|
||||||
der schnelle Default). Chatterbox ist neural und ~echtzeit-langsam → besser für Qualität als
|
|
||||||
für minimale Latenz. Konfig: `CHATTERBOX_BASE_URL`, `CHATTERBOX_VOICE` (Referenz-WAV fürs
|
|
||||||
Cloning), `CHATTERBOX_SPEED`.
|
|
||||||
|
|
||||||
### Komplett lokal: Profil `local-dev`
|
|
||||||
|
|
||||||
`VA_PROFILE=local-dev` betreibt **alle** KI-Module ohne Cloud. Die Route löst auf zu:
|
|
||||||
|
|
||||||
| Modul | Provider | Quelle |
|
|
||||||
|-------|----------|--------|
|
|
||||||
| STT | `faster-whisper` | lokales Whisper-Modell |
|
|
||||||
| **LLM** | `local-openai-compatible` | llama.cpp-Server `http://127.0.0.1:8001/v1`, Modell `va_llm` |
|
|
||||||
| TTS | `piper` | lokales Stimmmodell |
|
|
||||||
|
|
||||||
**Voraussetzungen:**
|
|
||||||
- **LLM:** llama.cpp-Container läuft (`make llm-up`)
|
|
||||||
- **STT + TTS:** `pip install -e .[local]` (installiert faster-whisper **und** piper-tts);
|
|
||||||
ein piper-Stimmmodell (`<name>.onnx` + `.onnx.json`) im `PIPER_VOICES_DIR` (siehe `PIPER_*`)
|
|
||||||
|
|
||||||
**Start (Reihenfolge):**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
make llm-up # 35B-Modell laden; mit make llm-status auf "HTTP OK" warten
|
|
||||||
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 |
|
|
||||||
|---------------------------------|-------|
|
|
||||||
| `GET /health` | Liveness-Check |
|
|
||||||
| `POST /api/chat` | Text rein → Audio raus (`?debug=true` → JSON-Trace) |
|
|
||||||
| `POST /api/speak` | Text rein → TTS-Audio raus |
|
|
||||||
| `POST /api/transcribe` | Audio-Upload → Transkript |
|
|
||||||
| `GET /api/devices` | verfügbare Audio-Endpunkte + Capabilities |
|
|
||||||
| `POST /api/sessions/{id}/route` | Geräte/Provider/Sprache je Session setzen |
|
|
||||||
| `GET /api/config` | aktives Profil + aufgelöste Route (ohne Secrets) |
|
|
||||||
| `POST /api/admin/users` | Nutzer anlegen (Admin-Key) → Token einmalig |
|
|
||||||
| `GET /api/me` | aktueller Nutzer + Präferenzen |
|
|
||||||
| `PUT /api/me/prefs` | dauerhafte Routing-Präferenzen des Nutzers setzen |
|
|
||||||
| `GET/POST/DELETE /api/me/memories` | Langzeit-Erinnerungen des Nutzers verwalten |
|
|
||||||
| `WS /ws/chat` | Echtzeit-Chat über WebSocket (Text rein, Streaming-Events) |
|
|
||||||
| `WS /ws/voice` | Echtzeit-Sprache (Audio rein → Transkript → Antwort) |
|
|
||||||
| `GET /api/metrics` | Metriken (JSON, oder `?format=prometheus`) |
|
|
||||||
|
|
||||||
Beispiel (Sprachausgabe an den Test-Loopback; `piper` = lokales TTS):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST http://localhost:8080/api/speak \
|
|
||||||
-H 'Content-Type: application/json' \
|
|
||||||
-d '{"text":"Guten Morgen!","tts_provider":"piper","output_endpoint":"loopback"}'
|
|
||||||
```
|
|
||||||
|
|
||||||
Unbekannter Endpunkt/Provider → `HTTP 422` mit Klartext-Hinweis.
|
|
||||||
|
|
||||||
## Gesprächsgedächtnis
|
|
||||||
|
|
||||||
Wird bei `/api/chat` eine `session_id` mitgegeben, merkt sich der Assistent den
|
|
||||||
Verlauf: vergangene Turns werden gespeichert und beim nächsten Aufruf ans LLM
|
|
||||||
gegeben (begrenzt auf die letzten `HISTORY_MAX_MESSAGES` Nachrichten, Default 10).
|
|
||||||
Ohne `session_id` bleibt der Aufruf zustandslos.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST "http://localhost:8080/api/chat?session_id=oma-anna&debug=true" \
|
|
||||||
-H 'Content-Type: application/json' -d '{"text":"Ich heiße Anna."}'
|
|
||||||
curl -X POST "http://localhost:8080/api/chat?session_id=oma-anna&debug=true" \
|
|
||||||
-H 'Content-Type: application/json' -d '{"text":"Wie war noch mein Name?"}'
|
|
||||||
```
|
|
||||||
|
|
||||||
**Langzeit-Erinnerungen** (über Sessions hinweg, pro Nutzer) werden über
|
|
||||||
`/api/me/memories` gepflegt und bei jedem Chat als Kontext ans LLM gegeben — auch
|
|
||||||
ohne `session_id`:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST http://localhost:8080/api/me/memories \
|
|
||||||
-H "Authorization: Bearer $TOKEN" \
|
|
||||||
-H 'Content-Type: application/json' -d '{"content":"Mag morgens Kamillentee."}'
|
|
||||||
```
|
|
||||||
|
|
||||||
**Automatische Erinnerungen:** Zusätzlich zur manuellen Pflege destilliert das LLM
|
|
||||||
nach je N Turns (Default 3) dauerhafte Fakten/Vorlieben aus dem Gespräch und legt sie
|
|
||||||
dedupliziert als Erinnerungen ab — best-effort und **nicht-blockierend** (Hintergrund-Task,
|
|
||||||
erhöht die Antwortlatenz nicht). Steuerung über `MEMORY_EXTRACTION_*` (siehe `.env.example`);
|
|
||||||
`MEMORY_EXTRACTION_ENABLED=false` schaltet es ab. Sinnvoll mit einem lokalen LLM, da pro
|
|
||||||
Turn ein zusätzlicher (kostenloser) Modellaufruf anfällt.
|
|
||||||
|
|
||||||
## Echtzeit-Chat (WebSocket)
|
|
||||||
|
|
||||||
`/ws/chat` bietet einen dauerhaften, bidirektionalen Kanal. Der Client sendet pro
|
|
||||||
Turn eine JSON-Nachricht (`{"text": "..."}`, optional Provider/Endpunkt-Overrides),
|
|
||||||
der Server streamt strukturierte Events zurück: `ack` → `semantic` → Audio (binär)
|
|
||||||
→ `done`. Auth (Token-Query `?token=…`), Session-Gedächtnis (`?session_id=…`) und
|
|
||||||
Erinnerungen gelten wie bei `POST /api/chat`.
|
|
||||||
|
|
||||||
**Token-Streaming:** Mit `{"text": "...", "stream": true}` schickt der Server die
|
|
||||||
LLM-Antwort schon während der Generierung als `token`-Events — spürbar geringere
|
|
||||||
wahrgenommene Latenz. OpenRouter und der lokale OpenAI-kompatible Provider streamen
|
|
||||||
via SSE; Provider ohne Streaming liefern die komplette Antwort als ein `token`-Event.
|
|
||||||
|
|
||||||
**Audio-Streaming:** Mit `{"text": "...", "audio_stream": true}` wird das Audio
|
|
||||||
**satzweise** erzeugt (chunked TTS) und pro fertigem Satz als `audio`-Event (JSON
|
|
||||||
mit `seq` + binärer Frame) gesendet — die Ausgabe beginnt, bevor die Antwort fertig
|
|
||||||
ist. `stream` und `audio_stream` lassen sich kombinieren.
|
|
||||||
|
|
||||||
**Sprach-Eingang (`/ws/voice`):** Der Client streamt Mikrofon-Audio als binäre
|
|
||||||
Frames; ein `{"type":"end"}`-Control-Frame schließt die Äußerung ab. Der Server
|
|
||||||
transkribiert (STT), sendet ein `transcript`-Event und durchläuft dann dieselbe
|
|
||||||
Antwort-Pipeline wie `/ws/chat` (inkl. `stream`/`audio_stream`). Damit ist
|
|
||||||
Sprach-zu-Sprach-Konversation über einen Kanal möglich.
|
|
||||||
|
|
||||||
**VAD (automatische Äußerungserkennung):** Mit `{"type":"start","vad":true,
|
|
||||||
"sample_rate":16000,"format":"pcm"}` segmentiert der Server Äußerungen selbst anhand
|
|
||||||
von Stille (energie-basiert, reines Python) — ohne explizites `end`. Optional:
|
|
||||||
`vad_silence_ms`, `vad_threshold`.
|
|
||||||
|
|
||||||
**Barge-in:** Eine laufende Antwort lässt sich mit `{"type":"interrupt"}` (oder durch
|
|
||||||
eine neue Eingabe) abbrechen — der Server stoppt das Streaming und meldet
|
|
||||||
`{"type":"interrupted"}`. Wichtig für natürliche Gespräche.
|
|
||||||
|
|
||||||
> Echte **partielle Live-Transkripte** (Streaming-STT-Dienst, wortweise während des
|
|
||||||
> Sprechens) und **WebRTC** sind als nächste Increments vorgesehen (siehe
|
|
||||||
> Architektur-Dokument). Heute läuft STT pro Äußerung.
|
|
||||||
|
|
||||||
## Resilienz & Metriken
|
|
||||||
|
|
||||||
**Fallback-Ketten:** Pro Modul lässt sich eine Ersatz-Provider-Liste setzen. Fällt
|
|
||||||
der primäre Provider aus (Timeout/Fehler), übernimmt transparent der nächste:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# z. B. Cloud-LLM mit lokalem Fallback
|
|
||||||
LLM_FALLBACK=local-openai-compatible
|
|
||||||
STT_FALLBACK=faster-whisper
|
|
||||||
TTS_FALLBACK=piper
|
|
||||||
```
|
|
||||||
|
|
||||||
Die Kette ist `Route-Provider` + `*_FALLBACK` (dedupliziert). Erfolgreiche Fallbacks
|
|
||||||
und Provider-Fehler werden gezählt.
|
|
||||||
|
|
||||||
**Metriken** (`GET /api/metrics`): Request-Counts/-Latenzen pro Pfad, Pipeline-Stufen
|
|
||||||
(`stt`/`llm`/`tts`), Fallback-/Fehlerzähler — als JSON oder Prometheus-Text
|
|
||||||
(`?format=prometheus`). In-Memory pro Prozess (keine externe Dependency).
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl http://localhost:8080/api/metrics
|
|
||||||
curl http://localhost:8080/api/metrics?format=prometheus
|
|
||||||
```
|
|
||||||
|
|
||||||
## Kontingent & Notfall-Eskalation
|
|
||||||
|
|
||||||
**Tageskontingent** pro Nutzer begrenzt die Kosten (Cloud-LLM/TTS). Bei Überschreitung
|
|
||||||
`HTTP 429` (bzw. `error`-Event über WebSocket):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
DAILY_REQUEST_LIMIT=200 # 0 = unbegrenzt; pro Nutzer/Tag
|
|
||||||
```
|
|
||||||
Pro Nutzer übersteuerbar via `prefs.daily_request_limit` (siehe `PUT /api/me/prefs`).
|
|
||||||
|
|
||||||
**Notfall-Eskalation (zweistufig):** `/api/chat` und `/ws/chat` prüfen die Nutzereingabe
|
|
||||||
auf Notlagen-Signale (medizinisch, Selbstgefährdung, Hilferuf — de/en). Bei Treffer
|
|
||||||
wird der Vorfall protokolliert, optional ein Webhook ausgelöst und das Signal sichtbar
|
|
||||||
gemacht (`X-Emergency`-Header / `emergency`-Feld / WebSocket-`emergency`-Event). Eine
|
|
||||||
Notfall-Eingabe umgeht das Kontingent (wird nie geblockt).
|
|
||||||
|
|
||||||
1. **Stichwort-Heuristik** im Hot-Path — sofort, ohne Latenz.
|
|
||||||
2. **LLM-Klassifikation** als **Hintergrund-Task**, der nur läuft, wenn die Stichwörter
|
|
||||||
nichts fanden. Fängt verpasste Formulierungen (z. B. metaphorisch geäußerte
|
|
||||||
Suizidalität oder Schlaganfall-Symptome ohne Schlüsselwort) mit Konfidenz-Schwelle —
|
|
||||||
**ohne** die Antwortlatenz zu erhöhen. Eskaliert genauso (Log/Webhook), beim WebSocket
|
|
||||||
zusätzlich ein nachgelagertes `emergency`-Event (`source: "llm"`).
|
|
||||||
|
|
||||||
```bash
|
|
||||||
EMERGENCY_WEBHOOK_URL=https://example.org/alert # optional, Benachrichtigung
|
|
||||||
EMERGENCY_LLM_ENABLED=true # Stufe 2 (Default an); false = nur Stichwörter
|
|
||||||
EMERGENCY_LLM_MIN_CONFIDENCE=0.6 # Schwelle gegen Fehlalarme
|
|
||||||
```
|
|
||||||
|
|
||||||
> ⚠️ Die Erkennung (Heuristik **und** LLM) ist **kein verlässlicher Lebensretter**
|
|
||||||
> und kein Ersatz für einen echten Notruf. Sie kann Notlagen verpassen oder Fehlalarme
|
|
||||||
> auslösen. Erkannte Texte sind hochsensibel (DSGVO: Einwilligung, Aufbewahrung,
|
|
||||||
> Zugriff beachten).
|
|
||||||
|
|
||||||
## Authentifizierung
|
|
||||||
|
|
||||||
Standardmäßig (`AUTH_ENABLED=true`) sind `chat`/`speak`/`transcribe`/`sessions`/`me`
|
|
||||||
durch ein **Bearer-Token pro Nutzer** geschützt. Nutzer/Sessions werden in SQLite
|
|
||||||
persistiert (`DB_PATH`, Default `data/voice-assistant.db`).
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1) Nutzer anlegen (Admin-Key aus der Umgebung) — Token erscheint EINMALIG
|
|
||||||
export ADMIN_API_KEY=ein-langes-geheimnis
|
|
||||||
curl -X POST http://localhost:8080/api/admin/users \
|
|
||||||
-H "X-Admin-Key: $ADMIN_API_KEY" \
|
|
||||||
-H 'Content-Type: application/json' \
|
|
||||||
-d '{"display_name":"Oma Anna"}'
|
|
||||||
# -> {"user_id":"…","display_name":"Oma Anna","token":"…"}
|
|
||||||
|
|
||||||
# 2) Mit dem Token aufrufen
|
|
||||||
curl http://localhost:8080/api/me -H "Authorization: Bearer <TOKEN>"
|
|
||||||
```
|
|
||||||
|
|
||||||
Dauerhafte Präferenzen pro Nutzer (`PUT /api/me/prefs`) fließen in die Route-Auflösung
|
|
||||||
ein (Ebene zwischen Profil und Session). Fremde Sessions → `HTTP 403`.
|
|
||||||
|
|
||||||
> **Lokale Entwicklung:** `AUTH_ENABLED=false` setzen — dann gilt ein anonymer
|
|
||||||
> Standardnutzer und es ist kein Token nötig.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
```bash
|
|
||||||
make test # oder: pytest -q (offline, mit Stubs)
|
|
||||||
```
|
|
||||||
|
|
||||||
Abgedeckt: Config-Profile & Präzedenz, Route-Auflösung, Device Router,
|
|
||||||
Auth/Mandanten, Gedächtnis, Streaming, Resilienz, Quota/Notfall.
|
|
||||||
|
|
||||||
**Echter End-to-End-Test gegen OpenRouter** (Netz-Aufrufe, geringe Kosten — prüft
|
|
||||||
LLM, TTS und STT live, inkl. TTS→STT-Round-Trip):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
make smoke # oder: python scripts/smoke_e2e.py
|
|
||||||
```
|
|
||||||
|
|
||||||
## Port ändern
|
|
||||||
|
|
||||||
```bash
|
|
||||||
PORT=8003 make run # einmalig
|
|
||||||
sed -i 's/^PORT=.*/PORT=8003/' .env # dauerhaft
|
|
||||||
PORT=8003 docker compose up # mit Docker
|
|
||||||
```
|
|
||||||
|
|
||||||
## Web-UI & Remote-Zugang
|
|
||||||
|
|
||||||
Das Gateway liefert unter `/` eine **Web-Oberfläche** aus (`app/web/`, Tailwind via CDN,
|
|
||||||
kein Build): responsives, modernes Layout mit **Tag-/Nacht-Umschalter** (folgt automatisch
|
|
||||||
dem System), Text-Eingabe + **Mikrofon-Button** (Aufnahme im Browser → `/ws/voice` → Antwort
|
|
||||||
wird vorgelesen), **Stimmen-Auswahl** (piper/chatterbox/cloud) sowie Identität/Logout und
|
|
||||||
(für Admins) eine Nutzerliste.
|
|
||||||
|
|
||||||
### Zugriff aus dem lokalen Netz (LAN)
|
|
||||||
|
|
||||||
Der Server lauscht standardmäßig auf `0.0.0.0` (alle Interfaces). Für den Zugriff von
|
|
||||||
anderen Rechnern/Handys im LAN reichen zwei Dinge:
|
|
||||||
|
|
||||||
1. **Firewall öffnen** für den Port (Beispiel ufw, auf die eigenen LAN-Subnetze beschränkt):
|
|
||||||
```bash
|
|
||||||
sudo ufw allow from 192.168.179.0/24 to any port 8003 proto tcp comment 'voice-assistant LAN'
|
|
||||||
```
|
|
||||||
2. Im Browser des anderen Geräts die **LAN-IP** des Servers aufrufen: `http://<server-lan-ip>:8003/`.
|
|
||||||
|
|
||||||
> ⚠️ **Mikrofon nur über HTTPS/localhost:** Browser geben das Mikrofon nur in einem
|
|
||||||
> „secure context" frei. Über `http://<lan-ip>:8003` funktioniert daher der **Text-Chat**,
|
|
||||||
> aber **nicht** der Mic-Button. Für Sprache von anderen Geräten den HTTPS-Weg nutzen
|
|
||||||
> (siehe unten) — am lokalen Rechner via `http://localhost:8003` geht das Mikrofon.
|
|
||||||
|
|
||||||
> ⚠️ Bei `AUTH_ENABLED=false` kann **jeder im LAN** den Dienst anonym nutzen. Für mehr
|
|
||||||
> als vertrautes Testen Auth aktivieren bzw. den SSO-Weg wählen.
|
|
||||||
|
|
||||||
### Remote von unterwegs (HTTPS + SSO)
|
|
||||||
|
|
||||||
Für den **Remote-Betrieb** (Handy/Browser von unterwegs) hinter einem Reverse-Proxy mit
|
|
||||||
HTTPS + SSO (z. B. YunoHost): siehe **`deploy/README.md`**. Kernpunkte:
|
|
||||||
- **HTTPS ist Pflicht** — Browser geben das Mikrofon nur im „secure context" frei.
|
|
||||||
- **Forward-/Trusted-Header-Auth**: der Proxy/SSO authentifiziert, reicht die Identität
|
|
||||||
per Header durch (`TRUSTED_AUTH_HEADER`); das Gateway legt Nutzer automatisch an.
|
|
||||||
Akzeptiert wird der Header nur von der Proxy-Quell-IP (`TRUSTED_PROXY_IPS`).
|
|
||||||
- **WebSocket-Upgrade** im nginx nicht vergessen (sonst kein Mikrofon).
|
|
||||||
|
|
||||||
## Deployment
|
|
||||||
|
|
||||||
- **Docker:** `docker compose up --build` (reicht `OPENROUTER_API_KEY` aus der Shell durch)
|
|
||||||
- **systemd:** Vorlagen unter `deploy/` (`voice-assistant.service`, `voice-assistant.env.example`)
|
|
||||||
- **Remote über YunoHost/Reverse-Proxy:** `deploy/README.md` (HTTPS, SSO, nginx, Firewall)
|
|
||||||
|
|
||||||
## Projektstruktur (Kurzform)
|
## Projektstruktur (Kurzform)
|
||||||
|
|
||||||
```text
|
```text
|
||||||
app/ Gateway: config, dependencies, api/, core/, audio/, pipeline/, providers/
|
app/ Gateway: config, api/, core/, audio/, pipeline/, providers/
|
||||||
config/ voice-assistant.example.toml (lokale .toml ist gitignored)
|
config/ voice-assistant.example.toml (lokale .toml ist gitignored)
|
||||||
deploy/ systemd-Unit + env-Beispiel
|
deploy/ systemd-Unit, nginx-Vorlage, env-Beispiel
|
||||||
tests/ Pytest-Suite
|
scripts/ voice_loop.py, chat_client.py, smoke_e2e.py, add_pronunciation.py
|
||||||
|
scripts/llm-server/ start/stop/status-llm-server.sh (llama.cpp-Docker)
|
||||||
|
tests/ Pytest-Suite (offline + smoke)
|
||||||
Docs/ Architektur-Dokument
|
Docs/ Architektur-Dokument
|
||||||
```
|
```
|
||||||
|
|
||||||
## Lizenz / Status
|
---
|
||||||
|
|
||||||
Lizenz: **proprietär – alle Rechte vorbehalten** (siehe [LICENSE.md](LICENSE.md)).
|
## Lizenz
|
||||||
|
|
||||||
Frühes, aktiv entwickeltes Projektgerüst. Audio-Hardware-/Streaming-Anbindung,
|
**Proprietär — alle Rechte vorbehalten.** Siehe [LICENSE.md](LICENSE.md).
|
||||||
Authentifizierung, Persistenz und Gedächtnis sind als nächste Schritte vorgesehen
|
|
||||||
(siehe Roadmap im Architektur-Dokument).
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue