WhisperX：2.2万+星标——2026年生产级ASR部署指南

# Install CUDA 12.8 toolkit first (Linux)
# https://docs.nvidia.com/cuda/cuda-installation-guide-linux/

# Install whisperx
pip install whisperx

# Verify installation
whisperx --version

# Using Astral uv for instant tool execution
uvx whisperx --help

# Or install from GitHub for latest features
uvx git+https://github.com/m-bain/whisperX.git

# Pull pre-built image with all dependencies
docker pull nvidia/cuda:12.8.0-runtime-ubuntu22.04

# Create a Dockerfile for WhisperX
cat > Dockerfile.whisperx << 'EOF'
FROM nvidia/cuda:12.8.0-runtime-ubuntu22.04

RUN apt-get update && apt-get install -y \
    python3-pip ffmpeg git wget \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir whisperx torch==2.7.1

WORKDIR /workspace
ENTRYPOINT ["whisperx"]
EOF

# Build and run
docker build -f Dockerfile.whisperx -t whisperx:latest .
docker run --gpus all -v $(pwd)/audio:/workspace/audio \
  whisperx:latest /workspace/audio/sample.wav --model large-v2

# 1. Create a Hugging Face account at https://huggingface.co
# 2. Generate a read token at https://huggingface.co/settings/tokens
# 3. Accept the license for:
#    - pyannote/speaker-diarization-community-1
#    - pyannote/segmentation-3.0

# Export token
export HF_TOKEN="hf_your_token_here"

# Pass via CLI
whisperx audio.wav --diarize --hf_token $HF_TOKEN

import whisperx

# Load model with faster-whisper backend
model = whisperx.load_model(
    whisper_arch="large-v2",
    device="cuda",
    compute_type="float16",   # float16 for speed, int8 for low VRAM
    language="en",
    asr_options={
        "beam_size": 5,
        "best_of": 5,
        "patience": 2.0,
    }
)

from whisperx.diarize import DiarizationPipeline

# Initialize diarization with pyannote backend
diarize_model = DiarizationPipeline(
    model_name="pyannote/speaker-diarization-community-1",
    use_auth_token=HF_TOKEN,
    device="cuda"
)

# Run diarization with known speaker count
diarize_segments = diarize_model(
    audio,
    min_speakers=2,
    max_speakers=4
)

# Assign speakers to words
result = whisperx.assign_word_speakers(diarize_segments, result)

# Model size options: tiny, base, small, medium, large-v1, large-v2, large-v3
whisperx audio.wav --model large-v3 --language en

# For 8GB VRAM GPUs, use INT8 quantization
whisperx audio.wav --model large-v2 --compute_type int8

# docker-compose.yml
version: "3.8"

services:
  whisperx:
    build:
      context: .
      dockerfile: Dockerfile.whisperx
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - HF_TOKEN=${HF_TOKEN}
      - CUDA_VISIBLE_DEVICES=0
    volumes:
      - ./audio:/workspace/audio:ro
      - ./output:/workspace/output
      - ./models:/root/.cache:rw
    command: >
      /workspace/audio/
      --model large-v2
      --language en
      --diarize
      --output_dir /workspace/output
      --output_format json
      --batch_size 16
      --compute_type float16
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  # Optional: Redis queue for batch jobs
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

# api.py - Production-ready WhisperX API
from fastapi import FastAPI, UploadFile, File
from fastapi.responses import JSONResponse
import whisperx
import torch
import tempfile
import os

app = FastAPI(title="WhisperX ASR Service")

# Preload models at startup
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
BATCH_SIZE = 16
MODEL = whisperx.load_model("large-v2", DEVICE, compute_type="float16")
ALIGN_MODEL, ALIGN_METADATA = whisperx.load_align_model("en", DEVICE)
DIARIZE_MODEL = whisperx.DiarizationPipeline(
    use_auth_token=os.getenv("HF_TOKEN"),
    device=DEVICE
)

@app.post("/transcribe")
async def transcribe(
    file: UploadFile = File(...),
    diarize: bool = True,
    language: str = "en"
):
    """Transcribe audio with word-level timestamps and speaker labels."""
    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
        tmp.write(await file.read())
        tmp_path = tmp.name

    try:
        # Load audio
        audio = whisperx.load_audio(tmp_path)

        # Stage 1: Transcribe
        result = MODEL.transcribe(audio, batch_size=BATCH_SIZE, language=language)

        # Stage 2: Align
        result = whisperx.align(
            result["segments"], ALIGN_MODEL, ALIGN_METADATA,
            audio, DEVICE, return_char_alignments=False
        )

        # Stage 3: Diarize (optional)
        if diarize:
            diarize_segments = DIARIZE_MODEL(audio)
            result = whisperx.assign_word_speakers(diarize_segments, result)

        return {
            "language": result.get("language", language),
            "segments": result["segments"],
            "word_count": sum(len(s.get("words", [])) for s in result["segments"]),
            "speakers": list(set(
                w.get("speaker", "UNKNOWN")
                for s in result["segments"]
                for w in s.get("words", [])
            )) if diarize else []
        }
    finally:
        os.unlink(tmp_path)

