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

692
INSTALL.md
View File

@@ -1,315 +1,242 @@
# RetrieX – Installationsanleitung
# RetrieX v1.6.0 – Installationsanleitung
Stand: 15.04.2026
Quelle: aktuelle `rag.zip` (Single Source of Truth)
Stand: Version **1.6.0** auf Basis des aktuellen `rag-inprogress.zip`.
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
RetrieX besteht aktuell aus diesen Hauptbausteinen:
RetrieX v1.6.0 besteht aus diesen Hauptbausteinen:
- **Symfony 7.4** auf **PHP 8.2+**
- **Doctrine ORM + Doctrine Migrations**
- **MariaDB/MySQL** als operative Datenbank
- **Python-Vektorlayer** mit `faiss-cpu`, `sentence-transformers`, `fastapi`, `uvicorn`
- **Ollama-kompatibler LLM-Endpunkt** über `AI_LLM_API_URL`
- **NDJSON + FAISS** im Dateisystem unter `var/knowledge`
- **Adminoberfläche** für Dokumente, Ingest-Profile, System Prompt, Modellkonfiguration und Jobs
- **SSE-Streaming** für den Browser-Chat
- Symfony 7.4 auf PHP 8.2+
- Doctrine ORM und Doctrine Migrations
- MariaDB/MySQL-orientierte Migrationen mit binären UUIDs
- dateibasierte Knowledge-Artefakte unter `var/knowledge`
- Python-Vektorlayer mit FastAPI, uvicorn, FAISS und SentenceTransformers
- Ollama-kompatibler LLM-Generate-Endpunkt über `AI_LLM_API_URL`
- hybrides Retrieval über NDJSON, FAISS, Keyword-/Lexical-Komponenten und Tag-Routing
- 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
- `var/log/` → System-, Agent- und Ingest-Logs
- `var/run/` → PID-Dateien des Python-Services
- `var/locks/` → Ingest-Lock
- `python/vector/` → Python-Control-, Search- und Service-Skripte
```text
var/knowledge/ NDJSON, FAISS-Indizes, Tags, Uploads
var/log/ Symfony-, Agent-, Ingest- und Vector-Logs
var/run/ PID-Dateien, z. B. vector_service.pid
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:
- Der Wissensspeicher liegt unter **`var/knowledge/`**, nicht unter `var/vector/`.
- Der Python-Code liegt unter **`python/vector/`**, nicht unter `vector/`.
- Die Python-Abhängigkeiten kommen aus der Datei **`requirements.txt` im Projektroot**.
- Der korrekte Rebuild-Befehl ist **`mto:agent:system:rebuild --hard`**, nicht `mto:agent:ingest:global`.
- Das LLM-Modell kommt **nicht** mehr aus einer `AI_LLM_MODEL`-Umgebungsvariable, sondern aus der **aktiven ModelGenerationConfig** in der Adminoberfläche.
- Für den Chat sind **zwingend** nötig:
- ein **aktiver System Prompt**
- eine **aktive ModelGenerationConfig**
- 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**.
- 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.
- Admin-Routen liegen unter `/admin...`; Chat-/Ask-/SSE-/History-Routen liegen in der Chat-Firewall.
- `ROLE_USER` allein reicht nicht mehr für Chat oder Admin.
- `ROLE_CHAT_USER` schaltet Chat-Zugriff frei.
- `ROLE_ADMIN_AREA`, `ROLE_EDITOR`, `ROLE_KNOWLEDGE_ADMIN` und `ROLE_SUPER_ADMIN` schalten Adminbereiche gestuft frei.
- Die CLI umfasst inzwischen 21 projektspezifische Commands unter `mto:agent:*`.
- `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.
- Der produktive Loader unterstützt PDF, TXT und Markdown (`.md`).
- `genre.yaml` ist die zentrale fachliche Source-of-Truth für Produktrollen, Query-Guards, Follow-up-Auflösung und Regression-Anker.
---
## 3. Systemvoraussetzungen
## 3.1 Betriebssystem
### 3.1 Betriebssystem
Empfohlen:
- Ubuntu 22.04 LTS oder neuer
- Debian 12 ist ebenfalls passend
- Linux Server oder VM
- 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:
- **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`
- `curl`
- `dom`
- `iconv`
- `libxml`
- `pdo`
- `pdo_mysql`
- `mbstring`
- `zip`
- `sqlite3`
Prüfen:
```bash
php -v
php -m
```
---
## 3.3 Composer
Prüfen:
```bash
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
---
## 3.4 Datenbank
Der aktuelle Projektstand ist praktisch auf **MariaDB/MySQL** ausgerichtet.
Die mitgelieferten Migrationen sind praktisch auf MariaDB/MySQL ausgelegt, z. B. durch `BINARY(16)`, `TINYINT`, `LONGTEXT`, `JSON` und MariaDB-kompatible UUID-Strukturen.
Empfohlen:
- **MariaDB 10.11.x**
- MariaDB 10.11.x oder kompatibles MySQL 8.x
Beispielinstallation:
```bash
sudo apt install mariadb-server
```
Beispiel für Datenbank und Benutzer:
Beispiel:
```sql
CREATE DATABASE db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'db'@'%' IDENTIFIED BY 'db';
GRANT ALL PRIVILEGES ON db.* TO 'db'@'%';
CREATE DATABASE retriex CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'retriex'@'%' IDENTIFIED BY 'change-me';
GRANT ALL PRIVILEGES ON retriex.* TO 'retriex'@'%';
FLUSH PRIVILEGES;
```
Hinweis:
Die mitgelieferte `.env` enthält derzeit noch eine PostgreSQL-Placeholder-URL. Für den realen Betrieb muss `DATABASE_URL` auf **MariaDB/MySQL** gesetzt werden.
Die mitgelieferte `.env` kann noch Platzhalter enthalten. Für Betrieb eine eigene `.env.local` verwenden.
---
## 3.5 Python
### 3.4 Python
Erforderlich:
- **Python 3.10 oder höher**
- Python 3.10 oder neuer
- `python3-venv`
- `python3-pip`
Installation:
Python-Abhängigkeiten aus `requirements.txt`:
```bash
sudo apt install python3 python3-venv python3-pip
```
- `fastapi`
- `uvicorn`
- `faiss-cpu`
- `sentence-transformers`
- `numpy`
Prüfen:
### 3.5 LLM-Endpunkt
```bash
python3 --version
```
RetrieX spricht den LLM über `AI_LLM_API_URL` an. Erwartet wird ein Ollama-kompatibler `/api/generate`-Endpoint.
---
## 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:
Beispiel:
```bash
curl http://127.0.0.1:11434/api/tags
```
Wichtig:
Welches Modell tatsächlich benutzt wird, bestimmt später die **aktive ModelGenerationConfig im Admin**, nicht eine `.env`-Variable.
Das konkret verwendete Modell wird über die aktive `ModelGenerationConfig` im Admin gesteuert, nicht allein über `.env`.
---
### 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.
Dafür werden diese Variablen verwendet:
Relevante Variablen:
- `SHOPWARE_STORE_API_BASE_URL`
- `SHOPWARE_SALES_CHANNEL_ACCESS_KEY`
- `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
ZIP entpacken und ins Projekt wechseln:
Beispiel mit ZIP:
```bash
unzip rag.zip -d retriex
unzip rag-inprogress.zip -d 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
Entwicklung:
```bash
composer install --no-interaction
```
Für Produktion:
Produktion:
```bash
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.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:
---
## 6.2 Minimale `.env.local`
Beispiel für einen lokalen oder servernahen MariaDB-Betrieb:
```env
```dotenv
APP_ENV=prod
APP_SECRET=change-me
DATABASE_URL="mysql://db:db@127.0.0.1:3306/db?serverVersion=10.11.0-mariadb&charset=utf8mb4"
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
DATABASE_URL="mysql://retriex:change-me@127.0.0.1:3306/retriex?serverVersion=10.11.2-MariaDB&charset=utf8mb4"
AI_LLM_API_URL="http://127.0.0.1:11434/api/generate"
```
Hinweise:
Optional für Shopware:
- `APP_ENV=prod` ist im aktuellen `.env` bereits voreingestellt.
- `DATABASE_URL` muss auf MariaDB/MySQL zeigen.
- `AI_LLM_API_URL` muss auf einen funktionierenden `/api/generate`-Endpoint zeigen.
- `AI_LLM_TIMEOUT=600` ist mit dem aktuellen Code konsistent.
- `AI_LLM_MODEL` wird **nicht** verwendet.
```dotenv
SHOPWARE_STORE_API_BASE_URL="https://example.invalid/store-api"
SHOPWARE_SALES_CHANNEL_ACCESS_KEY="change-me"
SHOPWARE_STORE_API_MAX_RESULT=10
```
---
## 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.
Wichtig: keine produktiven Secrets in die versionierte `.env` schreiben.
---
## 7. Datenbank initialisieren
Migrationen ausführen:
```bash
php bin/console doctrine:database:create --if-not-exists
php bin/console doctrine:migrations:migrate --no-interaction
```
Damit werden unter anderem diese zentralen Tabellen angelegt:
Bei Produktionsbetrieb danach Cache aufbauen:
- `user`
- `document`
- `document_version`
- `ingest_job`
- `system_prompt`
- `ingest_profile`
- `model_generation_config`
- `knowledge_tag`
- `document_tag`
- `tag_rebuild_job`
```bash
php bin/console cache:clear --env=prod
php bin/console cache:warmup --env=prod
```
---
## 8. Python-Umgebung aufbauen
## 8.1 Virtuelle Umgebung anlegen
Virtuelle Umgebung anlegen:
```bash
python3 -m venv .venv
source .venv/bin/activate
```
---
## 8.2 Python-Abhängigkeiten installieren
Manuell:
Abhängigkeiten installieren:
```bash
pip install --upgrade pip
@@ -322,12 +249,11 @@ Alternativ nach angelegter `.venv` über den Symfony-Wrapper:
php bin/console mto:agent:vector:control --install
```
Wichtig:
Der Wrapper erwartet bereits eine existierende `.venv`. Er erzeugt sie **nicht** selbst.
Der Wrapper erwartet eine vorhandene `.venv`; er legt sie nicht selbst an.
---
## 9. Vector Service starten
## 9. Vector-Service starten
Start:
@@ -335,335 +261,297 @@ Start:
php bin/console mto:agent:vector:control --start
```
Status prüfen:
Status:
```bash
php bin/console mto:agent:vector:control --status
```
Optionaler Reload:
Reload:
```bash
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`
- Port: `8090`
Der PHP-Code spricht standardmäßig gegen:
- `http://127.0.0.1:8090`
- PHP-Service-URL: typischerweise `http://127.0.0.1:8090`
- PID-Datei: `var/run/vector_service.pid`
---
## 10. Admin-Benutzer anlegen
## 10. Ersten Benutzer anlegen
Ohne Admin-Benutzer lässt sich das System nicht fertig konfigurieren.
CLI-Befehl:
Ohne Benutzer ist weder Chat noch Admin sinnvoll nutzbar.
```bash
php bin/console mto:agent:user:create
```
Der Command fragt interaktiv ab:
Der Command fragt ab:
- E-Mail
- Passwort
- Rolle
- Passwort mit Wiederholung
- eine oder mehrere Rollen
- Aktivstatus
Für die Erstinstallation ist typischerweise sinnvoll:
- `ROLE_SUPER_ADMIN`
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.
---
## 11. Anwendung starten
Für einen einfachen lokalen Test:
Lokaler Test:
```bash
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`
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
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:
- `/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>
```text
/admin/system/prompt
```
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.1 Vollständiger System-Rebuild
Sobald aktive Dokumente vorhanden sind, kann ein vollständiger Rebuild ausgeführt werden:
Vollständiger Hard-Rebuild:
```bash
php bin/console mto:agent:system:rebuild --hard
```
Dieser Ablauf umfasst aktuell:
Optionen:
1. globalen Reindex der aktiven Dokumente
2. Tag-Export und Tag-Index-Rebuild
3. Reload des Vector Service
4. Health-Checks
```bash
php bin/console mto:agent:system:rebuild --hard --dry-run
php bin/console mto:agent:system:rebuild --hard --no-tags
php bin/console mto:agent:system:rebuild --hard --no-reload
php bin/console mto:agent:system:rebuild --hard --no-health
```
Wichtig:
Der Befehl bricht absichtlich ab, wenn **keine aktiven Dokumente** vorhanden sind.
---
## 14.2 Vector Health prüfen
Health-Checks:
```bash
php bin/console mto:agent:vector:health
php bin/console mto:agent:tag:health --summary
```
Mögliche gesunde Zustände:
- `OK_EMPTY` → noch keine Wissensdaten vorhanden
- `OK` → NDJSON und FAISS konsistent
---
## 14.3 Tag Health prüfen
Tag-Retrieval neu aufbauen:
```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: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
- Datenbankmigrationen erfolgreich durchgelaufen
- `.env.local` korrekt gesetzt
- `.venv` vorhanden und Python-Abhängigkeiten installiert
- Vector Service läuft auf Port `8090`
- Admin-Benutzer existiert
- aktiver System Prompt vorhanden
- aktive ModelGenerationConfig vorhanden
- mindestens ein PDF erfolgreich ingestiert
- `mto:agent:vector:health` liefert `OK` oder `OK_EMPTY`
- Chat-Frontend und Admin-Login sind erreichbar
```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
```
Zur Übersicht:
```bash
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:
Es existiert kein aktiver System Prompt.
Lösung:
Im Admin unter `/admin/system/prompt` eine Version speichern und aktivieren.
`ROLE_SUPER_ADMIN` enthält alle darunterliegenden Rollen. `ROLE_USER` ist nur technische Basisrolle.
---
## 17.2 `No active ModelGenerationConfig found.`
## 17. Minimaler Go-Live-Check
Ursache:
Es existiert keine aktive Modellkonfiguration.
Vor produktiver Nutzung prüfen:
Lösung:
Im Admin unter `/admin/model-config/` eine Konfiguration anlegen und aktivieren.
- `.env.local` enthält produktive DB-, LLM- und ggf. Shopware-Werte.
- 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
- Python-Pakete fehlen
- Port `8090` ist schon belegt
- `uvicorn` ist nicht in der virtuellen Umgebung installiert
Im Admin einen System Prompt anlegen und aktivieren.
### `No active ModelGenerationConfig found.`
Im Admin unter `/admin/model-config/` eine Modellkonfiguration anlegen und aktivieren.
### Vector-Service startet nicht
Prüfen:
```bash
source .venv/bin/activate
pip install -r requirements.txt
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:
Es wurde noch kein aktives Dokument erfolgreich angelegt.
Mindestens ein Dokument und eine aktive, ingestierte Version anlegen.
Lösung:
Zuerst ein PDF hochladen und ingestieren, danach den Rebuild erneut starten.
### Chat zeigt Access Denied
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:
`exec()` ist auf dem Server deaktiviert.
Lösung:
Job manuell mit `mto:agent:ingest:run <jobId>` starten oder Serverkonfiguration anpassen.
- Webserver auf `public/` zeigen lassen.
- Schreibrechte für `var/` sicherstellen.
- `APP_ENV=prod` und `APP_DEBUG=0` setzen.
- Secrets nur in `.env.local` oder Secret-Management pflegen.
- 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:
Der aktuelle Code enthält nur einen `PdfExtractor`.
Nach Abschluss der Installation stehen zur Verfügung:
Lösung:
Für den aktuellen Stand ausschließlich PDFs ingestieren oder Extractor-Layer erweitern.
---
## 18. Empfohlene Produktionshinweise
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
- rollenbasierter Chat unter `/` und `/chat`
- rollenbasierter Adminbereich unter `/admin`
- dokumentenbasierter RAG-Ingest
- hybrides Retrieval mit Vector- und Tag-Komponenten
- optionaler Shopware-Commercepfad
- SSE-Streaming für Browserantworten
- CLI-Werkzeuge für Ingest, Rebuild, Health, Governance und Debugging