---

最近在尝试使用 OpenAI 的 Whisper 语音识别库时，遇到了经典的 ModuleNotFoundError: No module named 'whisper' 错误。经过一番折腾，终于搞定了从本地开发到生产环境部署的全流程，在这里把经验总结分享给大家。

一、为什么会出现这个错误？

当 Python 提示找不到 whisper 模块时，通常意味着以下几种情况：

• Python 环境未正确安装 whisper 包
• 使用了错误的 Python 环境（比如系统 Python 而不是虚拟环境）
• 依赖项未完全安装（特别是 FFmpeg）
• 平台兼容性问题（如 ARM 架构的 Mac）

二、基础解决方案：正确安装 Whisper

最简单直接的解决方法是使用 pip 安装。但需要注意 Whisper 是托管在 PyPI 上的，但部分依赖可能需要额外索引：

pip install openai-whisper

如果遇到网络问题，可以尝试：

pip install openai-whisper --extra-index-url https://pypi.org/simple/

三、进阶方案：环境隔离管理

为了避免污染系统 Python 环境，强烈建议使用虚拟环境：

使用 venv（Python 内置）

1. 创建虚拟环境

   python -m venv whisper_env

2. 激活环境
3. Windows: whisper_env\Scripts\activate
4. Mac/Linux: source whisper_env/bin/activate
5. 安装 whisper

   pip install openai-whisper

使用 conda（适合科学计算场景）

conda create -n whisper python=3.9
conda activate whisper
pip install openai-whisper

四、生产级部署：Docker 方案

对于生产环境，推荐使用 Docker 来确保环境一致性：

FROM python:3.9-slim

# 安装系统依赖
RUN apt-get update && apt-get install -y ffmpeg

# 安装 Python 依赖
RUN pip install openai-whisper

# 设置工作目录
WORKDIR /app
COPY . /app

CMD ["python", "your_script.py"]

构建并运行：

docker build -t whisper-app .
docker run -it whisper-app

五、代码示例与验证

带错误处理的初始化代码

try:
    import whisper
    print("Whisper 导入成功！")
except ImportError:
    print("Whisper 未安装，正在尝试自动安装...")
    import subprocess
    import sys

    subprocess.check_call([sys.executable, "-m", "pip", "install", "openai-whisper"])
    import whisper
    print("Whisper 安装并导入成功！")

# 验证 CUDA 是否可用
print(f"CUDA 可用: {whisper.available()}")

CUDA 可用性检查

import torch
print(f"CUDA 可用: {torch.cuda.is_available()}")
print(f"CUDA 设备数量: {torch.cuda.device_count()}")
if torch.cuda.is_available():
    print(f"当前设备: {torch.cuda.get_device_name(0)}")

六、常见问题与避坑指南

FFmpeg 依赖问题

Whisper 依赖 FFmpeg 处理音频文件。如果遇到相关错误：

• Windows: 下载 FFmpeg 并添加到 PATH
• Mac: brew install ffmpeg
• Linux: sudo apt-get install ffmpeg

模型内存需求

不同 Whisper 模型对内存的需求差异很大：

| 模型大小 | 内存需求 | 显存需求 | 精度 | |----------|----------|----------|------| | tiny | ~1GB | ~1GB | 32GB | | base | ~1GB | ~1GB | 32GB | | small | ~2GB | ~2GB | 32GB | | medium | ~5GB | ~5GB | 32GB | | large | ~10GB | ~10GB | 32GB |

Mac M1/M2 特殊配置

对于 Apple Silicon 芯片，建议：

# 安装兼容的 PyTorch 版本
pip install torch torchaudio -f https://download.pytorch.org/whl/nightly/cpu/torch_nightly.html

# 然后安装 whisper
pip install openai-whisper

七、性能优化技巧

模型加载加速

# 预加载模型到 GPU（如果有的话）
model = whisper.load_model("medium").cuda()

批处理音频文件

import glob

# 获取所有音频文件
audio_files = glob.glob("audio/*.mp3")

# 批量处理
results = []
for audio_file in audio_files:
    result = model.transcribe(audio_file)
    results.append(result)

八、动手实验

现在你可以在 Google Colab 上快速尝试 Whisper：

1. 打开 Google Colab
2. 新建一个笔记本
3. 运行以下代码：

!pip install openai-whisper
import whisper

model = whisper.load_model("base")
result = model.transcribe("your_audio_file.mp3")
print(result["text"])

希望这篇指南能帮助你顺利使用 Whisper 进行语音识别开发！如果遇到其他问题，欢迎在评论区讨论。