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

// installation

Inference

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

Übersicht

Der Inferenzserver stellt die LLM-Inferenz (Large Language Model) für die basebox-KI-Plattform bereit. Er hostet und bedient LLM-Modelle für Textgenerierung, Chat Completions und weitere KI-gestützte Funktionen. Der Dienst benötigt für optimale Leistung in der Regel GPU-Beschleunigung.

Deployment

Der Inferenzserver wird per Helm-Chart in Kubernetes-Cluster mit GPU-Unterstützung bereitgestellt.

Helm-Chart-Konfiguration

Grundeinstellungen

Parameter Standard Beschreibung
replicaCount 1 Anzahl der Inferenzserver-Pod-Replikate
image.repository gitea.basebox.health/basebox-distribution/inference Container-Image-Repository
image.pullPolicy IfNotPresent Image-Pull-Policy
image.tag latest Auszurollender Image-Tag
fullnameOverride inference Vollständigen Namen des Deployments überschreiben

Dienstkonfiguration

Parameter Standard Beschreibung
service.type ClusterIP Kubernetes-Service-Typ
service.port 8080 Service-Port

Ressourcenverwaltung

Parameter Standard Beschreibung
resources {} CPU-/Speicher-/GPU-Requests und -Limits
autoscaling.enabled false Horizontales Pod-Autoscaling aktivieren
autoscaling.minReplicas 1 Minimale Anzahl Replikate
autoscaling.maxReplicas 100 Maximale Anzahl Replikate
autoscaling.targetCPUUtilizationPercentage 80 Ziel-CPU-Auslastung für die Skalierung

Health-Checks

Parameter Standard Beschreibung
livenessProbe {} Konfiguration der Liveness-Probe (standardmäßig aus)
readinessProbe {} Konfiguration der Readiness-Probe (standardmäßig aus)

Umgebungsvariablen

Kernkonfiguration

Variable Standard Beschreibung
API_KEY Erforderlich API-Schlüssel zur Authentifizierung
HOSTNAME 0.0.0.0 Hostname, an den der Server bindet
PORT 8080 Server-Port

Modellkonfiguration

Variable Standard Beschreibung
MODEL_ID meta-llama/Llama-3.1-8B-Instruct HuggingFace-Modellbezeichner
MAX_INPUT_TOKENS 16000 Maximale Eingabe-Tokenlänge
HF_TOKEN Erforderlich HuggingFace-API-Token für Modell-Downloads

GPU-Konfiguration

Variable Standard Beschreibung
NUM_GPUS 1 Anzahl zu nutzender GPUs
SHM_SIZE 16gb Größe des Shared Memory für GPU-Operationen

Cache-Konfiguration

Variable Beschreibung
NUMBA_CACHE_DIR Cache-Verzeichnis für die Numba-JIT-Kompilierung
TRITON_CACHE_DIR Cache-Verzeichnis für Triton-Kernel
HF_HOME HuggingFace-Home-Verzeichnis (optional)
TRANSFORMERS_CACHE Cache-Verzeichnis für Transformers-Modelle (optional)
HF_HUB_OFFLINE Offline-Modus aktivieren (nur gecachte Modelle)
HF_HUB_ENABLE_HF_TRANSFER Schnellere HuggingFace-Übertragungen aktivieren

Speicherkonfiguration

Volumes für den Modell-Cache

Für persistente Modellspeicherung und Cache:

volumes:
  - name: model-cache
    persistentVolumeClaim:
      claimName: inference-models
  - name: cache-dir
    persistentVolumeClaim:
      claimName: inference-cache

volumeMounts:
  - name: model-cache
    mountPath: /data/.cache/huggingface
  - name: cache-dir
    mountPath: /data

Konfigurationsbeispiele

Produktivkonfiguration

# values-production.yaml
replicaCount: 2

image:
  repository: gitea.basebox.health/basebox-distribution/inference
  tag: "v1.2.3"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 8080

resources:
  requests:
    cpu: 4000m
    memory: 32Gi
    nvidia.com/gpu: 2
  limits:
    cpu: 8000m
    memory: 64Gi
    nvidia.com/gpu: 2

livenessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 300
  periodSeconds: 30
  timeoutSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 180
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 5

volumes:
  - name: model-cache
    persistentVolumeClaim:
      claimName: inference-models
  - name: cache-dir
    emptyDir:
      sizeLimit: 50Gi

volumeMounts:
  - name: model-cache
    mountPath: /data/.cache/huggingface
  - name: cache-dir
    mountPath: /data

nodeSelector:
  nvidia.com/gpu: "true"
  gpu-type: "a100"

env:
  API_KEY: "<generate-secure-api-key>"
  HOSTNAME: "0.0.0.0"
  PORT: "8080"

  # Model configuration
  MODEL_ID: "meta-llama/Llama-3.1-70B-Instruct"
  MAX_INPUT_TOKENS: "32000"
  HF_TOKEN: "<your-huggingface-token>"

  # GPU configuration
  NUM_GPUS: "2"
  SHM_SIZE: "32gb"

  # Cache configuration
  NUMBA_CACHE_DIR: "/data/numba_cache"
  TRITON_CACHE_DIR: "/data/triton_cache"
  HF_HOME: "/data/.cache/huggingface"
  TRANSFORMERS_CACHE: "/data/.cache/huggingface/transformers"

extraObjects:
  inference-models:
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: inference-models
    spec:
      accessModes:
        - ReadWriteOnce
      storageClassName: fast-ssd
      resources:
        requests:
          storage: 200Gi

Offline-Konfiguration

Für Umgebungen ohne Internetzugang (vorab heruntergeladene Modelle):

# values-offline.yaml
replicaCount: 1

resources:
  requests:
    cpu: 4000m
    memory: 32Gi
    nvidia.com/gpu: 1
  limits:
    cpu: 8000m
    memory: 64Gi
    nvidia.com/gpu: 1

volumes:
  - name: model-cache
    persistentVolumeClaim:
      claimName: inference-models-preloaded

volumeMounts:
  - name: model-cache
    mountPath: /data/.cache/huggingface

env:
  API_KEY: "<secure-api-key>"
  MODEL_ID: "meta-llama/Llama-3.1-8B-Instruct"
  HF_TOKEN: "<huggingface-token>"
  NUM_GPUS: "1"

  # Offline mode
  HF_HUB_OFFLINE: "1"
  HF_HOME: "/data/.cache/huggingface"
  TRANSFORMERS_CACHE: "/data/.cache/huggingface/transformers"
  NUMBA_CACHE_DIR: "/data/numba_cache"
  TRITON_CACHE_DIR: "/data/triton_cache"

Konfiguration für kleine Modelle

Für Umgebungen mit begrenzten Ressourcen:

# values-small.yaml
replicaCount: 1

resources:
  requests:
    cpu: 2000m
    memory: 16Gi
    nvidia.com/gpu: 1
  limits:
    cpu: 4000m
    memory: 32Gi
    nvidia.com/gpu: 1

env:
  API_KEY: "<secure-api-key>"
  MODEL_ID: "meta-llama/Llama-3.2-3B-Instruct"
  MAX_INPUT_TOKENS: "8000"
  HF_TOKEN: "<huggingface-token>"
  NUM_GPUS: "1"
  SHM_SIZE: "8gb"

Multi-GPU-Konfiguration

Für große Modelle, die mehrere GPUs benötigen:

# values-multi-gpu.yaml
replicaCount: 1

resources:
  requests:
    cpu: 8000m
    memory: 128Gi
    nvidia.com/gpu: 4
  limits:
    cpu: 16000m
    memory: 256Gi
    nvidia.com/gpu: 4

nodeSelector:
  nvidia.com/gpu: "true"
  gpu-type: "a100"

tolerations:
  - key: "nvidia.com/gpu"
    operator: "Exists"
    effect: "NoSchedule"

env:
  API_KEY: "<secure-api-key>"
  MODEL_ID: "meta-llama/Llama-3.1-405B-Instruct"
  MAX_INPUT_TOKENS: "64000"
  HF_TOKEN: "<huggingface-token>"
  NUM_GPUS: "4"
  SHM_SIZE: "64gb"
  HOSTNAME: "0.0.0.0"
  PORT: "8080"

Installation

