Qwen-Audio-3.0-Realtime 即時語音對話 iOS SDK

使用者指南：關於模型介紹和選型建議請參見即時語音對話。

快速開始

獲取 API Key：獲取與配置 API Key
下載 SDK 並執行範例程式碼：
- 下載最新 SDK 整合包。
- 解壓縮 ZIP 包，將其中的 nuisdk.xcframework 新增至工程。
- 在 Build Phases → Link Binary With Libraries 中新增 nuisdk.xcframework。
- 在 General → Frameworks, Libraries, and Embedded Content 中將 nuisdk.xcframework 設定為 Embed & Sign。
- 使用 Xcode 開啟範例專案。範例程式碼位於DashQwenAudioChatViewController.m，替換 API Key 後體驗功能。

呼叫步驟

初始化 SDK
依業務需求設定參數：透過nui_initialize介面設定連線與控制參數；透過nui_set_params介面設定語音對話效果參數。
呼叫nui_dialog_start啟動對話流程。
在 onNuiAudioStateChanged 回呼中，根據音訊狀態開啟錄音裝置。
在onNuiNeedAudioData回呼中持續提供錄音資料，或者透過nui_update_audio_data持續推送錄音資料。
在 onNuiAssistEventCallback 回呼中持續取得 AI 傳回的語音資料。
在 onNuiEventCallback 回呼中監聽事件並取得事件資訊。
呼叫nui_dialog_cancel停止對話，並透過監聽 EVENT_TRANSCRIBER_COMPLETE 事件確認對話已結束。
當對話功能不再使用時，呼叫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"
}

參數說明

