diff --git a/BEDIENUNGSANLEITUNG.md b/BEDIENUNGSANLEITUNG.md index 982293e..3e50498 100644 --- a/BEDIENUNGSANLEITUNG.md +++ b/BEDIENUNGSANLEITUNG.md @@ -35,7 +35,7 @@ funktioniert trotzdem, die Ausgabe ist dann unformatiert. 1. [Was ist dieses System?](#1-was-ist-dieses-system) 2. [Installation und Einrichtung](#2-installation-und-einrichtung) 3. [Betriebsprofile wählen](#3-betriebsprofile-wählen) -4. [Starten und Stoppen](#4-starten-und-stoppen) +4. [Starten und Stoppen](#4-starten-und-stoppen) — [4.5 llama.cpp](#45-llamacpp-server-für-profil-hybridlocal-dev) · [4.6 Ollama](#46-ollama-alternative-zu-llamacpp-kein-docker-nötig) **Bedienung** 5. [Das System benutzen](#5-das-system-benutzen) @@ -416,32 +416,121 @@ Port ändern: `PORT=8005 make run` (einmalig) oder `PORT=8005` in `.env` (dauerh ### 4.5 llama.cpp-Server (für Profil `hybrid`/`local-dev`) +**Voraussetzungen:** Docker mit NVIDIA-Container-Toolkit, GPU mit ausreichend VRAM +(Qwen3-35B-Q4: ~22 GB; Qwen3-8B-Q4: ~5 GB). + ```bash -make llm-up # startet Docker-Container (Default: GPU 1, Port 8001, Alias va_llm) -make llm-status # Container- + HTTP-Status prüfen -make llm-down # stoppen +# Starten (Default: GPU 1, Port 8001, Modell qwen3-35B-Uncensored): +make llm-up + +# Status prüfen (warten bis „Modell bereit" und HTTP 200 erscheinen): +make llm-status + +# Logs live beobachten: +docker logs -f va_llm + +# Stoppen: +make llm-down ``` -Parameter überschreibbar per ENV: +**Mit anderen Parametern** — ENV-Variable vor dem Befehl setzen: -| Variable | Default | Bedeutung | -|----------|---------|-----------| -| `HOST_PORT` | `8001` | Host-Port | -| `GPU_DEVICE` | `1` | GPU-Index | -| `MODEL_REL_PATH` | `models/qwen3/Qwen3.6-35B-A3B-Uncensored-...Q4_K_M.gguf` | Modellpfad relativ zu `HF_HOME` | -| `HF_HOME` | `~/nvme2n1p7_home/huggingface` | Modell-Sammlung | -| `MODEL_ALIAS` | `va_llm` | API-Modellname | -| `CONTAINER_NAME` | `va_llm` | Docker-Containername | - -Beispiel (andere GPU + anderes Modell): ```bash -GPU_DEVICE=2 MODEL_REL_PATH=models/qwen3/anderes-modell.gguf \ +# Andere GPU: +GPU_DEVICE=0 make llm-up + +# Anderen Port: +HOST_PORT=8101 make llm-up + +# Anderes Modell auf anderer GPU: +GPU_DEVICE=2 HOST_PORT=8102 MODEL_REL_PATH="models/qwen3/anderes-modell.gguf" make llm-up + +# Direkt (ohne make — identisch, aber zeigt alle Parameter): +bash scripts/llm-server/start-llm-server.sh +GPU_DEVICE=0 bash scripts/llm-server/start-llm-server.sh +GPU_DEVICE=2 HOST_PORT=8102 MODEL_REL_PATH="models/qwen3/anderes-modell.gguf" \ bash scripts/llm-server/start-llm-server.sh ``` +Alle überschreibbaren ENV-Variablen: + +| Variable | Default | Bedeutung | +|----------|---------|-----------| +| `GPU_DEVICE` | `1` | GPU-Index (0-basiert, `nvidia-smi` zeigt verfügbare GPUs) | +| `HOST_PORT` | `8001` | Host-Port des LLM-Servers | +| `MODEL_REL_PATH` | `models/qwen3/Qwen3.6-35B-A3B-Uncensored-...Q4_K_M.gguf` | Modellpfad relativ zu `HF_HOME` | +| `HF_HOME` | `~/nvme2n1p7_home/huggingface` | Modell-Basisverzeichnis (als Volume eingebunden) | +| `MODEL_ALIAS` | `va_llm` | Modellname in der OpenAI-API (→ `LOCAL_LLM_MODEL` in `.env`) | +| `CONTAINER_NAME` | `va_llm` | Docker-Containername | +| `IMAGE` | `ghcr.io/ggml-org/llama.cpp:server-cuda` | Docker-Image | + > ⚠️ Wird `HOST_PORT` oder `MODEL_ALIAS` geändert, müssen `LOCAL_LLM_BASE_URL` > und `LOCAL_LLM_MODEL` in `.env` entsprechend angepasst werden. +Das Skript wartet bis zu 300 Sekunden auf einen HTTP-200-Response und bricht mit +Fehler ab, wenn das Modell nicht startet — kein stilles Fehlschlagen. + +--- + +### 4.6 Ollama (Alternative zu llama.cpp, kein Docker nötig) + +Ollama verwaltet seinen Serverprozess selbst und braucht kein Docker. Es eignet sich +besonders für schnellen Einstieg, CPU-Betrieb und kleinere Modelle. + +**Installation** (falls noch nicht installiert): +```bash +curl -fsSL https://ollama.com/install.sh | sh +``` + +**Dienst starten:** +```bash +# empfohlen — systemd verwaltet den Prozess: +sudo systemctl start ollama +sudo systemctl enable ollama # automatisch bei Boot starten +sudo systemctl status ollama # Status prüfen + +# alternativ — manuell im Vordergrund (Strg+C stoppt): +ollama serve +# mit anderem Port (Default: 11434): +OLLAMA_HOST=0.0.0.0:11435 ollama serve +``` + +**Modell herunterladen** (einmalig): +```bash +ollama pull qwen3:30b-a3b # ~20 GB, Thinking deaktiviert (empfohlen für Voice) +ollama pull qwen3:8b # ~5 GB, CPU-tauglich, weniger Qualität +ollama pull qwen3:14b # ~9 GB, guter Kompromiss +``` + +**Status prüfen:** +```bash +ollama list # installierte Modelle mit Größe und Änderungsdatum +ollama ps # gerade aktive Modelle mit VRAM-Verbrauch +``` + +**Modell entfernen** (Speicher freigeben): +```bash +ollama rm qwen3:8b +``` + +**Gateway für Ollama konfigurieren** (in `.env`): +```bash +LOCAL_LLM_BASE_URL=http://127.0.0.1:11434/v1 +LOCAL_LLM_API_KEY=ollama +LOCAL_LLM_MODEL=qwen3:30b-a3b # exakter Name aus 'ollama list' +``` + +**Gateway starten:** +```bash +VA_PROFILE=hybrid make run # STT/TTS cloud, LLM via Ollama +VA_PROFILE=local-dev make run # alles lokal (STT/TTS in-process, LLM via Ollama) +``` + +> **Hinweis Reasoning:** `LOCAL_LLM_DISABLE_REASONING=true` (Gateway-Standard) schickt +> `enable_thinking: false` an den Server — Ollama ignoriert dieses Feld. Um Reasoning +> zu deaktivieren, den Modell-Tag ohne Thinking-Suffix wählen (`qwen3:30b-a3b` statt +> `qwen3:30b-a3b:thinking`). + --- ## 5. Das System benutzen @@ -1804,10 +1893,11 @@ in `app/dependencies.py` + Implementierung in `app/providers/`. → [Architektur | Kontingent (Kosten-Bremse) | § 9.3 | | llama.cpp | § 4.5, § 3.2, § 3.3 | | local-dev-Profil | § 3.3 | +| Ollama starten | § 4.6 | | Metriken / Monitoring | § 9.2, Anhang B.1 | | Mikrofon → Audio-Geräte | § 6.7 | | Notfall-Erkennung | § 10 | -| Ollama | § 3.3, § 3.2 | +| Ollama | § 3.2, § 3.3, **§ 4.6** | | piper (TTS) | § 6.5.2, Anhang C | | Pipeline (Architektur) | § 1.3 | | Profile (cloud/hybrid/local-dev) | § 3 | diff --git a/README.md b/README.md index 0c2df26..983cd44 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,94 @@ Web-Interface: Browser → `http://localhost:8080/` --- +## Starten — alle Szenarien + +### Profil `cloud` (nur Gateway, alles via OpenRouter) + +```bash +make run # Gateway auf PORT aus .env (Standard: 8080) +VA_PROFILE=cloud make run # Profil explizit setzen (überschreibt .env) +PORT=8003 make run # anderen Port für diesen Start +LOG_LEVEL=debug make run # ausführlichere Logs +``` + +### Profil `hybrid` / `local-dev` mit llama.cpp (Docker + GPU) + +```bash +# 1) LLM-Server starten +make llm-up # Default: GPU 1, Port 8001, Modell qwen3-35B-Uncensored +make llm-status # warten bis „Modell bereit" + HTTP 200 erscheint +make llm-down # stoppen + +# Mit anderen Parametern (via ENV): +GPU_DEVICE=0 make llm-up +HOST_PORT=8101 GPU_DEVICE=2 make llm-up +GPU_DEVICE=0 MODEL_REL_PATH="models/qwen3/anderes-modell.gguf" make llm-up + +# Direkt (ohne make): +bash scripts/llm-server/start-llm-server.sh +GPU_DEVICE=0 bash scripts/llm-server/start-llm-server.sh + +# 2) Gateway starten +VA_PROFILE=hybrid make run # STT/TTS cloud, LLM lokal +VA_PROFILE=local-dev make run # alles lokal (STT/TTS in-process) +``` + +ENV-Optionen für `make llm-up` / `start-llm-server.sh`: + +| Variable | Default | Bedeutung | +|----------|---------|-----------| +| `GPU_DEVICE` | `1` | GPU-Index (0-basiert) | +| `HOST_PORT` | `8001` | Host-Port des LLM-Servers | +| `MODEL_REL_PATH` | `models/qwen3/Qwen3.6-35B-...Q4_K_M.gguf` | Modellpfad relativ zu `HF_HOME` | +| `HF_HOME` | `~/nvme2n1p7_home/huggingface` | Modell-Basisverzeichnis | +| `MODEL_ALIAS` | `va_llm` | OpenAI-API-Modellname (→ `LOCAL_LLM_MODEL` in `.env`) | +| `CONTAINER_NAME` | `va_llm` | Docker-Containername | + +> Wird `HOST_PORT` oder `MODEL_ALIAS` geändert, müssen `LOCAL_LLM_BASE_URL` und +> `LOCAL_LLM_MODEL` in `.env` entsprechend angepasst werden. + +### Profil `hybrid` / `local-dev` mit Ollama + +```bash +# 1) Ollama-Dienst starten +sudo systemctl start ollama # empfohlen (bei systemd-Installation) +# oder im Vordergrund: +ollama serve + +# 2) Modell herunterladen (einmalig, ~20 GB): +ollama pull qwen3:30b-a3b # Thinking deaktiviert (empfohlen) +# kleinere Alternative (CPU-tauglich, ~5 GB): +ollama pull qwen3:8b + +# Status prüfen: +ollama list # installierte Modelle +ollama ps # gerade aktive Modelle (mit VRAM-Verbrauch) + +# 3) .env anpassen (einmalig): +# LOCAL_LLM_BASE_URL=http://127.0.0.1:11434/v1 +# LOCAL_LLM_API_KEY=ollama +# LOCAL_LLM_MODEL=qwen3:30b-a3b ← exakter Name aus 'ollama list' + +# 4) Gateway starten: +VA_PROFILE=hybrid make run +VA_PROFILE=local-dev make run +``` + +### Alle `make`-Targets im Überblick + +```bash +make install # venv anlegen + Abhängigkeiten installieren +make run # Gateway starten (uvicorn --reload, Port aus .env) +make test # Pytest-Suite (offline, kostenlos) +make smoke # Live-End-to-End-Test gegen OpenRouter (geringe Kosten) +make llm-up # llama.cpp-Docker-Container starten +make llm-down # llama.cpp-Container stoppen +make llm-status # Container- und HTTP-Status prüfen +``` + +--- + ## Dokumentation | Dokument | Zielgruppe | Inhalt |