--- doc_type: operations_manual audience: admin, devops scope: deployment, maintenance, backup, edge_registry, moe, lazy_prompts status: active version: 3.1.1 context: "Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v3.1.1 inklusive WP-25a Mixture of Experts (MoE) und WP-25b Lazy-Prompt-Orchestration Konfiguration." --- # Admin Operations Guide ## 1. Installation & Setup ### 1.1 Voraussetzungen * **OS:** Ubuntu 22.04+ (empfohlen). * **Tools:** Python 3.10+, Docker, Ollama. * **Hardware:** Min. 8GB RAM, 4 CPU Cores (für Async Import). ### 1.2 Qdrant (Docker) Startet die Vektor-DB mit persistentem Storage auf Port 6333. dockercompose.yaml ```bash services: qdrant: image: qdrant/qdrant container_name: qdrant ports: - "6333:6333" volumes: - ./qdrant_data:/qdrant/storage ulimits: nofile: soft: 65535 hard: 65535 restart: unless-stopped ``` ```bash docker compose up -d ``` Um Abstürze der Vektordatenbank bei einer hohen Anzahl an Collections (z. B. durch viele Notiz-Typen oder Dev-Umgebungen) zu vermeiden, müssen die System-Limits für den Container angepasst werden. Hintergrund: Qdrant öffnet für jedes Segment einer Collection mehrere Dateien. Ohne diese Erhöhung führt das Standard-Linux-Limit (1024) zum Absturz mit dem Fehler os error 24 (Too many open files). ### 1.3 Ollama (Modelle) **Wichtig:** Seit v2.4 ist `nomic-embed-text` Pflicht für Embeddings. Seit WP-25a wird die Modell-Konfiguration zentral über `llm_profiles.yaml` gesteuert. ```bash # Modelle laden ollama pull phi3:mini ollama pull nomic-embed-text # Testen curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}' ``` **WP-25a: LLM-Profil-Konfiguration** Die LLM-Steuerung erfolgt nun primär über `config/llm_profiles.yaml` statt ENV-Variablen: * **Zentrale Registry:** Alle Experten-Profile (Synthese, Validierung, Kompression) sind in einer Datei definiert * **Fallback-Kaskade:** Automatische Resilienz bei Provider-Fehlern * **ENV-Variablen:** `MINDNET_LLM_PROVIDER`, `MINDNET_LLM_MODEL` etc. dienen nur noch als Fallback Siehe [Konfigurations-Referenz](../03_Technical_References/03_tech_configuration.md#6-llm-profile-registry-llm_profilesyaml-v130) für Details. --- ## 2. Deployment (Systemd Services) Wir unterscheiden strikt zwischen **Prod** (Port 8001/8501) und **Dev** (Port 8002/8502). ### 2.1 Backend Service (`/etc/systemd/system/mindnet-prod.service`) ```ini [Unit] Description=Mindnet API Prod (8001) After=network.target [Service] User=llmadmin Group=llmadmin WorkingDirectory=/home/llmadmin/mindnet # Startet Uvicorn (Async Server) # Hinweis: Die .env muss MINDNET_VOCAB_PATH für die Edge Registry enthalten. ExecStart=/home/llmadmin/mindnet/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001 --env-file .env Restart=always RestartSec=5 [Install] WantedBy=multi-user.target ``` ### 2.2 UI Service (`/etc/systemd/system/mindnet-ui-prod.service`) ```ini [Unit] Description=Mindnet UI Prod (8501) After=mindnet-prod.service [Service] User=llmadmin Group=llmadmin WorkingDirectory=/home/llmadmin/mindnet # Environment für Streamlit Port & API-Ziel Environment="MINDNET_API_URL=http://localhost:8001" Environment="MINDNET_API_TIMEOUT=300" Environment="STREAMLIT_SERVER_PORT=8501" Environment="STREAMLIT_SERVER_ADDRESS=0.0.0.0" Environment="STREAMLIT_SERVER_HEADLESS=true" # WICHTIG: Pfad zur neuen Router-Datei (ui.py) ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py Restart=always RestartSec=5 [Install] WantedBy=multi-user.target ``` --- ## 3. Wartung & Monitoring ### 3.1 Regelmäßiger Import (Cron) Führt den Sync stündlich durch. Nutzt `--purge-before-upsert` für Sauberkeit. ```bash # Crontab Eintrag (user: llmadmin) 0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1 ``` ### 3.2 Monitoring der Edge Registry (WP-22) Administratoren sollten regelmäßig das Log für unbekannte Kanten-Typen prüfen. * **Pfad:** `data/logs/unknown_edges.jsonl`. * **Aktion:** Wenn neue Typen häufig auftreten, sollten diese als Alias in die `01_edge_vocabulary.md` aufgenommen werden. ### 3.3 Troubleshooting Guide Dieser Abschnitt hilft bei häufigen Problemen und deren Lösung. #### Allgemeine Diagnose-Schritte Bevor du spezifische Fehler behebst, führe diese Checks durch: 1. **Service-Status prüfen:** ```bash systemctl status mindnet-prod systemctl status mindnet-ui-prod docker ps | grep qdrant ``` 2. **Logs analysieren:** ```bash journalctl -u mindnet-prod -n 50 --no-pager journalctl -u mindnet-ui-prod -n 50 --no-pager docker logs qdrant --tail 50 ``` 3. **API-Verfügbarkeit testen:** ```bash curl http://localhost:8001/health curl http://localhost:8001/query -X POST -H "Content-Type: application/json" -d '{"query": "test", "top_k": 1}' ``` #### Häufige Fehler & Lösungen **Fehler: "Registry Initialization Failure" (Neu in v2.7)** * **Symptom:** API startet, aber Kanten werden nicht gewichtet oder Fehlermeldung im Log. * **Diagnose:** Prüfe die Logs auf `EdgeRegistry`-Fehler. * **Lösung:** 1. Prüfe `MINDNET_VOCAB_PATH` in der `.env`. Der Pfad muss absolut sein. 2. Stelle sicher, dass die Datei `01_edge_vocabulary.md` existiert und eine gültige Markdown-Tabelle enthält. 3. Prüfe Dateiberechtigungen: `ls -l $MINDNET_VOCAB_PATH` **Fehler: "ModuleNotFoundError: No module named 'st_cytoscape'"** * **Ursache:** Alte Dependencies oder falsches Paket installiert. * **Lösung:** Environment aktualisieren. ```bash source .venv/bin/activate pip uninstall streamlit-cytoscapejs pip install st-cytoscape pip install -r requirements.txt # Vollständige Synchronisation ``` **Fehler: "Vector dimension error: expected 768, got 384"** * **Ursache:** Alte DB (v2.2), neues Modell (v2.4) oder falsches Embedding-Modell. * **Diagnose:** Prüfe die Collection-Konfiguration in Qdrant. * **Lösung:** **Full Reset** (siehe Kap. 4.2) oder Collection neu erstellen: ```bash python3 -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply --force ``` **Fehler: Import sehr langsam** * **Ursache:** Smart Edges sind aktiv und analysieren jeden Chunk mit LLM-Calls. * **Diagnose:** Prüfe `MINDNET_LLM_BACKGROUND_LIMIT` und LLM-Provider-Status. * **Lösung:** 1. Erhöhe `MINDNET_LLM_BACKGROUND_LIMIT` in `.env` (Standard: 2) 2. Oder deaktiviere Smart Edges temporär in `types.yaml` für bestimmte Typen 3. Prüfe, ob Ollama/Cloud-Provider erreichbar ist **Fehler: UI "Read timed out"** * **Ursache:** Backend braucht für Smart Edges länger als das Timeout-Limit. * **Diagnose:** Prüfe Backend-Logs auf langsame LLM-Calls. * **Lösung:** 1. Erhöhe `MINDNET_API_TIMEOUT=300.0` in `.env` (oder im Systemd Service) 2. Prüfe `MINDNET_LLM_TIMEOUT` für einzelne LLM-Requests 3. Erwäge, Smart Edges für große Imports zu deaktivieren **Fehler: "Qdrant connection refused"** * **Ursache:** Qdrant-Container läuft nicht oder falsche URL. * **Lösung:** ```bash docker ps | grep qdrant # Prüfe Container-Status docker start qdrant # Starte Container falls gestoppt docker logs qdrant # Prüfe Container-Logs # Prüfe QDRANT_URL in .env ``` **Fehler: "Ollama model not found"** * **Ursache:** Modell nicht geladen oder falscher Modellname. * **Lösung:** ```bash ollama list # Zeige geladene Modelle ollama pull phi3:mini # Lade fehlendes Modell ollama pull nomic-embed-text # Prüfe MINDNET_LLM_MODEL und MINDNET_EMBEDDING_MODEL in .env ``` **Fehler: "Too many open files" (Qdrant)** * **Ursache:** System-Limit für offene Dateien zu niedrig (besonders bei vielen Collections). * **Lösung:** Erhöhe `ulimits` im Docker-Compose (siehe Kap. 1.2) oder systemweit: ```bash # Temporär ulimit -n 65535 # Permanently: /etc/security/limits.conf ``` **Fehler: "Unknown edge type" in Logs** * **Ursache:** Neue Kanten-Typen im Vault, die nicht in `edge_vocabulary.md` definiert sind. * **Diagnose:** Prüfe `data/logs/unknown_edges.jsonl`. * **Lösung:** 1. Füge fehlende Typen als Aliase in `01_edge_vocabulary.md` hinzu 2. Oder verwende kanonische Typen aus der Registry #### Performance-Optimierung **Problem: Langsame Chat-Antworten** * Prüfe LLM-Provider (Cloud vs. lokal) * Reduziere `top_k` in Query-Requests * Prüfe Qdrant-Performance (Anzahl Collections, Index-Größe) **Problem: Hoher Speicherverbrauch** * Reduziere `MINDNET_LLM_BACKGROUND_LIMIT` * Prüfe Qdrant-Speicherverbrauch: `docker stats qdrant` * Erwäge, alte Collections zu archivieren #### Weitere Hilfe Für detaillierte Informationen zu: - **Server-Betrieb:** Siehe [Server Operations Manual](04_server_operation_manual.md) - **Entwicklung:** Siehe [Developer Guide](../05_Development/05_developer_guide.md#10-troubleshooting--one-liners) - **Konfiguration:** Siehe [Configuration Reference](../03_Technical_References/03_tech_configuration.md) --- ## 4. Backup & Restore ### 4.1 Qdrant Snapshot Sichert den Vektor-Index. ```bash docker stop mindnet_qdrant tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage docker start mindnet_qdrant ``` ### 4.2 Notfall-Rebuild (Clean Slate) Wenn alles inkonsistent ist oder Dimensionen sich ändern: ```bash # 1. DB löschen python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes # 2. Neu importieren (Force Hash recalculation) python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force ``` **Wichtig (v2.9.1 Migration):** Nach dem Update auf v2.9.1 (Section-basierte Links, Multigraph-Support) ist ein vollständiger Re-Import erforderlich, um "Phantom-Knoten" zu beheben und die neue Edge-Struktur zu konsolidieren: ```bash python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force ``` Dies stellt sicher, dass alle bestehenden Links korrekt in `target_id` und `target_section` aufgeteilt werden.