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

// installation

Deployment-Topologien

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

basebox und das LLM müssen nicht auf demselben Server laufen.

Die Standard-Helm-Installation legt die basebox-Anwendungsdienste und den gebündelten Inferenzdienst in eine Kubernetes-Umgebung. Sie können basebox aber auch auf einem reinen CPU-Anwendungsserver betreiben und AISRV mit einem geschützten OpenAI-kompatiblen Inferenz-Endpunkt auf einem separaten GPU-Server verbinden.

Topologie wählen

Topologie Wann sinnvoll GPU-Vorbereitung
Ein Server, ein Cluster Evaluierung oder kompakte Appliance Diesen Server für GPU-Workloads vorbereiten
Ein Cluster mit CPU- und GPU-Knoten Kubernetes bietet die Knotentrennung bereits Nur die GPU-Knoten vorbereiten
Getrennte Anwendungs- und Inferenzserver Das GPU-System wird separat verwaltet oder gehört zu einer anderen Sicherheitszone Der basebox-Anwendungsserver kann rein CPU-basiert sein

Der Anwendungsserver betreibt weiterhin basebox, Identität, Datenbanken, Speicher und RAG-Dienste. Nur die LLM-Inferenz wandert auf den GPU-Server.

Nutzer
  |
  | HTTPS
  v
basebox-Anwendungsserver
  - frontend
  - AISRV
  - Keycloak
  - storesrv
  - ragsrv und Datenbanken
  |
  | authentifizierte OpenAI-kompatible API
  v
Dedizierter GPU-Inferenzserver
  - vLLM oder eine andere kompatible Runtime
  - Modellgewichte und Modell-Cache

Nutzer und Browser verbinden sich mit basebox, nicht direkt mit dem Inferenzserver.

Reiner CPU-Anwendungsserver

Der Server Preparation Guide beschreibt einen kombinierten Server, der GPU-Workloads ausführt. Für einen reinen basebox-Anwendungsserver:

  • Kubernetes, einen Ingress-Controller, Speicher und CloudNativePG installieren;
  • NVIDIA-Treiber, CUDA, NVIDIA Container Toolkit oder GPU Operator nicht installieren, sofern dieser Server nicht einen anderen GPU-Workload trägt;
  • ragsrv und ragsrv-support im CPU-Modus betreiben oder ihre beschleunigten Dienste separat auf einen GPU-Host legen;
  • sicherstellen, dass AISRV den Inferenz-Endpunkt auflösen und erreichen kann;
  • die private CA des Inferenz-Endpunkts in den basebox-Workload importieren, falls er ein privates TLS-Zertifikat verwendet.

Der CPU-Modus ist für RAG und OCR funktionsfähig, die Verarbeitung ist aber langsamer als in einer dedizierten GPU-Konfiguration. Dimensionieren Sie CPU, RAM und Speicher nach Anzahl und Größe der erwarteten Dokumente.

Netzwerk- und Sicherheitsanforderungen

Bei getrennten Servern muss der Inferenz-Endpunkt:

  • die OpenAI-kompatible API /v1/models und Chat-Completions implementieren, die das gewählte basebox-Release verwendet;
  • von AISRV erreichbar sein, aber nicht direkt für Endnutzer freigegeben;
  • eine API-Zugangsberechtigung verlangen;
  • TLS verwenden, wenn Verkehr Hosts oder Sicherheitszonen überschreitet;
  • denselben Modellbezeichner zurückgeben, der in AISRV konfiguriert ist;
  • kompatible Kontext- und Ausgabelimits unterstützen;
  • Health- und Runtime-Metriken für das Betriebsteam bereitstellen.

Behandeln Sie Prompts, abgerufenen Kontext und Inhalte hochgeladener Dokumente als Daten, die vom Anwendungsserver zum Inferenzserver wechseln. Beide Systeme müssen daher innerhalb der freigegebenen Datenverarbeitungsgrenze liegen.

Externe vLLM-Inferenz konfigurieren

Das folgende Beispiel wurde mit basebox 1.7.1, vLLM 0.15.0 und openai/gpt-oss-20b erprobt. Ersetzen Sie Endpunkt, Modell und Limits durch die Werte, die die Ziel-Runtime tatsächlich meldet.

1. Das Credential-Secret anlegen

Namespace und Secret vor der basebox-Installation anlegen. Den Schlüssel einlesen, ohne ihn in eine Values-Datei zu schreiben:

kubectl create namespace basebox --dry-run=client -o yaml | kubectl apply -f -

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. Die Helm-Values ergänzen

values.external-inference.yaml anlegen:

inference:
  enabled: false

