Skip to main content

非即時語音識別（Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash）HarmonyOS SDK

Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash非即時語音識別HarmonyOS SDK可將語音轉換為文字。

使用者指南：非即時語音辨識。關於支援的音訊格式、檔案大小限制、時長限制等輸入要求，請參見音訊規格。

快速開始

  1. 取得API Key：取得API Key，為安全起見，建議將API Key設定至環境變數。
  2. 下載 SDK 並執行範例程式碼：
    • 下載最新SDK整合包。
    • 解壓縮 TAR 套件。在 neonui 目錄中獲取 HAR 格式 SDK，並新增至專案相依性。需要 C++ 接入時，使用 TAR 套件內的 native/libs 與 native/include 獲取動態連結庫和標頭檔。
    • 使用 DevEco Studio 開啟專案。範例程式碼位於 DashFunAsrFlashFileTranscriberPage.ets，替換 API Key 後體驗功能。

呼叫步驟

同步模式

  1. 初始化 SDK
  2. 依業務需求設定相關參數
  3. 呼叫 startFileTranscriber 傳送非即時語音識別請求，並等待結果返回。
  4. 在onFileTransEventCallback介面中監聽EVENT_FILE_TRANS_RESULT 事件，獲取最終識別結果。
  5. 呼叫 release 釋放 SDK 資源

請求參數

連線與控制參數