參數	類型	是否必須	說明
`url`	`String`	是	服務位址： `wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>` 華北 2（北京）：`wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>` 新加坡：`wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>` 呼叫時，請將 `{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）的日誌才會被回調。

語音對話效果參數

透過在nui_set_params介面的params參數中傳入一個 JSON 字串來設定。 參數範例：以下為 JSON 字串範例，參數未完整列出。請按實際需求在編碼時補充：

{
    "service_type": 4,
    "nls_config": {
        "model": "qwen-audio-3.1-realtime-plus",
        "sr_format": "pcm"
    }
}

參數說明

一級參數	類型	是否必須	說明
`service_type`	`int`	是	語音服務類型。即時語音對話固定為 `4`。
`nls_config`	`object`	是	語音對話核心設定物件，包含模型選擇、對話效果控制等關鍵參數。
`nls_config.model`	`string`	是	指定模型名稱。支援 qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus 和 qwen-audio-3.0-realtime-flash 系列模型。
`nls_config.sr_format`	`string`	是	輸入音訊格式。目前僅支援 `pcm`（16kHz 16bit 單聲道），為預設值。
`nls_config.modalities`	`string`	否	array 格式的字串，模型輸出模態設定，可選值： `["text"]`：僅輸出文字。 `["audio", "text"]`（預設值）：同時輸出文字和音訊。
nls_config.voice	`string`	否	TTS 音色名稱，3.1 Plus 的預設值為 `longanqian_v3.1`，3.0 Plus/Flash 的預設值為 `longanqian`。支援兩種類型，僅可在第一次 `session.update` 中設定，後續傳入將被忽略。系統音色：可選值：`longanqian`、`longanlingxin`、`longanlingxi`、`longanxiaoxin`、`longanlufeng`。聲音複製音色：透過聲音複製 API 建立，將傳回的 `voice_id` 填入此參數。詳見音色設定。 3.1 Plus 還支援 `longanqian_v3.1`、`longanhuan_v3.1`、`longanlingxin_v3.1`、`longanfengyue_v3.1`、`xunanchuan_v3.1`、`beth_v3.1`、`betty_v3.1`、`cally_v3.1`。
nls_config.enable_speech_emotion	`BOOL`	否	是否開啟情緒增強功能。開啟後，回覆音色的情緒變化更明顯。預設值：`YES`。可選值：`YES`、`NO`。
nls_config.instructions	`string`	否	系統指令，用於設定模型的角色身分、回答風格和行為偏好。對整個對話生效。
nls_config.max_history_turns	int	否	允許單次請求的最大歷史 QA 輪數。取值範圍為 1-50，預設值為 20。
nls_config.tools	`string`	否	array 格式的字串。Function Calling 工具定義清單。設定後模型可根據使用者輸入自主決定是否呼叫工具。內部參數說明： type`string`（必選）固定為 `function`。 function.name`string`（必選）工具函數名稱。 function.description`string`（選填）對工具函數功能的描述，模型據此判斷是否呼叫該工具。 function.parameters`object`（選填）對工具函數輸入參數的描述，模型據此提取所需輸入參數。若函數無需輸入參數，可不指定。範例： `[ { "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的天气信息。", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市" } }, "required": [ "city" ] } } } ]`
nls_config.turn_detection	`string`	否	JSON 物件形式的字串。輪次偵測設定。未設定時則切換為 push-to-talk 模式（手動提交音訊並觸發推理）。否則啟用雙工對話模式。
nls_config.turn_detection.type	`string`	否	VAD 類型，可選值： `server_vad`（預設值）：基於聲學特徵偵測語音起止，自動觸發推理。 `smart_turn`：融合聲學感知與語意理解的智慧輪次偵測，透過聲學與語意雙重判斷輪次邊界。無語意的聲音（如「嗯」、「啊」）不會觸發對話輪或打斷模型播報。
nls_config.turn_detection.threshold	float	否	VAD 靈敏度，僅在 server_vad 模式下生效（smart_turn 模式下無效）。值越低，VAD 越靈敏，越容易將微弱聲音（包括背景雜訊）識別為語音；值越高，越不靈敏，需要更清晰、音量更大的語音才能觸發。取值範圍為 [-1.0, 1.0]，預設值為 0.5。
nls_config.turn_detection.silence_duration_ms	`int`	否	語音結束後需保持靜音的最短時間（毫秒），僅在 server_vad 模式下生效（smart_turn 模式下無效）。逾時即觸發模型回應。值越低，回應越快，但可能在短暫停顿時誤觸發。取值範圍為 [200, 6000]，預設值為 800。對話場景推薦 400-800。
nls_config.turn_detection.voiceprint_audio_urls	`string`	否	array 形式的字串。僅在 smart_turn 模式下生效。目標使用者預錄音訊的公網可存取 URL 清單，用於說話人增強。傳入後，模型將在雙工對話中精準鎖定目標說話人，有效忽略旁人聲音與背景雜訊。最多支援 5 個 URL。音訊格式要求：16kHz PCM 或 WAV。

關鍵介面

NeoNui

nui_initialize

初始化語音對話SDK 實例。SDK 為單例模式，在呼叫 nui_release 前禁止重複初始化。 方法簽章

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

參數說明

參數	類型	說明
`parameters`	`char*`	JSON 字串，包含驗證、連線和偵錯參數。請參見連線與控制參數。
`level`	`NuiSdkLogLevel`	控制 SDK 自身日誌的列印層級。
`save_log`	BOOL	是否儲存本機日誌。若為`YES`，須在連線與控制參數透過`debug_path`指定路徑，並可透過`max_log_file_size`設定檔案大小。

nui_set_params

以 JSON 格式設定語音對話效果參數。在 nui_dialog_start 之前呼叫。 方法簽章

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

參數說明

參數	類型	說明
`params`	`char*`	語音對話效果參數。

nui_dialog_start

開始對話。 方法簽章

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

參數說明

參數	類型	說明
`vad_mode`	`NuiVadMode`	VAD 模式。固定為 `MODE_P2T`。
`dialog_params`	`char*`	如果連線與控制參數的 `apikey` 參數使用的是臨時 API Key，當其過期時，可在此處進行更新。內容為 JSON 格式： `{ "apikey": "st-****" }`

nui_dialog_cancel

結束對話或者立即取消當前互動。 方法簽章

- (NuiResultCode) nui_dialog_cancel:(BOOL)force;

參數說明

參數	類型	說明
`force`	`BOOL`	是否強制結束而忽略最終結果。 `YES`：不等待伺服器返回最終辨識結果就立即結束任務。 `NO`：結束任務，但是會等待完整結果返回。

nui_dialog_action

在互動過程中下達對話動作指令，用於更新對話上下文等執行階段行為。 方法簽章

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

參數說明

參數	類型	說明
`params`	`char*`	JSON 字串，用於更新對話上下文等執行時行為。
`params.type`	`String`	固定為 `"action"`。
`params.command`	`String`	具體的執行指令，當前支援 `function_call`、`play_start`、`play_over`。 `function_call`：更新函數呼叫請求的指令。 `play_start`：當使用端側 AEC 時，透過此指令通知 SDK 內部 AEC 播放器開始播放音訊。 `play_over`：當使用端側 AEC 時，透過此指令通知 SDK 內部 AEC 播放器已經播放結束。
`params.context`	`String`	當 `command` 為 `"function_call"` 時，更新函數呼叫請求。
`params.context.type`	`String`	事件類型，當`command`為`"function_call"`時必須設定。 `conversation.item.create`：手動向對話上下文插入一條對話項目。可用於注入歷史上下文、補充文字資訊，或寫回 Function Calling 的工具執行結果。 `response.create`：在 `conversation.item.create` 指令傳送後，透過此指令觸發第二輪推理。
`params.context.item`	`object`	`params.context.type` 為 conversation.item.create 時必須設定，表示要建立的對話項目。詳見如下。
`params.context.response`	`object`	`params.context.type` 為 response.create 時可設定，表示用於覆蓋本輪推理的工作階段預設設定。未傳送時使用目前工作階段設定。詳見如下。

context.item參數：

參數	類型	說明
id	`String`	選填。對話項目的唯一識別碼。未傳送時由伺服器端自動產生。若指定的 ID 已存在於對話中，會傳回錯誤。
type	`String`	必選。對話項類型，可選值： `message`：一般對話訊息。 `function_call`：函數呼叫請求。通常由伺服器端產生，用戶端也可用於補充歷史上下文。 `function_call_output`：工具執行結果。用戶端收到 `function_call` 後執行工具，並用該類型寫回結果。
role	`String`	`message` 類型必選。訊息角色，可選值：`system`、`user`、`assistant`。
content	array	`message` 類型必選。訊息內容清單。每個元素包含 `type` 和對應的資料欄位。各 role 支援的 content 類型： system `input_text`：系統訊息，必填欄位 `text`。 user `input_text`：使用者文字輸入，必填欄位 `text`。 `input_audio`：使用者音訊輸入，必填欄位 `audio`（Base64 編碼）。 assistant `output_text`：助手文字輸出，必填欄位 `text`。
call_id	`String`	（`function_call` / `function_call_output` 類型必選）函數呼叫的唯一識別碼，用於關聯請求和結果。
name	`String`	（`function_call` 類型必選）要呼叫的函數名稱。
arguments	`String`	`function_call` 類型必選）函數呼叫參數，JSON 字串格式。
output	`String`	（`function_call_output` 類型必選）工具執行結果，JSON 字串格式。

context.response參數：

參數	類型	說明
modalities	`array`	array 格式的字串，模型輸出模態設定，可選值： `["text"]`：僅輸出文字。 `["audio", "text"]`（預設值）：同時輸出文字和音訊。
voice	string	覆蓋本輪的 TTS 音色。

範例：

{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"杭州\",\"condition\":\"晴\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": [
        "text",
        "audio"
      ]
    },
    "type": "response.create"
  }
}

