Whisper-large-v3步骤详解：从requirements.txt安装到app.py启动全链路

你是不是也遇到过这种情况？手里有一段重要的会议录音，或者一段外语视频，想要快速转换成文字，却找不到一个好用的工具。手动听写？效率太低。市面上的在线服务？要么收费昂贵，要么担心隐私泄露。

今天，我就带你从零开始，手把手部署一个属于你自己的、功能强大的语音识别服务。我们将要搭建的是基于 OpenAI Whisper Large v3 模型的Web应用。它不仅能识别99种语言，还能自动检测语言，支持上传音频文件或直接录音，最关键的是，它完全在你的掌控之中，数据安全有保障。

整个过程就像搭积木一样简单，你不需要是AI专家，只要跟着我的步骤走，一个小时后，你就能拥有一个媲美商业服务的语音转文字工具。我们开始吧。

1. 准备工作：理清思路与检查环境

在动手敲代码之前，我们先花几分钟，搞清楚我们要做什么，以及需要准备什么。这能帮你避开很多后续的坑。

1.1 项目是做什么的？

简单来说，这个项目就是一个语音识别网站。你打开浏览器，访问一个本地网址（比如 http://localhost:7860），就能看到一个简洁的网页。在这个网页上，你可以：

• 上传音频文件：支持 MP3、WAV、M4A 等常见格式。
• 直接录音：点击按钮，对着麦克风说话，实时识别。
• 选择模式：可以只转录成原文，也可以翻译成英文。
• 查看结果：识别出的文字会立刻显示在页面上，你可以复制或下载。

所有这些功能，背后都依靠 Whisper Large v3 这个强大的模型在支撑。它就像是一个精通99门语言的“耳朵”，负责把声音“听”成文字。

1.2 你的电脑需要满足什么条件？

这个模型比较“吃”硬件，尤其是显卡。以下是推荐的配置，如果你的配置稍低，后面我也会告诉你调整的方法。

硬件/环境	推荐配置	最低要求/说明
操作系统	Ubuntu 24.04 LTS	Linux系统（如Ubuntu 20.04+）最佳，Windows/macOS也可但可能需额外步骤。
显卡 (GPU)	NVIDIA RTX 4090 D (23GB显存)	强烈建议有NVIDIA显卡。显存8GB以上可尝试 large-v3，4GB可尝试 medium 模型。纯CPU也能跑，但速度会慢很多。
内存	16GB+	至少8GB，越大越好。
存储空间	10GB+	主要用来存放模型文件（约3GB）和Python环境。
网络	畅通	首次运行需要下载模型，约2.9GB。

重点检查你的显卡： 打开终端，输入以下命令，看看能否正确显示你的NVIDIA显卡信息。

nvidia-smi

如果看到类似下图的信息，说明驱动和CUDA环境基本没问题，可以享受GPU加速。如果报错，你可能需要先安装NVIDIA驱动和CUDA工具包，这部分网上教程很多，这里不展开。

2. 环境搭建：一步步安装所有依赖

好了，现在我们知道目标了，也检查了“地基”（环境）。接下来，我们开始“盖房子”。整个过程分为三步：安装Python依赖、安装音频处理工具、下载模型。

2.1 第一步：安装Python依赖包

项目所有的Python库都写在一个叫 requirements.txt 的文件里。我们只需要一条命令，就能自动安装所有需要的“零件”。

1. 打开终端，进入到你的项目目录。假设你把项目文件下载到了 /root/Whisper-large-v3/。

   cd /root/Whisper-large-v3/
   

2. 执行安装命令：

   pip install -r requirements.txt
   

   这条命令会读取 requirements.txt 文件，自动安装 gradio（用来做网页界面）、torch（PyTorch深度学习框架）、whisper（OpenAI的库）等核心组件。

   可能会遇到的问题：

   • 速度慢：因为要从国外的服务器下载，可能会很慢甚至超时。解决方法是指定国内的镜像源，比如清华源：

     pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
     

   • 权限错误：如果提示“Permission denied”，可以在命令前加上 sudo，或者使用 pip install --user 选项安装到用户目录。

2.2 第二步：安装FFmpeg（音频处理核心）

Whisper模型本身不直接处理MP3、M4A这类压缩音频文件。它需要一个“翻译官”先把这些格式转换成它认识的原始音频数据。这个“翻译官”就是 FFmpeg，一个强大的音视频处理工具。

在Ubuntu或Debian系统上，安装非常简单：

sudo apt-get update
sudo apt-get install -y ffmpeg

安装完成后，可以在终端输入 ffmpeg -version 检查是否安装成功。

如果你是Windows/macOS用户：

• Windows：可以去FFmpeg官网下载编译好的可执行文件，并将其所在目录添加到系统的环境变量 PATH 中。
• macOS：使用Homebrew安装最方便：brew install ffmpeg。

2.3 第三步：理解模型下载（首次运行自动进行）

Whisper Large v3模型文件大约有2.9GB。好消息是，你不需要手动下载。当你第一次运行程序时，代码会自动从Hugging Face的服务器下载这个模型。

模型会被保存在一个固定的缓存目录：/root/.cache/whisper/（Linux系统）或 C:\Users\<你的用户名>\.cache\whisper\（Windows系统）。文件名为 large-v3.pt。