Voraussetzungen

  • Kubernetes-Cluster (1.23+)
  • Helm 3.x
  • GPU-Knoten mit NVIDIA GPU Operator
  • NVIDIA-Systemtreiber Version >= 550.54.14 (für CUDA-12.4-Kompatibilität)
  • Storage-Provisioner mit dynamischer Bereitstellung
  • HuggingFace-Konto mit API-Token
  • Ausreichend Speicher für Modelldateien (50GB–500GB je nach Modell)

NVIDIA GPU Operator installieren

helm repo add nvidia https://helm.ngc.nvidia.com/nvidia
helm repo update

helm install gpu-operator nvidia/gpu-operator \
  --namespace gpu-operator \
  --create-namespace \
  --wait

Modelle vorab herunterladen (optional)

Für schnelleren Start und Offline-Deployments:

# Create a job to download models
kubectl create job model-download \
  --image=gitea.basebox.health/basebox-distribution/inference:latest \
  --namespace basebox \
  -- python -c "from transformers import AutoModel; AutoModel.from_pretrained('meta-llama/Llama-3.1-8B-Instruct')"

Inferenzserver installieren

# Install with custom values
helm install inference oci://gitea.basebox.health/basebox-distribution/helm/inference \
  --values values-production.yaml \
  --namespace basebox \
  --create-namespace

# Verify installation
kubectl get pods -n basebox -l app.kubernetes.io/name=inference

Upgrade

helm upgrade inference oci://gitea.basebox.health/basebox-distribution/helm/inference \
  --values values-production.yaml \
  --namespace basebox

Deinstallation

helm uninstall inference --namespace basebox

# Delete PVCs if needed
kubectl delete pvc -n basebox inference-models

Prüfung

Deployment prüfen

# Check pods
kubectl get pods -n basebox -l app.kubernetes.io/name=inference

# View logs
kubectl logs -n basebox -l app.kubernetes.io/name=inference --tail=100 -f

# Check GPU allocation
kubectl describe pod -n basebox -l app.kubernetes.io/name=inference | grep -A5 "nvidia.com/gpu"

Inferenz-Endpunkt testen

# Port forward
kubectl port-forward -n basebox svc/inference 8000:8000

# Test API (example with curl)
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'

Modellladevorgang beobachten

Das Laden des Modells kann beim ersten Start mehrere Minuten dauern:

# Watch logs for model download progress
kubectl logs -n basebox -l app.kubernetes.io/name=inference -f | grep -i "download\|loading"

GPU-Konfiguration

GPU-Anforderungen

  • NVIDIA-GPU mit CUDA-Unterstützung (Compute Capability 7.0+)
  • Ausreichend VRAM für das Modell:
  • 7B-Modelle: 16GB+ VRAM
  • 13B-Modelle: 24GB+ VRAM
  • 70B-Modelle: 80GB+ VRAM (A100)
  • 405B-Modelle: 320GB+ VRAM (4x A100)

GPU-Ressourcenzuteilung

resources:
  requests:
    nvidia.com/gpu: 1
  limits:
    nvidia.com/gpu: 1

# For multi-GPU
resources:
  requests:
    nvidia.com/gpu: 4
  limits:
    nvidia.com/gpu: 4

GPU-Zugriff prüfen

# Check GPU inside pod
kubectl exec -n basebox <pod-name> -- nvidia-smi

# Check GPU utilization
kubectl exec -n basebox <pod-name> -- nvidia-smi dmon

Modellauswahl

Unterstützte Modelle

Richtwerte nach Modellgröße

Modellgröße Benötigter VRAM GPU-Typ Anwendungsfall
1B–3B 8–16GB T4, L4 Kleine Deployments, Tests
7B–13B 16–24GB A10, L40 Allgemeiner Einsatz
70B 80GB A100 Antworten hoher Qualität
405B 320GB 4x A100 Maximale Qualität

Integration mit anderen Diensten

AISRV-Integration

AISRV verbindet sich für LLM-Fähigkeiten mit dem Inferenzserver:

