marek/MtoRagSystem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

new readme

Browse Source
This commit is contained in:
team2
2026-02-27 20:34:49 +01:00
parent dd7bae9678
commit efa9b17c2f
1 changed files with 186 additions and 303 deletions
Download Patch File Download Diff File Expand all files Collapse all files

489
README.md
View File

@@ -1,415 +1,298 @@
# 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)
Version: 2.0
Stand: Februar 2026
Status: Code-validierte Referenzarchitektur
---
# 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.“
Kernmerkmale:
Das System stellt sicher:
- Versionierte Dokumentverwaltung (immutable Primärquellen)
- Versionierte Dokumentverwaltung
- 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.
- 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 Systemebenen
### 1) Admin-Ebene (Symfony Backend)
Verantwortlich für:
## 2.1 Hauptkomponenten
Symfony (PHP)
- 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
- Ingest-Orchestrierung
- Job-System
- Admin-Oberfläche
- PromptBuilder
- SSE-Streaming
- History-Verarbeitung
- 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. Dokumentenarchitektur
# 3. Verzeichnisstruktur (verifiziert)
## 3.1 Primärquellen-Prinzip
bin/
config/
migrations/
public/
python/
src/
templates/
var/
- Dokumente sind immutable.
- Jede Änderung erzeugt eine neue DocumentVersion.
- Genau eine Version pro Dokument ist aktiv.
- Chunks sind abgeleitete Artefakte.
- Keine manuelle Chunk-Manipulation.
Python-Vektorlayer:
python/
vector_service.py
vector_control.py
vector_ingest.py
vector_search.py
vector_ingest_tags.py
vector_search_tags.py
---
## 3.2 Aktivierungsprozess (Async)
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. Source of Truth Konzept
## 4.1 index.ndjson
Eigenschaften:
Streamingfähiges NDJSON-Format:
- 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.
---
- Eine JSON-Zeile pro Chunk
- Kein JSON-Array
- Append-fähig
- Speicheroptimiert für >200k Chunks
## 4.2 index_meta.json
Struktur (validiert):
Beinhaltet:
- 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
- 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
- Deterministische Reproduktion
- Hard Limit: 120.000 Chunks
- Warnlimit: 100.000 Chunks
- Kein vollständiger RAM-Load
Es existiert immer nur eine aktive Version pro Dokument.
---
# 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
- POST /search-tags
- DB-Status wird geändert
- IngestStatus → PENDING
- IngestJob wird erzeugt
- CLI-Execution via:
Control:
```
bin/console mto:agent:ingest:run <jobId>
```
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
LockService verhindert Parallel-Ingest.
---
## 6.2 CLI-Fallback
# 7. Retrieval
Python-Skripte:
## 7.1 Architektur
- python/vector/vector_search.py
- python/vector/vector_ingest.py
- python/vector/vector_search_tags.py
- python/vector/vector_ingest_tags.py
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
---
## 6.3 Rebuild-Strategie
# 8. Python Vector Service
- Immer vollständiger FAISS-Rebuild
- Kein inkrementelles Patchen
- Atomarer Switch (.tmp → rename)
- Deterministisch und reproduzierbar
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.
---
# 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)
2) Optional: Tag-Routing
3) Chunk Vector Search
4) NDJSON Chunk Lookup
Bei Dimensionsänderung:
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
- DocumentTag
- TagRebuildJob
- Compaction nur für document_id
- Neue Chunks append
- Danach vollständiger FAISS-Rebuild
## 8.2 Trigger
## 10.2 Global Reindex
Rebuild bei:
- Tag-Erstellung
- Tag-Löschung
- 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.
- Alle aktiven Dokumente neu ingestieren
- index.ndjson komplett neu schreiben
- index_version++
- FAISS neu bauen
---
# 9. Job-Architektur
# 11. Rollenmodell
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
- SUPER_ADMIN
- KNOWLEDGE_ADMIN
- Wissensredaktion
- Frontend-User
Schutzmechanismen:
- Immutable Dokumente
- Versionierung statt Ersetzen
- Keine Chunk-Editierung
- Guardrail gegen Strukturdrift
- Atomare Dateioperationen
- Locking & Job-Orchestrierung
- Logging & Audit
Dokumente sind immutable.
Chunks sind niemals manuell editierbar.
---
# 12. Skalierbarkeit
# 12. Guardrails
Ausgelegt für:
Verhindert:
≥ 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.
- Embedding-Modell-Drift
- Chunking-Parameter-Drift
- Index-Format-Drift
- Parallele Ingest-Jobs
- Live-Änderung aktiver Ingest-Profile
---
# 13. Stabilitätsstatus
# 13. Wichtige Symfony Commands (validiert)
| 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 |
mto:agent:ingest:run
mto:agent:vector:control
mto:agent:vector:ingest
mto:agent:vector:search
Namespace ist durchgehend:
mto:agent:*
---
# 14. System-Freeze-Definition
# 14. Systemgrenzen
Dieses Dokument definiert den verbindlichen Referenzstand.
Das System ist ausgelegt für:
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.
- >200.000 Chunks
- Deterministische Reproduzierbarkeit
- Enterprise-Governance
- Drift-Sicherheit
- Skalierbare Erweiterung
---
# 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
- drift-sicher
- governance-konform
- skalierbar
- blockiersicher
- auditierbar
- reproduzierbar
- enterprise-ready
Immer vollständiger Rebuild.
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.