# 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 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 Log: var/log/tags/job_.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.