DeepbitDesktop v0 — RAG Support Desk

Logfiles und Dokumente rein. Wissen aufbauen. Crew fragt. Antwort kommt.

Multi-Channel RAG-System für RZ-Support-Teams — mit lokalem LLM-Coding-Assistenten.

Inhalt

• Was ist das?
• Stack
• Quickstart
• Architektur
• Wissen ingestieren
• Channels
• OpenCode → Ollama
• Deployment & Updates
• Troubleshooting

Was ist das?

ozmai (OZM AI) ist ein RAG-System (Retrieval-Augmented Generation) das intern läuft.
Kein Cloud-Speicher für die Dokumente. Kein Dritter sieht die Logfiles.

Wie es funktioniert:

Dokument / Logfile einmal ingestieren
         │
         ▼
    Ollama zerlegt es in Chunks und erstellt Vektoren
         │
         ▼
    pgvector speichert Vektoren + Inhalt in PostgreSQL
         │
         ▼
    Crew stellt Frage im Browser
         │
         ▼
    Frage → Vektor → ähnliche Chunks gesucht → Claude formuliert Antwort

Das Wissen bleibt lokal in PostgreSQL. Claude sieht nur den Kontext für eine Anfrage — keine Daten wandern dauerhaft in die Cloud.

Stack

Quickstart

Voraussetzungen

• Docker + Docker Compose
• Anthropic API Key

1. Einrichten

git clone <dieses-repo> DeepbitDesktop_v0
cd DeepbitDesktop_v0

2. API Key eintragen

# .env öffnen und ANTHROPIC_API_KEY eintragen
nano .env

DATABASE_URL=postgresql://rag:rag@db:5432/supportdesk
OLLAMA_URL=http://ollama:11434
ANTHROPIC_API_KEY=sk-ant-...

POSTGRES_USER=rag
POSTGRES_PASSWORD=rag
POSTGRES_DB=supportdesk

3. Starten

docker compose up --build

Beim ersten Start:
- Ollama lädt nomic-embed-text — je nach Verbindung 1–5 Minuten
- PostgreSQL importiert seed/02-seed.sql automatisch (nur einmal, auf leerem Volume)
- App wartet bis beide Services healthy sind

4. Öffnen

http://localhost:8080

Das Wissen aus dem Seed ist sofort verfügbar — kein Re-Ingest nötig.

Architektur

┌─────────────────────────────────────────────────────────────┐
│  Browser (public/index.html)                                 │
│  IRC-Style SPA · Channels · Vektor- und LLM-Modus           │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTP
┌───────────────────────▼─────────────────────────────────────┐
│  FastAPI (api.py) · Port 8080                                │
│                                                              │
│  POST /query        → Frage stellen (Vektor oder LLM)        │
│  POST /ingest-text  → Text direkt ingestieren                │
│  POST /ingest       → Datei ingestieren                      │
│  POST /analyze-log  → Anonymisierte Log-Analyse              │
│  GET  /history      → Chat-History eines Channels            │
│  GET  /channels     → Alle Channels                          │
│  POST /admin/reset  → Chunks löschen (channel-scoped)        │
└──────────┬──────────────────────┬───────────────────────────┘
           │                      │
┌──────────▼──────────┐  ┌────────▼────────────────────────────┐
│  Ollama             │  │  PostgreSQL 17 + pgvector             │
│  nomic-embed-text   │  │                                       │
│  768-dim Embeddings │  │  channels    — Kanal-Definitionen     │
│  Port 11434         │  │  chunks      — Vektoren + Inhalt      │
│  (auch für         │  │  chat_history — Gesprächsprotokoll     │
│   OpenCode)         │  │                                       │
└─────────────────────┘  └───────────────────────────────────────┘
           │
┌──────────▼──────────┐
│  Anthropic Claude   │
│  Sonnet API         │
│  Antwortgenerierung │
└─────────────────────┘

Query-Pipeline

Frage → Ollama Embedding → pgvector cosine search (TOP 5)
      → Claude (Vektor-Modus: nur Kontext | LLM-Modus: + eigenes Wissen)
      → Antwort + Quellen → Chat-History → Browser

