最完整whisperX入门指南：从安装到实现第一个语音识别功能

你还在为语音识别工具安装复杂、识别准确率低、时间戳不精准而烦恼吗？本文将带你从零开始，一步步掌握whisperX的安装配置，并实现你的第一个语音识别功能。读完本文，你将能够：搭建稳定的whisperX运行环境、使用命令行和Python API两种方式进行语音识别、获取精准的单词级时间戳、实现多 speaker 区分标注。

whisperX 简介

whisperX 是一个基于 OpenAI Whisper 的语音识别工具，它在 Whisper 的基础上进行了改进，提供了更精准的单词级时间戳和 speaker 区分功能。whisperX 采用了强制音素对齐（Phoneme-Based ASR）和语音活动检测（VAD）等技术，能够显著提高语音识别的准确性和效率。

whisperX 的主要特点包括：

• ⚡️ 批处理推理，使用 whisper large-v2 模型可实现 70 倍实时转录
• 🎯 使用 wav2vec2 对齐实现精准的单词级时间戳
• 👯‍♂️ 支持多 speaker 语音识别，使用 pyannote-audio 进行 speaker 区分
• 🗣️ VAD 预处理，减少幻觉，在不降低 WER 的情况下实现批处理

详细的技术细节可以参考官方文档 README.md。

环境搭建

1. 创建 Python 环境

首先，我们需要创建一个 Python 3.10 的环境。打开终端，执行以下命令：

conda create --name whisperx python=3.10
conda activate whisperx

2. 安装 PyTorch

whisperX 需要 PyTorch 的支持。对于 Linux 和 Windows 用户，推荐安装 CUDA 11.8 版本的 PyTorch：

conda install pytorch==2.0.0 torchaudio==2.0.0 pytorch-cuda=11.8 -c pytorch -c nvidia

其他系统或 CUDA 版本的安装方法可以参考 PyTorch 官方文档。

3. 安装 whisperX

whisperX 提供了多种安装方式，你可以根据自己的需求选择：

选项 A：稳定版本（推荐）

从 PyPI 安装最新的稳定版本：

pip install whisperx

选项 B：开发版本

从 GitHub 安装最新的开发版本（可能不稳定）：

pip install git+https://gitcode.com/gh_mirrors/wh/whisperX.git

如果已经安装了 whisperX，可以使用以下命令升级到最新版本：

pip install git+https://gitcode.com/gh_mirrors/wh/whisperX.git --upgrade

选项 C：开发模式

如果你需要修改源码，可以克隆仓库并以可编辑模式安装：

git clone https://gitcode.com/gh_mirrors/wh/whisperX.git
cd whisperX
pip install -e .

注意：开发版本可能包含实验性功能和 bug，生产环境建议使用稳定版本。

此外，你可能还需要安装 ffmpeg、rust 等依赖，可以参考 OpenAI Whisper 的 安装指南。

4. 配置 Speaker Diarization（可选）

如果需要使用 speaker 区分功能，你需要获取 Hugging Face 的访问令牌，并接受相关模型的用户协议。具体步骤如下：

1. 在 Hugging Face 设置页面 生成访问令牌
2. 接受 Segmentation 和 Speaker-Diarization-3.1 模型的用户协议

命令行使用

基本使用

安装完成后，我们可以使用命令行来调用 whisperX。最简单的用法是：

whisperx examples/sample01.wav

这个命令会使用默认的模型（small）对 examples/sample01.wav 文件进行转录。如果你想获取单词级的时间戳，可以添加 --highlight_words True 参数：

whisperx examples/sample01.wav --highlight_words True

提高识别准确率

为了提高识别准确率和时间戳精度，你可以使用更大的模型，例如：

whisperx examples/sample01.wav --model large-v2 --align_model WAV2VEC2_ASR_LARGE_LV60K_960H --batch_size 4

这里，--model large-v2 指定使用 large-v2 模型，--align_model 指定使用 WAV2VEC2_ASR_LARGE_LV60K_960H 模型进行对齐。

Speaker 区分

要实现 speaker 区分，可以使用 --diarize 参数。如果你知道 speaker 的数量，可以使用 --min_speakers 和 --max_speakers 参数来指定：

whisperx examples/sample01.wav --model large-v2 --diarize --highlight_words True --min_speakers 2 --max_speakers 2

CPU 运行

如果你没有 GPU，或者想在 Mac OS X 上运行 whisperX，可以使用 --compute_type int8 参数：

whisperx examples/sample01.wav --compute_type int8

多语言支持

whisperX 支持多种语言的识别。对于非英语语言，建议使用 large 模型，并通过 --language 参数指定语言代码。例如，识别德语音频：

whisperx examples/sample_de_01.wav --model large --language de

目前，whisperX 已为以下语言提供了默认的对齐模型：{en, fr, de, es, it, ja, zh, nl, uk, pt}。更多语言的例子可以参考 EXAMPLES.md。

Python API 使用

除了命令行，whisperX 还提供了 Python API，方便集成到你的项目中。下面是一个简单的示例：

import whisperx
import gc 

device = "cuda" 
audio_file = "audio.mp3"
batch_size = 16  # 减少批大小以降低 GPU 内存占用
compute_type = "float16"  # 如果 GPU 内存不足，可以改为 "int8"

# 1. 使用原始 whisper 进行转录（批处理）
model = whisperx.load_model("large-v2", device, compute_type=compute_type)

audio = whisperx.load_audio(audio_file)
result = model.transcribe(audio, batch_size=batch_size)
print(result["segments"])  # 对齐前的结果

# 2. 对齐 whisper 输出
model_a, metadata = whisperx.load_align_model(language_code=result["language"], device=device)
result = whisperx.align(result["segments"], model_a, metadata, audio, device, return_char_alignments=False)

print(result["segments"])  # 对齐后的结果

# 3. 分配 speaker 标签
diarize_model = whisperx.DiarizationPipeline(use_auth_token=YOUR_HF_TOKEN, device=device)

diarize_segments = diarize_model(audio)
result = whisperx.assign_word_speakers(diarize_segments, result)
print(result["segments"])  # 带有 speaker ID 的结果

上述代码演示了如何使用 whisperX 进行语音识别、时间戳对齐和 speaker 区分。详细的 API 文档可以参考 whisperx/transcribe.py 和 whisperx/diarize.py。

常见问题解决

GPU 内存不足

如果遇到 GPU 内存不足的问题，可以尝试以下方法：

1. 减少批大小，例如 --batch_size 4
2. 使用更小的模型，例如 --model base
3. 使用更轻量的计算类型，例如 --compute_type int8

Speaker 区分效果不佳

如果 speaker 区分效果不理想，可以尝试：

1. 明确指定 speaker 的数量，使用 --min_speakers 和 --max_speakers 参数
2. 确保音频质量良好，背景噪音较小
3. 使用更大的模型，如 large-v2

时间戳不准确

如果时间戳不够准确，可以尝试使用更大的对齐模型，例如 --align_model WAV2VEC2_ASR_LARGE_LV60K_960H。

总结

通过本文的介绍，你已经了解了 whisperX 的基本概念、安装配置方法以及如何使用命令行和 Python API 进行语音识别。whisperX 作为一个功能强大的语音识别工具，不仅提供了高准确率的转录结果，还支持单词级时间戳和多 speaker 区分，非常适合用于语音转写、字幕生成等场景。

如果你在使用过程中遇到问题，可以参考官方文档 README.md 或提交 issue 到 GitHub 仓库。同时，whisperX 是一个开源项目，欢迎你参与贡献，一起完善这个工具。

希望本文对你有所帮助，祝你在语音识别的道路上越走越远！