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

如何 3 行代码跑通 Qwen3-ASRPython 语音识别快速入门指南【免费下载链接】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-ASRQwen3-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 python3.12 -y conda activate qwen3-asr # 2. 安装最小依赖transformers 后端足够入门 pip install -U qwen-asr几个常见选择安装方式适用场景pip install -U qwen-asr入门试用transformers 后端pip install -U qwen-asr[vllm]追求最快推理速度 流式识别源码安装pip install -e .需要修改代码、做二次开发官方 Docker 镜像不想折腾环境装好 GPU 驱动就能跑如果走源码方式可以克隆仓库到本地再安装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.pyimport torch from qwen_asr import Qwen3ASRModel # 第 1 行加载 Qwen3-ASR 语音识别模型 model Qwen3ASRModel.from_pretrained( Qwen/Qwen3-ASR-1.7B, dtypetorch.bfloat16, device_mapcuda:0, ) # 第 2 行把一段英文语音转写成文字 results model.transcribe( audiohttps://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_en.wav, languageNone, # None 表示自动检测语言 ) # 第 3 行查看识别出的语言与文本 print(results[0].language) print(results[0].text)把audio换成你自己电脑上的.wav文件路径就能转写自己的音频了。输入形式很灵活本地路径、网络 URL、base64 数据甚至(np.ndarray, sr)波形元组都行还支持批量推理一次性传一个音频列表。运行后你会得到类似这样的输出English Mm. Oh, yeah, yeah. He wasnt even that big when I started listening to him...进阶用法批量转写 时间戳预测想要每句话/每个词出现在第几秒的时间戳做字幕、歌词对齐等场景很常用只需加载时挂上 ForcedAligner 强制对齐模型完整示例见 examples/example_qwen3_forced_aligner.pyimport torch from qwen_asr import Qwen3ASRModel model Qwen3ASRModel.from_pretrained( Qwen/Qwen3-ASR-1.7B, dtypetorch.bfloat16, device_mapcuda:0, forced_alignerQwen/Qwen3-ForcedAligner-0.6B, # 关键启用时间戳 forced_aligner_kwargsdict(dtypetorch.bfloat16, device_mapcuda:0), ) # 批量转写两条音频并返回时间戳 results model.transcribe( audio[audio_zh.wav, audio_en.wav], language[Chinese, English], return_time_stampsTrue, ) 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.pyif __name__ __main__: # 必须放在 main 保护下避免 vLLM spawn 报错 model Qwen3ASRModel.LLM( modelQwen/Qwen3-ASR-1.7B, gpu_memory_utilization0.7, max_inference_batch_size128, ) results model.transcribe(audioaudio.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 8000qwen-asr-serve启动后就是一个标准 OpenAI 风格 API 服务可以用requests或 OpenAI SDK 直接发请求转写音频方便集成进现有系统。常见问题与调优建议问题建议显存不足 / OOM换 0.6B 模型调小max_inference_batch_size装 FlashAttention 2 省显存长音频转写不完整调大max_new_tokens如 1024/2048语言识别不准手动指定languageChinese/English强制语言需要时间戳加载时传forced_alignerQwen/Qwen3-ForcedAligner-0.6B并设return_time_stampsTrue依赖冲突用全新的 conda 环境重装或用官方 Docker 镜像想微调专属模型参考 finetuning/README.md 和 finetuning/qwen3_asr_sft.py支持多卡torchrun训练其他关键文件指引推理核心实现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官方镜像 Dockerfiledocker/Dockerfile-qwen3-asr-cu128总结从 0 到语音识别只要三步回顾一下跑通 Qwen3-ASR 语音识别的完整路径非常短装包pip install -U qwen-asr加载模型Qwen3ASRModel.from_pretrained(Qwen/Qwen3-ASR-1.7B, ...)转写音频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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考