@app.get("/health")
async def health():
    return {"status": "ok", "device": DEVICE, "model": "large-v2"}

# Install dependencies
pip install fastapi uvicorn python-multipart

# Start server
uvicorn api:app --host 0.0.0.0 --port 8000 --workers 1

# Test with curl
curl -X POST "http://localhost:8000/transcribe?diarize=true" \
  -F "file=@interview.wav"

# INT8 quantization: 30-40% VRAM reduction, minimal accuracy loss
whisperx audio.wav \
  --model large-v2 \
  --compute_type int8 \
  --batch_size 4 \
  --device cuda

# CPU fallback for alignment (diarization still needs GPU)
whisperx audio.wav \
  --model base \
  --compute_type int8 \
  --device cpu

# Pre-download models to avoid cold-start latency
python3 << 'PYEOF'
import whisperx
import torch

# Download ASR model
model = whisperx.load_model("large-v2", "cuda")
del model

# Download alignment model
align_model, metadata = whisperx.load_align_model("en", "cuda")
del align_model

# Download diarization model
diarize = whisperx.DiarizationPipeline(use_auth_token="token", device="cuda")
del diarize

torch.cuda.empty_cache()
print("Models cached successfully")
PYEOF

# Mount cache in Docker
# -v /host/cache:/root/.cache:rw

# monitoring.py - Prometheus metrics for WhisperX
from prometheus_client import Counter, Histogram, start_http_server
import time

TRANSCRIPTION_DURATION = Histogram(
    "whisperx_transcription_seconds",
    "Time spent transcribing audio",
    ["model", "stage"]
)
REQUEST_COUNT = Counter(
    "whisperx_requests_total",
    "Total transcription requests",
    ["model", "status"]
)

def transcribe_with_metrics(audio_path, model_name="large-v2"):
    start = time.time()
    audio = whisperx.load_audio(audio_path)

    # Stage 1
    t0 = time.time()
    result = MODEL.transcribe(audio, batch_size=16)
    TRANSCRIPTION_DURATION.labels(model_name, "transcribe").observe(time.time() - t0)

    # Stage 2
    t0 = time.time()
    result = whisperx.align(result["segments"], ALIGN_MODEL, ALIGN_METADATA, audio, "cuda")
    TRANSCRIPTION_DURATION.labels(model_name, "align").observe(time.time() - t0)

    # Stage 3
    t0 = time.time()
    diarize_segments = DIARIZE_MODEL(audio)
    result = whisperx.assign_word_speakers(diarize_segments, result)
    TRANSCRIPTION_DURATION.labels(model_name, "diarize").observe(time.time() - t0)

    total = time.time() - start
    REQUEST_COUNT.labels(model_name, "success").inc()
    return result, total

# Expose metrics on port 9090
start_http_server(9090)

# Secure Docker run
docker run --gpus all \
  --read-only \
  --tmpfs /tmp:noexec,nosuid,size=1g \
  --security-opt no-new-privileges:true \
  --cap-drop ALL \
  -e HF_TOKEN_FILE=/run/secrets/hf_token \
  whisperx:latest audio.wav --diarize

# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: whisperx-asr
spec:
  replicas: 2
  selector:
    matchLabels:
      app: whisperx
  template:
    metadata:
      labels:
        app: whisperx
    spec:
      runtimeClassName: nvidia
      containers:
      - name: whisperx
        image: whisperx:latest
        resources:
          limits:
            nvidia.com/gpu: 1
            memory: "16Gi"
          requests:
            nvidia.com/gpu: 1
            memory: "8Gi"
        env:
        - name: HF_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-token-secret
              key: token
        volumeMounts:
        - name: model-cache
          mountPath: /root/.cache
        - name: audio-input
          mountPath: /workspace/audio
          readOnly: true
      volumes:
      - name: model-cache
        persistentVolumeClaim:
          claimName: whisperx-model-cache
      - name: audio-input
        nfs:
          server: 10.0.0.5
          path: /shared/audio