Alibaba Cloud Model Studio：Qwen-Audio-ASR-Message iOS SDK

本文檔提供了Qwen-Audio-3.1-ASR-Flash-Message實時語音識別iOS SDK的詳細使用指南，幫助您將語音轉換為文本。

快速開始

1. 獲取API Key：獲取與配置 API Key

2. 下載SDK並運行示例代碼：
   • 下載最新SDK整合包。
   • 解壓 ZIP 包，將其中的 nuisdk.xcframework 添加到工程。
   • 在 Build Phases → Link Binary With Libraries 中添加 nuisdk.xcframework。
   • 在 General → Frameworks, Libraries, and Embedded Content 中將 nuisdk.xcframework 設置為 Embed & Sign。
   • 用 Xcode 打開示例工程。示例代碼位於DashFunAsrSpeechTranscriberViewController.m，替換 API Key 後體驗功能。

調用步驟

1. 初始化 SDK
2. 按業務需求設置參數：通過nui_initialize接口設置連接與控制參數；通過nui_set_params接口設置語音識別效果參數。
3. 調用nui_dialog_start啓動識別流程。
4. 在onNuiAudioStateChanged回調中，根據音頻狀態開啓錄音設備。
5. 在onNuiNeedAudioData回調中持續提供錄音數據，或者通過nui_update_audio_data持續推送錄音數據。
6. 在onNuiEventCallback回調中監聽事件並獲取語音識別結果。
7. 調用nui_dialog_cancel停止識別，並通過監聽EVENT_TRANSCRIBER_COMPLETE事件確認識別已結束。
8. 當識別功能不再使用時，調用nui_release接口釋放 SDK 資源。

請求參數

連接與控制參數

通過在nui_initialize接口的parameters參數中傳入一個JSON字符串來配置。

參數示例：以下為 JSON 字符串示例，參數未完整列出。請按實際需求在編碼時補充：

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

語音識別效果參數

通過在nui_set_params接口的params參數中傳入一個JSON字符串來配置。

參數示例：以下為 JSON 字符串示例，參數未完整列出。請按實際需求在編碼時補充：

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

關鍵接口

NeoNui

nui_initialize

初始化語音識別SDK實例。SDK為單例模式，在調用 nui_release 前禁止重復初始化。

-(NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;

返回錯誤碼，參見錯誤碼查詢。

nui_set_params

以JSON格式設置語音識別效果參數。在 nui_dialog_start 之前調用。

-(NuiResultCode) nui_set_params:(const char *)params;

返回錯誤碼，參見錯誤碼查詢。

nui_dialog_start

開始識別。

-(NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
                      dialogParam:(const char *)dialog_params;

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

返回錯誤碼，參見錯誤碼查詢。

nui_dialog_cancel

結束識別或者立即取消當前交互。

-(NuiResultCode) nui_dialog_cancel:(BOOL)force;

返回錯誤碼，參見錯誤碼查詢。

nui_dialog_action

在交互過程中下發對話動作指令，用於更新識別上下文等運行時行為。

-(NuiResultCode) nui_dialog_action:(const char *)action_params;

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

返回錯誤碼，參見錯誤碼查詢。

nui_update_audio_data

當 audio_update_manually 設為 "true" 時，錄音數據不再通過 onNuiNeedAudioData 填入，而是通過此接口主動推送。

-(NuiResultCode) nui_update_audio_data:(const char *)data
                                    Len:(int)length
                              FirstPack:(BOOL)first_pack;

返回錯誤碼，參見錯誤碼查詢。

nui_push_reference_data

當 audio_update_manually 設為 "true" 且啓用端側 AEC 回聲消除能力時，需要通過此接口推送播放器播放的音頻數據作為參考信號。

-(NuiResultCode) nui_push_reference_data:(const char *)data
                                     Len:(int)length
                               FirstPack:(BOOL)first_pack;

返回錯誤碼，參見錯誤碼查詢。

nui_release

釋放SDK所有內部資源，並強制終止所有正在進行的任務。此方法調用後，SDK實例將變為不可用狀態，如需再次使用，必須重新調用 nui_initialize 進行初始化。

-(NuiResultCode) nui_release;

返回錯誤碼，參見錯誤碼查詢。

nui_get_version

獲得當前SDK版本信息。此接口需在 nui_initialize 之後調用才有返回值。

-(const char*) nui_get_version;

當前SDK版本信息。

nui_get_all_response

獲得當前事件回調的完整信息。

-(const char*) nui_get_all_response;

JSON字符串格式的完整事件信息。

NeoNuiSdkDelegate：監聽回調

onNuiEventCallback：監聽事件和語音識別結果

-(void) onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                    dialog:(long)dialog
                 kwsResult:(const char *)wuw
                 asrResult:(const char *)asr_result
                  ifFinish:(BOOL)finish
                   retCode:(int)code;

onNuiAudioStateChanged：監聽音頻狀態

SDK 通過此回調通知何時應該開始或停止錄音。

-(void) onNuiAudioStateChanged:(NuiAudioState)state;

onNuiNeedAudioData：填充待識別音頻數據

開始識別後，該回調被連續觸發，需在其中提供待識別音頻數據。

-(int) onNuiNeedAudioData:(char *)audioData length:(int)len;

onNuiAssistEventCallback：輔助數據和信息結果

此回調用於接收 SDK 內部的輔助事件和相關數據。

-(void) onNuiAssistEventCallback:(NuiCallbackEvent)nuiEvent
                            info:(char*)info
                         infoLen:(int)info_len
                          buffer:(char*)buffer
                             len:(int)len;

onNuiLogTrackCallback：監聽追蹤日誌

此回調用於接收 SDK 內部的詳細日誌，方便進行問題定位和調試。

-(void) onNuiLogTrackCallback:(NuiSdkLogLevel)level
                   logMessage:(const char *)log;

NuiCallbackEvent：事件類型