Fun-ASR-Realtime Android SDK - Alibaba Cloud Model Studio

本文檔提供了 Fun-ASR-Realtime 即時語音辨識 Android SDK 的詳細使用指南，協助您將語音轉換為文字。

快速開始

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

呼叫步驟

初始化 SDK
按業務需求設定參數：透過 initialize 介面的 parameters 參數設定連接與控制參數；透過 setParams 介面設定語音辨識效果參數。
呼叫 startDialog 啟動識別流程。
在 onNuiAudioStateChanged 回調中，根據音訊狀態開啟錄音裝置。
在 onNuiNeedAudioData 回調中持續提供錄音資料，或者透過 updateAudio 持續推送錄音資料。
在 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/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` 下。

語音識別效果參數

透過在 setParams 介面的 params 參數中傳入一個 JSON 字串來設定。

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

{
    "service_type": 4,
    "nls_config": {
        "model": "fun-asr-realtime",
        "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）。取值範圍：8k 模型僅支援 8000 Hz，其他模型支援任意採樣率。重要當啟用端側音訊功能（如 AEC、VAD）時，不支援 8000Hz。
`nls_config.semantic_punctuation_enabled`	`boolean`	否	是否啟用語意斷句。預設值：false。 true：開啟語意斷句，關閉 VAD 斷句。 false（預設）：啟用 VAD 斷句，停用語義斷句。語義斷句準確性更高，適合會議轉寫場景；VAD（Voice Activity Detection，語音活動檢測）斷句延遲較低，適合互動場景。
`nls_config.max_sentence_silence`	`int`	否	VAD 斷句靜音閾值（ms）。當一段語音後的靜音時長超過該閾值時，系統會判定該句子已結束。當 `semantic_punctuation_enabled` 為 true 時，不作為 `sentence_end` 返回依據，但設定過小可能會影響識別效果。預設值：1300。取值範圍：[200, 6000]。
`nls_config.multi_threshold_mode_enabled`	`boolean`	否	重要僅在 `semantic_punctuation_enabled` 參數為 false 時生效。是否啟用多閾值模式。啟用後可防止 VAD 斷句切割過長。預設值：false。
`nls_config.heartbeat`	`boolean`	否	是否啟用心跳封包。預設值：false。 true：在持續傳送靜音音訊的情況下，可保持與伺服器的連線不中斷。 false（預設）：即使持續傳送靜音音訊，連線也將在一定時間後因逾時而斷開。靜音音訊指的是在音訊檔案或資料流中沒有聲音訊號的內容。靜音音訊可以透過多種方法產生，例如使用音訊編輯軟體如 Audacity 或 Adobe Audition，或者透過命令列工具如 FFmpeg。
`nls_config.vocabulary_id`	`string`	否	預編譯熱詞清單 ID。需預先呼叫建立熱詞列表介面產生，識別時傳入該 ID 即可使用列表中的熱詞。適用於詞彙已知且相對穩定、需要跨請求重複使用同一詞表的場景。使用方法請參見預編譯熱詞。
`nls_config.language_hints`	`array[string]`	否	待識別音訊語種。無預設值，未設定時模型自動識別。僅支援設定 1 個值，設定多個時僅第一個生效。點擊檢視支援的語言代碼 fun-asr-realtime、fun-asr-realtime-2025-11-07： 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：斯洛伐克語 fun-asr-realtime-2026-02-28： zh: 中文 en: 英文 ja: 日語 fun-asr-realtime-2025-09-15： zh: 中文 en: 英文 fun-asr-flash-8k-realtime、fun-asr-flash-8k-realtime-2026-01-28： zh: 中文 fun-asr-mtl-realtime、fun-asr-mtl-realtime-2025-12-10： zh: 中文 en: 英文 ja: 日語 ko：韓語 vi：越南語 id：印尼語 th：泰語
`nls_config.speech_noise_threshold`	`float`	否	語音與噪音的判定閾值，用於調整語音活動檢測（VAD）的靈敏度。取值範圍：[-1.0, 1.0]。取值說明：取值越接近 -1：降低噪音判定閾值，噪音被識別為語音的機率增大，可能導致更多噪音被轉寫取值越接近 +1：提高噪音判定閾值，語音被誤判為噪音的機率增大，可能導致部分語音被過濾此參數為進階設定參數，調整可能顯著影響識別效果，建議：調整前充分測試驗證效果根據實際音訊環境小幅度調整（建議步長 0.1）
`nls_config.special_word_filter`	`object`	否	指定在語音識別過程中需要處理的敏感詞，並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。
`nls_config.enable_connection_fast_check`	`boolean`	否	啟動快速偵測網路的功能，即盡快回饋斷網情況，預設關閉。

關鍵介面

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 語音識別效果參數。
傳回值說明

參數	類型	說明
`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-****", "input_context": [ { "role": "user", "content": [ { "text": "xxxxx", "type": "input_text" } ] } ] }`

vad_mode

VadMode

VAD 模式。固定為 VadMode.TYPE_P2T。

dialog_params

String

如果連接與控制參數的 apikey 參數使用的是臨時 API Key，當其過期時，可在此處進行更新。

如果需要透過上下文增強來提升識別準確率，則在此處進行更新。

內容為 JSON 格式：

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

參數 audio_update_manually 設定為 "true" 時，錄音資料不再是透過 onNuiNeedAudioData 填入，而是用此介面主動推送。

方法簽章

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

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

參數	類型	說明
`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 請忽略，無需關注此參數。
傳回值說明

參數	類型	說明
`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 執行個體已釋放，可以徹底關閉錄音裝置。

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

onNuiNeedAudioData：填充待識別音訊資料

開始識別後，該回調會被連續觸發，需在其中提供待識別音訊資料。

方法簽章

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

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

參數	類型	說明
`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[] 輔助資料，例如 AEC 回音消除後的音訊資料。

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

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_WARN`	語音識別過程中出現不影響執行的警告，例如啟用斷網續傳後的斷網事件。
`EVENT_ASR_ERROR`	語音識別過程中發生錯誤。
`EVENT_MIC_ERROR`	因連續 2 秒未收到任何音訊資料而觸發。
`EVENT_SENTENCE_END`	偵測到一句話結束，此時會返回一句完整的識別結果。
`EVENT_TRANSCRIBER_COMPLETE`	語音識別結束。
`EVENT_AEC_DATA`	AEC 回音消除後的音訊資料。

快速開始

呼叫步驟

請求參數

連線與控制參數

語音識別效果參數

關鍵介面

NativeNui

initialize

setParams

startDialog

stopDialog

cancelDialog

updateAction

updateAudio

updateRefAudio

release

GetVersion

INativeNuiCallback：監聽回調

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

onNuiAudioStateChanged：監聽音訊狀態

onNuiNeedAudioData：填充待識別音訊資料

onNuiAssistEventCallback：輔助資料和資訊結果

onNuiLogTrackCallback：監聽追蹤日誌

NuiEvent：事件類型

`NuiEvent`：事件類型