Qwen3-ASR-1.7B保姆级教程：从安装到API调用，一篇搞定

语音识别，这个听起来有点技术门槛的词，其实离我们很近。想想看，手机里的语音助手、会议软件里的实时字幕、短视频平台上的自动字幕生成，背后都有它的身影。但过去，想要自己动手搭建一个高质量的语音识别系统，往往意味着复杂的部署流程、高昂的硬件成本和漫长的调试过程。

今天，这个门槛被大大降低了。阿里通义千问团队开源的 Qwen3-ASR-1.7B，将一款兼顾精度与效率的中等规模语音识别模型，封装成了开箱即用的镜像。它支持30种主流语言和22种中文方言，无论是普通话会议记录，还是带口音的方言访谈，都能准确识别。

更重要的是，它提供了极其友好的 WebUI界面 和标准的 OpenAI兼容API，让你无需深入了解深度学习框架，就能快速上手，将语音转文字的能力集成到自己的应用中。

这篇教程，就是为你准备的“一站式”指南。我们将从最基础的镜像启动开始，手把手带你体验WebUI的便捷，再深入到API调用的细节，最后解决你可能遇到的常见问题。目标很简单：让你在30分钟内，从零开始，拥有一个属于自己的、功能强大的语音识别服务。

1. 环境准备与快速启动

在开始之前，我们先快速了解一下Qwen3-ASR-1.7B的核心信息。它是一个基于17亿参数大模型的语音识别系统，模型文件大小约为4.4GB。它运行在 torch28 这个Conda环境中，并使用高效的 vLLM 作为推理后端，这意味着它在保证识别精度的同时，也能有不错的响应速度。

对于已经通过CSDN星图镜像广场等平台部署了该镜像的用户，启动过程通常是一键完成的。系统会自动完成环境配置和服务加载。启动后，你会看到两个关键的服务地址：

• WebUI 界面：http://localhost:7860 (或你指定的公网IP/域名)
• API 服务：http://localhost:8000/v1

你可以通过访问WebUI地址来打开图形化操作界面。如果服务没有自动启动，或者你需要管理服务状态，可以使用以下命令：

# 查看所有服务的运行状态
supervisorctl status

# 如果WebUI服务未运行，可以手动启动它
supervisorctl start qwen3-asr-webui

# 同样，可以启动核心的ASR识别服务
supervisorctl start qwen3-asr-1.7b

# 查看WebUI的实时日志，有助于排查问题
supervisorctl tail -f qwen3-asr-webui stderr

看到服务状态显示为 RUNNING，就说明你的语音识别引擎已经准备就绪了。

2. 零门槛体验：WebUI图形界面

对于绝大多数只是想快速体验功能，或者进行单次、小批量文件识别的用户，WebUI界面是最佳选择。它完全通过浏览器操作，直观易懂。

2.1 界面初探

打开 http://localhost:7860，你会看到一个简洁的界面。核心区域通常包括：

1. 音频URL输入框：用于粘贴网络音频文件的直接链接。
2. 语言选择下拉框（可选）：你可以手动指定音频的语言，如果留空或选择“Auto”，模型会自动检测。
3. “开始识别”按钮：点击它，魔法就开始了。
4. 结果显示区域：识别完成后，文本会显示在这里。

2.2 三步完成第一次识别

我们用一个官方提供的示例音频，来完成第一次识别：

1. 填入音频地址：在“音频URL”输入框中，粘贴以下测试链接：

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

   这是一个简短的英文测试音频。你也可以填入任何可公开访问的 .wav 或 .mp3 等常见格式的音频文件链接。

2. 选择语言：由于我们知道这是英文音频，可以在语言下拉框中选择 English。当然，选择 Auto（自动检测）也完全没问题。

3. 点击识别：点击“开始识别”按钮。稍等片刻（通常几秒到十几秒，取决于音频长度和网络速度），下方的结果框就会显示出识别出的文字：

   language English<asr_text>Hello, this is a test audio file.</asr_text>
   

看，就是这么简单！你不需要准备任何代码，也不需要懂命令行，就已经成功将一段英文语音转换成了文本。对于中文普通话、粤语、四川话等，操作流程完全一样，模型会自动适配。

小技巧：如果你想识别自己电脑上的本地音频文件，需要先将其上传到某个可以通过公网URL访问的地方，比如云存储服务，然后将得到的文件链接粘贴到这里。

3. 集成开发：API接口调用详解

当你需要将语音识别能力嵌入到自己的程序、网站或自动化流程中时，API接口就派上用场了。Qwen3-ASR-1.7B提供了与OpenAI API完全兼容的接口，这意味着如果你之前使用过ChatGPT的API，那么你会感到非常熟悉。

3.1 使用Python调用

这是最灵活的方式，适合在Python项目中集成。你需要先安装 openai 这个Python包（如果尚未安装的话）：

pip install openai

然后，你可以使用如下代码进行调用：

from openai import OpenAI

