小白友好：Qwen3-ASR-1.7B语音识别模型一键部署与使用教程

想不想让电脑听懂你说话？不管是把会议录音转成文字，还是给视频自动加字幕，或者做个能聊天的语音助手，以前这些都得靠大公司的服务。现在不一样了，有了Qwen3-ASR-1.7B这个模型，你在自己的电脑上就能搞定，而且完全免费，所有数据都在本地处理，不用担心隐私泄露。

这个模型是阿里通义千问团队出的，专门用来做语音识别。名字里的1.7B意思是它有17亿个参数，不算特别大，但在准确度和速度之间找到了很好的平衡。最厉害的是它能听懂30种不同的语言，还能识别22种中文方言，比如粤语、四川话这些，基本上你平时能听到的它都能处理。

今天我就带你从零开始，把这个模型装到你的电脑上，然后手把手教你用它。整个过程很简单，就算你之前没怎么接触过AI模型也能跟着做下来。准备好了吗？咱们开始吧。

1. 准备工作：看看你的电脑行不行

在动手安装之前，先确认一下你的电脑配置够不够。语音识别是个比较吃资源的活，特别是需要用到显卡来加速。

硬件要求：

  • 显卡（GPU）： 这是最重要的。你需要一块NVIDIA的显卡，而且显存至少要有8GB。像RTX 3060、RTX 3070或者更好的显卡都可以。如果没有独立显卡，只用CPU也能跑，但速度会慢很多。
  • 内存（RAM）： 建议16GB或以上。
  • 硬盘空间： 除了安装系统本身，还需要预留大约10GB的空间来放模型文件和各种依赖包。
  • 操作系统： Linux系统是最佳选择，比如Ubuntu 20.04或22.04。如果你用Windows，后面我会提到一个变通的方法。

软件环境：

  • Python： 需要Python 3.8到3.11之间的版本。
  • CUDA： 如果你的显卡是NVIDIA的，需要安装CUDA 11.8。这是让模型能用上显卡加速的关键。

如果你的电脑符合这些要求，那就可以放心往下走了。如果暂时没有合适的显卡，也可以先看看教程，了解整个流程，等有条件了再实践。

2. 两种方法，总有一款适合你

这个模型提供了两种主要的使用方式，一种是通过网页界面点点鼠标就能用，另一种是通过写代码来调用，更灵活。你可以根据你的需要和习惯来选择。

2.1 方法一：WebUI网页界面（推荐新手）

这是最简单的方法，不需要写任何代码，有个浏览器就能用。它会启动一个本地网页，你上传音频文件或者输入一个网络音频的链接，它就能把里面的语音转成文字。

适合谁用：

  • 想快速体验模型效果的朋友。
  • 不需要把识别功能集成到自己程序里的用户。
  • 偶尔需要转换一些音频文件的人。

它的界面通常很直观，有上传按钮、语言选择框和一个开始识别的按钮，用起来跟普通网站没什么区别。

2.2 方法二：API接口调用（推荐开发者）

如果你是个程序员，或者你想把这个语音识别功能用到自己的软件、网站或者脚本里，那就需要用API来调用。模型会作为一个服务运行在后台，你写的程序可以像访问一个网站接口一样，把音频数据发过去，然后接收识别出来的文字。

适合谁用：

  • 开发者，想把语音识别集成到自己的应用中。
  • 需要批量处理大量音频文件的人。
  • 想要更自动化、可编程控制流程的用户。

这种方式更强大，也更有趣。接下来，我们就分别看看这两种方法具体怎么操作。

3. 手把手部署：让模型跑起来

无论你用哪种方法，第一步都是要把模型服务在电脑上启动起来。这里我假设你使用的是Linux系统（比如Ubuntu），并且已经准备好了Python和CUDA环境。

第一步：获取模型和代码

通常，你需要从模型的官方仓库（比如GitHub）把代码下载下来。打开终端，执行类似下面的命令：

# 克隆代码仓库到本地
git clone https://github.com/Qwen/Qwen3-ASR.git
cd Qwen3-ASR

第二步：安装必要的软件包

模型运行需要一堆Python库来支持。一般项目里会有一个叫requirements.txt的文件，里面列出了所有需要的包。我们直接用pip安装它们：

# 创建并激活一个Python虚拟环境（推荐，可以避免包版本冲突）
python -m venv venv
source venv/bin/activate

# 安装依赖包
pip install -r requirements.txt

第三步：启动服务

