marek/MtoRagSystem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6e2ca15e97492a76b05832944cd400fe0d011932
MtoRagSystem/INSTALL.md
team 1 a01ca045dc update .md
2026-05-11 19:16:51 +02:00

14 KiB
Raw Blame History

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:

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:

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:

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:

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:

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:

composer install --no-interaction

Produktion:

composer install --no-dev --optimize-autoloader --no-interaction

Danach sollte bin/console ausführbar sein:

php bin/console list mto:agent

6. Umgebung konfigurieren

Eine lokale .env.local anlegen und mindestens Datenbank und LLM-Endpunkt setzen.

Beispiel:

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:

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

php bin/console doctrine:database:create --if-not-exists
php bin/console doctrine:migrations:migrate --no-interaction

Bei Produktionsbetrieb danach Cache aufbauen:

php bin/console cache:clear --env=prod
php bin/console cache:warmup --env=prod

8. Python-Umgebung aufbauen

Virtuelle Umgebung anlegen:

python3 -m venv .venv
source .venv/bin/activate

Abhängigkeiten installieren:

pip install --upgrade pip
pip install -r requirements.txt

Alternativ nach angelegter .venv über den Symfony-Wrapper:

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:

php bin/console mto:agent:vector:control --start

Status:

php bin/console mto:agent:vector:control --status

Reload:

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.

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:

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:

/admin/system/prompt

Ohne aktiven System Prompt kann der finale PromptBuilder keine saubere Antwortgrundlage erzeugen.

12.2 ModelGenerationConfig anlegen

Pfad:

/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:

/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:

php bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>

Vorhandenen Job ausführen:

php bin/console mto:agent:ingest:run <jobUuid>

14. Rebuild und Konsistenzprüfung

Vollständiger Hard-Rebuild:

php bin/console mto:agent:system:rebuild --hard

Optionen:

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:

php bin/console mto:agent:vector:health
php bin/console mto:agent:tag:health --summary

Tag-Retrieval neu aufbauen:

php bin/console mto:agent:tags:rebuild

15. Governance-Checks nach Installation oder Änderungen

Für Konfigurations- und Prompt-/Retrieval-/Commerce-Änderungen:

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:

php bin/console mto:agent:config:dump-effective --summary

Für reale Pfadtests:

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:

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
Reference in New Issue View Git Blame Copy Permalink