Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR 非即時語音辨識 HarmonyOS SDK_大模型服務平台百煉 (Model Studio) - Alibaba Cloud Model Studio

使用 Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR 非即時語音辨識 HarmonyOS SDK 將影音檔案轉換為文字。

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

快速開始

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

呼叫步驟

同步模式

初始化 SDK。
按業務需求配置相關參數。
呼叫 startFileTranscriber 啟動辨識任務，並將 async_request 設為 false。
在 onFileTransEventCallback 回呼中監聽 EVENT_FILE_TRANS_RESULT 事件，以取得最終辨識結果。
呼叫 release 釋放 SDK 資源。

非同步模式

初始化 SDK。
按業務需求配置相關參數。
呼叫 startFileTranscriber 啟動辨識任務，並將 async_request 設為 true。
呼叫 queryFileTranscriber 主動查詢辨識進度或結果。
在 onFileTransEventCallback 回呼中監聽 EVENT_FILE_TRANS_QUERY_RESULT 事件，以取得目前查詢結果。
在 onFileTransEventCallback 回呼中監聽 EVENT_FILE_TRANS_RESULT 事件，以取得最終辨識結果。
呼叫 release 釋放 SDK 資源。

請求參數

連接與控制參數

在 initializeFileTrans 介面的 parameters 參數中傳入 JSON 字串進行設定。 參數範例：以下為 JSON 字串範例，參數未完整列出。請按實際需求在編碼時補充：

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

參數說明

參數	類型	是否必須	說明
`url`	`string`	是	服務位址，固定為 `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription`。呼叫時請將 `{WorkspaceId}` 替換為真實的 Workspace ID。
`apikey`	`string`	是	API Key。建議使用時效性短、安全性更高的臨時 API Key，以降低長期有效金鑰洩露的風險。
`service_mode`	`string`	是	執行模式。非即時語音辨識固定為 `"1"`。
`device_id`	`string`	是	用於標識終端使用者的唯一字串，可設為應用程式內使用者 ID 或用戶端產生的裝置唯一識別碼。此 ID 主要用於日誌追蹤和問題排查。
`debug_path`	`string`	否	日誌檔案的儲存路徑。此參數僅在呼叫 initializeFileTrans 介面時將 `save_log` 設為 true 時生效。此時必須設定日誌檔案路徑，否則將報錯。本機最多保留兩個日誌檔案。
`max_log_file_size`	`number`	否	設定日誌檔案的最大位元組數。此參數僅在呼叫 initializeFileTrans 介面時將 `save_log` 設為 true 時生效。預設值：104857600（100 * 1024 * 1024 位元組，即 100MiB）。

語音識別效果參數

透過 setParams 介面設定 nls_config 參數，或者透過 startFileTranscriber 介面設定所有語音辨識效果參數。 參數範例：以下為 JSON 字串範例，參數未完整列出。請按實際需求在編碼時補充：

{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false,
        "parameters": {
            "speech_noise_threshold": 0.0
        }
    }
}

參數說明

參數	類型	是否必須	說明
`file_urls`	`array[string]`	是	影音檔案轉寫的 URL 清單，支援 HTTP / HTTPS 協定，單次請求僅支援 1 個 URL。關於支援的音訊格式、檔案大小限制、時長限制等輸入要求，請參見音訊規格。若錄音檔案儲存在阿里雲 OSS，使用 RESTful API 方式支援使用以 `oss://` 為前綴的臨時 URL，但使用 SDK 方式不支援使用以 oss:// 為前綴的臨時 URL。重要臨時 URL 有效期48小時，過期後無法使用，請勿用於生產環境。檔案上傳憑證介面限流為 100 QPS 且不支援擴容，請勿用於生產環境、高併發及壓力測試場景。生產環境建議使用阿里雲 OSS 等穩定儲存服務，確保檔案長期可用並規避限流問題。 - 錄音檔案 URL 設定為 OSS 臨時公網存取不通時該如何處理？可將請求標頭中的 `X-DashScope-OssResourceResolve` 設為 `enable`（不推薦此方式）。SDK 不支援對請求標頭進行設定。
`async_request`	`boolean`	否	語音辨識是否為非同步請求。預設值：`false`。取值範圍：- true：非同步請求 - false：同步請求
`apikey`	`string`	否	如果連線與控制參數的 `apikey` 使用的是臨時 API Key，可在此處進行更新，以免逾時失效。
`nls_config`	`object`	是	語音識別核心設定物件，包含模型選擇、識別效果控制等關鍵參數。
`nls_config.model`	`string`	是	指定範例呼叫的模型。模型資訊請參見支援的模型與地域。
`nls_config.special_word_filter`	`object`	否	指定在語音識別過程中需要處理的敏感詞，並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。
`nls_config.channel_id`	`array[integer]`	否	指定在多音軌音訊檔案中需要辨識的音軌索引，索引從 0 開始。例如，`[0]` 表示辨識第一個音軌，`[0, 1]` 表示同時辨識第一和第二個音軌。若省略此參數，則預設處理第一個音軌。重要指定的每一個音軌都將獨立計費。例如，為單一檔案請求 `[0, 1]` 會產生兩筆獨立的費用。預設值：`[0]`。
`nls_config.diarization_enabled`	`boolean`	否	是否啟用說話人分離，預設关闭。僅適用於單聲道音訊，多聲道音訊不支援說話人分離。啟用該功能後，識別結果中將顯示`speaker_id`欄位，用於區分不同說話人。說明如果啟用說話人分離功能，建議音訊時長不超過2小時，否則可能導致識別失敗或逾時。預設值：false。有關 `speaker_id` 的範例，請參見辨識結果說明。
`nls_config.speaker_count`	`integer`	否	重要僅在開啟說話人分離功能（`diarization_enabled`設定為`true`）時生效。說話者數量參考值。取值範圍為 2 至 100 的整數（包含 2 和 100）。預設自動判斷說話者數量，若設定此項目，僅能輔助演算法盡量輸出指定人數，無法保證一定會輸出此人數。無預設值。
`nls_config.vocabulary_id`	`string`	否	預編譯熱詞清單 ID。需預先呼叫建立熱詞清單介面產生，辨識時傳入該 ID 即可使用清單中的熱詞。適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的場景。使用方法請參閱預編譯熱詞。
`nls_config.language_hints`	`array[string]`	否	設定待辨識語言代碼。若無法提前確定語種，可不設定，模型會自動識別語種。對於 Qwen-Audio-3.x-ASR-Flash-Filetrans 系列模型，最多支援設定 4 個值，即便設定超出 4 個，也僅前 4 個生效；對於 Fun-ASR 系列模型，僅支援設定 1 個值，即便設定多個，也僅第一個生效。點擊查看支援的語言代碼 - Qwen-Audio-3.x-ASR-Flash-Filetrans、fun-asr：- 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：斯洛伐克語
`nls_config.parameters`	`object`	否	設定其他參數，內容為 JSON Object 格式。