根据你想用的方式，启动对应的服务。

  • 启动WebUI服务： 通常项目里会有一个启动WebUI的脚本，比如webui.py或者通过一个命令启动。你可能会运行：

    python webui.py

    运行成功后，终端会显示一个本地地址，比如 http://localhost:7860。把这个地址复制到浏览器里打开，就能看到操作界面了。

  • 启动API后端服务： 如果要使用API，需要先启动模型的后端推理服务。根据文档，它可能使用vLLM这样的高效推理引擎。启动命令可能类似：

    python -m vllm.entrypoints.openai.api_server \
    --model /root/ai-models/Qwen/Qwen3-ASR-1___7B \
    --served-model-name qwen-asr

    这个命令会让模型在 http://localhost:8000 这个地址上提供API服务。

启动过程可能会需要几分钟，因为模型比较大，要加载到内存和显存里。看到服务成功运行的信息后，就可以进行下一步了。

4. 实战演练：WebUI界面快速上手

假设你已经通过上面的步骤，在浏览器中打开了WebUI界面（比如 http://localhost:7860）。界面可能长得像下面这样，虽然具体布局可能不同，但核心功能都差不多：

  1. 音频输入区域： 这里通常有一个文本框，让你粘贴音频文件的网络链接（URL），或者一个上传按钮，让你选择电脑本地的音频文件（如.wav, .mp3格式）。
  2. 语言选择（可选）： 一个下拉菜单，让你选择音频的语言，比如中文、英文。如果不知道或者音频里混有多种语言，可以选择“自动检测”。
  3. 识别按钮： 一个大大的“开始识别”或“Transcribe”按钮。

我们来试一下：

  • 方法A：用网络音频链接 在教程文档里，我们看到了一个示例链接：

    https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_en.wav

    把这个链接复制到输入框里，点击“开始识别”。稍等几秒，下方就会显示出识别结果：Hello, this is a test audio file.

  • 方法B：上传本地文件 点击“上传”按钮，从你的电脑里选择一个录音文件。比如，你可以用手机录一段“今天天气不错”的语音，保存为MP3格式上传。点击识别后，看看它能不能准确地转成文字。

是不是很简单？你可以多试几个文件，比如试试带点背景音乐的，或者语速比较快的，看看它的表现如何。

5. 进阶玩法：用代码调用API

如果你喜欢用代码控制一切，或者需要把识别功能嵌入到你的程序里，API调用是你的不二之选。模型提供了兼容OpenAI格式的API，用起来非常方便。

首先，确保API后端服务已经启动（在终端里运行着，地址是 http://localhost:8000）。

然后，我们写一个简单的Python脚本来测试：

# test_asr.py
from openai import OpenAI

# 1. 创建客户端，连接到我们本地启动的服务
client = OpenAI(
    base_url="http://localhost:8000/v1",  # 本地服务地址
    api_key="EMPTY"  # 因为是本地服务，不需要真正的API密钥
)

# 2. 准备一段音频的URL（可以是本地文件路径，但需要服务能访问到。更常见的是先上传或使用网络URL）
audio_url = "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_en.wav"

# 3. 构建请求消息
response = client.chat.completions.create(
    model="/root/ai-models/Qwen/Qwen3-ASR-1___7B",  # 指定模型路径
    messages=[
        {
            "role": "user",
            "content": [{
                "type": "audio_url",  # 告诉模型，内容是音频URL
                "audio_url": {"url": audio_url}
            }]
        }
    ],
)

# 4. 打印识别结果
print("识别结果：", response.choices[0].message.content)

保存这个脚本为 test_asr.py，然后在终端里运行：

python test_asr.py

你会看到输出结果，格式类似 language English<asr_text>Hello, this is a test audio file.</asr_text>。前面 language English 是它检测到的语言，<asr_text>标签里的就是识别出的文字。

如果你想用更通用的命令行工具测试，比如curl，也可以：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "/root/ai-models/Qwen/Qwen3-ASR-1___7B",
    "messages": [{
      "role": "user",
      "content": [{
        "type": "audio_url",
        "audio_url": {"url": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_en.wav"}
      }]
    }]
  }'

6. 管理你的语音识别服务

模型服务一旦启动，可能会长时间运行。这里有几个常用的管理命令，帮你查看状态、重启服务或者排查问题。

这些命令通常通过 supervisorctl 这个工具来执行，它负责管理后台服务的运行。

  • 查看所有服务状态：

    supervisorctl status

    这个命令会列出所有由它管理的服务（比如WebUI服务、ASR后端服务），并显示它们是正在运行（RUNNING）还是停止了（STOPPED）。

  • 重启WebUI界面服务： 如果网页打不开了或者界面卡住了，可以重启它。

    supervisorctl restart qwen3-asr-webui

  • 重启ASR核心识别服务： 如果识别功能出错了，可以重启后端。

    supervisorctl restart qwen3-asr-1.7b

  • 查看服务日志： 当服务启动失败或者运行出错时，查看日志是找问题的最好方法。

    # 查看WebUI服务的错误日志
