update README.md

This commit is contained in:
team2
2026-02-23 21:02:55 +01:00
parent 0aff4d5f3b
commit a2a6e1bca2

515
README.md
View File

@@ -1,396 +1,321 @@
# mitho AI Agent Developer README # RAG-System Technische Projektdokumentation
Enterprise Hybrid RAG System (Symfony + NDJSON + FAISS + Persistent Vector Service) **Version:** 1.0
**Stand:** Februar 2026
Stand: Februar 2026 **Autor:** mitho
Status: Produktiv stabil Job-basierte Ingest-Architektur + Persistenter Vector-Service integriert **Status:** Verbindliche Referenzarchitektur (System Freeze)
--- ---
# 1. Systemüberblick # 1. Ziel des Systems
Dieses System implementiert eine deterministische, governance-stabile Das RAG-System dient der deterministischen, governance-stabilen Beantwortung von Nutzeranfragen auf Basis versionierter, kontrollierter Wissensquellen.
Hybrid-RAG-Architektur mit:
- Symfony (PHP Backend)
- NDJSON als Single Source of Truth
- FAISS als Vektorindex (immer Full Rebuild)
- Persistenter Python Vector-Service (FastAPI + Uvicorn)
- Hybrid Retrieval (Keyword + Vektor)
- Versioniertes Dokumentmodell
- Job-basierte Ingest-Pipeline
- Lock-geschützte Reindex-Operationen
- SSE-Streaming im Frontend
Grundprinzip: Grundprinzip:
> „Wir nutzen KI nicht, um kreativ zu raten, sondern um verlässlich auf Basis Ihres Wissens zu antworten.“
- Keine inkrementellen Vektor-Updates Das System kombiniert:
- FAISS wird immer vollständig aus `index.ndjson` neu gebaut
- Retrieval läuft über einen persistenten Service (kein Python-Spawn pro Anfrage) - Versionierte Dokumentverwaltung
- Deterministisches Chunking
- NDJSON als Single Source of Truth
- Vollständigen FAISS-Rebuild
- Hybrid Retrieval (Keyword + Vector + Tag)
- Job-basierte Orchestrierung
- Rollen- und Guardrail-Architektur
- SSE-Streaming
--- ---
# 2. Architekturprinzipien # 2. Architekturüberblick
## 2.1 Determinismus ## 2.1 Systemebenen
- Gleiche Dokumente + gleiche Konfiguration → identisches `index.ndjson` ### 1. Admin-Ebene (Symfony Backend)
- Gleiches `index.ndjson` → identisches FAISS - Dokumentverwaltung
- Gleiche Query → identisches Retrieval-Ergebnis - Versionierung
- Tag-Management
- Job-Steuerung
- System-Prompt-Verwaltung
- KI-Endpoint-Konfiguration
## 2.2 Governance ### 2. Wissensebene
- Dokumente (immutable)
- DocumentVersion
- Chunks
- index.ndjson
- index_meta.json
- Eine aktive Version pro Dokument ### 3. Vector-Ebene (Python)
- Keine impliziten Index-Änderungen - Embedding-Modell (lokal)
- Strukturänderungen erzwingen Global Reindex - FAISS-Index (Chunks)
- Keine Selbstmodifikation durch KI - FAISS-Index (Tags)
- Persistenter Vector-Service
- CLI-Fallback
## 2.3 Skalierbarkeit ### 4. Agent-Ebene
- Retrieval-Fusion
- NDJSON (streamingfähig) - PromptBuilder
- Kein RAM-basiertes JSON-Array - SSE-Streaming
- Zielgröße > 200k Chunks - Chat-History-Verarbeitung
- FAISS Full Rebuild ist deterministisch
--- ---
# 3. Wissensspeicher # 3. Dokumentenarchitektur
## 3.1 index.ndjson ## 3.1 Primärquellen
Single Source of Truth. - Dokumente sind immutable.
- Jede Änderung erzeugt eine neue DocumentVersion.
- Pro Dokument existiert genau eine aktive Version.
- 1 JSON-Objekt pro Zeile ## 3.2 Aktivierungsprozess
- Streaming-Append
- Deterministische Compaction by `document_id`
Beispielstruktur: 1. Aktivierung einer Version
2. Erstellung eines IngestJob
```json 3. Async-Start:
{ ```
"chunk_id": "uuid", bin/console mto:agent:ingest:run <jobId>
"document_id": "uuid", ```
"document_version_id": "uuid", 4. IngestOrchestrator:
"text": "...", - Guardrail-Validierung
"meta": { ... } - NDJSON Compaction by document_id
} - Chunking
``` - Streaming Append
- Vollständiger FAISS-Rebuild
Regeln: - index_meta.json Update
- Status COMPLETED/FAILED
- Keine JSON-Array-Datei
- Keine Mutation einzelner Chunks
- Nur Append + deterministische Entfernung per `document_id`
--- ---
## 3.2 index_meta.json # 4. NDJSON-Architektur
Strukturparameter: ## 4.1 index.ndjson (Single Source of Truth)
- `index_version` - Streamingfähiges Format
- `embedding_model` - Kein JSON-Array
- `embedding_dimension` - Append-only mit Compaction
- `chunk_size` - Keine vollständige RAM-Verarbeitung
- `chunk_overlap` - Atomare Datei-Switches (.tmp → rename)
- `scoring_version`
- `index_format`
- `vector_backend`
Wenn einer dieser Werte sich ändert: ## 4.2 index_meta.json
**Global Reindex zwingend erforderlich** Enthält:
- index_version
- embedding_model
- embedding_dimension
- chunk_size
- overlap
- scoring_version
- index_format
### Guardrail-Mechanismus
Bei strukturellen Änderungen (Embedding, Chunking, Scoring):
- Lokaler Ingest wird blockiert
- Global Reindex erforderlich
--- ---
## 3.3 FAISS # 5. Chunk-Management
Dateien: Verantwortlich: ChunkManager
- `vector.index` Eigenschaften:
- `vector.index.meta.json`
- `vector_tags.index`
- `vector_tags.index.meta.json`
FAISS wird IMMER vollständig aus `index.ndjson` gebaut. - Streaming-basiertes Schreiben
- Deterministische Reproduktion
Keine Partial Updates. - Hard Limit: 120.000 Chunks
Kein inkrementelles Vector-Append. - Warnlimit: 100.000 Chunks
- Kein vollständiger JSON-RAM-Load
--- ---
# 4. Persistenter Vector-Service # 6. Vector-Architektur
Retrieval läuft nicht mehr über: ## 6.1 Betriebsmodi
- Symfony Process ### A) Persistenter Vector-Service (bevorzugt)
- `exec()` - Lädt Embedding-Modell einmal
- `python vector_search.py` pro Anfrage - Lädt FAISS-Indizes in RAM
- REST-Endpunkte:
- /search-chunks
- /search-tags
Sondern über: ### B) CLI-Fallback
- Python-Skripte
- Wird genutzt, falls Service nicht verfügbar ist
**FastAPI + Uvicorn (persistent im RAM)** ## 6.2 Rebuild-Strategie
## 4.1 Eigenschaften - Immer vollständiger FAISS-Rebuild
- Kein inkrementelles Patchen
Beim Start lädt der Service: - Atomarer Index-Switch
- Deterministisch und drift-sicher
- Embedding-Modell
- Chunk-Index
- Tag-Index
- ID-Mappings
Diese bleiben dauerhaft im RAM.
Kein Modell-Reload pro Anfrage.
Kein Disk-Reload pro Anfrage.
Kein Python-Spawn pro Anfrage.
## 4.2 Endpoints
- `GET /health`
- `POST /search-chunks`
- `POST /search-tags`
- `POST /reload`
## 4.3 Reload-Mechanismus
Nach Global Reindex:
```bash
curl -X POST http://127.0.0.1:8090/reload
```
Lädt:
- Chunk-Index neu
- Tag-Index neu
- Modell nur wenn `embedding_model` geändert wurde
Kein Neustart nötig.
Keine Downtime.
--- ---
# 5. Score-Gates (Routing-Sicherheit) # 7. Hybrid Retrieval
## 5.1 Tag-Gate ## 7.1 Retrieval-Komponenten
Tags steuern Routing. 1. Keyword-Retrieval (führend)
2. FAISS-Chunk-Retrieval (ergänzend)
3. Tag-Routing (Soft-Gate)
Empfohlener Mindestscore: ## 7.2 Score-Fusion
`MIN_SCORE ≈ 0.70` - Keyword hat Priorität
- Vector ergänzt semantische Nähe
Schützt vor: - Tags dienen als Routing-Verstärker
- zufälligen semantischen Treffern
- falschem Dokumentrouting
## 5.2 Chunk-Gate
Chunks sind Kontext.
Weicher Gate:
`MIN_SCORE ≈ 0.50`
Optional: relativer Score zum besten Treffer.
--- ---
# 6. Dokument- & Versionsmodell # 8. Tag-System
Document ## 8.1 Entities
→ enthält mehrere `DocumentVersion`
→ genau eine Version ist aktiv
Regel: - Tag
- DocumentTag
- TagRebuildJob
Es darf immer nur eine aktive Version pro Dokument existieren. ## 8.2 Trigger-Logik
Beim Aktivieren einer Version: Ein Rebuild wird ausgelöst bei:
- Alle anderen Versionen werden inaktiv - Tag-Erstellung
- `IngestStatus → PENDING` - Tag-Löschung
- Re-Ingest via Job - Tag-Zuweisung
- Tag-Entfernung
## 8.3 Job-Mechanik
- Async-Start via:
```
php bin/console mto:agent:tags:job:run <jobId>
```
- Logfile unter:
```
var/log/tags/job_<uuid>.log
```
## 8.4 Stale-Protection
- QUEUED-Jobs älter als 5 Minuten → FAILED
- System kann nicht dauerhaft blockieren
- Coalescing (max. 1 aktiver Job)
## 8.5 Tag-Index
- tags.ndjson
- vector_tags.index
- Vollständiger Rebuild bei Änderung
--- ---
# 7. Ingest-Architektur (vollständig Job-basiert) # 9. Job-Architektur
Ingest läuft NIEMALS synchron im HTTP-Request. Statusmodell:
Jede Mutation am Index läuft über: - QUEUED
- RUNNING
- COMPLETED
- FAILED
IngestJob → CLI Runner → IngestOrchestrator → IngestFlow Eigenschaften:
## 7.1 Job-Typen - Async exec
- LockService gegen Parallel-Ausführung
- `DOCUMENT_VERSION_ACTIVATE` - Self-Healing gegen blockierte Jobs
- `DOCUMENT` - Logging pro Job
- `GLOBAL_REINDEX`
## 7.2 Job-Status
- `QUEUED`
- `RUNNING`
- `COMPLETED`
- `FAILED`
- `ABORTED`
CLI-Ausführung:
```bash
php bin/console mto:agent:ingest:run <jobId>
```
--- ---
# 8. Hybrid Retrieval # 10. Governance & Guardrails
Flow: ## 10.1 Rollen
User Query - Super Admin
→ Keyword Retrieval - Knowledge Admin
→ Tag Vector Search - Redaktion
→ Dokumentfilter - Frontend-User
→ Chunk Vector Retrieval
→ Score Fusion
→ NDJSON Lookup
→ Context Builder
→ LLM
→ SSE Streaming
Keyword bleibt Primärsignal. ## 10.2 Schutzmechanismen
Vector ergänzt Semantik.
- Dokumente immutable
- Keine manuelle Chunk-Manipulation
- Versionierte Ingest-Profile
- Versionierte System-Prompts
- Konfigurierbare KI-Endpunkte
- Logging & Audit-Fähigkeit
--- ---
# 9. Locking & Concurrency # 11. Agent-Architektur
LockService verhindert: - SSE-Streaming
- Historienverarbeitung korrekt implementiert
- parallelen Ingest - Deterministischer PromptBuilder
- gleichzeitige Reindex-Vorgänge - Retrieval-Kontext explizit eingebettet
- NDJSON-Korruption - Kein Think-Mode-Leak
Keine gleichzeitigen Mutationen erlaubt.
--- ---
# 10. Vector Control (Production Safe) # 12. Skalierbarkeit
Ein zentrales Kommando steuert: Zielgröße:
- Dependency-Check - >120.000 Chunks
- Auto-Install (opt-in)
- Service Start
- Service Stop
- Reload
- Status
- Health-Check
- PID-Management
## Command Ermöglicht durch:
`mto:agent:vector:control` - NDJSON Streaming
- Kein Full-RAM-JSON
## Beispiele - Vollständiger FAISS-Rebuild
- Persistenter Vector-Service
Status: - Atomare Switches
- Locking-Mechanismen
```bash
bin/console mto:agent:vector:control
```
Install + Start:
```bash
bin/console mto:agent:vector:control --install --start
```
Stop:
```bash
bin/console mto:agent:vector:control --stop
```
Reload:
```bash
bin/console mto:agent:vector:control --reload
```
## Production-Safety
- PID-File unter `var/run/vector_service.pid`
- SIGTERM Stop mit Timeout
- Optional SIGKILL (`--force`)
- Health-Check mit Retry-Mechanismus
- Kein automatisches Install ohne Flag
--- ---
# 11. CLI Commands # 13. Stabilitätsstatus (Freeze-Zustand)
- `mto:agent:ingest:run <jobId>` | Bereich | Status |
- `mto:agent:vector:control` |----------|--------|
- `mto:agent:test` | Dokument-Ingest | Stabil |
- `mto:agent:chat` | NDJSON-Architektur | Enterprise-Stabil |
| FAISS-Rebuild | Deterministisch |
Alle Commands unter: | Tag-System | Stabil mit Stale-Recovery |
| Async-Jobs | Blockiersicher |
`mto:agent:*` | Retrieval-Fusion | Funktional |
| SSE | Stabil |
| Governance | Aktiv |
--- ---
# 12. Failure Modes # 14. System-Freeze-Definition
Vector Service nicht erreichbar Dieses Dokument definiert den verbindlichen Referenzstand des Systems.
`vector:control --start`
Reload Endpoint fehlt Ab diesem Punkt gilt:
→ falsche Service-Version
index_meta mismatch - Keine strukturellen Änderungen ohne explizite Freigabe.
→ Global Reindex - Erweiterungen nur inkrementell.
- Keine Architektur-Rewrites.
Lock aktiv - Determinismus und Reproduzierbarkeit sind oberstes Prinzip.
→ Parallel-Ingest blockiert
--- ---
# 13. Non-Goals # 15. Zusammenfassung
- Kein Online-Learning Das System ist:
- Keine inkrementellen FAISS Updates
- Keine selbstverändernden Prompts
- Kein Auto-Merging von Chunks
- Kein Vector-Append im Runtime
Strukturänderungen → explizit + Reindex.
---
# 14. Zusammenfassung
Dieses System ist:
- deterministisch - deterministisch
- reproduzierbar
- drift-sicher - drift-sicher
- governance-stabil - governance-konform
- skalierbar
- blockiersicher
- debugbar
- enterprise-ready - enterprise-ready
- job-basiert
- versionssicher
- persistent im Retrieval
- ohne Spawn-Overhead
- reload-fähig ohne Downtime
Wichtige Neuerungen: Es erfüllt die Anforderungen an ein kontrolliertes, reproduzierbares RAG-System mit klarer Trennung zwischen Wissensquelle, Index, Retrieval und Generierung.
- Persistenter Vector-Service ersetzt CLI-Spawn
- Score-Gates verhindern falsches Routing
- Reload-Endpoint vermeidet Neustarts
- Production-Safe Control Command integriert
- Vollständige Trennung von Ingest und Runtime