Qwen-Audio-ASR-Message实时语音识别Android SDK

快速开始

获取与配置 API Key
下载SDK并运行示例代码：
- 下载最新SDK整合包。
- 解压 ZIP 包。在 app/libs 目录中获取 AAR 格式 SDK，并添加到项目依赖。需要 Android CPP 接入时，使用 ZIP 包内的 android_libs 与 android_include 获取动态库和头文件。
- 用 Android Studio 打开工程。示例代码位于DashFunAsrSpeechTranscriberActivity.java，替换 API Key 后体验功能。

调用步骤

初始化 SDK
按业务需求设置参数：通过initialize接口的parameters参数设置连接与控制参数；通过setParams接口设置语音识别效果参数。
调用startDialog启动识别流程。
在onNuiAudioStateChanged回调中，根据音频状态开启录音设备。
在onNuiNeedAudioData回调中持续提供录音数据，或者通过updateAudio持续推送录音数据。
在onNuiEventCallback回调中监听事件并获取语音识别结果。
调用stopDialog停止识别，并通过监听EVENT_TRANSCRIBER_COMPLETE事件确认识别已结束。
当识别功能不再使用时，调用release接口释放 SDK 资源。

请求参数

连接与控制参数

通过在initialize接口的parameters参数中传入一个JSON字符串来配置。 **参数示例：**以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：

