如何 3 行代码跑通 Qwen3-ASR：Python 语音识别快速入门指南

如何 3 行代码跑通 Qwen3-ASR：Python 语音识别快速入门指南

【免费下载链接】Qwen3-ASRQwen3-ASR is an open-source series of ASR models developed by the Qwen team at Alibaba Cloud, supporting stable multilingual speech/music/song recognition, language detection and timestamp prediction.项目地址: https://gitcode.com/gh_mirrors/qw/Qwen3-ASR

Qwen3-ASR 是阿里巴巴 Qwen 团队开源的语音识别（ASR）模型系列，支持 52 种语言和方言的语音识别、语言检测与时间戳预测，还能识别歌曲人声。本文是一份面向新手和 Python 初学者的 Qwen3-ASR 快速入门指南：只需一条pip安装命令，再用 3 行代码加载模型，即可把一段音频转写成文字，零基础也能快速跑通。

为什么选择 Qwen3-ASR 语音识别模型？

在看代码之前，先花一分钟了解这个项目的核心卖点 🎯：

• All-in-one 多语言识别：Qwen3-ASR-1.7B 和 Qwen3-ASR-0.6B 同时支持 30 种语言和 22 种中文方言（粤语、吴语、闽南语、四川话等），无需预先指定语言，模型会自动做语言检测（Language Identification）。
• 开源 SOTA 性能：1.7B 版本在开源 ASR 模型中取得领先成绩，多项基准上接近最强商用 API 的水平。
• 支持唱歌和带背景音乐的人声：这是它区别于普通语音识别工具的亮点。
• 时间戳预测：配套的 Qwen3-ForcedAligner-0.6B 可以对 11 种语言的语音做词级/字级时间戳对齐，平均对齐误差仅约 33~43ms，大幅领先 WhisperX 等方案。

💡 新手建议：先用0.6B版本体验，速度更快、显存占用更低；追求识别质量再上1.7B。

Qwen3-ASR 安装步骤：一条命令装好 Python 包

最简单的使用方式是安装 PyPI 上的官方 Python 包qwen-asr（源码见 pyproject.toml，包入口见 qwen_asr/init.py）：

# 1. 创建一个干净的 Python 3.12 环境（推荐，避免依赖冲突） conda create -n qwen3-asr python=3.12 -y conda activate qwen3-asr # 2. 安装最小依赖（transformers 后端，足够入门） pip install -U qwen-asr

几个常见选择：

如果走源码方式，可以克隆仓库到本地再安装：

git clone https://gitcode.com/gh_mirrors/qw/Qwen3-ASR cd Qwen3-ASR pip install -e .

⚠️ 注意：模型权重在首次加载时会自动下载，无需手动搬运。若运行环境无法联网下载，可用 ModelScope 或 Hugging Face 客户端提前把Qwen/Qwen3-ASR-1.7B等权重拉到本地目录（具体命令见 README.md 的 "Released Models Description and Download" 章节）。

3 行代码跑通 Qwen3-ASR：最小推理示例

环境装好后，真正的推理代码只有 3 行核心逻辑——加载模型、传入音频、打印结果。以下示例来自 examples/example_qwen3_asr_transformers.py：

import torch from qwen_asr import Qwen3ASRModel # 第 1 行：加载 Qwen3-ASR 语音识别模型 model = Qwen3ASRModel.from_pretrained( "Qwen/Qwen3-ASR-1.7B", dtype=torch.bfloat16, device_map="cuda:0", ) # 第 2 行：把一段英文语音转写成文字 results = model.transcribe( audio="https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_en.wav", language=None, # None 表示自动检测语言 ) # 第 3 行：查看识别出的语言与文本 print(results[0].language) print(results[0].text)

把audio换成你自己电脑上的.wav文件路径，就能转写自己的音频了。输入形式很灵活：本地路径、网络 URL、base64 数据，甚至(np.ndarray, sr)波形元组都行，还支持批量推理（一次性传一个音频列表）。

运行后你会得到类似这样的输出：

English Mm. Oh, yeah, yeah. He wasn't even that big when I started listening to him...

进阶用法：批量转写 + 时间戳预测

