RAG-System – Technische Projektdokumentation
Version: 2.0
Stand: Februar 2026
Status: Code-validierte Referenzarchitektur
1. Ziel des Systems
Das System implementiert ein deterministisches Retrieval-Augmented-Generation (RAG) Framework auf Basis versionierter Dokumente.
Leitprinzip:
„Wir nutzen KI nicht, um kreativ zu raten, sondern um verlässlich auf Basis Ihres Wissens zu antworten.“
Das System stellt sicher:
- Versionierte Dokumentverwaltung
- Deterministisches Chunking
- Streamingfähige NDJSON Source of Truth
- Vollständiger FAISS-Rebuild bei strukturellen Änderungen
- Persistenter Python Vector-Service
- Governance-stabile Ingest- und Reindex-Mechanik
2. Architekturüberblick
2.1 Hauptkomponenten
Symfony (PHP)
- Dokumentverwaltung
- Versionierung
- Ingest-Orchestrierung
- Job-System
- Admin-Oberfläche
- PromptBuilder
- VectorSearchClient
Python Layer
- Embedding-Modell (SentenceTransformers)
- FAISS Index
- Vector-Service (FastAPI + uvicorn)
- CLI-Fallback Scripts
Persistenz
- index.ndjson (Single Source of Truth)
- index_meta.json (Struktur-Metadaten)
- vector.index (FAISS)
- tags.ndjson (optional)
- vector_tags.index (optional)
3. Verzeichnisstruktur (verifiziert)
bin/ config/ migrations/ public/ python/ src/ templates/ var/
Python-Vektorlayer:
python/ vector_service.py vector_control.py vector_ingest.py vector_search.py vector_ingest_tags.py vector_search_tags.py
4. Source of Truth Konzept
4.1 index.ndjson
Streamingfähiges NDJSON-Format:
- Eine JSON-Zeile pro Chunk
- Kein JSON-Array
- Append-fähig
- Speicheroptimiert für >200k Chunks
4.2 index_meta.json
Beinhaltet:
- index_version
- embedding_model
- embedding_dimension
- chunk_size
- overlap
- scoring_version
- index_format
Bei strukturellen Änderungen wird ein Global Reindex erzwungen.
5. Dokument-Lifecycle
Dokument → Version → Aktivierung → IngestJob (QUEUE) → Chunking → NDJSON Compaction by document_id → Full FAISS Rebuild → Status INDEXED
Wichtige Regel:
Es existiert immer nur eine aktive Version pro Dokument.
6. Ingest-System
6.1 Job-Typen
- DOCUMENT_UPLOAD
- DOCUMENT_VERSION_ACTIVATE
- GLOBAL_REINDEX
6.2 Aktivierung
Beim Aktivieren einer Version:
- DB-Status wird geändert
- IngestStatus → PENDING
- IngestJob wird erzeugt
- CLI-Execution via:
bin/console mto:agent:ingest:run <jobId>
LockService verhindert Parallel-Ingest.
7. Retrieval
7.1 Architektur
Hybrid im Sinne von:
- FAISS Vektor-Retrieval
- Optionales Tag-Routing (separater Tag-Index)
Kein klassisches Keyword-Retrieval mehr aktiv.
7.2 Ablauf
- Anfrage
- VectorSearchClient → Python Service
- FAISS Similarity Search
- Top-K Chunks
- PromptBuilder
- LLM Response
8. Python Vector Service
FastAPI Service mit uvicorn.
Steuerung über:
bin/console mto:agent:vector:control
Mögliche Aktionen:
- --install
- --start
- --stop
- --reload
- --status
Service lädt:
- Embedding-Modell einmalig
- FAISS Index einmalig
- Hält alles persistent im RAM
CLI-Fallback bleibt verfügbar.
9. Embedding
Verwendetes Modell ist konfigurierbar.
Embedding-Dimension wird aus Modell bestimmt und im index_meta.json gespeichert.
Bei Dimensionsänderung:
→ Guardrail blockiert lokalen Ingest
→ Global Reindex erforderlich
10. Reindex-Strategie
10.1 Lokaler Re-Ingest
- Compaction nur für document_id
- Neue Chunks append
- Danach vollständiger FAISS-Rebuild
10.2 Global Reindex
- Alle aktiven Dokumente neu ingestieren
- index.ndjson komplett neu schreiben
- index_version++
- FAISS neu bauen
11. Rollenmodell
- SUPER_ADMIN
- KNOWLEDGE_ADMIN
- Wissensredaktion
- Frontend-User
Dokumente sind immutable. Chunks sind niemals manuell editierbar.
12. Guardrails
Verhindert:
- Embedding-Modell-Drift
- Chunking-Parameter-Drift
- Index-Format-Drift
- Parallele Ingest-Jobs
- Live-Änderung aktiver Ingest-Profile
13. Wichtige Symfony Commands (validiert)
mto:agent:ingest:run mto:agent:vector:control mto:agent:vector:ingest mto:agent:vector:search
Namespace ist durchgehend:
mto:agent:*
14. Systemgrenzen
Das System ist ausgelegt für:
-
200.000 Chunks
- Deterministische Reproduzierbarkeit
- Enterprise-Governance
- Drift-Sicherheit
- Skalierbare Erweiterung
15. Nicht Bestandteil
- Kein manuelles Chunk-Editing
- Kein Keyword-Retrieval
- Kein partieller FAISS-Rebuild
- Kein In-Place Index Update
Immer vollständiger Rebuild.
16. Zusammenfassung
Das System implementiert eine deterministische, governance-stabile RAG-Architektur mit:
- NDJSON als Streaming-Single-Source
- Vollständigem FAISS-Rebuild
- Persistenter Vector-Service-Schicht
- Versionierter Dokumentverwaltung
- Strikter Guardrail-Logik
Diese README entspricht vollständig dem aktuellen Code-Stand der rag.zip.