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