vLLM Server-Guide

Worum geht's?

Das ist der Server-Begleiter zum DeepSeek Coder Guide. Dort wird vLLM als der Hosting-Weg genannt, der "auf ein Team skaliert". Dieser Guide ist das Wie: vLLM auf einem Ubuntu-GPU-Server installieren, es als ordentlichen OpenAI-kompatiblen Dienst betreiben und deine Tools darauf zeigen lassen.

Wichtiger Kontext

Anforderungen und Befehle in den Abschnitten 1–4 stammen aus der offiziellen vLLM-Doku, geprueft am 22. Juni 2026. Die Production-Hardening-Teile (systemd, Binding, Reverse Proxy, Firewall) sind als Praxis gekennzeichnet — Standard-Linux-Serverbetrieb, keine vLLM-spezifische Dokumentation.

1. "Nur lokal?" — Nein. vLLM ist ein Server

Das ist die Frage, die diesen Guide ausgeloest hat, also wird sie zuerst beantwortet.

vLLM ist kein reines lokales Desktop-Tool wie LM Studio. Es ist eine Inferenzserver-Engine mit hohem Durchsatz. Es "lokal" zu betreiben heisst nur, dass der Server zufaellig auf deiner eigenen Maschine sitzt. Es auf einem entfernten Ubuntu-GPU-Server zu betreiben, ist der primaere, vorgesehene Anwendungsfall.

        your Ubuntu server (has the GPU)
        ┌─────────────────────────────┐
        │  vLLM  →  OpenAI-compatible  │
        │           API on :8000       │
        └──────────────┬──────────────┘
                       │  /v1/chat/completions
        ┌──────────────┼──────────────┐
     VS Code        your apps      Claude Code / Codex-style tools

Der Haken ist nicht "lokal vs. Server" — es ist die Hardware:

vLLM ist GPU-first — dein Server braucht eine NVIDIA-GPU

vLLM unterstuetzt offiziell nur Linux und zielt auf NVIDIA-CUDA-GPUs mit Compute Capability 7.5+ (z. B. T4, RTX 20xx, L4, A100, H100, B200). Ein reiner CPU-Build existiert, aber die Doku nennt ihn ausdruecklich nicht optimiert — behandle ihn als nicht praxistauglich fuer echtes Serving. AMD ROCm und Intel XPU werden ueber separate Wheels/Builds unterstuetzt.

Also: Wenn dein Ubuntu-Server eine unterstuetzte NVIDIA-GPU hat → perfekt passend. Wenn es ein reiner CPU-VPS ist → vLLM ist das falsche Tool; nutze stattdessen die gehostete DeepSeek API.

---

2. Anforderungen (bestaetigt)

Anforderung	Wert
OS	Nur Linux (Windows → WSL)
Python	3.10 – 3.13
GPU	NVIDIA, Compute Capability 7.5+
CUDA	12.9 Standard (12.8 und 13.0 ebenfalls verfuegbar)
Treiber	Ein aktueller NVIDIA-Treiber auf dem Host (pruefe mit nvidia-smi)

Treiber vs. Toolkit

Das vLLM-Wheel bringt sein eigenes PyTorch + CUDA-Runtime mit, sodass du auf dem Host hauptsaechlich den NVIDIA-Treiber brauchst, nicht das vollstaendige CUDA-Toolkit. Fuer den Docker-Weg brauchst du das NVIDIA Container Toolkit.

2.1 Den Ubuntu-Host vorbereiten

# Install the recommended NVIDIA driver, then reboot
sudo ubuntu-drivers autoinstall
sudo reboot

# After reboot, confirm the GPU is visible and note the CUDA version
nvidia-smi

Wenn nvidia-smi deine GPU und eine CUDA-Version auflistet, ist der Host bereit.

---

3. vLLM auf Ubuntu installieren

Drei Wege. Waehle einen. Fuer einen dedizierten Server empfehle ich Docker (sauber, reproduzierbar) oder uv (schnell, isoliertes venv).

3.1 uv (empfohlen fuer eine venv-Installation)

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

--torch-backend=auto erkennt deinen CUDA-Treiber und waehlt den passenden PyTorch-Build.

3.2 pip

pip install vllm --extra-index-url https://download.pytorch.org/whl/cu129
# CUDA 13.0 instead:
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu130

3.3 Docker (empfohlen fuer einen dedizierten Server)

Erfordert das NVIDIA Container Toolkit auf dem Host. Offizielles Image: vllm/vllm-openai:latest.

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 --ipc=host \
    vllm/vllm-openai:latest \
    --model deepseek-ai/deepseek-coder-6.7b-instruct

Der Mount -v ~/.cache/huggingface haelt heruntergeladene Weights ueber Container-Neustarts hinweg vor, sodass du nicht jedes Mal mehrere GB grosse Modelle erneut herunterlaedst.

---

4. Den OpenAI-kompatiblen Server starten

Der Kernbefehl — zeige damit auf eine Hugging-Face-Modell-ID:

vllm serve deepseek-ai/deepseek-coder-6.7b-instruct

Das bedient standardmaessig eine OpenAI-kompatible API unter http://localhost:8000. Nuetzliche Flags:

vllm serve <model> \
  --host 0.0.0.0 \        # listen on all interfaces (needed for remote access)
  --port 8000 \
  --api-key <YOUR_KEY>    # require this key on every request

Pruefe die exakte Modell-ID

