语音识别 (ASR) 项目完全新手指南

🎙️ 语音识别 (ASR) 项目完全新手指南

欢迎使用本语音识别项目！本文档专为零基础新手设计，将带你从“什么是语音识别”开始，一步步完成环境搭建、运行、测试，直到彻底弄懂它是如何工作的。

🏗️ 第零部分：从零开始创建项目（如果这里啥文件也没有）

如果你面前是一个空文件夹，你需要创建以下文件才能开始：

0.1 准备项目文件

你需要创建以下 4 个核心文件（可以用记事本创建，然后改名）：

1. app.py（主程序）

   • 作用：启动服务，加载 AI 模型。
   • 内容：复制粘贴你拿到的 app.py 完整代码。

2. requirements.txt（零件清单）

   • 作用：告诉 Python 需要安装哪些库。
   • 内容：复制以下内容保存：

     aiofiles==24.1.0
     fastapi==0.115.5
     ffmpeg==1.4
     ffmpeg_python==0.2.0
     funasr==1.1.16
     modelscope==1.20.1
     moviepy==1.0.3
     Requests==2.32.3
     uvicorn==0.32.1
     numpy==1.24.0
     pydub
     python-multipart
     python-dotenv
     psutil
     

3. hotwords.txt（热词表，可选）

   • 作用：提高特定词汇的识别率。
   • 内容：每行写一个词（如“阿里巴巴”、“通义实验室”），或者留空。

4. test/client.py（测试脚本）

   • 作用：用来测试服务好不好用。
   • 操作：新建一个 test 文件夹，在里面新建 client.py，填入测试代码。

0.2 那些“自动出现”的文件是怎么来的？

你可能会疑惑：“文件夹里怎么多出了好多我没创建的文件？” 别担心，不需要运行什么“初始化命令”。只要你运行了代码，程序就会自动帮你创建这些文件夹：

• 📂 models/：

  • 来源：第一次运行 app.py 时，程序会自动联网下载 1GB 多的模型文件放在这里。
  • 小白理解：这是程序的“大脑”，它是自动长出来的，不用你管。

• 📂 logs/：

  • 来源：app.py 启动时，会自动创建一个文件夹来写日记（日志）。
  • 小白理解：这是程序的“日记本”，记录它干了什么。

• 📂 temp_dir/：

  • 来源：处理音频时，程序需要个地方暂存文件，用完可能会自动删。
  • 小白理解：这是程序的“草稿纸”。

• 📂 __pycache__/：

  • 来源：Python 运行代码时自动生成的缓存。
  • 小白理解：这是 Python 的“加速器”，完全可以无视它。

0.3 没有初始化命令吗？

你可能会问：“不需要像 Java 或者前端项目那样运行什么初始化命令吗？”

不需要！

• Python 项目非常自由，“新建文件”就是它的初始化。
• 你手动创建了上面那几个文件，就已经完成了一个 Python 项目的“初始化”工作。

---

📖 第一部分：基础知识（这是什么？）

1.1 这个项目是干嘛的？

想象你雇了一个“速记员”，你给它播放一段录音，它快速地帮你把录音里的内容写成文字。 这个项目就是一个AI 速记员（服务端程序）。

1.2 它是怎么工作的？

整个流程就像去餐厅点菜：

1. 服务端（餐厅厨房）：就是 app.py。它启动后一直在后台等着。
2. 客户端（顾客）：就是 test/client.py。它负责把“食材”（录音文件）交给厨房。
3. 处理（做菜）：服务端收到录音，用 AI 模型进行分析、识别。
4. 响应（上菜）：服务端把识别好的“文字”返回给客户端。

---

🛠️ 第二部分：环境搭建（在新电脑上怎么跑？）

如果你换了一台全新的 Windows 电脑，必须先安装以下两个“基建”软件，否则程序跑不起来。

2.1 第一步：安装 Python (编程语言环境)

