Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
cd5056d4c9
mindnet/docs/04_Operations/04_admin_operations.md

9.2 KiB
Raw Blame History

doc_type audience scope status version context
operations_manual admin, devops deployment, maintenance, backup, edge_registry active 2.7.0 Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v2.7.

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

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


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.

# Modelle laden
ollama pull phi3:mini
ollama pull nomic-embed-text

# Testen
curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}'

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)

[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)

[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.

# 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:

    systemctl status mindnet-prod
systemctl status mindnet-ui-prod
docker ps | grep qdrant

  2. Logs analysieren:

    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:

    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. 
    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: 
    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: 
    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: 
    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: 
    # 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:

4. Backup & Restore

4.1 Qdrant Snapshot

Sichert den Vektor-Index.

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:

# 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:

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.