2.2 KiB
Technische Projektdokumentation
RAG-System – Phase A Abschluss
Projekt: KI-RAG System
Architekturstand: Phase A abgeschlossen
Datum: Februar 2026
Status: Verbindliche Referenzdokumentation
1. Zielsetzung von Phase A
Phase A hatte das Ziel, das bestehende Retrieval-Augmented-Generation-System strukturell zu stabilisieren und produktionsreif zu machen.
Im Fokus standen:
- Speicherstabilität (Streaming statt RAM-Load)
- Deterministische Indexierung
- Strikte Trennung von Domain (PHP) und Runtime (Python)
- Zentrale Konfigurationssteuerung
- Drift-Sicherheit des Vector-Index
Phase A beinhaltete keine funktionale Erweiterung, sondern ausschließlich strukturelle und architektonische Stabilisierung.
2. Architekturprinzipien
Das System folgt folgenden verbindlichen Grundprinzipien:
-
NDJSON ist Single Source of Truth
Alle Vektoren werden deterministisch ausindex.ndjsonerzeugt. -
Full Rebuild statt inkrementeller Mutation
Der FAISS-Index wird bei Änderungen vollständig neu aufgebaut. -
Streaming statt Full-RAM-Load
Keine vollständigen JSON-Arrays im Speicher. -
Runtime und Domain sind strikt getrennt
PHP enthält Orchestrierung und Governance, Python enthält Vektor-Runtime. -
Atomare Dateioperationen
Schreibvorgänge erfolgen über.tmp+rename(). -
Konfigurationszentrierung
Alle Pfade und Script-Referenzen sind überservices.yamlparametriert.
3. Umsetzung Phase A
A1 – Streaming-Architektur
Problem
RAM-basierte JSON-Verarbeitung hätte bei steigender Chunk-Zahl zu Speicherproblemen geführt.
Umsetzung
- Einführung von NDJSON als persistentes Format
- Streaming-Verarbeitung in:
ChunkManager::streamAll()ChunkManager::countAllChunks()ChunkManager::compactByDocument()ChunkManager::rewriteAll()
- Entfernung von
iterator_to_arrayim IngestFlow
Ergebnis
- Speicherverbrauch unabhängig von Chunk-Anzahl
- Stabil bis mindestens 120.000 Chunks
A2 – Strukturtrennung Runtime / Domain
Umsetzung
Python-Runtime wurde vollständig aus src/ entfernt und ausgelagert nach: