最完整whisperX入门指南：从安装到实现第一个语音识别功能
最完整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 的访问令牌，并接受相关模型的用户协议。具体步骤如下：
- 在 Hugging Face 设置页面 生成访问令牌
- 接受 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 内存不足的问题，可以尝试以下方法：
- 减少批大小，例如
--batch_size 4 - 使用更小的模型，例如
--model base - 使用更轻量的计算类型，例如
--compute_type int8
Speaker 区分效果不佳
如果 speaker 区分效果不理想，可以尝试：
- 明确指定 speaker 的数量，使用
--min_speakers和--max_speakers参数 - 确保音频质量良好，背景噪音较小
- 使用更大的模型，如
large-v2
时间戳不准确
如果时间戳不够准确，可以尝试使用更大的对齐模型，例如 --align_model WAV2VEC2_ASR_LARGE_LV60K_960H。
总结
通过本文的介绍，你已经了解了 whisperX 的基本概念、安装配置方法以及如何使用命令行和 Python API 进行语音识别。whisperX 作为一个功能强大的语音识别工具，不仅提供了高准确率的转录结果，还支持单词级时间戳和多 speaker 区分，非常适合用于语音转写、字幕生成等场景。
如果你在使用过程中遇到问题，可以参考官方文档 README.md 或提交 issue 到 GitHub 仓库。同时，whisperX 是一个开源项目，欢迎你参与贡献，一起完善这个工具。
希望本文对你有所帮助，祝你在语音识别的道路上越走越远！