# 1. 初始化客户端，指向本地启动的ASR服务
client = OpenAI(
    base_url="http://localhost:8000/v1",  # API服务地址
    api_key="EMPTY"  # 本地服务通常不需要密钥，用"EMPTY"填充即可
)

# 2. 发起识别请求
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": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_en.wav"  # 音频文件链接
                }
            }]
        }
    ],
)

# 3. 打印识别结果
print(response.choices[0].message.content)

运行这段代码，你会在控制台得到和WebUI中一样的识别结果。response.choices[0].message.content 这个字段里就包含了完整的识别文本。

代码解读：

• base_url：指向你本地运行的API服务。
• model：这个路径是镜像中固定的模型存放位置，直接照抄即可。
• messages：虽然叫“chat”，但这里我们传递的是一条包含音频URL的“用户消息”。
• audio_url：这是关键，告诉API去识别指定URL的音频。

3.2 使用cURL命令行调用

如果你习惯使用命令行，或者需要在Shell脚本中集成，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"}
            }]
        }]
    }'

执行后，你会直接收到一个JSON格式的响应，其中 content 字段就是识别文本。

3.3 处理更复杂的情况

指定语言：如果你想明确告诉模型音频的语言，以提高准确率或处理混合语言场景，可以在 messages 中添加一个文本“提示”：

response = client.chat.completions.create(
    model="/root/ai-models/Qwen/Qwen3-ASR-1___7B",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "这是一段中文普通话音频。"},  # 语言提示
                {
                    "type": "audio_url",
                    "audio_url": {
                        "url": "https://your-audio-file.com/chinese.wav"
                    }
                }
            ]
        }
    ],
)

4. 进阶技巧与问题排查

掌握了基本使用后，了解一些进阶技巧和常见问题的解决方法，能让你的使用过程更加顺畅。

4.1 理解输出格式

API返回的文本有一个固定的格式：

language <语言标签><asr_text>这里是识别出的文本内容</asr_text>

例如：language English<asr_text>Hello, this is a test audio file.</asr_text> 你在提取内容时，可以解析这个格式，也可以直接获取整个字符串，</asr_text> 标签之后的部分就是纯净的识别结果。

4.2 遇到显存不足怎么办？

如果音频较长或并发请求较多，可能会遇到GPU显存不足的错误。这时可以调整服务启动时分配的显存比例。 修改文件 /root/Qwen3-ASR-1.7B/scripts/start_asr.sh，找到 GPU_MEMORY 这一行：

# 默认可能是0.8，表示使用80%的显存
GPU_MEMORY="0.8"
# 可以尝试调低，比如0.6或0.5
GPU_MEMORY="0.6"

修改后，需要重启ASR服务才能生效：

supervisorctl restart qwen3-asr-1.7b

4.3 服务无法启动或调用失败？

按照以下步骤排查：

1. 检查环境：确保Conda环境已激活。在终端输入 conda activate torch28。
2. 查看日志：日志是排查问题的第一手资料。

   # 查看ASR核心服务日志
   supervisorctl tail qwen3-asr-1.7b stderr
   # 查看WebUI日志
   supervisorctl tail qwen3-asr-webui stderr
   

3. 检查模型文件：确认模型文件已正确下载。

   ls -la /root/ai-models/Qwen/Qwen3-ASR-1___7B/
   

4. 检查端口占用：确保8000和7860端口没有被其他程序占用。

4.4 探索更多功能

• Swagger API文档：访问 http://localhost:8000/docs，你可以看到一个交互式的API文档页面，里面详细列出了所有可用的端点及其参数，甚至可以就地发送测试请求。
• 方言支持：模型自动支持22种中文方言。对于像粤语、四川话、闽南语等音频，你通常不需要做任何特殊设置，选择“Auto”即可，模型会努力识别。如果效果不理想，可以尝试在API调用时通过文本提示指明方言。

5. 总结

回顾一下，我们完成了一次完整的Qwen3-ASR-1.7B语音识别之旅：

1. 快速启动：利用预置镜像，我们几乎零配置地启动了一个功能强大的语音识别服务。
2. 直观体验：通过WebUI界面，以最直观的方式完成了第一次语音转文字，感受到了其易用性和准确性。
3. 深度集成：学习了如何使用Python和cURL通过标准的OpenAI兼容API来调用服务，这为自动化处理和系统集成打开了大门。
4. 应对挑战：了解了如何调整配置以应对显存问题，以及如何通过查看日志来排查服务故障。

Qwen3-ASR-1.7B的价值在于，它将一个复杂的AI能力封装成了简单的服务。无论是用于个人学习、开发测试，还是作为企业项目中一个可靠的语音识别模块，它都是一个极具性价比的选择。其开源和免费商用的特性，更是降低了技术尝试和产品创新的门槛。

现在，你可以尝试用自己的音频文件（记得先上传到网络获取URL）进行测试，或者开始构思如何将它应用到你的会议记录工具、内容生产流程或智能助手应用中了。语音识别的世界，已经向你敞开。

---

获取更多AI镜像

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