238 lines
8.0 KiB
Markdown
238 lines
8.0 KiB
Markdown
# 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 <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.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. |