402 lines
5.6 KiB
Markdown
402 lines
5.6 KiB
Markdown
# 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 <repository>
|
||
cd <repository>
|
||
```
|
||
|
||
---
|
||
|
||
## 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 |