From efa9b17c2fc39f275e571181f3a3ea5d3550249c Mon Sep 17 00:00:00 2001 From: team2 Date: Fri, 27 Feb 2026 20:34:49 +0100 Subject: [PATCH] new readme --- README.md | 489 +++++++++++++++++++++--------------------------------- 1 file changed, 186 insertions(+), 303 deletions(-) diff --git a/README.md b/README.md index 8dd3dbb..a585f03 100644 --- a/README.md +++ b/README.md @@ -1,415 +1,298 @@ # 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) + +Version: 2.0 +Stand: Februar 2026 +Status: Code-validierte Referenzarchitektur --- # 1. Ziel des Systems -Das RAG-System dient der deterministischen, governance-stabilen Beantwortung von Nutzeranfragen auf Basis versionierter, kontrollierter Wissensquellen. +Das System implementiert ein deterministisches Retrieval-Augmented-Generation (RAG) Framework auf Basis versionierter Dokumente. -Grundprinzip: +Leitprinzip: > „Wir nutzen KI nicht, um kreativ zu raten, sondern um verlässlich auf Basis Ihres Wissens zu antworten.“ -Kernmerkmale: +Das System stellt sicher: -- Versionierte Dokumentverwaltung (immutable Primärquellen) +- Versionierte Dokumentverwaltung - 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. +- Streamingfähige NDJSON Source of Truth +- Vollständiger FAISS-Rebuild bei strukturellen Änderungen +- Persistenter Python Vector-Service +- Governance-stabile Ingest- und Reindex-Mechanik --- # 2. Architekturüberblick -## 2.1 Systemebenen - -### 1) Admin-Ebene (Symfony Backend) - -Verantwortlich für: +## 2.1 Hauptkomponenten +Symfony (PHP) - 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 +- Ingest-Orchestrierung +- Job-System +- Admin-Oberfläche - PromptBuilder -- SSE-Streaming -- History-Verarbeitung +- VectorSearchClient + +Python Layer +- Embedding-Modell (SentenceTransformers) +- FAISS Index +- Vector-Service (FastAPI + uvicorn) +- CLI-Fallback Scripts + +Persistenz +- index.ndjson (Single Source of Truth) +- index_meta.json (Struktur-Metadaten) +- vector.index (FAISS) +- tags.ndjson (optional) +- vector_tags.index (optional) --- -# 3. Dokumentenarchitektur +# 3. Verzeichnisstruktur (verifiziert) -## 3.1 Primärquellen-Prinzip +bin/ +config/ +migrations/ +public/ +python/ +src/ +templates/ +var/ -- Dokumente sind immutable. -- Jede Änderung erzeugt eine neue DocumentVersion. -- Genau eine Version pro Dokument ist aktiv. -- Chunks sind abgeleitete Artefakte. -- Keine manuelle Chunk-Manipulation. +Python-Vektorlayer: + +python/ +vector_service.py +vector_control.py +vector_ingest.py +vector_search.py +vector_ingest_tags.py +vector_search_tags.py --- -## 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. Source of Truth Konzept ## 4.1 index.ndjson -Eigenschaften: +Streamingfähiges NDJSON-Format: -- 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. - ---- +- Eine JSON-Zeile pro Chunk +- Kein JSON-Array +- Append-fähig +- Speicheroptimiert für >200k Chunks ## 4.2 index_meta.json -Struktur (validiert): +Beinhaltet: - 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 +- index_format -wird lokaler Ingest blockiert und ein Global Reindex erforderlich. +Bei strukturellen Änderungen wird ein Global Reindex erzwungen. --- -# 5. Chunk-Management +# 5. Dokument-Lifecycle -Verantwortlich: ChunkManager + Ingest-Services +Dokument +→ Version +→ Aktivierung +→ IngestJob (QUEUE) +→ Chunking +→ NDJSON Compaction by document_id +→ Full FAISS Rebuild +→ Status INDEXED -Eigenschaften: +Wichtige Regel: -- Streaming-Schreiben -- Deterministische Reproduktion -- Hard Limit: 120.000 Chunks -- Warnlimit: 100.000 Chunks -- Kein vollständiger RAM-Load +Es existiert immer nur eine aktive Version pro Dokument. --- -# 6. Vector-Architektur +# 6. Ingest-System -## 6.1 Persistenter Vector-Service (Standard) +## 6.1 Job-Typen -Service-URL (Default): +- DOCUMENT_UPLOAD +- DOCUMENT_VERSION_ACTIVATE +- GLOBAL_REINDEX -http://127.0.0.1:8090 +## 6.2 Aktivierung -Endpoints: +Beim Aktivieren einer Version: -- POST /search-chunks -- POST /search-tags +- DB-Status wird geändert +- IngestStatus → PENDING +- IngestJob wird erzeugt +- CLI-Execution via: -Control: +``` +bin/console mto:agent:ingest:run +``` -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 +LockService verhindert Parallel-Ingest. --- -## 6.2 CLI-Fallback +# 7. Retrieval -Python-Skripte: +## 7.1 Architektur -- python/vector/vector_search.py -- python/vector/vector_ingest.py -- python/vector/vector_search_tags.py -- python/vector/vector_ingest_tags.py +Hybrid im Sinne von: + +- FAISS Vektor-Retrieval +- Optionales Tag-Routing (separater Tag-Index) + +Kein klassisches Keyword-Retrieval mehr aktiv. + +## 7.2 Ablauf + +1. Anfrage +2. VectorSearchClient → Python Service +3. FAISS Similarity Search +4. Top-K Chunks +5. PromptBuilder +6. LLM Response --- -## 6.3 Rebuild-Strategie +# 8. Python Vector Service -- Immer vollständiger FAISS-Rebuild -- Kein inkrementelles Patchen -- Atomarer Switch (.tmp → rename) -- Deterministisch und reproduzierbar +FastAPI Service mit uvicorn. + +Steuerung über: + +``` +bin/console mto:agent:vector:control +``` + +Mögliche Aktionen: + +- --install +- --start +- --stop +- --reload +- --status + +Service lädt: + +- Embedding-Modell einmalig +- FAISS Index einmalig +- Hält alles persistent im RAM + +CLI-Fallback bleibt verfügbar. --- -# 7. Retrieval (Vector-only) +# 9. Embedding -Retrieval über `NdjsonHybridRetriever`. +Verwendetes Modell ist konfigurierbar. -Ablauf: +Embedding-Dimension wird aus Modell bestimmt und im index_meta.json gespeichert. -1) Query Cleaning (nur für Retrieval) -2) Optional: Tag-Routing -3) Chunk Vector Search -4) NDJSON Chunk Lookup +Bei Dimensionsänderung: -Keine Keyword-Suche im System vorhanden. +→ Guardrail blockiert lokalen Ingest +→ Global Reindex erforderlich --- -# 8. Tag-System +# 10. Reindex-Strategie -## 8.1 Entities +## 10.1 Lokaler Re-Ingest -- Tag -- DocumentTag -- TagRebuildJob +- Compaction nur für document_id +- Neue Chunks append +- Danach vollständiger FAISS-Rebuild -## 8.2 Trigger +## 10.2 Global Reindex -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. +- Alle aktiven Dokumente neu ingestieren +- index.ndjson komplett neu schreiben +- index_version++ +- FAISS neu bauen --- -# 9. Job-Architektur +# 11. Rollenmodell -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 +- SUPER_ADMIN +- KNOWLEDGE_ADMIN +- Wissensredaktion - Frontend-User -Schutzmechanismen: - -- Immutable Dokumente -- Versionierung statt Ersetzen -- Keine Chunk-Editierung -- Guardrail gegen Strukturdrift -- Atomare Dateioperationen -- Locking & Job-Orchestrierung -- Logging & Audit +Dokumente sind immutable. +Chunks sind niemals manuell editierbar. --- -# 12. Skalierbarkeit +# 12. Guardrails -Ausgelegt für: +Verhindert: -≥ 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. +- Embedding-Modell-Drift +- Chunking-Parameter-Drift +- Index-Format-Drift +- Parallele Ingest-Jobs +- Live-Änderung aktiver Ingest-Profile --- -# 13. Stabilitätsstatus +# 13. Wichtige Symfony Commands (validiert) -| 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 | +mto:agent:ingest:run +mto:agent:vector:control +mto:agent:vector:ingest +mto:agent:vector:search + +Namespace ist durchgehend: + +mto:agent:* --- -# 14. System-Freeze-Definition +# 14. Systemgrenzen -Dieses Dokument definiert den verbindlichen Referenzstand. +Das System ist ausgelegt für: -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. +- >200.000 Chunks +- Deterministische Reproduzierbarkeit +- Enterprise-Governance +- Drift-Sicherheit +- Skalierbare Erweiterung --- -# 15. Zusammenfassung +# 15. Nicht Bestandteil -Das System ist: +- Kein manuelles Chunk-Editing +- Kein Keyword-Retrieval +- Kein partieller FAISS-Rebuild +- Kein In-Place Index Update -- deterministisch -- drift-sicher -- governance-konform -- skalierbar -- blockiersicher -- auditierbar -- reproduzierbar -- enterprise-ready +Immer vollständiger Rebuild. -Retrieval ist vollständig vektorbasiert (Chunks + optional Tags). +--- -Architekturfluss: +# 16. Zusammenfassung -Primärquelle → NDJSON → FAISS → Vector Retrieval → Prompt → Generierung +Das System implementiert eine deterministische, governance-stabile RAG-Architektur mit: -Das System befindet sich im stabilen Freeze-Zustand. \ No newline at end of file +- NDJSON als Streaming-Single-Source +- Vollständigem FAISS-Rebuild +- Persistenter Vector-Service-Schicht +- Versionierter Dokumentverwaltung +- Strikter Guardrail-Logik + +Diese README entspricht vollständig dem aktuellen Code-Stand der rag.zip. \ No newline at end of file