add new md files
This commit is contained in:
team 1
588
README.md
588
README.md
@@ -1,430 +1,314 @@
|
||||
# mitho AI Agent – Developer Deep Dive
|
||||
|
||||
# mitho AI Agent – Developer README
|
||||
Enterprise Hybrid RAG System (Symfony + NDJSON + FAISS)
|
||||
|
||||
---
|
||||
|
||||
# 1. System Overview
|
||||
|
||||
This system implements a deterministic, governance-stable Retrieval Augmented Generation (RAG) architecture based on:
|
||||
|
||||
- Symfony (PHP backend)
|
||||
- NDJSON-based knowledge index
|
||||
- Full FAISS vector rebuild strategy
|
||||
- Hybrid retrieval (keyword + vector)
|
||||
- Deterministic ingest pipeline
|
||||
- Strict versioning & guardrails
|
||||
- Lock-based reindex protection
|
||||
|
||||
No incremental vector mutation is allowed.
|
||||
FAISS is always rebuilt from `index.ndjson`.
|
||||
Stand: Februar 2026
|
||||
Status: Produktiv stabil – Job-basierte Ingest-Architektur vollständig integriert
|
||||
|
||||
---
|
||||
|
||||
# 2. High-Level Architecture
|
||||
# 1. Systemüberblick
|
||||
|
||||
User Query
|
||||
→ Hybrid Retrieval
|
||||
→ Context Assembly
|
||||
→ Prompt Builder
|
||||
→ LLM
|
||||
→ Streaming Response (SSE)
|
||||
Dieses System implementiert eine deterministische, governance-stabile
|
||||
Hybrid-RAG-Architektur mit:
|
||||
|
||||
Knowledge Flow:
|
||||
Document → Version → Extract → Chunk → NDJSON → FAISS → Retrieval
|
||||
- Symfony (PHP Backend)
|
||||
- NDJSON als Single Source of Truth
|
||||
- FAISS als Vektorindex (immer Full Rebuild)
|
||||
- Hybrid Retrieval (Keyword + Vektor)
|
||||
- Versioniertes Dokumentmodell
|
||||
- Job-basierte Ingest-Pipeline
|
||||
- Lock-geschützte Reindex-Operationen
|
||||
- SSE-Streaming im Frontend
|
||||
|
||||
Grundprinzip:
|
||||
Keine inkrementellen Vektor-Updates.
|
||||
FAISS wird immer vollständig aus index.ndjson neu gebaut.
|
||||
|
||||
---
|
||||
|
||||
# 3. Directory Structure (Knowledge Layer)
|
||||
# 2. Architekturprinzipien
|
||||
|
||||
```
|
||||
var/knowledge/
|
||||
├── uploads/
|
||||
├── chunks/
|
||||
├── index.ndjson
|
||||
├── index_meta.json
|
||||
├── vector.index
|
||||
└── vector_meta.json
|
||||
```
|
||||
Determinismus:
|
||||
- Gleiche Dokumente + gleiche Konfiguration → identisches index.ndjson
|
||||
- Gleiches index.ndjson → identisches FAISS
|
||||
- Gleiche Query → identisches Retrieval-Ergebnis
|
||||
|
||||
Governance:
|
||||
- Eine aktive Version pro Dokument
|
||||
- Keine impliziten Index-Änderungen
|
||||
- Strukturänderungen erzwingen Global Reindex
|
||||
- Keine Selbstmodifikation durch KI
|
||||
|
||||
Skalierbarkeit:
|
||||
- NDJSON (streamingfähig)
|
||||
- Keine RAM-basierte JSON-Arrays
|
||||
- Zielgröße > 200k Chunks
|
||||
|
||||
---
|
||||
|
||||
# 4. NDJSON Index
|
||||
# 3. Wissensspeicher
|
||||
|
||||
## 4.1 index.ndjson
|
||||
## 3.1 index.ndjson
|
||||
|
||||
- Single Source of Truth
|
||||
- One JSON object per line
|
||||
- Streaming-readable
|
||||
- No JSON array wrapper
|
||||
- Scales beyond 200k chunks
|
||||
Single Source of Truth.
|
||||
|
||||
Each line contains:
|
||||
- 1 JSON-Objekt pro Zeile
|
||||
- Streaming-Append
|
||||
- Deterministische Compaction by document_id
|
||||
|
||||
Beispielstruktur:
|
||||
|
||||
```json
|
||||
{
|
||||
"chunk_id": "uuid",
|
||||
"document_id": "uuid",
|
||||
"version": 3,
|
||||
"document_version_id": "uuid",
|
||||
"text": "...",
|
||||
"meta": {...}
|
||||
}
|
||||
```
|
||||
|
||||
NDJSON enables:
|
||||
- Append-based writes
|
||||
- Compaction per document
|
||||
- Memory-safe streaming
|
||||
- Deterministic rebuilds
|
||||
Keine JSON-Array-Datei.
|
||||
Keine Mutation einzelner Chunks.
|
||||
Nur Append + deterministische Entfernung per document_id.
|
||||
|
||||
---
|
||||
|
||||
# 5. Index Metadata
|
||||
## 3.2 index_meta.json
|
||||
|
||||
## index_meta.json
|
||||
|
||||
Managed by:
|
||||
|
||||
- IndexMetaManager
|
||||
- IndexConfiguration
|
||||
|
||||
Contains:
|
||||
Enthält Strukturparameter:
|
||||
|
||||
- index_version
|
||||
- embedding_model
|
||||
- embedding_dimension
|
||||
- chunk_size
|
||||
- overlap
|
||||
- chunk_overlap
|
||||
- scoring_version
|
||||
- index_format
|
||||
- vector_backend
|
||||
|
||||
If configuration changes → Global Reindex required.
|
||||
|
||||
Guarded by:
|
||||
`IndexStructureChangedException`
|
||||
Wenn einer dieser Werte sich ändert:
|
||||
→ Global Reindex zwingend erforderlich.
|
||||
|
||||
---
|
||||
|
||||
# 6. Ingest Pipeline
|
||||
## 3.3 FAISS
|
||||
|
||||
## 6.1 Core Services
|
||||
Dateien:
|
||||
|
||||
| Service | Responsibility |
|
||||
|----------|----------------|
|
||||
| DocumentService | Document lifecycle |
|
||||
| DocumentVersionRepository | Version persistence |
|
||||
| KnowledgeIngestService | Chunk generation |
|
||||
| SimpleChunker | Deterministic splitting |
|
||||
| TextNormalizer | Text cleanup |
|
||||
| StopWords | Keyword filtering |
|
||||
| ChunkManager | NDJSON append + compaction |
|
||||
| ChunkWriter | Chunk persistence |
|
||||
| IngestFlow | Step orchestration |
|
||||
| IngestOrchestrator | Full ingest coordination |
|
||||
| IngestJobService | Job tracking |
|
||||
| LockService | Concurrency guard |
|
||||
- vector.index
|
||||
- vector_meta.json (Chunk-ID Mapping)
|
||||
|
||||
FAISS wird IMMER vollständig aus index.ndjson gebaut.
|
||||
Keine Partial Updates.
|
||||
|
||||
---
|
||||
|
||||
## 6.2 Local Ingest
|
||||
# 4. Dokument- & Versionsmodell
|
||||
|
||||
Used when:
|
||||
- A single document version changes
|
||||
Document
|
||||
→ enthält mehrere DocumentVersion
|
||||
→ genau eine Version ist aktiv
|
||||
|
||||
Process:
|
||||
Regel:
|
||||
Es darf immer nur eine aktive Version pro Dokument existieren.
|
||||
|
||||
1. Extract document
|
||||
2. Normalize text
|
||||
3. Chunk deterministically
|
||||
4. Remove previous chunks of document_id
|
||||
5. Append new chunks to index.ndjson
|
||||
6. Rebuild FAISS completely
|
||||
|
||||
index_version does NOT change.
|
||||
Beim Aktivieren einer Version:
|
||||
- Alle anderen Versionen werden inaktiv
|
||||
- IngestStatus → PENDING
|
||||
- Re-Ingest via Job
|
||||
|
||||
---
|
||||
|
||||
## 6.3 Global Reindex
|
||||
# 5. Ingest-Architektur (vollständig Job-basiert)
|
||||
|
||||
Used when:
|
||||
- Embedding model changes
|
||||
- Chunk size changes
|
||||
- Overlap changes
|
||||
- Scoring logic changes
|
||||
- index_format changes
|
||||
Ingest läuft NIEMALS synchron im HTTP-Request.
|
||||
|
||||
Process:
|
||||
Jede Mutation am Index läuft über:
|
||||
|
||||
1. Re-extract all active document versions
|
||||
2. Recreate full index.ndjson
|
||||
3. Rebuild FAISS
|
||||
IngestJob → CLI Runner → IngestOrchestrator → IngestFlow
|
||||
|
||||
---
|
||||
|
||||
## 5.1 Job-Typen
|
||||
|
||||
DOCUMENT_VERSION_ACTIVATE
|
||||
- Wird genutzt für:
|
||||
- Version aktivieren
|
||||
- Neue Datei hochladen (Auto-Ingest)
|
||||
|
||||
DOCUMENT
|
||||
- Manuelles Ingest einer Version
|
||||
|
||||
GLOBAL_REINDEX
|
||||
- Strukturänderungen
|
||||
|
||||
---
|
||||
|
||||
## 5.2 Job-Status
|
||||
|
||||
- QUEUED
|
||||
- RUNNING
|
||||
- COMPLETED
|
||||
- FAILED
|
||||
- ABORTED
|
||||
|
||||
Jobs werden über CLI ausgeführt:
|
||||
|
||||
php bin/console mto:agent:ingest:run <jobId>
|
||||
|
||||
Start erfolgt asynchron per exec() aus dem Controller.
|
||||
|
||||
---
|
||||
|
||||
# 6. Admin-Flows (aktueller Stand)
|
||||
|
||||
## 6.1 Neue Datei hochladen (NEU: Auto-Ingest)
|
||||
|
||||
Beim Upload:
|
||||
|
||||
1. Datei speichern
|
||||
2. Document + Version 1 erzeugen
|
||||
3. Version 1 aktiv setzen
|
||||
4. IngestJob vom Typ DOCUMENT_VERSION_ACTIVATE anlegen
|
||||
5. Job asynchron starten
|
||||
6. Redirect auf Job-Detailseite
|
||||
|
||||
Ergebnis:
|
||||
Neue Dokumente werden automatisch indexiert.
|
||||
|
||||
---
|
||||
|
||||
## 6.2 Version aktivieren
|
||||
|
||||
1. DB-Status anpassen
|
||||
2. IngestStatus → PENDING
|
||||
3. DOCUMENT_VERSION_ACTIVATE Job erzeugen
|
||||
4. Async Runner starten
|
||||
5. Redirect zur Job-Seite
|
||||
|
||||
---
|
||||
|
||||
## 6.3 Manuelles Ingest
|
||||
|
||||
1. DOCUMENT Job erzeugen
|
||||
2. Async Runner starten
|
||||
3. Redirect zur Job-Seite
|
||||
|
||||
---
|
||||
|
||||
## 6.4 Reset
|
||||
|
||||
Reset löscht:
|
||||
|
||||
- index.ndjson
|
||||
- vector.index
|
||||
- vector_meta.json
|
||||
- Upload-Verzeichnis
|
||||
- Tabellen:
|
||||
- document
|
||||
- document_version
|
||||
- ingest_job
|
||||
|
||||
Nur möglich, wenn exec() aktiv ist.
|
||||
|
||||
---
|
||||
|
||||
# 7. Ingest-Flow Details
|
||||
|
||||
Local Ingest (ein Dokument):
|
||||
|
||||
1. Extract
|
||||
2. Normalize
|
||||
3. Chunk deterministisch
|
||||
4. Entferne alte Chunks per document_id
|
||||
5. Append neue Chunks
|
||||
6. Full FAISS Rebuild
|
||||
|
||||
Global Reindex:
|
||||
|
||||
1. Alle aktiven Versionen neu verarbeiten
|
||||
2. Komplettes index.ndjson neu schreiben
|
||||
3. FAISS neu bauen
|
||||
4. index_version++
|
||||
|
||||
---
|
||||
|
||||
# 7. Vector Architecture
|
||||
|
||||
## 7.1 vector_ingest.py
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- Stream-read index.ndjson
|
||||
- Extract text + chunk_id
|
||||
- Build embeddings
|
||||
- Normalize embeddings
|
||||
- Build FAISS IndexFlatIP
|
||||
- Write vector.index
|
||||
- Write vector.meta.json
|
||||
|
||||
Execution:
|
||||
|
||||
```bash
|
||||
python vector_ingest.py --index path/to/index.ndjson --out path/to/vector.index
|
||||
```
|
||||
|
||||
Characteristics:
|
||||
|
||||
- No partial updates
|
||||
- No incremental mutation
|
||||
- Always full rebuild
|
||||
- Batch size = 64
|
||||
- normalize_embeddings=True
|
||||
|
||||
---
|
||||
|
||||
## 7.2 vector_search.py
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- Load vector.index
|
||||
- Load vector_meta.json
|
||||
- Encode query
|
||||
- Search top-K
|
||||
- Return JSON
|
||||
|
||||
Execution:
|
||||
|
||||
```bash
|
||||
python vector_search.py "query" 5
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
[
|
||||
{ "chunk_id": "...", "score": 0.82 }
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7.3 VectorSearchClient (PHP)
|
||||
|
||||
- Executes Python search script
|
||||
- Parses JSON response
|
||||
- Returns structured results
|
||||
- Handles timeout + error states
|
||||
|
||||
---
|
||||
|
||||
# 8. Hybrid Retrieval
|
||||
|
||||
## 8.1 Components
|
||||
Ablauf:
|
||||
|
||||
| Class | Role |
|
||||
|--------|------|
|
||||
| NdjsonHybridRetriever | Orchestrator |
|
||||
| NdjsonKeywordSearch | Keyword scoring |
|
||||
| NdjsonChunkLookup | Chunk resolution |
|
||||
| VectorSearchClient | Vector bridge |
|
||||
| CachedRetriever | Cache layer |
|
||||
User Query
|
||||
→ Keyword Retrieval
|
||||
→ FAISS Vector Retrieval
|
||||
→ Score Fusion
|
||||
→ NDJSON Chunk Lookup
|
||||
→ Context Builder
|
||||
→ LLM
|
||||
→ SSE Streaming
|
||||
|
||||
Keyword ist Primärsignal.
|
||||
Vector ergänzt Semantik.
|
||||
|
||||
---
|
||||
|
||||
## 8.2 Retrieval Flow
|
||||
# 9. Locking & Concurrency
|
||||
|
||||
1. Extract terms (StopWords + normalization)
|
||||
2. Keyword scoring
|
||||
3. Vector search
|
||||
4. Score fusion
|
||||
5. Limit to N chunks
|
||||
6. Resolve chunk text
|
||||
7. Build LLM context
|
||||
LockService verhindert:
|
||||
|
||||
Keyword score remains primary signal.
|
||||
Vector score augments semantic similarity.
|
||||
- parallelen Ingest
|
||||
- gleichzeitige Reindex-Vorgänge
|
||||
- NDJSON-Korruption
|
||||
|
||||
Keine gleichzeitigen Mutationen erlaubt.
|
||||
|
||||
---
|
||||
|
||||
# 9. Document Extraction
|
||||
# 10. CLI Commands
|
||||
|
||||
Supported via:
|
||||
mto:agent:ingest:run <jobId>
|
||||
mto:agent:vector:ingest
|
||||
mto:agent:vector:search
|
||||
|
||||
- DocumentExtractorInterface
|
||||
- ExtractorResolver
|
||||
- PdfExtractor
|
||||
- DocumentLoader
|
||||
|
||||
Extraction must return clean UTF-8 text.
|
||||
Chunking must remain deterministic.
|
||||
|
||||
---
|
||||
|
||||
# 10. Admin Layer (Symfony)
|
||||
|
||||
## Controllers
|
||||
|
||||
- DashboardController
|
||||
- DocumentController
|
||||
- IngestJobController
|
||||
- SecurityController
|
||||
|
||||
## Entities
|
||||
|
||||
- Document
|
||||
- DocumentVersion
|
||||
- IngestJob
|
||||
- User
|
||||
|
||||
## Repositories
|
||||
|
||||
- DocumentVersionRepository
|
||||
- UserRepository
|
||||
|
||||
---
|
||||
|
||||
# 11. Concurrency & Locks
|
||||
|
||||
LockService ensures:
|
||||
|
||||
- No parallel reindex
|
||||
- No parallel ingest conflict
|
||||
- Controlled mutation of index.ndjson
|
||||
|
||||
File-based or service-based locking.
|
||||
|
||||
---
|
||||
|
||||
# 12. Determinism Rules
|
||||
|
||||
The system guarantees:
|
||||
|
||||
- Same documents + same config = identical index.ndjson
|
||||
- Same index.ndjson = identical FAISS
|
||||
- Same query + same index = identical results
|
||||
|
||||
No randomness.
|
||||
No adaptive mutation.
|
||||
No auto-learning.
|
||||
|
||||
---
|
||||
|
||||
# 13. LLM Integration
|
||||
|
||||
- Context strictly limited to retrieved chunks
|
||||
- PromptBuilder constructs deterministic system prompt
|
||||
- ContextService manages history
|
||||
- SSE streaming enabled
|
||||
- Model endpoint configurable
|
||||
|
||||
LLM never has direct access to full knowledge base.
|
||||
Only retrieved chunks are injected.
|
||||
|
||||
---
|
||||
|
||||
# 14. Scalability
|
||||
|
||||
Designed for:
|
||||
|
||||
- >200k chunks
|
||||
- Streaming NDJSON reads
|
||||
- Full FAISS rebuild
|
||||
- Cache layer for retrieval
|
||||
- Controlled memory usage
|
||||
|
||||
No full-array JSON loads.
|
||||
|
||||
---
|
||||
|
||||
# 15. Failure Modes
|
||||
|
||||
Handled via:
|
||||
|
||||
- Missing vector index detection
|
||||
- Structure drift detection
|
||||
- Lock collision detection
|
||||
- Embedding dependency checks
|
||||
- Python execution errors
|
||||
- Empty chunk fallback
|
||||
|
||||
---
|
||||
|
||||
# 16. Non-Goals
|
||||
|
||||
This system intentionally does NOT include:
|
||||
|
||||
- Online learning
|
||||
- Embedding mutation
|
||||
- Incremental FAISS update
|
||||
- Auto chunk merging
|
||||
- Self-modifying prompts
|
||||
|
||||
All structural changes require explicit reindex.
|
||||
|
||||
---
|
||||
|
||||
# 17. Design Philosophy
|
||||
|
||||
This is a governance-first RAG architecture:
|
||||
|
||||
- Deterministic
|
||||
- Reproducible
|
||||
- Drift-safe
|
||||
- Audit-friendly
|
||||
- Version-controlled
|
||||
|
||||
It prioritizes correctness and control over dynamic mutation.
|
||||
|
||||
---
|
||||
|
||||
# 18. Development Guidelines
|
||||
|
||||
When extending the system:
|
||||
|
||||
- Never mutate FAISS directly
|
||||
- Never edit index.ndjson manually
|
||||
- Always preserve determinism
|
||||
- Increment index_version only via Global Reindex
|
||||
- Guard all structural changes
|
||||
- Maintain streaming compatibility
|
||||
|
||||
---
|
||||
|
||||
# 19. CLI Commands (Symfony)
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
php bin/console mto:agent:vector:ingest
|
||||
```
|
||||
|
||||
Custom commands follow namespace:
|
||||
|
||||
```
|
||||
Alle Commands unter:
|
||||
mto:agent:*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 20. Summary
|
||||
# 11. Failure Modes
|
||||
|
||||
This system is a deterministic, enterprise-grade hybrid RAG engine with:
|
||||
- Vector index fehlt → vector ingest ausführen
|
||||
- index_meta mismatch → Global Reindex
|
||||
- exec deaktiviert → Async-Start schlägt fehl
|
||||
- Lock aktiv → Parallel-Ingest blockiert
|
||||
|
||||
- NDJSON-based streaming index
|
||||
- Full FAISS rebuild strategy
|
||||
- Structured ingest pipeline
|
||||
- Hybrid retrieval
|
||||
- Admin governance layer
|
||||
- Strict guardrails
|
||||
---
|
||||
|
||||
It is designed for controlled enterprise deployment, not experimental AI workflows.
|
||||
# 12. Non-Goals
|
||||
|
||||
- Kein Online-Learning
|
||||
- Keine inkrementellen FAISS Updates
|
||||
- Keine selbstverändernden Prompts
|
||||
- Kein Auto-Merging von Chunks
|
||||
|
||||
Strukturänderungen → explizit + reindex.
|
||||
|
||||
---
|
||||
|
||||
# 13. Zusammenfassung
|
||||
|
||||
Dieses System ist:
|
||||
|
||||
- deterministisch
|
||||
- reproduzierbar
|
||||
- drift-sicher
|
||||
- governance-stabil
|
||||
- enterprise-ready
|
||||
- job-basiert
|
||||
- versionssicher
|
||||
|
||||
Wichtige Neuerung:
|
||||
Neue Dokumente lösen jetzt automatisch einen IngestJob aus
|
||||
(exakt derselbe Mechanismus wie bei Version-Aktivierung).
|
||||
|
||||
Kein HTTP-Ingest mehr.
|
||||
Keine Inline-Rebuilds.
|
||||
Alles läuft über das Job-System.
|
||||
|
||||
334
SYSTEM.md
334
SYSTEM.md
@@ -1,334 +0,0 @@
|
||||
# mitho AI Agent
|
||||
Enterprise Hybrid RAG System (Symfony + NDJSON + FAISS)
|
||||
|
||||
---
|
||||
|
||||
## Überblick
|
||||
|
||||
Der **mitho AI Agent** ist ein deterministisches, governance-stabiles Enterprise-RAG-System auf Symfony-Basis.
|
||||
|
||||
Es kombiniert:
|
||||
|
||||
- Versionierte Dokumente
|
||||
- Streaming-NDJSON-Index
|
||||
- Deterministischen Full-Vector-Rebuild
|
||||
- Keyword- + Vektor-Hybrid-Retrieval
|
||||
- Rollen- und Governance-Modell
|
||||
- Lock- und Guardrail-Mechanismen
|
||||
- Produktionsfähige Adminoberfläche
|
||||
|
||||
> „Wir nutzen KI nicht, um kreativ zu raten, sondern um verlässlich auf Basis Ihres Wissens zu antworten.“
|
||||
|
||||
---
|
||||
|
||||
# Architektur (Enterprise-Version)
|
||||
|
||||
## 1. Kernprinzipien
|
||||
|
||||
- Dokumente sind immutable Primärquellen
|
||||
- index.ndjson ist Single Source of Truth
|
||||
- FAISS wird IMMER vollständig aus index.ndjson neu gebaut
|
||||
- Keine partiellen Vektor-Updates
|
||||
- Strukturänderungen erzwingen Global Reindex
|
||||
- Atomare Switch-Strategie (.tmp + rename)
|
||||
- >200k Chunks skalierbar
|
||||
- Kein Full-JSON-RAM-Load
|
||||
|
||||
---
|
||||
|
||||
# Wissensarchitektur
|
||||
|
||||
```
|
||||
var/knowledge/
|
||||
├── uploads/
|
||||
├── chunks/
|
||||
├── index.ndjson
|
||||
├── index_meta.json
|
||||
├── vector.index
|
||||
└── vector_meta.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Indexstruktur
|
||||
|
||||
## index.ndjson
|
||||
|
||||
- Streamingfähig
|
||||
- Eine Zeile = ein Chunk
|
||||
- JSON pro Zeile
|
||||
- Enthält:
|
||||
- chunk_id
|
||||
- document_id
|
||||
- version
|
||||
- text
|
||||
- meta
|
||||
|
||||
NDJSON ersetzt das frühere index.json (kein Array mehr).
|
||||
|
||||
---
|
||||
|
||||
# Index Meta
|
||||
|
||||
`index_meta.json` enthält:
|
||||
|
||||
- index_version
|
||||
- embedding_model
|
||||
- embedding_dimension
|
||||
- chunk_size
|
||||
- overlap
|
||||
- scoring_version
|
||||
- index_format
|
||||
|
||||
Wird verwaltet durch:
|
||||
|
||||
- `IndexMetaManager`
|
||||
- `IndexConfiguration`
|
||||
|
||||
---
|
||||
|
||||
# Ingest-Architektur
|
||||
|
||||
## Zentrale Klassen
|
||||
|
||||
| Klasse | Aufgabe |
|
||||
|--------|----------|
|
||||
| `DocumentService` | Dokumentverwaltung |
|
||||
| `DocumentVersionRepository` | Versionierung |
|
||||
| `KnowledgeIngestService` | Chunk-Erstellung |
|
||||
| `ChunkManager` | NDJSON Append + Compaction |
|
||||
| `SimpleChunker` | deterministische Text-Splittung |
|
||||
| `TextNormalizer` | Normalisierung |
|
||||
| `StopWords` | Stopword-Filter |
|
||||
| `IngestFlow` | Ablaufsteuerung |
|
||||
| `IngestOrchestrator` | Gesamtkoordination |
|
||||
| `IngestJobService` | Job-Verwaltung |
|
||||
| `LockService` | Reindex-Lock-Mechanismus |
|
||||
| `IndexMetaManager` | Index-Metadaten |
|
||||
| `IndexStructureChangedException` | Guardrail bei Strukturdrift |
|
||||
|
||||
---
|
||||
|
||||
# Ingest-Typen
|
||||
|
||||
## 1. Lokaler Ingest
|
||||
|
||||
- Neue Dokumentversion
|
||||
- Alte Chunks der document_id werden kompakt entfernt
|
||||
- Neue Chunks werden appended
|
||||
- Danach vollständiger FAISS-Rebuild
|
||||
- index_version bleibt gleich
|
||||
|
||||
## 2. Global Reindex
|
||||
|
||||
- Alle aktiven Dokumente neu ingestieren
|
||||
- index.ndjson komplett neu schreiben
|
||||
- FAISS komplett neu bauen
|
||||
- index_version++
|
||||
|
||||
---
|
||||
|
||||
# Vektor-Architektur
|
||||
|
||||
## vector_ingest.py
|
||||
|
||||
Buildet FAISS vollständig aus index.ndjson.
|
||||
|
||||
Eigenschaften:
|
||||
|
||||
- Streaming NDJSON read
|
||||
- normalize_embeddings=True
|
||||
- IndexFlatIP (Inner Product)
|
||||
- Batch-Size 64
|
||||
- Modell konfigurierbar
|
||||
|
||||
Aufruf:
|
||||
|
||||
```bash
|
||||
python vector_ingest.py --index path/to/index.ndjson --out path/to/vector.index
|
||||
```
|
||||
|
||||
Keine inkrementellen Updates. Immer Full-Rebuild.
|
||||
|
||||
---
|
||||
|
||||
## vector_search.py
|
||||
|
||||
- Nimmt Query + Limit
|
||||
- Lädt vector.index
|
||||
- Lädt vector_meta.json
|
||||
- Gibt JSON mit chunk_id + score zurück
|
||||
|
||||
Aufruf:
|
||||
|
||||
```bash
|
||||
python vector_search.py "query" 5
|
||||
```
|
||||
|
||||
Rückgabe:
|
||||
|
||||
```json
|
||||
[
|
||||
{ "chunk_id": "...", "score": 0.83 }
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Hybrid Retrieval
|
||||
|
||||
## Komponenten
|
||||
|
||||
| Klasse | Aufgabe |
|
||||
|--------|----------|
|
||||
| `NdjsonHybridRetriever` | Score-Fusion |
|
||||
| `NdjsonKeywordSearch` | Keyword-Scoring |
|
||||
| `NdjsonChunkLookup` | Chunk-Resolving |
|
||||
| `VectorSearchClient` | Python-Bridge |
|
||||
| `CachedRetriever` | Cache Layer |
|
||||
|
||||
---
|
||||
|
||||
## Retrieval Flow
|
||||
|
||||
1. Prompt
|
||||
2. Keyword-Ranking
|
||||
3. FAISS Top-K
|
||||
4. Score-Fusion
|
||||
5. Final Chunk-Auswahl
|
||||
6. Kontextaufbau
|
||||
7. LLM-Antwort
|
||||
|
||||
Keyword bleibt führend.
|
||||
Vektor ergänzt semantisch.
|
||||
|
||||
---
|
||||
|
||||
# Dokument-Extraktion
|
||||
|
||||
Unterstützt via:
|
||||
|
||||
- `DocumentExtractorInterface`
|
||||
- `ExtractorResolver`
|
||||
- `PdfExtractor`
|
||||
- `DocumentLoader`
|
||||
|
||||
PDFs werden robust extrahiert und normalisiert.
|
||||
|
||||
---
|
||||
|
||||
# Adminbereich (Symfony)
|
||||
|
||||
Controller:
|
||||
|
||||
- `DashboardController`
|
||||
- `DocumentController`
|
||||
- `IngestJobController`
|
||||
- `SecurityController`
|
||||
|
||||
Entities:
|
||||
|
||||
- `Document`
|
||||
- `DocumentVersion`
|
||||
- `IngestJob`
|
||||
- `User`
|
||||
|
||||
Repositories:
|
||||
|
||||
- `DocumentVersionRepository`
|
||||
- `UserRepository`
|
||||
|
||||
Rollenmodell:
|
||||
|
||||
- Super Admin
|
||||
- Knowledge Admin
|
||||
- Redaktion
|
||||
- Frontend User
|
||||
|
||||
---
|
||||
|
||||
# Guardrails & Sicherheit
|
||||
|
||||
- Lock bei Reindex
|
||||
- Strukturdrift-Erkennung
|
||||
- Keine Live-Änderung von Ingest-Profilen
|
||||
- Deterministische Rebuilds
|
||||
- Atomare Datei-Switches
|
||||
- NDJSON niemals vollständig im RAM
|
||||
|
||||
---
|
||||
|
||||
# LLM-Integration
|
||||
|
||||
- Ollama oder kompatibler Endpoint
|
||||
- Streaming via SSE
|
||||
- Historienverwaltung
|
||||
- Prompt-Versionierung
|
||||
- Kontextkontrolle
|
||||
|
||||
---
|
||||
|
||||
# Performance-Merkmale
|
||||
|
||||
- Streaming NDJSON
|
||||
- Kein JSON-Array-Load
|
||||
- Deterministischer FAISS-Rebuild
|
||||
- Cache-Layer
|
||||
- >200k Chunks skalierbar
|
||||
|
||||
---
|
||||
|
||||
# Mindestanforderungen
|
||||
|
||||
Backend:
|
||||
- PHP 8.2+
|
||||
- Symfony 7.x
|
||||
|
||||
Python:
|
||||
- Python 3.9+
|
||||
- faiss
|
||||
- sentence-transformers
|
||||
|
||||
Optional:
|
||||
- Ollama
|
||||
|
||||
---
|
||||
|
||||
# Produktstatus
|
||||
|
||||
Enterprise-ready:
|
||||
|
||||
- Governance-stabil
|
||||
- Drift-sicher
|
||||
- Deterministisch reproduzierbar
|
||||
- Skalierbar
|
||||
- Adminfähig
|
||||
- Rollenbasiert
|
||||
|
||||
---
|
||||
|
||||
# Positionierung
|
||||
|
||||
Dieses System ist keine generische KI.
|
||||
|
||||
Es ist:
|
||||
|
||||
- kontrolliert
|
||||
- versioniert
|
||||
- reproduzierbar
|
||||
- auditierbar
|
||||
- enterprise-tauglich
|
||||
|
||||
---
|
||||
|
||||
# Fazit
|
||||
|
||||
Der mitho AI Agent ist ein kontrolliertes Enterprise-RAG-System mit:
|
||||
|
||||
- NDJSON-Streaming-Index
|
||||
- deterministischem Vector-Rebuild
|
||||
- Hybrid-Retrieval
|
||||
- Guardrail-Mechanismen
|
||||
- Symfony-Admin-Governance
|
||||
|
||||
Er ist gebaut für produktiven, langfristigen Unternehmenseinsatz.
|
||||
368
TECHNICAL_ARCHITECTURE.md
Normal file
368
TECHNICAL_ARCHITECTURE.md
Normal file
@@ -0,0 +1,368 @@
|
||||
# TECHNICAL_ARCHITECTURE.md
|
||||
mitho AI Agent – Enterprise Hybrid RAG System
|
||||
Stand: Februar 2026
|
||||
|
||||
---
|
||||
|
||||
# 1. Zielsetzung
|
||||
|
||||
Diese Dokumentation beschreibt die vollständige technische Architektur des
|
||||
mitho AI Agent RAG-Systems.
|
||||
|
||||
Ziele:
|
||||
|
||||
- Deterministisches Retrieval
|
||||
- Governance-stabile Index-Struktur
|
||||
- Versionierte Wissensbasis
|
||||
- Reproduzierbare Builds
|
||||
- Keine inkrementellen Vektor-Mutationen
|
||||
- Job-basierte, asynchrone Ingest-Architektur
|
||||
- Skalierbarkeit >200k Chunks
|
||||
|
||||
---
|
||||
|
||||
# 2. Architektur-Übersicht
|
||||
|
||||
Systemebenen:
|
||||
|
||||
1. Admin Layer (Symfony)
|
||||
2. Ingest Layer
|
||||
3. Storage Layer (NDJSON)
|
||||
4. Vector Layer (FAISS)
|
||||
5. Retrieval Layer (Hybrid)
|
||||
6. Application Layer (LLM + SSE)
|
||||
|
||||
---
|
||||
|
||||
# 3. Core Architekturprinzipien
|
||||
|
||||
## 3.1 Determinismus
|
||||
|
||||
Gleiche Eingabe + gleiche Konfiguration → identisches Ergebnis.
|
||||
|
||||
- index.ndjson ist deterministisch
|
||||
- FAISS wird vollständig neu gebaut
|
||||
- Retrieval ist stabil reproduzierbar
|
||||
- Keine impliziten Indexveränderungen
|
||||
|
||||
## 3.2 Governance
|
||||
|
||||
- Genau eine aktive Version pro Dokument
|
||||
- Keine Inline-Rebuilds im HTTP-Request
|
||||
- Strukturänderungen erzwingen Global Reindex
|
||||
- Locking verhindert Parallel-Ingest
|
||||
|
||||
## 3.3 Skalierbarkeit
|
||||
|
||||
- NDJSON statt JSON-Array
|
||||
- Streaming-Append
|
||||
- Streaming-Compaction
|
||||
- Kein RAM-Full-Load
|
||||
|
||||
---
|
||||
|
||||
# 4. Domain Model
|
||||
|
||||
## 4.1 Document
|
||||
|
||||
Primäre Wissenseinheit.
|
||||
|
||||
Eigenschaften:
|
||||
- id (UUID)
|
||||
- title
|
||||
- createdAt
|
||||
- createdBy
|
||||
- archived (bool)
|
||||
- currentVersion (ManyToOne → DocumentVersion)
|
||||
|
||||
## 4.2 DocumentVersion
|
||||
|
||||
Immutable Inhaltsversion.
|
||||
|
||||
Eigenschaften:
|
||||
- id (UUID)
|
||||
- document (ManyToOne)
|
||||
- versionNumber
|
||||
- filePath
|
||||
- checksum
|
||||
- active (bool)
|
||||
- ingestStatus (PENDING, RUNNING, INDEXED, FAILED)
|
||||
|
||||
Regel:
|
||||
Nur eine Version pro Dokument darf active = true sein.
|
||||
|
||||
---
|
||||
|
||||
# 5. Ingest Architektur
|
||||
|
||||
## 5.1 Grundsatz
|
||||
|
||||
Kein Ingest läuft synchron im HTTP-Request.
|
||||
|
||||
Jede Indexänderung läuft über:
|
||||
|
||||
IngestJob → CLI Runner → IngestOrchestrator → IngestFlow
|
||||
|
||||
---
|
||||
|
||||
## 5.2 IngestJob
|
||||
|
||||
Entity mit:
|
||||
|
||||
- id
|
||||
- type
|
||||
- status
|
||||
- documentId
|
||||
- documentVersionId
|
||||
- startedAt
|
||||
- finishedAt
|
||||
- errorMessage
|
||||
|
||||
Job-Typen:
|
||||
|
||||
DOCUMENT_VERSION_ACTIVATE
|
||||
DOCUMENT
|
||||
GLOBAL_REINDEX
|
||||
|
||||
Status:
|
||||
|
||||
QUEUED
|
||||
RUNNING
|
||||
COMPLETED
|
||||
FAILED
|
||||
ABORTED
|
||||
|
||||
---
|
||||
|
||||
## 5.3 Job-Execution
|
||||
|
||||
Start:
|
||||
|
||||
php bin/console mto:agent:ingest:run <jobId>
|
||||
|
||||
Execution-Flow:
|
||||
|
||||
1. LockService.acquire()
|
||||
2. Job → RUNNING
|
||||
3. IngestFlow ausführen
|
||||
4. Job → COMPLETED / FAILED
|
||||
5. LockService.release()
|
||||
|
||||
---
|
||||
|
||||
# 6. IngestFlow Details
|
||||
|
||||
## 6.1 Local Ingest (Version aktivieren oder neue Datei)
|
||||
|
||||
Ablauf:
|
||||
|
||||
1. Extract (PDF/Text)
|
||||
2. Normalize
|
||||
3. Chunk deterministisch
|
||||
4. Streaming Compaction:
|
||||
- Entferne alle Chunks mit document_id
|
||||
5. Append neue Chunks
|
||||
6. Full FAISS Rebuild
|
||||
|
||||
Wichtig:
|
||||
Es werden immer alle alten Chunks des Dokuments entfernt.
|
||||
|
||||
---
|
||||
|
||||
## 6.2 Global Reindex
|
||||
|
||||
Wird ausgelöst bei:
|
||||
|
||||
- embedding_model Änderung
|
||||
- embedding_dimension Änderung
|
||||
- chunk_size Änderung
|
||||
- scoring_version Änderung
|
||||
- index_format Änderung
|
||||
|
||||
Ablauf:
|
||||
|
||||
1. Alle aktiven Versionen extrahieren
|
||||
2. Komplettes index.ndjson neu schreiben
|
||||
3. FAISS neu bauen
|
||||
4. index_version++
|
||||
|
||||
---
|
||||
|
||||
# 7. Storage Layer
|
||||
|
||||
## 7.1 index.ndjson
|
||||
|
||||
Single Source of Truth.
|
||||
|
||||
Eigenschaften:
|
||||
|
||||
- 1 JSON-Objekt pro Zeile
|
||||
- Streaming-lesbar
|
||||
- Append-only
|
||||
- Compaction by document_id
|
||||
|
||||
Beispiel:
|
||||
|
||||
{
|
||||
"chunk_id": "...",
|
||||
"document_id": "...",
|
||||
"document_version_id": "...",
|
||||
"text": "...",
|
||||
"meta": {...}
|
||||
}
|
||||
|
||||
---
|
||||
|
||||
## 7.2 index_meta.json
|
||||
|
||||
Enthält:
|
||||
|
||||
- index_version
|
||||
- embedding_model
|
||||
- embedding_dimension
|
||||
- chunk_size
|
||||
- chunk_overlap
|
||||
- scoring_version
|
||||
- index_format
|
||||
- vector_backend
|
||||
|
||||
Bei strukturellem Mismatch:
|
||||
→ Global Reindex zwingend.
|
||||
|
||||
---
|
||||
|
||||
# 8. Vector Layer (FAISS)
|
||||
|
||||
## 8.1 Build
|
||||
|
||||
vector_ingest.py:
|
||||
|
||||
- stream index.ndjson
|
||||
- Embeddings berechnen
|
||||
- FAISS IndexFlatIP bauen
|
||||
- vector.index schreiben
|
||||
- vector_meta.json schreiben
|
||||
|
||||
Immer vollständiger Rebuild.
|
||||
Keine Partial Updates.
|
||||
|
||||
## 8.2 Search
|
||||
|
||||
vector_search.py:
|
||||
|
||||
Input:
|
||||
- Query
|
||||
- Top-K
|
||||
|
||||
Output:
|
||||
- chunk_id
|
||||
- score
|
||||
|
||||
---
|
||||
|
||||
# 9. Hybrid Retrieval
|
||||
|
||||
Ablauf:
|
||||
|
||||
1. Keyword Retrieval (NDJSON Keyword Search)
|
||||
2. Vector Retrieval (FAISS)
|
||||
3. Score Fusion
|
||||
4. Chunk Lookup
|
||||
5. Context Builder
|
||||
6. Prompt Builder
|
||||
7. LLM
|
||||
|
||||
Keyword bleibt Primärsignal.
|
||||
Vector ergänzt semantische Nähe.
|
||||
|
||||
---
|
||||
|
||||
# 10. Locking
|
||||
|
||||
LockService schützt:
|
||||
|
||||
- NDJSON Mutationen
|
||||
- FAISS Rebuild
|
||||
- Global Reindex
|
||||
- Aktivierungs-Parallelität
|
||||
|
||||
Keine zwei Ingest-Jobs gleichzeitig erlaubt.
|
||||
|
||||
---
|
||||
|
||||
# 11. Admin Flows
|
||||
|
||||
## 11.1 Neue Datei hochladen
|
||||
|
||||
1. Document + Version 1 erstellen
|
||||
2. Version aktiv
|
||||
3. DOCUMENT_VERSION_ACTIVATE Job anlegen
|
||||
4. Async Runner starten
|
||||
5. Redirect auf Job-Seite
|
||||
|
||||
## 11.2 Version aktivieren
|
||||
|
||||
1. DB-Status ändern
|
||||
2. IngestStatus → PENDING
|
||||
3. DOCUMENT_VERSION_ACTIVATE Job anlegen
|
||||
4. Async Runner starten
|
||||
|
||||
## 11.3 Manuelles Ingest
|
||||
|
||||
1. DOCUMENT Job anlegen
|
||||
2. Async Runner starten
|
||||
|
||||
---
|
||||
|
||||
# 12. Error Handling
|
||||
|
||||
Typische Fehler:
|
||||
|
||||
- exec deaktiviert → Async Start nicht möglich
|
||||
- Lock aktiv → paralleler Ingest blockiert
|
||||
- index_meta mismatch → Reindex erforderlich
|
||||
- Vector-Dateien fehlen → Rebuild ausführen
|
||||
|
||||
---
|
||||
|
||||
# 13. Security & Stability
|
||||
|
||||
- Keine User-Uploads direkt ins Retrieval
|
||||
- Kein Self-Learning
|
||||
- Kein unkontrollierter Index-Mutate
|
||||
- Strict Separation:
|
||||
- Admin Layer
|
||||
- Ingest Layer
|
||||
- Retrieval Layer
|
||||
- LLM Layer
|
||||
|
||||
---
|
||||
|
||||
# 14. System Guarantees
|
||||
|
||||
Dieses System garantiert:
|
||||
|
||||
- Reproduzierbarkeit
|
||||
- Drift-Freiheit
|
||||
- Auditierbarkeit
|
||||
- Versionierte Wissensbasis
|
||||
- Deterministische Retrieval-Ergebnisse
|
||||
- Enterprise-taugliche Skalierbarkeit
|
||||
|
||||
---
|
||||
|
||||
# 15. Zusammenfassung
|
||||
|
||||
Das mitho AI Agent System ist eine:
|
||||
|
||||
- deterministische Hybrid-RAG Engine
|
||||
- NDJSON-basierte Wissensplattform
|
||||
- Full-Rebuild-FAISS Architektur
|
||||
- Job-basierte Ingest-Pipeline
|
||||
- Versionierte, governance-stabile Wissensstruktur
|
||||
|
||||
Keine Inline-Rebuilds.
|
||||
Keine inkrementellen Vektor-Updates.
|
||||
Keine impliziten Strukturänderungen.
|
||||
|
||||
Alles läuft kontrolliert über das Job-System.
|
||||
Reference in New Issue
Block a user