232 lines
7.7 KiB
Markdown
232 lines
7.7 KiB
Markdown
# Voice-Agent
|
||
|
||
Self-hosted Transkriptions- und Protokollsystem für Sitzungsaufzeichnungen — vollständig lokal, DSGVO-konform.
|
||
|
||
> Vollständiges Lastenheft: siehe [`need.md`](need.md)
|
||
|
||
## Architektur
|
||
|
||
```
|
||
Benutzer
|
||
│
|
||
▼ HTTP (Upload)
|
||
┌─────────────────────────────┐ ┌──────────────────────────────┐
|
||
│ LXC-Container │ HTTP │ Mac (Apple Silicon) │
|
||
│ - FastAPI + HTML/JS UI │ ──────► │ - FastAPI Worker │
|
||
│ - SQLite Job-Store │ │ - lightning-whisper-mlx │
|
||
│ - Result-Verzeichnis │ ◄────── │ - Ollama (llama3.1:8b) │
|
||
│ - Nginx Reverse Proxy │ │ - python-docx │
|
||
└─────────────────────────────┘ └──────────────────────────────┘
|
||
```
|
||
|
||
- **LXC**: keine AI-Verarbeitung — nur Uploads, Job-Tracking, Auslieferung.
|
||
- **Mac**: Stateless API. Erhält Audio/Text, gibt Transkripte / Zusammenfassungen / Protokolle / DOCX zurück.
|
||
|
||
## MVP-Funktionsumfang (v0.1)
|
||
|
||
- [x] Audio-Upload (MP3, WAV, M4A, MP4, OGG, FLAC, max. 500 MB)
|
||
- [x] Whisper-Transkription auf dem Mac
|
||
- [x] Ollama-Zusammenfassung (Beschlüsse, Aufgaben, Teilnehmer)
|
||
- [x] Strukturiertes Sitzungsprotokoll
|
||
- [x] DOCX-Export
|
||
- [ ] Speaker-Diarization (Prio 2)
|
||
- [ ] Auth / Benutzerverwaltung (Prio 2)
|
||
- [ ] PDF-Export (Prio 2)
|
||
|
||
---
|
||
|
||
## Installation — Schritt für Schritt
|
||
|
||
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
|
||
bash <(curl -sSL https://git.cynfo.net/christian/voice-agent/raw/branch/main/deploy/install.sh)
|
||
```
|
||
|
||
**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
|
||
./deploy/install.sh
|
||
```
|
||
|
||
Das Skript installiert idempotent:
|
||
|
||
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 Test)
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8080
|
||
|
||
# Für Dauerbetrieb: als LaunchAgent registrieren
|
||
# (startet bei Login, restart nach Crash, Logs in ~/Library/Logs/)
|
||
./deploy/install-launchagent.sh
|
||
```
|
||
|
||
Test vom LXC aus:
|
||
|
||
```bash
|
||
curl http://<MAC-LAN-IP>: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
|
||
```
|
||
|
||
### Schritt 5 — Benutzen
|
||
|
||
Browser auf `http://<LXC-IP>/` → Audio hochladen → fertig.
|
||
|
||
---
|
||
|
||
## Benutzer-Verwaltung / Passwort zurücksetzen
|
||
|
||
Auf dem LXC steht nach dem Deploy `voice-agent-admin` als Befehl bereit:
|
||
|
||
```bash
|
||
# Passwort zurücksetzen (z. B. Admin-Login vergessen)
|
||
sudo voice-agent-admin reset admin 'NeuesPasswort123'
|
||
|
||
# User auflisten / anlegen / löschen
|
||
sudo voice-agent-admin list
|
||
sudo voice-agent-admin create maria 'StartPasswort123'
|
||
sudo voice-agent-admin create chefin 'Geheim12345' --admin
|
||
sudo voice-agent-admin delete maria
|
||
```
|
||
|
||
Vollständige Befehlsreferenz: [`lxc-frontend/README.md`](lxc-frontend/README.md#benutzer--und-passwort-verwaltung-per-cli).
|
||
|
||
## 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 <name>` und `OLLAMA_MODEL=<name>` 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
|
||
|
||
```
|
||
voice-agent/
|
||
├── lxc-frontend/ # FastAPI Web-App (läuft im LXC)
|
||
│ ├── app/
|
||
│ ├── requirements.txt
|
||
│ └── .env.example
|
||
├── mac-worker/ # FastAPI AI-Worker (läuft auf dem Mac)
|
||
│ ├── app/
|
||
│ ├── requirements.txt
|
||
│ └── .env.example
|
||
├── deploy/ # systemd / nginx / install.sh
|
||
├── config/ # Toolkit-Konfiguration (project.env)
|
||
├── .claude/ # KI-Agenten Skills
|
||
├── need.md # Lastenheft
|
||
└── README.md
|
||
```
|
||
|
||
## Sicherheit
|
||
|
||
- Vollständig lokaler Betrieb. Keine Cloud-Calls.
|
||
- HTTPS via Reverse-Proxy ist Aufgabe der Infrastruktur (Let's Encrypt o. Ä.).
|
||
- Mac-Worker hat **keine** Auth — Betrieb nur im internen Netz.
|
||
- Uploads / Ergebnisse unter `/var/lib/voice-agent/` — bei Bedarf Backup einplanen.
|