nui_update_audio_data

當 audio_update_manually 設為 "true" 時，錄音資料不再透過 onNuiNeedAudioData 填入，而是透過此介面主動推送。 方法簽章

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

參數說明

參數	類型	說明
`data`	`const char *`	推送的音訊資料。
`length`	`int`	推送的音訊資料的位元組數。
`first_pack`	`BOOL`	無需關注此參數。

nui_push_reference_data

當 audio_update_manually 設為 "true" 且啟用端側 AEC 回音消除能力時，需要透過此介面推送播放器播放的音訊資料作為參考訊號。 方法簽章

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

參數說明

參數	類型	說明
`data`	`const char *`	推送的音訊資料。
`length`	`int`	推送的音訊資料的位元組數。
`first_pack`	`BOOL`	無需關注此參數。

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;

參數說明

參數	類型	說明
`nuiEvent`	`NuiCallbackEvent`	回調事件。
`dialog`	`long`	會話編碼，無需關注該參數。
`wuw`	`char*`	語音喚醒功能。無需關注此參數。
`asr_result`	`char*`	語音辨識結果。
`finish`	`BOOL`	本輪辨識是否結束標誌。
`code`	`int`	僅在出現 `EVENT_ASR_ERROR` 事件時有效。

onNuiAudioStateChanged：監聽音訊狀態

