marek/MtoRagSystem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
56617f2612a3841369903adee0abfd96126b6def
MtoRagSystem/README.md
team2 06376e0fb4 optimize py control service
2026-02-22 09:00:06 +01:00

6.5 KiB
Raw Blame History

mitho AI Agent – Developer README

Enterprise Hybrid RAG System (Symfony + NDJSON + FAISS + Persistent Vector Service)

Stand: Februar 2026
Status: Produktiv stabil – Job-basierte Ingest-Architektur + Persistenter Vector-Service integriert

1. Systemüberblick

Dieses System implementiert eine deterministische, governance-stabile
Hybrid-RAG-Architektur mit:

  • Symfony (PHP Backend)
  • NDJSON als Single Source of Truth
  • FAISS als Vektorindex (immer Full Rebuild)
  • Persistenter Python Vector-Service (FastAPI + Uvicorn)
  • 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
  • Retrieval läuft über einen persistenten Service (kein Python-Spawn pro Anfrage)

2. Architekturprinzipien

2.1 Determinismus

  • Gleiche Dokumente + gleiche Konfiguration → identisches index.ndjson
  • Gleiches index.ndjson → identisches FAISS
  • Gleiche Query → identisches Retrieval-Ergebnis

2.2 Governance

  • Eine aktive Version pro Dokument
  • Keine impliziten Index-Änderungen
  • Strukturänderungen erzwingen Global Reindex
  • Keine Selbstmodifikation durch KI

2.3 Skalierbarkeit

  • NDJSON (streamingfähig)
  • Kein RAM-basiertes JSON-Array
  • Zielgröße > 200k Chunks
  • FAISS Full Rebuild ist deterministisch

3. Wissensspeicher

3.1 index.ndjson

Single Source of Truth.

  • 1 JSON-Objekt pro Zeile
  • Streaming-Append
  • Deterministische Compaction by document_id

Beispielstruktur:

{
  "chunk_id": "uuid",
  "document_id": "uuid",
  "document_version_id": "uuid",
  "text": "...",
  "meta": { ... }
}

Regeln:

  • Keine JSON-Array-Datei
  • Keine Mutation einzelner Chunks
  • Nur Append + deterministische Entfernung per document_id

3.2 index_meta.json

Strukturparameter:

  • index_version
  • embedding_model
  • embedding_dimension
  • chunk_size
  • chunk_overlap
  • scoring_version
  • index_format
  • vector_backend

Wenn einer dieser Werte sich ändert:

→ Global Reindex zwingend erforderlich

3.3 FAISS

Dateien:

  • vector.index
  • vector.index.meta.json
  • vector_tags.index
  • vector_tags.index.meta.json

FAISS wird IMMER vollständig aus index.ndjson gebaut.

Keine Partial Updates.
Kein inkrementelles Vector-Append.

4. Persistenter Vector-Service

Retrieval läuft nicht mehr über:

  • Symfony Process
  • exec()
  • python vector_search.py pro Anfrage

Sondern über:

FastAPI + Uvicorn (persistent im RAM)

4.1 Eigenschaften

Beim Start lädt der Service:

  • Embedding-Modell
  • Chunk-Index
  • Tag-Index
  • ID-Mappings

Diese bleiben dauerhaft im RAM.

Kein Modell-Reload pro Anfrage.
Kein Disk-Reload pro Anfrage.
Kein Python-Spawn pro Anfrage.

4.2 Endpoints

  • GET /health
  • POST /search-chunks
  • POST /search-tags
  • POST /reload

4.3 Reload-Mechanismus

Nach Global Reindex:

curl -X POST http://127.0.0.1:8090/reload

Lädt:

  • Chunk-Index neu
  • Tag-Index neu
  • Modell nur wenn embedding_model geändert wurde

Kein Neustart nötig.
Keine Downtime.

5. Score-Gates (Routing-Sicherheit)

5.1 Tag-Gate

Tags steuern Routing.

Empfohlener Mindestscore:

MIN_SCORE ≈ 0.70

