WhisperX: 22K+ Stars — 生产级ASR部署指南 2026

# 先安装 CUDA 12.8 toolkit (Linux)
# https://docs.nvidia.com/cuda/cuda-installation-guide-linux/

# 安装 whisperx
pip install whisperx

# 验证安装
whisperx --version

# 使用 Astral uv 即时执行工具
uvx whisperx --help

# 或从 GitHub 安装获取最新功能
uvx git+https://github.com/m-bain/whisperX.git

# 拉取包含所有依赖的预构建镜像
docker pull nvidia/cuda:12.8.0-runtime-ubuntu22.04

# 为 WhisperX 创建 Dockerfile
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

# 构建并运行
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. 在 https://huggingface.co 创建账户
# 2. 在 https://huggingface.co/settings/tokens 生成读取令牌
# 3. 接受以下模型许可：
#    - pyannote/speaker-diarization-community-1
#    - pyannote/segmentation-3.0

# 导出令牌
export HF_TOKEN="hf_your_token_here"

# 通过 CLI 传入
whisperx audio.wav --diarize --hf_token $HF_TOKEN

import whisperx

# 使用 faster-whisper 后端加载模型
model = whisperx.load_model(
    whisper_arch="large-v2",
    device="cuda",
    compute_type="float16",   # float16 速度优先, int8 节省显存
    language="en",
    asr_options={
        "beam_size": 5,
        "best_of": 5,
        "patience": 2.0,
    }
)

from whisperx.diarize import DiarizationPipeline

# 使用 pyannote 后端初始化分割

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

# 使用已知说话人数量运行分割
diarize_segments = diarize_model(
    audio,
    min_speakers=2,
    max_speakers=4
)

# 为单词分配说话人
result = whisperx.assign_word_speakers(diarize_segments, result)

# 模型大小选项: tiny, base, small, medium, large-v1, large-v2, large-v3
whisperx audio.wav --model large-v3 --language en

# 对于 8GB 显存 GPU，使用 INT8 量化
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]

  # 可选: Redis 队列用于批处理任务
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

# api.py - 生产级 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")

# 启动时预加载模型
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"
):
    """使用词级时间戳和说话人标签转录音频。"""
    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
        tmp.write(await file.read())
        tmp_path = tmp.name

    try:
        # 加载音频
        audio = whisperx.load_audio(tmp_path)

        # 阶段 1: 转录
        result = MODEL.transcribe(audio, batch_size=BATCH_SIZE, language=language)

        # 阶段 2: 对齐
        result = whisperx.align(
            result["segments"], ALIGN_MODEL, ALIGN_METADATA,
            audio, DEVICE, return_char_alignments=False
        )

        # 阶段 3: 分割 (可选)
        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"}

# 安装依赖
pip install fastapi uvicorn python-multipart

# 启动服务
uvicorn api:app --host 0.0.0.0 --port 8000 --workers 1

# 使用 curl 测试
curl -X POST "http://localhost:8000/transcribe?diarize=true" \
  -F "file=@interview.wav"

# INT8 量化: 显存减少30-40%，精度损失极小
whisperx audio.wav \
  --model large-v2 \
  --compute_type int8 \
  --batch_size 4 \
  --device cuda

# 对齐使用 CPU 回退 (分割仍需要 GPU)
whisperx audio.wav \
  --model base \
  --compute_type int8 \
  --device cpu

# 预下载模型以避免冷启动延迟
python3 << 'PYEOF'
import whisperx
import torch

# 下载 ASR 模型
model = whisperx.load_model("large-v2", "cuda")
del model

# 下载对齐模型
align_model, metadata = whisperx.load_align_model("en", "cuda")
del align_model

# 下载分割模型
diarize = whisperx.DiarizationPipeline(use_auth_token="token", device="cuda")
del diarize

torch.cuda.empty_cache()
print("模型缓存成功")
PYEOF

# 在 Docker 中挂载缓存
# -v /host/cache:/root/.cache:rw

# monitoring.py - WhisperX 的 Prometheus 指标
from prometheus_client import Counter, Histogram, start_http_server
import time

TRANSCRIPTION_DURATION = Histogram(
    "whisperx_transcription_seconds",
    "转录音频花费的时间",
    ["model", "stage"]
)
REQUEST_COUNT = Counter(
    "whisperx_requests_total",
    "总转录请求数",
    ["model", "status"]
)

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

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

    # 阶段 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)

    # 阶段 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

# 在 9090 端口暴露指标
start_http_server(9090)

# 安全的 Docker 运行
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