{
    "url": "wss://maas.qianwenaiapi.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

参数说明

参数	类型	是否必须	说明
`url`	`String`	是	服务地址，固定为 `wss://maas.qianwenaiapi.com/api-ws/v1/inference`。
`apikey`	`String`	是	API Key。
`service_mode`	`String`	是	运行模式。实时语音识别固定为 `"1"`。
`device_id`	`String`	是	用于标识终端用户的唯一字符串，可设为应用内用户ID或客户端生成的设备唯一标识符。此ID主要用于日志追踪和问题排查。
`audio_update_manually`	`String`	否	是否启用主动推送音频数据模式，默认值："false"。当设置为"true"启用主动推送音频数据模式时，且SDK版本支持端侧音频能力（如AEC、VAD），则默认开启端侧音频能力。
`workspace`	`String`	否	当参数audio_update_manually设置为"true"时，且启用端侧音频能力（如AEC、VAD）时，必须设置workspace，即端侧资源文件存储的路径。
`debug_path`	`String`	否	日志文件的存储路径。此参数仅在调用initialize接口时将`save_log`设为true时生效。此时必须设置日志文件路径，否则将报错。本地最多保留两个日志文件。
`save_wav`	`String`	否	是否保存调试用的音频文件。音频文件保存于`debug_path`下。默认值："false"。取值范围： "true"：是 "false"：否此参数仅在调用initialize接口时将`save_log`设为true时生效。同时，`debug_path`也必须被设置。
`max_log_file_size`	`int`	否	设定日志文件的最大字节数。此参数仅在调用initialize接口时将`save_log`设为true时生效。默认值：104857600（100 * 1024 * 1024 字节, 即 100MiB）。
`log_track_level`	`int`	否	控制通过日志回调（`onNuiLogTrackCallback`）对外发送的日志内容的过滤级别。默认值：2。取值范围： 0：LOG_LEVEL_VERBOSE 1：LOG_LEVEL_DEBUG 2：LOG_LEVEL_INFO 3：LOG_LEVEL_WARNING 4：LOG_LEVEL_ERROR 5：LOG_LEVEL_NONE（表示关闭此功能）注意：`log_track_level`与`level`（通过initialize接口设置）共同决定最终回调的日志。一条日志的级别数值必须同时大于或等于`log_track_level`和`level`的值，才会被回调。例如，`log_track_level`设为2 (INFO)，`level`设为3 (WARNING)，则只有WARNING及以上级别（数值>=3）的日志才会被回调。
`enable_reconnection`	`String`	否	是否开启断网续传功能，默认值："false"。
`aec_params`	`object`	否	端侧AEC能力高级参数配置对象。当参数audio_update_manually设置为"true"时才启用此配置对象。
`aec_params.enable_aec`	`boolean`	否	是否开启端侧AEC回声消除能力。当参数audio_update_manually设置为"true"时，且SDK版本支持端侧AEC音频能力，则默认开启。
`aec_params.save_audio`	`boolean`	否	是否开启端侧AEC回声消除模块音频存储功能。当`save_wav`为"true"，且设置了`debug_path`，则默认开启，将AEC运行音频数据存储到`debug_path`下。
`aec_params.enable_aec_data_callback`	`boolean`	否	是否将AEC后的数据送给用户，默认false；开启后在onNuiAssistEventCallback的EVENT_AEC_DATA接收。
`vad_params`	`object`	否	端侧VAD能力高级参数配置对象。当参数audio_update_manually设置为"true"时才启用此配置对象。
`vad_params.enable_aec`	`boolean`	否	是否开启端侧VAD人声检测能力。当参数audio_update_manually设置为"true"时，且SDK版本支持端侧VAD音频能力，则默认开启。
`vad_params.save_audio`	`boolean`	否	是否开启端侧VAD人声检测模块音频存储功能。当`save_wav`为"true"，且设置了`debug_path`，则默认开启，将VAD运行音频数据存储到`debug_path`下。

语音识别效果参数

通过在setParams接口的params参数中传入一个JSON字符串来配置。 **参数示例：**以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：

{
    "service_type": 4,
    "nls_config": {
        "model": "qwen-audio-3.1-asr-flash-message",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}

参数说明

一级参数	类型	是否必须	说明
`service_type`	`int`	是	语音服务类型。实时语音识别固定为 `4`。
`nls_config`	`object`	是	语音识别核心配置对象，包含模型选择、识别效果控制等关键参数。
`nls_config.model`	`string`	是	模型名，设置为 `qwen-audio-3.1-asr-flash-message`。
`nls_config.sr_format`	`string`	是	音频格式。取值范围： `pcm` `opus` 提示： opus：用户传入PCM格式音频，由SDK内部完成opus编码。
`nls_config.sample_rate`	`int`	是	采样率（Hz）。仅支持 `16000` Hz。
`nls_config.max_sentence_silence`	`int`	否	VAD 断句静音阈值（ms）。当一段语音后的静音时长超过该阈值时，系统会判定该句子已结束。默认值：1300。取值范围：[200, 6000]。
`nls_config.heartbeat`	`boolean`	否	是否启用心跳包。默认值：false。 true：在持续发送静音音频的情况下，可保持与服务端的连接不中断。 false（默认）：即使持续发送静音音频，连接也将在一定时间后因超时而断开。静音音频指的是在音频文件或数据流中没有声音信号的内容。静音音频可以通过多种方法生成，例如使用音频编辑软件如Audacity或Adobe Audition，或者通过命令行工具如FFmpeg。
`nls_config.disfluency_removal_enabled`	`boolean`	否	是否过滤语气词并对输出结果进行润色，默认值为 `false`。设置为 `true` 时启用。
`nls_config.intermediate_result_enabled`	`boolean`	否	是否返回流式中间结果，默认值为 `false`。设置为 `true` 时返回流式中间结果。
`nls_config.vocabulary_id`	`string`	否	预编译热词列表 ID。需预先调用创建热词列表接口生成，识别时传入该 ID 即可使用列表中的热词。适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。使用方法请参见预编译热词。
`nls_config.instant_vocabulary`	`object`	否	即时热词。以键值对形式传入，键为热词文本（`string`），值为热词权重（`integer`），无需预先创建热词列表。权重取值范围为 [1, 5] 或 50：取 [1, 5] 时值越大模型越倾向输出该词；取 50 时为超级热词，召回率大幅提升，但超级热词数量最多不超过 50 个。适用于临时性、会话级别的热词优化。与预编译热词同时配置时，系统会合并两类热词；合并后超过 2000 个时，随机选择 2000 个使用。使用方法、适用模型及限制请参见即时热词。
`nls_config.speech_noise_threshold`	`float`	否	语音与噪音的判定阈值，用于调整语音活动检测（VAD）的灵敏度。取值范围：[-1.0, 1.0]。取值说明：取值越接近 -1：降低噪音判定阈值，噪音被识别为语音的概率增大，可能导致更多噪音被转写取值越接近 +1：提高噪音判定阈值，语音被误判为噪音的概率增大，可能导致部分语音被过滤此参数为高级配置参数，调整可能显著影响识别效果，建议：调整前充分测试验证效果根据实际音频环境小幅度调整（建议步长 0.1）
`nls_config.enable_connection_fast_check`	`boolean`	否	启动快速检测网络的功能，即尽快反馈出断网情况，默认关闭。

关键接口

NativeNui

initialize

初始化语音识别SDK实例。SDK为单例模式，在调用release前禁止重复初始化。此接口会引起阻塞，应在非UI线程调用。 方法签名

public synchronized int initialize(final INativeNuiCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)

参数说明

参数	类型	说明
`callback`	`INativeNuiCallback`	事件和数据回调接口的实现。
`parameters`	`String`	JSON字符串，包含鉴权、连接和调试参数。参见连接与控制参数。
`level`	`Constants.LogLevel`	控制SDK自身日志的打印级别。
`save_log`	`boolean`	是否保存本地日志。若为`true`，须在连接与控制参数中通过`debug_path`指定路径，并可通过`max_log_file_size`设置文件大小。

setParams

以JSON格式设置语音识别效果参数。在startDialog之前调用。 方法签名

public synchronized int setParams(String params)

参数说明

参数	类型	说明
`params`	`String`	语音识别效果参数。

startDialog

开始识别。 方法签名

public synchronized int startDialog(VadMode vad_mode, String dialog_params)

参数说明

参数	类型	说明
`vad_mode`	`VadMode`	VAD模式。固定为`VadMode.TYPE_P2T`。
`dialog_params`	`String`	如果连接与控制参数的`apikey`参数使用的是临时API Key，当其过期时，可在此处进行更新。如果需要通过上下文增强来提升识别准确率，则在此处进行更新。内容为JSON格式：示例 1 请参见表格下方

示例 1（说明）：

{
  "apikey": "st-****",
  "input_context": [
    {
      "role": "user",
      "content": [
        {
          "text": "xxxxx",
          "type": "input_text"
        }
      ]
    }
  ]
}

stopDialog

结束识别，调用该接口后，服务端将返回最终识别结果并结束任务。 方法签名

public synchronized int stopDialog();

cancelDialog

立即结束识别，调用该接口后，不等待服务端返回最终识别结果就立即结束任务。 方法签名

public synchronized int cancelDialog();

updateAction

在交互过程中下发对话动作指令，用于更新识别上下文等运行时行为。 方法签名

public synchronized int updateAction(String params);

参数说明

参数	类型	说明
`params`	`String`	JSON形式的字符串，用于更新识别上下文等运行时行为。
`params.type`	`String`	固定"action"。
`params.command`	`String`	具体的运行指令，当前支持"context"、"play_start"、"play_over"。 - `context`：即时更新上下文增强来提升识别准确率。 `play_start`：当使用端侧AEC时，通过此指令通知SDK内部AEC播放器开始播放音频。 `play_over`：当使用端侧AEC时，通过此指令通知SDK内部AEC播放器已经播放结束。
`params.context`	`String`	当`command`为`"context"`时，即时更新上下文增强来提升识别准确率。参数值是JSON格式的字符串，示例如下。

{
  "context": [
    {
      "role": "user",
      "content": [
        {
          "text": "xxx",
          "type": "input_text"
        }
      ]
    }
  ]
}

updateAudio

参数audio_update_manually设置为"true"时，录音数据不再是通过onNuiNeedAudioData填入，而是用此接口主动推送。 方法签名

public synchronized int updateAudio(byte[] data, int len,
                                    boolean first_pack);

参数说明

参数	类型	说明
`data`	`byte[]`	推送的音频数据。
`len`	`int`	推送的音频数据的字节数。
`first_pack`	`boolean`	请忽略，无需关注此参数。

updateRefAudio

参数audio_update_manually设置为"true"时，且启用了端侧AEC回声消除能力，则需要用此接口推送播放器播放的音频数据作为参考信号。 方法签名

public synchronized int updateRefAudio(byte[] data, int len,
                                       boolean first_pack);

参数说明

参数	类型	说明
`data`	`byte[]`	推送的音频数据。
`len`	`int`	推送的音频数据的字节数。
`first_pack`	`boolean`	请忽略，无需关注此参数。

release

释放SDK所有内部资源。此方法调用后，SDK实例将变为不可用状态，如需再次使用，必须重新调用initialize进行初始化。 方法签名

public synchronized int release();

GetVersion

获得当前SDK版本信息。 方法签名

public synchronized String GetVersion();

返回值说明 当前SDK版本信息。

INativeNuiCallback：监听回调

onNuiEventCallback：监听事件和语音识别结果

方法签名

void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);

参数说明

参数	类型	说明
`event`	`NuiEvent`	回调事件。
`resultCode`	`int`	仅在出现 `EVENT_ASR_ERROR` 事件时有效。
`arg2`	`int`	保留参数。
`asrResult`	`AsrResult`	语音识别结果。
`kwsResult`	`KwsResult`	语音唤醒功能。无需关注该参数。

onNuiAudioStateChanged：监听音频状态

SDK 通过此回调通知何时应该开始或停止录音。 方法签名

void onNuiAudioStateChanged(AudioState state);

AudioState状态说明

状态	说明
`STATE_OPEN`	交互启动，可以打开录音设备进行录音。
`STATE_PAUSE`	交互停止，可以停止录音。
`STATE_CLOSE`	SDK 实例已释放，可以彻底关闭录音设备。

onNuiNeedAudioData：填充待识别音频数据

开始识别后，该回调被连续触发，需在其中提供待识别音频数据。 方法签名

int onNuiNeedAudioData(byte[] buffer, int len);

参数说明

参数	类型	说明
`buffer`	`byte[]`	填充的音频数据。
`len`	`int`	填充的音频数据的字节数。

返回值说明 实际填充的字节数。

onNuiAssistEventCallback：辅助数据和信息结果

此回调用于接收 SDK 内部的辅助事件和相关数据。 方法签名

void onNuiAssistEventCallback_(int event, byte[] info, int info_len,
                               byte[] data);

参数说明

参数	类型	说明
`event`	`int`	`NuiEvent`事件
`info`	`String`	无需关注该参数。
`info_len`	`int`	无需关注该参数。
`data`	`byte[]`	辅助数据，比如AEC回声消除后的音频数据。

onNuiLogTrackCallback：监听追踪日志

此回调用于接收 SDK 内部的详细日志，方便进行问题定位和调试。

default void onNuiLogTrackCallback(Constants.LogLevel level, String log)

`NuiEvent`：事件类型

事件	说明
EVENT_TRANSCRIBER_STARTED	任务启动成功。
EVENT_VAD_START	任务启动后即触发该事件。不代表检测到人声起点。
EVENT_VAD_END	检测到人声终点。
EVENT_ASR_PARTIAL_RESULT	语音识别中间结果。
EVENT_ASR_WARN	语音识别过程中出现不影响运行的警告，比如开启断网续传后的断网事件。
EVENT_ASR_ERROR	语音识别过程中出现错误。
EVENT_MIC_ERROR	因连续2秒未收到任何音频数据而触发。
EVENT_SENTENCE_END	检测到一句话结束，此时会返回一句完整的识别结果。
EVENT_TRANSCRIBER_COMPLETE	语音识别结束。
EVENT_AEC_DATA	AEC回声消除后的音频数据。

​快速开始

​调用步骤

​请求参数

​连接与控制参数

​语音识别效果参数

​关键接口

​NativeNui

​initialize

​setParams

​startDialog

​stopDialog

​cancelDialog

​updateAction

​updateAudio

​updateRefAudio

​release

​GetVersion

​INativeNuiCallback：监听回调

​onNuiEventCallback：监听事件和语音识别结果

​onNuiAudioStateChanged：监听音频状态

​onNuiNeedAudioData：填充待识别音频数据

​onNuiAssistEventCallback：辅助数据和信息结果

​onNuiLogTrackCallback：监听追踪日志

​NuiEvent：事件类型

快速开始

调用步骤

请求参数

连接与控制参数

语音识别效果参数

关键接口

NativeNui

initialize

setParams

startDialog

stopDialog

cancelDialog

updateAction

updateAudio

updateRefAudio

release

GetVersion

INativeNuiCallback：监听回调

onNuiEventCallback：监听事件和语音识别结果

onNuiAudioStateChanged：监听音频状态

onNuiNeedAudioData：填充待识别音频数据

onNuiAssistEventCallback：辅助数据和信息结果

onNuiLogTrackCallback：监听追踪日志

`NuiEvent`：事件类型