From 71f86f112b8fb1b9d3b1d696315b164a6d0327f1 Mon Sep 17 00:00:00 2001 From: team2 Date: Thu, 26 Feb 2026 21:07:24 +0100 Subject: [PATCH] add new guide files --- COMMAND_REF.md | 294 ++++++++++++++++++++++++++++++++++++ INSTALL.md | 402 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 696 insertions(+) create mode 100644 COMMAND_REF.md create mode 100644 INSTALL.md diff --git a/COMMAND_REF.md b/COMMAND_REF.md new file mode 100644 index 0000000..cf2817c --- /dev/null +++ b/COMMAND_REF.md @@ -0,0 +1,294 @@ +# RAG System – CLI Command Reference +**Projektstand: rag.zip (aktueller Code-Stand)** +Namespace-Konvention: `mto:agent:*` + +Diese Dokumentation beschreibt alle verfügbaren Symfony-Console-Commands des Systems inklusive Zweck, Einsatzszenario und typischer Aufrufe. + +--- + +# 1. Agent / Chat + +## `mto:agent:chat` +Interaktiver CLI-Chat mit dem Agenten. + +**Zweck** +- Direkter Zugriff auf AgentRunner +- Streaming-Ausgabe im Terminal +- Nutzt vollständige Retrieval- und Prompt-Logik + +**Start** +```bash +bin/console mto:agent:chat +``` + +**Eigenschaften** +- Streaming-first +- Think-Suppression wird im AgentRunner gesteuert +- Voller Kontext + Retrieval aktiv + +--- + +# 2. Dokument-Ingest + +## `mto:agent:ingest:version` +Ingest einer konkreten Dokumentversion. + +**Zweck** +- Chunking +- NDJSON-Append / Compaction +- Vollständiger FAISS-Rebuild +- index_meta.json Update + +**Beispiel** +```bash +bin/console mto:agent:ingest:version +``` + +--- + +## `mto:agent:ingest:run` +Führt einen einzelnen IngestJob aus. + +**Zweck** +- Job-basierte Verarbeitung (QUEUE → RUNNING → COMPLETED/FAILED) +- Wird intern bei Aktivierung einer Dokumentversion verwendet + +**Beispiel** +```bash +bin/console mto:agent:ingest:run +``` + +--- + +## `mto:agent:vector:rebuild` +Erzwingt vollständigen Vector-Rebuild aus `index.ndjson`. + +**Zweck** +- FAISS komplett neu aufbauen +- Kein Re-Chunking +- Reine Vektor-Neuerstellung + +```bash +bin/console mto:agent:vector:rebuild +``` + +--- + +# 3. Vector Service (Python / FastAPI) + +## `mto:agent:vector:control` +Steuert den persistenten Python-Vector-Service. + +**Beschreibung** +Production-sicheres Management des uvicorn-FastAPI-Dienstes. + +### Optionen + +| Option | Beschreibung | +|--------|--------------| +| `--install` | Fehlende Python-Dependencies installieren | +| `--start` | Service starten | +| `--stop` | Service stoppen | +| `--force` | Hard-Stop (SIGKILL) | +| `--reload` | /reload Trigger | +| `--status` | Status anzeigen | +| `--foreground` | Vordergrundstart | +| `--port=8090` | Port | +| `--host=0.0.0.0` | Host | + +### Beispiele + +Installieren: +```bash +bin/console mto:agent:vector:control --install +``` + +Starten: +```bash +bin/console mto:agent:vector:control --start +``` + +Status: +```bash +bin/console mto:agent:vector:control --status +``` + +Reload: +```bash +bin/console mto:agent:vector:control --reload +``` + +--- + +## `mto:agent:vector:health` +Gesundheitscheck von: + +- index.ndjson +- vector.index +- index_meta.json +- Embedding-Dimensionen +- Konsistenz + +```bash +bin/console mto:agent:vector:health +``` + +Ausgabe erfolgt als JSON. + +--- + +## `mto:agent:test-vector` +Testet direkte Vector-Suche. + +```bash +bin/console mto:agent:test-vector "Suchanfrage" +``` + +--- + +# 4. Tag-System + +## `mto:agent:tags:export` +Exportiert alle Tags in `tags.ndjson`. + +**Zweck** +- Grundlage für tag-basiertes Routing +- Keine Vector-Erstellung + +```bash +bin/console mto:agent:tags:export +``` + +--- + +## `mto:agent:tags:rebuild` +Vollständiger Tag-Rebuild: + +1. Export `tags.ndjson` +2. Erstellen von `vector_tags.index` +3. index_meta.json Update + +```bash +bin/console mto:agent:tags:rebuild +``` + +--- + +## `mto:agent:tags:job:run` +Führt einen einzelnen TagRebuildJob aus. + +**Mit Lock-Mechanismus.** + +```bash +bin/console mto:agent:tags:job:run +``` + +--- + +# 5. User-Management + +## `mto:agent:user:create` +Erstellt einen neuen Admin-User. + +Interaktiver Ablauf: +- E-Mail +- Passwort +- Rollenwahl + +```bash +bin/console mto:agent:user:create +``` + +--- + +# 6. Architektur-Zusammenhang der Commands + +| Bereich | Command-Typ | +|----------|------------| +| Dokumente | ingest:version | +| Jobs | ingest:run | +| Vector Index | vector:rebuild | +| Vector Service | vector:control | +| Vector Health | vector:health | +| Tag Export | tags:export | +| Tag Rebuild | tags:rebuild | +| Tag Job | tags:job:run | +| Agent CLI | chat | +| User | user:create | + +--- + +# 7. Typischer Produktions-Workflow + +### 1️⃣ Dokument aktivieren +→ erzeugt IngestJob + +### 2️⃣ Job ausführen +```bash +bin/console mto:agent:ingest:run +``` + +### 3️⃣ Vector-Service prüfen +```bash +bin/console mto:agent:vector:health +``` + +### 4️⃣ Optional: Service reload +```bash +bin/console mto:agent:vector:control --reload +``` + +--- + +# 8. System-Ebenen + +| Ebene | Technologie | +|--------|------------| +| Symfony | PHP / Doctrine | +| Retrieval | NDJSON + FAISS | +| Vector Service | Python FastAPI | +| Persistence | index.ndjson | +| Governance | index_meta.json | +| Streaming | SSE | +| CLI | Symfony Console | + +--- + +# 9. Wichtige Dateien (Runtime) + +``` +var/ + ├── run/ + │ └── vector.pid + ├── index.ndjson + ├── index_meta.json + ├── vector.index + └── vector_tags.index +``` + +--- + +# 10. Sicherheit & Locks + +- IngestFlow schützt mit LockService +- Tag-Rebuild verwendet File-Lock +- Vector-Service PID-basiert +- Global Rebuild atomar via `.tmp` + rename() + +--- + +# 11. Empfohlene Admin-Checks + +Regelmäßig ausführen: + +```bash +bin/console mto:agent:vector:health +``` + +Bei Änderungen am Embedding-Modell: +→ vollständiger Rebuild + +--- + +# Ende der Command-Dokumentation +System-Stand: rag.zip (aktueller Projektzustand) \ No newline at end of file diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..fbad37e --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,402 @@ +# 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 \ No newline at end of file