Zum Inhalt
Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// installation

Inferenz anbinden

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

AISRV auf den Inferenz-Endpunkt richten – gebündeltes vLLM auf demselben Knoten oder ein externer OpenAI-kompatibler Endpunkt auf einem separaten GPU-Host. In beiden Fällen gilt: Nutzer sprechen nie direkt mit der Inferenz; AISRV ruft sie über die OpenAI-kompatible API auf, und der Modellbezeichner muss auf beiden Seiten übereinstimmen.

Variante A: gebündeltes vLLM

Das Umbrella-Chart stellt inference bereit. Sie legen Modell, GPUs und Cache fest:

inference:
  enabled: true
  resources:
    requests: {cpu: 4000m, memory: 32Gi, nvidia.com/gpu: 1}   # 2 bei TP=2
    limits:   {cpu: 8000m, memory: 64Gi, nvidia.com/gpu: 1}
  env:
    MODEL_ID: "openai/gpt-oss-20b"        # HuggingFace-Bezeichner
    MAX_INPUT_TOKENS: "32000"
    NUM_GPUS: "1"                          # = Tensor-Parallelismus
    SHM_SIZE: "32gb"
    HF_HOME: "/data/.cache/huggingface"
    HF_TOKEN:
      valueFrom:
        secretKeyRef: {name: hf-credentials, key: token}
    API_KEY:
      valueFrom:
        secretKeyRef: {name: llm-credentials, key: api-key}
  livenessProbe:
    httpGet: {path: /health, port: http}
    initialDelaySeconds: 300               # Modellladezeit
    periodSeconds: 30
  readinessProbe:
    httpGet: {path: /health, port: http}
    initialDelaySeconds: 180
    periodSeconds: 10
  volumes:
    - name: model-cache
      persistentVolumeClaim: {claimName: inference-models}
  volumeMounts:
    - name: model-cache
      mountPath: /data/.cache/huggingface

AISRV auf den Dienst richten:

aisrv:
  env:
    AISRV_LLM_URL: "http://inference:8000"
    AISRV_LLM_CHAT_ENDPOINT: "/v1/chat/completions"
    AISRV_LLM_PROVIDER: "vLLM"
    AISRV_LLM_MODEL: "openai/gpt-oss-20b"   # exakt wie MODEL_ID
    AISRV_LLM_CONTEXT_SIZE: "32768"
    AISRV_LLM_MAX_TOKENS: "8000"
    AISRV_LLM_API_KEY:
      valueFrom:
        secretKeyRef: {name: llm-credentials, key: api-key}
    VLLM_API_KEY:
      valueFrom:
        secretKeyRef: {name: llm-credentials, key: api-key}

Aktuelle Releases leiten VLLM_API_KEY aus dem Provider-Namen vLLM ab; setzen Sie beide Schlüssel auf dasselbe Secret. Weitere Parameter (Temperatur, Top-p, Repetition Penalty, Wortlimit): Modelle konfigurieren. Offline-Betrieb mit vorab geladenen Modellen (HF_HUB_OFFLINE: "1"): Inference Server.

Variante B: externer Endpunkt

Für einen separaten GPU-Host, einen anderen Cluster oder – wo freigegeben – einen externen Anbieter: gebündelte Inferenz abschalten und AISRV auf den Endpunkt richten.

  1. Credential-Secret anlegen, ohne den Schlüssel in eine Datei zu schreiben: 
    read -s VLLM_API_KEY
kubectl -n basebox create secret generic external-inference-api \
  --from-literal=api-key="$VLLM_API_KEY" --dry-run=client -o yaml | kubectl apply -f -
unset VLLM_API_KEY
  2. Values (values.external-inference.yaml): inference.enabled: false, AISRV_LLM_URL: "https://inference.customer.internal", Provider, Modell, Kontext, beide API-Key-Einträge aus dem Secret; ragsrv/ragsrv-support im gewünschten Modus.
  3. Rendern und prüfen, dass kein inference-Deployment enthalten ist.
  4. Installieren mit beiden Values-Dateien.
  5. Grenze prüfen: kubectl -n basebox get deployment inference → NotFound.

Anforderungen an den Endpunkt: OpenAI-kompatible API (/v1/models, Chat Completions), API-Zugangsberechtigung, TLS über Hostgrenzen, gleicher Modellbezeichner, passende Kontext-/Ausgabelimits, Health- und Metrik-Endpunkte; nur von AISRV erreichbar. Private CA in den basebox-Workload importieren. Das vollständige, mit basebox 1.7.1 / vLLM 0.15.0 / openai/gpt-oss-20b erprobte Beispiel: Deployment-Topologien.

Modell wählen

Welches Modell auf welche GPU passt, mit Kontext- und Parallelitätsrichtwerten: LLM-Empfehlungen. Was geprüft, empfohlen oder lediglich kompatibel ist: Modelle & Inferenz. Bekannte Eigenheiten (GPT-OSS braucht vLLM 0.10.1+ und Reasoning-Parser; Qwen 3 /no_think; DeepSeek-R1 Thinking-Tokens): Bekannte Probleme.

Tensor-Parallelismus (NUM_GPUS) muss die Attention-Heads teilen – GPT-OSS 120B erlaubt 1, 2, 4, 8. Für zwei GPUs das Paar mit dem schnellsten Peer-Pfad wählen (nvidia-smi topo -m).

Prüfen

Ladevorgang beobachten – beim ersten Start mehrere Minuten, Kaltstart-Toleranz der 2 × H200 etwa 6 Minuten:

kubectl -n basebox logs -l app.kubernetes.io/name=inference -f | grep -iE "download|loading|ready"

Modell aus AISRV heraus prüfen, ohne Zugangsdaten anzuzeigen:

kubectl -n basebox exec deploy/aisrv -c aisrv -- sh -c '
  curl --fail --max-time 15 -H "Authorization: Bearer $VLLM_API_KEY" "$AISRV_LLM_URL/v1/models"'

Der zurückgegebene Modellbezeichner muss AISRV_LLM_MODEL entsprechen. Dann in der Oberfläche anmelden, eine Chat-Anfrage stellen und unter Benutzermenü → „Über" prüfen, dass Modell und Kontextgröße stimmen.

Fehlerverhalten testen: Inferenz in einem Wartungsfenster stoppen oder blockieren – basebox zeigt den Fehler an und erholt sich, sobald der Endpunkt wieder bereit ist. Es gibt keinen stillen Rückfall auf ein anderes Modell.

Häufige Fehlerbilder

Symptom Ursache Lösung
Inferenz-Pod Pending GPU-Ressource nicht frei oder falscher Ressourcenname kubectl describe node; Requests prüfen
Pod startet, dann Probe-Neustarts initialDelaySeconds zu kurz für den Modell-Download Probes auf 300/180 s; PVC für Modell-Cache
„Model not found" in AISRV AISRV_LLM_MODEL ≠ Bezeichner unter /v1/models Exakt übernehmen (Groß-/Kleinschreibung)
401 vom Endpunkt Schlüssel ungleich Beide Seiten aus demselben Secret
„data transmission failed (SSE)" im Chat Verbindung AISRV ↔ Inferenz oder ragsrv aisrv-Logs; Netzwerk/TLS zwischen den Hosts
Langer Kontext bricht ab AISRV_LLM_CONTEXT_SIZE > Runtime-Kontext Werte angleichen

Nächster Schritt: Installation prüfen