SDK 透過此回調通知何時應該開始或停止錄音。 方法簽章

- (void) onNuiAudioStateChanged:(NuiAudioState)state;

NuiAudioState狀態說明

參數	說明
`STATE_OPEN`	互動啟動，可以開啟錄音裝置進行錄音。
`STATE_PAUSE`	互動停止，可以停止錄音。
`STATE_CLOSE`	SDK 執行個體已釋放，可以徹底關閉錄音裝置。

onNuiNeedAudioData：填入待處理音訊資料

開始對話後，該回呼會被連續觸發，需在其中提供待處理的音訊資料。參數 audio_update_manually 設定為 "true" 時可不關注這個回呼。 方法簽章

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

參數說明

參數	類型	說明
`audioData`	`char *`	填入的音訊資料。
`len`	`int`	填入的音訊資料的位元組數。

onNuiAssistEventCallback：輔助資料和資訊結果

此回調用於接收 SDK 內部的輔助事件和相關資料。 方法簽章

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

參數說明

參數	類型	說明
`nuiEvent`	`NuiCallbackEvent`	回調事件。
`info`	`char *`	無需關注此參數。
`info_len`	`int`	無需關注此參數。
`buffer`	`char *`	輔助資料，例如 AI 返回的 TTS 音訊。
`len`	`int`	輔助資料的位元組數。

onNuiLogTrackCallback：監聽追蹤日誌

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

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

NuiCallbackEvent：事件類型

事件	說明
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_AUDIO_TRANSCRIPTION	音訊模式下的文字字幕增量事件，串流返回字幕片段。
EVENT_AUDIO_TRANSCRIPTION_COMPLETED	音訊模式下的字幕輸出完成事件。
EVENT_OTHER_RESULT	其他未歸類事件資訊，例如 function_call 的返回結果等。
EVENT_ASR_TTS_START	AI 開始返回 TTS 資料。
EVENT_ASR_TTS_DATA	AI 返回的 TTS 資料。
EVENT_ASR_TTS_COMPLETE	AI 返回 TTS 資料結束。
EVENT_AEC_DATA	AEC 回音消除後的音訊資料。

​快速開始

​呼叫步驟

​請求參數

​連線與控制參數

​語音對話效果參數

​關鍵介面

​NeoNui

​nui_initialize

​nui_set_params

​nui_dialog_start

​nui_dialog_cancel

​nui_dialog_action

​nui_update_audio_data

​nui_push_reference_data

​nui_release

​nui_get_version

​nui_get_all_response

​NeoNuiSdkDelegate：監聽回調

​onNuiEventCallback：監聽事件資訊

​onNuiAudioStateChanged：監聽音訊狀態

​onNuiNeedAudioData：填入待處理音訊資料

​onNuiAssistEventCallback：輔助資料和資訊結果

​onNuiLogTrackCallback：監聽追蹤日誌

​NuiCallbackEvent：事件類型

快速開始

呼叫步驟

請求參數

連線與控制參數

語音對話效果參數

關鍵介面

NeoNui

nui_initialize

nui_set_params

nui_dialog_start

nui_dialog_cancel

nui_dialog_action

nui_update_audio_data

nui_push_reference_data

nui_release

nui_get_version

nui_get_all_response

NeoNuiSdkDelegate：監聽回調

onNuiEventCallback：監聽事件資訊

onNuiAudioStateChanged：監聽音訊狀態

onNuiNeedAudioData：填入待處理音訊資料

onNuiAssistEventCallback：輔助資料和資訊結果

onNuiLogTrackCallback：監聽追蹤日誌

NuiCallbackEvent：事件類型