# Mindnet v2.2 – Admin Guide **Datei:** `docs/mindnet_admin_guide_v2.2.md` **Stand:** 2025-12-09 **Status:** **FINAL** (Inkl. RAG, Decision Engine & LLM Ops) **Quellen:** `Handbuch.md`, `mindnet_developer_guide_v2.2.md`. > Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz (API + DB + LLM). --- ## 1. Zielgruppe & Scope Mindnet ist als **Single-Node System** konzipiert, das lokal (z.B. Laptop) oder auf einem privaten Server (Homelab, Intranet) läuft. Wir unterscheiden strikt zwischen: * **Production (Port 8001):** Stabiler `main` Branch. * **Development (Port 8002):** Experimentelle Feature-Branches. --- ## 2. Initial Setup & Installation ### 2.1 Systemvoraussetzungen * **OS:** Linux (Ubuntu 22.04+ empfohlen) oder macOS. * **Runtime:** Python 3.10+, Docker (für Qdrant), Ollama (für LLM). * **Hardware:** * CPU: 4+ Cores empfohlen (für Import & Inference). * RAM: Min. 8GB empfohlen (4GB System + 4GB für Phi-3/Qdrant). * Disk: SSD empfohlen für Qdrant-Performance. ### 2.2 Installation (Code) # 1. Repository klonen git clone /home/llmadmin/mindnet cd /home/llmadmin/mindnet # 2. Umgebung einrichten python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 3. Verzeichnisse anlegen mkdir -p logs qdrant_storage data/logs ### 2.3 Qdrant Setup (Docker) Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig. docker run -d \ --name mindnet_qdrant \ --restart always \ -p 6333:6333 \ -v $(pwd)/qdrant_storage:/qdrant/storage \ qdrant/qdrant ### 2.4 Ollama Setup (LLM Service) Mindnet benötigt einen lokalen LLM-Server für den Chat. # 1. Installieren (Linux Script) curl -fsSL https://ollama.com/install.sh | sh # 2. Modell laden (Phi-3 Mini für CPU-Performance) ollama pull phi3:mini # 3. Testen curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}' ### 2.5 Konfiguration (ENV) Erstelle eine `.env` Datei im Root-Verzeichnis. Die neuen Settings für WP-06 (Timeout, Decision Config) sind essenziell für stabilen Betrieb auf CPUs. # Qdrant Verbindung QDRANT_URL="http://localhost:6333" # Mindnet Core Settings COLLECTION_PREFIX="mindnet" MINDNET_TYPES_FILE="./config/types.yaml" # LLM / RAG Settings MINDNET_LLM_MODEL="phi3:mini" MINDNET_OLLAMA_URL="http://127.0.0.1:11434" # NEU in v2.3: Config & Timeouts # Pfad zu Prompts MINDNET_PROMPTS_PATH="./config/prompts.yaml" # Pfad zur Decision Engine Config MINDNET_DECISION_CONFIG="./config/decision_engine.yaml" # Timeout in Sekunden (300s = 5min fuer Cold Starts) MINDNET_LLM_TIMEOUT=300.0 ### 2.6 Deployment via Systemd Mindnet wird als Systemdienst gestartet. Ollama läuft meist als eigener Dienst (`ollama.service`). **Production Service (`/etc/systemd/system/mindnet-prod.service`):** * Läuft auf Port 8001. * Autostart (`enabled`). * Restart Policy: `always`. * Abhängigkeit: Sollte nach `docker` und `ollama` starten. --- ## 3. Betrieb im Alltag ### 3.1 Regelmäßige Importe Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob) nach Qdrant synchronisiert werden. **Cronjob-Beispiel (stündlich):** 0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1 ### 3.2 Health-Checks Prüfe regelmäßig, ob alle drei Komponenten (API, DB, LLM) laufen. **Status prüfen:** sudo systemctl status mindnet-prod sudo systemctl status ollama **Logischer Smoke-Test:** python3 scripts/test_retriever_smoke.py --mode hybrid --url http://localhost:8001/query ### 3.3 Logs & Monitoring * **Technische Fehler (API):** `journalctl -u mindnet-prod -f` * Achte auf: `LLM Router Raw Output`. Hier siehst du, wie die Decision Engine entscheidet. * **LLM Fehler (Ollama):** `journalctl -u ollama -f` * **Fachliche Logs:** `data/logs/search_history.jsonl` **Troubleshooting Chat:** * Wenn `/chat` in den Timeout läuft (>300s): Prüfe `MINDNET_LLM_TIMEOUT` in `.env` und ob das Modell im RAM liegt. * Wenn `/chat` halluziniert: Prüfe `config/prompts.yaml` und ob der Import aktuell ist. --- ## 4. Update-Prozess Wenn neue Versionen ausgerollt werden (Deployment): 1. **Code aktualisieren:** cd /home/llmadmin/mindnet git pull origin main 2. **Dependencies prüfen:** source .venv/bin/activate pip install -r requirements.txt 3. **Dienst neustarten (Zwingend!):** sudo systemctl restart mindnet-prod 4. **Schema-Migration (falls nötig):** python3 -m scripts.import_markdown ... --apply --- ## 5. Backup & Restore Datensicherheit ruht auf drei Säulen: Vault (Source), Qdrant (Index), JSONL-Logs (Lern-Daten). ### 5.1 Vault-Backup (Priorität 1) Der Markdown-Vault ist die **Single Source of Truth**. Er muss klassisch gesichert werden (Git/NAS). ### 5.2 Qdrant-Snapshots (Priorität 2) Für schnelle Wiederherstellung des Suchindex. docker stop mindnet_qdrant tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage docker start mindnet_qdrant ### 5.3 Log-Daten (Priorität 3) Sichere den Ordner `data/logs/`. Verlust dieser Daten bedeutet, dass das System vergisst, welche Antworten Nutzer hilfreich fanden. ### 5.4 Notfall-Wiederherstellung (Rebuild) Wenn die Datenbank korrupt ist: # 1. DB komplett leeren (Wipe) python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes # 2. Alles neu importieren python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply --- ## 6. Governance & Sicherheit ### 6.1 Zugriffsschutz Mindnet hat aktuell **keine integrierte Authentifizierung**. * **API:** Muss hinter einem Reverse Proxy (Nginx) mit Basic Auth laufen. * **Qdrant:** Sollte via Firewall (ufw) auf `127.0.0.1` beschränkt sein. * **Ollama:** Standardmäßig hört Ollama nur auf `localhost`. Das ist sicher. ### 6.2 Typen-Governance Änderungen an der `types.yaml` (z.B. neue Gewichte) wirken global. * **Prozess:** Änderungen sollten getestet werden (Smoke-Test), bevor sie produktiv gehen.