手把手教学：Qwen3-ASR-1.7B API调用全解析-深圳市維司達科技有限公司

手把手教学：Qwen3-ASR-1.7B API调用全解析

导语：你是否还在为会议录音转文字耗时费力而发愁？是否想快速把一段采访音频变成可编辑的文稿，却苦于找不到稳定、易用又支持中文方言的语音识别工具？Qwen3-ASR-1.7B 就是为此而生——它不是实验室里的概念模型，而是一个开箱即用、部署简单、API清晰、效果扎实的语音识别服务。本文不讲晦涩原理，不堆参数指标，只聚焦一件事：让你从零开始，5分钟内跑通第一次识别，30分钟内掌握全部调用方式，1小时内就能集成进自己的工作流。

1. 为什么选 Qwen3-ASR-1.7B？它和你用过的其他语音识别有什么不同

很多开发者试过开源ASR模型，最后都卡在几个现实问题上：环境配不起来、API文档看不懂、中文识别不准、方言完全不认、或者一跑就显存爆炸。Qwen3-ASR-1.7B 的设计思路很务实：先让事情能做成，再追求做得更好。

它不是参数最大的模型，但它是目前少有的、把“好用”放在首位的中型ASR镜像。1.7B 参数意味着它不需要8张A100才能启动——单卡24G显存（如RTX 4090或A10）就能稳稳运行；4.4GB 模型体积让它下载快、加载快；vLLM后端则保证了高并发下的响应稳定性。

更重要的是，它真正理解中文场景。支持30种语言+22种中文方言，不是“列个名字完事”，而是实测可用：粤语新闻、四川话访谈、闽南语家常对话，它都能自动识别并输出对应语言标签。你不用提前告诉它“这段是粤语”，它自己听出来，再转成文字——这种“无感适配”能力，在真实业务中省掉大量预处理环节。

另外，它采用 OpenAI 兼容 API 格式。这意味着：如果你已经写过调用 GPT 或其他 vLLM 模型的代码，几乎不用改逻辑，只需换一个 model 路径和 content 类型，就能直接对接语音识别。对已有项目做语音能力升级，成本极低。

2. 快速上手：两种方式，总有一种适合你

2.1 WebUI 界面：零代码，三步完成识别（推荐给非开发人员或快速验证）

如果你只是想马上试试效果，或者需要临时处理几段音频，WebUI 是最快路径。它就像一个网页版的语音转文字小程序，无需安装、不写代码、不配环境。

第一步：打开界面
在已部署该镜像的服务器上，访问http://localhost:7860（或你配置的公网IP+端口），即可看到简洁的识别页面。
第二步：填入音频
页面提供「示例URL」按钮，点击即可自动填入官方测试音频：
https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_en.wav
你也可以替换成自己的音频链接（支持HTTP/HTTPS直链，格式为 WAV/MP3/FLAC，时长建议≤5分钟）。
第三步：点一下，等结果
点击「开始识别」，几秒后，右侧就会显示带语言标识的识别结果，例如：
language English<asr_text>Hello, this is a test audio file.</asr_text>
如果你上传的是中文音频，它会自动输出language Chinese<asr_text>你好，这是一段测试音频。</asr_text>。

优势：直观、即时、无门槛
注意：WebUI 默认使用自动语言检测，如需强制指定语言（比如确保粤语不被误判为普通话），可在高级选项中手动选择。

2.2 API 调用：面向开发者，灵活嵌入业务系统

当你需要批量处理、集成进脚本、或接入企业应用时，API 是唯一选择。Qwen3-ASR-1.7B 提供标准 REST 接口，并兼容 OpenAI Python SDK，大幅降低学习成本。

2.2.1 Python 调用（最常用，推荐）

以下代码在任何装有 Python 3.9+ 和openai包的环境中均可运行（无需本地模型，只要服务已启动）：

from openai import OpenAI # 初始化客户端（注意：base_url 指向你的服务地址，api_key 固定为 "EMPTY"） client = OpenAI( base_url="http://localhost:8000/v1", api_key="EMPTY" ) # 发起识别请求（替换为你自己的音频URL） response = client.chat.completions.create( 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_zh.wav"} }] } ], # 可选：指定语言（若关闭自动检测） # extra_body={"language": "Chinese"} ) # 提取纯文本内容（去除 language 和 <asr_text> 标签） raw_output = response.choices[0].message.content import re text_match = re.search(r'<asr_text>(.*?)</asr_text>', raw_output) if text_match: print("识别结果：", text_match.group(1)) else: print("未匹配到识别文本，原始返回：", raw_output)

关键说明：

model参数必须与镜像文档中完全一致（注意下划线___是转义后的.，不可写成/root/.../Qwen3-ASR-1.7B）
content必须是列表，且每个元素是字典，type必须为"audio_url"，结构不能错
返回结果含固定格式前缀，建议用正则提取，避免硬切字符串

