335 lines
5.4 KiB
Markdown
335 lines
5.4 KiB
Markdown
# 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.
|