docker-whisperX

这是社区为 https://github.com/m-bain/whisperX 构建的 Docker 镜像。

本项目旨在每周在 GitHub Free 运行器 上高效管理持续集成 Docker 构建工作流。该工作流包括并行构建 175 个 Docker 镜像，每个镜像大小为 10GB。为确保平稳运行，我专注于高效利用 Docker 层缓存、最大化层复用、精心管理缓存读写顺序以避免问题，并优化以最小化镜像大小和构建时间。

此外，出于个人偏好，我致力于尽最大努力遵循最佳实践、行业标准和政策。

可在 https://github.com/jim60105/docker-whisperX 获取 Dockerfile，或从 ghcr.io 拉取镜像。

🚀 准备支持 GPU 的 Docker 环境

Windows

安装 Docker Desktop、CUDA Toolkit、NVIDIA Windows Driver 并确保 Docker 以 WSL2 模式运行后，即可就绪。

有关更多参考，请查阅官方文档。

Linux、OSX

如果尚未安装 NVIDIA GPU 驱动，请先安装。

按照此指南安装 NVIDIA Container Toolkit。

[!TIP] 我有一篇关于此主题的中文博客： Fedora/RHEL 的 Podman GPU 配置笔记

📦 可用的预构建镜像

[!NOTE] 这些镜像中的 WhisperX 代码库与 git 子模块的提交哈希保持一致。 我设置了 https://github.com/jim60105/docker-whisperX/actions/workflows/submodule_update.yml%EF%BC%8C%E6%AF%8F%E5%91%A8%E8%BF%90%E8%A1%8C%E4%BB%A5%E9%92%88%E5%AF%B9 https://github.com/m-bain/whisperX/tree/main 重建所有 Docker 镜像。

docker run --gpus all -it -v ".:/app" ghcr.io/jim60105/whisperx:base-en -- --output_format srt audio.mp3
docker run --gpus all -it -v ".:/app" ghcr.io/jim60105/whisperx:large-v3-ja -- --output_format srt audio.mp3
docker run --gpus all -it -v ".:/app" ghcr.io/jim60105/whisperx:no_model -- --model tiny --language en --output_format srt audio.mp3

镜像标签格式为 WHISPER_MODEL-LANG，例如 tiny-en、base-de 或 large-v3-zh。 请注意，Whisper 模型 *.en、large-v1、large-v2 已被排除，因为我认为它们不常使用。如果需要这些模型，请参考以下部分自行构建。

可在 04-build-matrix-images.yml 中查看实际构建矩阵，并在 https://github.com/jim60105/docker-whisperX/pkgs/container/whisperx/versions?filters%5Bversion_type%5D=tagged 查看所有可用标签。

此外，还有一个 no_model 标签（也称为 latest），不包含任何预下载模型。

distil-large-v3-en 模型

large-v3 的蒸馏变体，由 HuggingFace 发布为 distil-whisper/distil-large-v3。该模型拥有 7.56 亿参数，约为 OpenAI large-v3（15.5 亿参数）的一半大小（约小 51%），相对延迟快 6.3 倍，同时在长音频的顺序和分块转录算法下，WER 仍与 large-v3 相差不超过 1%——是纯英文批量工作负载的理想选择。

由于蒸馏 Whisper 模型设计为仅支持英文，因此仅发布英文（en）语言版本。可通过 ghcr.io/jim60105/whisperx:distil-large-v3-en 拉取。

breeze-asr-26-zh 模型

联发科研究院发布的*闽南语（台语）ASR 模型，原模型为 MediaTek-Research/Breeze-ASR-26，经 paulpengtw/faster-whisper-Breeze-ASR-26 重新打包以支持 faster-whisper 运行时。该模型基于 Whisper 在约 10,000 小时合成台语语音（包括台语/普通话代码切换）上微调，将台语语音转录为汉字**，利用两种语言之间的大量词汇重叠实现实用、可复现的基准测试工作流。

由于输出脚本为中文，此镜像以 zh 语言版本发布。可通过 ghcr.io/jim60105/whisperx:breeze-asr-26-zh 拉取。

[!NOTE] 转录真实台语音频时，音素级对齐将无法工作——捆绑的 zh wav2vec2 对齐模型基于普通话语音学训练，无法可靠地将台语发音与模型的汉字输出对齐。对于台语输入，请传递 --no_align 跳过对齐步骤，例如 docker run ... ghcr.io/jim60105/whisperx:breeze-asr-26-zh -- --no_align audio.mp3。

⚡️ 为多语言场景保留对齐模型的下载缓存

可挂载 /.cache 目录在容器间共享对齐模型。 此场景请使用 no_model 标签（latest）。

docker run --gpus all -it -v ".:/app" -v whisper_cache:/.cache ghcr.io/jim60105/whisperx:latest -- --model large-v3 --language en --output_format srt audio.mp3

🛠️ 构建 Docker 镜像

[!IMPORTANT] 递归克隆 Git 仓库以包含子模块： git clone --recursive https://github.com/jim60105/docker-whisperX.git

构建参数

Dockerfile 构建包含模型的镜像。它接受两个构建参数：LANG 和 WHISPER_MODEL。

• LANG：要转录的语言。默认为 en。请参见 https://github.com/jim60105/docker-whisperX/blob/master/load_align_model.py%E3%80%82
• WHISPER_MODEL：模型名称。默认为 base。请参见 fast-whisper 了解支持的模型。

如需支持多种语言对齐，构建镜像时使用空格分隔的语言列表，例如 "LANG=pl fr en"。另请注意，WhisperX 在处理同一音频文件中的多种语言时表现不佳。即使不提供语言参数，它仍会识别语言（或回退到英文）并用于选择对齐模型。对齐模型是语言特定的。此说明仅用于将多个对齐模型嵌入 Docker 镜像。

构建命令

例如，如需构建包含 en 语言和 large-v3 模型的镜像：

docker build --build-arg LANG=en --build-arg WHISPER_MODEL=large-v3 -t whisperx:large-v3-en .

如需构建不包含任何预下载模型的镜像：

docker build --target no_model -t whisperx:no_model .

如需一次性构建所有镜像，我们提供 Docker bake 文件：

docker buildx bake build no_model

使用命令

将当前目录挂载为 /app 并使用附加输入参数运行 WhisperX：

docker run --gpus all -it -v ".:/app" whisperx:large-v3-ja -- --output_format srt audio.mp3

[!NOTE] 记得在参数前添加 --。 --model 和 --language 参数在 Dockerfile 中已定义，无需指定。

📝 许可证

主程序 WhisperX 采用 https://github.com/m-bain/whisperX/blob/main/LICENSE 分发。 有关源代码和许可证的详细信息，请查阅其仓库。

本仓库中的 Dockerfile 和 CI 工作流文件采用 MIT 许可证 授权。

🌟 Star History