Qwen Audio Agent

Qwen Audio Agent 快速入门

让你的 AI Agent 开口说话——实时语音交互，不只是打字聊天。

这是什么？适合谁？

Qwen Audio Agent 是通义千问团队的实时语音 Agent 运行时。它解决了传统 AI Agent 只能打字交互的痛点——通过语音输入/输出，让 Agent 像真人一样保持”在线通话”状态，适合需要语音交互的场景。

想象一下：你在开车时想让 AI 帮你查资料、你在做饭时想和 AI 讨论菜谱变体、你在做实验时双手没空但要记录数据——Qwen Audio Agent 让你用嘴”编程”。

适合：需要为 Agent 添加语音交互功能的开发者；想做语音助手、智能客服、语音版 AI 导师的应用开发者；研究多模态 Agent 交互的研究者。

准备工作

• Node.js 18+：框架用 JavaScript 实现
• 通义千问 API Key：注册阿里云百炼平台获取，新用户有免费额度
• 麦克风和扬声器：测试语音交互需要音频硬件
• 付费提示：语音识别和合成按 API 调用量计费，约 ¥0.004/千字符（识别）+ ¥2/万字符（合成）

3 步快速上手

第 1 步：安装

git clone https://github.com/QwenAudio/qwen-audio-agent.git
cd qwen-audio-agent
npm install

第 2 步：配置 API Key

# 创建 .env 文件
echo "DASHSCOPE_API_KEY=your-key-here" > .env

第 3 步：启动语音 Agent

npm start
# Agent 开始监听麦克风，说"你好"开始对话
# 按 Ctrl+C 停止

预期结果：终端显示”Listening…”，你说”帮我查一下今天天气”，Agent 语音回复天气信息。

踩坑指南

踩坑 1：麦克风权限未授权

症状：启动后报 Permission denied: microphone

原因：操作系统未授权终端访问麦克风

解决：macOS 在”系统设置 → 隐私与安全性 → 麦克风”中添加终端；Windows 在”设置 → 隐私 → 麦克风”中允许

踩坑 2：API Key 额度不足

症状：Agent 有反应但语音识别质量差，或返回”quota exceeded”

原因：阿里云百炼免费额度用完（新用户约 100 万 Token）

解决：登录阿里云百炼控制台查看余额，按需充值

踩坑 3：中文识别偶尔不准确

症状：说”千问”被识别成”亲吻”

原因：嘈杂环境或方言影响语音识别模型精度

解决：使用外接麦克风，在安静环境测试。可在配置中指定语言模型版本

踩坑 4：长时间通话 Agent 内存溢出

症状：连续通话超过 10 分钟后，Agent 响应变慢或崩溃

原因：语音上下文缓存未及时清理

解决：在配置中设置 maxConversationTurns 限制每轮对话长度，或在代码中定期调用 agent.resetContext()

踩坑 5：Windows 下音频设备驱动问题

症状：Windows 终端运行时报 No audio device found

原因：缺少系统音频驱动或 Windows 音频服务异常

解决：确保 Windows Audio 服务正在运行（services.msc 中找到并启动）

常见问题 FAQ

Q1: 和通义千问 App 的语音功能有什么区别？

A: Qwen Audio Agent 是给开发者用的开源语音运行时，你可以把它嵌入自己的应用。通义千问 App 的语音是给最终用户用的产品。前者灵活可定制，后者开箱即用。比如你要做一个”AI 面试官”应用，应该用 Audio Agent 而不是 App。

Q2: 支持哪些语言？

A: 主要支持中文和英文。中日韩多语言在测试中。英文识别质量与 Whisper 相当。

Q3: 语音合成听起来自然吗？

A: 使用阿里云 CosyVoice 语音合成引擎，支持多种音色（温柔女声、沉稳男声、活泼童声等），自然度接近真人。可在配置中切换音色。

Q4: 需要 GPU 吗？

A: 不需要。语音识别和合成都在云端完成，本地只负责音频采集和播放。普通笔记本即可。

Q5: 可以离线使用吗？

A: 当前版本依赖云端 API。离线语音识别需要自行集成 Whisper 等本地模型。

参考链接

• 官方仓库
• 阿里云百炼平台
• Apache-2.0 开源协议

基于公开资料整理，AI 辅助生成 | 核验日期：2026-07-31