2025-12-16 18:46:11 +01:00

6.6 KiB

Raw Blame History

doc_type	audience	scope	status	version	context
technical_reference	developer, devops	backend, ingestion, smart_edges	active	2.7.0	Detaillierte technische Beschreibung der Import-Pipeline, Chunking-Strategien 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 (CLI) oder routers/ingest.py (API).

1. Der Import-Prozess (14-Schritte-Workflow)

Der Prozess ist asynchron und idempotent.

Trigger & Async Dispatch:
- API (/save): Nimmt Request entgegen, validiert und startet Background-Task ("Fire & Forget"). Antwortet sofort mit 202/Queued.
- CLI: Iteriert über Dateien und nutzt asyncio.Semaphore zur Drosselung.
Markdown lesen: Rekursives Scannen des Vaults.
Frontmatter extrahieren: Validierung von Pflichtfeldern (id, type, title).
Config Resolution:
- Bestimmung von chunking_profile und retriever_weight.
- Priorität: 1. Frontmatter (Override) -> 2. types.yaml (Type) -> 3. Default.
Note-Payload generieren:
- Erstellen des JSON-Objekts für mindnet_notes.
- Multi-Hash Calculation: Berechnet Hashtabellen für body (nur Text) und full (Text + Metadaten).
Change Detection:
- Vergleich des Hashes mit Qdrant.
- Strategie wählbar via ENV MINDNET_CHANGE_DETECTION_MODE (full oder body).
Chunking anwenden: Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3).
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 via .env) drosselt die Last.
- Resilienz: Bei Timeout (Ollama) greift ein Fallback (Broadcasting an alle Chunks).
Inline-Kanten finden: Parsing von [[rel:...]].
Callout-Kanten finden: Parsing von > [!edge].
Default-Edges erzeugen: Anwendung der edge_defaults aus Registry.
Strukturkanten erzeugen: belongs_to, next, prev.
Embedding (Async): Generierung via nomic-embed-text (768 Dim).
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.

export QDRANT_URL="http://localhost:6333"
export COLLECTION_PREFIX="mindnet"
# Steuert, wann eine Datei als "geändert" gilt
export MINDNET_CHANGE_DETECTION_MODE="full" 

# 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 (z.B. neue Chunking-Profile) oder Modell-Wechsel.

# 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)
# --force ignoriert alle Hashes und schreibt alles neu
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force

3. Chunking & Payload

Das Chunking ist profilbasiert und in types.yaml konfiguriert.

3.1 Profile und Strategien

Profil	Strategie	Parameter	Einsatzgebiet
`sliding_short`	`sliding_window`	Max: 350, Target: 200	Kurze Logs, Chats, Risiken.
`sliding_standard`	`sliding_window`	Max: 650, Target: 450	Massendaten (Journal, Quellen).
`sliding_smart_edges`	`sliding_window`	Max: 600, Target: 400	Fließtexte mit hohem Wert (Projekte, Erfahrungen).
`structured_smart_edges`	`by_heading`	`strict: false` (Soft)	Strukturierte Texte, wo kleine Abschnitte gemergt werden dürfen.
`structured_smart_edges_strict`	`by_heading`	`strict: true` (Hard)	Atomare Einheiten: Entscheidungen, Werte, Profile.
`structured_smart_edges_strict_L3`	`by_heading`	`strict: true`, `level: 3`	Tief geschachtelte Prinzipien (Tier 2/MP1 Logik).

3.2 Die `by_heading` Logik (v2.9 Hybrid)

Die Strategie by_heading zerlegt Texte anhand ihrer Struktur (Überschriften). Sie unterstützt seit v2.9 ein "Safety Net" gegen zu große Chunks.

Split Level: Definiert die Tiefe (z.B. 2 = H1 & H2 triggern Split).
Modus "Strict" (strict_heading_split: true):
- Jede Überschrift (<= split_level) erzwingt einen neuen Chunk.
- Merge-Check: Wenn der vorherige Chunk leer war (nur Überschriften), wird gemergt (verhindert verwaiste Überschriften).
- Safety Net: Wird ein Abschnitt zu lang (> max Token), wird auch ohne Überschrift getrennt.
Modus "Soft" (strict_heading_split: false):
- Hierarchie-Check: Überschriften oberhalb des Split-Levels (z.B. H1 bei Level 2) erzwingen immer einen Split.
- Füll-Logik: Überschriften auf dem Split-Level (z.B. H2) lösen nur dann einen neuen Chunk aus, wenn der aktuelle Chunk die target-Größe erreicht hat.
- Safety Net: Auch hier greift das max Token Limit.

3.3 Payload-Felder (Qdrant)

text: Der reine Inhalt (Anzeige im UI). Überschriften bleiben erhalten.
window: Inhalt plus Overlap (für Embedding). Bei by_heading wird der Kontext (Eltern-Überschrift) oft vorangestellt.
chunk_profile: Das effektiv genutzte Profil (zur Nachverfolgung).

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.

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).

python3 -m scripts.edges_full_check

6.6 KiB Raw Blame History