Skip to main content

Paraformer 非即時語音識別 HarmonyOS SDK

使用 Paraformer 非即時語音識別 HarmonyOS SDK 將音視訊檔案轉換為文字。

使用者指南： 參見非即時語音識別。

快速開始

  1. 取得 API Key： 參見獲取與配置 API Key。建議將 API Key 設定到環境變數中。
    當需要為第三方應用程式或使用者提供臨時存取權限，或者希望嚴格控制敏感資料存取、刪除等高風險操作時，建議使用臨時 API Key。臨時 API Key 預設有效期為 60 秒，過期後需重新取得。
  2. 下載 SDK 並執行範例程式碼：
    • 下載最新 SDK 整合套件。
    • 解壓縮 TAR 套件。在 neonui 目錄中取得 HAR 格式 SDK，並新增至專案相依性。 若需以 C++ 接入，請使用 TAR 套件內的 native/libs 與 native/include 取得動態連結庫和標頭檔。
    • 使用 DevEco Studio 開啟專案。範例程式碼位於 DashParaformerFileTranscriberPage.ets 中，替換 API Key 後即可體驗功能。

呼叫步驟

同步模式

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

非同步模式

  1. 初始化 SDK。
  2. 按業務需求配置相關參數。
  3. 呼叫 startFileTranscriber 啟動辨識任務，並將 async_request 設為 true。
  4. 呼叫 queryFileTranscriber 主動查詢辨識進度或結果。
  5. 在 onFileTransEventCallback 回呼中監聽 EVENT_FILE_TRANS_QUERY_RESULT 事件，以取得目前查詢結果。
  6. 在 onFileTransEventCallback 回呼中監聽 EVENT_FILE_TRANS_RESULT 事件，以取得最終辨識結果。
  7. 呼叫 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"
}
  • 參數說明
參數類型是否必須說明
urlstring是服務位址，固定為 wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription。呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。
apikeystring是API Key。建議使用時效性短、安全性更高的 臨時 API 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 字串範例，參數未完整列出。請按實際需求在編碼時補充： 
{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"paraformer-v2",
        "disfluency_removal_enabled":false,
        "timestamp_alignment_enabled": false
    }
}
  • 參數說明
參數類型是否必須說明
file_urlsarray[string]是

音視訊檔案轉寫的 URL 清單，支援 HTTP / HTTPS 協定，單次請求僅支援1個 URL。 若錄音檔案儲存在阿里雲 OSS，使用 SDK 方式不支援使用以 oss:// 為前綴的臨時 URL。 - 音訊格式：aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv

由於音視訊格式及其變體眾多，技術上無法窮盡測試，API 不能保證所有格式均能夠被正確識別。請透過測試驗證您所提供的檔案能夠獲得正常的語音識別結果。

- 音訊取樣率 因模型而異： - paraformer-v2 支援任意取樣率 - paraformer-8k-v2 僅支援8kHz 取樣率 - 音訊檔案大小和時長：音訊檔案不超過2GB；時長在12小時以內。 如果希望處理的檔案超過了上述限制，可嘗試對檔案進行預處理以降低檔案尺寸。有關檔案預處理的最佳實踐可以查閱預處理視訊檔案以提高檔案轉寫效率（針對錄音檔案識別場景）。

