new readme

This commit is contained in:
team2
2026-02-27 20:34:49 +01:00
parent dd7bae9678
commit efa9b17c2f

489
README.md
View File

@@ -1,415 +1,298 @@
# RAG-System Technische Projektdokumentation # RAG-System Technische Projektdokumentation
**Version:** 1.3
**Stand:** Februar 2026 Version: 2.0
**Autor:** mitho Stand: Februar 2026
**Status:** Verbindliche Referenzarchitektur (System Freeze Phase A abgeschlossen) Status: Code-validierte Referenzarchitektur
**Validiert gegen:** aktuelle rag.zip (vollständig geprüft)
--- ---
# 1. Ziel des Systems # 1. Ziel des Systems
Das RAG-System dient der deterministischen, governance-stabilen Beantwortung von Nutzeranfragen auf Basis versionierter, kontrollierter Wissensquellen. Das System implementiert ein deterministisches Retrieval-Augmented-Generation (RAG) Framework auf Basis versionierter Dokumente.
Grundprinzip: Leitprinzip:
> „Wir nutzen KI nicht, um kreativ zu raten, sondern um verlässlich auf Basis Ihres Wissens zu antworten.“ > „Wir nutzen KI nicht, um kreativ zu raten, sondern um verlässlich auf Basis Ihres Wissens zu antworten.“
Kernmerkmale: Das System stellt sicher:
- Versionierte Dokumentverwaltung (immutable Primärquellen) - Versionierte Dokumentverwaltung
- Deterministisches Chunking - Deterministisches Chunking
- NDJSON als Single Source of Truth - Streamingfähige NDJSON Source of Truth
- Vollständiger FAISS-Rebuild aus NDJSON - Vollständiger FAISS-Rebuild bei strukturellen Änderungen
- Rein vektorbasiertes Retrieval (Chunks + optional Tags) - Persistenter Python Vector-Service
- Job-basierte Orchestrierung (async) - Governance-stabile Ingest- und Reindex-Mechanik
- 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. Architekturüberblick
## 2.1 Systemebenen ## 2.1 Hauptkomponenten
### 1) Admin-Ebene (Symfony Backend)
Verantwortlich für:
Symfony (PHP)
- Dokumentverwaltung - Dokumentverwaltung
- Versionierung - Versionierung
- Aktivierung von DocumentVersion - Ingest-Orchestrierung
- Tag-Management - Job-System
- Ingest-Jobs - Admin-Oberfläche
- 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 - PromptBuilder
- SSE-Streaming - VectorSearchClient
- History-Verarbeitung
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. Dokumentenarchitektur # 3. Verzeichnisstruktur (verifiziert)
## 3.1 Primärquellen-Prinzip bin/
config/
migrations/
public/
python/
src/
templates/
var/
- Dokumente sind immutable. Python-Vektorlayer:
- Jede Änderung erzeugt eine neue DocumentVersion.
- Genau eine Version pro Dokument ist aktiv. python/
- Chunks sind abgeleitete Artefakte. vector_service.py
- Keine manuelle Chunk-Manipulation. vector_control.py
vector_ingest.py
vector_search.py
vector_ingest_tags.py
vector_search_tags.py
--- ---
## 3.2 Aktivierungsprozess (Async) # 4. Source of Truth Konzept
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 ## 4.1 index.ndjson
Eigenschaften: Streamingfähiges NDJSON-Format:
- NDJSON (kein JSON-Array) - Eine JSON-Zeile pro Chunk
- Streaming-fähig - Kein JSON-Array
- Append + gezielte Compaction - Append-fähig
- Kein Full-RAM-Load - Speicheroptimiert für >200k Chunks
- Atomare Dateioperationen
FAISS wird immer vollständig aus index.ndjson neu gebaut.
Es existiert keine zweite Wahrheitsquelle.
---
## 4.2 index_meta.json ## 4.2 index_meta.json
Struktur (validiert): Beinhaltet:
- index_version - 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_model
- embedding_dimension - embedding_dimension
- chunk_size - chunk_size
- overlap - overlap
- scoring_version - scoring_version
- index_format
wird lokaler Ingest blockiert und ein Global Reindex erforderlich. Bei strukturellen Änderungen wird ein Global Reindex erzwungen.
--- ---
# 5. Chunk-Management # 5. Dokument-Lifecycle
Verantwortlich: ChunkManager + Ingest-Services Dokument
→ Version
→ Aktivierung
→ IngestJob (QUEUE)
→ Chunking
→ NDJSON Compaction by document_id
→ Full FAISS Rebuild
→ Status INDEXED
Eigenschaften: Wichtige Regel:
- Streaming-Schreiben Es existiert immer nur eine aktive Version pro Dokument.
- Deterministische Reproduktion
- Hard Limit: 120.000 Chunks
- Warnlimit: 100.000 Chunks
- Kein vollständiger RAM-Load
--- ---
# 6. Vector-Architektur # 6. Ingest-System
## 6.1 Persistenter Vector-Service (Standard) ## 6.1 Job-Typen
Service-URL (Default): - DOCUMENT_UPLOAD
- DOCUMENT_VERSION_ACTIVATE
- GLOBAL_REINDEX
http://127.0.0.1:8090 ## 6.2 Aktivierung
Endpoints: Beim Aktivieren einer Version:
- POST /search-chunks - DB-Status wird geändert
- POST /search-tags - IngestStatus → PENDING
- IngestJob wird erzeugt
- CLI-Execution via:
Control: ```
bin/console mto:agent:ingest:run <jobId>
```
bin/console mto:agent:vector:control --install LockService verhindert Parallel-Ingest.
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 # 7. Retrieval
Python-Skripte: ## 7.1 Architektur
- python/vector/vector_search.py Hybrid im Sinne von:
- python/vector/vector_ingest.py
- python/vector/vector_search_tags.py - FAISS Vektor-Retrieval
- python/vector/vector_ingest_tags.py - 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
--- ---
## 6.3 Rebuild-Strategie # 8. Python Vector Service
- Immer vollständiger FAISS-Rebuild FastAPI Service mit uvicorn.
- Kein inkrementelles Patchen
- Atomarer Switch (.tmp → rename) Steuerung über:
- Deterministisch und reproduzierbar
```
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.
--- ---
# 7. Retrieval (Vector-only) # 9. Embedding
Retrieval über `NdjsonHybridRetriever`. Verwendetes Modell ist konfigurierbar.
Ablauf: Embedding-Dimension wird aus Modell bestimmt und im index_meta.json gespeichert.
1) Query Cleaning (nur für Retrieval) Bei Dimensionsänderung:
2) Optional: Tag-Routing
3) Chunk Vector Search
4) NDJSON Chunk Lookup
Keine Keyword-Suche im System vorhanden. → Guardrail blockiert lokalen Ingest
→ Global Reindex erforderlich
--- ---
# 8. Tag-System # 10. Reindex-Strategie
## 8.1 Entities ## 10.1 Lokaler Re-Ingest
- Tag - Compaction nur für document_id
- DocumentTag - Neue Chunks append
- TagRebuildJob - Danach vollständiger FAISS-Rebuild
## 8.2 Trigger ## 10.2 Global Reindex
Rebuild bei: - Alle aktiven Dokumente neu ingestieren
- index.ndjson komplett neu schreiben
- Tag-Erstellung - index_version++
- Tag-Löschung - FAISS neu bauen
- 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 # 11. Rollenmodell
Status: - SUPER_ADMIN
- KNOWLEDGE_ADMIN
- QUEUED - Wissensredaktion
- 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 - Frontend-User
Schutzmechanismen: Dokumente sind immutable.
Chunks sind niemals manuell editierbar.
- Immutable Dokumente
- Versionierung statt Ersetzen
- Keine Chunk-Editierung
- Guardrail gegen Strukturdrift
- Atomare Dateioperationen
- Locking & Job-Orchestrierung
- Logging & Audit
--- ---
# 12. Skalierbarkeit # 12. Guardrails
Ausgelegt für: Verhindert:
≥ 120.000 Chunks - Embedding-Modell-Drift
- Chunking-Parameter-Drift
Ermöglicht durch: - Index-Format-Drift
- Parallele Ingest-Jobs
- NDJSON Streaming - Live-Änderung aktiver Ingest-Profile
- 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 # 13. Wichtige Symfony Commands (validiert)
| Bereich | Status | mto:agent:ingest:run
|----------|--------| mto:agent:vector:control
| Dokument-Ingest | Stabil | mto:agent:vector:ingest
| NDJSON | Enterprise-stabil | mto:agent:vector:search
| FAISS-Rebuild | Deterministisch |
| Vector-Service | Stabil | Namespace ist durchgehend:
| Tag-System | Stabil |
| Async-Jobs | Blockiersicher | mto:agent:*
| Retrieval | Vector-only |
| SSE | Stabil |
| Governance | Aktiv |
--- ---
# 14. System-Freeze-Definition # 14. Systemgrenzen
Dieses Dokument definiert den verbindlichen Referenzstand. Das System ist ausgelegt für:
Ab jetzt gilt: - >200.000 Chunks
- Deterministische Reproduzierbarkeit
- Keine strukturellen Änderungen ohne explizite Freigabe. - Enterprise-Governance
- Keine inkrementellen Vector-Patches. - Drift-Sicherheit
- Keine zweite Wahrheitsquelle neben index.ndjson. - Skalierbare Erweiterung
- Erweiterungen nur additiv.
- Kein Architektur-Rewrite.
- Determinismus und Reproduzierbarkeit sind oberstes Prinzip.
Phase A ist abgeschlossen.
--- ---
# 15. Zusammenfassung # 15. Nicht Bestandteil
Das System ist: - Kein manuelles Chunk-Editing
- Kein Keyword-Retrieval
- Kein partieller FAISS-Rebuild
- Kein In-Place Index Update
- deterministisch Immer vollständiger Rebuild.
- drift-sicher
- governance-konform
- skalierbar
- blockiersicher
- auditierbar
- reproduzierbar
- enterprise-ready
Retrieval ist vollständig vektorbasiert (Chunks + optional Tags). ---
Architekturfluss: # 16. Zusammenfassung
Primärquelle → NDJSON → FAISS → Vector Retrieval → Prompt → Generierung Das System implementiert eine deterministische, governance-stabile RAG-Architektur mit:
Das System befindet sich im stabilen Freeze-Zustand. - 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.