Dokumentation WP20

This commit is contained in:
Lars committed 2025-12-25 19:39:16 +01:00
1 parent 16e128668c
commit 27b404560c
7 files changed
+193 -113

No files matched your search

@@ -1,17 +1,17 @@
---
doc_type: technical_reference
audience: developer, architect
scope: backend, chat, ollama, traffic_control
scope: backend, chat, llm_service, traffic_control, resilience
status: active
version: 2.6
context: "Technische Implementierung des FastAPI-Routers, der Decision Engine und des Traffic Control Systems."
version: 2.8
context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService und des WP-76 Resilienz-Systems."
---
# Chat Backend & Traffic Control
## 1. Hybrid Router (Decision Engine)
Der zentrale Einstiegspunkt für jede Chatanfrage ist der **Hybrid Router** (`app/routers/chat.py`). Er entscheidet dynamisch, welche Strategie gewählt wird, basierend auf dem User-Input.
Der zentrale Einstiegspunkt für jede Chatanfrage ist der **Hybrid Router** (`app/routers/chat.py`). Er entscheidet dynamisch über die Strategie und nutzt den `LLMService` zur provider-agnostischen Generierung.
### 1.1 Intent-Erkennung (Logik)
@@ -21,18 +21,26 @@ Der Router prüft den Input in drei Stufen (Wasserfall-Prinzip):
* Prüfung auf Vorhandensein von `?` oder W-Wörtern (Wer, Wie, Was, Soll ich).
* Wenn positiv: **RAG Modus** (Interview wird blockiert).
2. **Keyword Scan (Fast Path):**
* Lädt `types.yaml` (Objekte, z.B. "Projekt") und `decision_engine.yaml` (Handlungen, z.B. "neu").
* Lädt `types.yaml` (Objekte) und `decision_engine.yaml` (Handlungen).
* Wenn Match (z.B. "Projekt" + "neu"): **INTERVIEW Modus**.
3. **LLM Fallback (Slow Path):**
* Wenn unklar: Anfrage an LLM zur Klassifizierung.
* Wenn unklar: Anfrage an LLM zur Klassifizierung mittels `router_prompt`.
### 1.2 RAG Flow (Technisch)
### 1.2 Prompt-Auflösung (WP-20 Fix)
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()`.
### 1.3 RAG Flow (Technisch)
Wenn der Intent `FACT` oder `DECISION` ist, wird folgender Flow ausgeführt:
1. **Pre-Processing:** Query Rewriting (optional).
2. **Context Enrichment:**
* Abruf via `retriever.py` (Hybrid Search).
* Integration von **Edge Boosts** aus der `decision_engine.yaml` zur Beeinflussung der Graph-Gewichtung.
* Injection von Metadaten (`[TYPE]`, `[SCORE]`) in den Prompt.
3. **Prompt Construction:** Assembly aus System-Prompt (Persona) + Context + Query.
4. **Streaming:** LLM-Antwort wird via **SSE (Server-Sent Events)** an den Client gestreamt.
@@ -40,36 +48,44 @@ Wenn der Intent `FACT` oder `DECISION` ist, wird folgender Flow ausgeführt:
---
## 2. Traffic Control (WP-15)
## 2. LLM Service & Traffic Control (WP-15/WP-20)
Das Traffic Control System (`app/core/llm_service.py`) schützt das System vor Überlastung, wenn rechenintensive Hintergrundprozesse (Smart Edge Import) und Latenz-kritische Chat-Anfragen gleichzeitig laufen.
Der `LLMService` (`app/services/llm_service.py`) fungiert als zentraler Hybrid-Client für OpenRouter, Google Gemini und Ollama. Er schützt das System vor Überlastung und verwaltet Quoten.
### 2.1 Prioritäts-Semaphor
Jeder LLM-Request muss ein `priority`-Flag setzen.
**Prioritäten-Levels:**
Jeder LLM-Request steuert über ein `priority`-Flag den Zugriff auf Hardware- und API-Ressourcen:
| Priority | Verwendung | Limitierung |
| :--- | :--- | :--- |
| **realtime** | Chat-Anfragen | Keine (Hardware-Limit) |
| **background** | Smart Edge Allocation, Drafts | `MINDNET_LLM_BACKGROUND_LIMIT` |
| **realtime** | Chat-Anfragen, Intent-Routing | Keine (Hardware-Limit) |
| **background** | Smart Edge Allocation, Import-Tasks | `MINDNET_LLM_BACKGROUND_LIMIT` |
**Funktionsweise:**
* Hintergrund-Tasks nutzen `asyncio.Semaphore`.
* Wenn das Limit (Default: 2) erreicht ist, warten weitere Import-Tasks.
* Chat-Tasks umgehen die Semaphore und werden sofort bearbeitet.
* 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.
* Chat-Tasks umgehen die Semaphore für minimale Latenz.
### 2.2 Timeout-Konfiguration
Deadlocks werden durch strikte Timeouts verhindert, die in der `.env` definiert sind.
* **Chat:** `MINDNET_LLM_TIMEOUT` (Default: 300s).
* **Frontend:** `MINDNET_API_TIMEOUT` (Default: 300s).
Deadlocks und "hängende" Importe werden durch differenzierte Timeouts verhindert:
* **Cloud-Calls (OpenRouter/Gemini):** Strikte **45 Sekunden** zur Vermeidung von Blockaden bei Provider-Latenz.
* **Lokales LLM (Ollama):** Konfigurierbar via `MINDNET_LLM_TIMEOUT` (Default: 300s).
---
## 3. Feedback Traceability
## 3. Resilience & Quota Management (WP-76)
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).
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").
---
## 4. Feedback Traceability
Unterstützt das geplante Self-Tuning (WP08).