# Jan.ai Offline-Assistent

## Überblick

[Jan.ai](https://github.com/janhq/jan) ist eine Open-Source-, datenschutzorientierte ChatGPT-Alternative mit über 40.000 GitHub-Sternen. Während Jan am bekanntesten als Desktop-Anwendung ist, stellt seine Serverkomponente — **Jan Server** — eine vollständig OpenAI-kompatible REST-API bereit, die auf Cloud-GPU-Infrastrukturen wie Clore.ai bereitgestellt werden kann.

Jan Server basiert auf der [Cortex.cpp](https://github.com/janhq/cortex.cpp) Inference-Engine, einer leistungsstarken Laufzeitumgebung, die `llama.cpp`, `TensorRT-LLM`und ONNX-Backends unterstützt. Auf Clore.ai können Sie einen GPU-Server schon ab **$0.20/hr**mieten, Jan Server mit Docker Compose ausführen, jedes GGUF- oder GPTQ-Modell laden und es über eine OpenAI-kompatible API bereitstellen — alles, ohne dass Ihre Daten die Maschine verlassen.

**Hauptfunktionen:**

* 🔒 100% offline — keine Daten verlassen jemals Ihren Server
* 🤖 OpenAI-kompatible API (`/v1/chat/completions`, `/v1/models`, etc.)
* 📦 Modell-Hub mit Ein-Kommando-Modell-Downloads
* 🚀 GPU-Beschleunigung via CUDA (llama.cpp + TensorRT-LLM Backends)
* 💬 Eingebaute Gesprächsverwaltung und Thread-Historie
* 🔌 Drop-in-Ersatz für OpenAI in bestehenden Anwendungen

***

## Anforderungen

### Hardware-Anforderungen

| Tier              | GPU           | VRAM  | RAM    | Speicher   | Clore.ai-Preis |
| ----------------- | ------------- | ----- | ------ | ---------- | -------------- |
| **Minimum**       | RTX 3060 12GB | 12 GB | 16 GB  | 50 GB SSD  | \~0,10 $/Std.  |
| **Empfohlen**     | RTX 3090      | 24 GB | 32 GB  | 100 GB SSD | \~$0.20/Stunde |
| **High-End**      | RTX 4090      | 24 GB | 64 GB  | 200 GB SSD | \~$0.35/Stunde |
| **Große Modelle** | A100 80GB     | 80 GB | 128 GB | 500 GB SSD | \~$1.10/Stunde |

### Referenz für Modell-VRAM

| Modell              | Benötigter VRAM | Empfohlene GPU |
| ------------------- | --------------- | -------------- |
| Llama 3.1 8B (Q4)   | \~5 GB          | RTX 3060       |
| Llama 3.1 8B (FP16) | \~16 GB         | RTX 3090       |
| Llama 3.3 70B (Q4)  | \~40 GB         | A100 40GB      |
| Llama 3.1 405B (Q4) | \~220 GB        | 4× A100 80GB   |
| Mistral 7B (Q4)     | \~4 GB          | RTX 3060       |
| Qwen2.5 72B (Q4)    | \~45 GB         | A100 80GB      |

### Software-Voraussetzungen

* Clore.ai-Konto mit aufgeladenem Wallet
* Grundkenntnisse in Docker
* (Optional) OpenSSH-Client für Port-Forwarding

***

## Schnellstart

### Schritt 1 — Mieten Sie einen GPU-Server auf Clore.ai

1. Navigieren Sie zu [clore.ai](https://clore.ai) und melden Sie sich an
2. Server filtern: **GPU-Typ** → RTX 3090 oder besser, **Docker** → aktiviert
3. Wählen Sie einen Server und wählen Sie die **Docker** Bereitstellungsoption
4. Verwenden Sie das offizielle `nvidia/cuda:12.1.0-devel-ubuntu22.04` Basis-Image oder ein beliebiges CUDA-Image
5. Offene Ports: **1337** (Jan Server API), **39281** (Cortex API), **22** (SSH)

### Schritt 2 — Mit Ihrem Server verbinden

```bash
# SSH auf Ihren Clore.ai-Server
ssh -p <CLORE_SSH_PORT> root@<CLORE_SERVER_IP>

# GPU-Verfügbarkeit prüfen
nvidia-smi
```

### Schritt 3 — Docker Compose installieren (falls nicht vorhanden)

```bash
# Prüfen, ob Docker Compose verfügbar ist
docker compose version

# Installieren, falls fehlt (Ubuntu/Debian)
apt-get update && apt-get install -y docker-compose-plugin

# Verifizieren
docker compose version
```

### Schritt 4 — Jan Server mit Docker Compose bereitstellen

```bash
# Arbeitsverzeichnis erstellen
mkdir -p /workspace/jan-server && cd /workspace/jan-server

# Offizielle Jan Server docker-compose.yml herunterladen
curl -fsSL https://raw.githubusercontent.com/janhq/jan-server/main/docker-compose.yml \
  -o docker-compose.yml

# Konfiguration prüfen und bearbeiten
cat docker-compose.yml
```

Wenn die Upstream-Compose-Datei nicht verfügbar ist oder Sie vollständige Kontrolle möchten, erstellen Sie sie manuell:

```yaml
# /workspace/jan-server/docker-compose.yml
version: '3.8'

services:
  jan-server:
    image: ghcr.io/janhq/cortex:latest
    container_name: jan-server
    restart: unless-stopped
    ports:
      - "1337:1337"
      - "39281:39281"
    volumes:
      - jan-data:/root/jan
      - jan-models:/root/cortex/models
    environment:
      - CUDA_VISIBLE_DEVICES=0
      - JAN_API_HOST=0.0.0.0
      - JAN_API_PORT=1337
      - CORTEX_API_PORT=39281
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:1337/health"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s

volumes:
  jan-data:
    driver: local
  jan-models:
    driver: local
```

```bash
# Jan Server starten
docker compose up -d

# Startup-Logs verfolgen (auf die Meldung "Server started" warten)
docker compose logs -f jan-server
```

### Schritt 5 — Überprüfen, ob der Server läuft

```bash
# Server-Health prüfen
curl http://localhost:1337/health

# Verfügbare Modelle auflisten (anfangs leer)
curl http://localhost:1337/v1/models

# Erwartete Antwort:
# {"object":"list","data":[]}
```

### Schritt 6 — Ihr erstes Modell ziehen

```bash
# Llama 3.2 3B ziehen (guter Einstieg, ~2GB)
curl -X POST http://localhost:1337/v1/models/pull \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2:3b-gguf-q4-km"}'

# Oder Mistral 7B Instruct Q4 ziehen
curl -X POST http://localhost:1337/v1/models/pull \
  -H "Content-Type: application/json" \
  -d '{"model": "mistral:7b-instruct-v0.3-gguf-q4-km"}'

# Download-Fortschritt überwachen
curl http://localhost:1337/v1/models
```

### Schritt 7 — Modell starten & chatten

```bash
# Modell starten (lädt es in die GPU-VRAM)
curl -X POST http://localhost:1337/v1/models/start \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2:3b-gguf-q4-km"}'

# Ihre erste Chat-Anfrage senden
curl http://localhost:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2:3b-gguf-q4-km",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello! What can you help me with?"}
    ],
    "temperature": 0.7,
    "max_tokens": 512,
    "stream": false
  }'
```

***

## Konfiguration

### Umgebungsvariablen

| Variable               | Standard              | Beschreibung                                                           |
| ---------------------- | --------------------- | ---------------------------------------------------------------------- |
| `JAN_API_HOST`         | `0.0.0.0`             | Host, an den der API-Server gebunden wird                              |
| `JAN_API_PORT`         | `1337`                | Jan Server API-Port                                                    |
| `CORTEX_API_PORT`      | `39281`               | Interner Cortex-Engine-Port                                            |
| `CUDA_VISIBLE_DEVICES` | `all`                 | Welche GPUs freigegeben werden sollen (durch Kommas getrennte Indizes) |
| `JAN_DATA_FOLDER`      | `/root/jan`           | Pfad zum Jan-Datenordner                                               |
| `CORTEX_MODELS_PATH`   | `/root/cortex/models` | Pfad zum Modell-Speicher                                               |

### Multi-GPU-Konfiguration

Für Server mit mehreren GPUs (z. B. 2× RTX 3090 auf Clore.ai):

```yaml
environment:
  - CUDA_VISIBLE_DEVICES=0,1  # Beide GPUs verwenden
```

Oder um bestimmte GPUs zuzuweisen:

```bash
# Jan Server nur auf GPU 0 ausführen
docker run -d \
  --name jan-server \
  --gpus '"device=0"' \
  -p 1337:1337 \
  -v jan-data:/root/jan \
  -v jan-models:/root/cortex/models \
  ghcr.io/janhq/cortex:latest
```

### Benutzerdefinierte Modellkonfiguration

```bash
# Alle gezogenen Modelle auflisten
curl http://localhost:1337/v1/models | jq '.data[].id'

# Modelldetails abrufen
curl http://localhost:1337/v1/models/llama3.2:3b-gguf-q4-km

# Ein laufendes Modell stoppen (VRAM freigeben)
curl -X POST http://localhost:1337/v1/models/stop \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2:3b-gguf-q4-km"}'

# Ein Modell löschen (Platz auf der Festplatte freigeben)
curl -X DELETE http://localhost:1337/v1/models/llama3.2:3b-gguf-q4-km
```

### Die API mit einem Token absichern

Jan Server enthält standardmäßig keine Authentifizierung. Verwenden Sie Nginx als Reverse-Proxy:

```bash
apt-get install -y nginx apache2-utils

# Passwortdatei erstellen
htpasswd -c /etc/nginx/.htpasswd admin

# Nginx konfigurieren
cat > /etc/nginx/sites-available/jan-server << 'EOF'
server {
    listen 80;
    server_name _;

    location / {
        auth_basic "Jan Server";
        auth_basic_user_file /etc/nginx/.htpasswd;
        proxy_pass http://127.0.0.1:1337;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
    }
}
EOF

ln -s /etc/nginx/sites-available/jan-server /etc/nginx/sites-enabled/
nginx -t && systemctl restart nginx
```

***

## GPU-Beschleunigung

### CUDA-Beschleunigung verifizieren

Die Cortex-Engine von Jan Server erkennt CUDA automatisch. Überprüfen Sie, ob die GPU verwendet wird:

```bash
# GPU-Speicherauslastung nach dem Laden eines Modells prüfen
nvidia-smi

# Sollte den cortex-Prozess anzeigen, der VRAM verbraucht
# Beispielausgabe:
# | Processes:                                                            |
# |  GPU   GI   CI        PID   Type   Process name            GPU Memory |
# |    0    N/A  N/A    12345    C   /usr/local/bin/cortex    8192MiB |
```

### Inference-Backends wechseln

Cortex unterstützt mehrere Backends:

```bash
# Prüfen, welche Backends innerhalb des Containers verfügbar sind
docker exec jan-server cortex engines list

# TensorRT-LLM-Backend für NVIDIA-GPUs verwenden (schneller, erfordert mehr Einrichtung)
docker exec jan-server cortex engines install tensorrt-llm

# llama.cpp-Backend verwenden (Standard, am kompatibelsten)
docker exec jan-server cortex engines install llama-cpp
```

### Anpassung von Context Window und Batch-Größe

```bash
# Modellparameter für GPU-Leistung anpassen
curl -X POST http://localhost:1337/v1/models/start \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2:3b-gguf-q4-km",
    "ctx_len": 8192,
    "ngl": 99,
    "n_batch": 512,
    "n_parallel": 4,
    "cpu_threads": 8
  }'
```

| Parameter    | Beschreibung                             | Empfehlung                                      |
| ------------ | ---------------------------------------- | ----------------------------------------------- |
| `ngl`        | GPU-Schichten (höher = mehr GPU-Nutzung) | Auf `99` setzen, um die GPU maximal auszunutzen |
| `ctx_len`    | Größe des Kontextfensters                | 4096–32768 je nach VRAM                         |
| `n_batch`    | Batch-Größe für die Prompt-Verarbeitung  | 512 für RTX 3090, 256 für kleinere              |
| `n_parallel` | Parallele Anfrageslots                   | 4–8 für den API-Server-Betrieb                  |

***

## Tipps & bewährte Methoden

### 🎯 Modellauswahl für Clore.ai-Budgets

```bash
# Budget-Stufe (~$0.10/hr, RTX 3060 12GB):
# Verwenden Sie Q4_K_M-Quantisierungen von 7B-Modellen
curl -X POST http://localhost:1337/v1/models/pull \
  -d '{"model": "mistral:7b-instruct-v0.3-gguf-q4-km"}'

# Standard-Stufe (~$0.20/hr, RTX 3090 24GB):
# Verwenden Sie Q5_K_M-Quantisierungen von 13B-Modellen oder Q4 von 30B
curl -X POST http://localhost:1337/v1/models/pull \
  -d '{"model": "llama3.1:8b-instruct-gguf-q5-km"}'

# High-End-Stufe (~$1.10/hr, A100 80GB):
# Vollständige 70B-Modelle in hoher Präzision ausführen
curl -X POST http://localhost:1337/v1/models/pull \
  -d '{"model": "llama3.3:70b-instruct-gguf-q4-km"}'
```

### 💾 Persistenter Modellspeicher

Da Clore.ai-Instanzen ephemer sind, sollten Sie in Erwägung ziehen, externen Speicher einzuhängen:

```bash
# Benennenes Volume verwenden (bleibt mit Docker erhalten)
docker compose down
# Modelle bleiben im benannten Volume 'jan-models' erhalten

# Für wirklich persistenten Speicher über Instanzen hinweg,
# Modelle in Objektspeicher hochladen und beim Start ziehen:
cat > /workspace/startup.sh << 'EOF'
#!/bin/bash
docker compose up -d
sleep 30
# Ziehen Sie Ihre häufig verwendeten Modelle vorab
curl -X POST http://localhost:1337/v1/models/pull \
  -H "Content-Type: application/json" \
  -d '{"model": "mistral:7b-instruct-v0.3-gguf-q4-km"}'
EOF
chmod +x /workspace/startup.sh
```

### 🔗 Jan Server als OpenAI-Drop-in verwenden

```python
# Python — vorhandene OpenAI-Clientbibliotheken verwenden
from openai import OpenAI

client = OpenAI(
    base_url="http://<CLORE_IP>:1337/v1",
    api_key="not-required"  # Jan Server hat standardmäßig keine Authentifizierung
)

response = client.chat.completions.create(
    model="llama3.2:3b-gguf-q4-km",
    messages=[{"role": "user", "content": "Explain quantum computing"}],
    temperature=0.7
)
print(response.choices[0].message.content)
```

```bash
# Streaming-Unterstützung
curl http://localhost:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2:3b-gguf-q4-km",
    "messages": [{"role": "user", "content": "Write a haiku about GPUs"}],
    "stream": true
  }'
```

### 📊 Überwachung der Ressourcennutzung

```bash
# GPU-Auslastung in Echtzeit beobachten
watch -n 1 nvidia-smi

# Container-Ressourcennutzung prüfen
docker stats jan-server

# Detaillierte Logs anzeigen
docker compose logs --tail=100 jan-server

# Modell-Ladezeiten prüfen
docker compose logs jan-server | grep -E "(loaded|started|error)"
```

***

## Fehlerbehebung

### Container startet nicht — GPU nicht gefunden

```bash
# Überprüfen, ob die NVIDIA Docker-Runtime konfiguriert ist
docker info | grep -i nvidia

# GPU-Zugriff direkt testen
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

# Wenn dies fehlschlägt, prüfen Sie die Docker-Daemon-Konfiguration
cat /etc/docker/daemon.json
# Sollte enthalten: {"runtimes": {"nvidia": {...}}}
```

### Modell-Download bleibt hängen oder schlägt fehl

```bash
# Festplattenspeicher prüfen
df -h /root

# Container-Logs auf Fehler prüfen
docker compose logs jan-server | tail -50

# Pull erneut versuchen
curl -X POST http://localhost:1337/v1/models/pull \
  -H "Content-Type: application/json" \
  -d '{"model": "mistral:7b-instruct-v0.3-gguf-q4-km"}'
```

### Kein VRAM mehr (CUDA out of memory)

```bash
# Aktuelle VRAM-Nutzung prüfen
nvidia-smi --query-gpu=memory.used,memory.free --format=csv

# Zuerst alle laufenden Modelle stoppen
curl http://localhost:1337/v1/models | jq -r '.data[].id' | while read model; do
  curl -X POST http://localhost:1337/v1/models/stop \
    -H "Content-Type: application/json" \
    -d "{\"model\": \"$model\"}"
done

# Ein stärker quantisiertes Modell verwenden (Q3 oder Q4 statt Q8)
# Q4_K_M benötigt typischerweise ~50% des Q8-VRAM-Bedarfs
```

### Keine Verbindung zur API von außerhalb des Containers möglich

```bash
# Sicherstellen, dass Port 1337 an allen Schnittstellen gebunden ist
docker ps --format "table {{.Names}}\t{{.Ports}}"
# Sollte anzeigen: 0.0.0.0:1337->1337/tcp

# Clore.ai-Firewallregeln prüfen — Port 1337 in den Servereinstellungen öffnen
# Zuerst lokal testen:
curl http://127.0.0.1:1337/health

# Dann von außen testen:
curl http://<CLORE_SERVER_IP>:<MAPPED_PORT>/health
```

### Langsame Inferenz (CPU-Fallback)

```bash
# Bestätigen, dass CUDA verwendet wird (nicht CPU)
docker exec jan-server cortex ps
# Sollte GPU-Speicherzuweisung anzeigen

# GPU-Schichten beim Modellstart erzwingen
curl -X POST http://localhost:1337/v1/models/start \
  -H "Content-Type: application/json" \
  -d '{"model": "mistral:7b-instruct-v0.3-gguf-q4-km", "ngl": 99}'
```

***

## Weiterführende Lektüre

* [Offizielle Jan.ai-Dokumentation](https://jan.ai/docs) — Vollständige Plattform-Dokumentation
* [Jan GitHub-Repository](https://github.com/janhq/jan) — Quellcode und Issues
* [Jan Server / Jan API](https://github.com/janhq/jan-server) — Server-spezifische Dokumentation
* [Cortex.cpp Engine](https://github.com/janhq/cortex.cpp) — Die zugrunde liegende Inference-Engine
* [Clore.ai Erste Schritte](https://docs.clore.ai/guides/guides_v2-de/erste-schritte/getting-started) — Plattform-Grundlagen
* [GPU-Vergleichsanleitung](https://docs.clore.ai/guides/guides_v2-de/erste-schritte/gpu-comparison) — Wählen Sie die richtige GPU
* [Ollama auf Clore.ai ausführen](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/ollama) — Alternative LLM-Server
* [vLLM auf Clore.ai ausführen](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/vllm) — Hochdurchsatz-Inferenzserver
* [Hugging Face Model Hub](https://huggingface.co/models?library=gguf) — GGUF-Modelle finden

> 💡 **Kosten-Tipp:** Eine RTX 3090 auf Clore.ai (\~$0.20/hr) kann Llama 3.1 8B mit **\~50 Tokens/Sekunde** — ausreichend für den persönlichen Gebrauch oder API mit geringem Traffic. Für Produktionslasten sollten Sie vLLM in Erwägung ziehen (siehe [vLLM-Anleitung](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/vllm)) auf einer A100.