在Ubuntu上搭建Whisper语音识别，核心链路可以拆成三部分：安装FFmpeg处理音频解码、准备Python环境并安装PyTorch与Whisper、通过命令行或Python脚本完成转写。本文以Ubuntu 22.04为基准，Ubuntu 24.04的操作基本一致。完成后既能批量转写音频文件，也能接入实时麦克风做持续识别。
一、准备系统依赖与Python虚拟环境
Whisper本身不负责音频解码，它依赖FFmpeg来读取mp3、wav、m4a等常见格式。很多安装失败的情况都是因为系统里没有FFmpeg，或者FFmpeg版本过旧。Ubuntu软件源里自带FFmpeg，直接使用apt安装即可。为了避免破坏系统Python环境，建议单独创建一个虚拟环境，后续所有依赖都装在这个环境里。
先更新软件包列表并安装FFmpeg，然后创建虚拟环境。下面的命令会把虚拟环境目录命名为whisper-venv，并激活它。激活成功后终端提示符前会出现括号和目录名，表示后续pip安装只影响这个环境。
sudo apt update sudo apt install -y ffmpeg python3 -m venv whisper-venv source whisper-venv/bin/activate pip install --upgrade pip
如果机器上同时存在多个Python版本，建议确认python3指向的是3.9或更高版本。可以用python3 --version查看。Ubuntu 22.04默认Python版本为3.10，Ubuntu 24.04默认为3.12，均满足Whisper的运行要求。如果不小心在系统环境下直接执行pip install，可能会与系统包管理器产生冲突，这也是推荐虚拟环境的原因。
二、安装PyTorch与OpenAI Whisper
Whisper基于PyTorch构建，因此需要先安装PyTorch。如果没有NVIDIA显卡，或者暂时不想处理CUDA驱动问题，可以直接安装CPU版本。CPU版本安装简单，适合小模型和短音频，但处理长音频时速度会明显偏慢。对于有NVIDIA显卡的机器，需要先确认驱动和CUDA工具链是否正常，再选择对应的PyTorch安装命令。
安装CPU版PyTorch和Whisper的命令如下。openai-whisper是官方Python包名，不要只写whisper。
pip install torch torchaudio pip install -U openai-whisper
对于需要CUDA加速的机器，可以先执行nvidia-smi查看驱动版本，再根据PyTorch官方给出的索引地址安装CUDA版。下面以CUDA 12.1为例，实际版本需要与驱动匹配。安装完成后可以用一行Python命令检查CUDA是否可用。
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121 python -c "import torch; print(torch.cuda.is_available())"
如果输出True，表示后续Whisper可以调用GPU。需要注意，不同CUDA版本对应的索引地址不同，装错版本会导致torch仍然回退到CPU。如果已经装过CPU版PyTorch，建议先pip uninstall torch torchaudio再重新安装CUDA版。模型尺寸方面，Whisper提供了tiny、base、small、medium、large等多种选择，tiny和base适合快速验证，small和medium在中文识别上表现更稳定，large需要约10GB显存。
三、使用命令行进行音频转写
安装完成后，系统会提供一个whisper命令。最简单的用法是直接指定音频文件路径，Whisper会自动检测语言并输出识别结果。如果音频是普通话或带方言的对话，建议显式加上language参数为zh，避免语言检测错误影响准确率。输出格式可以通过output_format参数指定为txt、srt、json等，方便后续处理。
下面这条命令使用base模型转写一个mp3文件，输出为txt格式。首次运行会自动下载对应模型文件，默认存放在用户目录的.cache/whisper下。下载速度取决于网络环境，如果下载失败，可以提前从OpenAI的模型仓库获取模型文件并放到缓存目录。
whisper /home/user/audio/interview.mp3 --model base --language zh --output_format txt
对于批量处理，可以使用shell循环遍历目录下所有音频文件。为了避免变量名和路径中的空格导致错误，命令中给变量加了双引号。下面示例处理/home/user/audio目录下所有wav文件，结果输出到/home/user/transcripts目录。
for f in /home/user/audio/*.wav; do whisper "$f" --model small --language zh --output_dir /home/user/transcripts done
命令行方式适合一次性任务或任务队列较少的情况。对于需要反复调用或集成到业务系统的场景，建议使用Python API，这样可以在内存中复用模型，减少重复加载开销。
四、Python API调用与中文识别优化
通过Python调用Whisper只需要导入whisper模块，加载模型后调用transcribe方法即可。与命令行相比，Python API允许更细粒度的参数控制。例如设置language为zh后，模型在中文上的稳定性会提高；设置initial_prompt可以给Whisper提供上下文，减少专有名词误识别。initial_prompt只是提示文本，不会作为最终输出的一部分。
下面这段代码加载base模型，对音频文件进行中文转写，并打印识别文本。路径需要替换成实际存在的音频文件路径。
import whisper
model = whisper.load_model("base")
result = model.transcribe(
"/home/user/audio/interview.wav",
language="zh",
initial_prompt="以下是普通话的技术访谈内容。"
)
print(result["text"])
如果要做实时麦克风识别，可以借助sounddevice库持续采集音频块，再交给Whisper处理。下面的代码框架展示了基本思路：使用16kHz单声道输入，每5秒回调一次，在回调里调用transcribe并打印结果。实际使用时需要控制块大小，避免回调耗时过长导致音频流溢出。fp16设为False是为了兼容没有GPU或CPU推理的场景。
import whisper
import sounddevice as sd
import numpy as np
model = whisper.load_model("base")
sample_rate = 16000
block_duration = 5
def callback(indata, frames, time_info, status):
audio = indata[:, 0]
result = model.transcribe(audio, language="zh", fp16=False)
print(result["text"])
with sd.InputStream(samplerate=sample_rate, channels=1, callback=callback,
blocksize=int(sample_rate * block_duration)):
print("开始录音，按 Ctrl+C 退出")
sd.sleep(60000)
执行这段代码前需要先安装sounddevice和numpy。实时识别对模型尺寸和硬件要求较高，base模型在CPU上可能出现超过音频块时长的处理延迟，实际项目建议先用small或medium模型配合GPU测试。
五、常见问题排查与性能调优
Ubuntu上部署Whisper最常见的问题是FFmpeg缺失。如果运行时报错FileNotFoundError或提示找不到ffmpeg，先执行ffmpeg -version确认是否已安装。另一个高频问题是PyTorch装成了CPU版却以为在使用GPU，此时nvidia-smi可能显示有进程，但推理速度没有提升，应当用torch.cuda.is_available()确认。如果返回False，需要重新安装与CUDA匹配的PyTorch版本。
显存不足是中等以上显卡跑large模型时的常见报错。可以在load_model或transcribe中降低模型尺寸，或者设置device参数指定使用CPU进行部分计算。对于长音频，官方Whisper实现会等待整个音频加载完成后再转写，内存占用较高。可以改用faster-whisper这类优化实现，它基于CTranslate2重写了推理部分，速度更快且显存占用更少。
音频格式不支持也是容易遇到的问题。Whisper依赖FFmpeg读取音频，如果文件扩展名正确但内容是特殊编码，仍然可能解码失败。此时可以先用FFmpeg把音频统一转换为16kHz单声道wav，再进行识别。对于中文长音频，使用initial_prompt提供领域词通常能明显降低错字率，但提示不宜过长，以免占用户过多的推理上下文。