2.2.2 cURL 调用（调试与跨语言集成）

适用于 Shell 脚本、CI/CD 流程或非 Python 环境（如 Node.js、Go）：

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_cantonese.wav"} }] }] }'

小技巧：用jq工具可直接解析并提取文本：

curl -s ... | jq -r '.choices[0].message.content' | sed -n 's/.*<asr_text>\(.*\)<\/asr_text>.*/\1/p'

3. 实战进阶：处理真实业务中的常见需求

3.1 如何指定语言？什么时候该关掉自动检测

自动检测很方便，但在某些场景下反而不准。比如：

一段混合粤语和普通话的访谈，自动检测可能全程标为Chinese
专业术语密集的英文技术讲座，夹杂中文人名，可能被误判为Chinese

此时，你可以通过extra_body参数强制指定语言（Python）或在 JSON 中添加字段（cURL）：

# Python 方式（在 create() 调用中加入） response = client.chat.completions.create( model="...", messages=[...], extra_body={"language": "Cantonese"} # 支持值见文档：Chinese / Cantonese / Sichuanese 等 )

# cURL 方式（在 JSON body 中添加） -d '{ "model": "...", "messages": [...], "language": "Cantonese" }'

建议：对已知语种的批量任务（如全部粤语客服录音），务必指定语言，准确率提升显著；对未知语种探索性任务，保留自动检测更稳妥。

3.2 如何处理本地音频文件（而非网络URL）

API 只接受音频 URL，不支持直接上传二进制文件。但你有三个实用方案：

方案一：临时托管（最简单）
用python -m http.server 8000在本地启一个静态服务，把音频放进去，然后用http://localhost:8000/xxx.wav当 URL 调用。

方案二：OSS/对象存储（生产推荐）
将音频上传至阿里云 OSS、腾讯云 COS 或 MinIO，生成公开可读 URL。这是企业级做法，安全、可追溯、支持大文件。

方案三：服务端代理（高级）
在你的后端加一层轻量代理：接收用户上传的音频 → 保存临时文件 → 用file://协议？不行（vLLM 不支持）→ 所以仍需转成 HTTP URL。因此，前两种更实际。

3.3 如何提升识别质量？三个立竿见影的技巧

Qwen3-ASR-1.7B 本身已优化充分，但音频质量直接影响结果。以下三点无需改模型，只需调整输入：

降噪预处理：用noisereduce或 Audacity 对原始录音做一次轻度降噪（尤其对会议室回声、键盘敲击声有效），WER 可下降 15–20%
采样率统一为 16kHz：模型训练数据以此为主，非 16kHz 音频（如 44.1kHz 音乐转录）建议先重采样，避免失真
分段提交长音频：单次请求建议 ≤3分钟。超过5分钟的会议录音，按句子/段落切分（可用pydub按静音分割），分别识别后拼接，比整段识别错误率更低

4. 故障排查：遇到问题，先看这三处

部署顺利不代表永远不出错。以下是高频问题及对应解法，按发生概率排序：

4.1 “Connection refused” 或 “Failed to connect”

第一步：确认服务是否在运行
运行supervisorctl status，检查qwen3-asr-1.7b和qwen3-asr-webui是否均为RUNNING
若为FATAL或STOPPED，执行supervisorctl restart qwen3-asr-1.7b
第二步：确认端口是否被占用
netstat -tuln | grep :8000查看 8000 端口是否被其他进程占用。如有，修改config/supervisor_qwen3_asr.conf中的port配置
第三步：确认 Conda 环境激活
conda activate torch28后再操作，否则 supervisor 可能无法加载正确依赖

4.2 识别结果为空，或返回格式异常

检查音频 URL 是否可公开访问
在浏览器中直接打开该 URL，确认能正常播放且不是 403/404。私有 bucket 需设为 public-read
检查音频格式与时长
仅支持 WAV/MP3/FLAC；MP3 建议用 CBR 编码（VBR 可能解析失败）；单文件建议 ≤5分钟（vLLM 默认 max_tokens 限制）
检查返回内容是否含<asr_text>
若返回纯乱码或空字符串，大概率是音频损坏或 URL 失效。用curl -I <your_url>确认 HTTP 状态码为 200

4.3 GPU 显存不足，服务启动失败

日志中出现CUDA out of memory错误时：

修改scripts/start_asr.sh中的GPU_MEMORY参数
将GPU_MEMORY="0.8"改为"0.5"或"0.4"，降低显存占用比例
同时检查--gpu-memory-utilization参数是否重复设置（vLLM 启动命令中应只有一处）
若仍失败，可尝试添加--enforce-eager启动参数（牺牲一点速度，换取显存稳定）