Dokumentation WP20
This commit is contained in:
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).
|
||||
|
||||
|
||||
@@ -1,15 +1,15 @@
|
||||
---
|
||||
doc_type: technical_reference
|
||||
audience: developer, admin
|
||||
scope: configuration, env, registry, scoring
|
||||
scope: configuration, env, registry, scoring, resilience
|
||||
status: active
|
||||
version: 2.7.2
|
||||
context: "Umfassende Referenztabellen für Umgebungsvariablen, YAML-Konfigurationen und die Edge Registry Struktur."
|
||||
version: 2.8.0
|
||||
context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen und die Edge Registry Struktur."
|
||||
---
|
||||
|
||||
# Konfigurations-Referenz
|
||||
|
||||
Dieses Dokument beschreibt alle Steuerungsdateien von Mindnet. In der Version 2.7 wurde die Konfiguration professionalisiert, um die Edge Registry und dynamische Scoring-Parameter (Lifecycle & Intent) zu unterstützen.
|
||||
Dieses Dokument beschreibt alle Steuerungsdateien von Mindnet. In der Version 2.8 wurde die Konfiguration professionalisiert, um die Edge Registry, dynamische Scoring-Parameter (Lifecycle & Intent) sowie die neue Hybrid-Cloud-Resilienz zu unterstützen.
|
||||
|
||||
## 1. Environment Variablen (`.env`)
|
||||
|
||||
@@ -22,17 +22,25 @@ Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts.
|
||||
| `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (erzeugt `{prefix}_notes` etc). |
|
||||
| `VECTOR_DIM` | `768` | **Muss 768 sein** (für Nomic Embeddings). |
|
||||
| `MINDNET_VOCAB_PATH` | *(Pfad)* | **Neu (WP-22):** Absoluter Pfad zur `01_edge_vocabulary.md`. Definiert den Ort des Dictionarys. |
|
||||
| `MINDNET_VAULT_ROOT` | `./vault` | Basis-Pfad für Datei-Operationen. Dient als Fallback-Basis, falls `MINDNET_VOCAB_PATH` nicht gesetzt ist. |
|
||||
| `MINDNET_VAULT_ROOT` | `./vault` | Basis-Pfad für Datei-Operationen. |
|
||||
| `MINDNET_TYPES_FILE` | `config/types.yaml` | Pfad zur Typ-Registry. |
|
||||
| `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. |
|
||||
| `MINDNET_DECISION_CONFIG` | `config/decision_engine.yaml` | Pfad zur Router & Intent Config. |
|
||||
| `MINDNET_PROMPTS_PATH` | `config/prompts.yaml` | Pfad zu LLM Prompts. |
|
||||
| `MINDNET_LLM_MODEL` | `phi3:mini` | Name des Chat-Modells (Ollama). |
|
||||
| `MINDNET_LLM_PROVIDER` | `openrouter` | **Neu (WP-20):** Aktiver Provider (`openrouter`, `gemini`, `ollama`). |
|
||||
| `MINDNET_LLM_FALLBACK` | `true` | **Neu (WP-20):** Aktiviert automatischen Ollama-Fallback bei Cloud-Fehlern. |
|
||||
| `MINDNET_LLM_RATE_LIMIT_WAIT`| `60.0` | **Neu (WP-76):** Wartezeit in Sekunden bei HTTP 429 (Rate Limit). |
|
||||
| `MINDNET_LLM_RATE_LIMIT_RETRIES`| `3` | **Neu (WP-76):** Anzahl Cloud-Retries vor lokalem Fallback. |
|
||||
| `GOOGLE_API_KEY` | *(Key)* | API Key für Google AI Studio. |
|
||||
| `MINDNET_GEMINI_MODEL` | `gemini-2.5-flash-lite` | **Update 2025:** Optimiertes Lite-Modell für hohe Quoten. |
|
||||
| `OPENROUTER_API_KEY` | *(Key)* | API Key für OpenRouter Integration. |
|
||||
| `OPENROUTER_MODEL` | `mistralai/mistral-7b-instruct:free` | **Update 2025:** Verifiziertes Free-Modell für strukturierte Extraktion. |
|
||||
| `MINDNET_LLM_MODEL` | `phi3:mini` | Name des lokalen Chat-Modells (Ollama). |
|
||||
| `MINDNET_EMBEDDING_MODEL` | `nomic-embed-text` | Name des Embedding-Modells (Ollama). |
|
||||
| `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum LLM-Server. |
|
||||
| `MINDNET_LLM_TIMEOUT` | `300.0` | Timeout in Sekunden (Erhöht für CPU Cold-Starts). |
|
||||
| `MINDNET_API_TIMEOUT` | `300.0` | Frontend Timeout (Erhöht für Smart Edge Wartezeiten). |
|
||||
| `MINDNET_LLM_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Hintergrund-Tasks (Semaphore). |
|
||||
| `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum lokalen LLM-Server. |
|
||||
| `MINDNET_LLM_TIMEOUT` | `300.0` | Timeout in Sekunden für LLM-Anfragen. |
|
||||
| `MINDNET_API_TIMEOUT` | `300.0` | Globales API-Timeout für das Frontend. |
|
||||
| `MINDNET_LL_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Hintergrund-Tasks (Semaphore). |
|
||||
| `MINDNET_CHANGE_DETECTION_MODE` | `full` | `full` (Text + Meta) oder `body` (nur Text). |
|
||||
|
||||
---
|
||||
@@ -199,21 +207,21 @@ Die Datei muss eine Markdown-Tabelle enthalten, die vom Regex-Parser gelesen wir
|
||||
|
||||
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Beschreibung |
|
||||
| :--------------------- | :--------------------------------------------------- | :-------------------------------------- |
|
||||
| **`caused_by`** | `ausgelöst_durch`, `wegen`, `ursache_ist` | Kausalität: A löst B aus. |
|
||||
| **`derived_from`** | `abgeleitet_von`, `quelle`, `inspiriert_durch` | Herkunft: A stammt von B. |
|
||||
| **`based_on`** | `basiert_auf`, `fundament`, `grundlage` | Fundament: B baut auf A auf. |
|
||||
| **`solves`** | `löst`, `beantwortet`, `fix_für` | Lösung: A ist Lösung für Problem B. |
|
||||
| **`part_of`** | `teil_von`, `gehört_zu`, `cluster` | Hierarchie: Kind -> Eltern. |
|
||||
| **`depends_on`** | `hängt_ab_von`, `braucht`, `requires`, `enforced_by` | Abhängigkeit: A braucht B. |
|
||||
| **`blocks`** | `blockiert`, `verhindert`, `risiko_für` | Blocker: A verhindert B. |
|
||||
| **`uses`** | `nutzt`, `verwendet`, `tool` | Werkzeug: A nutzt B. |
|
||||
| **`guides`** | `steuert`, `leitet`, `orientierung` | Soft-Dependency: A gibt Richtung für B. |
|
||||
| **`followed_by`** | `danach`, `folgt`, `nachfolger`, `followed_by` | Prozess: A -> B. |
|
||||
| **`preceeded_by`** | `davor`, `vorgänger`, `preceded_by` | Prozess: B <- A. |
|
||||
| **`related_to`** | `siehe_auch`, `kontext`, `thematisch` | Lose Assoziation. |
|
||||
| **`similar_to`** | `ähnlich_wie`, `vergleichbar` | Synonym / Ähnlichkeit. |
|
||||
| **`references`** | *(Kein Alias)* | Standard-Verweis (Fallback). |
|
||||
| **`resulted_in`** | `ergebnis`, `resultat`, `erzeugt` | Herkunft: A erzeugt Ergebnis B |
|
||||
| **`caused_by`** | `ausgelöst_durch`, `wegen`, `ursache_ist` | Kausalität: A löst B aus. |
|
||||
| **`derived_from`** | `abgeleitet_von`, `quelle`, `inspiriert_durch` | Herkunft: A stammt von B. |
|
||||
| **`based_on`** | `basiert_auf`, `fundament`, `grundlage` | Fundament: B baut auf A auf. |
|
||||
| **`solves`** | `löst`, `beantwortet`, `fix_für` | Lösung: A ist Lösung für Problem B. |
|
||||
| **`part_of`** | `teil_von`, `gehört_zu`, `cluster` | Hierarchie: Kind -> Eltern. |
|
||||
| **`depends_on`** | `hängt_ab_von`, `braucht`, `requires`, `enforced_by` | Abhängigkeit: A braucht B. |
|
||||
| **`blocks`** | `blockiert`, `verhindert`, `risiko_für` | Blocker: A verhindert B. |
|
||||
| **`uses`** | `nutzt`, `verwendet`, `tool` | Werkzeug: A nutzt B. |
|
||||
| **`guides`** | `steuert`, `leitet`, `orientierung` | Soft-Dependency: A gibt Richtung für B. |
|
||||
| **`followed_by`** | `danach`, `folgt`, `nachfolger`, `followed_by` | Prozess: A -> B. |
|
||||
| **`preceeded_by`** | `davor`, `vorgänger`, `preceded_by` | Prozess: B <- A. |
|
||||
| **`related_to`** | `siehe_auch`, `kontext`, `thematisch` | Lose Assoziation. |
|
||||
| **`similar_to`** | `ähnlich_wie`, `vergleichbar` | Synonym / Ähnlichkeit. |
|
||||
| **`references`** | *(Kein Alias)* | Standard-Verweis (Fallback). |
|
||||
| **`resulted_in`** | `ergebnis`, `resultat`, `erzeugt` | Herkunft: A erzeugt Ergebnis B |
|
||||
|
||||
**ACHTUNG!** Die Kantentypen
|
||||
**belongs_to**, **next** und **prev** dürfen nicht vom Nutzer gesetzt werden
|
||||
|
||||
@@ -3,15 +3,15 @@ doc_type: technical_reference
|
||||
audience: developer, devops
|
||||
scope: backend, ingestion, smart_edges, edge_registry
|
||||
status: active
|
||||
version: 2.7.1
|
||||
context: "Detaillierte technische Beschreibung der Import-Pipeline, Chunking-Strategien und CLI-Befehle."
|
||||
version: 2.8.0
|
||||
context: "Detaillierte technische Beschreibung der Import-Pipeline, Mistral-safe Parsing und WP-76 Resilienz-Logik."
|
||||
---
|
||||
|
||||
# Ingestion Pipeline & Smart Processing
|
||||
|
||||
**Quellen:** `pipeline_playbook.md`, `Handbuch.md`, `edge_registry.py`, `01_edge_vocabulary.md`, `06_active_roadmap.md`
|
||||
**Quellen:** `pipeline_playbook.md`, `ingestion.py`, `edge_registry.py`, `01_edge_vocabulary.md`, `llm_service.py`
|
||||
|
||||
Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py` (CLI) oder `routers/ingest.py` (API). Seit v2.7 integriert dieser Prozess die **Edge Registry** zur Normalisierung des Vokabulars und beachtet den **Content Lifecycle**.
|
||||
Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py` (CLI) oder `routers/ingest.py` (API). Seit v2.8 integriert dieser Prozess eine **intelligente Quoten-Steuerung** (WP-76) und ein **robustes JSON-Parsing** für Cloud-Modelle (Mistral/Gemini).
|
||||
|
||||
## 1. Der Import-Prozess (15-Schritte-Workflow)
|
||||
|
||||
@@ -38,10 +38,11 @@ Der Prozess ist **asynchron** und **idempotent**.
|
||||
* Vergleich des Hashes mit Qdrant.
|
||||
* Strategie wählbar via ENV `MINDNET_CHANGE_DETECTION_MODE` (`full` oder `body`).
|
||||
8. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3).
|
||||
9. **Smart Edge Allocation (WP15):**
|
||||
9. **Smart Edge Allocation (WP15/WP20):**
|
||||
* Wenn `enable_smart_edge_allocation: true`: Der `SemanticAnalyzer` sendet Chunks an das LLM.
|
||||
* **Traffic Control:** Request nutzt `priority="background"`. Semaphore (Limit via `.env`) drosselt die Last.
|
||||
* **Resilienz:** Bei Timeout (Ollama) greift ein Fallback (Broadcasting an alle Chunks).
|
||||
* **Traffic Control:** Request nutzt `priority="background"`. Semaphore drosselt die Last.
|
||||
* **Resilienz (WP-76):** Erkennt HTTP 429 (Rate-Limit) und pausiert kontrolliert (via `LLM_RATE_LIMIT_WAIT`), bevor ein Cloud-Retry oder der lokale Fallback erfolgt.
|
||||
* **Mistral-safe Parsing:** Automatisierte Bereinigung von BOS-Tokens (`<s>`) und Framework-Tags (`[OUT]`) zur Sicherstellung validen JSONs.
|
||||
10. **Inline-Kanten finden:** Parsing von `[[rel:...]]`.
|
||||
11. **Alias-Auflösung & Kanonisierung (WP-22):**
|
||||
* Jede Kante wird via `edge_registry.resolve()` normalisiert.
|
||||
@@ -138,20 +139,20 @@ Die Strategie `by_heading` zerlegt Texte anhand ihrer Struktur (Überschriften).
|
||||
|
||||
Kanten werden nach Vertrauenswürdigkeit (`provenance`) priorisiert. Die höhere Prio gewinnt.
|
||||
|
||||
| Prio | Quelle | Rule ID | Confidence | Erläuterung |
|
||||
| Prio | Quelle | Rule ID / Provenance | Confidence | Erläuterung |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **1** | Wikilink | `explicit:wikilink` | **1.00** | Harte menschliche Setzung. |
|
||||
| **2** | Inline | `inline:rel` | **0.95** | Typisierte menschliche Kante. |
|
||||
| **3** | Callout | `callout:edge` | **0.90** | Explizite Meta-Information. |
|
||||
| **4** | Smart Edge | `smart:llm_filter` | **0.90** | KI-validierte Verbindung. |
|
||||
| **4** | Semantic AI | `semantic_ai` | **0.90** | KI-extrahierte Verbindung (Mistral-safe). |
|
||||
| **5** | Type Default | `edge_defaults` | **0.70** | Heuristik aus der Registry. |
|
||||
| **6** | Struktur | `structure` | **1.00** | System-interne Verkettung. |
|
||||
| **6** | Struktur | `structure` | **1.00** | System-interne Verkettung (`belongs_to`). |
|
||||
|
||||
---
|
||||
|
||||
## 5. Quality Gates & Monitoring
|
||||
|
||||
In v2.7 wurden Tools zur Überwachung der Datenqualität integriert:
|
||||
In v2.7+ wurden Tools zur Überwachung der Datenqualität integriert:
|
||||
|
||||
**1. Registry Review:** Prüfung der `data/logs/unknown_edges.jsonl`. Administratoren sollten hier gelistete Begriffe als Aliase in die `01_edge_vocabulary.md` aufnehmen.
|
||||
|
||||
|
||||
Reference in new issue
Block a user