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)

---

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

Kernmerkmale:

• Versionierte Dokumentverwaltung (immutable Primärquellen)
• 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.

---

2. Architekturüberblick

2.1 Systemebenen

1) Admin-Ebene (Symfony Backend)

Verantwortlich für:

• 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
• PromptBuilder
• SSE-Streaming
• History-Verarbeitung

---

3. Dokumentenarchitektur

3.1 Primärquellen-Prinzip

• Dokumente sind immutable.
• Jede Änderung erzeugt eine neue DocumentVersion.
• Genau eine Version pro Dokument ist aktiv.
• Chunks sind abgeleitete Artefakte.
• Keine manuelle Chunk-Manipulation.

---

3.2 Aktivierungsprozess (Async)

1. Aktivierung einer DocumentVersion
2. Erstellung eines IngestJob (Status: QUEUED)
3. Async-Ausführung:

bin/console mto:agent:ingest:run

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

Eigenschaften:

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

---

4.2 index_meta.json

Struktur (validiert):

• 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

wird lokaler Ingest blockiert und ein Global Reindex erforderlich.

---

5. Chunk-Management

Verantwortlich: ChunkManager + Ingest-Services

Eigenschaften:

• Streaming-Schreiben
• Deterministische Reproduktion
• Hard Limit: 120.000 Chunks
• Warnlimit: 100.000 Chunks
• Kein vollständiger RAM-Load

---

6. Vector-Architektur

6.1 Persistenter Vector-Service (Standard)

Service-URL (Default):

http://127.0.0.1:8090

Endpoints:

• POST /search-chunks
• POST /search-tags

Control:

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

---

6.2 CLI-Fallback

Python-Skripte:

• python/vector/vector_search.py
• python/vector/vector_ingest.py
• python/vector/vector_search_tags.py
• python/vector/vector_ingest_tags.py

---

6.3 Rebuild-Strategie

• Immer vollständiger FAISS-Rebuild
• Kein inkrementelles Patchen
• Atomarer Switch (.tmp → rename)
• Deterministisch und reproduzierbar

---

7. Retrieval (Vector-only)

Retrieval über NdjsonHybridRetriever.

Ablauf:

1. Query Cleaning (nur für Retrieval)
2. Optional: Tag-Routing
3. Chunk Vector Search
4. NDJSON Chunk Lookup

Keine Keyword-Suche im System vorhanden.

---

8. Tag-System

8.1 Entities

• Tag
• DocumentTag
• TagRebuildJob

8.2 Trigger

Rebuild bei:

• Tag-Erstellung
• Tag-Löschung
• Tag-Zuweisung
• Tag-Entfernung

8.3 Async-Ausführung

php bin/console mto:agent:tags:job:run

Log:

var/log/tags/job_.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

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
• Frontend-User

Schutzmechanismen:

• Immutable Dokumente
• Versionierung statt Ersetzen
• Keine Chunk-Editierung
• Guardrail gegen Strukturdrift
• Atomare Dateioperationen
• Locking & Job-Orchestrierung
• Logging & Audit

---

12. Skalierbarkeit

Ausgelegt für:

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

---

13. Stabilitätsstatus

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

---

14. System-Freeze-Definition

Dieses Dokument definiert den verbindlichen Referenzstand.

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.

---

15. Zusammenfassung

Das System ist:

• deterministisch
• drift-sicher
• governance-konform
• skalierbar
• blockiersicher
• auditierbar
• reproduzierbar
• enterprise-ready

Retrieval ist vollständig vektorbasiert (Chunks + optional Tags).

Architekturfluss:

Primärquelle → NDJSON → FAISS → Vector Retrieval → Prompt → Generierung

Das System befindet sich im stabilen Freeze-Zustand.