298 lines
4.8 KiB
Markdown
298 lines
4.8 KiB
Markdown
# 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
|
||
|
||
1. Anfrage
|
||
2. VectorSearchClient → Python Service
|
||
3. FAISS Similarity Search
|
||
4. Top-K Chunks
|
||
5. PromptBuilder
|
||
6. 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. |