透過在initializeFileTrans介面的parameters參數中傳入一個JSON字串來設定。 參數範例：以下為 JSON 字串範例，參數未完整列出。請按實際需求在編碼時補充： 
{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
參數說明
參數類型是否必須說明
urlstring是服務位址，固定為 wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation。呼叫時請將{WorkspaceId}替換為真實的Workspace ID。
apikeystring是API Key。建議使用時效性短、安全性更高的 臨時 API Key，以降低長期有效 Key 外洩的風險。
service_modestring是執行模式。非即時語音辨識固定為 "1"。
device_idstring是用於識別終端使用者的唯一字串，可設為應用程式內使用者 ID 或用戶端產生的裝置唯一識別碼。此 ID 主要用於日誌追蹤和問題排查。
debug_pathstring否記錄檔的儲存路徑。 此參數僅在呼叫initializeFileTrans介面時將save_log設為true時生效。此時必須設定記錄檔路徑，否則將回報錯誤。 本機最多保留兩個記錄檔。
max_log_file_sizenumber否設定記錄檔的最大位元組數。 此參數僅在呼叫initializeFileTrans介面時將save_log設為true時生效。 預設值：104857600（100 * 1024 * 1024 位元組, 即 100MiB）。

語音辨識效果參數

透過setParams介面設定nls_config參數，或者透過startFileTranscriber介面設定所有語音識別效果參數。 參數範例：以下為 JSON 字串範例，參數未完整列出。請按實際需求在編碼時補充： 
{
  "apikey": "st-****",
  "messages": [
    {
      "content": [
        {
          "input_audio": {
            "data": "{YOUR_AUDIO_URL}"
          },
          "type": "input_audio"
        }
      ],
      "role": "user"
    }
  ],
  "nls_config": {
    "format": "mp3",
    "model": "qwen-audio-3.0-asr-flash"
  }
}
參數說明
參數類型是否必須說明
apikeystring否如果連線與控制參數的apikey使用的是臨時API Key，可在此處進行更新，以免逾時失效。
nls_configobject是語音辨識核心設定物件，包含模型選擇、辨識效果控制等關鍵參數。
nls_config.modelstring是指定範例呼叫的模型。模型資訊請參見支援的模型與地域。
nls_config.formatstring是音訊格式。根據實際音訊格式填寫，支援wav、mp3、opus等。詳情請參見音訊規格。
nls_config.sample_ratestring否音訊取樣率，單位Hz。例如16000表示16kHz取樣率。詳情請參見音訊規格。
nls_config.vocabulary_idstring否預編譯熱詞清單 ID。 需預先呼叫建立熱詞清單介面產生，識別時傳入該 ID 即可使用清單中的熱詞。 適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的場景。 使用方法請參見預編譯熱詞。
nls_config.instant_vocabularyobject否即時熱詞。
以鍵值對形式傳入，鍵為熱詞文字（string），值為熱詞權重（integer），無需預先建立熱詞清單。權重取值範圍為 [1, 5] 或 50：取 [1, 5] 時值越大模型越傾向輸出該詞；取 50 時為超級熱詞，召回率大幅提升，但超級熱詞數量最多不超過 50 個。
適用於臨時性、工作階段層級的熱詞最佳化。
與預編譯熱詞同時設定時，系統會合併兩類熱詞；合併後超過 2000 個時，隨機選擇 2000 個使用。使用方法請參見即時熱詞。
即時熱詞的適用模型及限制請參見即時熱詞。

{
 "张三": 5,
 "李四": 5
}
nls_config.language_hintsarray[string]否設定待辨識語言代碼。如果無法提前確定語種，可不設定，模型會自動辨識語種。
對於 Qwen-Audio-3.x-ASR-Flash 系列模型，最多支援設定 4 個值，即便設定超出 4 個，也僅前 4 個生效；對於 Fun-ASR-Flash 系列模型，僅支援設定 1 個值，即便設定多個，也僅第一個生效。
  • Qwen-Audio-3.x-ASR-Flash、fun-asr-flash-2026-06-15：
  • 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：斯洛伐克語
messagesarray[object]是訊息列表。包含當前待識別的音訊，以及可選的對話上下文（用於提升識別效果）。
詳見如下說明。
messages參數說明：
上下文功能用於提升專有詞彙的識別準確率，使用方法詳見上下文增強。約束：上下文訊息（input_text 和 text 類型）各最多 5 條，超出時保留最近的 5 條。每輪上下文文字總長度（user 和 assistant 的 text 欄位長度之和）不超過 400 個字元（按字元數計算，每個字元計為 1），超出部分從末尾截斷。
攜帶上下文時，messages 中的訊息順序有要求：上下文訊息必須按對話輪次排列，每輪中 user（input_text 類型）必須在對應的 assistant（text 類型）之前；包含 input_audio 的 user 訊息必須放在 messages 陣列的最後。
參數類型是否必須說明
rolestring是訊息角色。取值範圍：
  • user（必選）：使用者訊息。type為input_audio時表示當前待識別的音訊；type為input_text時表示前幾輪的識別結果或領域相關的詞表（可選，上下文）。
  • assistant（可選，上下文）：前幾輪大型語言模型的回覆內容。
contentarray[object]是訊息內容清單。詳細如下說明。
content參數說明：
參數類型是否必須說明
typestring是內容類型。每個請求至少需要一條input_audio類型的訊息。取值範圍：
  • input_audio（必選）：當前待識別的音訊輸入（role為user），需同時傳入input_audio物件。
  • input_text（可選，上下文）：前幾輪使用者語音的識別結果或領域相關的詞表（role為user），需同時傳入text欄位。
  • text（可選，上下文）：前幾輪大型語言模型的回覆內容（role為assistant），需同時傳入text欄位。
input_audioobject否當type為input_audio時必填。
input_audio.datastring是待識別音訊資料。關於支援的音訊格式、檔案大小限制、時長限制等輸入要求，請參見音訊規格。支援以下兩種方式：
  • 音訊檔案URL：直接傳入可公開存取的音訊檔案位址。
  • Base64 Data URI：採用Data URI格式傳入Base64編碼的音訊資料，值由data:{MIME_TYPE};base64,前綴與Base64編碼的音訊資料拼接而成。支援的MIME類型包括audio/wav、audio/mp3等。
    範例（URL方式）：https://example.com/audio/sample.wav
    範例（Base64方式）：data:audio/wav;base64,{BASE64_ENCODED_DATA}
textstring否當type為input_text時，填入前幾輪使用者語音的識別結果或領域相關的詞表；當type為text時，填入前幾輪大型語言模型的回覆內容。文字按字元數計算，每個字元計為 1。每輪上下文中所有訊息的 text 欄位長度之和不超過 400 個字元，超出部分從末尾截斷。

關鍵介面

NativeNui

initializeFileTrans

初始化語音識別SDK執行個體。
與即時語音識別不同，非即時（錄音檔案）轉錄必須使用 initializeFileTrans 方法並傳入 INativeFileTransCallback 回呼，而不是 initialize。
此介面會引起阻塞，應在非 UI 執行緒呼叫。 方法簽章 
public initializeFileTrans(callback: INativeFileTransCallback,
                           parameters: string,
                           level: number,
                           save_log: boolean = false): number
參數說明
參數類型說明
callbackINativeFileTransCallback檔案轉錄事件和資料回呼介面的實作。
parametersstringJSON字串，包含驗證、連線和偵錯參數。參見連線與控制參數。
levelnumber控制SDK自身記錄的列印層級，取值為列舉。
save_logboolean是否儲存本機日誌。若為 true，須在 連線與控制參數 中透過 debug_path 指定路徑，並可透過 max_log_file_size 設定檔案大小。

setParams

此介面用於獨立設定或更新 nls_config 參數。如果所有參數都在startFileTranscriber中一次性提供，則無需呼叫此方法。 方法簽章 
public setParams(params: string): number
參數說明
參數類型說明
paramsstring語音辨識效果參數中的nls_config參數，nls_config之外的參數不支援透過此方法進行設定。

startFileTranscriber

開始辨識。 方法簽章 
public startFileTranscriber(params: string, task_id: ArrayBuffer): number
參數說明
參數類型說明
paramsstring語音識別效果參數。
範例：
{
 "apikey": "st-****",
 "messages": [
 {
 "content": [
 {
 "input_audio": {
 "data": "{YOUR_AUDIO_URL}"
 },
 "type": "input_audio"
 }
 ],
 "role": "user"
 }
 ],
 "nls_config": {
 "format": "mp3",
 "model": "qwen-audio-3.0-asr-flash"
 }
}
task_idArrayBuffer任務ID緩衝區。SDK會將內部產生的隨機任務ID字串寫入該緩衝區，要求緩衝區位元組長度必須 >= 33位元組（範例中使用 new ArrayBuffer(64)）。呼叫成功後可透過轉碼獲取該任務的task_id。

queryFileTranscriber

此介面用於主動查詢一個非同步任務的當前狀態和結果。呼叫成功後，結果將透過onFileTransEventCallback回呼中的 EVENT_FILE_TRANS_QUERY_RESULT 事件返回。 方法簽章 
public queryFileTranscriber(task_id: string): number
參數說明
參數類型說明
task_idstring待查詢的任務ID（由 startFileTranscriber 寫入緩衝區獲得）。

cancelFileTranscriber

立即取消目前任務。 方法簽章 
public cancelFileTranscriber(task_id: string): number
參數說明
參數類型說明
task_idstring待取消的任務ID。

release

釋放SDK所有內部資源。此方法呼叫後，SDK執行個體將變為不可用狀態，如需再次使用，必須重新呼叫initializeFileTrans進行初始化。 方法簽章 
public release(): number

GetVersion

取得目前 SDK 版本資訊。 方法簽章 
public GetVersion(): string
傳回值說明 目前 SDK 版本資訊。

INativeFileTransCallback：監聽回呼

onFileTransEventCallback：監聽事件和語音辨識結果

方法簽章 
onFileTransEventCallback: (event: Constants.NuiEvent, resultCode: number, finish: number,
                           asrResult: AsrResult, taskId: string) => void;
參數說明
參數類型說明
eventConstants.NuiEvent回調事件。
resultCodenumber僅在出現 EVENT_ASR_ERROR 事件時有效。
finishnumber任務是否結束標記。
asrResultAsrResult語音辨識結果。
taskIdstring任務 ID。

onFileTransLogTrackCallback：監聽追蹤日誌

此回調用於接收 SDK 內部的詳細日誌，方便進行問題定位和偵錯。 使用此回呼需下載 20260908 或更新的 HarmonyOS SDK 套件。 
onFileTransLogTrackCallback?: (level: Constants.LogLevel, log: string) => void;

事件類型

HarmonyOS SDK 中事件類型透過 Constants.NuiEvent 列舉定義，以下列出錄音檔案轉錄相關的事件：
事件說明
EVENT_FILE_TRANS_CONNECTED連線服務成功。
EVENT_FILE_TRANS_UPLOADED上傳待識別音訊檔案成功。
EVENT_FILE_TRANS_QUERY_RESULT查詢任務結果。
EVENT_FILE_TRANS_RESULT辨識最終結果。
EVENT_ASR_ERROR語音辨識過程中出現錯誤。
非即時語音識別（Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash）HarmonyOS SDK - Alibaba Cloud Model Studio