marek/MtoRagSystem

Fork 0

Files

team2 a2a6e1bca2 update README.md

2026-02-23 21:02:55 +01:00

5.8 KiB

Raw Blame History

RAG-System – Technische Projektdokumentation

Version: 1.0
Stand: Februar 2026
Autor: mitho
Status: Verbindliche Referenzarchitektur (System Freeze)

1. Ziel des Systems

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.“

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. Architekturüberblick

2.1 Systemebenen

1. Admin-Ebene (Symfony Backend)

Dokumentverwaltung
Versionierung
Tag-Management
Job-Steuerung
System-Prompt-Verwaltung
KI-Endpoint-Konfiguration

2. Wissensebene

Dokumente (immutable)
DocumentVersion
Chunks
index.ndjson
index_meta.json

3. Vector-Ebene (Python)

Embedding-Modell (lokal)
FAISS-Index (Chunks)
FAISS-Index (Tags)
Persistenter Vector-Service
CLI-Fallback

4. Agent-Ebene

Retrieval-Fusion
PromptBuilder
SSE-Streaming
Chat-History-Verarbeitung

3. Dokumentenarchitektur

3.1 Primärquellen

Dokumente sind immutable.
Jede Änderung erzeugt eine neue DocumentVersion.
Pro Dokument existiert genau eine aktive Version.

3.2 Aktivierungsprozess

Aktivierung einer Version
Erstellung eines IngestJob

Async-Start:

bin/console mto:agent:ingest:run <jobId>

IngestOrchestrator:
- Guardrail-Validierung
- NDJSON Compaction by document_id
- Chunking
- Streaming Append
- Vollständiger FAISS-Rebuild
- index_meta.json Update
- Status COMPLETED/FAILED

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

Keyword-Retrieval (führend)
FAISS-Chunk-Retrieval (ergänzend)
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
```

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

9. Job-Architektur

Statusmodell:

QUEUED
RUNNING
COMPLETED
FAILED