Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
f6f3213b84
mindnet/docs/03_Technical_References/03_tech_ingestion_pipeline.md
Lars f6f3213b84
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 5s
Details
WP20final
2025-12-25 22:21:41 +01:00

8.4 KiB
Raw Blame History

doc_type audience scope status version context
technical_reference developer, devops backend, ingestion, smart_edges, edge_registry active 2.8.1 Detaillierte technische Beschreibung der Import-Pipeline, Mistral-safe Parsing und Deep Fallback Resilienz.

Ingestion Pipeline & Smart Processing

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.8 integriert dieser Prozess eine intelligente Quoten-Steuerung (WP-20) und ein robustes JSON-Parsing für Cloud-Modelle (Mistral/Gemini).

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

Der Prozess ist asynchron und idempotent.

  1. 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.
  2. Markdown lesen: Rekursives Scannen des Vaults.
  3. Frontmatter Check & Hard Skip (WP-22):
    • Extraktion von status und type.
    • Hard Skip Rule: Wenn status in ['system', 'template', 'archive', 'hidden'] ist, wird die Datei sofort übersprungen. Sie wird weder vektorisiert noch in den Graphen aufgenommen.
    • Validierung der Pflichtfelder (id, title) für alle anderen Dateien.
  4. Edge Registry Initialisierung (WP-22):
    • Laden der Singleton-Instanz der EdgeRegistry.
    • Validierung der Vokabular-Datei unter MINDNET_VOCAB_PATH.
  5. Config Resolution:
    • Bestimmung von chunking_profile und retriever_weight.
    • Priorität: 1. Frontmatter (Override) -> 2. types.yaml (Type) -> 3. Global Default.
  6. Note-Payload generieren:
    • Erstellen des JSON-Objekts inklusive status (für Scoring).
    • Multi-Hash Calculation: Berechnet Hashtabellen für body (nur Text) und full (Text + Metadaten).
  7. Change Detection:
    • 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 (WP-20):
    • Wenn enable_smart_edge_allocation: true: Der SemanticAnalyzer sendet Chunks an das LLM.
    • Traffic Control: Request nutzt priority="background". Semaphore drosselt die Last.
    • Resilienz (Quota Handling): Erkennt HTTP 429 (Rate-Limit) und pausiert kontrolliert (via LLM_RATE_LIMIT_WAIT), bevor ein Cloud-Retry erfolgt.
    • Mistral-safe Parsing: Automatisierte Bereinigung von BOS-Tokens (<s>) und Framework-Tags ([OUT]) sowie Recovery-Logik für Dictionaries (Suche nach edges, links, results, kanten).
    • Deep Fallback (v2.11.14): Erkennt "Silent Refusals" (Data Policy Violations). Liefert die Cloud trotz erfolgreicher Verbindung keine verwertbaren Kanten, wird ein lokaler Fallback via Ollama erzwungen, um Kantenverlust zu vermeiden.
  10. Inline-Kanten finden: Parsing von [[rel:...]].
  11. Alias-Auflösung & Kanonisierung (WP-22):
    • Jede Kante wird via edge_registry.resolve() normalisiert.
    • Aliase (z.B. basiert_auf) werden zu kanonischen Typen (z.B. based_on) aufgelöst.
    • Unbekannte Typen werden in unknown_edges.jsonl protokolliert.
  12. Callout-Kanten finden: Parsing von > [!edge].
  13. Default- & Matrix-Edges erzeugen: Anwendung der edge_defaults aus Registry und Matrix-Logik.
  14. Strukturkanten erzeugen: belongs_to, next, prev.
  15. Embedding (Async): Generierung via nomic-embed-text (768 Dim).
  16. 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), der Registry 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 (Vollständige Referenz)

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).
structured_smart_edges by_heading strict: false (Soft) Strukturierte Texte, Merging erlaubt.
structured_smart_edges_strict by_heading strict: true (Hard) Atomare Einheiten: Entscheidungen, Werte.
structured_smart_edges_strict_L3 by_heading strict: true, level: 3 Tief geschachtelte Prinzipien (Tier 2/MP1).

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.
    • 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 erzwingen immer einen Split.
    • Füll-Logik: Überschriften auf dem Split-Level 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).
  • window: Inhalt plus Overlap (für Embedding).
  • chunk_profile: Das effektiv genutzte Profil (zur Nachverfolgung).

4. Edge-Erzeugung & Prioritäten (Provenance)

Kanten werden nach Vertrauenswürdigkeit (provenance) priorisiert. Die höhere Prio gewinnt.

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

5. Quality Gates & Monitoring

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.

2. Payload Dryrun (Schema-Check): Simuliert Import, prüft JSON-Schema Konformität.

python3 -m scripts.payload_dryrun --vault ./test_vault

3. Full Edge Check (Graph-Integrität): Prüft Invarianten (z.B. next muss reziprok zu prev sein).

python3 -m scripts.edges_full_check