async_requestboolean否語音辨識是否為非同步請求。預設值：false。取值範圍：- true：非同步請求 - false：同步請求
apikeystring否如果 連線與控制參數 的 apikey 使用的是 臨時 API Key，可在此處進行更新，以免逾時失效。
nls_configobject是語音識別核心設定物件，包含模型選擇、識別效果控制等關鍵參數。
nls_config.modelstring是語音識別 模型。
nls_config.language_hintsarray[string]否指定待識別語音的語言代碼。該參數僅適用於 paraformer-v2 模型。 預設值：["zh", "en"]。 支援的語言代碼： - zh: 中文 - en: 英文 - ja: 日語 - yue: 粵語 - ko: 韓語 - de：德語 - fr：法語 - ru：俄語
nls_config.disfluency_removal_enabledboolean否是否過濾語氣詞，如「嗯」、「啊」等。 預設值：false。 取值範圍： - true：過濾 - false：不過濾
nls_config.timestamp_alignment_enabledboolean否是否啟用時間戳記校正功能。 預設值：false。 取值範圍： - true：開啟 - false：關閉
nls_config.special_word_filterobject否指定在語音識別過程中需要處理的敏感詞，並支援對不同敏感詞設定不同的處理方式。 若未傳入該參數，系統將啟用系統內建的敏感詞過濾邏輯，識別結果中與阿里雲百煉敏感詞表匹配的詞語將被替換為等長的*。 若傳入該參數，則可實現以下敏感詞處理策略： - 替換為 *：將匹配的敏感詞替換為等長的 *； - 直接過濾：將匹配的敏感詞從識別結果中完全移除。 該參數的值應為一個 JSON Object，其結構如下所示： { "filter_with_signed": { "word_list": ["测试"] }, "filter_with_empty": { "word_list": ["开始", "发生"] }, "system_reserved_filter": true } JSON 欄位說明： - filter_with_signed - 類型：物件。 - 是否必填：否。 - 描述：設定需替換為*的敏感詞清單。識別結果中匹配的詞語將被等長的 * 替代。 - 範例：以上述 JSON 為例，「幫我測試一下這段程式碼」的語音識別結果將會是「幫我**一下這段程式碼」。 - 內部欄位： - word_list: 字串陣列，列出需被替換的敏感詞。 - filter_with_empty - 類型：物件。 - 是否必填：否。 - 描述：設定需從識別結果中移除（過濾）的敏感詞清單。識別結果中匹配的詞語將被完全刪除。 - 範例：以上述 JSON 為例，「比賽這就要開始了嗎？」的語音識別結果將會是「比賽這就要了嗎」。 - 內部欄位： - word_list: 字串陣列，列出需被完全移除（過濾）的敏感詞。 - system_reserved_filter - 類型：布林值。 - 是否必填：否。 - 預設值：true。 - 描述：是否啟用系統預設的敏感詞規則。設為true時，將同時啟用系統內建的敏感詞過濾邏輯，識別結果中與阿里雲百煉敏感詞表匹配的詞語將被替換為等長的*。
nls_config.channel_idarray[integer]否

指定在多音軌音訊檔案中需要辨識的音軌索引，索引從 0 開始。例如，[0] 表示辨識第一個音軌，[0, 1] 表示同時辨識第一和第二個音軌。若省略此參數，則預設處理第一個音軌。

指定的每一個音軌都將獨立計費。例如，為單一檔案請求 [0, 1] 會產生兩筆獨立的費用。

預設值：[0]。

nls_config.diarization_enabledboolean否

自動說話人分離，預設关闭。僅適用於單聲道音訊，多聲道音訊不支援說話人分離。啟用該功能後，識別結果中將顯示speaker_id欄位，用於區分不同說話人。

如果啟用說話人分離功能，建議音訊時長不超過2小時，否則可能導致識別失敗或逾時。

有關speaker_id的範例，請參見識別結果說明。

nls_config.speaker_countinteger否說話人數量參考值。若要使用該功能，需將diarization_enabled設定為true。 預設自動判斷說話人數量，如果設定此項，只能輔助演算法盡量輸出指定人數，無法保證一定會輸出此人數。 取值範圍：[2, 100]。該功能用於區分多個說話人，因此最少需要設定2。
nls_config.vocabulary_idstring否熱詞詞表 ID，用於提升特定詞彙的識別準確率。該參數適用於 v2 及更高版本模型。熱詞的使用方法請參見 定制热词。

關鍵介面

NativeNui

initializeFileTrans

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

setParams

此介面用於獨立設定或更新 nls_config 參數。如果所有參數都在 startFileTranscriber 中一次性提供，則無需呼叫此方法。
  • 方法簽章
public setParams(params: string): number
  • 參數說明
參數類型說明
paramsstring語音辨識效果參數中的 nls_config 參數，nls_config 之外的參數不支援透過此方法進行設定。範例：{ "nls_config": { "model":"paraformer-v2", "disfluency_removal_enabled":false, "timestamp_alignment_enabled": false } }
  • 傳回值說明

startFileTranscriber

開始識別。
  • 方法簽章
public startFileTranscriber(params: string, task_id: ArrayBuffer): number
  • 參數說明
參數類型說明
paramsstring語音辨識效果參數。範例：{ "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"paraformer-v2", "disfluency_removal_enabled":false, "timestamp_alignment_enabled": false } }
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。

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 具有有效期間，應及時下載。