Whisper 安装与配置指南：环境搭建与验证

进入 Python 交互模式测试：

import torch
print(torch.__version__)
print(torch.cuda.is_available())

若输出版本号且 cuda.is_available() 返回 True（GPU 版），则安装成功。

3. 安装 Whisper

推荐使用 pip 安装最新稳定版，也可从源码获取开发版。

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：

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg
# CentOS/RHEL
sudo yum install ffmpeg
# Arch Linux
sudo pacman -S ffmpeg

• macOS：

brew install ffmpeg

验证

ffmpeg -version

输出版本信息即表示可用。

5. 其他依赖（可选）

部分场景可能需要额外组件：

• Rust：若遇到 tiktoken 相关错误，需安装 Rust 环境并重新安装 Whisper。
• setuptools_rust：报错 No module named 'setuptools_rust' 时执行：

pip install setuptools-rust

验证安装

命令行测试

whisper --help

显示帮助信息即代表 CLI 工具正常。

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}")

运行脚本，看到成功提示即完成验证。

常见问题解决方案

权限问题

使用管理员权限运行终端，或在 pip 命令中添加 --user 参数：

pip install -U openai-whisper --user

模型下载失败

• 检查网络连接
• 尝试使用代理
• 手动下载模型文件放入缓存目录 ~/.cache/whisper

FFmpeg 未找到

• 确认 bin 目录已加入 PATH
• 重启终端或计算机

CUDA 错误

• 核对驱动与 PyTorch 版本是否匹配
• 确认 GPU 支持 CUDA
• 临时切换至 CPU 版本测试

Python 版本不兼容

• 锁定 3.8 - 3.11 版本
• 使用虚拟环境隔离依赖

最佳实践

使用虚拟环境

避免全局污染，推荐独立环境管理：

# 创建
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 并优化模型，建议保持更新：

pip install -U openai-whisper

总结

本文涵盖了从 Python 环境搭建到 Whisper 核心库配置的完整流程，包括 PyTorch 部署、FFmpeg 集成及依赖项处理。通过命令行与 API 双重验证确保环境可用性，并针对权限、网络、CUDA 等常见坑点提供了排查方案。建议采用虚拟环境隔离依赖，根据硬件资源灵活选择模型规模。

后续我们将深入讲解 Whisper 的实际调用方法，包括命令行工具的高级用法与 Python API 的定制化开发。