想要"每句话/每个词出现在第几秒"的时间戳（做字幕、歌词对齐等场景很常用），只需加载时挂上 ForcedAligner 强制对齐模型（完整示例见 examples/example_qwen3_forced_aligner.py）：

import torch from qwen_asr import Qwen3ASRModel model = Qwen3ASRModel.from_pretrained( "Qwen/Qwen3-ASR-1.7B", dtype=torch.bfloat16, device_map="cuda:0", forced_aligner="Qwen/Qwen3-ForcedAligner-0.6B", # 关键：启用时间戳 forced_aligner_kwargs=dict(dtype=torch.bfloat16, device_map="cuda:0"), ) # 批量转写两条音频，并返回时间戳 results = model.transcribe( audio=["audio_zh.wav", "audio_en.wav"], language=["Chinese", "English"], return_time_stamps=True, ) for r in results: print(r.language, r.text, r.time_stamps[0])

这样每段音频都会输出语言 + 全文 + 逐词开始/结束时间，非常适合做字幕生成和语音分析。

想更快？切换 vLLM 后端与本地 Web UI

最快的推理方式：vLLM 后端

对速度敏感时，官方强烈推荐使用 vLLM 后端（需pip install -U qwen-asr[vllm]，参考 examples/example_qwen3_asr_vllm.py）：

if __name__ == '__main__': # 必须放在 main 保护下，避免 vLLM spawn 报错 model = Qwen3ASRModel.LLM( model="Qwen/Qwen3-ASR-1.7B", gpu_memory_utilization=0.7, max_inference_batch_size=128, ) results = model.transcribe(audio="audio.wav")

vLLM 后端还支持流式识别（边说边出字，仅支持 vLLM 后端），示例见 examples/example_qwen3_asr_vllm_streaming.py。

不想写代码？一行命令启动 Web UI

安装qwen-asr后，内置了几个命令行工具（定义在 pyproject.toml 的[project.scripts]中）：

# 启动 Gradio 网页版演示，浏览器打开 http://localhost:8000 即可试听 qwen-asr-demo \ --asr-checkpoint Qwen/Qwen3-ASR-1.7B \ --backend transformers \ --ip 0.0.0.0 --port 8000 # 启动流式识别演示（需 vLLM 后端） qwen-asr-demo-streaming --asr-model-path Qwen/Qwen3-ASR-1.7B --port 8000 # 启动 OpenAI 兼容的推理服务 qwen-asr-serve Qwen/Qwen3-ASR-1.7B --port 8000

qwen-asr-serve启动后就是一个标准 OpenAI 风格 API 服务，可以用requests或 OpenAI SDK 直接发请求转写音频，方便集成进现有系统。

常见问题与调优建议

其他关键文件指引：

• 推理核心实现：qwen_asr/inference/qwen3_asr.py
• 强制对齐模型：qwen_asr/inference/qwen3_forced_aligner.py
• 模型结构定义：qwen_asr/core/transformers_backend/modeling_qwen3_asr.py
• 技术报告：assets/Qwen3_ASR.pdf
• 官方镜像 Dockerfile：docker/Dockerfile-qwen3-asr-cu128

总结：从 0 到语音识别只要三步

回顾一下，跑通 Qwen3-ASR 语音识别的完整路径非常短：

1. 装包：pip install -U qwen-asr
2. 加载模型：Qwen3ASRModel.from_pretrained("Qwen/Qwen3-ASR-1.7B", ...)
3. 转写音频：model.transcribe(audio="你的音频.wav")

Qwen3-ASR 把多语言识别、语言检测、时间戳预测、流式推理全部打包进了一个开源工具包里，对个人开发者来说，是目前上手成本最低的开源 ASR 方案之一。现在就可以打开终端，3 行代码体验你的第一次语音转文字 🔥。

【免费下载链接】Qwen3-ASRQwen3-ASR is an open-source series of ASR models developed by the Qwen team at Alibaba Cloud, supporting stable multilingual speech/music/song recognition, language detection and timestamp prediction.项目地址: https://gitcode.com/gh_mirrors/qw/Qwen3-ASR