Lars 32128c06c1 docs/pipeline_playbook.md aktualisiert

2025-12-08 18:50:54 +01:00

9.7 KiB

Raw Blame History

mindnet v2.2 – Pipeline Playbook

Datei: docs/mindnet_pipeline_playbook_v2.2.md Stand: 2025-12-08 Status: FINAL (Inkl. WP05 RAG Pipeline) Quellen: mindnet_v2_implementation_playbook.md, Handbuch.md, chunking_strategy.md, docs_mindnet_retriever.md, mindnet_admin_guide_v2.2.md.

📖 Inhaltsverzeichnis (Klicken zum Öffnen)

mindnet v2.2 – Pipeline Playbook

---

1. Zweck & Einordnung

Dieses Playbook ist das zentrale operative Handbuch für die mindnet-Pipeline. Es beschreibt, wie Daten vom Markdown-Vault in den Wissensgraphen (Qdrant) gelangen, wie der Retriever betrieben wird und wie die RAG-Generierung funktioniert.

Zielgruppe: Dev/Ops, Tech-Leads. Scope:

Ist-Stand (WP01–WP05): Import, Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat, Feedback Loop.
Roadmap (Ausblick): Technische Skizzen für Self-Healing (WP06) und Self-Tuning (WP08).

2. Die Import-Pipeline (Runbook)

Der Import ist der kritischste Prozess ("Data Ingestion"). Er muss deterministisch und idempotent sein. Wir nutzen scripts/import_markdown.py als zentralen Entrypoint.

2.1 Der 12-Schritte-Prozess

Gemäß WP03-Spezifikation läuft der Import intern wie folgt ab:

Markdown lesen: Rekursives Scannen des Vaults.
Frontmatter extrahieren: Validierung von Pflichtfeldern (id, type, title).
Typauflösung: Bestimmung des type via types.yaml (Prio: Frontmatter > Pfad > Default).
Note-Payload generieren: Erstellen des JSON-Objekts für mindnet_notes.
Chunking anwenden: Zerlegung des Textes basierend auf dem chunk_profile des Typs.
Inline-Kanten finden: Parsing von [[rel:...]] im Fließtext.
Callout-Kanten finden: Parsing von > [!edge] Blöcken.
Default-Edges erzeugen: Anwendung der edge_defaults aus der Typ-Registry.
Strukturkanten erzeugen: belongs_to (Chunk->Note), next/prev (Sequenz).
Chunks upserten: Schreiben in Qdrant (mindnet_chunks).
Edges upserten: Schreiben in Qdrant (mindnet_edges).
Diagnose: Automatischer Check der Integrität nach dem Lauf.

2.2 Standard-Betrieb (Inkrementell)

Für regelmäßige Updates (z.B. Cronjob). Erkennt Änderungen via Hash.

export QDRANT_URL="http://localhost:6333"
export COLLECTION_PREFIX="mindnet"

# Import starten (Apply = Schreiben, Purge = Sauberer Upsert)
# 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

--apply: Ohne dieses Flag läuft ein Dry-Run (nur Simulation).
--purge-before-upsert: Löscht vor dem Schreiben einer Note ihre alten Chunks/Edges. Essentiell, um "Geister-Chunks" zu vermeiden, wenn Text gekürzt wurde.
--sync-deletes: Entfernt Notizen aus Qdrant, die im Vault gelöscht wurden.

2.3 Deployment & Restart (Systemd)

Nach einem Import oder Code-Update muss der API-Prozess neu gestartet werden.

# Neustart des Produktions-Services
sudo systemctl restart mindnet-prod

# Prüfung
sudo systemctl status mindnet-prod

2.4 Full Rebuild (Clean Slate)

Notwendig bei Änderungen an types.yaml (z.B. neue Chunk-Größen) oder Embedding-Modellen.

# 1. Qdrant Collections löschen und neu anlegen (Wipe inkl. Schema)
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes

# 2. Vollständiger Import aller Dateien
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply

3. Chunking & Payload-Aufbau

Das Chunking ist profilbasiert und typgesteuert.

3.1 Chunk-Profile

In types.yaml definiert. Standard-Profile (in chunk_config.py implementiert):

short: Max 128 Tokens (z.B. für Logs, Chats).
medium: Max 256 Tokens (z.B. für Konzepte).
long: Max 512 Tokens (z.B. für Essays, Projekte).
by_heading: Trennt strikt an Überschriften.

3.2 Payload-Felder

Jeder Chunk erhält zwei Text-Felder:

