415 lines
7.4 KiB
Markdown
415 lines
7.4 KiB
Markdown
# RAG-System – Technische Projektdokumentation
|
||
**Version:** 1.3
|
||
**Stand:** Februar 2026
|
||
**Autor:** mitho
|
||
**Status:** Verbindliche Referenzarchitektur (System Freeze – Phase A abgeschlossen)
|
||
**Validiert gegen:** aktuelle rag.zip (vollständig geprüft)
|
||
|
||
---
|
||
|
||
# 1. Ziel des Systems
|
||
|
||
Das RAG-System dient der deterministischen, governance-stabilen Beantwortung von Nutzeranfragen auf Basis versionierter, kontrollierter Wissensquellen.
|
||
|
||
Grundprinzip:
|
||
|
||
> „Wir nutzen KI nicht, um kreativ zu raten, sondern um verlässlich auf Basis Ihres Wissens zu antworten.“
|
||
|
||
Kernmerkmale:
|
||
|
||
- Versionierte Dokumentverwaltung (immutable Primärquellen)
|
||
- Deterministisches Chunking
|
||
- NDJSON als Single Source of Truth
|
||
- Vollständiger FAISS-Rebuild aus NDJSON
|
||
- Rein vektorbasiertes Retrieval (Chunks + optional Tags)
|
||
- Job-basierte Orchestrierung (async)
|
||
- Rollen- und Guardrail-Architektur
|
||
- SSE-Streaming
|
||
|
||
Wichtig (validiert im Code):
|
||
Es existiert **kein Keyword-Retrieval** mehr. Retrieval erfolgt ausschließlich über den Vector-Service (Chunks) mit optionalem Tag-Routing.
|
||
|
||
---
|
||
|
||
# 2. Architekturüberblick
|
||
|
||
## 2.1 Systemebenen
|
||
|
||
### 1) Admin-Ebene (Symfony Backend)
|
||
|
||
Verantwortlich für:
|
||
|
||
- Dokumentverwaltung
|
||
- Versionierung
|
||
- Aktivierung von DocumentVersion
|
||
- Tag-Management
|
||
- Ingest-Jobs
|
||
- Tag-Rebuild-Jobs
|
||
- System-Prompt-Verwaltung
|
||
- KI-Modell-/Generierungs-Konfiguration
|
||
- Security/Login
|
||
|
||
---
|
||
|
||
### 2) Wissensebene (Index & Artefakte)
|
||
|
||
Speicherpfad: `var/knowledge/`
|
||
|
||
Artefakte:
|
||
|
||
- `index.ndjson` (Single Source of Truth)
|
||
- `index_meta.json` (Index-Struktur/Governance)
|
||
- `index_runtime.json` (Runtime-Stats)
|
||
- `tags.ndjson`
|
||
- `vector.index`
|
||
- `vector.index.meta.json`
|
||
- `vector_tags.index`
|
||
- `vector_tags.index.meta.json`
|
||
|
||
Chunks sind vollständig ableitbar aus DocumentVersion.
|
||
|
||
---
|
||
|
||
### 3) Vector-Ebene (Python, FAISS)
|
||
|
||
- Persistenter Vector-Service (FastAPI)
|
||
- Embedding-Modell (lokal)
|
||
- FAISS-Index (Chunks)
|
||
- FAISS-Index (Tags)
|
||
- CLI-Fallback-Skripte
|
||
- Control-Script für Install / Start / Stop / Reload / Status
|
||
|
||
FAISS wird ausschließlich aus `index.ndjson` erzeugt.
|
||
|
||
---
|
||
|
||
### 4) Agent-Ebene
|
||
|
||
- Retrieval über `NdjsonHybridRetriever`
|
||
- Query-Cleaning nur für Retrieval
|
||
- Optionales Tag-Routing
|
||
- PromptBuilder
|
||
- SSE-Streaming
|
||
- History-Verarbeitung
|
||
|
||
---
|
||
|
||
# 3. Dokumentenarchitektur
|
||
|
||
## 3.1 Primärquellen-Prinzip
|
||
|
||
- Dokumente sind immutable.
|
||
- Jede Änderung erzeugt eine neue DocumentVersion.
|
||
- Genau eine Version pro Dokument ist aktiv.
|
||
- Chunks sind abgeleitete Artefakte.
|
||
- Keine manuelle Chunk-Manipulation.
|
||
|
||
---
|
||
|
||
## 3.2 Aktivierungsprozess (Async)
|
||
|
||
1. Aktivierung einer DocumentVersion
|
||
2. Erstellung eines IngestJob (Status: QUEUED)
|
||
3. Async-Ausführung:
|
||
|
||
bin/console mto:agent:ingest:run <jobId>
|
||
|
||
4. IngestOrchestrator führt deterministisch aus:
|
||
|
||
- Guardrail-Validierung
|
||
- NDJSON Compaction by document_id
|
||
- Chunking
|
||
- Streaming Write
|
||
- Vollständiger FAISS-Rebuild
|
||
- Atomare Datei-Switches
|
||
- Update von index_meta.json
|
||
- Job-Status: COMPLETED / FAILED / ABORTED
|
||
|
||
---
|
||
|
||
# 4. NDJSON-Architektur
|
||
|
||
## 4.1 index.ndjson
|
||
|
||
Eigenschaften:
|
||
|
||
- NDJSON (kein JSON-Array)
|
||
- Streaming-fähig
|
||
- Append + gezielte Compaction
|
||
- Kein Full-RAM-Load
|
||
- Atomare Dateioperationen
|
||
|
||
FAISS wird immer vollständig aus index.ndjson neu gebaut.
|
||
|
||
Es existiert keine zweite Wahrheitsquelle.
|
||
|
||
---
|
||
|
||
## 4.2 index_meta.json
|
||
|
||
Struktur (validiert):
|
||
|
||
- index_version
|
||
- created_at
|
||
- embedding_model
|
||
- embedding_dimension
|
||
- chunk_size
|
||
- chunk_overlap
|
||
- scoring_version
|
||
- index_format (ndjson)
|
||
- vector_backend (faiss)
|
||
|
||
---
|
||
|
||
## 4.3 Guardrail-Mechanismus
|
||
|
||
Bei strukturellen Änderungen:
|
||
|
||
- embedding_model
|
||
- embedding_dimension
|
||
- chunk_size
|
||
- overlap
|
||
- scoring_version
|
||
|
||
wird lokaler Ingest blockiert und ein Global Reindex erforderlich.
|
||
|
||
---
|
||
|
||
# 5. Chunk-Management
|
||
|
||
Verantwortlich: ChunkManager + Ingest-Services
|
||
|
||
Eigenschaften:
|
||
|
||
- Streaming-Schreiben
|
||
- Deterministische Reproduktion
|
||
- Hard Limit: 120.000 Chunks
|
||
- Warnlimit: 100.000 Chunks
|
||
- Kein vollständiger RAM-Load
|
||
|
||
---
|
||
|
||
# 6. Vector-Architektur
|
||
|
||
## 6.1 Persistenter Vector-Service (Standard)
|
||
|
||
Service-URL (Default):
|
||
|
||
http://127.0.0.1:8090
|
||
|
||
Endpoints:
|
||
|
||
- POST /search-chunks
|
||
- POST /search-tags
|
||
|
||
Control:
|
||
|
||
bin/console mto:agent:vector:control --install
|
||
bin/console mto:agent:vector:control --start
|
||
bin/console mto:agent:vector:control --reload
|
||
bin/console mto:agent:vector:control --status
|
||
|
||
---
|
||
|
||
## 6.2 CLI-Fallback
|
||
|
||
Python-Skripte:
|
||
|
||
- python/vector/vector_search.py
|
||
- python/vector/vector_ingest.py
|
||
- python/vector/vector_search_tags.py
|
||
- python/vector/vector_ingest_tags.py
|
||
|
||
---
|
||
|
||
## 6.3 Rebuild-Strategie
|
||
|
||
- Immer vollständiger FAISS-Rebuild
|
||
- Kein inkrementelles Patchen
|
||
- Atomarer Switch (.tmp → rename)
|
||
- Deterministisch und reproduzierbar
|
||
|
||
---
|
||
|
||
# 7. Retrieval (Vector-only)
|
||
|
||
Retrieval über `NdjsonHybridRetriever`.
|
||
|
||
Ablauf:
|
||
|
||
1) Query Cleaning (nur für Retrieval)
|
||
2) Optional: Tag-Routing
|
||
3) Chunk Vector Search
|
||
4) NDJSON Chunk Lookup
|
||
|
||
Keine Keyword-Suche im System vorhanden.
|
||
|
||
---
|
||
|
||
# 8. Tag-System
|
||
|
||
## 8.1 Entities
|
||
|
||
- Tag
|
||
- DocumentTag
|
||
- TagRebuildJob
|
||
|
||
## 8.2 Trigger
|
||
|
||
Rebuild bei:
|
||
|
||
- Tag-Erstellung
|
||
- Tag-Löschung
|
||
- Tag-Zuweisung
|
||
- Tag-Entfernung
|
||
|
||
## 8.3 Async-Ausführung
|
||
|
||
php bin/console mto:agent:tags:job:run <jobId>
|
||
|
||
Log:
|
||
|
||
var/log/tags/job_<uuid>.log
|
||
|
||
## 8.4 Stale-Protection
|
||
|
||
- QUEUED > 300 Sekunden → FAILED
|
||
- Maximal 1 aktiver Job
|
||
- Lockfile: var/knowledge/locks/tag_rebuild.lock
|
||
|
||
## 8.5 Tag-Index
|
||
|
||
- tags.ndjson
|
||
- vector_tags.index
|
||
- vector_tags.index.meta.json
|
||
|
||
Vollständiger Rebuild bei Änderung.
|
||
|
||
---
|
||
|
||
# 9. Job-Architektur
|
||
|
||
Status:
|
||
|
||
- QUEUED
|
||
- RUNNING
|
||
- COMPLETED
|
||
- FAILED
|
||
- ABORTED (Ingest)
|
||
|
||
Eigenschaften:
|
||
|
||
- Async exec
|
||
- Locking gegen Parallel-Ausführung
|
||
- Logging pro Job
|
||
- Recovery bei stale Jobs
|
||
|
||
---
|
||
|
||
# 10. Vector Health
|
||
|
||
Health-Check:
|
||
|
||
bin/console mto:agent:vector:health
|
||
|
||
Prüft:
|
||
|
||
- NDJSON Chunk Count
|
||
- FAISS Index Count
|
||
- Meta-Konsistenz
|
||
|
||
---
|
||
|
||
# 11. Governance & Guardrails
|
||
|
||
Rollen:
|
||
|
||
- Super Admin
|
||
- Knowledge Admin
|
||
- Redaktion
|
||
- Frontend-User
|
||
|
||
Schutzmechanismen:
|
||
|
||
- Immutable Dokumente
|
||
- Versionierung statt Ersetzen
|
||
- Keine Chunk-Editierung
|
||
- Guardrail gegen Strukturdrift
|
||
- Atomare Dateioperationen
|
||
- Locking & Job-Orchestrierung
|
||
- Logging & Audit
|
||
|
||
---
|
||
|
||
# 12. Skalierbarkeit
|
||
|
||
Ausgelegt für:
|
||
|
||
≥ 120.000 Chunks
|
||
|
||
Ermöglicht durch:
|
||
|
||
- NDJSON Streaming
|
||
- Kein Full-RAM JSON
|
||
- Vollständiger FAISS-Rebuild
|
||
- Persistenter Vector-Service
|
||
- Atomare Switches
|
||
- Locking-Mechanismen
|
||
|
||
Ab >300k Chunks sollte Sharding evaluiert werden.
|
||
|
||
---
|
||
|
||
# 13. Stabilitätsstatus
|
||
|
||
| Bereich | Status |
|
||
|----------|--------|
|
||
| Dokument-Ingest | Stabil |
|
||
| NDJSON | Enterprise-stabil |
|
||
| FAISS-Rebuild | Deterministisch |
|
||
| Vector-Service | Stabil |
|
||
| Tag-System | Stabil |
|
||
| Async-Jobs | Blockiersicher |
|
||
| Retrieval | Vector-only |
|
||
| SSE | Stabil |
|
||
| Governance | Aktiv |
|
||
|
||
---
|
||
|
||
# 14. System-Freeze-Definition
|
||
|
||
Dieses Dokument definiert den verbindlichen Referenzstand.
|
||
|
||
Ab jetzt gilt:
|
||
|
||
- Keine strukturellen Änderungen ohne explizite Freigabe.
|
||
- Keine inkrementellen Vector-Patches.
|
||
- Keine zweite Wahrheitsquelle neben index.ndjson.
|
||
- Erweiterungen nur additiv.
|
||
- Kein Architektur-Rewrite.
|
||
- Determinismus und Reproduzierbarkeit sind oberstes Prinzip.
|
||
|
||
Phase A ist abgeschlossen.
|
||
|
||
---
|
||
|
||
# 15. Zusammenfassung
|
||
|
||
Das System ist:
|
||
|
||
- deterministisch
|
||
- drift-sicher
|
||
- governance-konform
|
||
- skalierbar
|
||
- blockiersicher
|
||
- auditierbar
|
||
- reproduzierbar
|
||
- enterprise-ready
|
||
|
||
Retrieval ist vollständig vektorbasiert (Chunks + optional Tags).
|
||
|
||
Architekturfluss:
|
||
|
||
Primärquelle → NDJSON → FAISS → Vector Retrieval → Prompt → Generierung
|
||
|
||
Das System befindet sich im stabilen Freeze-Zustand. |