Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
c741cc7d1b
mindnet/docs/admin_guide.md
Lars 5bf91d51da Dokumentation WP11
2025-12-11 16:58:23 +01:00

7.4 KiB
Raw Blame History

Mindnet v2.4 – Admin Guide

Datei: docs/mindnet_admin_guide_v2.4.md Stand: 2025-12-11 Status: FINAL (Inkl. Async Architecture & Nomic Model) Quellen: Handbuch.md, mindnet_developer_guide_v2.4.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 <repo-url> /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.3.10): 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 MINDNET_EMBEDDING_MODEL.

# 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" # NEU

# Timeouts (Erhöht für Async/Nomic)
MINDNET_LLM_TIMEOUT=300.0
MINDNET_API_TIMEOUT=60.0

# 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 und eine Semaphore, um Ollama nicht zu überlasten.

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

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.4)

"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

  • Ursache: Oft Timeout bei Ollama, wenn nomic-embed-text noch nicht im RAM geladen ist ("Cold Start").
  • Lösung:
    1. Sicherstellen, dass Modell existiert: ollama list.
    2. API neustarten (re-initialisiert Async Clients).

"NameError: name 'os' is not defined"

  • Ursache: Fehlender Import in Skripten nach Updates.
  • Lösung: git pull (Fix wurde in v2.3.10 deployed).

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