Qwen-Audio-3.0-Realtime即時語音對話Android SDK - Alibaba Cloud Model Studio

使用Qwen-Audio-3.0-Realtime即時語音對話Android SDK，實現即時音訊輸入以及語音或文字輸出。

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

快速開始

取得與設定 API Key
下載 SDK 並執行範例程式碼：
- 下載最新 SDK 整合包。
- 解壓縮 ZIP 套件。在 app/libs 目錄中取得 AAR 格式 SDK，並新增至專案相依性。需要 Android C++ 接入時，使用 ZIP 套件內的 android_libs 與 android_include 取得動態連結庫和標頭檔。
- 使用 Android Studio 開啟專案。範例程式碼位於 DashQwenAudioChatActivity.java，替換 API Key 後體驗功能。

呼叫步驟

初始化 SDK
按業務需求設定參數：透過 initialize 介面的 parameters 參數設定連線與控制參數；透過 setParams 介面設定語音對話效果參數。
呼叫 startDialog 啟動對話流程。
在 onNuiAudioStateChanged 回呼中，根據音訊狀態開啟錄音裝置。
在 onNuiNeedAudioData 回呼中持續提供錄音資料，或者透過 updateAudio 持續推送錄音資料。
在 onNuiAssistEventCallback 回呼中持續取得 AI 傳回的語音資料。
在 onNuiEventCallback 回呼中監聽事件並取得事件資訊。
呼叫 stopDialog 停止對話，並透過監聽 EVENT_TRANSCRIBER_COMPLETE 事件確認對話已結束。
當對話功能不再使用時，呼叫 release 介面釋放 SDK 資源。

請求參數

連線與控制參數

透過在 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）時，必須設定 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）的日誌才會被回調。
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_vad	`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-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	`boolean`	否	是否開啟情緒增強功能。開啟後，回覆音色的情緒變化更明顯。預設值：`true`。可選值：`true`、`false`。
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。

關鍵介面

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 格式： `{ "apikey": "st-****" }`

vad_mode

VadMode

VAD 模式。固定為 VadMode.TYPE_P2T。

dialog_params

String

如果連線與控制參數的 apikey 參數使用的是臨時 API Key，當其過期時，可在此處進行更新。
內容為 JSON 格式：

{
  "apikey": "st-****"
}

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`	具體的執行指令，當前支援 `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 音色。

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"
  }
}

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：填入待處理音訊資料

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

方法簽章

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[]`	輔助資料，例如 AI 返回的 TTS 音訊。

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_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 回音消除後的音訊資料。