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 낮은 VRAM
    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 VRAM 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 양자화: VRAM 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