WhisperX 本地部署与使用笔记（Windows 11 + RTX 3060 12G）

一、环境准备

1.1 创建 Conda 环境

conda create -n whisper python=3.10 -y
conda activate whisper

1.2 安装 PyTorch（CUDA 12.6）

下载对应 wheel 文件后本地安装：

pip install "G:\file\conda\torch-2.8.0+cu126-cp310-cp310-win_amd64.whl"
pip install torch==2.8.0 torchaudio==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu126

1.3 验证 GPU 可用性

python -c "import torch; print('PyTorch版本:', torch.__version__); print('CUDA是否可用:', torch.cuda.is_available()); print('CUDA版本:', torch.version.cuda); print('显卡:', torch.cuda.get_device_name(0))"

预期输出：

PyTorch版本: 2.8.0+cu126
CUDA是否可用: True
CUDA版本: 12.6
显卡: NVIDIA GeForce RTX 3060

1.4 安装 WhisperX

pip install whisperx

二、本地模型目录说明

模型存放路径：G:\ProgramFiles\anaconda-file\Whisper\models

2.1 CTranslate2 模型目录结构

whisper-large-v3-turbo-ct2 目录应包含以下文件：

whisper-large-v3-turbo-ct2\
├── config.json
├── model.bin
├── preprocessor_config.json
└── vocabulary.json

确认目录内容：

cd models\whisper-large-v3-turbo-ct2
dir

三、基础转录（导出 txt）

3.1 使用 WhisperX 命令行

whisperx a1.mp4 --model "G:\ProgramFiles\anaconda-file\Whisper\models\whisper-large-v3-turbo-ct2" --language zh --output_format txt

参数说明：

• --model：指向本地 CTranslate2 模型目录的完整路径，加引号避免空格问题。
• --language zh：指定中文，识别更准。
• --output_format txt：只输出纯文本文件 a1.txt。

3.2 两段式处理（更稳妥）

若直接处理 mp4 报错，可先用 FFmpeg 提取音频：

ffmpeg -i a1.mp4 -vn -acodec libmp3lame -ar 16000 -ac 1 a1.mp3

参数说明：

• -vn：不要视频，只提取音频。
• -ar 16000：采样率设为 16kHz。
• -ac 1：转为单声道。

再用 WhisperX 转录：

whisperx a1.mp3 --model "G:\ProgramFiles\anaconda-file\Whisper\models\whisper-large-v3-turbo-ct2" --language zh --output_format txt

四、常见报错与处理

4.1 torchcodec 警告（可忽略）

UserWarning: torchcodec is not installed correctly so built-in audio decoding will fail.

该警告不影响转录，WhisperX 会退回使用其他音频解码方式。

4.2 HuggingFace 连接超时

报错特征：

MaxRetryError("HTTPSConnectionPool(host='huggingface.co', port=443): Max retries exceeded...")

原因：WhisperX 的对齐步骤默认需要联网下载 wav2vec2 对齐模型，国内网络无法直连 HuggingFace。

解决方法一：设置国内镜像

set HF_ENDPOINT=https://hf-mirror.com

注意：必须在同一个 cmd 窗口内设置后再运行 whisperx 命令，新窗口会失效。

解决方法二：指定本地对齐模型

whisperx a1.mp4 --model "G:\ProgramFiles\anaconda-file\Whisper\models\whisper-large-v3-turbo-ct2" --language zh --output_format txt --align_model "models\wav2vec2-large-xlsr-53-chinese-zh-cn"

解决方法三：跳过对齐，直接用 faster-whisper 拿纯文本

pip install faster-whisper

from faster_whisper import WhisperModel
model = WhisperModel(r"G:\ProgramFiles\anaconda-file\Whisper\models\whisper-large-v3-turbo-ct2", device="cuda", compute_type="float16")
segments, info = model.transcribe("a1.mp4", language="zh")
with open("a1.txt", "w", encoding="utf-8") as f:
    for seg in segments:
        f.write(seg.text + "\n")