# AISRV configuration
env:
  AISRV_LLM_URL: "http://inference:8000"
  AISRV_LLM_CHAT_ENDPOINT: "/v1/chat/completions"
  AISRV_LLM_API_KEY: "<must-match-inference-api-key>"
  AISRV_LLM_MODEL: "meta-llama/Llama-3.1-8B-Instruct"

Sicherheitsaspekte

API-Schlüsselverwaltung

  • Kryptografisch sichere API-Schlüssel erzeugen
  • API-Schlüssel in Kubernetes-Secrets speichern
  • API-Schlüssel regelmäßig rotieren
  • Je Umgebung unterschiedliche Schlüssel verwenden

Modellzugriff

  • HuggingFace-Tokens als Secrets schützen
  • Private Modell-Repositories für proprietäre Modelle nutzen
  • Zugriffsprotokollierung für Audit-Trails einrichten

Netzwerksicherheit

  • ClusterIP für rein internen Zugriff nutzen
  • Network Policies umsetzen
  • Ratenbegrenzung auf Ingress-Ebene (bei externer Freigabe)

Ressourcenisolierung

  • Node Selectors für GPU-Knoten nutzen
  • Ressourcenquoten umsetzen
  • GPU-Speichernutzung überwachen

Performance-Tuning

Shared Memory

Shared Memory für bessere GPU-Leistung erhöhen:

env:
  SHM_SIZE: "32gb"

# Also configure at pod level
podSecurityContext:
  fsGroup: 2000

volumes:
  - name: dshm
    emptyDir:
      medium: Memory
      sizeLimit: 32Gi

volumeMounts:
  - name: dshm
    mountPath: /dev/shm

Batch-Verarbeitung

Für hohen Durchsatz:

  • MAX_INPUT_TOKENS für längere Kontexte erhöhen
  • Batching in der Modellserver-Konfiguration aktivieren

Modellladezeit

Startzeit verkürzen:

  • Modelle vorab auf persistente Volumes laden
  • HF_HUB_OFFLINE=1 mit gecachten Modellen nutzen
  • Schnelleren Speicher nutzen (NVMe-SSD)

Monitoring und Metriken

Health-Checks

Health-Probes konfigurieren:

livenessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 300 # Allow time for model loading
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 180
  periodSeconds: 10

GPU-Monitoring

GPU-Metriken überwachen:

  • GPU-Auslastung
  • VRAM-Nutzung
  • Temperatur
  • Leistungsaufnahme

Für die Prometheus-Integration NVIDIA DCGM nutzen.

Anwendungsmetriken

Inferenzleistung überwachen:

  • Anfragelatenz
  • Tokens pro Sekunde
  • Warteschlangentiefe
  • Fehlerraten

Modell-Download und -Caching

Modelle vorab herunterladen

Ein PVC anlegen und Modelle vor dem Deployment herunterladen:

# model-download-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: model-download
  namespace: basebox
spec:
  template:
    spec:
      containers:
        - name: downloader
          image: gitea.basebox.health/basebox-distribution/inference:latest
          env:
            - name: HF_TOKEN
              value: "<your-token>"
            - name: HF_HOME
              value: "/models"
          command:
            - python
            - -c
            - |
              from transformers import AutoModelForCausalLM, AutoTokenizer
              model_id = "meta-llama/Llama-3.1-8B-Instruct"
              AutoModelForCausalLM.from_pretrained(model_id)
              AutoTokenizer.from_pretrained(model_id)
          volumeMounts:
            - name: model-cache
              mountPath: /models
      volumes:
        - name: model-cache
          persistentVolumeClaim:
            claimName: inference-models
      restartPolicy: OnFailure

Offline-Deployment

Nach dem Vorab-Download:

env:
  HF_HUB_OFFLINE: "1"
  HF_HOME: "/models"
  TRANSFORMERS_CACHE: "/models/transformers"

volumes:
  - name: model-cache
    persistentVolumeClaim:
      claimName: inference-models

volumeMounts:
  - name: model-cache
    mountPath: /models

Kostenoptimierung

GPU-Auswahl

  • T4/L4: Kosteneffizient für kleinere Modelle (7B–13B)
  • A10/L40: Ausgewogenes Leistungs-/Kostenverhältnis für mittlere Modelle
  • A100: Für große Modelle erforderlich, teuer