WhisperX：给 Whisper 加上时间对齐与说话人识别的超强转写流水线

开篇

这篇教程带你从零跑通 WhisperX 的完整 Demo：输入一个视频或音频文件，输出带精确时间戳的转写文本，并区分每句话是谁说的。最终你会得到一个可运行的本地转写环境，可以直接处理真实文件。

前置条件

• Python 3.9-3.12，推荐 3.10，避免依赖冲突
• FFmpeg 已安装并加入 PATH，用于音频解码
• CUDA 显卡（可选但强烈建议），显存 ≥ 6GB，否则CPU跑大模型会非常慢
• 系统依赖：Linux 需要 build-essential，macOS 需要 xcode-select --install，Windows 需安装 Microsoft C++ Build Tools

安装部署

1. 创建虚拟环境并安装依赖

python -m venv whisperx_env
source whisperx_env/bin/activate  # Windows 用 whisperx_envScriptsactivate
pip install -U pip

2. 安装 WhisperX

pip install whisperx

如果安装的是 CPU 版本 PyTorch，先执行：

pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu

3. 初始化模型目录（可选）

WhisperX 第一次运行会自动下载模型，但建议手动预下载，避免运行时卡住：

python -c "
import whisperx
whisperx.load_model('large-v3', device='cuda')
whisperx.load_align_model(language_code='en', device='cuda')
"

这个命令会下载 Whisper 模型和强制对齐模型到 ~/.cache/huggingface，后续转写直接用。

4. 验证安装

whisperx --help

看到命令选项列表说明安装成功。

第一个 Demo

我们用一个真实可下载的英语播客片段，完整走一遍转写、对齐、说话人识别流程。以下命令全部在项目目录下执行。

第一步：准备测试音频

这一步要做什么：下载一段 30 秒的公开领域音频，避免版权问题。

wget https://github.com/m-bain/whisperX/raw/main/samples/example.wav

Windows 用户可以用 PowerShell：Invoke-WebRequest -Uri "..." -OutFile example.wav

第二步：写转写脚本

这一步要做什么：创建一个 Python 脚本，完成转录（transcribe）、对齐（align）、说话人识别（diarize）三件事。

cat > demo.py << 'EOF'
import whisperx

device = "cuda"  # 无GPU改成 "cpu"
audio_file = "example.wav"

# 1. 转写文本 + 粗时间戳
model = whisperx.load_model("large-v3", device=device)
result = model.transcribe(audio_file, language="en")
print("转写完成，句子数：", len(result["segments"]))

# 2. 强制对齐，补精确到单词的时间戳
model_a, metadata = whisperx.load_align_model(language_code="en", device=device)
result = whisperx.align(result["segments"], model_a, metadata, audio_file, device)
print("对齐后首句时间：", result["segments"][0]["start"], "-", result["segments"][0]["end"])

# 3. 说话人识别并关联到句子
diarize_model = whisperx.DiarizationPipeline(device=device)
diarize_segments = diarize_model(audio_file)
result = whisperx.assign_word_speakers(diarize_segments, result)

for seg in result["segments"]:
    print(f'{seg["speaker"]} [{seg["start"]:.1f}s - {seg["end"]:.1f}s] {seg["text"]}')
EOF

<< 'EOF' 在 Windows cmd 不可用，建议直接用编辑器创建 demo.py。

第三步：运行

python demo.py

预期输出类似：

SPEAKER_00 [0.6s - 4.2s]  In this video, we are going to talk about...
SPEAKER_01 [4.8s - 8.5s]  First, let me show you the setup...
SPEAKER_00 [9.1s - 12.7s] As you can see, the latency is quite low...

听到的是两段不同的人声，会被识别成不同说话人。CPU 上 large-v3 跑这段 30 秒文件可能需要 2-5 分钟，GPU 只要十几秒。

配置与调优

1. 选择合适的 Whisper 模型

默认加载 large-v3 精度最高但最慢。快速实验或 CPU 环境改用 small 或 base：

model = whisperx.load_model("base", device="cpu")

中文转写建议保持 large-v3，小模型中文错字率较高。

2. 降低说话人识别耗时

Diarization 使用 pyannote，默认参数足够但较慢。如果只关心时间戳，不关心谁说的，直接注释掉第 3 步的代码即可。想提升准确度，可以传入 max_speakers 限制人数：

diarize_segments = diarize_model(audio_file, max_speakers=2)

3. 批量处理长音频

WhisperX 对超长音频会自动分段。如果想避免内存溢出，可以用 batch_size 参数控制转写时的批次大小：

model.transcribe(audio_file, batch_size=8)

GPU 显存 8GB 以下时建议减到 4。采样率不一致时，WhisperX 会自动重采样，无需手动转换。

常见坑与排错

下一步

• 接入字幕生成：把对齐后的 segments 输出成 SRT/VTT 字幕文件，不再需要二次对准时间
• 中文优化：WhisperX 对中文标点和韵律支持一般，尝试接入标点恢复模型（如 ctranslate2 + 中文 punctuation 模型）提升可读性
• 服务化部署：用 FastAPI 封装转写函数，让多用户提交音频异步转写，适合落地为内部工具或 API 服务