deepseek-ai/deepseek-coder-6.7b-instruct ist die erwartete Hugging-Face-Repo-ID, aber bestaetige den genauen Namen in der deepseek-ai-HF-Org, bevor du sie ziehst — und denk an die Entscheidung Base vs. Instruct aus dem DeepSeek Coder Guide.

4.1 Pruefen, ob es funktioniert

# List loaded models
curl http://localhost:8000/v1/models

# Chat completion
curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "deepseek-ai/deepseek-coder-6.7b-instruct",
        "messages": [
            {"role": "system", "content": "You are a senior engineer."},
            {"role": "user", "content": "Write a Python function to debounce calls."}
        ]
    }'

Es gibt zwei Endpunkte: /v1/chat/completions (nutze das Instruct-Modell, Nachrichtenformat) und /v1/completions (roher Prompt, gut mit Base-Modellen).

---

5. Es als echten Server betreiben (Praxis)

vllm serve in einem Terminal stirbt, wenn deine SSH-Sitzung endet. Auf einem Server willst du es verwaltet, bei Fehlern neu gestartet und nicht roh ins Internet exponiert haben.

5.1 systemd-Service

Erstelle /etc/systemd/system/vllm.service:

[Unit]
Description=vLLM OpenAI-compatible server
After=network-online.target
Wants=network-online.target

[Service]
User=vllm
WorkingDirectory=/opt/vllm
Environment="HF_HOME=/opt/vllm/hf-cache"
ExecStart=/opt/vllm/.venv/bin/vllm serve deepseek-ai/deepseek-coder-6.7b-instruct \
    --host 127.0.0.1 --port 8000 --api-key ${VLLM_API_KEY}
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now vllm
journalctl -u vllm -f      # watch startup / model load

Exponiere Port 8000 nicht ins oeffentliche Internet

vLLMs --api-key ist ein einzelnes statisches gemeinsames Geheimnis — es ist keine echte Authentifizierung oder Rate-Limitierung. Zwei sichere Muster:

1. Binde an 127.0.0.1 (wie oben) und erreiche es nur ueber einen SSH-Tunnel oder ein privates Netzwerk / VPN.
2. Setze es hinter einen Reverse Proxy (nginx/Caddy), der TLS terminiert und Auth ergaenzt, und schliesse dann den rohen Port per Firewall:

sudo ufw allow 22/tcp
sudo ufw allow 443/tcp
sudo ufw deny 8000/tcp
sudo ufw enable

Lege niemals einen rohen --host 0.0.0.0-vLLM-Port auf eine oeffentliche IP.

5.2 nginx-Reverse-Proxy (Skizze)

server {
    listen 443 ssl;
    server_name llm.yourdomain.tld;
    # ssl_certificate ... (e.g. via certbot)

    location /v1/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_read_timeout 300s;          # long generations
        proxy_buffering off;              # stream tokens through
    }
}

---

6. Clients anbinden

Weil die API OpenAI-kompatibel ist, funktioniert alles, was OpenAI spricht — ueberschreibe einfach base_url.

Python / deine Apps:

from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_KEY>",                 # the --api-key value ("EMPTY" if none set)
    base_url="https://llm.yourdomain.tld/v1",
)
resp = client.chat.completions.create(
    model="deepseek-ai/deepseek-coder-6.7b-instruct",
    messages=[{"role": "user", "content": "Refactor this for readability: ..."}],
)
print(resp.choices[0].message.content)

VS Code (Continue), Claude Code / Codex-artige Tools: zeige sie auf dieselbe Base-URL + denselben Key. Die Editor-Verdrahtung wird im Cursor + DeepSeek + VS Code Guide behandelt.

---

7. vLLM vs. Ollama — welches?

	Ollama	vLLM
Setup-Aufwand	Minimal	Moderat
Ziel	Eine Entwicklermaschine	Server / Team-Backend
Durchsatz & Nebenlaeufigkeit	Bescheiden	Hoch (Batching, Paged Attention)
OpenAI-kompatible API	Ja (/v1)	Ja (/v1)
Am besten fuer	"Laeuft einfach" lokales Coding	Gemeinsamer GPU-Server, viele Clients, groessere Modelle

Faustregel: Ollama fuer deinen Laptop, vLLM fuer den GPU-Server. Fuer den lokalen Weg siehe den Ollama Developer Guide.

---

8. Fazit

• Nur lokal? Nein. vLLM ist eine Server-Engine; eine entfernte Ubuntu-GPU-Maschine ist sein Heimterrain.
• Harte Anforderung: Linux + eine unterstuetzte NVIDIA-GPU (CC 7.5+). Reines CPU ist nicht praxistauglich; ein CPU-VPS → nutze stattdessen die DeepSeek API.
• Installation: uv pip install vllm --torch-backend=auto oder das Docker-Image vllm/vllm-openai.
• Serve: vllm serve <model> → OpenAI-kompatibles /v1 auf Port 8000.
• Productionize: systemd-Unit, an 127.0.0.1 binden, ueber SSH-Tunnel/VPN oder einen TLS-Reverse-Proxy erreichen, den rohen Port per Firewall schliessen.

Fuer die Modellseite (Variantenwahl, Base vs. Instruct, FIM, Prompting) gehe zurueck zum DeepSeek Coder Guide.

---

Quellen

• vLLM-Dokumentation
• vLLM-GPU-Installation
• vLLM-Quickstart
• DeepSeek Coder Guide
• Cursor + DeepSeek + VS Code Guide
• Ollama Developer Guide