# Mindnet v2.4 – Admin Guide **Datei:** `docs/mindnet_admin_guide_v2.6.md` **Stand:** 2025-12-12 **Status:** **FINAL** (Inkl. Traffic Control & Smart Edge Config) **Quellen:** `Handbuch.md`, `mindnet_developer_guide_v2.6.md`. > Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz (API + UI + DB). --- ## 1. Zielgruppe & Scope Mindnet ist als **Multi-Service-Architektur** konzipiert, die lokal oder auf einem privaten Server läuft. Wir unterscheiden strikt zwischen: * **Production:** Backend (8001) + Frontend (8501). Stabiler `main` Branch. * **Development:** Backend (8002) + Frontend (8502). 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 Async 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 # 3. Dependencies installieren (inkl. Streamlit, HTTPX) pip install -r requirements.txt # 4. Verzeichnisse anlegen mkdir -p logs qdrant_storage data/logs vault ### 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 & Embeddings) Mindnet benötigt einen lokalen LLM-Server für Chat UND Embeddings. **WICHTIG (Update v2.4):** Es muss zwingend `nomic-embed-text` installiert sein, sonst startet der Import nicht. # 1. Installieren (Linux Script) curl -fsSL https://ollama.com/install.sh | sh # 2. Modelle laden ollama pull phi3:mini # Für Chat/Reasoning ollama pull nomic-embed-text # Für Vektoren (768 Dim) # 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. Achte besonders auf `VECTOR_DIM` und das neue `MINDNET_LLM_BACKGROUND_LIMIT`. # Server Config UVICORN_HOST=0.0.0.0 # Qdrant Verbindung QDRANT_URL="http://localhost:6333" # Mindnet Core Settings COLLECTION_PREFIX="mindnet" MINDNET_TYPES_FILE="./config/types.yaml" MINDNET_VAULT_ROOT="./vault" # WICHTIG: Dimension auf 768 setzen (für Nomic) VECTOR_DIM=768 # AI Modelle (Ollama) MINDNET_OLLAMA_URL="http://127.0.0.1:11434" MINDNET_LLM_MODEL="phi3:mini" MINDNET_EMBEDDING_MODEL="nomic-embed-text" # Timeouts (Erhöht für Async/Nomic/Smart Edges) MINDNET_LLM_TIMEOUT=300.0 MINDNET_API_TIMEOUT=300.0 # Wichtig: Frontend muss warten können # Traffic Control (Neu in v2.6) # Begrenzt parallele LLM-Calls im Import, um Chat stabil zu halten. MINDNET_LLM_BACKGROUND_LIMIT=2 # Configs MINDNET_PROMPTS_PATH="./config/prompts.yaml" MINDNET_DECISION_CONFIG="./config/decision_engine.yaml" ### 2.6 Deployment via Systemd (Backend & Frontend) Mindnet benötigt zwei Services pro Umgebung: API (Uvicorn) und UI (Streamlit). **Production Backend (`/etc/systemd/system/mindnet-prod.service`):** [Unit] Description=Mindnet API Prod (8001) After=network.target [Service] User=llmadmin Group=llmadmin WorkingDirectory=/home/llmadmin/mindnet # Async Server Start 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 **Production Frontend (`/etc/systemd/system/mindnet-ui-prod.service`):** [Unit] Description=Mindnet UI Prod (8501) After=mindnet-prod.service [Service] User=llmadmin Group=llmadmin WorkingDirectory=/home/llmadmin/mindnet # Environment Variables 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" ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py Restart=always RestartSec=5 [Install] WantedBy=multi-user.target **Firewall (UFW):** Öffne die Ports für den Zugriff: sudo ufw allow 8501/tcp # Prod UI sudo ufw allow 8502/tcp # Dev UI (falls gewünscht) --- ## 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. Das Skript nutzt nun **AsyncIO**, **Smart Edges** und **Traffic Control**. **Cronjob-Beispiel (stündlich):** 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 **Hinweis zu Smart Edges:** Der Import dauert nun länger (ca. 2-3 Min pro Datei), da das LLM intensiv genutzt wird. Dank `MINDNET_LLM_BACKGROUND_LIMIT=2` bleibt der Server dabei aber für den Chat responsive. ### 3.2 Health-Checks Prüfe regelmäßig, ob alle Komponenten laufen. sudo systemctl status mindnet-prod sudo systemctl status mindnet-ui-prod sudo systemctl status ollama ### 3.3 Logs & Monitoring * **Backend Fehler:** `journalctl -u mindnet-prod -f` * **Frontend Fehler:** `journalctl -u mindnet-ui-prod -f` * **LLM Fehler:** `journalctl -u ollama -f` * **Fachliche Logs:** `data/logs/search_history.jsonl` --- ## 4. Troubleshooting (Update v2.6) ### "Vector dimension error: expected dim: 768, got 384" * **Ursache:** Du versuchst, in eine alte Qdrant-Collection (mit 384 Dim aus v2.2) neue Embeddings (mit 768 Dim von Nomic) zu schreiben. * **Lösung:** Full Reset erforderlich. 1. `python -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes` (Löscht DB). 2. `python -m scripts.import_markdown ...` (Baut neu auf). ### "500 Internal Server Error" beim Speichern/Chatten * **Ursache:** Oft Timeout bei Ollama, wenn `nomic-embed-text` noch nicht im RAM geladen ist ("Cold Start") oder der Import die GPU blockiert. * **Lösung:** 1. `MINDNET_LLM_TIMEOUT` in `.env` auf `300.0` setzen. 2. `MINDNET_LLM_BACKGROUND_LIMIT` auf `1` reduzieren (falls Hardware schwach). ### Import ist sehr langsam * **Ursache:** Smart Edges sind aktiv (`types.yaml`) und analysieren jeden Chunk. * **Lösung:** * Akzeptieren (für bessere Qualität). * Oder für Massen-Initial-Import in `types.yaml` temporär `enable_smart_edge_allocation: false` setzen. --- ## 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**. ### 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 Notfall-Wiederherstellung (Rebuild) Wenn die Datenbank korrupt ist oder Modelle gewechselt werden: # 1. DB komplett leeren (Wipe) python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes # 2. Alles neu importieren (Force re-calculates Hashes) python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force --- ## 6. Governance & Sicherheit ### 6.1 Zugriffsschutz Mindnet hat aktuell **keine integrierte Authentifizierung**. * **Frontend:** Streamlit auf Port 8501 ist offen. Nutze Nginx Basic Auth oder VPN. * **API:** Sollte nicht direkt im öffentlichen Netz stehen. * **Qdrant:** Auf `127.0.0.1` beschränken.