Qwen-Audio-ASR-Message Android SDK

​

快速開始

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

​

呼叫步驟

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

​

請求參數

​

連線與控制參數

• 參數範例：以下為 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/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）時，必須設定 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 下。

​

語音識別效果參數

• 參數範例：以下為 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	是	指定範例呼叫的模型。模型資訊請參見支援的模型與地域。
  nls_config.sr_format	string	是	音訊格式。取值範圍： pcm opus opus：使用者傳入 PCM 格式音訊，由 SDK 內部完成 opus 編碼。
  nls_config.sample_rate	int	是	採樣率（Hz），僅支援 16000。
  nls_config.language_hints	array[string]	否	待識別音訊語種。無預設值，未設定時模型自動識別。最多支援設定 4 個值，超出時僅前 4 個生效。 點擊檢視支援的語言代碼 zh: 中文 en: 英文 ja: 日語 ko：韓語 vi：越南語 th：泰語 id：印尼語 ms：馬來語 tl：菲律賓語 hi：印地語 ar：阿拉伯語 fr：法語 de：德語 es：西班牙語 pt：葡萄牙語 ru：俄語 it：義大利語 nl：荷蘭語 sv：瑞典語 da：丹麥語 fi：芬蘭語 no：挪威語 el：希臘語 pl：波蘭語 cs：捷克語 hu：匈牙利語 ro：羅馬尼亞語 bg：保加利亞語 hr：克羅埃西亞語 sk：斯洛伐克語 僅在最終結果（sentence_end=true）生效，中間結果（sentence_end=false）不支援。
  nls_config.keep_dialect	boolean	否	是否保留方言表達，預設值為 false。false：將方言轉寫為普通話文字；true：保留方言表達。 僅在最終結果（sentence_end=true）生效，中間結果（sentence_end=false）不支援。
  nls_config.vad_model	string	否	VAD 模型，預設值為 far_field_meeting_16k。 near_meeting_16k：近場情境。 far_field_meeting_16k：遠場情境。
  nls_config.max_sentence_silence	int	否	VAD 斷句靜音閾值（毫秒）。語音後的靜音時長超過此值時判定句子結束。預設值為 800，取值範圍為 [200, 6000]。
  nls_config.heartbeat	boolean	否	是否啟用心跳封包。預設值：false。 true：在持續傳送靜音音訊的情況下，可保持與伺服器的連線不中斷。 false（預設）：即使持續傳送靜音音訊，連線也將在一定時間後因逾時而斷開。 靜音音訊指的是在音訊檔案或資料流中沒有聲音訊號的內容。靜音音訊可以透過多種方法產生，例如使用音訊編輯軟體如 Audacity 或 Adobe Audition，或者透過命令列工具如 FFmpeg。
  nls_config.disfluency_removal_enabled	boolean	否	僅 qwen-audio-3.1-asr-flash-message 支援。是否過濾語氣詞並對輸出結果進行潤飾，預設值為 false。設定為 true 時啟用。
  nls_config.intermediate_result_enabled	boolean	否	僅 qwen-audio-3.1-asr-flash-message 支援。是否返回串流中間結果，預設值為 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

• 方法簽章

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

• 方法簽章

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 格式： Copy { "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

• 方法簽章

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

• 參數說明

  參數	類型	說明
  data	byte[]	推送的音訊資料。
  len	int	推送的音訊資料的位元組數。
  first_pack	boolean	請忽略，無需關注此參數。

• 傳回值說明

​

updateRefAudio

• 方法簽章

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

• 參數說明

  參數	類型	說明
  data	byte[]	推送的音訊資料。
  len	int	推送的音訊資料的位元組數。
  first_pack	boolean	請忽略，無需關注此參數。

• 傳回值說明

​

release

• 方法簽章

public synchronized int release();

• 傳回值說明

​

GetVersion

• 方法簽章

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：監聽音訊狀態

• 方法簽章

void onNuiAudioStateChanged(AudioState state);

• AudioState 狀態說明

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

​

onNuiNeedAudioData：填充待識別音訊資料

• 方法簽章

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

• 參數說明

  參數	類型	說明
  buffer	byte[]	填入的音訊資料。
  len	int	填入的音訊資料的位元組數。

• 傳回值說明 實際填入的位元組數。

​

onNuiAssistEventCallback：輔助資料和資訊結果

• 方法簽章

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

• 參數說明

  參數	類型	說明
  event	int	NuiEvent事件
  info	String	無需關注此參數。
  info_len	int	無需關注此參數。
  data	byte[]	輔助資料，例如 AEC 回音消除後的音訊資料。

​

onNuiLogTrackCallback：監聽追蹤日誌

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

​

NuiEvent：事件類型