Dokumentation WP14&WP15b
This commit is contained in:
1 parent
7fa9ce81bd
commit
fa909e2e7d
8 files changed
+267
-246
No files matched your search
@@ -1,71 +1,77 @@
|
||||
---
|
||||
doc_type: technical_reference
|
||||
audience: developer, devops
|
||||
scope: backend, ingestion, smart_edges, edge_registry
|
||||
scope: backend, ingestion, smart_edges, edge_registry, modularization
|
||||
status: active
|
||||
version: 2.8.1
|
||||
context: "Detaillierte technische Beschreibung der Import-Pipeline, Mistral-safe Parsing und Deep Fallback Resilienz."
|
||||
version: 2.9.0
|
||||
context: "Detaillierte technische Beschreibung der Import-Pipeline, Two-Pass-Workflow (WP-15b) und modularer Datenbank-Architektur (WP-14). Integriert Mistral-safe Parsing und Deep Fallback."
|
||||
---
|
||||
|
||||
# Ingestion Pipeline & Smart Processing
|
||||
|
||||
**Quellen:** `pipeline_playbook.md`, `ingestion.py`, `edge_registry.py`, `01_edge_vocabulary.md`, `llm_service.py`
|
||||
**Quellen:** `pipeline_playbook.md`, `ingestion_processor.py`, `ingestion_db.py`, `ingestion_validation.py`, `registry.py`, `edge_registry.py`
|
||||
|
||||
Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py` (CLI) oder `routers/ingest.py` (API). Seit v2.9 nutzt dieser Prozess ein hocheffizientes **Two-Pass-Verfahren**, um globale Kontext-Informationen für die semantische Validierung bereitzustellen, ohne die Idempotenz oder die Change-Detection zu verletzen.
|
||||
|
||||
|
||||
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**.
|
||||
Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durchläufe (Passes) unterteilt, um die semantische Genauigkeit zu maximieren.
|
||||
|
||||
### Phase 1: Pre-Scan & Context (Pass 1)
|
||||
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.
|
||||
2. **Markdown lesen:** Rekursives Scannen des Vaults zur Erstellung des Dateiinventars.
|
||||
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.
|
||||
* **Hard Skip Rule:** Wenn `status` in `['system', 'template', 'archive', 'hidden']` ist, wird die Datei für das Deep-Processing übersprungen, ihre Metadaten werden jedoch für den Kontext-Cache erfasst.
|
||||
* 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`.
|
||||
5. **Config Resolution (WP-14):**
|
||||
* Bestimmung von `chunking_profile` und `retriever_weight` via zentraler `TypeRegistry`.
|
||||
* **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.
|
||||
6. **LocalBatchCache & Summary Generation (WP-15b):**
|
||||
* Erstellung von Kurz-Zusammenfassungen für jede Note.
|
||||
* Speicherung im `batch_cache` als Referenzrahmen für die spätere Kantenvalidierung.
|
||||
|
||||
### Phase 2: Semantic Processing & Persistence (Pass 2)
|
||||
7. **Note-Payload & Multi-Hash (WP-15b):**
|
||||
* Erstellen des JSON-Objekts inklusive `status`.
|
||||
* **Multi-Hash Calculation:** Berechnet Hashtabellen für `body` (nur Text) und `full` (Text + Metadaten) zur präzisen Änderungskontrolle.
|
||||
8. **Change Detection:**
|
||||
* Vergleich des aktuellen Hashes mit den Daten in Qdrant (Collection `{prefix}_notes`).
|
||||
* Strategie wählbar via ENV `MINDNET_CHANGE_DETECTION_MODE` (`full` oder `body`). Unveränderte Dateien werden hier final übersprungen.
|
||||
9. **Purge Old Artifacts (WP-14):**
|
||||
* Bei Änderungen löscht `purge_artifacts()` via `app.core.ingestion.ingestion_db` alle alten Chunks und Edges der Note.
|
||||
* Die Namensauflösung erfolgt nun über das modularisierte `database`-Paket.
|
||||
10. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3).
|
||||
11. **Smart Edge Allocation & Semantic Validation (WP-15b):**
|
||||
* Der `SemanticAnalyzer` schlägt Kanten-Kandidaten vor.
|
||||
* **Validierung:** Jeder Kandidat wird durch das LLM semantisch gegen das Ziel im **LocalBatchCache** geprüft.
|
||||
* **Traffic Control:** Nutzung der neutralen `clean_llm_text` Funktion zur Bereinigung von Steuerzeichen (<s>, [OUT]).
|
||||
* **Deep Fallback (v2.11.14):** Erkennt "Silent Refusals". Liefert die Cloud keine verwertbaren Kanten, wird ein lokaler Fallback via Ollama erzwungen.
|
||||
12. **Inline-Kanten finden:** Parsing von `[[rel:...]]` und Callouts.
|
||||
13. **Alias-Auflösung & Kanonisierung (WP-22):**
|
||||
* Jede Kante wird via `EdgeRegistry` normalisiert (z.B. `basiert_auf` -> `based_on`).
|
||||
* 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.
|
||||
14. **Default- & Strukturkanten:** Anwendung der `edge_defaults` und Erzeugung von Systemkanten (`belongs_to`, `next`, `prev`).
|
||||
15. **Embedding (Async):** Generierung der Vektoren via `nomic-embed-text` (768 Dimensionen).
|
||||
16. **Database Sync (WP-14):** Batch-Upsert aller Points in die Collections `{prefix}_chunks` und `{prefix}_edges` über die zentrale Infrastruktur.
|
||||
|
||||
---
|
||||
|
||||
## 2. Betrieb & CLI Befehle
|
||||
|
||||
### 2.1 Standard-Betrieb (Inkrementell)
|
||||
Für regelmäßige Updates (Cronjob). Erkennt Änderungen via Hash.
|
||||
Erkennt Änderungen via Multi-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
|
||||
@@ -78,20 +84,13 @@ export MINDNET_CHANGE_DETECTION_MODE="full"
|
||||
```
|
||||
|
||||
> **[!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).
|
||||
> Das Flag `--purge-before-upsert` nutzt nun `ingestion_db.purge_artifacts`. Es ist kritisch, um "Geister-Chunks" (verwaiste Daten nach Textlöschung) konsistent aus den spezialisierten Collections zu entfernen.
|
||||
|
||||
### 2.2 Full Rebuild (Clean Slate)
|
||||
Notwendig bei Änderungen an `types.yaml` (z.B. neue Chunking-Profile), der Registry oder Modell-Wechsel.
|
||||
Notwendig bei Änderungen an `types.yaml`, der Registry 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)
|
||||
# --force ignoriert alle Hashes und schreibt alles neu
|
||||
# --force ignoriert alle Hashes und erzwingt den vollständigen Two-Pass Workflow
|
||||
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
||||
```
|
||||
|
||||
@@ -99,22 +98,20 @@ python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --
|
||||
|
||||
## 3. Chunking & Payload
|
||||
|
||||
Das Chunking ist profilbasiert und in `types.yaml` konfiguriert.
|
||||
Das Chunking ist profilbasiert und bezieht seine Konfiguration dynamisch aus der `TypeRegistry`.
|
||||
|
||||
### 3.1 Profile und Strategien (Vollständige Referenz)
|
||||
### 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). |
|
||||
| `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). |
|
||||
| `sliding_short` | `sliding_window` | Max: 350, Target: 200 | Kurze Logs, Chats. |
|
||||
| `sliding_standard` | `sliding_window` | Max: 650, Target: 450 | Standard-Wissen. |
|
||||
| `sliding_smart_edges`| `sliding_window` | Max: 600, Target: 400 | Fließtexte (Projekte). |
|
||||
| `structured_smart_edges` | `by_heading` | `strict: false` | Strukturierte Texte. |
|
||||
|
||||
### 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.
|
||||
Die Strategie `by_heading` zerlegt Texte anhand ihrer Struktur (Überschriften). Sie unterstützt 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`):**
|
||||
@@ -126,12 +123,6 @@ Die Strategie `by_heading` zerlegt Texte anhand ihrer Struktur (Überschriften).
|
||||
* **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)
|
||||
@@ -143,7 +134,7 @@ Kanten werden nach Vertrauenswürdigkeit (`provenance`) priorisiert. Die höhere
|
||||
| **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). |
|
||||
| **4** | Semantic AI | `semantic_ai` | **0.90** | KI-validiert gegen LocalBatchCache. |
|
||||
| **5** | Type Default | `edge_defaults` | **0.70** | Heuristik aus der Registry. |
|
||||
| **6** | Struktur | `structure` | **1.00** | System-interne Verkettung (`belongs_to`). |
|
||||
|
||||
@@ -151,18 +142,8 @@ Kanten werden nach Vertrauenswürdigkeit (`provenance`) priorisiert. Die höhere
|
||||
|
||||
## 5. Quality Gates & Monitoring
|
||||
|
||||
In v2.7+ wurden Tools zur Überwachung der Datenqualität integriert:
|
||||
**1. Registry Review (WP-14):** Prüfung der `data/logs/unknown_edges.jsonl`. Die zentrale Auflösung via `registry.py` verhindert Inkonsistenzen zwischen Import und Retrieval.
|
||||
|
||||
**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. Mistral-safe Parsing:** Automatisierte Bereinigung von LLM-Antworten in `ingestion_validation.py`. Stellt sicher, dass semantische Entscheidungen ("YES"/"NO") nicht durch technische Header verfälscht werden.
|
||||
|
||||
**2. Payload Dryrun (Schema-Check):**
|
||||
Simuliert Import, prüft JSON-Schema Konformität.
|
||||
```bash
|
||||
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).
|
||||
```bash
|
||||
python3 -m scripts.edges_full_check
|
||||
```
|
||||
**3. Purge Integrity:** Validierung, dass vor jedem Upsert alle assoziierten Artefakte in den Collections `{prefix}_chunks` und `{prefix}_edges` gelöscht wurden, um Daten-Duplikate zu vermeiden.
|
||||
Reference in new issue
Block a user