本文档介绍如何使用 DashScope Java SDK 调用实时语音识别(Qwen-ASR-Realtime)模型。
前提条件
- 安装SDK,确保DashScope SDK版本不低于2.22.5。
- 获取与配置 API Key。
- 了解WebSocket API。
完整示例
示例代码读取
your_audio_file.pcm(PCM16、16 kHz、单声道)。如仅有 MP3/WAV 等格式,可使用 ffmpeg 转换:Java
请求参数
- 以下参数通过
OmniRealtimeParam的链式方法设置。
点击查看示例代码
点击查看示例代码
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | String | 是 | 指定要使用的模型名称。 |
url | String | 是 | 语音识别服务地址,固定为 wss://maas.qianwenaiapi.com/api-ws/v1/realtime。 |
apikey | String | 否 | 设置API Key。 |
- 以下参数通过
OmniRealtimeConfig的链式方法设置。
点击查看示例代码
点击查看示例代码
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
modalities | List<OmniRealtimeModality> | 是 | 模型输出模态,固定为[OmniRealtimeModality.TEXT]。 |
enableTurnDetection | boolean | 否 | 是否开启服务端语音活动检测(VAD)。关闭后,需手动调用commit()方法触发识别。默认值: true。取值范围:
|
turnDetectionType | String | 否 | 服务端VAD类型,固定为 server_vad。 |
turnDetectionThreshold | float | 否 | VAD检测阈值。推荐将该值设为0.0。默认值: 0.5。取值范围: [-1, 1]。较低的阈值会提高 VAD 的灵敏度,可能将背景噪音误判为语音。较高的阈值则降低灵敏度,有助于在嘈杂环境中减少误触发。 |
turnDetectionSilenceDurationMs | int | 否 | VAD断句检测阈值(ms)。静音持续时长超过该阈值将被认为是语句结束。推荐将该值设为400。默认值: 800。取值范围: [200, 6000]。较低的值(如 300ms)可使模型更快响应,但可能导致在自然停顿处发生不合理的断句。较高的值(如 1200ms)可更好地处理长句内的停顿,但会增加整体响应延迟。 |
transcriptionConfig | OmniRealtimeTranscriptionParam | 否 | 语音识别相关配置。 |
- 以下参数通过
OmniRealtimeTranscriptionParam的setter方法设置。
点击查看示例代码
点击查看示例代码
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
language | String | 否 | 音频源语言。
|
inputSampleRate | int | 否 | 音频采样率(Hz)。支持16000和8000。默认值: 16000。设置为 8000 时,服务端会先升采样到16000Hz再进行识别,可能引入微小延迟。建议仅在源音频为8000Hz(如电话线路)时使用。 |
inputAudioFormat | String | 否 | 音频格式。支持pcm和opus。默认值: pcm。 |
关键接口
OmniRealtimeConversation类
OmniRealtimeConversation通过import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;方法引入。
| 方法签名 | 服务端响应事件(通过回调下发) | 说明 |
|---|---|---|
| 示例 1 请参见表格下方 | 无 | 构造方法。 |
| 示例 2 请参见表格下方 | session.created > 会话已创建 session.updated > 会话配置已更新 | 和服务端创建连接。 |
| 示例 3 请参见表格下方 | session.updated > 会话配置已更新 | 用于更新会话配置,建议在连接建立后首先调用该方法进行设置。若未调用该方法,系统将使用默认配置。只需关注请求参数中的涉及到的参数。 |
| 示例 4 请参见表格下方 | 无 | 将Base64编码后的音频数据片段追加到云端输入音频缓冲区。 |
| 示例 5 请参见表格下方 | input_audio_buffer.committed > 服务端收到提交的音频 | 提交之前通过append添加到云端缓冲区的音视频,如果输入的音频缓冲区为空将产生错误。 禁用场景:请求参数enableTurnDetection设为true时。 |
| 示例 6 请参见表格下方 | session.finished > 服务端完成语音识别,结束会话 | 通知服务端结束会话,服务端收到会话结束通知后将完成最后的语音识别。 调用时机:
endSessionAsync 是 endSession 的异步版本,两者功能完全相同。 |
| 示例 7 请参见表格下方 | 无 | 终止任务,并关闭连接。 |
| 示例 8 请参见表格下方 | 无 | 获取当前任务的session_id。 |
| 示例 9 请参见表格下方 | 无 | 获取最近一次response的response_id。 |
回调接口(OmniRealtimeCallback)
服务端会通过回调的方式,将服务端响应事件和数据返回给客户端。
继承此类并实现相应方法以处理服务端事件。
通过import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback;引入。
| 方法签名 | 参数 | 说明 |
|---|---|---|
| 示例 1 请参见表格下方 | 无 | WebSocket连接成功建立时触发。 |
| 示例 2 请参见表格下方 | message:服务端事件 | 收到服务端事件时触发。 |
| 示例 3 请参见表格下方 | code:状态码 reason:WebSocket连接关闭时的日志信息 | WebSocket连接关闭时触发。 |