From 0bbb7bbacd7d935f746f956d1e7056a4f52d90e5 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 13 May 2026 19:02:01 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20detaillierte=20Installations-Anleitung?= =?UTF-8?q?=20+=20Modell-=C3=9Cbersicht?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: 5-Schritt-Installation (LXC + Mac), Update-Pfad, neue Sektion "Modelle" mit Whisper- und Ollama-Optionen - mac-worker/README: vollständige Tabellen für MLX-Whisper-Modelle und Ollama-Alternativen (qwen2.5, mistral-small, gemma3, gpt-oss, llama3.3), Empfehlungen nach Mac-RAM, Hinweise zu WhisperX/whisper.cpp/Voxtral --- README.md | 144 +++++++++++++++++++++++++++++++++++++++---- mac-worker/README.md | 113 ++++++++++++++++++++++++++++++--- 2 files changed, 236 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 9fbf565..869fbf1 100644 --- a/README.md +++ b/README.md @@ -33,35 +33,155 @@ Benutzer - [ ] Auth / Benutzerverwaltung (Prio 2) - [ ] PDF-Export (Prio 2) -## Schnellstart +--- -### 1. Mac einrichten -Siehe [`mac-worker/README.md`](mac-worker/README.md). +## Installation — Schritt für Schritt -### 2. LXC provisionieren -Mit dem Toolkit-Skill `/proxmox-lxc` (oder manuell). Anschließend auf dem LXC: +Voraussetzungen: + +- **Mac** (Apple Silicon empfohlen, M1/M2/M3/M4) mit min. 16 GB RAM, besser 32 GB. +- **Proxmox-Host** für den LXC-Container. +- **Netzwerk**: Mac und LXC im selben LAN, der LXC muss den Mac auf Port 8080 erreichen. + +### Schritt 1 — LXC-Container provisionieren (Proxmox) + +Entweder mit dem Toolkit-Skill `/proxmox-lxc` oder manuell ein Container mit: + +- Debian 13 (Trixie) oder Ubuntu 24.04 +- 2 vCPU, 2 GB RAM, 20 GB Disk reichen +- Statische LAN-IP, SSH-Zugang als root + +### Schritt 2 — App im LXC installieren + +Im Container als `root` einloggen, dann **eine** der folgenden Optionen wählen: + +**Option A — Auto-Install per Curl** (Repo wird selbst geklont): ```bash -sudo bash <(curl -sSL https://git.cynfo.net/christian/voice-agent/raw/branch/main/deploy/install.sh) +bash <(curl -sSL https://git.cynfo.net/christian/voice-agent/raw/branch/main/deploy/install.sh) ``` -oder nach `git clone`: +**Option B — Manuell aus geklontem Repo:** ```bash +git clone https://git.cynfo.net/christian/voice-agent.git /var/www/voice-agent cd /var/www/voice-agent -sudo ./deploy/install.sh +./deploy/install.sh ``` -### 3. Konfigurieren +Das Skript installiert idempotent: -`/var/www/voice-agent/lxc-frontend/.env` öffnen und `MAC_API_URL` auf die LAN-IP des Macs setzen, dann: +1. apt-Pakete (`git python3-venv nginx ffmpeg ...`) +2. Deploy-User `deploy`, klont/aktualisiert Repo nach `/var/www/voice-agent` +3. Python-venv + Dependencies in `lxc-frontend/.venv` +4. `.env` aus Vorlage anlegen (falls nicht vorhanden) +5. Verzeichnisse `/var/lib/voice-agent/{uploads,results}` +6. systemd-Service `voice-agent.service` (autostart, restart on-failure) +7. Nginx-Reverse-Proxy auf Port 80 → `127.0.0.1:8000` + +Erneutes Ausführen aktualisiert auf den neuesten `main`. + +### Schritt 3 — Mac-Worker einrichten + +Auf dem Mac (Details in [`mac-worker/README.md`](mac-worker/README.md)): ```bash +# Repo holen +git clone https://git.cynfo.net/christian/voice-agent.git ~/voice-agent +cd ~/voice-agent/mac-worker + +# Python-Umgebung +python3.11 -m venv .venv +source .venv/bin/activate +pip install --upgrade pip +pip install -r requirements.txt +cp .env.example .env + +# Ollama + Modell +brew install ollama +launchctl setenv OLLAMA_HOST "0.0.0.0:11434" +brew services restart ollama +ollama pull llama3.1:8b + +# Worker starten (Vordergrund — für dauerhaften Betrieb LaunchAgent nutzen) +uvicorn app.main:app --host 0.0.0.0 --port 8080 +``` + +Test vom LXC aus: + +```bash +curl http://:8080/health +# erwartet: {"status":"ok","whisper_engine":"mlx","ollama_reachable":true,...} +``` + +### Schritt 4 — LXC mit Mac verbinden + +Im LXC `MAC_API_URL` auf die Mac-LAN-IP setzen: + +```bash +sudo nano /var/www/voice-agent/lxc-frontend/.env +# MAC_API_URL=http://192.168.x.y:8080 sudo systemctl restart voice-agent ``` -### 4. Verwenden -Browser auf `http:///` öffnen, Audio hochladen, fertig. +### Schritt 5 — Benutzen + +Browser auf `http:///` → Audio hochladen → fertig. + +--- + +## Update / Neudeployment + +Auf dem LXC einfach nochmal: + +```bash +sudo /var/www/voice-agent/deploy/install.sh +``` + +Auf dem Mac: + +```bash +cd ~/voice-agent && git pull +cd mac-worker && source .venv/bin/activate && pip install -r requirements.txt +# Worker neu starten +``` + +--- + +## Modelle + +### Transkription (Mac, Whisper) + +| `WHISPER_ENGINE` | `WHISPER_MODEL` | Wann nutzen | +|---|---|---| +| `mlx` | `large-v3` (Default) | Maximale Qualität, langsamer (~0.3× Realzeit auf M2) | +| `mlx` | `distil-large-v3` | ~5× schneller, minimal schlechtere Qualität | +| `mlx` | `medium` | Schneller, deutlich schlechter bei Fachbegriffen | +| `faster` | `large-v3` | Intel-Mac / Linux / CUDA | +| `mock` | – | Tests ohne Modell-Download | + +Standard ist `mlx` + `large-v3`. Für lange Sitzungen lohnt sich ein Test mit `distil-large-v3`. Alternativen (whisper.cpp + CoreML, WhisperX mit Diarization, Voxtral) sind in [`mac-worker/README.md`](mac-worker/README.md#alternative-transkriptions-engines) dokumentiert. + +### Zusammenfassung (Ollama) + +Standard: `llama3.1:8b` — solide Basisqualität bei deutschen Texten, ~8 GB Speicher. + +Empfohlene Alternativen je nach Hardware (alle via `ollama pull ` und `OLLAMA_MODEL=` in `.env`): + +| Modell | Größe | RAM-Bedarf | Stärken | +|---|---|---|---| +| `llama3.1:8b` (Default) | 8 B | ~8 GB | Schnell, brauchbares Deutsch | +| `qwen2.5:14b` | 14 B | ~10 GB | Sehr zuverlässige JSON-Ausgabe, exzellentes Deutsch | +| `mistral-small:24b` | 24 B | ~16 GB | Europäisch trainiert, beste Kompromiss-Wahl | +| `gemma3:12b` | 12 B | ~10 GB | Stark multilingual, gute Strukturierung | +| `gpt-oss:20b` | 20 B | ~14 GB | Sehr gute strukturierte Ausgabe (OpenAI Open-Weight) | +| `llama3.3:70b` | 70 B | ~48 GB | Top-Qualität, nur auf Macs mit 64 GB+ | + +Für Sitzungsprotokolle (deutsch, viel JSON-Struktur) ist **`qwen2.5:14b`** oder **`mistral-small:24b`** der beste Sweet-Spot auf einem Mac mit 32 GB. + +Detaillierte Bewertung siehe [`mac-worker/README.md`](mac-worker/README.md#ollama-modell-wählen). + +--- ## Verzeichnisstruktur diff --git a/mac-worker/README.md b/mac-worker/README.md index d2a00c8..c54e882 100644 --- a/mac-worker/README.md +++ b/mac-worker/README.md @@ -20,7 +20,7 @@ cp .env.example .env # Ollama installieren, falls noch nicht geschehen brew install ollama -# Modell ziehen +# Modell ziehen (Default — siehe unten für Alternativen) ollama pull llama3.1:8b # Ollama netzwerkweit erreichbar machen (LaunchAgent) @@ -28,14 +28,6 @@ launchctl setenv OLLAMA_HOST "0.0.0.0:11434" brew services restart ollama ``` -## Whisper-Engine wählen - -| `WHISPER_ENGINE` | Wann nutzen | -|---|---| -| `mlx` | Apple Silicon — schnellste Option | -| `faster` | Intel-Mac / Linux / CUDA | -| `mock` | Testbetrieb ohne echtes Modell | - ## Worker starten ```bash @@ -65,3 +57,106 @@ curl http://:8080/health ``` Der Worker hat **keine Authentifizierung** — Betrieb nur im internen Netz. + +--- + +## Whisper-Engine wählen + +In `.env`: + +``` +WHISPER_ENGINE=mlx # mlx | faster | mock +WHISPER_MODEL=large-v3 # Modellname (siehe Tabellen unten) +WHISPER_BATCH_SIZE=12 # MLX: höher = schneller + mehr RAM +WHISPER_LANGUAGE=de +``` + +| `WHISPER_ENGINE` | Wann nutzen | +|---|---| +| `mlx` (Default) | Apple Silicon — nutzt Apple Neural Engine via [`lightning-whisper-mlx`](https://github.com/mustafaaljadery/lightning-whisper-mlx) | +| `faster` | Intel-Mac, Linux oder CUDA — [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) (CTranslate2) | +| `mock` | Testbetrieb ohne Modell-Download | + +### MLX-Modelle (`WHISPER_ENGINE=mlx`) + +| `WHISPER_MODEL` | Größe | Geschwindigkeit (M2) | Qualität (Deutsch) | +|---|---|---|---| +| `tiny` | 75 MB | ~20× Realzeit | Niedrig — nur für Voice-Commands | +| `base` | 145 MB | ~15× Realzeit | Niedrig | +| `small` | 466 MB | ~6× Realzeit | Mittel | +| `medium` | 1.5 GB | ~2× Realzeit | Gut, schwächelt bei Fachbegriffen | +| `large-v3` (Default) | 3 GB | ~0.3× Realzeit | **Sehr gut** — Standard für Sitzungsprotokolle | +| `distil-large-v3` | 1.5 GB | ~1.5× Realzeit | Fast wie `large-v3`, ~5× schneller | +| `large-v3-turbo` | 1.6 GB | ~3× Realzeit | Wie `large-v3` für lange Inhalte, schwächer bei kurzen | + +Empfehlung: `large-v3` für maximale Qualität, `distil-large-v3` wenn Geschwindigkeit wichtiger ist. + +Modelle werden beim ersten Aufruf automatisch von HuggingFace gezogen (`mlx-community/whisper-...`). + +### Alternative Transkriptions-Engines + +Diese sind im Standard-Setup **nicht** aktiviert, lassen sich aber statt `lightning-whisper-mlx` einbauen: + +- **`whisper.cpp` mit CoreML** — pure C++, sehr ressourceneffizient, kann das Whisper-Modell auf der Apple Neural Engine ausführen. Eigener Subprozess statt Python-Bindings. +- **WhisperX** ([github.com/m-bain/whisperX](https://github.com/m-bain/whisperX)) — basiert auf `faster-whisper`, fügt **Wort-genaue Timestamps** und **Sprecher-Diarization** (via pyannote) hinzu. Erfordert HuggingFace-Token. Sinnvoll, sobald „Wer hat was gesagt?" wichtiger wird. +- **Voxtral** (Mistral, 2025) — multimodales Sprach-LLM, kann Audio direkt zusammenfassen ohne separaten Whisper-Schritt. Reduziert die Pipeline auf einen einzigen Modell-Call, braucht aber andere Library und höheren VRAM. +- **NVIDIA Parakeet TDT** — extrem schnell, aber primär englisch. Für deutsche Sitzungen nicht empfehlenswert. + +Für reinen Geschwindigkeits-Boost ohne Architektur-Änderung: einfach `WHISPER_MODEL=distil-large-v3` setzen. + +--- + +## Ollama-Modell wählen + +In `.env`: + +``` +OLLAMA_MODEL=llama3.1:8b +OLLAMA_TIMEOUT=600 +``` + +Anschließend nur noch: + +```bash +ollama pull +# Worker neu starten +``` + +### Empfehlung nach Mac-RAM + +| Mac-RAM | Empfohlenes Modell | Begründung | +|---|---|---| +| 16 GB | `llama3.1:8b` oder `qwen2.5:7b` | Genug Spielraum neben Whisper-large-v3 | +| 24 GB | `qwen2.5:14b` oder `gemma3:12b` | Großer Qualitätssprung bei deutscher JSON-Ausgabe | +| 32 GB | `mistral-small:24b` (Q4) oder `gpt-oss:20b` | Beste Kompromiss-Wahl | +| 64 GB+ | `llama3.3:70b` oder `qwen2.5:72b` | Top-Qualität, aber langsamer (~20–60 s pro Summary) | + +### Detailbewertung der Kandidaten + +| Modell | Größe | Deutsch | JSON-Stabilität | Geschwindigkeit | Notizen | +|---|---|---|---|---|---| +| `llama3.1:8b` (Default) | 8 B | Gut | Mittel — gelegentlich Codefences | Schnell (~5 s) | Ausreichend für die meisten Sitzungen | +| `qwen2.5:7b` | 7 B | Sehr gut | Hoch | Schnell | Beste 7B-Wahl für Deutsch | +| `qwen2.5:14b` | 14 B | Sehr gut | Sehr hoch | Mittel (~10 s) | **Empfehlung für 24–32 GB Macs** | +| `gemma3:12b` | 12 B | Gut | Hoch | Mittel | Google, gute Strukturierung | +| `mistral-small:24b` | 24 B | Sehr gut | Sehr hoch | Mittel (~15 s) | Europäisch trainiert, sehr stark bei Fachsprache | +| `gpt-oss:20b` | 20 B | Gut | Sehr hoch | Mittel | OpenAI Open-Weight (2025), explizit auf Tool-Use trainiert | +| `phi4:14b` | 14 B | Mittel | Hoch | Mittel | Microsoft, stark im Reasoning, schwächer im Deutschen | +| `llama3.3:70b` | 70 B | Exzellent | Sehr hoch | Langsam (~30–60 s) | Top-Qualität, nur mit 48 GB+ RAM sinnvoll | + +### Modell wechseln + +```bash +# 1. Modell ziehen +ollama pull qwen2.5:14b + +# 2. .env anpassen +sed -i '' 's/^OLLAMA_MODEL=.*/OLLAMA_MODEL=qwen2.5:14b/' .env + +# 3. Worker neu starten +# (z.B. Ctrl-C im Terminal und uvicorn erneut) +``` + +### Tipp: JSON-Modus erzwingen + +Der aktuelle Worker parst die Antwort manuell und greift bei Fehlern auf einen Text-Fallback zurück. Mit Ollama lässt sich JSON-Output erzwingen, indem im Generate-Call `format: "json"` gesetzt wird — das senkt Parse-Fehler bei kleineren Modellen drastisch. Bei Bedarf in `app/core/ollama_client.py` ergänzen.