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

url

String

是

服务地址：

• wss://dashscope.aliyuncs.com/api-ws/v1/inference

• 华北2（北京）：wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference

• 新加坡：wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference

调用时，请将 {WorkspaceId} 替换为真实的 Workspace ID。

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）时，必须设置此参数。

debug_path

String

否

日志文件的存储路径。

此参数仅在调用nui_initialize接口时将save_log设为YES时生效。此时必须设置日志文件路径，否则将报错。

本地最多保留两个日志文件。

save_wav

String

否

是否保存调试用的音频文件。音频文件保存于debug_path下。

默认值："false"。

取值范围：

• "true"：是

• "false"：否

此参数仅在调用nui_initialize接口时将save_log设为true时生效。 同时，debug_path也必须被设置。

max_log_file_size

int

否

设定日志文件的最大字节数。

此参数仅在调用nui_initialize接口时将save_log设为YES时生效。

默认值：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（通过nui_initialize接口设置）共同决定最终回调的日志。一条日志的级别数值必须同时大于或等于log_track_level和level的值，才会被回调。例如，log_track_level设为2 (INFO)，level设为3 (WARNING)，则只有WARNING及以上级别（数值>=3）的日志才会被回调。

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

nls_config.sample_rate

int

是

采样率（Hz）。

仅支持 16000 Hz。

nls_config.language_hints

array[string]

否

待识别音频语种。无默认值，不设置时模型自动识别。

最多支持设置 4 个值，超出时仅前 4 个生效。

仅在最终结果（sentence_end=true）生效，中间结果（sentence_end=false）不支持。

nls_config.keep_dialect

boolean

否

是否保留方言表达，默认值为 false。false：将方言转写为普通话文本；true：保留方言表达。

nls_config.vad_model

string

否

VAD 模型，默认值为 far_field_meeting_16k。

• near_meeting_16k：近场场景。
• far_field_meeting_16k：远场场景。

nls_config.max_sentence_silence

int

否

VAD 断句静音阈值（ms）。当一段语音后的静音时长超过该阈值时，系统会判定该句子已结束。

默认值：800。

取值范围：[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

BOOL

否

是否启用快速网络检测，以便尽快反馈断网情况。默认值：NO。

parameters

char*

JSON字符串，包含鉴权、连接和调试参数。参见连接与控制参数。

level

NuiSdkLogLevel

控制SDK自身日志的打印级别。

save_log

BOOL

是否保存本地日志。若为YES，须在连接与控制参数通过debug_path指定路径，并可通过max_log_file_size设置文件大小。

params

char*

语音识别效果参数。

vad_mode

NuiVadMode

VAD模式。固定为MODE_P2T。

dialog_params

char*

如果连接与控制参数的apikey参数使用的是临时API Key，当其过期时，可在此处更新。如果需要通过上下文增强来提升识别准确率，也可在此处传入上下文。

内容为JSON格式：

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

force

BOOL

是否强制结束而忽略最终结果。

• YES：不等待服务端返回最终识别结果就立即结束任务。

• NO：结束任务，但是会等待完整结果返回。

action_params

char*

JSON 字符串，用于更新识别上下文等运行时行为。

action_params.type

String

固定为 "action"。

action_params.command

String

运行指令。支持以下取值：

• context：即时更新上下文增强，以提升识别准确率。

• play_start：使用端侧 AEC 时，通知 SDK 内部 AEC 播放器开始播放音频。

• play_over：使用端侧 AEC 时，通知 SDK 内部 AEC 播放器已经播放结束。

action_params.context

String

当 command 为 "context" 时，用于即时更新上下文增强。示例：

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

data

const char *

推送的音频数据。

length

int

推送的音频数据的字节数。

first_pack

BOOL

无需关注此参数。

data

const char *

推送的音频数据。

length

int

推送的音频数据的字节数。

first_pack

BOOL

无需关注此参数。

nuiEvent

NuiCallbackEvent

回调事件。

dialog

long

会话编码，无需关注该参数。

wuw

char*

语音唤醒功能。无需关注该参数。

asr_result

char*

语音识别结果。

finish

BOOL

本轮识别是否结束标志。

code

int

仅在出现 EVENT_ASR_ERROR 事件时有效。

STATE_OPEN

交互启动，可以打开录音设备进行录音。

STATE_PAUSE

交互停止，可以停止录音。

STATE_CLOSE

SDK 实例已释放，可以彻底关闭录音设备。

audioData

char *

填充的音频数据。

len

int

填充的音频数据的字节数。

nuiEvent

NuiCallbackEvent

回调事件。

info

char *

无需关注此参数。

info_len

int

无需关注此参数。

buffer

char *

辅助数据，例如 AEC 回声消除后的音频数据。

len

int

辅助数据的字节数。

EVENT_TRANSCRIBER_STARTED

任务启动成功。

EVENT_VAD_START

任务启动后即触发该事件。不代表检测到人声起点。

EVENT_VAD_END

检测到人声终点。

EVENT_ASR_PARTIAL_RESULT

语音识别中间结果。

EVENT_ASR_ERROR

语音识别过程中出现错误。

EVENT_MIC_ERROR

因连续2秒未收到任何音频数据而触发。

EVENT_SENTENCE_END

检测到一句话结束，此时会返回一句完整的识别结果。

EVENT_TRANSCRIBER_COMPLETE

语音识别结束。

EVENT_AEC_DATA

AEC 回声消除后的音频数据。