Voice IT Agent

Lokaler, persoenlicher IT-Support Voice Agent: Mikrofon → Whisper (STT) → Qwen2.5-7B mit Tool-Calling → Piper (TTS) → Browser. Alles lokal, keine Cloud-API.

Stand: Phase 0–8 fertig, End-to-End funktional (/ws mit STT+LLM+Tools+RAG+TTS). Phase 9 (Finetuning) ist optional und steht in TODO.md.

Stack

Schicht	Tool
STT	faster-whisper
LLM	Qwen2.5-7B-Instruct in 4-bit (bitsandbytes nf4)
TTS	Piper (de_DE-thorsten-high)
Tools	psutil, subprocess, socket
Backend	FastAPI + WebSocket
RAG	PostgreSQL 16 + pgvector + HNSW + sentence-transformers (multilingual mpnet 768d)
Proxy (Prod)	Nginx WSS (TLS 1.2/1.3)

Voraussetzungen

• Python 3.11+ (getestet auf 3.12)
• Docker Desktop (oder Docker Engine)
• NVIDIA GPU mit ≥ 6 GB VRAM (für Qwen 7B 4-bit). Ohne GPU läuft die App auf CPU, aber Antworten dauern dann viele Sekunden.
• ~25 GB freien Speicher (HuggingFace Cache: Qwen ~15 GB, Whisper ~150 MB, sentence-transformers ~420 MB, Piper-Voice ~110 MB)

Quickstart

# 1. .env anlegen
cp .env.example .env
# .env oeffnen und POSTGRES_PASSWORD + DATABASE_URL anpassen

# 2. venv + Dependencies
python -m venv .venv
. .venv/Scripts/activate           # Windows-PowerShell: .\.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt
pip install -r requirements-dev.txt

# 3. DB starten (pgvector + HNSW-Index wird beim ersten Start angelegt)
docker compose -f docker/docker-compose.yml up -d db

# 4. Piper-Stimme laden
bash scripts/download_voices.sh

# 5. RAG-Dokumentation indexieren
PYTHONPATH=. python rag/ingest.py --reset

# 6. Server starten
uvicorn main:app --host 127.0.0.1 --port 8001

# 7. Im Browser: http://127.0.0.1:8001/static/index.html
#    Leertaste halten = Push-to-Talk

Bequemer mit Make (Linux/Mac) bzw. .\scripts\make.ps1 (Windows):

make install   # alle Dependencies
make db-up     # Docker-DB
make ingest    # RAG-Docs indexieren
make serve     # uvicorn auf 8001 mit --reload
make test      # schnelle Tests (ohne LLM-Lade)
make check     # ruff + mypy + test

Tests

pytest tests/unit/ tests/smoke/ -m "not slow"      # schnell, ~30s
pytest tests/ -m "slow or integration"             # vollstaendig, laedt LLM

Stand aktuell: 44/44 grün (mypy clean, ruff clean).

Architektur

Browser  ───WS─►  FastAPI /ws  ───►  VoicePipeline
                                       │
                                       ├─► WhisperSTT.transcribe(audio_bytes) ──► text
                                       │
                                       ├─► QwenLLM.run(text)
                                       │     │
                                       │     ├─► Tool-Call <tool_call>{...}</tool_call>?
                                       │     │     │ ja
                                       │     │     └─► execute_tool() → JSON-Result
                                       │     │           │
                                       │     │           └─► weiterer LLM-Step
                                       │     │
                                       │     └─► finale Antwort (deutsch, kurz, ohne Markdown)
                                       │
                                       └─► PiperTTS satzweise → WAV-Chunks ──► WS

Pipeline-Spezifika:

• pipeline.process() ist async generator – TTS-Chunks gehen direkt zum Client, nicht erst gesammelt.
• __END__ / __EMPTY__ Signale am Ende jeder Anfrage; __RESET__ setzt die Konversations-History zurück.
• HNSW statt ivfflat für pgvector – stabil bei wenigen Dokumenten (rag/store.py).

5 Tools

Tool	Zweck
get_system_info	CPU / RAM / Disk / Top-Prozesse via psutil
run_shell	Diagnose-Befehle mit Praefix-Whitelist (Get-, ping, df, …)
network_diagnose	ping / DNS / Port-Check
manage_service	Windows-Service oder systemd: start/stop/restart/status
search_knowledge_base	Semantische Suche in rag/docs/ über pgvector

Sicherheit

• Shell-Tool akzeptiert nur Befehle aus der Whitelist in tools/shell.py. SHELL_WHITELIST_ENABLED=false zum Deaktivieren (nur für Tests).
• WebSocket ist ohne Auth – läuft per Default auf 127.0.0.1. Für Prod: Nginx WSS + Basic-Auth oder OAuth davorhängen (docker/nginx/nginx.conf).
• Kein Cloud-API-Aufruf zur Laufzeit. Alle Modelle lokal.

Roadmap

Siehe TODO.md.

Quellen / Doku

Phasenplan in files/PHASE_*.md (intern, nicht im Repo). Implementierungs-Reihenfolge: 0 → 1+2 → 3 → 4+5 → 6 → 7 → 8 → 9.