Channel-Scoping

Jede Anfrage sucht im Ziel-Channel. Der general-Channel wird immer als Fallback einbezogen. Das verhindert tote Anfragen wenn ein Channel leer ist.

Wissen ingestieren

Text direkt (API)

curl -X POST http://localhost:8080/ingest-text \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Inhalt des Dokuments...",
    "source": "mein_dokument.md",
    "channel_id": "dns"
  }'

Markdown-Datei via Browser

Im Frontend: Channel wählen → Ingest → Datei hochladen oder Text einfügen.

Empfohlene Chunk-Struktur

Chunks werden nach 20 Zeilen aufgeteilt. Für gute Retrieval-Qualität:

• FAQ-Format für Grundbegriffe: Frage direkt in die erste Zeile des Abschnitts:
  Frage: Was ist X und wie funktioniert es? Antwort: X ist ...
• Kommando-Blöcke für Procedures: Kommentare + Befehl in einem Block
• Nicht vermischen: Ein Chunk = ein Thema

Log-Analyse (anonym)

curl -X POST http://localhost:8080/analyze-log \
  -H "Content-Type: application/json" \
  -d '{
    "log_text": "Apr  1 03:22:11 srv01 sshd[1234]: Failed password...",
    "question": "Was ist hier auffällig?"
  }'

IPs, Hostnamen und User werden automatisch anonymisiert. Die Rohdaten werden nie gespeichert.

Channels

Neuen Channel anlegen:

curl -X POST http://localhost:8080/channels \
  -H "Content-Type: application/json" \
  -d '{"name": "Nginx", "category": "Service"}'

OpenRouter

OpenRouter gibt Zugriff auf 200+ Modelle über eine einzige OpenAI-kompatible API — Claude, GPT-4o, Llama, Mistral, Gemini und mehr.

API Key besorgen

1. https://openrouter.ai/keys → Key erstellen
2. In .env eintragen:

OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_MODEL=anthropic/claude-3.5-haiku

Modell wählen

Beliebtes Modell für Kosten/Qualität:

Vollständige Liste: https://openrouter.ai/models

Im Frontend nutzen

Nach dem Stack-Neustart erscheint im Header ein Provider-Toggle:

🔒 Vektor  🧠 LLM  │  🔵 Claude  🌐 OpenRouter

• 🔵 Claude → Anthropic API direkt
• 🌐 OpenRouter → konfiguriertes OPENROUTER_MODEL

Der Nick zeigt welcher Provider geantwortet hat: 🌐🔒 ozmai oder 🔵🧠 ozmai.

Stack neu starten nach .env-Änderung

docker compose down && docker compose up --build

OpenCode → Ollama

OpenCode ist ein KI-Coding-Assistent für das Terminal — ähnlich wie Claude Code, aber mit lokalem LLM. Der Ollama-Stack läuft bereits auf Port 11434 und ist OpenAI-API-kompatibel.

OpenCode installieren

curl -fsSL https://opencode.ai/install | bash

Coding-Modell laden

nomic-embed-text ist nur für Embeddings. Für Code-Assistance ein Coding-Modell nachladen:

# Empfohlen: Qwen 2.5 Coder (7B — läuft auf 16 GB RAM)
docker compose exec ollama ollama pull qwen2.5-coder:7b

# Alternativ kleiner (8 GB RAM):
docker compose exec ollama ollama pull qwen2.5-coder:3b

# Oder CodeLlama:
docker compose exec ollama ollama pull codellama:7b

OpenCode konfigurieren

Das Setup-Script legt die Konfiguration automatisch an. Manuell:

~/.config/opencode/config.json

{
  "$schema": "https://opencode.ai/config.json",
  "autoshare": false,
  "providers": {
    "ollama": {
      "npm": "@opensdks/runtime",
      "baseURL": "http://localhost:11434/v1",
      "apiKey": "ollama"
    }
  },
  "model": "ollama/qwen2.5-coder:7b"
}

Starten

# Im Projektverzeichnis
opencode

