Dokumentation

This commit is contained in:
Lars committed 2025-12-16 18:46:11 +01:00
1 parent edbd8f0ca8
commit 25ec3880bb
6 files changed
+105 -59

No files matched your search

@@ -3,7 +3,7 @@ doc_type: technical_reference
audience: developer, devops
scope: backend, ingestion, smart_edges
status: active
version: 2.6.0
version: 2.7.0
context: "Detaillierte technische Beschreibung der Import-Pipeline, Chunking-Strategien und CLI-Befehle."
---
@@ -11,28 +11,37 @@ context: "Detaillierte technische Beschreibung der Import-Pipeline, Chunking-Str
**Quellen:** `pipeline_playbook.md`, `Handbuch.md`
Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py`.
Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py` (CLI) oder `routers/ingest.py` (API).
## 1. Der Import-Prozess (13-Schritte-Workflow)
## 1. Der Import-Prozess (14-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 Kap. 3).
6. **Smart Edge Allocation (WP15):**
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 extrahieren:** Validierung von Pflichtfeldern (`id`, `type`, `title`).
4. **Config Resolution:**
* Bestimmung von `chunking_profile` und `retriever_weight`.
* **Priorität:** 1. Frontmatter (Override) -> 2. `types.yaml` (Type) -> 3. Default.
5. **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).
6. **Change Detection:**
* Vergleich des Hashes mit Qdrant.
* Strategie wählbar via ENV `MINDNET_CHANGE_DETECTION_MODE` (`full` oder `body`).
7. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3).
8. **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).
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` (768 Dim).
12. **Strict Mode:** Abbruch bei leeren Embeddings oder Dimension 0.
13. **Diagnose:** Integritäts-Check nach dem Lauf.
9. **Inline-Kanten finden:** Parsing von `[[rel:...]]`.
10. **Callout-Kanten finden:** Parsing von `> [!edge]`.
11. **Default-Edges erzeugen:** Anwendung der `edge_defaults` aus Registry.
12. **Strukturkanten erzeugen:** `belongs_to`, `next`, `prev`.
13. **Embedding (Async):** Generierung via `nomic-embed-text` (768 Dim).
14. **Diagnose:** Integritäts-Check nach dem Lauf.
---
@@ -44,6 +53,8 @@ Für regelmäßige Updates (Cronjob). Erkennt Änderungen via Hash.
```bash
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 \
@@ -68,6 +79,7 @@ ollama pull nomic-embed-text
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
```
@@ -75,7 +87,7 @@ python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --
## 3. Chunking & Payload
Das Chunking ist profilbasiert und in `types.yaml` konfiguriert. Seit v2.6 unterscheiden wir zwischen **Sliding Window** und **Heading Split**.
Das Chunking ist profilbasiert und in `types.yaml` konfiguriert.
### 3.1 Profile und Strategien
@@ -86,24 +98,27 @@ Das Chunking ist profilbasiert und in `types.yaml` konfiguriert. Seit v2.6 unter
| `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 (Neu in v2.6)
### 3.2 Die `by_heading` Logik (v2.9 Hybrid)
Die Strategie `by_heading` zerlegt Texte anhand ihrer Struktur (Überschriften).
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.
* *Ausnahme:* Wenn der vorherige Chunk leer war (nur Überschriften), wird gemergt (Context-Aware Merge).
* *Safety:* Wird ein Abschnitt zu lang (> `max`), wird trotzdem getrennt (Hybrid-Fallback).
* *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`):**
* Ü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.
* Überschriften *oberhalb* (z.B. H1) erzwingen immer einen Split (Hierarchie-Reset).
* **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).
* `window`: Inhalt plus Overlap (für Embedding). Bei `by_heading` enthält dies oft den Kontext der Eltern-Überschrift.
* `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).
---