neue Dokumentationstruktur - (QS geprüft)
Deploy mindnet to llm-node / deploy (push) Successful in 4s
Deploy mindnet to llm-node / deploy (push) Successful in 4s
This commit is contained in:
1 parent
0bb5f57cc6
commit
620858a575
39 files changed
+1840
No files matched your search
@@ -0,0 +1,78 @@
|
||||
---
|
||||
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`.
|
||||
@@ -0,0 +1,132 @@
|
||||
---
|
||||
doc_type: technical_reference
|
||||
audience: developer, admin
|
||||
scope: configuration, env
|
||||
status: active
|
||||
version: 2.6
|
||||
context: "Referenztabellen für Umgebungsvariablen und YAML-Konfigurationen."
|
||||
---
|
||||
|
||||
# Konfigurations-Referenz
|
||||
|
||||
Dieses Dokument beschreibt die Steuerungsdateien von Mindnet.
|
||||
|
||||
## 1. Environment Variablen (`.env`)
|
||||
|
||||
Diese Variablen steuern die Infrastruktur, Timeouts und Feature-Flags.
|
||||
|
||||
| Variable | Default | Beschreibung |
|
||||
| :--- | :--- | :--- |
|
||||
| `QDRANT_URL` | `http://localhost:6333` | URL zur Vektor-DB API. |
|
||||
| `QDRANT_API_KEY` | *(leer)* | Optionaler Key für Absicherung. |
|
||||
| `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (erzeugt `{prefix}_notes` etc). |
|
||||
| `VECTOR_DIM` | `768` | **Muss 768 sein** (für Nomic Embeddings). |
|
||||
| `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_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 Import-Tasks. |
|
||||
| `MINDNET_VAULT_ROOT` | `./vault` | Pfad für Write-Back Operationen (Drafts). |
|
||||
| `MINDNET_HASH_COMPARE` | `Body` | Import-Strategie: `Body`, `Frontmatter` oder `Full`. |
|
||||
| `MINDNET_HASH_SOURCE` | `parsed` | Hash-Quelle: `parsed`, `raw` oder `file`. |
|
||||
|
||||
---
|
||||
|
||||
## 2. Typ-Registry (`types.yaml`)
|
||||
|
||||
Steuert das Import-Verhalten, Chunking und die Kanten-Logik pro Typ.
|
||||
|
||||
**Referenztabelle (Stand v2.6):**
|
||||
|
||||
| Typ (`type`) | Chunk Profile | Retriever Weight | Smart Edges? | Beschreibung |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **concept** | `sliding_smart_edges` | 0.60 | Ja | Abstrakte Begriffe. |
|
||||
| **project** | `sliding_smart_edges` | 0.97 | Ja | Aktive Vorhaben. |
|
||||
| **decision** | `structured_smart_edges` | 1.00 | Ja | Entscheidungen (ADRs). |
|
||||
| **experience** | `sliding_smart_edges` | 0.90 | Ja | Persönliche Learnings. |
|
||||
| **journal** | `sliding_standard` | 0.80 | Nein | Logs / Dailies. |
|
||||
| **value** | `structured_smart_edges` | 1.00 | Ja | Werte/Prinzipien. |
|
||||
| **risk** | `sliding_short` | 0.90 | Nein | Risiken. |
|
||||
| **person** | `sliding_standard` | 0.50 | Nein | Profile. |
|
||||
| **source** | `sliding_standard` | 0.50 | Nein | Externe Quellen. |
|
||||
| **event** | `sliding_standard` | 0.60 | Nein | Meetings. |
|
||||
| **goal** | `sliding_standard` | 0.95 | Nein | Strategische Ziele. |
|
||||
| **belief** | `sliding_short` | 0.90 | Nein | Glaubenssätze. |
|
||||
| **default** | `sliding_standard` | 1.00 | Nein | Fallback. |
|
||||
|
||||
*Hinweis: `Smart Edges?` entspricht dem YAML-Key `enable_smart_edge_allocation: true`.*
|
||||
|
||||
---
|
||||
|
||||
## 3. Retriever Config (`retriever.yaml`)
|
||||
|
||||
Steuert die Gewichtung der Scoring-Formel (WP04a).
|
||||
|
||||
**Beispielkonfiguration:**
|
||||
|
||||
```yaml
|
||||
scoring:
|
||||
semantic_weight: 1.0 # Basis-Relevanz (Cosine Similarity)
|
||||
edge_weight: 0.7 # Einfluss des Graphen (Bonus)
|
||||
centrality_weight: 0.5 # Einfluss von Hubs
|
||||
|
||||
edge_weights:
|
||||
# Multiplikatoren für den Edge-Bonus
|
||||
depends_on: 1.5 # Harte Abhängigkeiten stark gewichten
|
||||
blocks: 1.5 # Risiken stark gewichten
|
||||
caused_by: 1.2 # Kausalitäten stärken
|
||||
related_to: 0.5 # Weiche Themen schwächer gewichten
|
||||
references: 0.8 # Standard-Referenzen
|
||||
based_on: 1.3 # Werte-Bezug
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Edge Typen Referenz
|
||||
|
||||
Definiert die Semantik der `kind`-Felder in der Edge-Collection.
|
||||
|
||||
| Kind | Symmetrisch? | Herkunft (Primär) | Bedeutung |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `references` | Nein | Wikilink | Standard-Verweis. "Erwähnt X". |
|
||||
| `belongs_to` | Nein | Struktur | Chunk gehört zu Note. |
|
||||
| `next` / `prev` | Ja | Struktur | Lesereihenfolge. |
|
||||
| `depends_on` | Nein | Inline / Default | Harte Abhängigkeit. |
|
||||
| `related_to` | Ja | Callout / Default | Thematische Nähe. |
|
||||
| `similar_to` | Ja | Inline | Inhaltliche Ähnlichkeit. |
|
||||
| `caused_by` | Nein | Inline | Kausalität. |
|
||||
| `solves` | Nein | Inline | Lösung für ein Problem. |
|
||||
| `blocks` | Nein | Inline | Blockade / Risiko. |
|
||||
| `derived_from` | Nein | Matrix | Herkunft (z.B. Prinzip -> Buch). |
|
||||
| `based_on` | Nein | Matrix | Fundament (z.B. Erfahrung -> Wert). |
|
||||
| `uses` | Nein | Matrix | Nutzung (z.B. Projekt -> Tool). |
|
||||
|
||||
---
|
||||
|
||||
## 5. Decision Engine (`decision_engine.yaml`)
|
||||
|
||||
Steuert den Hybrid Router (WP06). Definiert, welche Keywords welche Strategie auslösen.
|
||||
|
||||
**Beispielauszug:**
|
||||
|
||||
```yaml
|
||||
# Strategie-Definitionen
|
||||
strategies:
|
||||
DECISION:
|
||||
description: "Hilfe bei Entscheidungen"
|
||||
inject_types: ["value", "principle", "goal", "risk"] # Strategic Retrieval
|
||||
llm_fallback_enabled: true
|
||||
|
||||
INTERVIEW:
|
||||
description: "Wissenserfassung"
|
||||
trigger_keywords: ["erstellen", "neu", "anlegen", "festhalten"]
|
||||
|
||||
EMPATHY:
|
||||
description: "Emotionaler Support"
|
||||
inject_types: ["experience", "belief"]
|
||||
```
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
doc_type: technical_reference
|
||||
audience: developer, architect
|
||||
scope: database, qdrant, schema
|
||||
status: active
|
||||
version: 2.6
|
||||
context: "Exakte Definition der Datenmodelle (Payloads) in Qdrant und Index-Anforderungen."
|
||||
---
|
||||
|
||||
# Technisches Datenmodell (Qdrant Schema)
|
||||
|
||||
## 1. Collections & Namenskonvention
|
||||
|
||||
Mindnet speichert Daten in drei getrennten Qdrant-Collections. Der Prefix ist via ENV `COLLECTION_PREFIX` konfigurierbar (Default: `mindnet`).
|
||||
|
||||
Das System nutzt folgende drei Collections:
|
||||
* `{prefix}_notes`: Metadaten der Dateien.
|
||||
* `{prefix}_chunks`: Vektorisierte Textsegmente.
|
||||
* `{prefix}_edges`: Gerichtete Graph-Kanten.
|
||||
|
||||
---
|
||||
|
||||
## 2. Note Payload (`mindnet_notes`)
|
||||
|
||||
Repräsentiert die Metadaten einer Markdown-Datei (1:1 Beziehung).
|
||||
|
||||
**JSON-Schema:**
|
||||
|
||||
```json
|
||||
{
|
||||
"note_id": "string (keyword)", // UUIDv5 (deterministisch) oder Slug
|
||||
"title": "string (text)", // Titel aus Frontmatter
|
||||
"type": "string (keyword)", // Logischer Typ (z.B. 'project', 'concept')
|
||||
"retriever_weight": "float", // Numerische Wichtigkeit (0.0-1.0), aus types.yaml
|
||||
"chunk_profile": "string", // Genutztes Profil (z.B. 'sliding_smart_edges')
|
||||
"edge_defaults": ["string"], // Liste der aktiven Default-Kanten
|
||||
"tags": ["string"], // Liste von Tags aus Frontmatter
|
||||
"created": "string (iso-date)", // Erstellungsdatum
|
||||
"updated": "integer", // Timestamp (File Modification Time)
|
||||
"fulltext": "string (no-index)" // Gesamter Text (nur für Recovery/Export)
|
||||
}
|
||||
```
|
||||
|
||||
**Erforderliche Indizes:**
|
||||
Es müssen Payload-Indizes für folgende Felder existieren:
|
||||
* `note_id`
|
||||
* `type`
|
||||
* `tags`
|
||||
|
||||
---
|
||||
|
||||
## 3. Chunk Payload (`mindnet_chunks`)
|
||||
|
||||
Die atomare Sucheinheit. Enthält den Vektor.
|
||||
|
||||
**Vektor-Konfiguration:**
|
||||
* Modell: `nomic-embed-text`
|
||||
* Dimension: **768**
|
||||
* Metrik: Cosine Similarity
|
||||
|
||||
**JSON-Schema:**
|
||||
|
||||
```json
|
||||
{
|
||||
"chunk_id": "string (keyword)", // Format: {note_id}#c{index} (z.B. 'abc-123#c01')
|
||||
"note_id": "string (keyword)", // Foreign Key zur Note
|
||||
"type": "string (keyword)", // Kopie aus Note (Denormalisiert für Filterung)
|
||||
"text": "string (text)", // Reintext für Anzeige (ohne Overlap)
|
||||
"window": "string (text)", // Text + Overlap (Basis für Embedding)
|
||||
"ord": "integer", // Laufende Nummer (1..N) für Sortierung
|
||||
"retriever_weight": "float", // Kopie aus Note (für Query-Speed)
|
||||
"chunk_profile": "string", // Vererbt von Note
|
||||
"neighbors_prev": ["string"], // ID des Vorgängers (Linked List)
|
||||
"neighbors_next": ["string"] // ID des Nachfolgers
|
||||
}
|
||||
```
|
||||
|
||||
**Erforderliche Indizes:**
|
||||
Es müssen Payload-Indizes für folgende Felder existieren:
|
||||
* `note_id`
|
||||
* `chunk_id`
|
||||
* `type`
|
||||
|
||||
---
|
||||
|
||||
## 4. Edge Payload (`mindnet_edges`)
|
||||
|
||||
Gerichtete Kanten zwischen Knoten. Stark erweitert in v2.6 für Provenienz-Tracking.
|
||||
|
||||
**JSON-Schema:**
|
||||
|
||||
```json
|
||||
{
|
||||
"edge_id": "string (keyword)", // Deterministischer Hash aus (src, dst, kind)
|
||||
"source_id": "string (keyword)", // Chunk-ID (Start)
|
||||
"target_id": "string (keyword)", // Chunk-ID oder Note-Titel (bei Unresolved)
|
||||
"kind": "string (keyword)", // Beziehungsart (z.B. 'depends_on')
|
||||
"scope": "string (keyword)", // Immer 'chunk' (Legacy-Support: 'note')
|
||||
"note_id": "string (keyword)", // Owner Note ID (Ursprung der Kante)
|
||||
|
||||
// Provenance & Quality (WP03/WP15)
|
||||
"provenance": "keyword", // 'explicit', 'rule', 'smart' (NEU)
|
||||
"rule_id": "string (keyword)", // Traceability: 'inline:rel', 'explicit:wikilink', 'smart:llm'
|
||||
"confidence": "float" // Vertrauenswürdigkeit (0.0 - 1.0)
|
||||
}
|
||||
```
|
||||
|
||||
**Erforderliche Indizes:**
|
||||
Es müssen Payload-Indizes für folgende Felder existieren:
|
||||
* `source_id`
|
||||
* `target_id`
|
||||
* `kind`
|
||||
* `scope`
|
||||
* `note_id`
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
doc_type: technical_reference
|
||||
audience: developer, devops
|
||||
scope: backend, ingestion, smart_edges
|
||||
status: active
|
||||
version: 2.6
|
||||
context: "Detaillierte technische Beschreibung der Import-Pipeline, Quality Gates und CLI-Befehle."
|
||||
---
|
||||
|
||||
# Ingestion Pipeline & Smart Processing
|
||||
|
||||
**Quellen:** `pipeline_playbook.md`, `Handbuch.md`
|
||||
|
||||
Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py`.
|
||||
|
||||
## 1. Der Import-Prozess (13-Schritte-Workflow)
|
||||
|
||||
Der Prozess ist **asynchron** und **idempotent**.
|
||||
|
||||
1. **Markdown lesen:** Rekursives Scannen des Vaults.
|
||||
2. **Frontmatter extrahieren:** Validierung von Pflichtfeldern (`id`, `type`, `title`).
|
||||
3. **Typauflösung:** Bestimmung des `type` via `types.yaml`.
|
||||
4. **Note-Payload generieren:** Erstellen des JSON-Objekts für `mindnet_notes`.
|
||||
5. **Chunking anwenden:** Zerlegung des Textes basierend auf dem `chunk_profile` (siehe unten).
|
||||
6. **Smart Edge Allocation (WP15):**
|
||||
* Wenn `enable_smart_edge_allocation: true`: Der `SemanticAnalyzer` sendet Chunks an das LLM.
|
||||
* **Traffic Control:** Request nutzt `priority="background"`. Semaphore (Limit: 2) drosselt die Last.
|
||||
* **Resilienz:** Bei Timeout (Ollama) greift ein Fallback (Broadcasting an alle Chunks).
|
||||
7. **Inline-Kanten finden:** Parsing von `[[rel:...]]`.
|
||||
8. **Callout-Kanten finden:** Parsing von `> [!edge]`.
|
||||
9. **Default-Edges erzeugen:** Anwendung der `edge_defaults` aus Registry.
|
||||
10. **Strukturkanten erzeugen:** `belongs_to`, `next`, `prev`.
|
||||
11. **Embedding (Async):** Generierung via `nomic-embed-text` (768d).
|
||||
12. **Strict Mode:** Abbruch bei leeren Embeddings oder Dimension 0.
|
||||
13. **Diagnose:** Integritäts-Check nach dem Lauf.
|
||||
|
||||
---
|
||||
|
||||
## 2. Betrieb & CLI Befehle
|
||||
|
||||
### 2.1 Standard-Betrieb (Inkrementell)
|
||||
Für regelmäßige Updates (Cronjob). Erkennt Änderungen via Hash.
|
||||
|
||||
```bash
|
||||
export QDRANT_URL="http://localhost:6333"
|
||||
export COLLECTION_PREFIX="mindnet"
|
||||
|
||||
# Nutzt das Venv der Produktionsumgebung
|
||||
/home/llmadmin/mindnet/.venv/bin/python3 -m scripts.import_markdown \
|
||||
--vault ./vault \
|
||||
--prefix "$COLLECTION_PREFIX" \
|
||||
--apply \
|
||||
--purge-before-upsert \
|
||||
--sync-deletes
|
||||
```
|
||||
|
||||
> **[!WARNING] Purge-Before-Upsert**
|
||||
> Das Flag `--purge-before-upsert` ist kritisch. Es löscht vor dem Schreiben einer Note ihre alten Chunks/Edges. Ohne dieses Flag entstehen **"Geister-Chunks"** (alte Textabschnitte, die im Markdown gelöscht wurden, aber im Index verbleiben).
|
||||
|
||||
### 2.2 Full Rebuild (Clean Slate)
|
||||
Notwendig bei Änderungen an `types.yaml` oder Modell-Wechsel.
|
||||
|
||||
```bash
|
||||
# 0. Modell sicherstellen
|
||||
ollama pull nomic-embed-text
|
||||
|
||||
# 1. Qdrant Collections löschen (Wipe)
|
||||
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
|
||||
|
||||
# 2. Vollständiger Import (Force)
|
||||
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Chunking & Payload
|
||||
|
||||
Das Chunking ist profilbasiert.
|
||||
|
||||
| Profil | Max Token | Overlap | Einsatz |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `sliding_short` | 128 | 20 | Logs, Chats. |
|
||||
| `sliding_standard` | 512 | 50 | Massendaten. |
|
||||
| `sliding_smart_edges`| 512 | 50 | Wichtige Inhalte (Experience, Project). |
|
||||
| `structured_smart` | n/a | n/a | Trennt strikt an Headings (für ADRs). |
|
||||
|
||||
**Payload-Felder:**
|
||||
* `text`: Der reine Inhalt (Anzeige).
|
||||
* `window`: Inhalt plus Overlap (für Embedding).
|
||||
|
||||
---
|
||||
|
||||
## 4. Edge-Erzeugung & Prioritäten
|
||||
|
||||
Kanten werden nach Vertrauenswürdigkeit (`provenance`) priorisiert. Die höhere Prio gewinnt.
|
||||
|
||||
| Prio | Quelle | Rule ID | Confidence |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **1** | Inline | `inline:rel` | 0.95 |
|
||||
| **2** | Callout | `callout:edge` | 0.90 |
|
||||
| **3** | Wikilink | `explicit:wikilink` | 1.00 |
|
||||
| **4** | Smart Edge | `smart:llm_filter` | 0.90 |
|
||||
| **5** | Type Default | `edge_defaults` | 0.70 |
|
||||
| **6** | Struktur | `structure` | 1.00 |
|
||||
|
||||
---
|
||||
|
||||
## 5. Quality Gates & Tests
|
||||
|
||||
Diese Tests garantieren die Stabilität der Pipeline.
|
||||
|
||||
**1. Payload Dryrun (Schema-Check):**
|
||||
Simuliert Import, prüft JSON-Schema Konformität.
|
||||
```bash
|
||||
python3 -m scripts.payload_dryrun --vault ./test_vault
|
||||
```
|
||||
|
||||
**2. Full Edge Check (Graph-Integrität):**
|
||||
Prüft Invarianten (z.B. `next` muss reziprok zu `prev` sein).
|
||||
```bash
|
||||
python3 -m scripts.edges_full_check
|
||||
```
|
||||
@@ -0,0 +1,113 @@
|
||||
---
|
||||
doc_type: technical_reference
|
||||
audience: developer, data_scientist
|
||||
scope: backend, retrieval, scoring
|
||||
status: active
|
||||
version: 2.6
|
||||
context: "Formeln und Algorithmen des Hybrid Retrievers und Explanation Layer."
|
||||
---
|
||||
|
||||
# Retrieval & Scoring Algorithmen
|
||||
|
||||
Der Retriever (`app/core/retriever.py`) unterstützt **Semantic Search** und **Hybrid Search**. Seit v2.4 (WP04a) nutzt Mindnet ein gewichtetes Scoring-Modell, das Semantik, Graphentheorie und Metadaten kombiniert.
|
||||
|
||||
## 1. Scoring Formel (WP04a)
|
||||
|
||||
Der Gesamtscore eines Treffers berechnet sich als gewichtete Summe. Alle Gewichte ($W$) sind in `retriever.yaml` konfigurierbar.
|
||||
|
||||
$$
|
||||
TotalScore = (W_{sem} \cdot S_{sem} \cdot \max(W_{type}, 0)) + (W_{edge} \cdot B_{edge}) + (W_{cent} \cdot B_{cent})
|
||||
$$
|
||||
|
||||
### Die Komponenten
|
||||
|
||||
**1. Semantic Score ($S_{sem}$):**
|
||||
* **Basis:** Cosine Similarity des Vektors.
|
||||
* **Modell:** `nomic-embed-text` (768d).
|
||||
* **Wertebereich:** 0.0 bis 1.0.
|
||||
|
||||
**2. Type Weight ($W_{type}$):**
|
||||
* **Herkunft:** Feld `retriever_weight` aus der Note/Chunk Payload.
|
||||
* **Zweck:** Priorisierung bestimmter Dokumententypen unabhängig vom Inhalt.
|
||||
* **Beispiel:** Eine `decision` (Gewicht 1.0) schlägt ein `concept` (Gewicht 0.6) bei gleicher textueller Ähnlichkeit.
|
||||
|
||||
**3. Edge Bonus ($B_{edge}$):**
|
||||
* **Kontext:** Berechnet im lokalen Subgraphen (Expansion Tiefe 1).
|
||||
* **Logik:** Summe der `confidence` aller eingehenden Kanten, die von Knoten stammen, die *ebenfalls* im aktuellen Result-Set (oder dem übergebenen Kontext) enthalten sind.
|
||||
* **Zweck:** Belohnt Chunks, die "im Thema" vernetzt sind.
|
||||
|
||||
**4. Centrality Bonus ($B_{cent}$):**
|
||||
* **Kontext:** Berechnet im lokalen Subgraphen.
|
||||
* **Logik:** Eine vereinfachte PageRank-Metrik (Degree Centrality) im temporären Graphen.
|
||||
* **Zweck:** Belohnt "Hubs", die viele Verbindungen zu anderen Treffern haben.
|
||||
|
||||
---
|
||||
|
||||
## 2. Hybrid Retrieval Flow
|
||||
|
||||
Der Hybrid-Modus ist der Standard für den Chat (`/chat`). Er läuft in drei Phasen ab:
|
||||
|
||||
**Phase 1: Vector Search (Seed Generation)**
|
||||
* Suche die Top-K (z.B. 20) Kandidaten via Embeddings in Qdrant.
|
||||
* Dies sind die "Seeds" für den Graphen.
|
||||
|
||||
**Phase 2: Graph Expansion**
|
||||
* Nutze `graph_adapter.expand(seeds, depth=1)`.
|
||||
* Lade alle direkten Nachbarn (Incoming & Outgoing) der Seeds aus der `_edges` Collection.
|
||||
* Konstruiere einen temporären `NetworkX`-Graphen im Speicher (`Subgraph`).
|
||||
|
||||
**Phase 3: Re-Ranking**
|
||||
* Berechne für jeden Knoten im Subgraphen die Boni ($B_{edge}$, $B_{cent}$).
|
||||
* Wende die Scoring-Formel an.
|
||||
* Sortiere die Liste neu absteigend nach `TotalScore`.
|
||||
* Schneide die Liste beim finalen Limit (z.B. 5) ab.
|
||||
|
||||
---
|
||||
|
||||
## 3. Explanation Layer (WP04b)
|
||||
|
||||
Wenn der Parameter `explain=True` an die API übergeben wird, generiert der Retriever ein `Explanation` Objekt für jeden Treffer.
|
||||
|
||||
**JSON-Struktur der Erklärung:**
|
||||
|
||||
```json
|
||||
{
|
||||
"score_breakdown": {
|
||||
"semantic": 0.85,
|
||||
"type_boost": 1.0,
|
||||
"edge_bonus": 0.4,
|
||||
"centrality": 0.1
|
||||
},
|
||||
"reasons": [
|
||||
"Hohe textuelle Übereinstimmung (>0.85).",
|
||||
"Bevorzugt, da Typ 'decision' (Gewicht 1.0).",
|
||||
"Wird referenziert von 'Projekt Alpha' via 'depends_on'."
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Logik der Text-Generierung:**
|
||||
* **Semantik:** Wenn $S_{sem} > 0.8$: "Hohe Übereinstimmung".
|
||||
* **Typ:** Wenn $W_{type} > 0.8$: "Bevorzugt, da Typ X".
|
||||
* **Graph:** Listet bis zu 3 eingehende Kanten mit hoher Konfidenz auf ("Wird referenziert von...").
|
||||
|
||||
---
|
||||
|
||||
## 4. Konfiguration (`retriever.yaml`)
|
||||
|
||||
Diese Datei steuert die Balance der Formel.
|
||||
|
||||
```yaml
|
||||
scoring:
|
||||
semantic_weight: 1.0 # Basis-Relevanz (sollte immer ca. 1.0 sein)
|
||||
edge_weight: 0.7 # Einfluss des Graphen (0.5 - 1.0 empfohlen)
|
||||
centrality_weight: 0.5 # Einfluss der Zentralität (Hub-Bonus)
|
||||
|
||||
# Kanten-spezifische Gewichtung für den Edge-Bonus
|
||||
edge_weights:
|
||||
depends_on: 1.5 # Harte Abhängigkeiten sehr stark gewichten
|
||||
blocks: 1.5 # Risiken/Blocker stark gewichten
|
||||
caused_by: 1.2 # Kausalitäten moderat stärken
|
||||
related_to: 0.5 # Weiche Themen schwächer gewichten
|
||||
references: 0.8 # Standard-Referenzen
|
||||
```
|
||||
Reference in new issue
Block a user