文章目录
关于 Whisper(OpenAI 开源语音识别工具)的详细安装与使用指南,涵盖技术细节、参数解释、优化技巧和常见问题解决方案。
1. 安装 Whisper
1.1 系统依赖
- 必须安装 FFmpeg:处理音频/视频编解码。
- Linux:
# Debian/Ubuntu sudo apt update && sudo apt install ffmpeg # CentOS/RHEL sudo yum install ffmpeg ffmpeg-devel
- macOS:
# 使用 Homebrew brew install ffmpeg
- Windows:
- 推荐通过 官方二进制包 安装,或使用 Chocolatey:
choco install ffmpeg
- 安装后需将
ffmpeg
添加到系统环境变量PATH
。
- 推荐通过 官方二进制包 安装,或使用 Chocolatey:
- Linux:
1.2 安装 Whisper
-
通过 pip 安装:
pip install -U openai-whisper
- Python 版本要求:建议 Python 3.9 或更高版本。
- 依赖项:自动安装
torch
,numpy
,tqdm
,more_itertools
等。
-
验证安装:
whisper --version # 输出 Whisper 版本
1.3 GPU 加速(可选)
-
NVIDIA GPU 用户:
- 安装 CUDA Toolkit 11.7+ 和 cuDNN。
- 安装 PyTorch 的 CUDA 版本:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117
- 验证 GPU 是否启用:
import torch print(torch.cuda.is_available()) # 输出应为 True
-
Apple Silicon (M1/M2) 用户:
- 使用
Metal Performance Shaders (MPS)
加速:pip install torch torchaudio -U --pre --extra-index-url https://download.pytorch.org/whl/nightly/cpu
- 运行命令时添加
--device mps
:whisper audio.mp3 --device mps
- 使用
2. 模型详解
2.1 模型类型
Whisper 提供 5 种预训练模型,按精度和速度排序(从低到高):
模型名称 | 参数量 | 内存占用 | 适合场景 |
---|---|---|---|
tiny |
39M | ~1 GB | 快速转录,低精度 |
base |
74M | ~1.5 GB | 平衡速度与精度 |
small |
244M | ~2.5 GB | 中等精度,多语言支持 |
medium |
769M | ~5 GB | 高精度,复杂音频 |
large |
1550M | ~10 GB | 最高精度,专业场景 |
- 多语言支持:
large
模型支持 99 种语言,其他模型支持主要语言(如中、英、日、西等)。
2.2 模型下载
- 自动下载:首次运行时会自动下载模型到
~/.cache/whisper/
。 - 手动下载(解决网络问题):
- 从 Hugging Face 仓库下载模型文件(如
medium.pt
)。 - 将文件放入
~/.cache/whisper/
(Linux/macOS)或C:\Users\<用户名>\.cache\whisper\
(Windows)。
- 从 Hugging Face 仓库下载模型文件(如
3. 命令行使用
3.1 基础命令
whisper [音频文件路径] --model [模型名] --language [语言代码]
- 示例:
# 使用中等模型转录英文音频,生成 TXT 和 SRT 文件 whisper lecture.mp3 --model medium --language en --output_format txt,srt
3.2 核心参数
参数 | 说明 |
---|---|
--model |
指定模型(默认 small ) |
--language |
指定语言(如 zh , en , ja ),若未指定会自动检测 |
--task |
transcribe (转录)或 translate (翻译为英文) |
--output_format |
输出格式:txt , srt , vtt , tsv , json (默认全部生成) |
--output_dir |
指定输出目录(默认当前目录) |
--fp16 |
使用 FP16 精度加速推理(需 GPU 支持) |
--device |
指定计算设备:cpu , cuda , mps (Apple Silicon) |
--temperature |
控制生成随机性(0-1,0 表示确定性输出) |
--best_of |
束搜索候选数(影响精度与速度) |
--beam_size |
束搜索宽度(与 best_of 配合使用) |
--word_timestamps |
为每个单词生成时间戳(适用于 json 和 srt 格式) |
3.3 高级用法
- 处理长音频(自动分割):
whisper long_audio.wav --model large --language en --split_duration 300 # 每 300 秒分割一次
- 仅生成字幕文件:
whisper audio.mp4 --task translate --output_format srt # 翻译为英文字幕
- 自定义提示词(提升准确性):
whisper audio.mp3 --initial_prompt "以下是关于量子力学的讲座。" # 提供上下文提示
4. Python API 使用
通过 Python 脚本灵活调用 Whisper:
import whisper
# 加载模型
model = whisper.load_model("medium")
# 转录音频
result = model.transcribe("audio.mp3", language="zh", fp16=False)
# 输出结果
print(result["text"]) # 完整文本
for segment in result["segments"]:
print(f"[{
segment['start']}-{
segment['end']}s] {
segment['text']}")
API 参数
transcribe()
方法支持所有命令行参数:result = model.transcribe( "audio.wav", language="en", temperature=0.2, beam_size=5, word_timestamps=True, initial_prompt="This is a podcast about climate change." )
5. 性能优化
5.1 加速技巧
- GPU 加速:确保安装 CUDA 版本的 PyTorch。
- 量化模型(降低内存占用):
model = whisper.load_model("medium", device="cuda", in_memory=True)
- 批处理(同时处理多个文件):
whisper audio1.mp3 audio2.wav --model small --output_dir ./outputs/
5.2 内存不足处理
- 使用更小的模型(如
base
或tiny
)。 - 添加
--split_duration
参数分割长音频。
6. 常见问题解决
6.1 错误:FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'
- 原因:FFmpeg 未正确安装或未添加到
PATH
。 - 解决:
- 重新安装 FFmpeg 并确认命令行中
ffmpeg -version
可执行。 - Windows 用户需手动添加 FFmpeg 到环境变量。
- 重新安装 FFmpeg 并确认命令行中
6.2 错误:ERROR: Could not find model file
- 原因:模型下载失败或路径错误。
- 解决:
- 手动下载模型并放入
~/.cache/whisper/
。 - 指定模型路径:
whisper audio.mp3 --model /path/to/custom_model.pt
- 手动下载模型并放入
6.3 识别结果不准确
- 优化方法:
- 使用更大的模型(如
medium
或large
)。 - 添加
--initial_prompt
提供上下文关键词。 - 清理音频背景噪音(使用 Audacity 等工具预处理)。
- 使用更大的模型(如
7. 扩展应用
7.1 实时语音识别
结合麦克风输入库(如 pyaudio
)实现实时转录:
import whisper
import pyaudio
import wave
# 录制音频并保存为文件
CHUNK = 1024
FORMAT = pyaudio.paInt16
CHANNELS = 1
RATE = 16000
RECORD_SECONDS = 5
p = pyaudio.PyAudio()
stream = p.open(format=FORMAT, channels=CHANNELS, rate=RATE, input=True, frames_per_buffer=CHUNK)
frames = []
print("Recording...")
for _ in range(0, int(RATE / CHUNK * RECORD_SECONDS)):
data = stream.read(CHUNK)
frames.append(data)
stream.stop_stream()
stream.close()
p.terminate()
# 保存为 WAV 文件
with wave.open("temp.wav", 'wb') as wf:
wf.setnchannels(CHANNELS)
wf.setsampwidth(p.get_sample_size(FORMAT))
wf.setframerate(RATE)
wf.writeframes(b''.join(frames))
# 使用 Whisper 转录
model = whisper.load_model("base")
result = model.transcribe("temp.wav")
print(result["text"])
7.2 集成到其他工具
- 生成字幕文件:将 SRT 文件导入视频剪辑软件(如 Premiere、DaVinci Resolve)。
- 批量处理脚本:
# 遍历目录下所有 MP3 文件 for file in *.mp3; do whisper "$file" --model small --output_dir ./transcripts/ done
8. 注意事项
- 音频格式:支持 MP3、WAV、OGG、FLAC 等格式,建议使用 16kHz 单声道音频。
- 硬件要求:
large
模型需至少 10GB 内存(GPU 推荐 16GB+ VRAM)。- 长音频处理可能需要更多内存。
- 隐私保护:离线运行,无需联网(模型下载后数据不上传)。
通过上述指南,你可以充分利用 Whisper 实现高精度语音识别。如需进一步定制(如微调模型),可参考 官方 GitHub 仓库 和开发者文档。