80 lines
2.2 KiB
Markdown
80 lines
2.2 KiB
Markdown
# 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:
|
||
|
||
1. **NDJSON ist Single Source of Truth**
|
||
Alle Vektoren werden deterministisch aus `index.ndjson` erzeugt.
|
||
|
||
2. **Full Rebuild statt inkrementeller Mutation**
|
||
Der FAISS-Index wird bei Änderungen vollständig neu aufgebaut.
|
||
|
||
3. **Streaming statt Full-RAM-Load**
|
||
Keine vollständigen JSON-Arrays im Speicher.
|
||
|
||
4. **Runtime und Domain sind strikt getrennt**
|
||
PHP enthält Orchestrierung und Governance, Python enthält Vektor-Runtime.
|
||
|
||
5. **Atomare Dateioperationen**
|
||
Schreibvorgänge erfolgen über `.tmp` + `rename()`.
|
||
|
||
6. **Konfigurationszentrierung**
|
||
Alle Pfade und Script-Referenzen sind über `services.yaml` parametriert.
|
||
|
||
---
|
||
|
||
# 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_array` im 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:
|