add new md files
This commit is contained in:
team 1
596
README.md
596
README.md
@@ -1,430 +1,314 @@
|
|||||||
# mitho AI Agent – Developer Deep Dive
|
# mitho AI Agent – Developer README
|
||||||
|
|
||||||
Enterprise Hybrid RAG System (Symfony + NDJSON + FAISS)
|
Enterprise Hybrid RAG System (Symfony + NDJSON + FAISS)
|
||||||
|
|
||||||
---
|
Stand: Februar 2026
|
||||||
|
Status: Produktiv stabil – Job-basierte Ingest-Architektur vollständig integriert
|
||||||
# 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`.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
# 2. High-Level Architecture
|
# 1. Systemüberblick
|
||||||
|
|
||||||
User Query
|
Dieses System implementiert eine deterministische, governance-stabile
|
||||||
→ Hybrid Retrieval
|
Hybrid-RAG-Architektur mit:
|
||||||
→ Context Assembly
|
|
||||||
→ Prompt Builder
|
|
||||||
→ LLM
|
|
||||||
→ Streaming Response (SSE)
|
|
||||||
|
|
||||||
Knowledge Flow:
|
- Symfony (PHP Backend)
|
||||||
Document → Version → Extract → Chunk → NDJSON → FAISS → Retrieval
|
- 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
|
||||||
|
|
||||||
```
|
Determinismus:
|
||||||
var/knowledge/
|
- Gleiche Dokumente + gleiche Konfiguration → identisches index.ndjson
|
||||||
├── uploads/
|
- Gleiches index.ndjson → identisches FAISS
|
||||||
├── chunks/
|
- Gleiche Query → identisches Retrieval-Ergebnis
|
||||||
├── index.ndjson
|
|
||||||
├── index_meta.json
|
Governance:
|
||||||
├── vector.index
|
- Eine aktive Version pro Dokument
|
||||||
└── vector_meta.json
|
- 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
|
Single Source of Truth.
|
||||||
- One JSON object per line
|
|
||||||
- Streaming-readable
|
|
||||||
- No JSON array wrapper
|
|
||||||
- Scales beyond 200k chunks
|
|
||||||
|
|
||||||
Each line contains:
|
- 1 JSON-Objekt pro Zeile
|
||||||
|
- Streaming-Append
|
||||||
|
- Deterministische Compaction by document_id
|
||||||
|
|
||||||
|
Beispielstruktur:
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
{
|
||||||
"chunk_id": "uuid",
|
"chunk_id": "uuid",
|
||||||
"document_id": "uuid",
|
"document_id": "uuid",
|
||||||
"version": 3,
|
"document_version_id": "uuid",
|
||||||
"text": "...",
|
"text": "...",
|
||||||
"meta": { ... }
|
"meta": {...}
|
||||||
}
|
}
|
||||||
```
|
|
||||||
|
|
||||||
NDJSON enables:
|
Keine JSON-Array-Datei.
|
||||||
- Append-based writes
|
Keine Mutation einzelner Chunks.
|
||||||
- Compaction per document
|
Nur Append + deterministische Entfernung per document_id.
|
||||||
- Memory-safe streaming
|
|
||||||
- Deterministic rebuilds
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
# 5. Index Metadata
|
## 3.2 index_meta.json
|
||||||
|
|
||||||
## index_meta.json
|
Enthält Strukturparameter:
|
||||||
|
|
||||||
Managed by:
|
|
||||||
|
|
||||||
- IndexMetaManager
|
|
||||||
- IndexConfiguration
|
|
||||||
|
|
||||||
Contains:
|
|
||||||
|
|
||||||
- index_version
|
- index_version
|
||||||
- embedding_model
|
- embedding_model
|
||||||
- embedding_dimension
|
- embedding_dimension
|
||||||
- chunk_size
|
- chunk_size
|
||||||
- overlap
|
- chunk_overlap
|
||||||
- scoring_version
|
- scoring_version
|
||||||
- index_format
|
- index_format
|
||||||
|
- vector_backend
|
||||||
|
|
||||||
If configuration changes → Global Reindex required.
|
Wenn einer dieser Werte sich ändert:
|
||||||
|
→ Global Reindex zwingend erforderlich.
|
||||||
Guarded by:
|
|
||||||
`IndexStructureChangedException`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
# 6. Ingest Pipeline
|
## 3.3 FAISS
|
||||||
|
|
||||||
## 6.1 Core Services
|
Dateien:
|
||||||
|
|
||||||
| Service | Responsibility |
|
- vector.index
|
||||||
|----------|----------------|
|
- vector_meta.json (Chunk-ID Mapping)
|
||||||
| DocumentService | Document lifecycle |
|
|
||||||
| DocumentVersionRepository | Version persistence |
|
FAISS wird IMMER vollständig aus index.ndjson gebaut.
|
||||||
| KnowledgeIngestService | Chunk generation |
|
Keine Partial Updates.
|
||||||
| 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 |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 6.2 Local Ingest
|
# 4. Dokument- & Versionsmodell
|
||||||
|
|
||||||
Used when:
|
Document
|
||||||
- A single document version changes
|
→ enthält mehrere DocumentVersion
|
||||||
|
→ genau eine Version ist aktiv
|
||||||
|
|
||||||
Process:
|
Regel:
|
||||||
|
Es darf immer nur eine aktive Version pro Dokument existieren.
|
||||||
|
|
||||||
1. Extract document
|
Beim Aktivieren einer Version:
|
||||||
2. Normalize text
|
- Alle anderen Versionen werden inaktiv
|
||||||
3. Chunk deterministically
|
- IngestStatus → PENDING
|
||||||
4. Remove previous chunks of document_id
|
- Re-Ingest via Job
|
||||||
5. Append new chunks to index.ndjson
|
|
||||||
6. Rebuild FAISS completely
|
|
||||||
|
|
||||||
index_version does NOT change.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 6.3 Global Reindex
|
# 5. Ingest-Architektur (vollständig Job-basiert)
|
||||||
|
|
||||||
Used when:
|
Ingest läuft NIEMALS synchron im HTTP-Request.
|
||||||
- Embedding model changes
|
|
||||||
- Chunk size changes
|
|
||||||
- Overlap changes
|
|
||||||
- Scoring logic changes
|
|
||||||
- index_format changes
|
|
||||||
|
|
||||||
Process:
|
Jede Mutation am Index läuft über:
|
||||||
|
|
||||||
1. Re-extract all active document versions
|
IngestJob → CLI Runner → IngestOrchestrator → IngestFlow
|
||||||
2. Recreate full index.ndjson
|
|
||||||
3. Rebuild FAISS
|
---
|
||||||
|
|
||||||
|
## 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++
|
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. Hybrid Retrieval
|
||||||
|
|
||||||
## 8.1 Components
|
Ablauf:
|
||||||
|
|
||||||
| Class | Role |
|
User Query
|
||||||
|--------|------|
|
→ Keyword Retrieval
|
||||||
| NdjsonHybridRetriever | Orchestrator |
|
→ FAISS Vector Retrieval
|
||||||
| NdjsonKeywordSearch | Keyword scoring |
|
→ Score Fusion
|
||||||
| NdjsonChunkLookup | Chunk resolution |
|
→ NDJSON Chunk Lookup
|
||||||
| VectorSearchClient | Vector bridge |
|
→ Context Builder
|
||||||
| CachedRetriever | Cache layer |
|
→ LLM
|
||||||
|
→ SSE Streaming
|
||||||
|
|
||||||
|
Keyword ist Primärsignal.
|
||||||
|
Vector ergänzt Semantik.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 8.2 Retrieval Flow
|
# 9. Locking & Concurrency
|
||||||
|
|
||||||
1. Extract terms (StopWords + normalization)
|
LockService verhindert:
|
||||||
2. Keyword scoring
|
|
||||||
3. Vector search
|
|
||||||
4. Score fusion
|
|
||||||
5. Limit to N chunks
|
|
||||||
6. Resolve chunk text
|
|
||||||
7. Build LLM context
|
|
||||||
|
|
||||||
Keyword score remains primary signal.
|
- parallelen Ingest
|
||||||
Vector score augments semantic similarity.
|
- 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
|
Alle Commands unter:
|
||||||
- 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:
|
|
||||||
|
|
||||||
```
|
|
||||||
mto:agent:*
|
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