manus-skills/.kortix/opencode/skills/media/video-to-subtitle-summary/docs/faster-whisper-setup.md

faster-whisper 安装指南

本 skill 在 ASR_BACKEND=faster-whisper 时，使用 faster-whisper 作为本地语音识别后端，将音频转为字幕文本。

官方参考：

• faster-whisper README
• CTranslate2 Hardware Support

步骤 1：确认后端选择

在 .env 或 shell 环境中设置：

ASR_BACKEND=faster-whisper

未配置时也会默认使用这个后端。

步骤 2：确认 Python 版本

faster-whisper 需要 Python 3.9+。

python3 --version

如果版本低于 3.9，请先升级 Python。

步骤 3：安装 faster-whisper

推荐使用安装 helper。它会先测速常见 PyPI 镜像，选择最快可用源，然后创建独立 venv 安装，避免污染系统 Python：

python3 ~/.codex/skills/video-to-subtitle-summary/scripts/install_faster_whisper.py

默认 venv 路径：

~/.cache/video-to-subtitle-summary/faster-whisper-venv

如需指定 venv 路径：

python3 ~/.codex/skills/video-to-subtitle-summary/scripts/install_faster_whisper.py \
  --venv-dir /tmp/video_analysis/faster_whisper_venv

使用自定义 venv 时，在 .env 或 shell 环境中指定：

FW_PYTHON=/tmp/video_analysis/faster_whisper_venv/bin/python

这会同时安装 ctranslate2 等依赖。如果你明确要装进当前 Python 环境，也可以手动执行 python3 -m pip install -U faster-whisper。

步骤 4：按需安装 FFmpeg 和 yt-dlp

FFmpeg（视频提音频需要）：

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Windows
choco install ffmpeg

yt-dlp（B 站视频下载或 YouTube 字幕抓取需要）：

# macOS
brew install yt-dlp

# 通用
python3 -m pip install -U yt-dlp

步骤 5：可选配置运行时参数

将以下变量写入 .env 或 shell 配置：

FW_MODEL_SIZE=small
FW_DEVICE=auto
FW_COMPUTE_TYPE=

说明：

• FW_MODEL_SIZE：默认 small
• FW_DEVICE：auto、cpu、cuda
• FW_COMPUTE_TYPE：留空时自动选择；例如 CPU 常见为 int8，CUDA 常见为 float16

步骤 6：验证安装

~/.cache/video-to-subtitle-summary/faster-whisper-venv/bin/python - <<'PY'
import ctranslate2
import faster_whisper

print("faster_whisper:", faster_whisper.__file__)
print("cuda_devices:", ctranslate2.get_cuda_device_count())
print("cpu_compute_types:", ctranslate2.get_supported_compute_types("cpu"))
PY

如果输出了模块路径和 cuda_devices 数值，说明安装成功。

GPU 说明

CPU 默认行为

• FW_DEVICE=auto 时，如果没有可用的 NVIDIA/CUDA 设备，会自动使用 cpu
• Apple Silicon（M1/M2/M3）即使有 Metal GPU，也会按 CPU 路径运行

NVIDIA GPU

如果你在 Linux/Windows 服务器或工作站上使用 NVIDIA GPU：

1. 安装兼容版本的 NVIDIA 驱动
2. 按官方要求准备 CUDA 12 与 cuDNN 9 运行时
3. 保持 FW_DEVICE=auto，helper 会在检测到 CUDA 时自动切到 device="cuda"

如果 CUDA 运行时不完整，helper 会报错或回退到 CPU。优先确保 ctranslate2.get_cuda_device_count() 能返回正确的设备数量。

常见问题

Q: ModuleNotFoundError: No module named 'faster_whisper'？
A: 执行 python3 ~/.codex/skills/video-to-subtitle-summary/scripts/install_faster_whisper.py。如果你用的是自定义 venv，运行转写时也要使用该 venv 的 Python。

Q: Apple Silicon 为什么没有走 GPU？
A: 当前方案只把 NVIDIA/CUDA 视为可用 GPU 路径。Apple GPU 会回退到 CPU。

Q: 首次运行很慢？
A: 首次会下载模型文件，后续会复用本地缓存。

Q: 该选什么模型？
A: 默认 small，通常是速度和质量的平衡点。资源更紧张可降到 base，更看重准确率可升到 medium 或 large-v3。