marek/MtoRagSystem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update .md

Browse Source
This commit is contained in:
team 1
2026-05-11 19:16:51 +02:00
parent f79062c336
commit a01ca045dc
3 changed files with 1080 additions and 1194 deletions
Download Patch File Download Diff File Expand all files Collapse all files

709
COMMAND_REF.md
View File

@@ -1,449 +1,646 @@
# RetrieX – CLI Command Reference # RetrieX v1.6.0 – CLI Command Reference
**Basis:** `rag.zip` (aktueller Code-Stand vom 2026-04-15) Basis: aktueller `rag-inprogress.zip`-Stand der Version **1.6.0**.
**Scope:** ausschließlich projektspezifische Symfony-Commands unter `src/Command` Scope: projektspezifische Symfony-Commands unter `src/Command`.
**Namespace-Konvention:** `mto:agent:*` Namespace-Konvention: `mto:agent:*`.
Diese Referenz ist gegen den realen Codebestand abgeglichen und ersetzt die veraltete Fassung der bisherigen `COMMAND_REF.md`. Diese Referenz ist gegen die real vorhandenen Command-Klassen im Paket abgeglichen.
--- ---
## 1. Überblick ## 1. Überblick
| Command | Bereich | Kurzbeschreibung | | Command | Bereich | Kurzbeschreibung |
|---|---|---| | --- | --- | --- |
| `mto:agent:chat` | Agent / CLI | Interaktiver Terminal-Chat gegen den AgentRunner | | `mto:agent:chat` | Agent / CLI | Interaktiver Terminal-Chat gegen den `AgentRunner` |
| `mto:agent:ingest:version` | Ingest | Startet einen Ingest für eine konkrete Dokumentversion | | `mto:agent:eval:run` | Evaluation | Führt versionierte Eval-Cases aus |
| `mto:agent:ingest:version` | Ingest | Startet den Ingest für eine konkrete Dokumentversion |
| `mto:agent:ingest:run` | Ingest Jobs | Führt einen vorhandenen `IngestJob` aus | | `mto:agent:ingest:run` | Ingest Jobs | Führt einen vorhandenen `IngestJob` aus |
| `mto:agent:system:rebuild` | System | Globaler Hard-Rebuild von Chunks, Vektorindex, Tags und optional Service-Reload | | `mto:agent:system:rebuild` | System | Globaler Hard-Rebuild von Knowledge-, Vector- und optional Tag-Artefakten |
| `mto:agent:vector:rebuild` | Vector | Baut den Chunk-Vektorindex aus `index.ndjson` neu |
| `mto:agent:vector:control` | Vector Service | Install, Start, Stop, Reload und Status des Python-Vector-Service |
| `mto:agent:vector:health` | Vector | Konsistenzcheck für Chunk-NDJSON und Vektorindex |
| `mto:agent:test-vector` | Debug | Testet Tag- und Chunk-Vector-Clients direkt |
| `mto:agent:retrieval:test` | Retrieval Debug | Testet den realen hybriden Retrieval-Pfad mit Debugausgabe |
| `mto:agent:tags:export` | Tags | Exportiert Tags nach `tags.ndjson` |
| `mto:agent:tags:rebuild` | Tags | Exportiert Tags und baut `vector_tags.index` neu |
| `mto:agent:tags:job:run` | Tag Jobs | Führt einen vorhandenen Tag-Rebuild-Job aus oder erstellt direkt einen neuen |
| `mto:agent:tag:health` | Tags | Konsistenzcheck für Tag-NDJSON und Tag-Vektorindex |
| `mto:agent:test:shop-search` | Commerce / Debug | Testkommando für Shopware-Suche und optional Search Repair |
| `mto:agent:user:create` | User | Interaktive Anlage eines Users |
| `mto:agent:config:validate` | Config / Governance | Validiert die effektive RetrieX-Konfiguration | | `mto:agent:config:validate` | Config / Governance | Validiert die effektive RetrieX-Konfiguration |
| `mto:agent:config:audit-source` | Config / Governance | Auditiert YAML-Mappings gegen PHP-Fallbacks und Defaults | | `mto:agent:config:audit-source` | Config / Governance | Auditiert YAML-Mappings gegen PHP-Fallbacks und Defaults |
| `mto:agent:config:audit-patterns` | Config / Governance | Auditiert fachliche Pattern-, Token- und Signalreste im PHP-Core | | `mto:agent:config:audit-patterns` | Config / Governance | Auditiert fachliche Pattern-, Token- und Signalreste im PHP-Core |
| `mto:agent:config:dump-effective` | Config / Governance | Gibt die effektive Konfigurationsinventur aus | | `mto:agent:config:dump-effective` | Config / Governance | Gibt die effektive Konfigurationsinventur aus |
| `mto:agent:regression:test` | Config / Governance | Fuehrt Offline-Regression-Guards fuer stabile Pfade aus | | `mto:agent:regression:test` | Config / Governance | Führt Offline-Regression-Guards für stabile Pfade aus |
| `mto:agent:vector:rebuild` | Vector | Baut den Chunk-Vektorindex aus `index.ndjson` neu |
| `mto:agent:vector:control` | Vector Service | Install, Start, Stop, Reload und Status des Python-Vector-Service |
| `mto:agent:vector:health` | Vector | Konsistenzcheck für Chunk-NDJSON und Vektorindex |
| `mto:agent:test-vector` | Debug | Führt Tag-Routing und Chunk-Retrieval für einen Testprompt aus |
| `mto:agent:tags:export` | Tags | Exportiert Tags nach `tags.ndjson` |
| `mto:agent:tags:rebuild` | Tags | Exportiert Tags und baut `vector_tags.index` neu |
| `mto:agent:tags:job:run` | Tag Jobs | Führt einen vorhandenen Tag-Rebuild-Job aus oder erstellt direkt einen neuen |
| `mto:agent:tag:health` | Tags | Konsistenzcheck für `tags.ndjson` und Tag-Vektorindex |
| `mto:agent:test:shop-search` | Commerce / Debug | Testkommando für die Shopware-Suche |
| `mto:agent:user:create` | User | Interaktive Anlage eines Users |
--- ---
## 2. Agent / Chat ## 2. Agent / Chat
### `mto:agent:chat` ### `mto:agent:chat`
Interaktiver CLI-Chat mit dem Agenten. Interaktiver CLI-Chat mit dem Agenten.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:chat [user-id] php bin/console mto:agent:chat [user-id]
``` ```
**Argumente** **Argumente**
- `user-id` optional, Default: `cli`
**Reales Verhalten im Code** - `user-id` optional, Default `cli`
**Reales Verhalten**
- startet eine Terminal-Schleife mit `Question` → `Answer` - startet eine Terminal-Schleife mit `Question` → `Answer`
- ruft pro Eingabe `AgentRunner->run($prompt, $userId)` auf - ruft pro Eingabe `AgentRunner->run($prompt, $userId)` auf
- streamt Tokens direkt ins Terminal - streamt Tokens direkt ins Terminal
- beendet sich bei EOF, leerer Eingabe oder `exit` - beendet sich bei EOF, leerer Eingabe oder `exit`
**Beispiel** **Beispiele**
```bash ```bash
bin/console mto:agent:chat php bin/console mto:agent:chat
bin/console mto:agent:chat admin-debug php bin/console mto:agent:chat cli-debug
``` ```
--- ---
## 3. Ingest / Jobs ## 3. Evaluation
### `mto:agent:eval:run`
Führt versionierte Eval-Cases aus.
**Signatur**
```bash
php bin/console mto:agent:eval:run [type] [--case=CASE_ID] [--json] [--no-write]
```
**Argumente / Optionen**
- `type` optional, Default `retrieval`
- `--case=CASE_ID` führt nur einen einzelnen Case aus
- `--json` gibt den vollständigen Report als JSON aus
- `--no-write` verhindert das Schreiben des Report-Files
**Reales Verhalten**
- lädt Cases über `EvalCaseLoader`
- filtert optional auf eine Case-ID
- führt Cases über `AgentEvalRunner` aus
- schreibt standardmäßig einen Report über `EvalReportWriter`
- Exit-Code ist fehlerhaft, wenn mindestens ein Case fehlschlägt
**Beispiele**
```bash
php bin/console mto:agent:eval:run
php bin/console mto:agent:eval:run retrieval --case=water-hardness-lowest
php bin/console mto:agent:eval:run retrieval --json --no-write
```
---
## 4. Ingest / Jobs
### `mto:agent:ingest:version` ### `mto:agent:ingest:version`
Startet einen Ingest für eine konkrete `DocumentVersion` mit explizitem Benutzerkontext. Startet einen Ingest für eine konkrete `DocumentVersion` mit explizitem Benutzerkontext.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:ingest:version <versionId> <userId> php bin/console mto:agent:ingest:version <versionId> <userId>
``` ```
**Argumente** **Argumente**
- `versionId` erforderlich, UUID einer `DocumentVersion` - `versionId` erforderlich, UUID einer `DocumentVersion`
- `userId` erforderlich, UUID des auslösenden Users - `userId` erforderlich, UUID des auslösenden Users
**Reales Verhalten im Code** **Reales Verhalten**
- lädt `DocumentVersion` und `User` aus Doctrine - lädt `DocumentVersion` und `User` aus Doctrine
- bricht mit Fehler ab, wenn Version oder User nicht existieren - bricht ab, wenn Version oder User nicht existieren
- ruft `IngestOrchestrator->runForVersion($version, $user)` auf - ruft `IngestOrchestrator->runForVersion($version, $user)` auf
- gibt nach Abschluss die erzeugte Job-ID aus - gibt nach Abschluss die erzeugte Job-ID aus
**Beispiel** **Beispiel**
```bash ```bash
bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid> php bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
``` ```
**Wichtige Korrektur zur alten Doku**
Die bisherige Referenz dokumentierte nur einen Parameter. Im aktuellen Code sind **zwei Pflichtargumente** erforderlich.
---
### `mto:agent:ingest:run` ### `mto:agent:ingest:run`
Führt einen bereits existierenden `IngestJob` aus. Führt einen bereits existierenden `IngestJob` aus.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:ingest:run <jobId> [--dry-run] php bin/console mto:agent:ingest:run <jobId> [--dry-run]
``` ```
**Argumente / Optionen** **Argumente / Optionen**
- `jobId` erforderlich, UUID eines `IngestJob`
- `--dry-run` optional, simuliert schwere Operationen ohne tatsächliche Ausführung
**Reales Verhalten im Code** - `jobId` erforderlich, UUID eines `IngestJob`
- `--dry-run` simuliert schwere Operationen ohne tatsächliche Ausführung
**Reales Verhalten**
- lädt den Job aus der Datenbank - lädt den Job aus der Datenbank
- bricht mit Fehler ab, wenn der Job nicht gefunden wird
- beendet sich erfolgreich, wenn der Job bereits terminal ist (`COMPLETED`, `FAILED`, `ABORTED`) - beendet sich erfolgreich, wenn der Job bereits terminal ist (`COMPLETED`, `FAILED`, `ABORTED`)
- ruft sonst `IngestOrchestrator->runExistingJob($job, $dryRun)` auf - ruft sonst `IngestOrchestrator->runExistingJob($job, $dryRun)` auf
**Beispiele** **Beispiele**
```bash ```bash
bin/console mto:agent:ingest:run <jobUuid> php bin/console mto:agent:ingest:run <jobUuid>
bin/console mto:agent:ingest:run <jobUuid> --dry-run php bin/console mto:agent:ingest:run <jobUuid> --dry-run
``` ```
---
### `mto:agent:system:rebuild` ### `mto:agent:system:rebuild`
Globaler Hard-Rebuild des Systems. Globaler Hard-Rebuild des Systems.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:system:rebuild --hard [--no-tags] [--no-reload] [--no-health] [--dry-run] php bin/console mto:agent:system:rebuild --hard [--no-tags] [--no-reload] [--no-health] [--dry-run]
``` ```
**Optionen** **Optionen**
- `--hard` **Pflicht-Sicherheitsschalter**; ohne diese Option bricht das Kommando ab
- `--no-tags` überspringt den Tag-Rebuild
- `--no-reload` überspringt Reload/Start des Vector-Service
- `--no-health` überspringt den abschließenden Health-Check
- `--dry-run` simuliert den Reindex ohne Schreiboperationen
**Reales Verhalten im Code** - `--hard` Pflicht-Sicherheitsschalter; ohne diese Option bricht das Kommando ab
1. erzeugt einen neuen `IngestJob` vom Typ `GLOBAL_REINDEX` - `--no-tags` überspringt Tag-Rebuild
- `--no-reload` überspringt Reload/Start des Vector-Service
- `--no-health` überspringt abschließende Health-Checks
- `--dry-run` simuliert Schritte ohne Schreiboperationen
**Reales Verhalten**
1. erzeugt einen globalen Reindex-Job
2. führt den globalen Reindex über den Orchestrator aus 2. führt den globalen Reindex über den Orchestrator aus
3. exportiert optional `tags.ndjson` und baut `vector_tags.index` neu 3. exportiert optional Tags und baut `vector_tags.index` neu
4. startet bzw. reloadet optional den Python-Vector-Service 4. startet oder reloadet optional den Python-Vector-Service
5. führt optional Chunk- und Tag-Health-Checks aus 5. führt optional Chunk- und Tag-Health-Checks aus
**Beispiele** **Beispiele**
```bash
bin/console mto:agent:system:rebuild --hard
bin/console mto:agent:system:rebuild --hard --dry-run
bin/console mto:agent:system:rebuild --hard --no-tags --no-reload
```
**Hinweis** ```bash
Dieses Kommando ist aktuell der zentrale Produktions-Entry-Point für einen vollständigen Neuaufbau des Retrieval-Stacks. php bin/console mto:agent:system:rebuild --hard
php bin/console mto:agent:system:rebuild --hard --dry-run
php bin/console mto:agent:system:rebuild --hard --no-tags --no-reload
```
--- ---
## 4. Vector / Retrieval ## 5. Vector / Retrieval
### `mto:agent:vector:rebuild` ### `mto:agent:vector:rebuild`
Baut den Chunk-Vektorindex neu.
Baut den Chunk-Vektorindex aus `index.ndjson` neu.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:vector:rebuild php bin/console mto:agent:vector:rebuild
``` ```
**Reales Verhalten im Code** **Reales Verhalten**
- schreibt `Rebuilding vector index...` - schreibt `Rebuilding vector index...`
- ruft `VectorIndexBuilder->rebuildFromNdjson()` auf - ruft `VectorIndexBuilder->rebuildFromNdjson()` auf
- schreibt anschließend `Done.` - schreibt anschließend `Done.`
**Beispiel**
```bash
bin/console mto:agent:vector:rebuild
```
---
### `mto:agent:vector:control` ### `mto:agent:vector:control`
Steuert den persistenten Python-Vector-Service über `python/vector/vector_control.py`. Steuert den persistenten Python-Vector-Service über `python/vector/vector_control.py`.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:vector:control [optionen] php bin/console mto:agent:vector:control [--install] [--start] [--stop] [--force] [--reload] [--status] [--foreground] [--port=8090] [--host=0.0.0.0]
``` ```
**Unterstützte Optionen** **Optionen**
- `--install` installiert fehlende Python-Dependencies in `.venv`
- `--install` installiert fehlende Python-Abhängigkeiten in `.venv`
- `--start` startet den Service, falls er nicht läuft - `--start` startet den Service, falls er nicht läuft
- `--stop` stoppt den Service anhand der PID-Datei - `--stop` stoppt den Service anhand der PID-Datei
- `--force` erzwingt einen Hard-Stop - `--force` erzwingt einen Hard-Stop
- `--reload` triggert den `/reload`-Endpoint des Service - `--reload` triggert den `/reload`-Endpoint
- `--status` gibt den aktuellen Status aus - `--status` gibt den aktuellen Status aus
- `--foreground` startet im Vordergrund - `--foreground` startet im Vordergrund
- `--port=8090` setzt den Port - `--port` setzt den Port, Default `8090`
- `--host=0.0.0.0` setzt den Host - `--host` setzt den Host, Default `0.0.0.0`
**Reales Verhalten im Code**
- baut einen Prozessaufruf gegen `.venv/bin/python python/vector/vector_control.py`
- reicht gesetzte Optionen durch
- hängt immer `--port` und `--host` an
- gibt `stdout` des Python-Skripts direkt aus
**Beispiele** **Beispiele**
```bash ```bash
bin/console mto:agent:vector:control --install php bin/console mto:agent:vector:control --install
bin/console mto:agent:vector:control --start php bin/console mto:agent:vector:control --start
bin/console mto:agent:vector:control --status php bin/console mto:agent:vector:control --status
bin/console mto:agent:vector:control --reload php bin/console mto:agent:vector:control --reload
bin/console mto:agent:vector:control --stop --force php bin/console mto:agent:vector:control --stop --force
``` ```
---
### `mto:agent:vector:health` ### `mto:agent:vector:health`
Health-Check für Chunk-NDJSON und Chunk-Vektorindex. Health-Check für Chunk-NDJSON und Chunk-Vektorindex.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:vector:health php bin/console mto:agent:vector:health
``` ```
**Reales Verhalten im Code** **Reales Verhalten**
- ruft `VectorIndexHealthService->check()` auf - ruft `VectorIndexHealthService->check()` auf
- gibt den Report als JSON aus - gibt JSON aus
- endet mit Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1` - Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1`
**Beispiel**
```bash
bin/console mto:agent:vector:health
```
---
### `mto:agent:test-vector` ### `mto:agent:test-vector`
Debug-Kommando für einen realistischen Retrieval-Test.
Debug-Kommando für Tag- und Chunk-Vector-Clients.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:test-vector <prompt> php bin/console mto:agent:test-vector <prompt>
``` ```
**Argumente** **Argumente**
- `prompt` erforderlich, Testanfrage für das Retrieval
**Reales Verhalten im Code** - `prompt` erforderlich
- führt zuerst Tag-Routing über `TagVectorSearchClient` aus
- führt danach Chunk-Retrieval über `VectorSearchClient` aus **Reales Verhalten**
- führt Tag-Routing über `TagVectorSearchClient` aus
- führt Chunk-Retrieval über `VectorSearchClient` aus
- misst Tag-, Chunk- und Gesamtdauer - misst Tag-, Chunk- und Gesamtdauer
- gibt beide Result-Sets als JSON aus - gibt beide Result-Sets als JSON aus
**Beispiel** **Beispiel**
```bash ```bash
bin/console mto:agent:test-vector "welche dokumente behandeln den ingest-flow?" php bin/console mto:agent:test-vector "welche dokumente behandeln den ingest-flow?"
```
### `mto:agent:retrieval:test`
Testet den realen hybriden Retrieval-Pfad mit Debugausgabe.
**Signatur**
```bash
php bin/console mto:agent:retrieval:test <prompt> [--json] [--show-text]
```
**Argumente / Optionen**
- `prompt` erforderlich
- `--json` gibt das rohe Debugresultat als JSON aus
- `--show-text` zeigt vollständige Chunktexte statt gekürzter Vorschau
**Reales Verhalten**
- ruft `NdjsonHybridRetriever->retrieveDebug($prompt)` auf
- zeigt Pipeline Summary, Scope Candidates, Hit Counts, Boosts und ausgewählte Chunks
- bricht bei leerem Prompt oder Retrieval-Exception mit Fehler ab
**Beispiele**
```bash
php bin/console mto:agent:retrieval:test "niedrigster Grenzwert Wasserhärte"
php bin/console mto:agent:retrieval:test "Testomat 808 SIO2" --json
php bin/console mto:agent:retrieval:test "Indikatortyp 300" --show-text
``` ```
--- ---
## 5. Tag-System ## 6. Tag-System
### `mto:agent:tags:export` ### `mto:agent:tags:export`
Exportiert die Tag-Datenbasis nach `tags.ndjson`. Exportiert die Tag-Datenbasis nach `tags.ndjson`.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:tags:export php bin/console mto:agent:tags:export
``` ```
**Reales Verhalten im Code** **Reales Verhalten**
- ruft `TagNdjsonExporter->export()` auf - ruft `TagNdjsonExporter->export()` auf
- gibt Pfad, Tag-Anzahl, Zeilen und Bytes aus - gibt Pfad, Tag-Anzahl, Zeilen und Bytes aus
**Beispiel**
```bash
bin/console mto:agent:tags:export
```
---
### `mto:agent:tags:rebuild` ### `mto:agent:tags:rebuild`
Kompletter Neuaufbau des Tag-Retrievals. Kompletter Neuaufbau des Tag-Retrievals.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:tags:rebuild php bin/console mto:agent:tags:rebuild
``` ```
**Reales Verhalten im Code** **Reales Verhalten**
1. exportiert `tags.ndjson` 1. exportiert `tags.ndjson`
2. baut `vector_tags.index` 2. baut `vector_tags.index`
3. setzt einen Runtime-Marker über `IndexMetaManager->touchRuntime()` 3. setzt einen Runtime-Marker über `IndexMetaManager->touchRuntime()`
**Beispiel**
```bash
bin/console mto:agent:tags:rebuild
```
---
### `mto:agent:tags:job:run` ### `mto:agent:tags:job:run`
Führt einen Tag-Rebuild-Job mit File-Lock aus. Führt einen Tag-Rebuild-Job mit File-Lock aus.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:tags:job:run [jobId] [--create] php bin/console mto:agent:tags:job:run [jobId] [--create]
``` ```
**Argumente / Optionen** **Argumente / Optionen**
- `jobId` optional, UUID eines bestehenden `TagRebuildJob`
- `--create` optional, erstellt und startet sofort einen neuen `TagRebuildJob`
**Regeln im Code** - `jobId` optional, UUID eines bestehenden `TagRebuildJob`
- entweder `jobId` **oder** `--create` - `--create` erstellt und startet sofort einen neuen `TagRebuildJob`
**Regeln**
- entweder `jobId` oder `--create`
- beides zusammen ist ungültig - beides zusammen ist ungültig
- keines von beiden ist ebenfalls ungültig - keines von beiden ist ebenfalls ungültig
**Reales Verhalten im Code**
- markiert den Job auf `RUNNING`
- sperrt parallel laufende Tag-Rebuilds per File-Lock
- exportiert `tags.ndjson`
- baut `vector_tags.index`
- markiert den Job bei Erfolg als `COMPLETED`, sonst als `FAILED`
**Beispiele** **Beispiele**
```bash ```bash
bin/console mto:agent:tags:job:run --create php bin/console mto:agent:tags:job:run --create
bin/console mto:agent:tags:job:run <jobUuid> php bin/console mto:agent:tags:job:run <jobUuid>
``` ```
---
### `mto:agent:tag:health` ### `mto:agent:tag:health`
Health-Check für das Tag-Retrieval. Health-Check für das Tag-Retrieval.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:tag:health php bin/console mto:agent:tag:health [--summary]
``` ```
**Reales Verhalten im Code** **Optionen**
- `--summary` gibt eine lesbare Zusammenfassung statt JSON aus
**Reales Verhalten**
- ruft `TagVectorIndexHealthService->check()` auf - ruft `TagVectorIndexHealthService->check()` auf
- gibt den Report als JSON aus - gibt JSON oder Summary aus
- endet mit Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1` - Exit-Code `0`, wenn der Status als gesund gilt; sonst `1`
**Beispiele**
**Beispiel**
```bash ```bash
bin/console mto:agent:tag:health php bin/console mto:agent:tag:health
php bin/console mto:agent:tag:health --summary
``` ```
**Wichtige Korrektur zur alten Doku** Wichtig: Der reale Command-Name ist `tag:health` im Singular.
Der reale Command-Name ist **`tag:health` (Singular)**, nicht `tags:health`.
--- ---
## 6. Commerce / Shopware Debug ## 7. Commerce / Shopware Debug
### `mto:agent:test:shop-search` ### `mto:agent:test:shop-search`
Testkommando für die Shopware-Suche.
Testkommando für Shopware-Suche und optionalen Search-Repair-Test.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:test:shop-search [query] php bin/console mto:agent:test:shop-search [query] [--intent=INTENT] [--history=TEXT] [--repair]
``` ```
**Argumente** **Argumente / Optionen**
- `query` optional
- Default im Code: `zeige mir testomat modelle wasserhärte unter 5000 euro`
**Beabsichtigtes Verhalten** - `query` optional, Default `zeige mir testomat modelle wasserhärte unter 5000 euro`
- ruft die Shop-Suche auf - `--intent` optional, Default `CommerceIntentLite::ADVISORY_PRODUCT_SEARCH`
- gibt pro Treffer Produktdaten wie ID, Produktnummer, Hersteller, Preis, Verfügbarkeit, URL und Description aus - `--history` optionaler Commerce-History-Kontext
- `--repair` aktiviert zusätzlich die Search-Repair-Auswertung
**Wichtiger Code-Hinweis** **Reales Verhalten**
Im aktuellen Stand von `rag.zip` ruft das Command `ShopSearchService->search($query)` mit **einem** Argument auf, die Service-Signatur erwartet aber **zwei** Argumente (`string $originalPrompt, string $commerceIntent`). Das Kommando ist daher im aktuellen Codebestand sehr wahrscheinlich **nicht lauffähig**, solange diese Signaturabweichung nicht behoben wird.
- ruft `ShopSearchService->search($query, $intent, $history)` auf
- gibt Treffer mit ID, Produktnummer, Hersteller, Preis, Verfügbarkeit, URL, Description und Highlights aus
- bei `--repair` werden Knowledge-Chunks geholt und `SearchRepairService->repair(...)` ausgeführt
- zeigt dann verwendete Repair-Queries und finale gemergte Ergebnisse
**Beispiele**
```bash
php bin/console mto:agent:test:shop-search "testomat 808 300 indikator"
php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
php bin/console mto:agent:test:shop-search "testomat lab cl" --intent=advisory_product_search
php bin/console mto:agent:test:shop-search "was kostet der indikator" --history="Testomat 808 Indikatortyp 300"
```
--- ---
## 7. User-Management ## 8. User-Management
### `mto:agent:user:create` ### `mto:agent:user:create`
Interaktive Anlage eines Users. Interaktive Anlage eines Users.
**Signatur** **Signatur**
```bash ```bash
bin/console mto:agent:user:create php bin/console mto:agent:user:create
``` ```
**Interaktiver Ablauf** **Interaktiver Ablauf**
1. E-Mail eingeben 1. E-Mail eingeben
2. Passwort eingeben 2. Passwort eingeben
3. Rolle wählen 3. Passwort wiederholen
4. eine oder mehrere Rollen wählen
5. Aktivstatus bestätigen
**Validierungen**
**Validierungen im Code**
- E-Mail muss valide sein - E-Mail muss valide sein
- User mit gleicher E-Mail darf nicht bereits existieren - E-Mail darf noch nicht existieren
- Passwort muss mindestens 8 Zeichen lang sein - Passwort muss mindestens 8 Zeichen lang sein
- Passwortwiederholung muss übereinstimmen
- mindestens eine Rolle muss gewählt werden
**Zuweisbare Rollen**
**Im Code auswählbare Rollen**
- `ROLE_SUPER_ADMIN` - `ROLE_SUPER_ADMIN`
- `ROLE_KNOWLEDGE_ADMIN` - `ROLE_KNOWLEDGE_ADMIN`
- `ROLE_EDITOR` - `ROLE_EDITOR`
- `ROLE_USER` - `ROLE_ADMIN_AREA`
- `ROLE_CHAT_USER`
**Beispiel** `ROLE_USER` wird als technische Basisrolle über die Hierarchie genutzt, ist aber nicht als fachliche Zielrolle in der Auswahl vorgesehen.
```bash
bin/console mto:agent:user:create
```
--- ---
## 8. Typische Betriebsabläufe ## 9. Config / Governance
### `mto:agent:config:validate`
Validiert die effektive RetrieX-Konfiguration.
**Signatur**
```bash
php bin/console mto:agent:config:validate [--json]
```
**Erwartung vor Merge/Deployment**
- Status `OK`
- keine Errors
### `mto:agent:config:audit-source`
Auditiert YAML-backed Configuration gegen PHP-Defaults, Fallback-Accessors und Constructor-Defaults.
**Signatur**
```bash
php bin/console mto:agent:config:audit-source [--details] [--json]
```
**Optionen**
- `--details` zeigt reviewbare Detailzeilen
- `--json` gibt maschinenlesbares JSON aus
### `mto:agent:config:audit-patterns`
Auditiert verbleibende Pattern-, Token- und Signalnutzung im PHP-Core.
**Signatur**
```bash
php bin/console mto:agent:config:audit-patterns [--details] [--json] [--all]
```
**Zweck**
- findet konfigurierte Calls wie `preg_match`, `str_contains`, `in_array` usw.
- markiert WARN-Funde bei Domain-Marker-Terms
- bleibt revieworientiert und nicht selbst runtime-verändernd
**Beispiel**
```bash
php bin/console mto:agent:config:audit-patterns --details
```
### `mto:agent:config:dump-effective`
Gibt die effektive RetrieX-Konfigurationsinventur aus.
**Signatur**
```bash
php bin/console mto:agent:config:dump-effective [--summary]
```
**Beispiele**
```bash
php bin/console mto:agent:config:dump-effective
php bin/console mto:agent:config:dump-effective --summary
```
### `mto:agent:regression:test`
Führt Offline-Regression-Guards für stabile Pfade aus.
**Signatur**
```bash
php bin/console mto:agent:regression:test [--json]
```
**Zweck**
- schützt regressionsempfindliche 1.4.x/1.5.x/1.6.0-Flows
- prüft Konfigurationspfade, Tokens und Guardrail-Erwartungen
- ist Pflichtcheck für Änderungen an YAML-, Prompt-, Retrieval-, Commerce- oder Agent-Logik
---
## 10. Typische Betriebsabläufe
### Manueller Ingest einer Version ### Manueller Ingest einer Version
```bash ```bash
bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid> php bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
``` ```
### Vorhandenen Ingest-Job ausführen ### Vorhandenen Ingest-Job ausführen
```bash ```bash
bin/console mto:agent:ingest:run <jobUuid> php bin/console mto:agent:ingest:run <jobUuid>
``` ```
### Nur Chunk-Vektorindex neu bauen ### Nur Chunk-Vektorindex neu bauen
```bash ```bash
bin/console mto:agent:vector:rebuild php bin/console mto:agent:vector:rebuild
``` ```
### Gesamtsystem hart neu aufbauen ### Gesamtsystem hart neu aufbauen
```bash ```bash
bin/console mto:agent:system:rebuild --hard php bin/console mto:agent:system:rebuild --hard
``` ```
### Vector-Service prüfen und reloaden ### Vector-Service prüfen und reloaden
```bash ```bash
bin/console mto:agent:vector:health php bin/console mto:agent:vector:health
bin/console mto:agent:vector:control --reload php bin/console mto:agent:vector:control --status
php bin/console mto:agent:vector:control --reload
``` ```
### Tag-Retrieval neu aufbauen ### Tag-Retrieval neu aufbauen
```bash ```bash
bin/console mto:agent:tags:rebuild php bin/console mto:agent:tags:rebuild
bin/console mto:agent:tag:health php bin/console mto:agent:tag:health --summary
```
### Shopquery mit Repair testen
```bash
php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
```
### Config-Änderung prüfen
```bash
php bin/console mto:agent:config:validate
php bin/console mto:agent:config:audit-source --details
php bin/console mto:agent:config:audit-patterns --details
php bin/console mto:agent:regression:test
``` ```
--- ---
## 9. Wichtige Runtime-Dateien und Pfade ## 11. Wichtige Runtime-Dateien und Pfade
Die bisherige Doku nannte teilweise veraltete Pfade unter `var/`. Im aktuellen Code liegen die Knowledge-Artefakte primär unter `var/knowledge/`.
```text ```text
var/ var/
@@ -458,128 +655,52 @@ var/
│ ├── vector_tags.index.meta.json │ ├── vector_tags.index.meta.json
│ ├── uploads/ │ ├── uploads/
│ └── locks/ │ └── locks/
│ └── tag_rebuild.lock
├── run/ ├── run/
│ └── vector_service.pid │ └── vector_service.pid
└── locks/ └── locks/
└── ingest.lock └── ingest.lock
``` ```
**Herkunft im Code** Herkunft im Code:
- `config/services.yaml` definiert `mto.knowledge.root = %mto.root%/var/knowledge`
- `python/vector/vector_control.py` verwendet `var/run/vector_service.pid` - `config/services.yaml` bindet `mto.knowledge.*` an `retriex.knowledge.*`.
- `App\Service\LockService` verwendet aktuell `var/locks/ingest.lock` - `python/vector/vector_control.py` verwendet `var/run/vector_service.pid`.
- `App\Service\LockService` verwendet `var/locks/ingest.lock`.
--- ---
## 10. Wichtige Abweichungen zur alten `COMMAND_REF.md` ## 12. Wichtige Korrekturen gegenüber älteren Referenzen
Die bisherige Datei war in mehreren Punkten nicht mehr codekonform. Wesentliche Korrekturen: 1. Der aktuelle Stand enthält **21** projektspezifische Commands, nicht nur die älteren 18.
2. `mto:agent:eval:run` ist Teil des aktuellen Command-Sets.
1. `mto:agent:system:rebuild` fehlte vollständig 3. `mto:agent:retrieval:test` testet den realen hybriden Retrieval-Pfad und ergänzt `mto:agent:test-vector`.
2. `mto:agent:test:shop-search` fehlte vollständig 4. `mto:agent:test:shop-search` ist im aktuellen Stand mit `query`, `--intent`, `--history` und `--repair` codekonform dokumentiert.
3. `mto:agent:tag:health` fehlte und war zudem leicht falsch benannt 5. `mto:agent:tag:health` unterstützt `--summary`.
4. `mto:agent:ingest:version` braucht aktuell **`<versionId> <userId>`** 6. `mto:agent:user:create` kann mehrere Rollen auswählen und fragt Aktivstatus ab.
5. Runtime-Dateien liegen nicht nur unter `var/`, sondern überwiegend unter `var/knowledge/` 7. Zuweisbare Rollen umfassen `ROLE_ADMIN_AREA` und `ROLE_CHAT_USER`.
6. der globale Rebuild läuft heute über `mto:agent:system:rebuild --hard`, nicht über ein dokumentiertes `ingest:global` 8. `mto:agent:ingest:version` braucht weiterhin zwei Pflichtargumente: `<versionId> <userId>`.
9. Der globale Rebuild läuft über `mto:agent:system:rebuild --hard`.
10. Runtime-Artefakte liegen überwiegend unter `var/knowledge/`.
--- ---
## 13. Fazit
## 11. Config-Governance / YAML-only Guardrails Für den operativen Betrieb sind besonders relevant:
These commands are mandatory for changes that touch YAML-backed configuration, prompt/retrieval behavior, intent detection, commerce/shop logic or regression-sensitive answer paths. - `mto:agent:system:rebuild --hard`
- `mto:agent:vector:control --status|--reload|--start`
### `mto:agent:config:validate`
Validates the effective RetrieX configuration.
**Signature**
```bash
bin/console mto:agent:config:validate [--json]
```
**Expected result before merge**
- status `OK`
- no errors
### `mto:agent:config:audit-source`
Audits YAML-backed configuration against remaining PHP defaults, fallback accessors and constructor defaults.
**Signature**
```bash
bin/console mto:agent:config:audit-source [--details] [--json]
```
**Expected result before merge**
- no missing YAML mappings
- no new undocumented PHP-only semantic constants
- no constructor defaults without YAML/service-parameter mapping
Use `--details` for reviewable console output and `--json` for machine-readable CI output.
### `mto:agent:config:dump-effective`
Dumps the effective RetrieX configuration inventory.
**Signature**
```bash
bin/console mto:agent:config:dump-effective [--summary]
```
Use `--summary` for a compact review view.
### `mto:agent:regression:test`
Runs offline regression guards for stable configuration paths.
**Signature**
```bash
bin/console mto:agent:regression:test [--json]
```
**Expected result before merge**
- status `OK`
- all checks pass
This command protects the regression-sensitive 1.4.2/1.5.0 baseline, especially the Testomat 808 / 0,02 deg dH / indicator type 300 flow and related configuration paths.
---
## 12. Fazit
Der aktuelle Custom-CLI-Umfang des Systems besteht aus mindestens **18 projektspezifischen Commands**. Für den operativen Betrieb sind besonders relevant:
- `mto:agent:ingest:run`
- `mto:agent:system:rebuild`
- `mto:agent:vector:control`
- `mto:agent:vector:health` - `mto:agent:vector:health`
- `mto:agent:tags:rebuild` - `mto:agent:tag:health --summary`
- `mto:agent:tag:health` - `mto:agent:ingest:run`
- `mto:agent:config:validate`
- `mto:agent:regression:test`
### `mto:agent:config:audit-patterns` Für Entwicklung und Fehlersuche sind besonders hilfreich:
Audits remaining pattern-, token- and signal-sensitive calls in PHP core files for developer-policy review. - `mto:agent:chat`
- `mto:agent:retrieval:test`
**Signature** - `mto:agent:test-vector`
```bash - `mto:agent:test:shop-search --repair`
bin/console mto:agent:config:audit-patterns [--details] [--json] [--all] - `mto:agent:config:dump-effective --summary`
``` - `mto:agent:config:audit-patterns --details`
**Purpose**
- finds configured calls such as `preg_match`, `str_contains`, `in_array` and related pattern/token helpers in configured source roots
- raises WARN findings when configured domain marker terms are involved
- keeps the command non-blocking and review-oriented; it does not change runtime behavior and does not activate strict validation
**Options**
- `--details` renders reviewable warning rows
- `--json` renders machine-readable audit output
- `--all` includes lower-priority REVIEW findings in addition to WARN findings
**Expected use before merge**
```bash
bin/console mto:agent:config:audit-patterns --details
```
Review WARN findings and move new semantic terms, product names, intent words, commerce signals or retrieval/follow-up patterns to YAML-backed configuration when they are not purely technical.

692
INSTALL.md
View File

@@ -1,315 +1,242 @@
# RetrieX – Installationsanleitung # RetrieX v1.6.0 – Installationsanleitung
Stand: 15.04.2026 Stand: Version **1.6.0** auf Basis des aktuellen `rag-inprogress.zip`.
Quelle: aktuelle `rag.zip` (Single Source of Truth)
Diese Anleitung beschreibt die **codebasierte Neuinstallation** des aktuellen Systems. Sie ersetzt ältere Installationsstände. Alle Angaben unten wurden an den tatsächlich vorhandenen Dateien, Services, Commands und Pfaden aus dem ZIP ausgerichtet. Diese Anleitung beschreibt eine codebasierte Neuinstallation des aktuellen Systems. Sie ersetzt ältere Installationshinweise, die noch von `rag.zip`, einem Stand vom 15.04.2026 oder einer rein statischen Chat-Startseite ausgehen.
--- ---
## 1. Architektur des aktuellen Stands ## 1. Architektur des aktuellen Stands
RetrieX besteht aktuell aus diesen Hauptbausteinen: RetrieX v1.6.0 besteht aus diesen Hauptbausteinen:
- **Symfony 7.4** auf **PHP 8.2+** - Symfony 7.4 auf PHP 8.2+
- **Doctrine ORM + Doctrine Migrations** - Doctrine ORM und Doctrine Migrations
- **MariaDB/MySQL** als operative Datenbank - MariaDB/MySQL-orientierte Migrationen mit binären UUIDs
- **Python-Vektorlayer** mit `faiss-cpu`, `sentence-transformers`, `fastapi`, `uvicorn` - dateibasierte Knowledge-Artefakte unter `var/knowledge`
- **Ollama-kompatibler LLM-Endpunkt** über `AI_LLM_API_URL` - Python-Vektorlayer mit FastAPI, uvicorn, FAISS und SentenceTransformers
- **NDJSON + FAISS** im Dateisystem unter `var/knowledge` - Ollama-kompatibler LLM-Generate-Endpunkt über `AI_LLM_API_URL`
- **Adminoberfläche** für Dokumente, Ingest-Profile, System Prompt, Modellkonfiguration und Jobs - hybrides Retrieval über NDJSON, FAISS, Keyword-/Lexical-Komponenten und Tag-Routing
- **SSE-Streaming** für den Browser-Chat - optionaler Shopware-Store-API-Commercepfad
- Twig-basierte Chat- und Adminoberflächen
- Job-basierter SSE-Flow für Browserantworten
- getrennte Admin- und Chat-Firewalls mit Rollenmodell
- Admin-Benutzerverwaltung, Fehlerseiten und Access-Denied-UX
- Config-/Governance-/Regression-Commands für sichere Änderungen
Wichtige Betriebsordner im aktuellen Code: Wichtige Ordner:
- `var/knowledge/` → NDJSON, FAISS-Indizes, Uploads ```text
- `var/log/` → System-, Agent- und Ingest-Logs var/knowledge/ NDJSON, FAISS-Indizes, Tags, Uploads
- `var/run/` → PID-Dateien des Python-Services var/log/ Symfony-, Agent-, Ingest- und Vector-Logs
- `var/locks/` → Ingest-Lock var/run/ PID-Dateien, z. B. vector_service.pid
- `python/vector/` → Python-Control-, Search- und Service-Skripte var/locks/ globale Locks, z. B. ingest.lock
python/vector/ Python-Control-, Search- und Ingest-Skripte
config/retriex/ Runtime-, Retrieval-, Commerce-, Prompt- und Genre-Konfiguration
```
--- ---
## 2. Wichtige Korrekturen gegenüber älteren Installationsständen ## 2. Wichtige Änderungen gegenüber älteren Ständen
Die frühere `INSTALL.md` passt nicht mehr zum aktuellen Code. Für den aktuellen Stand gelten insbesondere diese Punkte: - Das Chat-Frontend läuft nicht mehr über eine statische `public/index.html`, sondern über `App\Controller\Chat\ChatController` mit `/` und `/chat`.
- Chat- und Adminbereiche sind architektonisch und sicherheitsseitig getrennt.
- Der Wissensspeicher liegt unter **`var/knowledge/`**, nicht unter `var/vector/`. - Admin-Routen liegen unter `/admin...`; Chat-/Ask-/SSE-/History-Routen liegen in der Chat-Firewall.
- Der Python-Code liegt unter **`python/vector/`**, nicht unter `vector/`. - `ROLE_USER` allein reicht nicht mehr für Chat oder Admin.
- Die Python-Abhängigkeiten kommen aus der Datei **`requirements.txt` im Projektroot**. - `ROLE_CHAT_USER` schaltet Chat-Zugriff frei.
- Der korrekte Rebuild-Befehl ist **`mto:agent:system:rebuild --hard`**, nicht `mto:agent:ingest:global`. - `ROLE_ADMIN_AREA`, `ROLE_EDITOR`, `ROLE_KNOWLEDGE_ADMIN` und `ROLE_SUPER_ADMIN` schalten Adminbereiche gestuft frei.
- Das LLM-Modell kommt **nicht** mehr aus einer `AI_LLM_MODEL`-Umgebungsvariable, sondern aus der **aktiven ModelGenerationConfig** in der Adminoberfläche. - Die CLI umfasst inzwischen 21 projektspezifische Commands unter `mto:agent:*`.
- Für den Chat sind **zwingend** nötig: - `mto:agent:test:shop-search` unterstützt jetzt `--intent`, `--history` und optional `--repair`; die ältere Warnung über eine falsche Service-Signatur ist nicht mehr zutreffend.
- ein **aktiver System Prompt** - Der produktive Loader unterstützt PDF, TXT und Markdown (`.md`).
- eine **aktive ModelGenerationConfig** - `genre.yaml` ist die zentrale fachliche Source-of-Truth für Produktrollen, Query-Guards, Follow-up-Auflösung und Regression-Anker.
- mindestens ein erfolgreich indexiertes Dokument für wissensbasiertes Retrieval
- Die Upload-UI erwähnt mehrere Dateitypen, der aktuelle Extractor-Code unterstützt jedoch **faktisch nur PDF**.
--- ---
## 3. Systemvoraussetzungen ## 3. Systemvoraussetzungen
## 3.1 Betriebssystem ### 3.1 Betriebssystem
Empfohlen: Empfohlen:
- Ubuntu 22.04 LTS oder neuer - Linux Server oder VM
- Debian 12 ist ebenfalls passend - Ubuntu 22.04/24.04 oder Debian 12
Für lokale Entwicklung sind auch macOS oder Linux-Container-Setups möglich. Lokal ist Entwicklung auch auf macOS oder WSL möglich, produktiv sollte ein regulärer Webserver mit PHP-FPM verwendet werden.
--- ### 3.2 PHP
## 3.2 PHP
Erforderlich: Erforderlich:
- **PHP 8.2 oder höher** - PHP 8.2 oder neuer
- Composer
Benötigte bzw. praktisch notwendige Extensions aus dem aktuellen Projektstand: Relevante PHP-Erweiterungen aus `composer.json` und Runtime:
- `ctype` - `ctype`
- `curl` - `curl`
- `dom` - `dom`
- `iconv` - `iconv`
- `libxml` - `libxml`
- `pdo`
- `pdo_mysql` - `pdo_mysql`
- `mbstring` - `mbstring`
- `zip` - `zip`
- `sqlite3`
Prüfen: Prüfen:
```bash ```bash
php -v php -v
php -m php -m
```
---
## 3.3 Composer
Prüfen:
```bash
composer --version composer --version
``` ```
Falls Composer nicht global vorhanden ist, kann lokal installiert werden. Für den regulären Betrieb ist ein globaler Composer aber sinnvoll. ### 3.3 Datenbank
--- Die mitgelieferten Migrationen sind praktisch auf MariaDB/MySQL ausgelegt, z. B. durch `BINARY(16)`, `TINYINT`, `LONGTEXT`, `JSON` und MariaDB-kompatible UUID-Strukturen.
## 3.4 Datenbank
Der aktuelle Projektstand ist praktisch auf **MariaDB/MySQL** ausgerichtet.
Empfohlen: Empfohlen:
- **MariaDB 10.11.x** - MariaDB 10.11.x oder kompatibles MySQL 8.x
Beispielinstallation: Beispiel:
```bash
sudo apt install mariadb-server
```
Beispiel für Datenbank und Benutzer:
```sql ```sql
CREATE DATABASE db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE DATABASE retriex CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'db'@'%' IDENTIFIED BY 'db'; CREATE USER 'retriex'@'%' IDENTIFIED BY 'change-me';
GRANT ALL PRIVILEGES ON db.* TO 'db'@'%'; GRANT ALL PRIVILEGES ON retriex.* TO 'retriex'@'%';
FLUSH PRIVILEGES; FLUSH PRIVILEGES;
``` ```
Hinweis: Die mitgelieferte `.env` kann noch Platzhalter enthalten. Für Betrieb eine eigene `.env.local` verwenden.
Die mitgelieferte `.env` enthält derzeit noch eine PostgreSQL-Placeholder-URL. Für den realen Betrieb muss `DATABASE_URL` auf **MariaDB/MySQL** gesetzt werden.
--- ### 3.4 Python
## 3.5 Python
Erforderlich: Erforderlich:
- **Python 3.10 oder höher** - Python 3.10 oder neuer
- `python3-venv` - `python3-venv`
- `python3-pip` - `python3-pip`
Installation: Python-Abhängigkeiten aus `requirements.txt`:
```bash - `fastapi`
sudo apt install python3 python3-venv python3-pip - `uvicorn`
``` - `faiss-cpu`
- `sentence-transformers`
- `numpy`
Prüfen: ### 3.5 LLM-Endpunkt
```bash RetrieX spricht den LLM über `AI_LLM_API_URL` an. Erwartet wird ein Ollama-kompatibler `/api/generate`-Endpoint.
python3 --version
```
--- Beispiel:
## 3.6 Ollama oder kompatibler Generate-Endpunkt
RetrieX spricht den LLM-Endpunkt über `AI_LLM_API_URL` an. Erwartet wird ein **Ollama-kompatibler `/api/generate`-Endpoint**.
Beispiel mit Ollama:
```bash
curl -fsSL https://ollama.com/install.sh | sh
```
Ein Modell muss lokal vorhanden sein, zum Beispiel:
```bash
ollama pull qwen3
```
oder ein projektspezifisches Modell, falls vorhanden.
Verfügbarkeit prüfen:
```bash ```bash
curl http://127.0.0.1:11434/api/tags curl http://127.0.0.1:11434/api/tags
``` ```
Wichtig: Das konkret verwendete Modell wird über die aktive `ModelGenerationConfig` im Admin gesteuert, nicht allein über `.env`.
Welches Modell tatsächlich benutzt wird, bestimmt später die **aktive ModelGenerationConfig im Admin**, nicht eine `.env`-Variable.
--- ### 3.6 Optional: Shopware Store API
## 3.7 Optional: Shopware Store API Für Commerce-/Shopfragen kann die Shopware Store API angebunden werden.
Der Commerce-Pfad ist im aktuellen Code **standardmäßig aktiviert**. Für produktbezogene Anfragen nutzt das System optional die Shopware Store API. Relevante Variablen:
Dafür werden diese Variablen verwendet:
- `SHOPWARE_STORE_API_BASE_URL` - `SHOPWARE_STORE_API_BASE_URL`
- `SHOPWARE_SALES_CHANNEL_ACCESS_KEY` - `SHOPWARE_SALES_CHANNEL_ACCESS_KEY`
- `SHOPWARE_STORE_API_MAX_RESULT` - `SHOPWARE_STORE_API_MAX_RESULT`
Wenn keine Shopware-Suche gewünscht ist, sollte der Commerce-Pfad vor produktivem Einsatz bewusst deaktiviert oder sauber konfiguriert werden. Wenn keine Shopware-Suche gewünscht ist, Commerce bewusst deaktivieren oder sauber mit leeren/ungefährlichen Testwerten konfigurieren.
--- ---
## 4. Projekt bereitstellen ## 4. Projekt bereitstellen
ZIP entpacken und ins Projekt wechseln: Beispiel mit ZIP:
```bash ```bash
unzip rag.zip -d retriex unzip rag-inprogress.zip -d retriex
cd retriex cd retriex
``` ```
Alternativ über Repository-Checkout, falls das Projekt aus Git bereitgestellt wird. Oder über Repository-Checkout, falls der Stand in Git verwaltet wird.
--- ---
## 5. PHP-Abhängigkeiten installieren ## 5. PHP-Abhängigkeiten installieren
Entwicklung:
```bash ```bash
composer install --no-interaction composer install --no-interaction
``` ```
Für Produktion: Produktion:
```bash ```bash
composer install --no-dev --optimize-autoloader --no-interaction composer install --no-dev --optimize-autoloader --no-interaction
``` ```
Erst nach diesem Schritt funktionieren `bin/console` und die Symfony-Commands. Danach sollte `bin/console` ausführbar sein:
```bash
php bin/console list mto:agent
```
--- ---
## 6. Umgebung konfigurieren ## 6. Umgebung konfigurieren
## 6.1 Grundregel Eine lokale `.env.local` anlegen und mindestens Datenbank und LLM-Endpunkt setzen.
Lokale oder serverbezogene Overrides sollten in **`.env.local`** gepflegt werden, nicht direkt in der committeten `.env`. Beispiel:
--- ```dotenv
## 6.2 Minimale `.env.local`
Beispiel für einen lokalen oder servernahen MariaDB-Betrieb:
```env
APP_ENV=prod APP_ENV=prod
APP_SECRET=change-me APP_SECRET=change-me
DATABASE_URL="mysql://retriex:change-me@127.0.0.1:3306/retriex?serverVersion=10.11.2-MariaDB&charset=utf8mb4"
DATABASE_URL="mysql://db:db@127.0.0.1:3306/db?serverVersion=10.11.0-mariadb&charset=utf8mb4" AI_LLM_API_URL="http://127.0.0.1:11434/api/generate"
MESSENGER_TRANSPORT_DSN=doctrine://default?auto_setup=0
AI_LLM_API_URL=http://127.0.0.1:11434/api/generate
AI_LLM_TIMEOUT=600
AI_HISTORY_DIR=var/agent-history
AI_DEBUG=false
AI_LOG_PROMPT=false
AI_LOG_CONTEXT=false
SHOPWARE_STORE_API_BASE_URL="https://example.invalid"
SHOPWARE_SALES_CHANNEL_ACCESS_KEY="replace-me"
SHOPWARE_STORE_API_MAX_RESULT=25
``` ```
Hinweise: Optional für Shopware:
- `APP_ENV=prod` ist im aktuellen `.env` bereits voreingestellt. ```dotenv
- `DATABASE_URL` muss auf MariaDB/MySQL zeigen. SHOPWARE_STORE_API_BASE_URL="https://example.invalid/store-api"
- `AI_LLM_API_URL` muss auf einen funktionierenden `/api/generate`-Endpoint zeigen. SHOPWARE_SALES_CHANNEL_ACCESS_KEY="change-me"
- `AI_LLM_TIMEOUT=600` ist mit dem aktuellen Code konsistent. SHOPWARE_STORE_API_MAX_RESULT=10
- `AI_LLM_MODEL` wird **nicht** verwendet. ```
--- Wichtig: keine produktiven Secrets in die versionierte `.env` schreiben.
## 6.3 Shopware deaktivieren, wenn nicht benötigt
Im aktuellen Code ist `mto.commerce.enabled` in `config/services.yaml` auf `true` gesetzt. Wer die Shopware-Suche nicht einsetzen will, sollte vor produktivem Einsatz bewusst einen dieser Wege wählen:
1. gültige Shopware-Zugangsdaten hinterlegen, oder
2. `config/services.yaml` gezielt anpassen und Commerce deaktivieren.
Für reine Wissens- und Dokumentinstallation ist die Shopware-Anbindung nicht zwingend, sollte aber nicht unklar halbkonfiguriert bleiben.
--- ---
## 7. Datenbank initialisieren ## 7. Datenbank initialisieren
Migrationen ausführen:
```bash ```bash
php bin/console doctrine:database:create --if-not-exists
php bin/console doctrine:migrations:migrate --no-interaction php bin/console doctrine:migrations:migrate --no-interaction
``` ```
Damit werden unter anderem diese zentralen Tabellen angelegt: Bei Produktionsbetrieb danach Cache aufbauen:
- `user` ```bash
- `document` php bin/console cache:clear --env=prod
- `document_version` php bin/console cache:warmup --env=prod
- `ingest_job` ```
- `system_prompt`
- `ingest_profile`
- `model_generation_config`
- `knowledge_tag`
- `document_tag`
- `tag_rebuild_job`
--- ---
## 8. Python-Umgebung aufbauen ## 8. Python-Umgebung aufbauen
## 8.1 Virtuelle Umgebung anlegen Virtuelle Umgebung anlegen:
```bash ```bash
python3 -m venv .venv python3 -m venv .venv
source .venv/bin/activate source .venv/bin/activate
``` ```
--- Abhängigkeiten installieren:
## 8.2 Python-Abhängigkeiten installieren
Manuell:
```bash ```bash
pip install --upgrade pip pip install --upgrade pip
@@ -322,12 +249,11 @@ Alternativ nach angelegter `.venv` über den Symfony-Wrapper:
php bin/console mto:agent:vector:control --install php bin/console mto:agent:vector:control --install
``` ```
Wichtig: Der Wrapper erwartet eine vorhandene `.venv`; er legt sie nicht selbst an.
Der Wrapper erwartet bereits eine existierende `.venv`. Er erzeugt sie **nicht** selbst.
--- ---
## 9. Vector Service starten ## 9. Vector-Service starten
Start: Start:
@@ -335,335 +261,297 @@ Start:
php bin/console mto:agent:vector:control --start php bin/console mto:agent:vector:control --start
``` ```
Status prüfen: Status:
```bash ```bash
php bin/console mto:agent:vector:control --status php bin/console mto:agent:vector:control --status
``` ```
Optionaler Reload: Reload:
```bash ```bash
php bin/console mto:agent:vector:control --reload php bin/console mto:agent:vector:control --reload
``` ```
Der Service startet aktuell standardmäßig auf: Standardwerte aus dem aktuellen Command/Service-Setup:
- Host: `0.0.0.0` - Host: `0.0.0.0`
- Port: `8090` - Port: `8090`
- PHP-Service-URL: typischerweise `http://127.0.0.1:8090`
Der PHP-Code spricht standardmäßig gegen: - PID-Datei: `var/run/vector_service.pid`
- `http://127.0.0.1:8090`
--- ---
## 10. Admin-Benutzer anlegen ## 10. Ersten Benutzer anlegen
Ohne Admin-Benutzer lässt sich das System nicht fertig konfigurieren. Ohne Benutzer ist weder Chat noch Admin sinnvoll nutzbar.
CLI-Befehl:
```bash ```bash
php bin/console mto:agent:user:create php bin/console mto:agent:user:create
``` ```
Der Command fragt interaktiv ab: Der Command fragt ab:
- E-Mail - E-Mail
- Passwort - Passwort mit Wiederholung
- Rolle - eine oder mehrere Rollen
- Aktivstatus
Für die Erstinstallation ist typischerweise sinnvoll: Für die Erstinstallation ist typischerweise `ROLE_SUPER_ADMIN` sinnvoll. Diese Rolle enthält über die Hierarchie auch Admin-, Editor-, Knowledge-Admin- und Chat-Rechte.
- `ROLE_SUPER_ADMIN`
--- ---
## 11. Anwendung starten ## 11. Anwendung starten
Für einen einfachen lokalen Test: Lokaler Test:
```bash ```bash
php -S 127.0.0.1:8000 -t public php -S 127.0.0.1:8000 -t public
``` ```
Danach sind typischerweise relevant: Relevante Einstiegspunkte:
- Chat-Frontend: `http://127.0.0.1:8000/` - Chat: `http://127.0.0.1:8000/`
- Chat-Login: `http://127.0.0.1:8000/chat/login`
- Admin-Login: `http://127.0.0.1:8000/admin/login` - Admin-Login: `http://127.0.0.1:8000/admin/login`
Für Produktion sollte stattdessen ein regulärer Webserver genutzt werden, zum Beispiel Nginx + PHP-FPM. Für Produktion Nginx/Apache + PHP-FPM verwenden und `public/` als Document Root setzen.
--- ---
## 12. Pflicht-Initialisierung im Admin ## 12. Pflicht-Initialisierung im Admin
Nach der technischen Grundinstallation ist das System **noch nicht vollständig betriebsbereit**. Es müssen im Admin zwingend Inhalte angelegt werden. ### 12.1 System Prompt anlegen
## 12.1 System Prompt anlegen und aktivieren Pfad:
Pfad im Admin: ```text
/admin/system/prompt
- `/admin/system/prompt`
Ohne aktiven System Prompt wirft der PromptBuilder zur Laufzeit einen Fehler.
---
## 12.2 ModelGenerationConfig anlegen und aktivieren
Pfad im Admin:
- `/admin/model-config/`
Ohne aktive ModelGenerationConfig schlägt das Retrieval fehl, weil `NdjsonHybridRetriever` explizit eine aktive Konfiguration verlangt.
Sinnvolle Minimalwerte für einen stabilen Start:
- Modellname: exakt wie im Ollama-Endpunkt verfügbar, z. B. `qwen3:latest`
- Streaming: aktiv
- Temperature: `0.2` bis `0.4`
- Top K: `40`
- Top P: `0.9`
- Repeat Penalty: `1.1`
- num_ctx: `8192`
- Retrieval Max Chunks: `25`
- Retrieval Vector Top K: `25`
---
## 12.3 Optional: Ingest-Profil anlegen
Pfad im Admin:
- `/admin/ingest-profiles/`
Wenn kein Profil aktiv ist, fällt das System auf die Parameter aus `config/services.yaml` zurück:
- Chunk Size: `800`
- Chunk Overlap: `100`
- Embedding Model: `intfloat/multilingual-e5-base`
- Embedding Dimension: `768`
- Scoring Version: `1`
Das ist für einen ersten Start ausreichend. Ein eigenes Ingest-Profil ist also **optional**, solange man die Fallback-Werte bewusst akzeptiert.
---
## 13. Erste Dokumente ingestieren
## 13.1 Wichtiger Format-Hinweis
Die Upload-Maske nennt mehrere Formate, aber der aktuelle Extractor-Code enthält nur einen **`PdfExtractor`**. Für einen sicheren Erstbetrieb sollten daher aktuell **nur PDF-Dateien** hochgeladen werden.
---
## 13.2 Erstes Dokument hochladen
Pfad im Admin:
- `/admin/documents/new`
Beim Upload passiert im aktuellen Code folgendes:
1. Datei wird nach `var/knowledge/uploads` verschoben.
2. Dokument und Version 1 werden in der DB angelegt.
3. Die neue Version wird aktiv gesetzt.
4. Ein Ingest-Job vom Typ `DOCUMENT_VERSION_ACTIVATE` wird erstellt.
5. Der Job wird **asynchron per `exec()`** gestartet.
---
## 13.3 Wenn `exec()` deaktiviert ist
Der Admin-Flow für Upload, Aktivierung und Löschen setzt im aktuellen Code Hintergrundstarts über `exec()` voraus.
Ist `exec()` serverseitig deaktiviert, werden Jobs zwar angelegt, aber nicht automatisch ausgeführt. In diesem Fall muss der Job manuell gestartet werden:
```bash
php bin/console mto:agent:ingest:run <jobId>
``` ```
Die `jobId` ist in der Job-Ansicht im Admin nachvollziehbar. Ohne aktiven System Prompt kann der finale PromptBuilder keine saubere Antwortgrundlage erzeugen.
### 12.2 ModelGenerationConfig anlegen
Pfad:
```text
/admin/model-config/
```
Sinnvolle Startwerte:
| Feld | Beispiel |
| --- | --- |
| Modellname | `qwen3:latest` oder der lokal verfügbare Ollama-Name |
| Streaming | aktiv |
| Temperature | `0.2` bis `0.4` |
| Top K | `40` |
| Top P | `0.9` |
| Repeat Penalty | `1.1` |
| num_ctx | `8192` oder höher, passend zum Modell |
| Retrieval Max Chunks | `25` |
| Retrieval Vector Top K | `25` |
### 12.3 Optional: Ingest-Profil prüfen
Pfad:
```text
/admin/ingest-profiles/
```
Wenn kein Profil aktiv ist, gelten die Fallbackwerte aus der technischen Konfiguration. Für produktive Systeme sollte ein bewusstes Profil gepflegt werden.
---
## 13. Dokumente ingestieren
Unterstützte Formate im aktuellen Ingest-Loader:
- `.pdf`
- `.txt`
- `.md`
Ablauf im Admin:
1. Als Benutzer mit `ROLE_EDITOR` oder höher einloggen.
2. Dokument anlegen oder öffnen.
3. Version hochladen.
4. Version ingestieren bzw. aktivieren.
5. Ingest-Job prüfen.
6. Danach Vector-/Tag-Health prüfen.
CLI-Ingest einer konkreten Version:
```bash
php bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
```
Vorhandenen Job ausführen:
```bash
php bin/console mto:agent:ingest:run <jobUuid>
```
--- ---
## 14. Rebuild und Konsistenzprüfung ## 14. Rebuild und Konsistenzprüfung
## 14.1 Vollständiger System-Rebuild Vollständiger Hard-Rebuild:
Sobald aktive Dokumente vorhanden sind, kann ein vollständiger Rebuild ausgeführt werden:
```bash ```bash
php bin/console mto:agent:system:rebuild --hard php bin/console mto:agent:system:rebuild --hard
``` ```
Dieser Ablauf umfasst aktuell: Optionen:
1. globalen Reindex der aktiven Dokumente ```bash
2. Tag-Export und Tag-Index-Rebuild php bin/console mto:agent:system:rebuild --hard --dry-run
3. Reload des Vector Service php bin/console mto:agent:system:rebuild --hard --no-tags
4. Health-Checks php bin/console mto:agent:system:rebuild --hard --no-reload
php bin/console mto:agent:system:rebuild --hard --no-health
```
Wichtig: Health-Checks:
Der Befehl bricht absichtlich ab, wenn **keine aktiven Dokumente** vorhanden sind.
---
## 14.2 Vector Health prüfen
```bash ```bash
php bin/console mto:agent:vector:health php bin/console mto:agent:vector:health
php bin/console mto:agent:tag:health --summary
``` ```
Mögliche gesunde Zustände: Tag-Retrieval neu aufbauen:
- `OK_EMPTY` → noch keine Wissensdaten vorhanden
- `OK` → NDJSON und FAISS konsistent
---
## 14.3 Tag Health prüfen
```bash ```bash
php bin/console mto:agent:tag:health
```
---
## 15. Wichtige Commands im aktuellen Stand
```bash
php bin/console mto:agent:user:create
php bin/console mto:agent:vector:control --install
php bin/console mto:agent:vector:control --start
php bin/console mto:agent:vector:control --status
php bin/console mto:agent:vector:control --reload
php bin/console mto:agent:vector:rebuild
php bin/console mto:agent:vector:health
php bin/console mto:agent:ingest:run <jobId>
php bin/console mto:agent:ingest:version <versionId> <userId>
php bin/console mto:agent:system:rebuild --hard
php bin/console mto:agent:tags:export
php bin/console mto:agent:tags:rebuild php bin/console mto:agent:tags:rebuild
php bin/console mto:agent:tag:health
php bin/console mto:agent:chat
php bin/console mto:agent:test:shop-search "deine Anfrage"
``` ```
--- ---
## 16. Minimaler Go-Live-Check ## 15. Governance-Checks nach Installation oder Änderungen
Eine Installation ist im aktuellen Stand erst dann wirklich lauffähig, wenn alle folgenden Punkte erfüllt sind: Für Konfigurations- und Prompt-/Retrieval-/Commerce-Änderungen:
- Composer-Abhängigkeiten installiert ```bash
- Datenbankmigrationen erfolgreich durchgelaufen php bin/console mto:agent:config:validate
- `.env.local` korrekt gesetzt php bin/console mto:agent:config:audit-source --details
- `.venv` vorhanden und Python-Abhängigkeiten installiert php bin/console mto:agent:config:audit-patterns --details
- Vector Service läuft auf Port `8090` php bin/console mto:agent:regression:test
- Admin-Benutzer existiert ```
- aktiver System Prompt vorhanden
- aktive ModelGenerationConfig vorhanden Zur Übersicht:
- mindestens ein PDF erfolgreich ingestiert
- `mto:agent:vector:health` liefert `OK` oder `OK_EMPTY` ```bash
- Chat-Frontend und Admin-Login sind erreichbar php bin/console mto:agent:config:dump-effective --summary
```
Für reale Pfadtests:
```bash
php bin/console mto:agent:retrieval:test "niedrigster Grenzwert Wasserhärte"
php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
php bin/console mto:agent:chat cli-debug
```
--- ---
## 17. Häufige Fehlerbilder ## 16. Rollenmodell für den Betrieb
## 17.1 `No active system prompt configured.` | Rolle | Zweck |
| --- | --- |
| `ROLE_CHAT_USER` | Zugriff auf Chat, Ask/SSE, History und Frontend-Messages |
| `ROLE_ADMIN_AREA` | Adminbasis, Dashboard, Guides und Jobübersicht |
| `ROLE_EDITOR` | Dokumente, Versionen, Tags und Dokument-Ingest |
| `ROLE_KNOWLEDGE_ADMIN` | Modell-/Retrieval-Konfiguration und Ingest-Profile |
| `ROLE_SUPER_ADMIN` | Userverwaltung, Logs, System Prompt/Agent, kritische Aktionen, Global Reindex |
Ursache: `ROLE_SUPER_ADMIN` enthält alle darunterliegenden Rollen. `ROLE_USER` ist nur technische Basisrolle.
Es existiert kein aktiver System Prompt.
Lösung:
Im Admin unter `/admin/system/prompt` eine Version speichern und aktivieren.
--- ---
## 17.2 `No active ModelGenerationConfig found.` ## 17. Minimaler Go-Live-Check
Ursache: Vor produktiver Nutzung prüfen:
Es existiert keine aktive Modellkonfiguration.
Lösung: - `.env.local` enthält produktive DB-, LLM- und ggf. Shopware-Werte.
Im Admin unter `/admin/model-config/` eine Konfiguration anlegen und aktivieren. - Datenbankmigrationen sind durchgelaufen.
- Mindestens ein aktiver `ROLE_SUPER_ADMIN` existiert.
- Mindestens ein aktiver Chat-User existiert.
- Aktiver System Prompt ist vorhanden.
- Aktive ModelGenerationConfig ist vorhanden.
- Vector-Service läuft.
- Mindestens ein aktives Dokument ist ingestiert.
- `mto:agent:vector:health` ist grün.
- `mto:agent:tag:health --summary` ist grün oder bewusst initial leer.
- `mto:agent:config:validate` ist grün.
- `mto:agent:regression:test` ist grün.
- Chat-Login und Admin-Login sind getrennt erreichbar.
- 403/404/500-Seiten funktionieren im gewünschten Layout.
--- ---
## 17.3 Vector Service startet nicht ## 18. Häufige Fehlerbilder
Typische Ursachen: ### `No active system prompt configured.`
- `.venv` fehlt Im Admin einen System Prompt anlegen und aktivieren.
- Python-Pakete fehlen
- Port `8090` ist schon belegt ### `No active ModelGenerationConfig found.`
- `uvicorn` ist nicht in der virtuellen Umgebung installiert
Im Admin unter `/admin/model-config/` eine Modellkonfiguration anlegen und aktivieren.
### Vector-Service startet nicht
Prüfen: Prüfen:
```bash ```bash
source .venv/bin/activate
pip install -r requirements.txt
php bin/console mto:agent:vector:control --status php bin/console mto:agent:vector:control --status
``` ```
--- Außerdem prüfen, ob Port `8090` frei ist und `python/vector/vector_control.py` existiert.
## 17.4 Rebuild bricht mit „no active documents found“ ab ### Rebuild bricht mit `no active documents found` ab
Ursache: Mindestens ein Dokument und eine aktive, ingestierte Version anlegen.
Es wurde noch kein aktives Dokument erfolgreich angelegt.
Lösung: ### Chat zeigt Access Denied
Zuerst ein PDF hochladen und ingestieren, danach den Rebuild erneut starten.
Der Benutzer braucht `ROLE_CHAT_USER` oder eine übergeordnete Rolle.
### Admin zeigt Access Denied
Der Benutzer braucht mindestens `ROLE_ADMIN_AREA`; für Dokumente `ROLE_EDITOR`, für Modell-/Ingest-Konfiguration `ROLE_KNOWLEDGE_ADMIN`, für Userverwaltung und kritische Systemaktionen `ROLE_SUPER_ADMIN`.
### Nicht-PDF-Ingest
TXT und Markdown werden im aktuellen `DocumentLoader` unterstützt. Für andere Formate wie DOCX gibt es im aktuellen produktiven Ingest-Pfad keinen verifizierten Loader.
--- ---
## 17.5 Upload klappt, Ingest startet aber nicht ## 19. Produktionshinweise
Ursache: - Webserver auf `public/` zeigen lassen.
`exec()` ist auf dem Server deaktiviert. - Schreibrechte für `var/` sicherstellen.
- `APP_ENV=prod` und `APP_DEBUG=0` setzen.
Lösung: - Secrets nur in `.env.local` oder Secret-Management pflegen.
Job manuell mit `mto:agent:ingest:run <jobId>` starten oder Serverkonfiguration anpassen. - Vector-Service über systemd, Supervisor oder Container-Prozessmanagement betreiben.
- Logs rotieren.
- Rebuilds nicht parallel ausführen.
- Vor Änderungen an `genre.yaml`, `commerce.yaml`, `prompt.yaml` oder Retrieval-Konfiguration immer Governance-Checks ausführen.
- Regelmäßig ein Backup von Datenbank und `var/knowledge` erstellen.
--- ---
## 17.6 Dokument-Ingest schlägt bei Nicht-PDF fehl ## 20. Ergebnis
Ursache: Nach Abschluss der Installation stehen zur Verfügung:
Der aktuelle Code enthält nur einen `PdfExtractor`.
Lösung: - rollenbasierter Chat unter `/` und `/chat`
Für den aktuellen Stand ausschließlich PDFs ingestieren oder Extractor-Layer erweitern. - rollenbasierter Adminbereich unter `/admin`
- dokumentenbasierter RAG-Ingest
--- - hybrides Retrieval mit Vector- und Tag-Komponenten
- optionaler Shopware-Commercepfad
## 18. Empfohlene Produktionshinweise - SSE-Streaming für Browserantworten
- CLI-Werkzeuge für Ingest, Rebuild, Health, Governance und Debugging
Für stabilen produktiven Betrieb sind sinnvoll:
- Nginx oder Apache vor Symfony/PHP-FPM
- eigener Service-Start für den Python-Vector-Service
- eigener Service für Ollama
- Backup von Datenbank und `var/knowledge/`
- Monitoring der Logs unter `var/log/`
- bewusstes Governance-Handling für Ingest-Profile, System Prompts und Model-Konfigurationen
---
## 19. Ergebnis
Nach erfolgreicher Installation bietet der aktuelle Stand von RetrieX:
- dokumentenbasierte Wissensverwaltung
- versionierte Dokumente
- asynchronen Ingest über Jobs
- NDJSON als Wissensspeicher
- FAISS-basiertes Retrieval
- optionales Tag-Routing
- optionalen Shopware-Commerce-Pfad
- browserbasierten SSE-Chat
- Symfony-Adminoberfläche für Betrieb und Governance

873
genre_yaml_konfigurationsanleitung.md
View File

File diff suppressed because it is too large Load Diff