Deploy mindnet to llm-node / deploy (push) Successful in 4s

Details

2025-12-26 17:21:58 +01:00

5.1 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

Fehler: "Registry Initialization Failure" (Neu in v2.7)

Symptom: API startet, aber Kanten werden nicht gewichtet oder Fehlermeldung im Log.
Lösung: Prüfen Sie MINDNET_VOCAB_PATH in der .env. Der Pfad muss absolut sein und auf eine existierende Markdown-Tabelle zeigen.

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

Fehler: "Vector dimension error: expected 768, got 384"

Ursache: Alte DB (v2.2), neues Modell (v2.4).
Lösung: Full Reset (siehe Kap. 4.2).

Fehler: Import sehr langsam

Ursache: Smart Edges sind aktiv und analysieren jeden Chunk.
Lösung: MINDNET_LLM_BACKGROUND_LIMIT prüfen oder Feature in types.yaml deaktivieren.

Fehler: UI "Read timed out"

Ursache: Backend braucht für Smart Edges länger als 60s.
Lösung: MINDNET_API_TIMEOUT=300.0 in .env setzen (oder im Systemd Service).

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

5.1 KiB Raw Blame History