这个项目是用 Python 写的，所以必须先装 Python。我们推荐 Python 3.10 版本。

• 方法 A（推荐，最快）： 打开终端（PowerShell），复制并运行以下命令：

  winget install Python.Python.3.10
  

• 方法 B（手动下载）：
  1. 访问 Python 官网下载页。
  2. 下载 Windows installer (64-bit)。
  3. 安装时务必勾选 Add Python to PATH（这一步至关重要！）。

2.2 第二步：安装 FFmpeg (音频处理工具)

AI 模型只听得懂特定格式的音频（比如 16000Hz 采样率），FFmpeg 负责把各种乱七八糟的录音文件转换成 AI 能听懂的格式。

• 安装命令：

  winget install Gyan.FFmpeg
  

• 重要：安装完成后，必须关闭当前终端，重新打开一个新的终端，否则电脑不认识 ffmpeg 命令。

📦 第三部分：项目初始化（安装零件）

环境装好了，现在要安装项目特有的“零件”（第三方库）。

3.1 安装依赖库

在项目文件夹下打开终端，运行以下命令（直接复制）：

# 解释：使用 python 3.10，通过清华大学的镜像站（下载速度快）来安装 requirements.txt 里列出的所有库
py -3.10 -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3.2 补充安装 Torch (如果上一步报错)

Torch 是 AI 的核心引擎。如果上一步安装顺利，这里可以跳过。如果发现报错说找不到 torch，请单独运行：

py -3.10 -m pip install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple

🚀 第四部分：启动服务（开始运行！）

一切准备就绪，我们来启动“厨房”。

4.1 启动命令

在终端输入：

py -3.10 app.py

4.2 你会看到什么？

1. 第一次启动时：你会看到屏幕上疯狂刷屏下载进度条。
   • 这是在干嘛？ 程序发现你本地没有 AI 模型，正在自动从网上下载（大概 1.5GB）。
   • 你要做什么？ 等。去喝杯咖啡，下载完会自动继续。
2. 启动成功时：当屏幕最后停在类似这样的一行字：

   INFO:     Uvicorn running on http://0.0.0.0:8000
   

   🎉 恭喜！服务已经启动成功了！ 此时不要关闭这个窗口。

🧪 第五部分：测试使用（验证成果）

现在厨房开张了，我们来发个订单试试。

5.1 准备测试

1. 保持刚才启动服务的窗口打开（不要关！）。
2. 新建一个终端窗口（在 IDE 里点 + 号）。

5.2 运行测试脚本

在新的窗口里输入：

py -3.10 test/client.py

5.3 见证奇迹

几秒钟后，你应该会看到一段 JSON 格式的文字输出：

• text: 这里面就是识别出来的完整文字。
• sentences: 这里面是拆解的每一句话，甚至包含是谁说的（spk:1 代表说话人1）。

如果你看到了这些文字，说明你已经完全跑通了整个流程！

---

❓ 第六部分：常见小白问答

Q1: 这个 models 文件夹好大，有 1GB 多，我能删了吗？

• 可以删。如果你硬盘不够了，直接删掉 models 文件夹没事。
• 但是：下次你再运行 app.py 时，它又会重新下载一遍。建议如果不缺空间就留着，这样下次启动只要几秒钟。

Q2: 为什么我运行命令报错说 'py' 不是内部或外部命令？

• 这说明你安装 Python 时可能没勾选 Add to PATH，或者系统没反应过来。
• 解决：尝试把命令里的 py -3.10 换成 python 试试。如果还不行，建议重装 Python 并确保勾选 PATH 选项。

Q3: 我能识别自己的录音吗？

• 能！
  1. 把你录好的 .wav 文件放到项目文件夹里（比如叫 my_audio.wav）。
  2. 打开 test/client.py 文件。
  3. 找到第 6 行：audio_path=r"./test_audio.wav"。
  4. 改成你的文件名：audio_path=r"./my_audio.wav"。
  5. 再次运行测试脚本即可。

---