aisrv:
  env:
    AISRV_LLM_URL: "https://inference.customer.internal"
    AISRV_LLM_CHAT_ENDPOINT: "v1/chat/completions"
    AISRV_LLM_PROVIDER: "vLLM"
    AISRV_LLM_MODEL: "openai/gpt-oss-20b"
    AISRV_LLM_CONTEXT_SIZE: "32768"
    AISRV_LLM_WORD_LIMIT: "2000"
    AISRV_LLM_API_KEY:
      valueFrom:
        secretKeyRef:
          name: external-inference-api
          key: api-key
    VLLM_API_KEY:
      valueFrom:
        secretKeyRef:
          name: external-inference-api
          key: api-key

ragsrv:
  enabled: true
  mode: cpu

ragsrv-support:
  enabled: true
  mode: cpu

Aktuelle basebox-Releases leiten VLLM_API_KEY aus dem Provider-Namen vLLM ab. Setzen Sie beide API-Key-Einträge auf dasselbe Secret, damit die Values sowohl mit der allgemeinen AISRV-Einstellung als auch mit der providerspezifischen Runtime-Abfrage kompatibel bleiben.

Kombinieren Sie diese Datei mit den Domain-, TLS-, Speicher- und Administrator-Einstellungen aus Helm Charts verwenden.

3. Vor der Installation rendern

helm template basebox \
  oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version 0.3.32 \
  --namespace basebox \
  -f values.customer.yaml \
  -f values.external-inference.yaml \
  > /tmp/basebox-rendered.yaml

rg -n 'AISRV_LLM_URL|VLLM_API_KEY|name: inference' \
  /tmp/basebox-rendered.yaml

Prüfen Sie das Rendering. Es muss den externen Endpunkt und die Secret-Referenzen enthalten und darf kein inference-Deployment enthalten.

4. Installieren

helm upgrade --install basebox \
  oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version 0.3.32 \
  --namespace basebox \
  --wait \
  --timeout 120m \
  -f values.customer.yaml \
  -f values.external-inference.yaml

5. Die Grenze prüfen

kubectl -n basebox get pods
kubectl -n basebox get deployment inference

Der zweite Befehl muss NotFound zurückgeben. Prüfen Sie dann das entfernte Modell aus AISRV heraus, ohne die 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" >/dev/null
'

Führen Sie den normalen Login- und Chat-Smoke-Test durch. Stoppen oder blockieren Sie außerdem den Inferenz-Endpunkt in einem freigegebenen Wartungsfenster und bestätigen Sie, dass basebox den Fehler anzeigt und sich erholt, sobald die Inferenz wieder bereit ist. basebox fällt nicht stillschweigend auf ein anderes Modell zurück, wenn der konfigurierte Endpunkt offline ist.

TLS ohne Internetzugang

Let's Encrypt ist für eine private basebox-Installation nicht erforderlich.

  • Verwenden Sie global.tls.mode=existing-secret, wenn Ihre Organisation ein Zertifikat ihrer internen CA bereitstellt.
  • Verwenden Sie global.tls.mode=local für Evaluierung oder selbst verwaltetes lokales Vertrauen. Jedes Client-Gerät muss der ausstellenden CA vertrauen.
  • Behandeln Sie das basebox-Ingress-Zertifikat und das Zertifikat des Inferenz-Endpunkts als getrennte Vertrauensentscheidungen. AISRV muss beiden Pfaden vertrauen, die es nutzt.

Siehe Helm Charts verwenden und den Lokalen Schnellstart für die entsprechenden Installationswege.

Produktions-Checkliste

Prüfen Sie vor dem Produktiveinsatz eines getrennten Deployments:

  • privates DNS und Zertifikatsinhaberschaft;
  • Firewall-Regeln nur von AISRV zur Inferenz;
  • Secret-Rotation, ohne Zugangsdaten in Git oder Helm-Values zu schreiben;
  • Modellidentität, Kontextlimit, Ausgabelimit, Streaming und Timeouts;
  • Inferenz-Health, GPU-Metriken, Logs, Alarmierung und Kapazitätsgrenzen;
  • Backup- und Rollback-Verfahren für basebox und Datenbanken;
  • Fehler- und Wiederherstellungsverhalten;
  • Platzierung und Ressourcenverantwortung für RAG, OCR und STT;
  • die dokumentierte Datenverarbeitungsgrenze.

Dieselbe Topologie funktioniert, wenn der Inferenz-Endpunkt von einem anderen Kubernetes-Cluster oder einem freigegebenen API-Anbieter bereitgestellt wird. Anforderungen an Sicherheit, Latenz, Kapazität und Data Governance gelten weiterhin.