關鍵介面

NativeNui

initializeFileTrans

初始化語音轉錄 SDK 實例。在呼叫 release 前禁止重複初始化。

說明與即時語音辨識不同，非即時（錄音檔案）轉錄必須使用 initializeFileTrans 方法並傳入 INativeFileTransCallback 回呼，而不是 initialize。

此介面會阻塞呼叫執行緒，請在非 UI 執行緒中呼叫。

方法簽章

public initializeFileTrans(callback: INativeFileTransCallback,
                           parameters: string,
                           level: number,
                           save_log: boolean = false): number

參數說明

參數	類型	說明
`callback`	`INativeFileTransCallback`	檔案轉錄事件和資料回呼介面的實作。
`parameters`	`string`	JSON 字串，包含鑑權、連線和除錯參數。參見連線與控制參數。
`level`	`number`	控制 SDK 自身日誌的列印層級，取值為 Constants.LogLevel 列舉。
`save_log`	`boolean`	是否儲存本機日誌。若為 `true`，須在連接與控制參數中透過 `debug_path` 指定路徑，並可透過 `max_log_file_size` 設定檔案大小。

傳回值說明

setParams

此介面用於獨立設定或更新 nls_config 參數。如果所有參數都在 startFileTranscriber 中一次性提供，則無需呼叫此方法。

方法簽章

public setParams(params: string): number

參數說明

參數	類型	說明
`params`	`string`	語音辨識效果參數中的 `nls_config` 參數，`nls_config` 之外的參數不支援透過此方法進行設定。範例：`{ "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }`

傳回值說明

startFileTranscriber

開始識別。

方法簽章

public startFileTranscriber(params: string, task_id: ArrayBuffer): number

參數說明

參數	類型	說明
`params`	`string`	語音辨識效果參數。範例：`{ "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }`
`task_id`	`ArrayBuffer`	任務 ID 緩衝區。SDK 會將內部產生的隨機任務 ID 字串寫入該緩衝區，要求緩衝區位元組長度必須大於或等於 33 位元組（範例中使用 `new ArrayBuffer(64)`）。呼叫成功後可透過轉碼取得該任務的 `task_id`。

傳回值說明

queryFileTranscriber

此介面用於主動查詢一個非同步任務的目前狀態和結果。呼叫成功後，結果將透過 onFileTransEventCallback 回呼中的 EVENT_FILE_TRANS_QUERY_RESULT 事件返回。

方法簽章

public queryFileTranscriber(task_id: string): number

參數說明

參數	類型	說明
`task_id`	`string`	待查詢的任務 ID（由 `startFileTranscriber` 寫入緩衝區獲得）。

傳回值說明

cancelFileTranscriber

立即取消目前任務。

方法簽章

public cancelFileTranscriber(task_id: string): number

參數說明

參數	類型	說明
`task_id`	`string`	待取消的任務 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;

參數說明

參數	類型	說明
`event`	`Constants.NuiEvent`	回呼事件。
`resultCode`	`number`	僅在出現 `EVENT_ASR_ERROR` 事件時有效。
`finish`	`number`	任務是否結束標記。
`asrResult`	`AsrResult`	語音識別結果。
`taskId`	`string`	任務 ID。

Constants.NuiEvent

HarmonyOS SDK 中事件類型透過 Constants.NuiEvent 列舉定義，以下列出錄音檔案轉錄相關的事件：

事件	說明
`EVENT_FILE_TRANS_CONNECTED`	成功連線至服務。
`EVENT_FILE_TRANS_UPLOADED`	成功上傳待辨識音訊檔案。
`EVENT_FILE_TRANS_QUERY_RESULT`	查詢任務結果。
`EVENT_FILE_TRANS_RESULT`	辨識最終結果。
`EVENT_ASR_ERROR`	語音識別過程中發生錯誤。

輔助類型

Constants.LogLevel

level 參數的取值列舉：

值	說明
`LOG_LEVEL_VERBOSE`	最詳細日誌。
`LOG_LEVEL_DEBUG`	偵錯日誌。
`LOG_LEVEL_INFO`	一般資訊日誌（預設）。
`LOG_LEVEL_WARNING`	警告日誌。
`LOG_LEVEL_ERROR`	錯誤日誌。
`LOG_LEVEL_NONE`	關閉日誌。

結果下載

非即時語音辨識結果為非同步產生，EVENT_FILE_TRANS_RESULT 事件返回的回應中包含 transcription_url，辨識文本需透過該 URL 下載取得（JSON 格式）。請注意該 URL 具有有效期間，應及時下載。