RAG-System – Technische Projektdokumentation
Version: 1.0
Stand: Februar 2026
Autor: mitho
Status: Verbindliche Referenzarchitektur (System Freeze)
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.“
Das System kombiniert:
- Versionierte Dokumentverwaltung
- Deterministisches Chunking
- NDJSON als Single Source of Truth
- Vollständigen FAISS-Rebuild
- Hybrid Retrieval (Keyword + Vector + Tag)
- Job-basierte Orchestrierung
- Rollen- und Guardrail-Architektur
- SSE-Streaming
2. Architekturüberblick
2.1 Systemebenen
1. Admin-Ebene (Symfony Backend)
- Dokumentverwaltung
- Versionierung
- Tag-Management
- Job-Steuerung
- System-Prompt-Verwaltung
- KI-Endpoint-Konfiguration
2. Wissensebene
- Dokumente (immutable)
- DocumentVersion
- Chunks
- index.ndjson
- index_meta.json
3. Vector-Ebene (Python)
- Embedding-Modell (lokal)
- FAISS-Index (Chunks)
- FAISS-Index (Tags)
- Persistenter Vector-Service
- CLI-Fallback
4. Agent-Ebene
- Retrieval-Fusion
- PromptBuilder
- SSE-Streaming
- Chat-History-Verarbeitung
3. Dokumentenarchitektur
3.1 Primärquellen
- Dokumente sind immutable.
- Jede Änderung erzeugt eine neue DocumentVersion.
- Pro Dokument existiert genau eine aktive Version.
3.2 Aktivierungsprozess
- Aktivierung einer Version
- Erstellung eines IngestJob
- Async-Start:
bin/console mto:agent:ingest:run <jobId> - IngestOrchestrator:
- Guardrail-Validierung
- NDJSON Compaction by document_id
- Chunking
- Streaming Append
- Vollständiger FAISS-Rebuild
- index_meta.json Update
- Status COMPLETED/FAILED
4. NDJSON-Architektur
4.1 index.ndjson (Single Source of Truth)
- Streamingfähiges Format
- Kein JSON-Array
- Append-only mit Compaction
- Keine vollständige RAM-Verarbeitung
- Atomare Datei-Switches (.tmp → rename)
4.2 index_meta.json
Enthält:
- index_version
- embedding_model
- embedding_dimension
- chunk_size
- overlap
- scoring_version
- index_format
Guardrail-Mechanismus
Bei strukturellen Änderungen (Embedding, Chunking, Scoring):
- Lokaler Ingest wird blockiert
- Global Reindex erforderlich
5. Chunk-Management
Verantwortlich: ChunkManager
Eigenschaften:
- Streaming-basiertes Schreiben
- Deterministische Reproduktion
- Hard Limit: 120.000 Chunks
- Warnlimit: 100.000 Chunks
- Kein vollständiger JSON-RAM-Load
6. Vector-Architektur
6.1 Betriebsmodi
A) Persistenter Vector-Service (bevorzugt)
- Lädt Embedding-Modell einmal
- Lädt FAISS-Indizes in RAM
- REST-Endpunkte:
- /search-chunks
- /search-tags
B) CLI-Fallback
- Python-Skripte
- Wird genutzt, falls Service nicht verfügbar ist
6.2 Rebuild-Strategie
- Immer vollständiger FAISS-Rebuild
- Kein inkrementelles Patchen
- Atomarer Index-Switch
- Deterministisch und drift-sicher
7. Hybrid Retrieval
7.1 Retrieval-Komponenten
- Keyword-Retrieval (führend)
- FAISS-Chunk-Retrieval (ergänzend)
- Tag-Routing (Soft-Gate)
7.2 Score-Fusion
- Keyword hat Priorität
- Vector ergänzt semantische Nähe
- Tags dienen als Routing-Verstärker
8. Tag-System
8.1 Entities
- Tag
- DocumentTag
- TagRebuildJob
8.2 Trigger-Logik
Ein Rebuild wird ausgelöst bei:
- Tag-Erstellung
- Tag-Löschung
- Tag-Zuweisung
- Tag-Entfernung
8.3 Job-Mechanik
- Async-Start via:
php bin/console mto:agent:tags:job:run <jobId> - Logfile unter:
var/log/tags/job_<uuid>.log
8.4 Stale-Protection
- QUEUED-Jobs älter als 5 Minuten → FAILED
- System kann nicht dauerhaft blockieren
- Coalescing (max. 1 aktiver Job)
8.5 Tag-Index
- tags.ndjson
- vector_tags.index
- Vollständiger Rebuild bei Änderung
9. Job-Architektur
Statusmodell:
- QUEUED
- RUNNING
- COMPLETED
- FAILED
Eigenschaften:
- Async exec
- LockService gegen Parallel-Ausführung
- Self-Healing gegen blockierte Jobs
- Logging pro Job
10. Governance & Guardrails
10.1 Rollen
- Super Admin
- Knowledge Admin
- Redaktion
- Frontend-User
10.2 Schutzmechanismen
- Dokumente immutable
- Keine manuelle Chunk-Manipulation
- Versionierte Ingest-Profile
- Versionierte System-Prompts
- Konfigurierbare KI-Endpunkte
- Logging & Audit-Fähigkeit
11. Agent-Architektur
- SSE-Streaming
- Historienverarbeitung korrekt implementiert
- Deterministischer PromptBuilder
- Retrieval-Kontext explizit eingebettet
- Kein Think-Mode-Leak
12. Skalierbarkeit
Zielgröße:
-
120.000 Chunks
Ermöglicht durch:
- NDJSON Streaming
- Kein Full-RAM-JSON
- Vollständiger FAISS-Rebuild
- Persistenter Vector-Service
- Atomare Switches
- Locking-Mechanismen
13. Stabilitätsstatus (Freeze-Zustand)
| Bereich | Status |
|---|---|
| Dokument-Ingest | Stabil |
| NDJSON-Architektur | Enterprise-Stabil |
| FAISS-Rebuild | Deterministisch |
| Tag-System | Stabil mit Stale-Recovery |
| Async-Jobs | Blockiersicher |
| Retrieval-Fusion | Funktional |
| SSE | Stabil |
| Governance | Aktiv |
14. System-Freeze-Definition
Dieses Dokument definiert den verbindlichen Referenzstand des Systems.
Ab diesem Punkt gilt:
- Keine strukturellen Änderungen ohne explizite Freigabe.
- Erweiterungen nur inkrementell.
- Keine Architektur-Rewrites.
- Determinismus und Reproduzierbarkeit sind oberstes Prinzip.
15. Zusammenfassung
Das System ist:
- deterministisch
- drift-sicher
- governance-konform
- skalierbar
- blockiersicher
- debugbar
- enterprise-ready
Es erfüllt die Anforderungen an ein kontrolliertes, reproduzierbares RAG-System mit klarer Trennung zwischen Wissensquelle, Index, Retrieval und Generierung.