294 lines
5.0 KiB
Markdown
294 lines
5.0 KiB
Markdown
# RAG System – CLI Command Reference
|
||
**Projektstand: rag.zip (aktueller Code-Stand)**
|
||
Namespace-Konvention: `mto:agent:*`
|
||
|
||
Diese Dokumentation beschreibt alle verfügbaren Symfony-Console-Commands des Systems inklusive Zweck, Einsatzszenario und typischer Aufrufe.
|
||
|
||
---
|
||
|
||
# 1. Agent / Chat
|
||
|
||
## `mto:agent:chat`
|
||
Interaktiver CLI-Chat mit dem Agenten.
|
||
|
||
**Zweck**
|
||
- Direkter Zugriff auf AgentRunner
|
||
- Streaming-Ausgabe im Terminal
|
||
- Nutzt vollständige Retrieval- und Prompt-Logik
|
||
|
||
**Start**
|
||
```bash
|
||
bin/console mto:agent:chat
|
||
```
|
||
|
||
**Eigenschaften**
|
||
- Streaming-first
|
||
- Think-Suppression wird im AgentRunner gesteuert
|
||
- Voller Kontext + Retrieval aktiv
|
||
|
||
---
|
||
|
||
# 2. Dokument-Ingest
|
||
|
||
## `mto:agent:ingest:version`
|
||
Ingest einer konkreten Dokumentversion.
|
||
|
||
**Zweck**
|
||
- Chunking
|
||
- NDJSON-Append / Compaction
|
||
- Vollständiger FAISS-Rebuild
|
||
- index_meta.json Update
|
||
|
||
**Beispiel**
|
||
```bash
|
||
bin/console mto:agent:ingest:version <documentVersionUuid>
|
||
```
|
||
|
||
---
|
||
|
||
## `mto:agent:ingest:run`
|
||
Führt einen einzelnen IngestJob aus.
|
||
|
||
**Zweck**
|
||
- Job-basierte Verarbeitung (QUEUE → RUNNING → COMPLETED/FAILED)
|
||
- Wird intern bei Aktivierung einer Dokumentversion verwendet
|
||
|
||
**Beispiel**
|
||
```bash
|
||
bin/console mto:agent:ingest:run <jobUuid>
|
||
```
|
||
|
||
---
|
||
|
||
## `mto:agent:vector:rebuild`
|
||
Erzwingt vollständigen Vector-Rebuild aus `index.ndjson`.
|
||
|
||
**Zweck**
|
||
- FAISS komplett neu aufbauen
|
||
- Kein Re-Chunking
|
||
- Reine Vektor-Neuerstellung
|
||
|
||
```bash
|
||
bin/console mto:agent:vector:rebuild
|
||
```
|
||
|
||
---
|
||
|
||
# 3. Vector Service (Python / FastAPI)
|
||
|
||
## `mto:agent:vector:control`
|
||
Steuert den persistenten Python-Vector-Service.
|
||
|
||
**Beschreibung**
|
||
Production-sicheres Management des uvicorn-FastAPI-Dienstes.
|
||
|
||
### Optionen
|
||
|
||
| Option | Beschreibung |
|
||
|--------|--------------|
|
||
| `--install` | Fehlende Python-Dependencies installieren |
|
||
| `--start` | Service starten |
|
||
| `--stop` | Service stoppen |
|
||
| `--force` | Hard-Stop (SIGKILL) |
|
||
| `--reload` | /reload Trigger |
|
||
| `--status` | Status anzeigen |
|
||
| `--foreground` | Vordergrundstart |
|
||
| `--port=8090` | Port |
|
||
| `--host=0.0.0.0` | Host |
|
||
|
||
### Beispiele
|
||
|
||
Installieren:
|
||
```bash
|
||
bin/console mto:agent:vector:control --install
|
||
```
|
||
|
||
Starten:
|
||
```bash
|
||
bin/console mto:agent:vector:control --start
|
||
```
|
||
|
||
Status:
|
||
```bash
|
||
bin/console mto:agent:vector:control --status
|
||
```
|
||
|
||
Reload:
|
||
```bash
|
||
bin/console mto:agent:vector:control --reload
|
||
```
|
||
|
||
---
|
||
|
||
## `mto:agent:vector:health`
|
||
Gesundheitscheck von:
|
||
|
||
- index.ndjson
|
||
- vector.index
|
||
- index_meta.json
|
||
- Embedding-Dimensionen
|
||
- Konsistenz
|
||
|
||
```bash
|
||
bin/console mto:agent:vector:health
|
||
```
|
||
|
||
Ausgabe erfolgt als JSON.
|
||
|
||
---
|
||
|
||
## `mto:agent:test-vector`
|
||
Testet direkte Vector-Suche.
|
||
|
||
```bash
|
||
bin/console mto:agent:test-vector "Suchanfrage"
|
||
```
|
||
|
||
---
|
||
|
||
# 4. Tag-System
|
||
|
||
## `mto:agent:tags:export`
|
||
Exportiert alle Tags in `tags.ndjson`.
|
||
|
||
**Zweck**
|
||
- Grundlage für tag-basiertes Routing
|
||
- Keine Vector-Erstellung
|
||
|
||
```bash
|
||
bin/console mto:agent:tags:export
|
||
```
|
||
|
||
---
|
||
|
||
## `mto:agent:tags:rebuild`
|
||
Vollständiger Tag-Rebuild:
|
||
|
||
1. Export `tags.ndjson`
|
||
2. Erstellen von `vector_tags.index`
|
||
3. index_meta.json Update
|
||
|
||
```bash
|
||
bin/console mto:agent:tags:rebuild
|
||
```
|
||
|
||
---
|
||
|
||
## `mto:agent:tags:job:run`
|
||
Führt einen einzelnen TagRebuildJob aus.
|
||
|
||
**Mit Lock-Mechanismus.**
|
||
|
||
```bash
|
||
bin/console mto:agent:tags:job:run <jobUuid>
|
||
```
|
||
|
||
---
|
||
|
||
# 5. User-Management
|
||
|
||
## `mto:agent:user:create`
|
||
Erstellt einen neuen Admin-User.
|
||
|
||
Interaktiver Ablauf:
|
||
- E-Mail
|
||
- Passwort
|
||
- Rollenwahl
|
||
|
||
```bash
|
||
bin/console mto:agent:user:create
|
||
```
|
||
|
||
---
|
||
|
||
# 6. Architektur-Zusammenhang der Commands
|
||
|
||
| Bereich | Command-Typ |
|
||
|----------|------------|
|
||
| Dokumente | ingest:version |
|
||
| Jobs | ingest:run |
|
||
| Vector Index | vector:rebuild |
|
||
| Vector Service | vector:control |
|
||
| Vector Health | vector:health |
|
||
| Tag Export | tags:export |
|
||
| Tag Rebuild | tags:rebuild |
|
||
| Tag Job | tags:job:run |
|
||
| Agent CLI | chat |
|
||
| User | user:create |
|
||
|
||
---
|
||
|
||
# 7. Typischer Produktions-Workflow
|
||
|
||
### 1️⃣ Dokument aktivieren
|
||
→ erzeugt IngestJob
|
||
|
||
### 2️⃣ Job ausführen
|
||
```bash
|
||
bin/console mto:agent:ingest:run <jobUuid>
|
||
```
|
||
|
||
### 3️⃣ Vector-Service prüfen
|
||
```bash
|
||
bin/console mto:agent:vector:health
|
||
```
|
||
|
||
### 4️⃣ Optional: Service reload
|
||
```bash
|
||
bin/console mto:agent:vector:control --reload
|
||
```
|
||
|
||
---
|
||
|
||
# 8. System-Ebenen
|
||
|
||
| Ebene | Technologie |
|
||
|--------|------------|
|
||
| Symfony | PHP / Doctrine |
|
||
| Retrieval | NDJSON + FAISS |
|
||
| Vector Service | Python FastAPI |
|
||
| Persistence | index.ndjson |
|
||
| Governance | index_meta.json |
|
||
| Streaming | SSE |
|
||
| CLI | Symfony Console |
|
||
|
||
---
|
||
|
||
# 9. Wichtige Dateien (Runtime)
|
||
|
||
```
|
||
var/
|
||
├── run/
|
||
│ └── vector.pid
|
||
├── index.ndjson
|
||
├── index_meta.json
|
||
├── vector.index
|
||
└── vector_tags.index
|
||
```
|
||
|
||
---
|
||
|
||
# 10. Sicherheit & Locks
|
||
|
||
- IngestFlow schützt mit LockService
|
||
- Tag-Rebuild verwendet File-Lock
|
||
- Vector-Service PID-basiert
|
||
- Global Rebuild atomar via `.tmp` + rename()
|
||
|
||
---
|
||
|
||
# 11. Empfohlene Admin-Checks
|
||
|
||
Regelmäßig ausführen:
|
||
|
||
```bash
|
||
bin/console mto:agent:vector:health
|
||
```
|
||
|
||
Bei Änderungen am Embedding-Modell:
|
||
→ vollständiger Rebuild
|
||
|
||
---
|
||
|
||
# Ende der Command-Dokumentation
|
||
System-Stand: rag.zip (aktueller Projektzustand) |