diff --git a/docs/03_Technical_References/03_tech_chat_backend.md b/docs/03_Technical_References/03_tech_chat_backend.md index 5696fdf..3437b8d 100644 --- a/docs/03_Technical_References/03_tech_chat_backend.md +++ b/docs/03_Technical_References/03_tech_chat_backend.md @@ -4,7 +4,7 @@ audience: developer, architect scope: backend, chat, llm_service, traffic_control, resilience status: active version: 2.8.1 -context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService und der WP-20 Resilienz-Logik." +context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.3.6) und der WP-20 Resilienz-Logik." --- # Chat Backend & Traffic Control @@ -26,12 +26,13 @@ Der Router prüft den Input in drei Stufen (Wasserfall-Prinzip): 3. **LLM Fallback (Slow Path):** * Wenn unklar: Anfrage an LLM zur Klassifizierung mittels `router_prompt`. -### 1.2 Prompt-Auflösung (WP-20 Fix) +### 1.2 Prompt-Auflösung (Bulletproof Resolution) Um Kompatibilitätsprobleme mit verschachtelten YAML-Prompts zu vermeiden, nutzt der Router die Methode `llm.get_prompt()`. Diese implementiert eine **Provider-Kaskade**: -* Das System sucht zuerst nach einem Prompt für den aktiven Provider (z.B. `openrouter`). -* Existiert dieser nicht, erfolgt ein Fallback auf `gemini` und schließlich auf `ollama`. -* Dies garantiert die Rückgabe eines validen Strings und verhindert 500-Fehler bei String-Operationen wie `.replace()`. +* **Spezifischer Provider:** Das System sucht zuerst nach einem Prompt für den aktiv konfigurierten Provider (z.B. `openrouter`). +* **Cloud-Stil Fallback:** Existiert dieser nicht, erfolgt ein Fallback auf das `gemini`-Template. +* **Basis-Fallback:** Als letzte Instanz wird das `ollama`-Template geladen. +* **String-Garantie:** Die Methode garantiert die Rückgabe eines Strings (selbst bei verschachtelten YAML-Dicts), was 500-Fehler bei String-Operationen wie `.replace()` oder `.format()` verhindert. ### 1.3 RAG Flow (Technisch) @@ -63,10 +64,16 @@ Jeder LLM-Request steuert über ein `priority`-Flag den Zugriff auf Hardware- un **Funktionsweise:** * Hintergrund-Tasks nutzen ein globales `asyncio.Semaphore`. -* Das Limit (Default: 2) verhindert, dass parallele Import-Vorgänge die API-Quoten oder die lokale CPU erschöpfen. +* Das Limit (Standard: 2) verhindert, dass parallele Import-Vorgänge die API-Quoten oder die lokale CPU erschöpfen. * Chat-Tasks umgehen die Semaphore für minimale Latenz. -### 2.2 Timeout-Konfiguration +### 2.2 Task-Mapping & Model Selection + +Die Konfiguration ermöglicht eine spezialisierte Modell-Auswahl je nach Anwendungsfall: +* **Semantische Extraktion (Turbo):** Nutzt bevorzugt `OPENROUTER_MODEL` (Mistral-7B) für schnelles und präzises JSON-Parsing. +* **RAG-Chat:** Nutzt bevorzugt `GEMINI_MODEL` (2.5 flash-lite) für hohe Kapazität und Stabilität mittels erzwungener **v1-API Version**. + +### 2.3 Timeout-Konfiguration Deadlocks und "hängende" Importe werden durch differenzierte Timeouts verhindert: * **Cloud-Calls (OpenRouter/Gemini):** Strikte **45 Sekunden** zur Vermeidung von Blockaden bei Provider-Latenz. @@ -79,10 +86,10 @@ Deadlocks und "hängende" Importe werden durch differenzierte Timeouts verhinder In v2.8 wurde ein intelligentes Fehler-Handling für Cloud-Provider implementiert: 1. **Rate-Limit Erkennung:** Der Service erkennt HTTP 429 Fehler sowie provider-spezifische Meldungen wie `RESOURCE_EXHAUSTED`. -2. **Intelligenter Backoff:** Statt sofort auf das langsame lokale Modell zu wechseln, pausiert das System für die Dauer von `LLM_RATE_LIMIT_WAIT` (Default: 60s). +2. **Intelligenter Backoff:** Statt sofort auf das langsame lokale Modell zu wechseln, pausiert das System für die Dauer von `LLM_RATE_LIMIT_WAIT` (Standard: 60s). 3. **Cloud-Retry:** Nach der Pause erfolgt ein erneuter Versuch (bis zu `LLM_RATE_LIMIT_RETRIES` Mal). 4. **Ollama Fallback:** Erst nach Erschöpfung der Retries schaltet das System auf den lokalen Ollama um, um die Betriebssicherheit zu gewährleisten ("Quoten-Schutz"). -5. **Deep Fallback Support:** Der Service stellt die Infrastruktur für den inhaltsbasierten Fallback (v2.11.14) bereit, falls die Cloud zwar technisch antwortet, aber inhaltlich (z.B. wegen Policy-Filtern) keine Daten liefert. +5. **Deep Fallback Support:** Der Service stellt die Infrastruktur für den inhaltsbasierten Fallback (v2.11.14) bereit, falls die Cloud zwar technisch antwortet, aber inhaltlich (z.B. wegen Policy-Filtern oder Silent Refusal) keine validen Daten liefert. ---