Licensed to be used in conjunction with basebox, only.
// installation
Whisper Speech-to-Text mit Helm bereitstellen
Gilt für
Produkt: basebox Server · Zielgruppe: Platform Operator · Referenz: basebox 1.9.3, Chart 0.3.35
Für Sprache-zu-Text (STT) benötigt die basebox-Plattform einen erreichbaren Whisper-Transkriptionsdienst. Auf Kubernetes lässt sich der Dienst als eigener Deployment- und Service-Eintrag über Helm extraObjects bereitstellen. AISRV sendet Audio an dessen HTTP-Endpunkt; das Frontend aktiviert die Mikrofonfunktion separat.
Diese Anleitung beschreibt ein nachweislich eingesetztes Konfigurationsmuster aus einer Installation mit basebox 1.9.3 und dem Inferenz-Image v1.9.4. Sie ist keine generelle Zusage für andere Chart- oder Image-Versionen. Prüfen Sie vor einer Übernahme die tatsächlich installierte Version und die Helm-Templates.
Voraussetzungen vor der Bereitstellung prüfen
- Kubernetes, Helm und eine geeignete NVIDIA-GPU mit funktionsfähiger Container-Runtime stehen bereit.
- Die Whisper-Modellgewichte
openai/whisper-large-v3-turbosind in einem für den Pod erreichbaren Model-Cache vorhanden und anhand der freigegebenen Paketprüfsumme geprüft. - Das benötigte Inferenz-Image steht im Kundencluster zur Verfügung; bei abgeschotteten Umgebungen erfolgt die Bereitstellung über einen geprüften Offline-Import.
- Ein vorhandenes Kubernetes Secret enthält den erforderlichen Inferenz-API-Schlüssel. Verwenden Sie nur Secret-Referenzen, keine Klartextschlüssel in Helm-Werten.
- Sie kennen den Ziel-GPU-Knoten, die für Whisper vorgesehene GPU/MIG-Zuweisung und den vorhandenen Model-Cache-PVC.
- Für die Produktionsänderung liegen aktuelle, geschützte Helm-Werte, Backups, ein Rückfallplan und eine Freigabe vor.
kubectl -n basebox get deployments,services,pvc
kubectl -n basebox get secrets
kubectl get runtimeclass
kubectl get nodes -o wide
# Auf dem zugelassenen GPU-Host (nicht im Kubernetes-Manifest):
nvidia-smi -L
Die GPU-Zuweisung ist installationsabhängig
Das unten gezeigte Muster nutzt nvidia-legacy und eine explizite NVIDIA_VISIBLE_DEVICES-UUID, ohne Kubernetes-GPU-Ressourcenanforderung. Das wurde in der Referenzinstallation verwendet, ist aber kein allgemeines GPU-Scheduling-Muster. Bei anderen Clustern die GPU-Operator-/MIG-Ressourcenanforderungen und die Zuweisung mit dem Plattformteam abstimmen. UUIDs und Knotennamen nicht übernehmen.
AISRV und Frontend mit dem Whisper-Endpunkt verbinden
Ergänzen Sie die folgenden Werte als Overlay zu den vorhandenen freigegebenen Helm-Werten. Der Secret-Name ist ein Platzhalter; der Schlüsselname muss zum tatsächlich provisionierten Secret passen.
aisrv:
env:
AISRV_WHISPER_URL: http://whisper:8081/v1/audio/transcriptions
AISRV_WHISPER_MODEL: openai/whisper-large-v3-turbo
AISRV_WHISPER_API_KEY:
valueFrom:
secretKeyRef:
name: <EXISTING_INFERENCE_API_SECRET>
key: inference_api_key
frontend:
env:
VITE_BB_STT_ENABLED: "true"
AISRV_WHISPER_URL zeigt auf den Kubernetes Service whisper an Port 8081 mit der OpenAI-kompatiblen Route /v1/audio/transcriptions. Die Einstellung VITE_BB_STT_ENABLED aktiviert STT im Frontend. Beide Einstellungen müssen tatsächlich im laufenden Deployment ankommen.
Whisper als Deployment und Service definieren
Das folgende extraObjects-Beispiel bildet die in der Referenzinstallation verifizierte Struktur ab. Ersetzen Sie alle <...>-Platzhalter. Modellpfad, Inferenz-Image, RuntimeClass, GPU-Zuordnung, Secret-Mount, Ressourcen und Probes sind vor jeder Verwendung gegen die Zielinstallation zu prüfen.
extraObjects:
whisper-deployment:
apiVersion: apps/v1
kind: Deployment
metadata:
name: whisper
spec:
replicas: 1
strategy:
type: Recreate
selector:
matchLabels:
app.kubernetes.io/name: whisper
template:
metadata:
labels:
app.kubernetes.io/name: whisper
app.kubernetes.io/component: stt
spec:
# Example: explicit GPU selection with a tested legacy runtime.
# Replace both values and verify node/GPU pairing.
runtimeClassName: nvidia-legacy
nodeSelector:
kubernetes.io/hostname: <APPROVED_GPU_NODE>
imagePullSecrets:
- name: <EXISTING_IMAGE_PULL_SECRET>
containers:
- name: whisper
image: gitea.basebox.health/basebox-distribution/inference:v1.9.4
imagePullPolicy: IfNotPresent
args:
- /model-cache/models/openai/whisper-large-v3-turbo
- --host
- 0.0.0.0
- --port
- "8081"
- --served-model-name
- openai/whisper-large-v3-turbo
- --dtype
- auto
- --gpu-memory-utilization
- "0.05"
- --trust-remote-code
env:
- name: NVIDIA_VISIBLE_DEVICES
value: "<APPROVED_GPU_UUID>"
- name: NVIDIA_DRIVER_CAPABILITIES
value: compute,utility
- name: HF_HOME
value: /model-cache
- name: VLLM_NO_USAGE_STATS
value: "1"
- name: LD_LIBRARY_PATH
value: /usr/local/nvidia/lib64:/usr/local/nvidia/lib:/usr/lib/x86_64-linux-gnu
ports:
- name: http
containerPort: 8081
resources:
requests:
cpu: "500m"
memory: 4Gi
limits:
cpu: "8"
memory: 32Gi
startupProbe:
httpGet: {path: /health, port: http}
periodSeconds: 10
failureThreshold: 180
readinessProbe:
httpGet: {path: /health, port: http}
periodSeconds: 10
livenessProbe:
httpGet: {path: /health, port: http}
periodSeconds: 30
volumeMounts:
- name: model-cache
mountPath: /model-cache
- name: inference-api-key
mountPath: /run/secrets/inference_api_key
subPath: inference_api_key
readOnly: true
- name: dshm
mountPath: /dev/shm
volumes:
- name: model-cache
persistentVolumeClaim:
claimName: <EXISTING_MODEL_CACHE_PVC>
- name: inference-api-key
secret:
secretName: <EXISTING_INFERENCE_API_SECRET>
items:
- key: inference_api_key
path: inference_api_key
- name: dshm
emptyDir:
medium: Memory
sizeLimit: 16Gi
whisper-service:
apiVersion: v1
kind: Service
metadata:
name: whisper
spec:
type: ClusterIP
selector:
app.kubernetes.io/name: whisper
ports:
- name: http
port: 8081
targetPort: http
Sicherheits- und Kompatibilitätsprüfung
--trust-remote-code stammt aus der historischen Referenzkonfiguration. Verwenden Sie diese Option nur, wenn Modellquelle und Modellcode geprüft und freigegeben sind. Die Modellgewichte, das Image und die GPU-Verteilung müssen vor dem Produktivbetrieb zusammenpassen.
Helm-Änderungen vor dem Upgrade prüfen
Verwenden Sie die aktuelle Chart-Version und die bestehenden Kundenwerte. Speichern Sie Live-Werte und gerenderte Manifeste nur in einem geschützten Verzeichnis außerhalb von Git; sie können sensible Informationen enthalten.
umask 077
PRIVATE_DIR="$HOME/private/basebox-stt-review"
mkdir -p "$PRIVATE_DIR"
chmod 700 "$PRIVATE_DIR"
helm get values basebox -n basebox -o yaml > "$PRIVATE_DIR/current-values.yaml"
# CHART verweist auf das geprüfte, zur Installation passende Chart-Paket.
# STT_OVERLAY verweist auf die angepasste und freigegebene YAML-Datei.
helm lint "$CHART" -f "$PRIVATE_DIR/current-values.yaml" -f "$STT_OVERLAY"
helm template basebox "$CHART" -n basebox \
-f "$PRIVATE_DIR/current-values.yaml" -f "$STT_OVERLAY" \
> "$PRIVATE_DIR/rendered.yaml"
Prüfen Sie im Rendering, dass whisper als Deployment und Service angelegt wird, der Service Port 8081 bereitstellt, das Inferenz-Image und die Secret-Referenzen stimmen und bestehende Ressourcen nicht unbeabsichtigt geändert werden. Erst danach erfolgt ein freigegebenes Upgrade nach Updates. Führen Sie keine historische Produktionsskripte ungeprüft aus.
Whisper nach dem Deployment verifizieren
kubectl -n basebox rollout status deployment/whisper --timeout=20m
kubectl -n basebox get deployment whisper
kubectl -n basebox get service whisper
kubectl -n basebox get endpoints whisper
kubectl -n basebox get pods -l app.kubernetes.io/name=whisper
Kontrollieren Sie die Pod-Events und die Modellinitialisierung. Testen Sie anschließend eine Transkription mit einer freigegebenen, nicht sensiblen Audioaufnahme. Prüfen Sie separat die Frontend-Mikrofonfunktion in einem Browser mit aktivierter Mikrofonberechtigung.
- Deployment und Service bereit, Modell geladen: Voraussetzung für funktionierende Backend-Transkription.
- Backend-Transkriptionsantwort erfolgreich: STT-Backend nachgewiesen.
- Browser-Mikrofonaufnahme und Texteinfügung erfolgreich: Ende-zu-Ende-Funktion nachgewiesen.
In der Referenzinstallation waren Deployment, Service und automatisierter Backend-Transkriptionstest erfolgreich. Der Browser-Mikrofontest konnte wegen fehlender Berechtigung im Remote-Client nicht abgeschlossen werden.
Fehlerbehebung bei Start- und Transkriptionsproblemen
| Symptom | Prüfen |
|---|---|
Pod bleibt Pending |
GPU-Knoten, RuntimeClass, PVC und Ressourcenanforderungen |
ImagePullBackOff |
Lokale Image-Verfügbarkeit und Registry-Zugriff |
| Pod startet, wird aber nicht Ready | Modellpfad, Model-Cache-Mount, GPU-Speicher, Health-Endpoint und Startzeit |
| AISRV kann nicht transkribieren | Service-DNS, Port 8081, Route, API-Key-Secret-Referenz |
| Mikrofonfunktion fehlt | Tatsächliche Frontend-Umgebung VITE_BB_STT_ENABLED, Browserberechtigung |
| Andere GPU-Dienste werden beeinträchtigt | Gemeinsame GPU-Auslastung, Speicherreserve und explizite Geräteauswahl |
Weiterlesen: Service-Modelle bereitstellen · AISRV · Inference Server · Updates · Speech-to-Text nutzen