将连续音频流实时转写为文字
实时语音识别服务接收音频流并实时转写为带标点的文本,适用于直播字幕、在线会议、语音聊天、智能助手等场景。
实现低延迟音频到文本转换。
Qwen-Audio-3.0-ASR-Flash-Streaming 和 Fun-ASR-Realtime 默认输出句级与字级两种粒度的时间戳,便于字幕对齐、关键词高亮、卡拉 OK 跟读等场景。Qwen3-ASR-Flash-Realtime(qwen3-asr-flash-realtime)当前不返回时间戳信息,如需时间戳请使用 Qwen-Audio-3.0-ASR-Flash-Streaming 或 Fun-ASR-Realtime。录音文件转写模型
以上字段名以 WebSocket JSON 路径为准。不同 SDK 暴露上述字段的命名习惯不同(如字典 key、对象属性、getter 方法等),完整字段对照请参见服务端事件。
Qwen3-ASR-Flash-Realtime(qwen3-asr-flash-realtime) 可在转写结果中附带说话人的情绪状态:固定开启,无需配置。在
以上字段名以 WebSocket JSON 路径为准。不同 SDK 暴露上述字段的命名习惯不同(如字典 key、对象属性、getter 方法等),完整字段定义、取值约束与示例请参见服务端事件。
Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime 的 WebSocket 连接支持复用:一个识别任务结束后,无需重新建立连接即可开启下一个任务。
复用流程:客户端发送
Qwen3-ASR-Flash-Realtime 采用会话模式,每次会话结束后需主动断开连接,不支持连接复用。
各模型事件说明请参见对应的 API 参考。
DashScope SDK 内置池化机制,可复用 WebSocket 连接和识别对象,避免频繁创建销毁带来的开销。
2. 配置连接池通过环境变量配置连接池关键参数:
3. 配置对象池通过环境变量配置对象池大小:
通过如下代码创建对象池:4. 从对象池中获取 Recognition 对象未归还的对象数量超过对象池上限时,系统会额外创建新的 5. 进行语音识别调用
敏感词过滤可对识别结果中的敏感词执行替换或移除,适用于客服质检、内容合规、字幕审核等场景。
不同 SDK 暴露上述参数的命名习惯不同(如字典 key、对象属性、方法等),完整字段对照请参见 Fun-ASR 实时语音识别 API 参考。
通过提供上下文,可优化特定领域词汇的识别效果,例如人名、地名和产品术语。
长度限制: 上下文内容不得超过 10,000 个 token。
使用方式:
如需实现上述效果,可将以下任意一种内容添加至上下文:
Qwen 实时语音识别通过 WebSocket 流式传输音频。提供两种模式:VAD 模式(默认) 和手动模式。
将
服务端检测语音边界并自动分句。客户端流式推送音频,服务端在每句话结束时返回识别结果。适合对话和会议转写场景。
启用方式: 在
由客户端控制分句:发送一句话完整的音频后,再发送
启用方式: 在
您也可以使用 Qwen-Omni(
ASR 提示词模板:
Qwen-Audio-3.0-ASR-Flash-Streaming 和 Fun-ASR-Realtime 支持 pcm、wav、mp3、opus、speex、aac、amr 格式。Qwen3-ASR-Flash-Realtime 推荐使用 pcm 或 opus 格式;其他格式(如 wav、aac、amr)虽然在
DashScope SDK 封装了 WebSocket 连接管理、鉴权、重连等细节,适合快速集成。WebSocket API 直连提供更细粒度的控制能力,适用于 SDK 未覆盖的编程语言或需要自定义连接管理的场景。推荐优先使用 SDK。
使用热词或上下文增强。详细的配置方法和使用说明,请参见提升识别准确率。
建议实现客户端重连机制,并开启心跳参数(
概述
实现低延迟音频到文本转换。
- 支持普通话及粤语、四川话等多种方言的高精度语音识别
- 具备应对复杂声学环境的能力,支持自动语种检测与智能非人声过滤
- 支持惊讶、平静、愉快、悲伤、厌恶、愤怒、恐惧等多种情绪状态识别
- 支持热词定制,可提升特定词汇的识别准确率
- 支持上下文增强,通过配置上下文提高识别准确率
- 支持时间戳输出,生成结构化识别结果
- 灵活采样率与多种音频格式,适配不同录音环境
模型可用性、支持语言和功能对比,请参见语音转文字模型。
前提条件
- 已获取 API Key并将其配置到环境变量。
- 如果通过 DashScope SDK 调用,需安装最新版 SDK。
- 如果通过 AOQ 协议接入 Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime,需下载并集成 AOQ 客户端 SDK,详见 AOQ SDK 简介。
快速开始
- Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime
- Qwen3-ASR-Flash-Realtime
更多代码示例,请参见 GitHub。获取 API Key 并将其设置为环境变量。如需使用 SDK,请先安装。如果通过 AOQ 协议接入 Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime,需要下载并集成 AOQ 客户端 SDK,详见 AOQ SDK 简介。该模型除 WebSocket 协议外,还支持通过 AOQ 协议接入;如果是客户端对接,且更看重稳定的延迟、弱网下的交互能力、实时双工的降噪与回声消除,可优先考虑 AOQ,协议对比与选型请参见模型/应用支持力度。
安装依赖
模型可用性
以下价格为目录价。具体优惠活动及折扣价格请前往模型市场查看。
| 模型 | 版本 | 单价 | 免费额度 (说明) |
|---|---|---|---|
| fun-asr-realtime 当前版本:fun-asr-realtime-2025-11-07 | 稳定版 | 0.00033元/秒 | 36,000 秒(10 小时) 有效期 90 天 |
| fun-asr-realtime-2025-11-07 | 快照版 | 0.00033元/秒 | 36,000 秒(10 小时) 有效期 90 天 |
- 支持语言:普通话、粤语、吴语、闽南语、客家话、赣语、湘语、晋语,以及中原、西南、冀鲁、江淮、兰银、胶辽、东北、北京、港台等地区的普通话口音——涵盖河南、陕西、湖北、四川、重庆、云南、贵州、广东、广西、河北、天津、山东、安徽、南京、江苏、杭州、甘肃、宁夏等地。同时支持英语和日语。
- 采样率:16 kHz
- 音频格式:pcm、wav、mp3、opus、speex、aac、amr
从麦克风实时识别
从麦克风采集音频并实时输出识别结果。运行 Python 示例前,请先执行
pip install pyaudio 安装第三方音频播放和采集套件。pyaudio 依赖 portaudio 库:Ubuntu/Debian 执行 sudo apt-get install libportaudio2 portaudio19-dev,macOS 执行 brew install portaudio。识别本地音频文件
该功能用于识别并转写本地音频文件,适合需要近实时处理短音频的场景,如语音聊天、语音指令、语音输入和语音搜索。以下示例使用的音频文件为 asr_example.wav。
WebSocket API
以下示例演示如何通过原生 WebSocket 连接发送本地音频文件并获取识别结果。以下示例使用的音频文件为 asr_example.wav。
请勿将示例代码文件命名为
websocket.py,否则可能出现以下错误:AttributeError: module 'websocket' has no attribute 'WebSocketApp'. Did you mean: 'WebSocket'?进阶功能
获取时间戳
Qwen-Audio-3.0-ASR-Flash-Streaming 和 Fun-ASR-Realtime 默认输出句级与字级两种粒度的时间戳,便于字幕对齐、关键词高亮、卡拉 OK 跟读等场景。Qwen3-ASR-Flash-Realtime(qwen3-asr-flash-realtime)当前不返回时间戳信息,如需时间戳请使用 Qwen-Audio-3.0-ASR-Flash-Streaming 或 Fun-ASR-Realtime。录音文件转写模型 qwen3-asr-flash-filetrans 支持字级时间戳,详见非实时语音识别。
时间戳单位均为毫秒,分两个层级返回:
- 句级:
payload.output.sentence.begin_time与payload.output.sentence.end_time,标识整句在音频中的起止时刻。中间结果中end_time可能为null,待句子结束(sentence_end = true)时填充最终值。 - 字级:
payload.output.sentence.words数组,每个元素包含begin_time、end_time、text(该字/词文本)以及punctuation(该字后跟随的标点,无则为空串)。
情感识别
Qwen3-ASR-Flash-Realtime(qwen3-asr-flash-realtime) 可在转写结果中附带说话人的情绪状态:固定开启,无需配置。在 conversation.item.input_audio_transcription.text 与 conversation.item.input_audio_transcription.completed 事件中均通过顶层 emotion 字段返回,取值为 7 类细粒度情绪:surprised(惊讶)、neutral(平静)、happy(愉快)、sad(悲伤)、disgusted(厌恶)、angry(愤怒)、fearful(恐惧)。
上线部署
连接复用(WebSocket)
Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime 的 WebSocket 连接支持复用:一个识别任务结束后,无需重新建立连接即可开启下一个任务。
复用流程:客户端发送 finish-task,服务端返回 task-finished 后,可重新发送 run-task 开启新任务。
- 必须等服务端返回
task-finished事件后才可发起新任务。 - 复用连接中的不同任务需要使用不同的
task_id。 - 任务失败时服务端返回错误事件并关闭连接,该连接不可复用。
- 任务结束后 60 秒无新任务,连接自动断开。
高并发最佳实践
DashScope SDK 内置池化机制,可复用 WebSocket 连接和识别对象,避免频繁创建销毁带来的开销。
目前仅 Java SDK 支持此功能。
点击查看高并发最佳实践
点击查看高并发最佳实践
前提条件
- 已获取 API Key并将其配置到环境变量。
- 已安装符合版本要求的 DashScope SDK,建议安装最新版:Java SDK 版本 ≥ 2.16.9。
- 连接池:SDK 内部集成的 OkHttp3 连接池,负责管理和复用底层的 WebSocket 连接,减少网络握手开销。此功能默认开启。
- 对象池:基于
commons-pool2实现,用于维护一组已预先建立好连接的Recognition对象。从池中获取对象可消除连接建立的延迟,显著降低首包延迟。
实现步骤
1. 添加依赖根据项目构建工具,在依赖配置文件中添加 dashscope-sdk-java 和 commons-pool2。- Maven
- Gradle
在
pom.xml 的 <dependencies> 标签内添加以下依赖,保存后执行 mvn clean install 或 mvn compile 更新依赖。| 环境变量 | 描述 |
|---|---|
DASHSCOPE_CONNECTION_POOL_SIZE | 连接池大小。推荐值:峰值并发数的 2 倍以上。默认值:32。 |
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS | 最大异步请求数。推荐值:与 DASHSCOPE_CONNECTION_POOL_SIZE 保持一致。默认值:32。 |
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST | 单主机最大异步请求数。推荐值:与 DASHSCOPE_CONNECTION_POOL_SIZE 保持一致。默认值:32。 |
| 环境变量 | 描述 |
|---|---|
RECOGNITION_OBJECTPOOL_SIZE | 对象池大小。推荐值:峰值并发数的 1.5 至 2 倍。默认值:500。 |
- 对象池的大小(
RECOGNITION_OBJECTPOOL_SIZE)必须小于或等于连接池的大小(DASHSCOPE_CONNECTION_POOL_SIZE)。否则,当对象池请求对象时,若连接池已满,会导致调用线程阻塞。 - 对象池大小不应超过账户的 QPS(每秒查询率)限制。
Recognition 对象。这类新对象需重新建立 WebSocket 连接,无法复用。Recognition 对象的 call 或 streamCall 方法进行语音识别。6. 归还 Recognition 对象语音识别任务结束后,归还 Recognition 对象以供复用。不要归还未完成任务或任务失败的对象。完整代码
推荐配置
以下配置基于在指定规格的服务器上仅运行实时语音识别服务的测试结果。其中单机并发数指的是同一时刻正在运行的实时语音识别任务数(即工作线程数)。| 机器配置 | 单机最大并发数 | 对象池大小 | 连接池大小 |
|---|---|---|---|
| 4 核 8 GiB | 100 | 500 | 2000 |
| 8 核 16 GiB | 200 | 500 | 2000 |
| 16 核 32 GiB | 400 | 500 | 2000 |
资源管理与异常处理
-
任务成功:必须调用
GenericObjectPool.returnObject()将 Recognition 对象归还到池中以便复用。不要归还未完成任务或任务失败的 Recognition 对象。 - 任务失败:当 SDK 内部或业务逻辑抛出异常导致任务中断时,必须主动关闭底层的 WebSocket 连接,并从对象池中废弃该对象,防止被再次使用。
- 在服务出现 TaskFailed 报错时,不需要额外处理。
调用预热与耗时统计
在对 DashScope Java SDK 进行并发调用延迟等性能评估时,建议在正式测试前执行充分的预热操作。连接复用机制DashScope Java SDK 通过全局单例的连接池管理和复用 WebSocket 连接。该机制的工作特点如下:- 按需创建:SDK 不会在服务启动时预创建 WebSocket 连接,而是在首次调用时按需建立。
- 限时复用:请求完成后,连接将在池中保留最多 60 秒以备复用。若 60 秒内有新请求,将复用现有连接,避免重复握手开销;若连接空闲超过 60 秒,将被自动关闭以释放资源。
- 应用刚启动,尚未发起任何调用。
- 服务空闲时间超过 60 秒,池中连接已因超时而关闭。
- 模拟正式测试的并发级别,提前发起一定数量的调用(例如,持续 1~2 分钟),以充分填充连接池。
- 确认连接池已建立并维持足够的活跃连接后,再开始正式的性能数据采集。
提升识别准确率
- 选择采样率匹配的模型:对于 8 kHz 电话音频,请直接使用 8 kHz 模型,而非将其上采样至 16 kHz 后再识别。上采样会导致信息失真,影响识别效果。
- 使用自定义词汇功能:针对业务专有名词、人名、品牌名等,可配置自定义词汇,显著提升识别准确率。详情请参见自定义词汇。
- 优化输入音频质量:尽量使用高质量麦克风,保证较高的信噪比(SNR)和无回声的录音环境。在应用层,可集成降噪(如 RNNoise)和声学回声消除(AEC)等算法对音频进行预处理,获取更干净的信号。
- 指定识别语言:对于多语言模型,若在调用时能预先确定音频语言,有助于模型快速收敛,避免发音相似的语言之间产生混淆,从而提升准确率。
敏感词过滤
敏感词过滤可对识别结果中的敏感词执行替换或移除,适用于客服质检、内容合规、字幕审核等场景。
- 支持范围:仅 Fun-ASR。
- 使用限制:最多支持设置 32 个敏感词。
- 默认行为:未传入
special_word_filter参数时,不会对敏感词进行过滤。
special_word_filter 是 JSON 对象,包含三个子字段:
filter_with_signed.word_list:字符串数组,列出需要被替换为等长*的敏感词。例如["测试"],「帮我测试一下」会变成「帮我**一下」。filter_with_empty.word_list:字符串数组,列出需要从结果中完全移除的敏感词。例如["开始"],「比赛这就要开始了吗」会变成「比赛这就要了吗」。system_reserved_filter:布尔值,默认false。是否启用敏感词过滤功能。
设置容错策略
- 客户端断线重连:客户端应实现自动重连机制,以应对网络抖动。对于 Python SDK,建议:
- 捕获异常:在
Callback类中实现on_error方法。网络错误或其他异常发生时,dashscopeSDK 会调用此方法。 - 通知状态:
on_error触发时,设置重连信号。在 Python 中,可使用线程安全标志threading.Event。 - 重连循环:将主逻辑包裹在
for循环中(例如重试 3 次)。检测到重连信号时,中断当前识别、清理资源,并在等待数秒后重启循环以建立新连接。
- 捕获异常:在
- 设置心跳防止连接断开:为保持与服务器的持久连接,请将
heartbeat参数设置为true。即使音频长时间静音,也能确保连接不中断。 - 限流:调用模型接口时,请注意遵守模型的限流规则。
核心功能:上下文增强(Qwen-ASR)
通过提供上下文,可优化特定领域词汇的识别效果,例如人名、地名和产品术语。
长度限制: 上下文内容不得超过 10,000 个 token。
使用方式:
- WebSocket API:在 session.update 事件中设置
session.input_audio_transcription.corpus.text参数。 - Python SDK:设置
corpus_text参数。 - Java SDK:设置
corpusText参数。
- 各类分隔符格式的热词列表,如:热词1、热词2、热词3、热词4
- 任意格式和长度的文本段落或章节
- 混合内容:词汇列表与段落的任意组合
- 无关或无意义的文本,包括乱码。该功能容错性强,几乎不受无关文本的负面影响。
| 无上下文增强 | 有上下文增强 |
|---|---|
| 无上下文增强时,部分投行名称可能被误识。例如,"Bulge Bracket"被识别为"鸟石"。识别结果:"你了解哪些投行圈的内部黑话?首先是九大外资投行,即鸟石,BB……" | 有上下文增强时,投行名称被正确识别。识别结果:"你了解哪些投行圈的内部黑话?首先是九大外资投行,即 Bulge Bracket,BB……" |
- 词汇列表:
- 词汇列表 1:
- 词汇列表 2:
- 词汇列表 3:
- 自然语言:
- 含干扰信息的自然语言:部分文本与识别内容无关,例如以下示例中的人名列表。
API 参考
- Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime
- Qwen3-ASR-Flash-Realtime
- Fun-ASR 实时语音识别 API 参考
- AOQ 客户端 API(适用于 Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime)
交互流程(Qwen-ASR-Realtime)
Qwen 实时语音识别通过 WebSocket 流式传输音频。提供两种模式:VAD 模式(默认) 和手动模式。
URL
将 <model_name> 替换为您的模型名称。
请求头
VAD 模式(默认)
服务端检测语音边界并自动分句。客户端流式推送音频,服务端在每句话结束时返回识别结果。适合对话和会议转写场景。
启用方式: 在 session.update 事件中设置 session.turn_detection。
-
客户端发送
input_audio_buffer.append,向缓冲区追加音频。 -
服务端检测到语音时,返回
input_audio_buffer.speech_started。若客户端在此事件之前发送了session.finish,服务端将返回session.finished,客户端须断开连接。 -
客户端继续发送
input_audio_buffer.append。 -
所有音频发送完毕后,客户端发送
session.finish结束会话。 -
服务端检测到语音结束时,返回
input_audio_buffer.speech_stopped。 -
服务端返回
input_audio_buffer.committed。 -
服务端返回
conversation.item.created。 -
服务端返回
conversation.item.input_audio_transcription.text,包含实时转写结果。 -
服务端返回
conversation.item.input_audio_transcription.completed,包含最终转写结果。 -
识别完成后,服务端返回
session.finished,客户端须断开连接。
手动模式
由客户端控制分句:发送一句话完整的音频后,再发送 input_audio_buffer.commit。适合客户端已知句子边界的场景,例如聊天应用中的语音消息。
使用非 VAD(Manual)模式时,建议单次会话持续发送的音频时长累加不超过 60 秒。
session.update 事件中将 session.turn_detection 设置为 null。
-
客户端发送
input_audio_buffer.append,向缓冲区追加音频。 -
客户端发送
input_audio_buffer.commit,创建新的用户消息。 -
客户端发送
session.finish结束会话。 -
服务端返回
input_audio_buffer.committed。 -
服务端返回
conversation.item.input_audio_transcription.text,包含实时转写结果。 -
服务端返回
conversation.item.input_audio_transcription.completed,包含最终转写结果。 -
识别完成后,服务端返回
session.finished,客户端须断开连接。
备选方案:使用 Qwen-Omni
您也可以使用 Qwen-Omni(qwen3-omni-flash-realtime)通过 WebSocket 进行实时语音识别。Qwen-Omni 是一个能理解音频的大语言模型——您可以通过系统提示词提供领域上下文,而无需使用热词列表。
适合使用 Omni 进行 ASR 的场景: 输入音频干净(麦克风、语音通话),且需要通过提示词处理特定领域术语。
适合使用专用 ASR 模型的场景: 音频嘈杂或混合(含背景音乐的会议、含音效的视频),或需要热词、说话人分离、时间戳等功能。
Qwen-Omni 会处理所有音频内容,而不仅仅是语音。音乐、打字声或环境噪声可能产生描述性文字而非转写结果。对于混合音频,请提前使用 VAD 隔离语音,或改用专用 ASR 模型。
Qwen-Omni-Realtime 使用 WebSocket 进行双向流式传输。完整的 API 和 SDK 参考,请参见实时对话。
常见问题
实时语音识别支持哪些音频格式?
Qwen-Audio-3.0-ASR-Flash-Streaming 和 Fun-ASR-Realtime 支持 pcm、wav、mp3、opus、speex、aac、amr 格式。Qwen3-ASR-Flash-Realtime 推荐使用 pcm 或 opus 格式;其他格式(如 wav、aac、amr)虽然在 session.update 校验层会被接受,但服务端实际解码可能失败,请务必确认音频流为推荐格式后再发送。
SDK 和 WebSocket API 有什么区别?该如何选择?
DashScope SDK 封装了 WebSocket 连接管理、鉴权、重连等细节,适合快速集成。WebSocket API 直连提供更细粒度的控制能力,适用于 SDK 未覆盖的编程语言或需要自定义连接管理的场景。推荐优先使用 SDK。
如何提升专有名词的识别准确率?
使用热词或上下文增强。详细的配置方法和使用说明,请参见提升识别准确率。
连接经常断开怎么办?
建议实现客户端重连机制,并开启心跳参数(heartbeat=true)防止长时间无音频导致连接断开。详细的容错策略请参见设置容错策略。