Files
memory/patterns/llm-backend-hang-diagnosis.md
T
2026-10-02 22:00:00 +00:00

119 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: "LLM-Backend hängt — Modell- vs. Infra-Defekt unterscheiden"
pattern_id: PAT-015
category: patterns
tags: [llm, timeout, diagnosis, noris, hermes, debugging]
created: "2026-10-02"
severity: high
---
# PAT-015: LLM-Backend hängt — Modell- vs. Infra-Defekt unterscheiden
## Symptom
Agent-Turns laufen in Timeouts. Logs zeigen:
```
httpx.ReadError: [Errno 32] Broken pipe
→ openai.APIConnectionError: Connection error.
→ 3 Retries mit Backoff
→ "Provider has been unresponsive (no response received) for
5 consecutive stale attempts — aborting this call"
```
Der Instinkt sagt "Netzwerk" oder "VM überlastet". **Meist falsch.**
## Signatur des Modell-Defekts
| Beobachtung | Bedeutung |
|-------------|-----------|
| TCP-Connect **erfolgreich** (`time_connect` < 1s) | Netzwerk ist in Ordnung |
| TLS-Handshake OK (`time_appconnect` gesetzt) | Proxy/Ingress funktioniert |
| **`ttfb = 0.000000`**, Timeout mit *0 bytes received* | Backend nimmt an, antwortet nie |
| Trifft stream **und** non-stream gleich | Kein Streaming-Bug — Modell-Server hängt |
| **Andere Modelle am selben Endpoint: 200** | Key, Netz, Infra alle gesund |
**Kernpunkt:** `code=000` bei erfolgreichem Connect = der Upstream-Backend-Prozess
für *dieses eine Modell* ist tot/hängt. Nicht das Netz.
## Diagnose-Rezept (5 Minuten)
Identischer Key, identischer Host, **Modell-Matrix** gegentesten:
```bash
KEY=<from running process>
for m in <broken-model> <candidate-a> <candidate-b>; do
curl -s -o /tmp/r.json -w "%{http_code}" --max-time 20 \
https://<endpoint>/v1/chat/completions \
-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d "{\"model\":\"$m\",\"messages\":[{\"role\":\"user\",\"content\":\"say OK\"}],\"max_tokens\":8}"
done
```
**Ein einziges Modell 000 + Rest 200 ⇒ Modell-Defekt, kein Infra-Defekt.**
Gegenprobe von einem **zweiten Host** ausschließen, dass es host-spezifisch ist.
## Pitfalls bei der Diagnose
1. **Key aus `~/.hermes/.env` greppen schlägt fehl**, wenn der Key im systemd-Unit
als `Environment=` steht. → Aus dem laufenden Prozess lesen, nicht aus `.env`:
`sudo tr '\0' '\n' < /proc/<PID>/environ`
Die PID rotiert bei jedem Restart — nicht cachen.
2. **401/403/400 nicht mit 000 verwechseln.** Key-Scope-Fehler antworten sofort
mit Body. `code=000` ist der einzige echte Hang.
3. **`/v1/models` listet auch Modelle, die der Key nicht darf** (`403 model_blocked`).
Auflisten ≠ nutzbar.
4. **Veraltete Response-Datei:** bei `code=000` schreibt curl keine Datei →
`head` zeigt die *vorherige* Antwort. Sieht aus wie Erfolg. Immer `-w %{http_code}`
als Wahrheit nehmen, nicht den Body.
## Amplifier: fehlender Fallback
```yaml
fallback_providers: [] # ← kein Fallback
agent:
api_max_retries: 3
mcp_servers:
playwright:
timeout: 120
connect_timeout: 60
```
Ohne Fallback hängt jeder Turn bis `timeout` × Retries. Ein defektes Modell
legt dann die **ganze** Instanz lahm statt einen degradierten Betrieb zu erzeugen.
## Fix
Default-Modell auf ein verifiziert funktionierendes umstellen, **dann E2E testen** —
nicht nur Config-Write verifizieren:
```bash
# 1. Backup
cp -a config.yaml config.yaml.bak.$(date +%Y%m%d_%H%M%S)
# 2. Beide Modell-Referenzen patchen (model.default + providers.<p>.model)
sed -i 's|<old>|<new>|g' config.yaml
# 3. YAML validieren
python3 -c "import yaml;yaml.safe_load(open('config.yaml'))"
# 4. mtime(config) MUSS < Prozessstart sein
stat -c '%y' config.yaml; systemctl show <svc> -p ActiveEnterTimestamp
# 5. Restart + E2E-Turn
```
**Verifikationskette, die zählt:**
- Neue Session meldet das neue Modell (`session.model`)
- Ein echter Turn läuft durch (`terminal_state: completed`)
- Transcript enthält die Assistant-Antwort
## Referenz-Vorfall
2026-10-02, sarah-hermes VM107: `vllm/release/glm-5-2` hing bei `ai.noris.de`
(0 Bytes, stream + non-stream, von 2 Hosts). Derselbe Key lieferte mit
`qsu/deepseek-v41-flash`, `release/gpt-oss-120b`, `qsu/qwen3.8-27b`,
`release/qwen3.6-27b` jeweils 200. Fix: Default → `qsu/deepseek-v41-flash`,
E2E-Turn in 15s.
## Related
- [[systems/sarah-hermes]] — Vorfall VM107
- [[systems/noris-ai]] — Endpoint, Modell-Katalog