78 lines
3.0 KiB
Markdown
78 lines
3.0 KiB
Markdown
|
---
|
||
|
|
doc_type: technical_reference
|
||
|
|
audience: developer, architect
|
||
|
|
scope: backend, chat, ollama, traffic_control
|
||
|
|
status: active
|
||
|
|
version: 2.6
|
||
|
|
context: "Technische Implementierung des FastAPI-Routers, der Decision Engine und des Traffic Control 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.
|
||
|
|
|
||
|
|
### 1.1 Intent-Erkennung (Logik)
|
||
|
|
|
||
|
|
Der Router prüft den Input in drei Stufen (Wasserfall-Prinzip):
|
||
|
|
|
||
|
|
1. **Question Detection (Regelbasiert):**
|
||
|
|
* 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").
|
||
|
|
* Wenn Match (z.B. "Projekt" + "neu"): **INTERVIEW Modus**.
|
||
|
|
3. **LLM Fallback (Slow Path):**
|
||
|
|
* Wenn unklar: Anfrage an LLM zur Klassifizierung.
|
||
|
|
|
||
|
|
### 1.2 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).
|
||
|
|
* 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.
|
||
|
|
5. **Post-Processing:** Anhängen des `Explanation` Layers (JSON-Breakdown) an das Ende des Streams.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. Traffic Control (WP-15)
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
### 2.1 Prioritäts-Semaphor
|
||
|
|
|
||
|
|
Jeder LLM-Request muss ein `priority`-Flag setzen.
|
||
|
|
|
||
|
|
**Prioritäten-Levels:**
|
||
|
|
|
||
|
|
| Priority | Verwendung | Limitierung |
|
||
|
|
| :--- | :--- | :--- |
|
||
|
|
| **realtime** | Chat-Anfragen | Keine (Hardware-Limit) |
|
||
|
|
| **background** | Smart Edge Allocation, Drafts | `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.
|
||
|
|
|
||
|
|
### 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).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. Feedback Traceability
|
||
|
|
|
||
|
|
Unterstützt das geplante Self-Tuning (WP08).
|
||
|
|
|
||
|
|
1. **Query ID:** Generiert bei jedem `/query` Call eine `UUIDv4`.
|
||
|
|
2. **Logging:** Speichert einen Snapshot in `data/logs/query_snapshot.jsonl` (Input + Retrieved Context).
|
||
|
|
3. **Feedback:** Der `/feedback` Endpoint verknüpft das User-Rating (1-5) mit der `query_id`.
|