122 lines
4.1 KiB
Markdown
122 lines
4.1 KiB
Markdown
|
---
|
||
|
|
doc_type: technical_reference
|
||
|
|
audience: developer, devops
|
||
|
|
scope: backend, ingestion, smart_edges
|
||
|
|
status: active
|
||
|
|
version: 2.6
|
||
|
|
context: "Detaillierte technische Beschreibung der Import-Pipeline, Quality Gates 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`.
|
||
|
|
|
||
|
|
## 1. Der Import-Prozess (13-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 unten).
|
||
|
|
6. **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: 2) 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` (768d).
|
||
|
|
12. **Strict Mode:** Abbruch bei leeren Embeddings oder Dimension 0.
|
||
|
|
13. **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.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
export QDRANT_URL="http://localhost:6333"
|
||
|
|
export COLLECTION_PREFIX="mindnet"
|
||
|
|
|
||
|
|
# 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` 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)
|
||
|
|
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. Chunking & Payload
|
||
|
|
|
||
|
|
Das Chunking ist profilbasiert.
|
||
|
|
|
||
|
|
| Profil | Max Token | Overlap | Einsatz |
|
||
|
|
| :--- | :--- | :--- | :--- |
|
||
|
|
| `sliding_short` | 128 | 20 | Logs, Chats. |
|
||
|
|
| `sliding_standard` | 512 | 50 | Massendaten. |
|
||
|
|
| `sliding_smart_edges`| 512 | 50 | Wichtige Inhalte (Experience, Project). |
|
||
|
|
| `structured_smart` | n/a | n/a | Trennt strikt an Headings (für ADRs). |
|
||
|
|
|
||
|
|
**Payload-Felder:**
|
||
|
|
* `text`: Der reine Inhalt (Anzeige).
|
||
|
|
* `window`: Inhalt plus Overlap (für Embedding).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 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.
|
||
|
|
```bash
|
||
|
|
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).
|
||
|
|
```bash
|
||
|
|
python3 -m scripts.edges_full_check
|
||
|
|
```
|