text: Der reine Inhalt des Chunks (ohne Overlap). Wird dem Nutzer angezeigt.
window: Der Inhalt plus Overlap zu Vorgänger/Nachfolger. Wird für das Embedding genutzt (besserer Kontext).

4. Edge-Erzeugung (Die V2-Logik)

In v2.2 entstehen Kanten nach strenger Priorität.

4.1 Prioritäten & Provenance

Der Importer setzt provenance, rule_id und confidence automatisch:

Priorität	Quelle	Syntax (Bsp.)	Rule ID	Confidence
1	Inline	`[[rel:depends_on X]]`	`inline:rel`	~0.95
2	Callout	`> [!edge] related_to: [[X]]`	`callout:edge`	~0.90
3	Wikilink	`[[X]]`	`explicit:wikilink`	1.00
4	Default	(via types.yaml)	`edge_defaults:...`	~0.70
5	Struktur	(automatisch)	`structure:...`	1.00

4.2 Typ-Defaults

Wenn in types.yaml für einen Typ edge_defaults definiert sind, werden diese additiv zu expliziten Links erzeugt.

Beispiel: Note Typ project verlinkt [[Tool A]].
Ergebnis: Kante references (explizit) UND Kante depends_on (Default).

5. Retriever, Chat & Generation (RAG Pipeline)

Der Datenfluss endet nicht beim Finden. Er geht weiter bis zur Antwort.

5.1 Retrieval (Hybrid)

total_score =
    semantic_weight   * semantic_score
  + edge_weight       * edge_bonus
  + centrality_weight * centrality_bonus
  + type_weight       * retriever_weight

Der /chat Endpunkt nutzt Hybrid Retrieval (Semantic + Graph), um auch logisch verbundene, aber textlich unterschiedliche Notizen zu finden (z.B. Decisions zu einem Projekt).

5.2 Context Enrichment (Das "Context Intelligence" Pattern)

Bevor der Text an das LLM geht, reichert der Router (chat.py) ihn an.

Metadaten-Injection: [DECISION], [PROJECT], [SCORE: 0.9].
Zweck: Ermöglicht kleinen Modellen (Phi-3) das Erkennen von logischen Rollen ("Warum?" vs "Was?").

5.3 Generation (LLM)

Engine: Ollama (lokal).
Modell: phi3:mini (Standard).
Prompting: Gesteuert über config/prompts.yaml.

5.4 Explanation Mode (WP04b)

Wird /query mit explain=True aufgerufen, führt der Retriever eine Post-Processing-Analyse durch und liefert reasons ("Verweist auf...", "Hoher Typ-Bonus").

6. Feedback & Lernen (WP04c)

Das System schreibt kontinuierlich Logs ("Data Flywheel"):

data/logs/search_history.jsonl: Trainingsdaten (Query + Ergebnisse + Breakdown).
data/logs/feedback.jsonl: Labels (User-Rating zur query_id).

7. Quality Gates & Tests

Diese Tests garantieren die Stabilität der Pipeline.

7.1 Pflicht-Tests vor Commit

Payload Dryrun (Schema-Check): Simuliert Import, prüft JSON-Schema Konformität.
```
python3 -m scripts.payload_dryrun --vault ./test_vault
```
Full Edge Check (Graph-Integrität): Prüft Invarianten (z.B. next muss reziprok zu prev sein).
```
python3 -m scripts.edges_full_check
```

7.2 Smoke-Test (E2E)

Prüft am laufenden System (Prod oder Dev), ob Semantik, Graph und Feedback funktionieren.

# Retriever Test
python scripts/test_retriever_smoke.py --mode hybrid --top-k 5

# Chat Test (Neu WP05)
python tests/test_chat_wp05.py

# Feedback Test
python tests/test_feedback_smoke.py --url http://localhost:8001/query

8. Ausblick & Roadmap (Technische Skizzen)

Wie entwickeln wir die Pipeline weiter?

8.1 WP-06: Decision Engine (Skizze)

Ziel: Aktive Entscheidungsberatung. Erweiterung: Der Chat-Router lädt bei Entscheidungfragen gezielt type: value Notizen nach, um Optionen gegen Werte abzuwägen.

8.2 WP-08: Self-Tuning (Skizze)

Ziel: Die Gewichte in retriever.yaml basierend auf feedback.jsonl optimieren. Ansatz: Ein Offline-Learning-Skript scripts/optimize_weights.py.

Load: Liest search_history.jsonl und joint mit feedback.jsonl via query_id.
Analyze: Korrelation Scores vs. User-Rating.
Optimize: Vorschlag neuer Gewichte für retriever.yaml.

9.7 KiB Raw Blame History Unescape Escape