请注意：

• 确保网络通畅：首次运行需要下载2.9GB文件，请保持网络稳定。
• 耐心等待：下载速度取决于你的网络，下载过程中程序可能会“卡住”，这是正常的，不要中断它。
• 磁盘空间：确保缓存目录所在的磁盘有足够空间。

3. 核心实战：启动服务与使用指南

所有依赖都准备好了，最激动人心的时刻来了——启动服务，看看它的真面目。

3.1 启动Web服务

在项目根目录下，执行一条简单的命令：

python3 app.py

你会看到终端开始滚动输出一些信息。如果一切顺利，最后几行会看到类似这样的提示：

Running on local URL:  http://0.0.0.0:7860

这表示服务已经成功启动，并在本机的7860端口上监听。

3.2 访问与使用Web界面

打开你的浏览器（Chrome, Firefox等），在地址栏输入：http://localhost:7860，然后回车。

一个简洁的Gradio界面就会出现在你面前。通常它包含以下几个部分：

1. 模式选择：transcribe（转录，输出原语言文字）或 translate（翻译，输出英文文字）。
2. 音频输入：一个文件上传区域和一个“录音”按钮。
3. 执行按钮：一个“Submit”或“Transcribe”按钮。
4. 结果输出：一个文本框，用于显示识别出的文字。

我们来试一下：

1. 点击“上传”按钮，选择一个你的MP3或WAV文件。
2. 点击“Submit”按钮。
3. 稍等片刻（时间取决于音频长度和你的电脑速度），识别结果就会出现在下方的文本框里。

3.3 试试用代码调用（进阶）

除了使用网页，这个模型本身也是一个Python库，你可以在自己的Python脚本里直接调用它，实现自动化处理。

创建一个新的Python文件，比如 my_transcribe.py，写入以下代码：

import whisper

# 加载模型，指定使用GPU（如果可用）
model = whisper.load_model("large-v3", device="cuda") # device="cpu" 表示使用CPU

# 转录音频文件
result = model.transcribe("你的音频文件路径.mp3", language="zh") # 指定语言为中文，不指定则自动检测

# 打印结果
print("识别出的文本：")
print(result["text"])

# 如果你想看更详细的信息，比如每段话的时间戳
print("\n带时间戳的段落：")
for segment in result["segments"]:
    print(f"[{segment['start']:.2f}s -> {segment['end']:.2f}s] {segment['text']}")

运行这个脚本，你就能在命令行里看到识别结果。这对于批量处理大量音频文件非常有用。

4. 遇到问题怎么办？常见故障排查

即使步骤再详细，也可能会遇到一些小问题。别担心，大部分问题都有现成的解决办法。

你遇到的问题	可能的原因和解决办法
运行 python3 app.py 时报错 ffmpeg not found	FFmpeg没有正确安装或不在系统路径中。解决：确保已按照2.2步骤安装，并在终端输入 ffmpeg -version 确认。
启动时卡住，提示下载模型失败	网络连接问题。解决： 1. 检查网络。 2. 可以尝试手动下载模型：在能访问的机器上下载 large-v3.pt 文件，放到 ~/.cache/whisper/ 目录下。 3. 使用国内镜像（如果可用）。
运行中程序崩溃，提示 CUDA out of memory	显卡显存不够。解决： 1. 换小模型：修改 app.py 或代码中的 whisper.load_model(“large-v3”)，将 “large-v3” 换成 “medium”、“small” 或 “tiny”。模型越小，精度略低，但所需显存也越少。 2. 用CPU运行：将 device 参数改为 “cpu”（速度会慢很多）。 3. 关闭其他占用显存的程序。
访问 http://localhost:7860 打不开	端口被占用或服务没启动。解决： 1. 检查终端里服务是否成功启动（看是否有Running的提示）。 2. 检查端口是否被占用：`netstat -tlnp
识别中文效果不好	Whisper对中文的识别效果已经很好，但如果音频质量差（嘈杂、口音重、语速快），效果会下降。解决： 1. 尽量上传清晰的音频。 2. 在 transcribe 函数中尝试调整参数，如 fp16=False（如果CPU运行）。

5. 总结

回顾一下，我们今天完成了一件很酷的事：从无到有，部署了一个功能强大的多语言语音识别Web服务。我们经历了：

1. 规划与检查：明确了项目目标，核对了硬件环境。
2. 安装与配置：用 requirements.txt 一键安装Python环境，并确保了FFmpeg这个关键组件的就位。
3. 启动与体验：一行命令启动服务，通过浏览器就能使用直观的界面进行语音转文字。
4. 探索与调试：了解了如何用代码直接调用模型，并学会了解决常见的运行问题。

这个由 Whisper Large v3 驱动的服务，其核心优势在于隐私性、可控性和高质量。无论是处理个人录音、会议纪要，还是为视频添加字幕，它都是一个得力的离线助手。

你可以在此基础上继续探索，比如：

• 修改 app.py 的界面，增加批量上传功能。
• 将服务部署到云服务器，通过公网访问。
• 将识别结果自动保存为SRT字幕文件。
• 尝试集成到你的其他应用工作流中。

希望这篇详细的指南能帮你顺利搭建起自己的语音识别工具。技术不再是黑盒，动手实践，你就能掌控它。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。