Schützt vor:

  • zufälligen semantischen Treffern
  • falschem Dokumentrouting

5.2 Chunk-Gate

Chunks sind Kontext.

Weicher Gate:

MIN_SCORE ≈ 0.50

Optional: relativer Score zum besten Treffer.

6. Dokument- & Versionsmodell

Document
→ enthält mehrere DocumentVersion
→ genau eine Version ist aktiv

Regel:

Es darf immer nur eine aktive Version pro Dokument existieren.

Beim Aktivieren einer Version:

  • Alle anderen Versionen werden inaktiv
  • IngestStatus → PENDING
  • Re-Ingest via Job

7. Ingest-Architektur (vollständig Job-basiert)

Ingest läuft NIEMALS synchron im HTTP-Request.

Jede Mutation am Index läuft über:

IngestJob → CLI Runner → IngestOrchestrator → IngestFlow

7.1 Job-Typen

  • DOCUMENT_VERSION_ACTIVATE
  • DOCUMENT
  • GLOBAL_REINDEX

7.2 Job-Status

  • QUEUED
  • RUNNING
  • COMPLETED
  • FAILED
  • ABORTED

CLI-Ausführung:

php bin/console mto:agent:ingest:run <jobId>

8. Hybrid Retrieval

Flow:

User Query
→ Keyword Retrieval
→ Tag Vector Search
→ Dokumentfilter
→ Chunk Vector Retrieval
→ Score Fusion
→ NDJSON Lookup
→ Context Builder
→ LLM
→ SSE Streaming

Keyword bleibt Primärsignal.
Vector ergänzt Semantik.

9. Locking & Concurrency

LockService verhindert:

  • parallelen Ingest
  • gleichzeitige Reindex-Vorgänge
  • NDJSON-Korruption

Keine gleichzeitigen Mutationen erlaubt.

10. Vector Control (Production Safe)

Ein zentrales Kommando steuert:

  • Dependency-Check
  • Auto-Install (opt-in)
  • Service Start
  • Service Stop
  • Reload
  • Status
  • Health-Check
  • PID-Management

Command

mto:agent:vector:control

Beispiele

Status:

bin/console mto:agent:vector:control

Install + Start:

bin/console mto:agent:vector:control --install --start

Stop:

bin/console mto:agent:vector:control --stop

Reload:

bin/console mto:agent:vector:control --reload

Production-Safety

  • PID-File unter var/run/vector_service.pid
  • SIGTERM Stop mit Timeout
  • Optional SIGKILL (--force)
  • Health-Check mit Retry-Mechanismus
  • Kein automatisches Install ohne Flag

11. CLI Commands

  • mto:agent:ingest:run <jobId>
  • mto:agent:vector:control
  • mto:agent:test
  • mto:agent:chat

Alle Commands unter:

mto:agent:*

12. Failure Modes

Vector Service nicht erreichbar
→ vector:control --start

Reload Endpoint fehlt
→ falsche Service-Version

index_meta mismatch
→ Global Reindex

Lock aktiv
→ Parallel-Ingest blockiert

13. Non-Goals

  • Kein Online-Learning
  • Keine inkrementellen FAISS Updates
  • Keine selbstverändernden Prompts
  • Kein Auto-Merging von Chunks
  • Kein Vector-Append im Runtime

Strukturänderungen → explizit + Reindex.

14. Zusammenfassung

Dieses System ist:

  • deterministisch
  • reproduzierbar
  • drift-sicher
  • governance-stabil
  • enterprise-ready
  • job-basiert
  • versionssicher
  • persistent im Retrieval
  • ohne Spawn-Overhead
  • reload-fähig ohne Downtime

Wichtige Neuerungen:

  • Persistenter Vector-Service ersetzt CLI-Spawn
  • Score-Gates verhindern falsches Routing
  • Reload-Endpoint vermeidet Neustarts
  • Production-Safe Control Command integriert
  • Vollständige Trennung von Ingest und Runtime
Reference in New Issue View Git Blame Copy Permalink