使用 DashScope Java SDK 调用 Qwen-Audio-ASR-Streaming、Qwen-Audio-ASR-Message 和 Fun-ASR-Realtime。
使用 DashScope Java SDK 识别本地音频文件或麦克风输入。本文覆盖 Qwen-Audio-ASR-Streaming、Qwen-Audio-ASR-Message 和 Fun-ASR-Realtime。
SDK的接口地址需在初始化前设置为下方地址(包含WorkspaceId)。如需切换到其他地域,请修改
以下代码可共用。示例默认使用 Qwen-Audio-ASR-Streaming。调用其他模型时,按下表替换
如需指定识别语言,请按对应模型的请求参数配置
在DashScope Java SDK中,采用了OkHttp3的连接池技术,以减少重复建立连接的开销。详情请参见高并发最佳实践。
通过
通过
通过
这两个系列共用以下会话、回调和识别结果接口。各模型支持的字段以本页「请求参数」为准。
双向流式调用时,服务端会通过回调的方式,将关键流程信息和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。
回调方法的实现,通过继承抽象类
双向流式调用时,服务端会通过回调的方式,将关键流程信息和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。
回调方法的实现,通过继承抽象类
如遇报错问题,请参见错误码进行排查。
若问题仍未解决,可加入语音 SDK 示例仓库中列出的开发者群反馈问题,并提供Request ID,以便进一步排查问题。
前提条件
- 已开通服务并获取与配置 API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
- 安装最新版DashScope SDK。
接口地址
SDK的接口地址需在初始化前设置为下方地址(包含WorkspaceId)。如需切换到其他地域,请修改 Constants.baseWebsocketApiUrl为对应地域的URL。
- 华北2(北京)
- 新加坡
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference调用时请将{WorkspaceId}替换为真实的Workspace ID。快速开始
以下代码可共用。示例默认使用 Qwen-Audio-ASR-Streaming。调用其他模型时,按下表替换 model。
| 模型 | model 的值 |
|---|---|
| Qwen-Audio-ASR-Streaming | 非流式调用和基于回调的本地文件示例使用 qwen-audio-3.1-asr-flash-streaming。麦克风和 Flowable 示例使用 qwen-audio-3.0-asr-flash-streaming。 |
| Qwen-Audio-ASR-Message | qwen-audio-3.1-asr-flash-message |
| Fun-ASR-Realtime | fun-asr-realtime |
language_hints。
Recognition提供了非流式调用和双向流式调用等接口。请根据实际需求选择合适的调用方式:
- 非流式调用:针对本地文件进行识别,并一次性返回完整的处理结果。适合处理录制好的音频。
- 双向流式调用:可直接对音频流进行识别,并实时输出结果。音频流可以来自外部设备(如麦克风)或从本地文件读取。适合需要即时反馈的场景。
- 非流式调用
- 双向流式调用:基于回调
- 双向流式调用:基于Flowable
提交单个语音实时转写任务,通过传入本地文件的方式同步阻塞地拿到转写结果。将示例中的
{YOUR_AUDIO_FILE} 替换为本地 WAV 文件的路径。运行后,程序会在终端打印完整的识别结果。高并发调用
在DashScope Java SDK中,采用了OkHttp3的连接池技术,以减少重复建立连接的开销。详情请参见高并发最佳实践。
请求参数
Qwen-Audio-ASR-Streaming
通过RecognitionParam的链式方法配置模型、采样率、音频格式等参数。配置完成的参数对象传入Recognition类的call/streamCall方法中使用。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | String | 是 | 模型名称。 |
sampleRate | Integer | 是 | 采样率(Hz),支持任意采样率。 |
format | String | 是 | 音频格式。取值范围:
|
keep_dialect | boolean | 否 | 仅 qwen-audio-3.1-asr-flash-streaming 支持。默认 false,将方言转写为普通话;设为 true 时保留方言表达。通过 .parameter("keep_dialect", value) 设置。完整参数说明请参见客户端事件。 |
vad_model | String | 否 | 仅 qwen-audio-3.1-asr-flash-streaming 支持。可选 near_meeting_16k(近场)或 far_field_meeting_16k(远场,默认值)。通过 .parameter("vad_model", value) 设置。完整参数说明请参见客户端事件。 |
vocabularyId | String | 否 | 预编译热词列表 ID。需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。使用方法请参见预编译热词。 |
vocabulary | Map<String, Integer> | 否 | 即时热词。以键值对形式传入,键为热词文本(string),值为热词权重(integer),无需预先创建热词列表。权重取值范围为 [1, 5] 或 50:取 [1, 5] 时值越大模型越倾向输出该词;取 50 时为超级热词,召回率大幅提升,但超级热词数量最多不超过 50 个。适用于临时性、会话级别的热词优化。与预编译热词同时配置时,系统会合并两类热词;合并后超过 2000 个时,随机选择 2000 个使用。使用方法请参见即时热词。vocabulary需要通过 RecognitionParam 实例的 parameter 方法或者 parameters 方法进行设置: |
max_sentence_silence | Integer | 否 | VAD 断句静音阈值(ms)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。默认值:800。取值范围:[200, 6000]。max_sentence_silence需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
multi_threshold_mode_enabled | boolean | 否 | 是否启用多阈值模式。启用后可防止 VAD 断句切割过长。默认值:false。multi_threshold_mode_enabled需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
punctuation_prediction_enabled | boolean | 否 | 设置是否在识别结果中自动添加标点:
punctuation_prediction_enabled需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
heartbeat | boolean | 否 | 是否启用心跳包。默认值:false。
使用该字段时,SDK版本不能低于2.19.1。 heartbeat需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
language_hints | String[] | 否 | 待识别音频语种。无默认值,不设置时模型自动识别。最多支持设置 4 个值,超出时仅前 4 个生效。
点击查看支持的语言代码
language_hints需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
speech_noise_threshold | float | 否 | 语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。取值范围:[-1.0, 1.0]。取值说明:
speech_noise_threshold需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
special_word_filter | String | 否 | 指定在语音识别过程中需要处理的敏感词,并支持对不同敏感词设置不同的处理方式。详情请参见敏感词过滤。special_word_filter需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
input | Map<String, Object> | 否 | 输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见提升识别准确率。Map 中需包含 context 键,值为 List<Map<String, Object>> 类型的消息数组,每条消息包含以下字段:
使用该字段时,SDK版本不能低于2.22.23。 input通过RecognitionParam实例的input方法进行设置: |
apiKey | String | 否 | 用户API Key。 |
Qwen-Audio-ASR-Message
通过RecognitionParam的链式方法配置模型、采样率、音频格式等参数。配置完成的参数对象传入Recognition类的call/streamCall方法中使用。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | String | 是 | 模型名,设置为 qwen-audio-3.1-asr-flash-message。 |
sampleRate | Integer | 是 | 采样率(Hz)。 仅支持16000 Hz。 |
format | String | 是 | 音频格式。 取值范围:
|
disfluency_removal_enabled | boolean | 否 | 是否过滤语气词并对输出结果进行润色,默认值为 false。设置为 true 时启用。 通过 .parameter("disfluency_removal_enabled", value) 设置。 |
intermediate_result_enabled | boolean | 否 | 是否返回流式中间结果,默认值为 false。设置为 true 时返回流式中间结果。 通过 .parameter("intermediate_result_enabled", value) 设置。 |
keep_dialect | boolean | 否 | 默认 false,将方言转写为普通话;设为 true 时保留方言表达。通过 .parameter("keep_dialect", value) 设置。完整参数说明请参见客户端事件。仅在最终结果(sentence_end=true)生效,中间结果(sentence_end=false)不支持。 |
vad_model | String | 否 | 可选 near_meeting_16k(近场)或 far_field_meeting_16k(远场,默认值)。通过 .parameter("vad_model", value) 设置。完整参数说明请参见客户端事件。 |
vocabularyId | String | 否 | 预编译热词列表 ID。 需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。使用方法请参见预编译热词。 |
vocabulary | Map<String, Integer> | 否 | 即时热词。 以键值对形式传入,键为热词文本(string),值为热词权重(integer),无需预先创建热词列表。权重取值范围为 [1, 5] 或 50:取 [1, 5] 时值越大模型越倾向输出该词;取 50 时为超级热词,召回率大幅提升,但超级热词数量最多不超过 50 个。适用于临时性、会话级别的热词优化。与预编译热词同时配置时,系统会合并两类热词;合并后超过 2000 个时,随机选择 2000 个使用。使用方法请参见即时热词。vocabulary需要通过 RecognitionParam 实例的 parameter 方法或者 parameters 方法进行设置: |
language_hints | String[] | 否 | 待识别音频语种。无默认值,不设置时模型自动识别。最多支持设置 4 个值,超出时仅前 4 个生效。
点击查看支持的语言代码
RecognitionParam 的 .parameter("language_hints", new String[]{"zh"}) 设置。仅在最终结果(sentence_end=true)生效,中间结果(sentence_end=false)不支持。 |
max_sentence_silence | Integer | 否 | VAD 断句静音阈值(ms)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。 默认值:800。取值范围:[200, 6000]。max_sentence_silence需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
heartbeat | boolean | 否 | 是否启用心跳包。 默认值:false。
使用该字段时,SDK版本不能低于2.19.1。 heartbeat需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
speech_noise_threshold | float | 否 | 语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。 取值范围:[-1.0, 1.0]。取值说明:
speech_noise_threshold需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
input | Map<String, Object> | 否 | 输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见提升识别准确率。 Map 中需包含context 键,值为 List<Map<String, Object>> 类型的消息数组,每条消息包含以下字段:
使用该字段时,SDK版本不能低于2.22.23。 input通过RecognitionParam实例的input方法进行设置: |
apiKey | String | 否 | 用户API Key。 |
Fun-ASR-Realtime
通过RecognitionParam的链式方法配置模型、采样率、音频格式等参数。配置完成的参数对象传入Recognition类的call/streamCall方法中使用。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | String | 是 | 模型名称。 |
sampleRate | Integer | 是 | 采样率(Hz)。取值范围:8k模型仅支持 8000 Hz,其他模型支持任意采样率。 |
format | String | 是 | 音频格式。取值范围:
|
vocabularyId | String | 否 | 预编译热词列表 ID。需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。使用方法请参见预编译热词。 |
max_sentence_silence | Integer | 否 | VAD 断句静音阈值(ms)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。默认值:1300。取值范围:[200, 6000]。max_sentence_silence需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
multi_threshold_mode_enabled | boolean | 否 | 是否启用多阈值模式。启用后可防止 VAD 断句切割过长。默认值:false。multi_threshold_mode_enabled需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
punctuation_prediction_enabled | boolean | 否 | 设置是否在识别结果中自动添加标点:
punctuation_prediction_enabled需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
heartbeat | boolean | 否 | 是否启用心跳包。默认值:false。
使用该字段时,SDK版本不能低于2.19.1。 heartbeat需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
language_hints | String[] | 否 | 待识别音频语种。无默认值,不设置时模型自动识别。仅支持设置 1 个值,设置多个时仅第一个生效。
点击查看支持的语言代码
language_hints需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
speech_noise_threshold | float | 否 | 语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。取值范围:[-1.0, 1.0]。取值说明:
speech_noise_threshold需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
special_word_filter | String | 否 | 指定在语音识别过程中需要处理的敏感词,并支持对不同敏感词设置不同的处理方式。详情请参见敏感词过滤。special_word_filter需要通过RecognitionParam实例的parameter方法或者parameters方法进行设置: |
input | Map<String, Object> | 否 | 输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见提升识别准确率。Map 中需包含 context 键,值为 List<Map<String, Object>> 类型的消息数组,每条消息包含以下字段:
使用该字段时,SDK版本不能低于2.22.23。 input通过RecognitionParam实例的input方法进行设置: |
apiKey | String | 否 | 用户API Key。 |
接口参考
Qwen-Audio-ASR-Streaming 与 Fun-ASR-Realtime
这两个系列共用以下会话、回调和识别结果接口。各模型支持的字段以本页「请求参数」为准。
Recognition类
Recognition通过import com.alibaba.dashscope.audio.asr.recognition.Recognition;方式引入。它的关键接口如下:
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | 基于回调形式的流式实时识别,该方法不会阻塞当前线程。 | |
| 识别结果 | 基于本地文件的非流式调用,该方法会阻塞当前线程直到全部音频读完,该方法要求所识别文件具有可读权限。 | |
| Flowable<RecognitionResult> | 基于Flowable的流式实时识别。 | |
| 无 | 推送音频,每次推送的音频流不宜过大或过小,建议每包音频时长为100ms左右,大小在1KB~16KB之间。识别结果通过回调接口(ResultCallback)的onEvent方法获取。 | |
| 无 | 无 | 停止实时识别。该方法会阻塞当前线程,直到回调实例ResultCallback的onComplete或者onError被调用之后才会解除对当前线程的阻塞。 | |
| code: WebSocket关闭码(Close Code)reason:关闭原因这两个参数可参考The WebSocket Protocol文档进行配置 | true | 在任务结束后,无论是否出现异常都需要关闭WebSocket连接,避免造成连接泄漏。关于如何复用连接提升效率请参考高并发最佳实践。 | |
| 无 | requestId | 获取当前任务的requestId,在调用call、streamingCall开始新任务之后可以使用。该方法自2.18.0版本及以后的SDK中才开始提供。 | |
| 无 | 首包延迟 | 获取首包延迟,从发送第一包音频到收到首包识别结果延迟,在任务完成后使用。 该方法自2.18.0版本及以后的SDK中才开始提供。 | |
| 无 | 尾包延迟 | 获得尾包延迟,发送stop指令到最后一包识别结果下发耗时,在任务完成后使用。该方法自2.18.0版本及以后的SDK中才开始提供。 |
回调接口(ResultCallback)
双向流式调用时,服务端会通过回调的方式,将关键流程信息和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。
回调方法的实现,通过继承抽象类ResultCallback完成,继承该抽象类时,您可以指定泛型为RecognitionResult。RecognitionResult封装了服务器返回的数据结构。
由于Java支持连接复用,因此没有onClose和onOpen。
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
result:实时识别结果(RecognitionResult) | 无 | 当服务有回复时会被回调。 | |
| 无 | 无 | 任务完成后该接口被回调。 | |
e:异常信息 | 无 | 发生异常时该接口被回调。 |
实时识别结果(RecognitionResult)
RecognitionResult代表一次实时识别的结果。
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | requestId | 获取requestId。 | |
| 无 | 是否是完整句子,即产生断句 | 判断给定句子是否已经结束。 | |
| 无 | 单句信息(Sentence) | 获取单句信息,包括时间戳和文本信息等。 |
单句信息(Sentence)
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | 句子开始时间,单位为ms | 返回句子开始时间。 | |
| 无 | 句子结束时间,单位为ms | 返回句子结束时间。 | |
| 无 | 识别文本 | 返回识别文本。 | |
| 无 | 字时间戳信息(Word)的List集合 | 返回字时间戳信息。 |
字时间戳信息(Word)
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | 字开始时间,单位为ms | 返回字开始时间。 | |
| 无 | 字结束时间,单位为ms | 返回字结束时间。 | |
| 无 | 字 | 返回识别的字。 | |
| 无 | 标点 | 返回标点。 |
Qwen-Audio-ASR-Message 的接口
Recognition类
Recognition通过import com.alibaba.dashscope.audio.asr.recognition.Recognition;方式引入。它的关键接口如下:
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | 基于回调形式的流式实时识别,该方法不会阻塞当前线程。 | |
| 识别结果 | 基于本地文件的非流式调用,该方法会阻塞当前线程直到全部音频读完,该方法要求所识别文件具有可读权限。 | |
| Flowable<RecognitionResult> | 基于Flowable的流式实时识别。 | |
| 无 | 推送音频,每次推送的音频流不宜过大或过小,建议每包音频时长为100ms左右,大小在1KB~16KB之间。 识别结果通过回调接口(ResultCallback)的onEvent方法获取。 | |
| 无 | 无 | 停止实时识别。 该方法会阻塞当前线程,直到回调实例ResultCallback的onComplete或者onError被调用之后才会解除对当前线程的阻塞。 | |
code: WebSocket关闭码(Close Code) reason:关闭原因这两个参数可参考The WebSocket Protocol文档进行配置 | true | 在任务结束后,无论是否出现异常都需要关闭WebSocket连接,避免造成连接泄漏。关于如何复用连接提升效率请参考高并发最佳实践。 | |
| 无 | requestId | 获取当前任务的requestId,在调用 该方法自2.18.0版本及以后的SDK中才开始提供。 | |
| 无 | 首包延迟 | 获取首包延迟,从发送第一包音频到收到首包识别结果延迟,在任务完成后使用。 该方法自2.18.0版本及以后的SDK中才开始提供。 | |
| 无 | 尾包延迟 | 获得尾包延迟,发送 该方法自2.18.0版本及以后的SDK中才开始提供。 |
更新对话上下文
调用updateContext 在识别任务运行过程中更新对话上下文,用于辅助后续音频的识别。该方法要求 DashScope Java SDK 2.23.0 及以上版本。
- 调用时机:调用
call(param, callback)启动流式识别后、调用stop前。 - 参数:
payloadInput为Map<String, Object>,传入continue-task事件的payload.input对象,包含context字段,不要额外包装payload或input层级。 - 支持范围与参数约束:请参见 continue-task。
recognizer 实例,Java 集合类型通过 import java.util.*; 导入。
回调接口(ResultCallback)
双向流式调用时,服务端会通过回调的方式,将关键流程信息和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。
回调方法的实现,通过继承抽象类ResultCallback完成,继承该抽象类时,您可以指定泛型为RecognitionResult。RecognitionResult封装了服务器返回的数据结构。
由于Java支持连接复用,因此没有onClose和onOpen。
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
result:实时识别结果(RecognitionResult) | 无 | 当服务有回复时会被回调。 | |
| 无 | 无 | 任务完成后该接口被回调。 | |
e:异常信息 | 无 | 发生异常时该接口被回调。 |
实时识别结果(RecognitionResult)
RecognitionResult代表一次实时识别的结果。
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | requestId | 获取requestId。 | |
| 无 | 是否是完整句子,即产生断句 | 判断给定句子是否已经结束。 | |
| 无 | 单句信息(Sentence) | 获取单句信息,包括时间戳和文本信息等。 |
单句信息(Sentence)
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | 句子开始时间,单位为ms | 返回句子开始时间。 | |
| 无 | 句子结束时间,单位为ms | 返回句子结束时间。 | |
| 无 | 识别文本 | 返回识别文本。 | |
| 无 | 字时间戳信息(Word)的List集合 | 返回字时间戳信息。 |
字时间戳信息(Word)
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | 字开始时间,单位为ms | 返回字开始时间。 | |
| 无 | 字结束时间,单位为ms | 返回字结束时间。 | |
| 无 | 字 | 返回识别的字。 | |
| 无 | 标点 | 返回标点。 |