558 lines
14 KiB
Markdown
558 lines
14 KiB
Markdown
# RetrieX v1.6.0 – Installationsanleitung
|
||
|
||
Stand: Version **1.6.0** auf Basis des aktuellen `rag-inprogress.zip`.
|
||
|
||
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 v1.6.0 besteht aus diesen Hauptbausteinen:
|
||
|
||
- 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 Ordner:
|
||
|
||
```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 Änderungen gegenüber älteren Ständen
|
||
|
||
- 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
|
||
|
||
Empfohlen:
|
||
|
||
- Linux Server oder VM
|
||
- Ubuntu 22.04/24.04 oder Debian 12
|
||
|
||
Lokal ist Entwicklung auch auf macOS oder WSL möglich, produktiv sollte ein regulärer Webserver mit PHP-FPM verwendet werden.
|
||
|
||
### 3.2 PHP
|
||
|
||
Erforderlich:
|
||
|
||
- PHP 8.2 oder neuer
|
||
- Composer
|
||
|
||
Relevante PHP-Erweiterungen aus `composer.json` und Runtime:
|
||
|
||
- `ctype`
|
||
- `curl`
|
||
- `dom`
|
||
- `iconv`
|
||
- `libxml`
|
||
- `pdo_mysql`
|
||
- `mbstring`
|
||
- `zip`
|
||
- `sqlite3`
|
||
|
||
Prüfen:
|
||
|
||
```bash
|
||
php -v
|
||
php -m
|
||
composer --version
|
||
```
|
||
|
||
### 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.
|
||
|
||
Empfohlen:
|
||
|
||
- MariaDB 10.11.x oder kompatibles MySQL 8.x
|
||
|
||
Beispiel:
|
||
|
||
```sql
|
||
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;
|
||
```
|
||
|
||
Die mitgelieferte `.env` kann noch Platzhalter enthalten. Für Betrieb eine eigene `.env.local` verwenden.
|
||
|
||
### 3.4 Python
|
||
|
||
Erforderlich:
|
||
|
||
- Python 3.10 oder neuer
|
||
- `python3-venv`
|
||
- `python3-pip`
|
||
|
||
Python-Abhängigkeiten aus `requirements.txt`:
|
||
|
||
- `fastapi`
|
||
- `uvicorn`
|
||
- `faiss-cpu`
|
||
- `sentence-transformers`
|
||
- `numpy`
|
||
|
||
### 3.5 LLM-Endpunkt
|
||
|
||
RetrieX spricht den LLM über `AI_LLM_API_URL` an. Erwartet wird ein Ollama-kompatibler `/api/generate`-Endpoint.
|
||
|
||
Beispiel:
|
||
|
||
```bash
|
||
curl http://127.0.0.1:11434/api/tags
|
||
```
|
||
|
||
Das konkret verwendete Modell wird über die aktive `ModelGenerationConfig` im Admin gesteuert, nicht allein über `.env`.
|
||
|
||
### 3.6 Optional: Shopware Store API
|
||
|
||
Für Commerce-/Shopfragen kann die Shopware Store API angebunden werden.
|
||
|
||
Relevante Variablen:
|
||
|
||
- `SHOPWARE_STORE_API_BASE_URL`
|
||
- `SHOPWARE_SALES_CHANNEL_ACCESS_KEY`
|
||
- `SHOPWARE_STORE_API_MAX_RESULT`
|
||
|
||
Wenn keine Shopware-Suche gewünscht ist, Commerce bewusst deaktivieren oder sauber mit leeren/ungefährlichen Testwerten konfigurieren.
|
||
|
||
---
|
||
|
||
## 4. Projekt bereitstellen
|
||
|
||
Beispiel mit ZIP:
|
||
|
||
```bash
|
||
unzip rag-inprogress.zip -d retriex
|
||
cd retriex
|
||
```
|
||
|
||
Oder über Repository-Checkout, falls der Stand in Git verwaltet wird.
|
||
|
||
---
|
||
|
||
## 5. PHP-Abhängigkeiten installieren
|
||
|
||
Entwicklung:
|
||
|
||
```bash
|
||
composer install --no-interaction
|
||
```
|
||
|
||
Produktion:
|
||
|
||
```bash
|
||
composer install --no-dev --optimize-autoloader --no-interaction
|
||
```
|
||
|
||
Danach sollte `bin/console` ausführbar sein:
|
||
|
||
```bash
|
||
php bin/console list mto:agent
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Umgebung konfigurieren
|
||
|
||
Eine lokale `.env.local` anlegen und mindestens Datenbank und LLM-Endpunkt setzen.
|
||
|
||
Beispiel:
|
||
|
||
```dotenv
|
||
APP_ENV=prod
|
||
APP_SECRET=change-me
|
||
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"
|
||
```
|
||
|
||
Optional für Shopware:
|
||
|
||
```dotenv
|
||
SHOPWARE_STORE_API_BASE_URL="https://example.invalid/store-api"
|
||
SHOPWARE_SALES_CHANNEL_ACCESS_KEY="change-me"
|
||
SHOPWARE_STORE_API_MAX_RESULT=10
|
||
```
|
||
|
||
Wichtig: keine produktiven Secrets in die versionierte `.env` schreiben.
|
||
|
||
---
|
||
|
||
## 7. Datenbank initialisieren
|
||
|
||
```bash
|
||
php bin/console doctrine:database:create --if-not-exists
|
||
php bin/console doctrine:migrations:migrate --no-interaction
|
||
```
|
||
|
||
Bei Produktionsbetrieb danach Cache aufbauen:
|
||
|
||
```bash
|
||
php bin/console cache:clear --env=prod
|
||
php bin/console cache:warmup --env=prod
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Python-Umgebung aufbauen
|
||
|
||
Virtuelle Umgebung anlegen:
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
Abhängigkeiten installieren:
|
||
|
||
```bash
|
||
pip install --upgrade pip
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
Alternativ nach angelegter `.venv` über den Symfony-Wrapper:
|
||
|
||
```bash
|
||
php bin/console mto:agent:vector:control --install
|
||
```
|
||
|
||
Der Wrapper erwartet eine vorhandene `.venv`; er legt sie nicht selbst an.
|
||
|
||
---
|
||
|
||
## 9. Vector-Service starten
|
||
|
||
Start:
|
||
|
||
```bash
|
||
php bin/console mto:agent:vector:control --start
|
||
```
|
||
|
||
Status:
|
||
|
||
```bash
|
||
php bin/console mto:agent:vector:control --status
|
||
```
|
||
|
||
Reload:
|
||
|
||
```bash
|
||
php bin/console mto:agent:vector:control --reload
|
||
```
|
||
|
||
Standardwerte aus dem aktuellen Command/Service-Setup:
|
||
|
||
- Host: `0.0.0.0`
|
||
- Port: `8090`
|
||
- PHP-Service-URL: typischerweise `http://127.0.0.1:8090`
|
||
- PID-Datei: `var/run/vector_service.pid`
|
||
|
||
---
|
||
|
||
## 10. Ersten Benutzer anlegen
|
||
|
||
Ohne Benutzer ist weder Chat noch Admin sinnvoll nutzbar.
|
||
|
||
```bash
|
||
php bin/console mto:agent:user:create
|
||
```
|
||
|
||
Der Command fragt ab:
|
||
|
||
- E-Mail
|
||
- Passwort mit Wiederholung
|
||
- eine oder mehrere Rollen
|
||
- Aktivstatus
|
||
|
||
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
|
||
|
||
Lokaler Test:
|
||
|
||
```bash
|
||
php -S 127.0.0.1:8000 -t public
|
||
```
|
||
|
||
Relevante Einstiegspunkte:
|
||
|
||
- 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 Nginx/Apache + PHP-FPM verwenden und `public/` als Document Root setzen.
|
||
|
||
---
|
||
|
||
## 12. Pflicht-Initialisierung im Admin
|
||
|
||
### 12.1 System Prompt anlegen
|
||
|
||
Pfad:
|
||
|
||
```text
|
||
/admin/system/prompt
|
||
```
|
||
|
||
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
|
||
|
||
Vollständiger Hard-Rebuild:
|
||
|
||
```bash
|
||
php bin/console mto:agent:system:rebuild --hard
|
||
```
|
||
|
||
Optionen:
|
||
|
||
```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
|
||
```
|
||
|
||
Health-Checks:
|
||
|
||
```bash
|
||
php bin/console mto:agent:vector:health
|
||
php bin/console mto:agent:tag:health --summary
|
||
```
|
||
|
||
Tag-Retrieval neu aufbauen:
|
||
|
||
```bash
|
||
php bin/console mto:agent:tags:rebuild
|
||
```
|
||
|
||
---
|
||
|
||
## 15. Governance-Checks nach Installation oder Änderungen
|
||
|
||
Für Konfigurations- und Prompt-/Retrieval-/Commerce-Änderungen:
|
||
|
||
```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
|
||
```
|
||
|
||
---
|
||
|
||
## 16. Rollenmodell für den Betrieb
|
||
|
||
| 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 |
|
||
|
||
`ROLE_SUPER_ADMIN` enthält alle darunterliegenden Rollen. `ROLE_USER` ist nur technische Basisrolle.
|
||
|
||
---
|
||
|
||
## 17. Minimaler Go-Live-Check
|
||
|
||
Vor produktiver Nutzung prüfen:
|
||
|
||
- `.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.
|
||
|
||
---
|
||
|
||
## 18. Häufige Fehlerbilder
|
||
|
||
### `No active system prompt configured.`
|
||
|
||
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.
|
||
|
||
### Rebuild bricht mit `no active documents found` ab
|
||
|
||
Mindestens ein Dokument und eine aktive, ingestierte Version anlegen.
|
||
|
||
### 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.
|
||
|
||
---
|
||
|
||
## 19. Produktionshinweise
|
||
|
||
- 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.
|
||
|
||
---
|
||
|
||
## 20. Ergebnis
|
||
|
||
Nach Abschluss der Installation stehen zur Verfügung:
|
||
|
||
- 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
|