OpenCode nutzt dann das lokale Coding-Modell über den laufenden Stack. Keine Daten gehen nach außen.

Verfügbare Modelle prüfen

docker compose exec ollama ollama list
# oder direkt:
curl http://localhost:11434/api/tags | python3 -m json.tool

Deployment & Updates

Setup-Script (bei neuem Rechner / neuem Deploy)

# Laufenden Original-Stack vorausgesetzt:
bash setup_deploy_crewscript.sh

Das Script:
1. Exportiert den aktuellen DB-Stand (pg_dump)
2. Kopiert App-Quellcode
3. Erstellt docker-compose.yml mit Seed
4. Legt .env-Vorlage an
5. Konfiguriert OpenCode → Ollama (falls installiert)

Wissen aktualisieren (neuen Snapshot machen)

# Neuen Seed aus laufendem Stack exportieren:
docker exec rkl-ozm-chat-hook-v00-db-1 \
  pg_dump -U rag -d supportdesk --data-only --no-privileges --no-owner \
  > seed/02-seed.sql

# Vollbackup mit Zeitstempel:
docker exec rkl-ozm-chat-hook-v00-db-1 \
  pg_dump -U rag -d supportdesk --no-privileges --no-owner \
  > seed/backup_$(date +%Y%m%d_%H%M%S).sql

Wissen auf neuer Instanz zurückspielen

# pgdata-Volume löschen (erzwingt Neu-Import beim nächsten Start):
docker compose down -v
docker compose up --build

Der Seed wird beim ersten Start automatisch importiert.

Troubleshooting

Ollama startet nicht / Modell fehlt

# Logs prüfen:
docker compose logs ollama

# Modell manuell ziehen:
docker compose exec ollama ollama pull nomic-embed-text

DB nicht erreichbar

# Health-Check:
docker compose ps
curl http://localhost:8080/health

# DB direkt:
docker compose exec db psql -U rag -d supportdesk -c "SELECT COUNT(*) FROM chunks;"

Seed wurde nicht importiert

Der docker-entrypoint-initdb.d-Mechanismus greift nur auf leerem Volume. Wenn das Volume schon Daten hat:

docker compose down -v   # Volume löschen
docker compose up        # Neu starten mit Seed-Import

"Keine Information im Vektor" trotz vorhandenem Wissen

Das passiert wenn:
- Die Frage im Vektor-Modus ist, aber kein passender Chunk im Top-5 landet
- Lösung A: LLM-Modus wählen (Claude darf eigenes Wissen ergänzen)
- Lösung B: Fehlendes Wissen als FAQ-Chunk ingestieren (Frage + Antwort direkt im Text)

Port 8080 belegt

# Original-Stack stoppen:
cd /Users/bmt/Documents/RKL-OZM-Chat-Hook-v.0.0 && docker compose down
# Dann hier:
docker compose up

OpenCode findet Ollama nicht

# Stack läuft?
curl http://localhost:11434/api/tags

# Modell geladen?
docker compose exec ollama ollama list

# Config prüfen:
cat ~/.config/opencode/config.json

Dateien

DeepbitDesktop_v0/
├── api.py                    ← FastAPI App, alle Endpunkte
├── ingest.py                 ← Ingest-Pipeline
├── query.py                  ← RAG-Query + Log-Analyse
├── embeddings.py             ← Ollama Embedding-Client
├── requirements.txt
├── Dockerfile
├── schema.sql                ← DB-Schema (DDL)
├── ollama-entrypoint.sh      ← Modell-Autoload beim Start
├── docker-compose.yml        ← Stack-Definition
├── .env                      ← Secrets (nicht ins Git!)
├── public/                   ← Frontend SPA
│   └── index.html
├── seed/
│   ├── 02-seed.sql           ← Aktueller Wissens-Snapshot
│   └── backup_*.sql          ← Vollbackups mit Zeitstempel
├── logs/                     ← Runtime-Logs
├── docs/
│   └── opencode_config_example.json
└── setup_deploy_crewscript.sh ← Dieses Script

kein Wald ist einfach — aber jeder Baum fängt mit einem Samen an.