feat(llm): Make-Targets zum Wechseln des LLM-Backends (Ollama <-> llama.cpp)

- scripts/llm-server/switch-llm.sh: gibt GPU des anderen Backends frei
  (llama.cpp-Container stoppen bzw. Ollama-Modelle entladen, Dienst bleibt),
  startet das gewünschte Backend, passt LOCAL_LLM_* in .env an und startet
  das Gateway (als Dienst) neu bzw. weist auf manuellen Neustart hin.
- Makefile: Targets `llm-ollama` / `llm-llamacpp` (Modell via OLLAMA_MODEL=...).
- Doku §4.7 + Schnellbefehle §4.0: Make-Targets als empfohlener Weg, inkl.
  Erklärung warum der Gateway-Neustart nötig ist (Makefile exportiert .env als
  Env-Variablen -> Vorrang vor .env-Datei).

Getestet: Round-Trip ollama -> llamacpp -> ollama; llama.cpp 2,3s, gemma3 warm.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Dieter Schlüter 2026-06-20 15:56:42 +02:00
commit 317ad2ff97
3 changed files with 131 additions and 9 deletions

View file

@ -379,6 +379,8 @@ Die wichtigsten Kommandos auf einen Blick — Details in den Abschnitten darunte
| Profil `cloud` — nur Gateway | `make run` |
| Profil `hybrid` / `local-dev` — llama.cpp + Gateway | `make start` |
| Profil `hybrid` / `local-dev` — Ollama + Gateway | `sudo systemctl start ollama && make run` |
| LLM-Backend → Ollama wechseln | `make llm-ollama` (→ § 4.7) |
| LLM-Backend → llama.cpp wechseln | `make llm-llamacpp` (→ § 4.7) |
| systemd-Dienst starten | `systemctl --user start voice-assistant` |
**Stoppen:**
@ -571,18 +573,37 @@ VA_PROFILE=local-dev make run # alles lokal (STT/TTS in-process, LLM via Ollam
### 4.7 Zwischen llama.cpp und Ollama wechseln
Beide nutzen denselben Gateway-Provider `local-openai-compatible` (OpenAI-kompatible
API). Der Wechsel besteht daher aus drei Dingen: **(A)** den jeweils anderen
Backend-Prozess stoppen (beide teilen sich den GPU-Speicher), **(B)** das gewünschte
Backend starten, **(C)** die drei `LOCAL_LLM_*`-Zeilen in `.env` umstellen und das
Gateway neu starten. `DEFAULT_LLM_PROVIDER` bleibt unverändert.
API). `DEFAULT_LLM_PROVIDER` bleibt beim Wechsel unverändert.
#### Schnellster Weg: Make-Targets (empfohlen)
```bash
make llm-ollama # -> Ollama (Default-Modell gemma3:latest)
make llm-llamacpp # -> llama.cpp (Alias va_llm)
# Anderes Ollama-Modell:
OLLAMA_MODEL=qwen2.5:latest make llm-ollama
```
Das Target erledigt automatisch alle Schritte: es gibt den GPU-Speicher des anderen
Backends frei (llama.cpp-Container stoppen bzw. geladene Ollama-Modelle entladen — der
Ollama-*Dienst* bleibt für andere Nutzungen laufen), startet das gewünschte Backend,
passt die `LOCAL_LLM_*`-Zeilen in `.env` an und startet das Gateway neu (als Dienst)
bzw. weist auf den manuellen Neustart hin. Skript: `scripts/llm-server/switch-llm.sh`.
> **Warum der Gateway-Neustart nötig ist:** Das `Makefile` exportiert die `.env`-Werte
> als echte Umgebungsvariablen an `uvicorn` — und Env-Variablen haben **Vorrang vor der
> `.env`-Datei**. Eine reine `.env`-Änderung wirkt daher erst, wenn das Gateway neu
> gestartet wird (uvicorn `--reload` reagiert nur auf Code-, nicht auf `.env`-Änderungen).
> Starte es **in einer frischen Shell** neu (`make run`) bzw. als Dienst:
> `systemctl --user restart voice-assistant.service`.
#### Manuell (was die Targets im Hintergrund tun)
**Merkhilfe:**
- llama.cpp = Docker-Container `va_llm``make llm-up` / `make llm-down` (Port 8001)
- Ollama = systemd-Dienst → `sudo systemctl start/stop ollama` (Port 11434)
> **Wichtig:** `.env`-Änderungen werden erst bei einem **Gateway-Neustart** wirksam
> (uvicorn `--reload` lädt nur bei Code-Änderungen neu, nicht bei `.env`). Als Dienst:
> `systemctl --user restart voice-assistant.service`.
GPU freigeben ohne Dienst-Stopp: `ollama stop <modell>`
#### Von llama.cpp → Ollama wechseln