faster-whisper 与 WhisperX 共用同一个 ct2 模型目录，不需要对齐模型、不联网、速度更快。

4.3 对齐阶段 WARNING

Failed to align segment (""): no characters in this segment found in model dictionary, resorting to original

原因：中文对齐模型字典中只有中文字符，转录结果里的英文单词、数字、标点符号不在字典内，导致个别片段对齐失败，WhisperX 自动保留原始时间戳。

影响：不影响 txt 文本内容，仅该段时间戳精度略低（做字幕时可能有轻微偏移）。

4.4 其他警告

• Lightning automatically upgraded your loaded checkpoint from v1.5.4 to v2.6.6：仅提示，可忽略。
• ReproducibilityWarning: TensorFloat-32 (TF32) has been disabled：pyannote 的复现性警告，不影响结果。
• gradient_checkpointing 弃用警告：transformers 版本提示，可忽略。

五、说话人分离（Diarization）

5.1 获取 HuggingFace Token

1. 注册/登录 HuggingFace 账号。
2. 生成一个 Read 权限的 access token。

5.2 接受模型使用协议（关键步骤）

pyannote/speaker-diarization-3.1 是受限模型，必须先在网页手动同意协议，token 才能生效：

1. 访问 https://huggingface.co/pyannote/speaker-diarization-3.1
2. 点击页面上的 Agree and access repository 按钮
3. 对 https://huggingface.co/pyannote/segmentation-3.0 执行相同操作

5.3 运行带说话人分离的命令

whisperx a1.mp4 --model "G:\ProgramFiles\anaconda-file\Whisper\models\whisper-large-v3-turbo-ct2" --language zh --diarize --hf_token YOUR_HF_TOKEN --min_speakers 1 --max_speakers 5 --output_format txt

参数说明：

• --diarize：启用说话人分离。
• --hf_token：填入 HuggingFace token。
• --min_speakers / --max_speakers：根据视频中说话人数设置范围，帮助模型更准确聚类。

5.4 注意事项

• 如果视频中只有一个人说话，分离结果可能全部标记为 SPEAKER_00，属正常现象。
• 若网络受限，可先 set HF_ENDPOINT=https://hf-mirror.com 再运行。

六、实测结果记录

6.1 成功运行命令

set HF_ENDPOINT=https://hf-mirror.com
whisperx a1.mp4 --model "G:\ProgramFiles\anaconda-file\Whisper\models\whisper-large-v3-turbo-ct2" --language zh --output_format txt --align_model "models\wav2vec2-large-xlsr-53-chinese-zh-cn"

6.2 运行状态

6.3 输出文本示例

比贵人思维,最近外网爆火了一段视频,白手起家的亿万富翁Grant教自己的女儿怎么赚钱看完之后最大的感触就是真正的富人教育和我们从小到大的传统认知几乎是完全相反的
我提点出视频里面最值钱的四个富人思维不管是你自己想逆袭还是想帮孩子从小就摆脱贫穷局限一定要认真地听懂石头
只听食物链上方的人的建议什么叫食物链上方就是那些已经拿到结果的人如果你想创业不要去问从来没有创业过的人他们给不出答案原因非常简单因为他没干过没经历过
Grant的女儿想拍摄一部电影短片急需钱其实Grant完全可以直接出钱但是他却拒绝了他让女儿自己去找钱后来女儿没办法只能自己去找投资人拜访陌生人主动介绍自己的短片项目两天筹到了三千美元
...

6.4 识别误差记录

large-v3-turbo 模型在中文上有少量识别误差，例如：

• 比贵人思维 应为 富人思维
• 我提点出 应为 我提炼出
• 听不懂石头 应为 听不懂时
• 筛选批选批评 应为 筛选批评

如需更高精度，可换用 large-v3（非 turbo）模型，速度较慢但中文识别更准。

七、方案对比总结

八、关键路径速查