Whisper 语音识别库安装与配置指南

若返回 True 且版本号正常，则环境就绪。

3. 安装 Whisper 库

Pip 安装（推荐）

获取最新稳定版：

pip install -U openai-whisper

GitHub 源码安装

如需测试开发版：

pip install git+https://github.com/openai/whisper.git

更新现有版本：

pip install --upgrade --no-deps --force-reinstall git+https://github.com/openai/whisper.git

4. 配置 FFmpeg

音频处理依赖 FFmpeg，需确保其已安装并加入环境变量。

Windows

下载构建版（如 gyan.dev），解压后将 bin 目录路径添加至系统环境变量 Path。

Linux / macOS

Ubuntu/Debian：

sudo apt update && sudo apt install ffmpeg

CentOS/RHEL：

sudo yum install ffmpeg

Arch Linux：

sudo pacman -S ffmpeg

macOS (Homebrew)：

brew install ffmpeg

验证

ffmpeg -version

5. 其他依赖（按需）

部分场景可能遇到编译错误，需补充以下组件：

• Rust：若提示 tiktoken 相关错误，需安装 Rust 工具链并将 $HOME/.cargo/bin 加入 PATH。
• setuptools_rust：若报错 No module named 'setuptools_rust'，执行：

pip install setuptools-rust

验证安装结果

命令行测试

whisper --help

Python API 测试

创建 test_whisper.py：

import whisper

try:
    model = whisper.load_model("tiny")
    print("模型加载成功！")
    print("可用模型：", whisper.available_models())
    print("Whisper 安装成功！")
except Exception as e:
    print(f"安装失败：{e}")

运行脚本，若输出成功提示即表示环境无误。

常见问题排查

1. 权限不足：使用 --user 参数或管理员权限运行 pip。

   pip install -U openai-whisper --user
   

2. 模型下载失败：检查网络，尝试代理，或手动下载模型放入缓存目录 ~/.cache/whisper。
3. FFmpeg 未找到：确认 bin 目录已加入 PATH，重启终端生效。
4. CUDA 错误：核对驱动版本与 PyTorch 匹配度，必要时切换 CPU 版本。
5. 版本冲突：建议使用虚拟环境隔离依赖。

最佳实践建议

使用虚拟环境

避免全局污染，保护项目独立性：

# 创建
python -m venv whisper-env
# 激活
# Windows: whisper-env\Scripts\activate
# Linux/macOS: source whisper-env/bin/activate
# 安装
pip install -U openai-whisper

模型选型策略

• 低配设备（<4GB 内存）：选用 tiny 或 base。
• 高精度需求：选用 medium 或 large。
• 实时性优先：考虑 turbo 模型。

定期维护

开发者会持续修复 Bug 并优化性能，建议定期执行更新命令保持同步。

结语

至此，Whisper 的基础运行环境已准备完毕。接下来即可深入探索命令行调用与 Python API 的具体用法，将语音识别能力集成到您的实际项目中。