add new guide files
This commit is contained in:
team2
294
COMMAND_REF.md
Normal file
294
COMMAND_REF.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user