Lars
4d6fce2d93
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
198 lines
7.1 KiB
Markdown
198 lines
7.1 KiB
Markdown
# Mindnet v2.2 – Admin Guide
|
||
**Datei:** `docs/mindnet_admin_guide_v2.2.md`
|
||
**Stand:** 2025-12-08
|
||
**Status:** **FINAL** (Inkl. RAG & LLM Ops)
|
||
**Quellen:** `Handbuch.md`, `mindnet_developer_guide_v2.2.md`.
|
||
|
||
> Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz (API + DB + LLM).
|
||
|
||
---
|
||
<details>
|
||
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
|
||
|
||
- [Mindnet v2.2 – Admin Guide](#mindnet-v22--admin-guide)
|
||
- [1. Zielgruppe \& Scope](#1-zielgruppe--scope)
|
||
- [2. Initial Setup \& Installation](#2-initial-setup--installation)
|
||
- [2.1 Systemvoraussetzungen](#21-systemvoraussetzungen)
|
||
- [2.2 Installation (Code)](#22-installation-code)
|
||
- [2.3 Qdrant Setup (Docker)](#23-qdrant-setup-docker)
|
||
- [2.4 Ollama Setup (LLM Service)](#24-ollama-setup-llm-service)
|
||
- [2.5 Konfiguration (ENV)](#25-konfiguration-env)
|
||
- [2.6 Deployment via Systemd](#26-deployment-via-systemd)
|
||
- [3. Betrieb im Alltag](#3-betrieb-im-alltag)
|
||
- [3.1 Regelmäßige Importe](#31-regelmäßige-importe)
|
||
- [3.2 Health-Checks](#32-health-checks)
|
||
- [3.3 Logs \& Monitoring](#33-logs--monitoring)
|
||
- [4. Update-Prozess](#4-update-prozess)
|
||
- [5. Backup \& Restore](#5-backup--restore)
|
||
- [5.1 Vault-Backup (Priorität 1)](#51-vault-backup-priorität-1)
|
||
- [5.2 Qdrant-Snapshots (Priorität 2)](#52-qdrant-snapshots-priorität-2)
|
||
- [5.3 Log-Daten (Priorität 3)](#53-log-daten-priorität-3)
|
||
- [5.4 Notfall-Wiederherstellung (Rebuild)](#54-notfall-wiederherstellung-rebuild)
|
||
- [6. Governance \& Sicherheit](#6-governance--sicherheit)
|
||
- [6.1 Zugriffsschutz](#61-zugriffsschutz)
|
||
- [6.2 Typen-Governance](#62-typen-governance)
|
||
|
||
|
||
---
|
||
|
||
## 1. Zielgruppe & Scope
|
||
|
||
Mindnet ist als **Single-Node System** konzipiert, das lokal (z.B. Laptop) oder auf einem privaten Server (Homelab, Intranet) läuft.
|
||
Wir unterscheiden strikt zwischen:
|
||
* **Production (Port 8001):** Stabiler `main` Branch.
|
||
* **Development (Port 8002):** 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 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
|
||
pip install -r requirements.txt
|
||
|
||
# 3. Verzeichnisse anlegen
|
||
mkdir -p logs qdrant_storage data/logs
|
||
|
||
### 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 Service)
|
||
Mindnet benötigt einen lokalen LLM-Server für den Chat.
|
||
# 1. Installieren (Linux Script)
|
||
curl -fsSL https://ollama.com/install.sh | sh
|
||
|
||
# 2. Modell laden (Phi-3 Mini für CPU-Performance)
|
||
ollama pull phi3:mini
|
||
|
||
# 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.
|
||
|
||
# Qdrant Verbindung
|
||
QDRANT_URL="http://localhost:6333"
|
||
|
||
# Mindnet Core Settings
|
||
COLLECTION_PREFIX="mindnet"
|
||
MINDNET_TYPES_FILE="./config/types.yaml"
|
||
MINDNET_PROMPTS_PATH="./config/prompts.yaml"
|
||
|
||
# LLM Settings
|
||
MINDNET_LLM_MODEL="phi3:mini"
|
||
MINDNET_OLLAMA_URL="http://127.0.0.1:11434"
|
||
|
||
### 2.6 Deployment via Systemd
|
||
Mindnet wird als Systemdienst gestartet. Ollama läuft meist als eigener Dienst (`ollama.service`).
|
||
|
||
**Production Service (`/etc/systemd/system/mindnet-prod.service`):**
|
||
* Läuft auf Port 8001.
|
||
* Autostart (`enabled`).
|
||
* Restart Policy: `always`.
|
||
* Abhängigkeit: Sollte nach `docker` und `ollama` starten.
|
||
|
||
---
|
||
|
||
## 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.
|
||
|
||
**Cronjob-Beispiel (stündlich):**
|
||
0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1
|
||
|
||
### 3.2 Health-Checks
|
||
Prüfe regelmäßig, ob alle drei Komponenten (API, DB, LLM) laufen.
|
||
|
||
**Status prüfen:**
|
||
sudo systemctl status mindnet-prod
|
||
sudo systemctl status ollama
|
||
|
||
**Logischer Smoke-Test:**
|
||
python3 scripts/test_retriever_smoke.py --mode hybrid --url http://localhost:8001/query
|
||
|
||
### 3.3 Logs & Monitoring
|
||
* **Technische Fehler (API):** `journalctl -u mindnet-prod -f`
|
||
* **LLM Fehler (Ollama):** `journalctl -u ollama -f`
|
||
* **Fachliche Logs:** `data/logs/search_history.jsonl`
|
||
|
||
**Troubleshooting Chat:**
|
||
* Wenn `/chat` in den Timeout läuft (>300s): Prüfe, ob `phi3:mini` geladen ist und ob der Server überlastet ist.
|
||
* Wenn `/chat` halluziniert: Prüfe `config/prompts.yaml` und ob der Import aktuell ist.
|
||
|
||
---
|
||
|
||
## 4. Update-Prozess
|
||
|
||
Wenn neue Versionen ausgerollt werden (Deployment):
|
||
|
||
1. **Code aktualisieren:**
|
||
cd /home/llmadmin/mindnet
|
||
git pull origin main
|
||
2. **Dependencies prüfen:**
|
||
source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
3. **Dienst neustarten (Zwingend!):**
|
||
sudo systemctl restart mindnet-prod
|
||
4. **Schema-Migration (falls nötig):**
|
||
python3 -m scripts.import_markdown ... --apply
|
||
|
||
---
|
||
|
||
## 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**. Er muss klassisch gesichert werden (Git/NAS).
|
||
|
||
### 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 Log-Daten (Priorität 3)
|
||
Sichere den Ordner `data/logs/`. Verlust dieser Daten bedeutet, dass das System vergisst, welche Antworten Nutzer hilfreich fanden.
|
||
|
||
### 5.4 Notfall-Wiederherstellung (Rebuild)
|
||
Wenn die Datenbank korrupt ist:
|
||
# 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 /path/to/vault --prefix "mindnet" --apply
|
||
|
||
---
|
||
|
||
## 6. Governance & Sicherheit
|
||
|
||
### 6.1 Zugriffsschutz
|
||
Mindnet hat aktuell **keine integrierte Authentifizierung**.
|
||
* **API:** Muss hinter einem Reverse Proxy (Nginx) mit Basic Auth laufen.
|
||
* **Qdrant:** Sollte via Firewall (ufw) auf `127.0.0.1` beschränkt sein.
|
||
* **Ollama:** Standardmäßig hört Ollama nur auf `localhost`. Das ist sicher.
|
||
|
||
### 6.2 Typen-Governance
|
||
Änderungen an der `types.yaml` (z.B. neue Gewichte) wirken global.
|
||
* **Prozess:** Änderungen sollten getestet werden (Smoke-Test), bevor sie produktiv gehen. |