supervisorctl tail -f qwen3-asr-webui stderr

# 查看ASR后端服务的错误日志
supervisorctl tail -f qwen3-asr-1.7b stderr

    参数 -f 表示“跟随”，会持续输出新的日志，方便你实时监控。

7. 你可能遇到的问题和解决办法

在部署和使用过程中，可能会碰到一些小麻烦。别担心，大部分都有解决办法。

  • 问题一：运行模型时提示“GPU显存不足（Out of Memory）” 原因： 你的音频太长了，或者模型加载时占用的显存比你显卡实际拥有的多。 解决：

    1. 尝试处理更短的音频片段。
    2. 修改启动脚本，限制模型使用的显存比例。找到 scripts/start_asr.sh 这个文件，里面可能有一个叫 GPU_MEMORY 的参数，默认是 0.8（即使用80%的显存）。你可以把它改小一点，比如 0.6 或 0.5。
    3. 如果显卡显存实在太小（比如小于6GB），可能就需要考虑在CPU上运行了，但速度会慢很多。

  • 问题二：服务启动失败，或者调用API没反应 原因： 环境没配置好，或者端口被占用了。 解决：

    1. 检查环境： 确保你激活了正确的Conda或Python虚拟环境。对于这个镜像，需要的环境是 torch28，可以运行 conda activate torch28 来激活。
    2. 检查模型文件： 运行 ls -la /root/ai-models/Qwen/Qwen3-ASR-1___7B/ 看看模型文件是否完整下载了。
    3. 检查端口： 默认的API端口是8000，WebUI端口是7860。用 netstat -tulpn | grep :8000 看看8000端口是不是已经被别的程序用了。如果是，可以在启动命令里换一个端口。

  • 问题三：识别中文方言（如粤语）效果不好 原因： 虽然模型支持方言，但可能对某些特定口音或嘈杂环境下的方言识别率会下降。 解决：

    1. 在WebUI或API请求中，明确指定语言参数为对应的方言（如果支持的话）。
    2. 确保音频质量尽可能好，减少背景噪音。
    3. 对于非常重要的场景，可以先用普通话试试，或者寻找更专门的方言识别模型。

8. 总结

好了，到这里你应该已经成功地把Qwen3-ASR-1.7B这个强大的语音识别模型部署到自己的环境里，并且学会了通过网页和代码两种方式来使用它。

我们来快速回顾一下今天的重点：

  1. 准备环境：确认电脑有NVIDIA显卡和足够的显存，准备好Linux和Python环境。
  2. 选择方式：想简单玩玩就用WebUI；想开发集成就用API。
  3. 部署模型：下载代码、安装依赖、启动服务，三步走。
  4. 开始使用：在网页上传音频或贴链接；用Python代码调用本地API接口。
  5. 管理服务：用几个简单的命令查看状态、重启服务、看日志。
  6. 遇到问题：优先检查显存是否够用、服务端口是否冲突、模型文件是否完整。

这个模型最吸引人的地方，就是它在本地运行，你的语音数据不用上传到任何人的服务器，隐私有保障。而且它支持的语言和方言非常多，实用性很强。无论是做会议记录的工具，还是给自己拍的视频加字幕，甚至做一个能和你对话的桌面助手，它都是一个非常好的起点。

动手试试吧，找一段有趣的音频，或者自己录几句话，看看它能不能准确地“听懂”你。实践过程中如果遇到文档没覆盖的问题，别忘了去查看项目的官方GitHub页面，那里通常有更详细的讨论和解决方案。

获取更多AI镜像

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

# 语音识别
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

从Anthropic官方文档看Claude的安全机制：隔离、模型与外部内容的三层防御体系

十二个月前，如果有人提议让Claude拥有足以搞垮Anthropic内部服务的权限，我们一定会断然拒绝。而今天，这种访问级别已经成为常态，Anthropic内部的开发者们正因为这种部署而大幅提升了生产力。这是我读完Anthropic官方工程博客《How we contain Claude across products》（2026年5月25日发布）后的第一感受。当AI Agent的能力越强大，它的

avatar AI Agent技术社区
cover

AI Agent 为什么会跑偏：目标漂移、上下文污染和工具诱导

avatar AI Agent技术社区
cover

斯坦福 OpenJarvis 源码解读:一个“本地优先“AI Agent 框架是怎么设计的

avatar AI Agent技术社区