# RAG-System – Enterprise Installationsanleitung Stand: Februar 2026 Architektur: Symfony (PHP 8.2+) + MariaDB 10.11 + Python Vector Service (FAISS) + Ollama LLM Betriebsmodus: On-Prem / Containerfähig / CPU-basiert Diese Anleitung beschreibt eine vollständige Neuinstallation auf sauberer Infrastruktur. --- # 1. Systemvoraussetzungen ## 1.1 Betriebssystem Empfohlen: - Ubuntu 22.04 LTS (Server) Alternativ: - Debian 12 - macOS (Entwicklung) - Windows nur via WSL2 --- ## 1.2 PHP Version: - PHP 8.2 oder höher Erforderliche Extensions: - pdo - pdo_mysql - mbstring - intl - curl - json - zip Prüfung: ```bash php -v php -m ``` --- ## 1.3 Composer ```bash composer --version ``` Falls nicht vorhanden: ```bash sudo apt install composer ``` --- ## 1.4 Datenbank Version: - MariaDB 10.11.x (entspricht aktueller ENV) Installation: ```bash sudo apt install mariadb-server ``` Datenbank und Benutzer anlegen: ```sql CREATE DATABASE db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'db'@'%' IDENTIFIED BY 'db'; GRANT ALL PRIVILEGES ON db.* TO 'db'@'%'; FLUSH PRIVILEGES; ``` --- ## 1.5 Python Version: - Python 3.10 oder höher Installation: ```bash sudo apt install python3 python3-venv python3-pip ``` Prüfen: ```bash python3 --version ``` --- ## 1.6 Ollama (LLM Backend) Installation: ```bash curl -fsSL https://ollama.com/install.sh | sh ``` Modell bereitstellen: ```bash ollama pull qwen3 oder ollama pull mto-model (Wenn eigens KI-Model erstellt wurde) ``` Verfügbarkeit prüfen: ```bash curl http://127.0.0.1:11434/api/tags ``` --- # 2. Projektbereitstellung ## 2.1 Entpacken ```bash unzip rag.zip cd rag ``` oder via Git: ```bash git clone cd ``` --- ## 2.2 PHP-Abhängigkeiten installieren ```bash composer install --no-interaction ``` Für Produktion: ```bash composer install --no-dev --optimize-autoloader ``` --- # 3. Environment-Konfiguration Datei `.env` im Projektroot konfigurieren. ## 3.1 Symfony Core ```env APP_ENV=dev APP_SECRET=09333662211af45850ff13d68a40f8e3 ``` Produktion: ```env APP_ENV=prod ``` --- ## 3.2 AI Agent Core ```env AI_LLM_API_URL=http://host.docker.internal:11434/api/generate AI_LLM_MODEL=mto-model AI_LLM_TIMEOUT=600 AI_HISTORY_DIR=var/agent-history AI_CONTEXT_LINES=20 AI_CONTEXT_LINES_FULL=500 ``` Hinweise: - Timeout unter 600 Sekunden wird nicht empfohlen. - API-URL an Infrastruktur anpassen (Docker vs. Localhost). --- ## 3.3 Debug-Konfiguration ```env AI_DEBUG=false AI_LOG_PROMPT=false AI_LOG_CONTEXT=false ``` In Entwicklungsumgebung optional aktivieren. --- ## 3.4 Datenbank (aktive Konfiguration) Nur diese DATABASE_URL verwenden: ```env DATABASE_URL="mysql://db:db@db:3306/db?sslmode=disable&charset=utf8mb4&serverVersion=10.11.0-mariadb" DATABASE_VERSION="10.11.0-mariadb" DATABASE_DRIVER="mysql" DATABASE_HOST="db" DATABASE_PORT="3306" DATABASE_USER="db" DATABASE_PASSWORD="db" DATABASE_NAME="db" DATABASE_SERVER="mysql://db:3306" ``` Wichtig: - PostgreSQL-Konfiguration entfernen. - Nur eine DATABASE_URL definieren. --- ## 3.5 Messenger ```env MESSENGER_TRANSPORT_DSN=doctrine://default?auto_setup=0 ``` Queue läuft über Datenbank. --- ## 3.6 Mailer (optional) ```env MAILER_DSN="smtp://127.0.0.1:1025" MAILER_HOST="127.0.0.1" MAILER_PORT="1025" MAILER_DRIVER="smtp" MAILER_AUTH_MODE="" MAILER_USERNAME="" MAILER_PASSWORD="" MAILER_CATCHER="1" MAILER_WEB_URL="https://rag.ddev.site:8026" ``` Nur relevant wenn Mailfunktionen aktiv genutzt werden. --- # 4. Datenbankmigration ```bash php bin/console doctrine:migrations:migrate --no-interaction ``` --- # 5. Python Vector Service ## 5.1 Virtual Environment anlegen ```bash python3 -m venv .venv source .venv/bin/activate ``` --- ## 5.2 Abhängigkeiten installieren Automatisiert: ```bash php bin/console mto:agent:vector:control --install ``` Alternativ manuell: ```bash pip install fastapi uvicorn sentence-transformers faiss-cpu numpy ``` CPU-Version von FAISS ist ausreichend. --- ## 5.3 Vector Service starten ```bash php bin/console mto:agent:vector:control --start ``` Status prüfen: ```bash php bin/console mto:agent:vector:control --status ``` --- # 6. Initialer Reindex Vor produktiver Nutzung zwingend erforderlich: ```bash php bin/console mto:agent:ingest:global ``` Ohne Reindex ist kein Retrieval möglich. --- # 7. Anwendung starten Entwicklung: ```bash php -S 127.0.0.1:8000 -t public ``` Produktion: - Über Nginx oder Apache bereitstellen - APP_ENV=prod setzen - Cache warmup durchführen ```bash php bin/console cache:clear --env=prod php bin/console cache:warmup --env=prod ``` --- # 8. Funktionstest 1. Datenbank erreichbar 2. Migration erfolgreich 3. Vector Service aktiv 4. Ollama erreichbar 5. Global Reindex durchgeführt 6. Dokument hochgeladen 7. Version aktiviert 8. Chat liefert Antwort --- # 9. Betriebsrelevante Hinweise ## Modellwechsel Bei Änderung von: - AI_LLM_MODEL Kein Reindex erforderlich. Bei Änderung von: - Embedding-Modell (Python-Seite) - Embedding-Dimension - Chunking-Parametern Global Reindex zwingend erforderlich. --- ## NDJSON und Vector Index Speicherort: ``` var/vector/ ``` Nicht manuell verändern. Index ist deterministisch und wird vollständig neu aufgebaut. --- ## Produktionsbetrieb Empfohlen: - Reverse Proxy (Nginx) - Systemd Service für Vector Service - Eigener Service für Ollama - Backup von Datenbank + var/vector/ --- # Installation abgeschlossen Das System ist betriebsbereit für: - Versionierte Dokumentverwaltung - Deterministischen NDJSON-Ingest - FAISS-Vektorindex - Hybrid Retrieval - LLM-gestützte Antwortgenerierung