Alibaba Cloud Model Studio：Paraformer 即時語音識別 HarmonyOS SDK

使用 Paraformer 即時語音識別 HarmonyOS SDK 將語音轉換為文字。

請將 {WorkspaceId} 替換為真實的 Workspace ID。現有網域仍可正常使用。

使用者指南：關於模型介紹和選型建議請參見 即時語音識別-Fun-ASR/Paraformer。

線上體驗：僅 paraformer-realtime-v2、paraformer-realtime-8k-v2 和 paraformer-realtime-v1 支援線上體驗。

快速開始

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 開啟專案。範例程式碼位於 DashParaformerSpeechTranscriberPage.ets 中，替換 API Key 後即可體驗功能。

呼叫步驟

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

請求參數

連接與控制參數

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

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

• 參數說明

參數	類型	是否必須	說明
url	string	是	服務位址，固定為 wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference。呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。
apikey	string	是	API Key。建議使用時效性短、安全性更高的 臨時 API Key，以降低長期有效金鑰洩露的風險。
service_mode	string	是	執行模式。即時語音識別固定為 "1"。
device_id	string	是	用於標識終端使用者的唯一字串，可設為應用程式內使用者 ID 或用戶端產生的裝置唯一識別碼。此 ID 主要用於日誌追蹤和問題排查。
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	number	否	設定記錄檔的最大位元組數。此參數僅在呼叫 initialize 介面時將 save_log 設為 true 時生效。預設值：104857600（100 * 1024 * 1024 位元組，即 100MiB）。
log_track_level	number	否	控制透過日誌回呼（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）的日誌才會被回呼。

語音識別效果參數

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

{
    "service_type": 4,
    "nls_config": {
        "model": "paraformer-realtime-v2",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}

• 參數說明

一級參數	類型	是否必須	說明
service_type	int	是	語音服務類型。即時語音識別固定為 4。
nls_config	object	是	語音識別核心設定物件，包含模型選擇、識別效果控制等關鍵參數。
nls_config.model	string	是	語音識別 模型。
nls_config.sr_format	string	是	待識別音訊格式。支援的音訊格式：pcm、wav、opus。 重要 opus：必須為 PCM 編碼，SDK 內部會將其編碼成 OPUS 格式； wav/pcm：必須為 PCM 編碼。
nls_config.sample_rate	int	是	待識別音訊取樣率（單位 Hz）。因模型而異： - paraformer-realtime-v2 支援任意取樣率。 - paraformer-realtime-v1 僅支援 16000Hz 取樣。 - paraformer-realtime-8k-v2 僅支援 8000Hz 取樣率。 - paraformer-realtime-8k-v1 僅支援 8000Hz 取樣率。
nls_config.disfluency_removal_enabled	boolean	否	是否過濾語氣詞，如「嗯」、「啊」等。預設值：false。
nls_config.language_hints	array[string]	否	設定待識別語言代碼。如果無法提前確定語種，可不設定，模型會自動識別語種。支援的語言代碼： - zh: 中文 - en: 英文 - ja: 日語 - yue: 粵語 - ko: 韓語 - de：德語 - fr：法語 - ru：俄語 此參數僅對支援多語言的 模型 生效
nls_config.semantic_punctuation_enabled	boolean	否	設定斷句模式。預設值：false。取值範圍： - true：啟用語意斷句，停用 VAD 斷句。 - false：啟用 VAD 斷句，停用語意斷句。語意斷句準確性較高，適合會議轉錄場景；VAD（Voice Activity Detection，語音活動偵測）斷句延遲較低，適合即時互動場景。此參數僅在模型為 v2 及更高版本時生效。
nls_config.max_sentence_silence	int	否	VAD（Voice Activity Detection，語音活動偵測）斷句的靜音時長閾值（單位為 ms）。預設值：800。取值範圍：[200, 6000]。當一段語音後的靜音時長超過該閾值時，系統會判定該句子已結束。此參數僅在 semantic_punctuation_enabled 參數為 false 且模型為 v2 及更高版本時生效。
nls_config.multi_threshold_mode_enabled	boolean	否	是否啟用防過長切割模式。啟用可防止 VAD 斷句切割過長。預設值：false（停用）。取值範圍： - true：啟用 - false：停用 此參數僅在 semantic_punctuation_enabled 參數為 false 且模型為 v2 及更高版本時生效。
nls_config.punctuation_prediction_enabled	boolean	否	是否在識別結果中自動新增標點符號。預設值：true（是）。取值範圍： - true：是 - false：否 該參數僅在模型為 v2 及更高版本時生效。
nls_config.heartbeat	boolean	否	是否與伺服器端保持長連線。預設值：false。取值範圍： - true：在持續傳送靜音音訊的情況下，可保持與伺服器端的連線不中斷。 - false：即使持續傳送靜音音訊，連線也將在一定時間後因逾時而中斷。該逾時為伺服器端預設行為，用戶端不可設定。此參數僅在模型為 v2 及更高版本時生效。
nls_config.inverse_text_normalization_enabled	boolean	否	是否啟用 ITN（Inverse Text Normalization，逆文字正規化）。啟用後，中文數字將轉換為阿拉伯數字。預設值：true（啟用）。取值範圍： - true：啟用 - false：停用 此參數僅在模型為 v2 及更高版本時生效。
nls_config.vocabulary_id	string	否	熱詞詞表 ID，用於提升特定詞彙的識別準確率。該參數適用於 v2 及更高版本模型。熱詞的使用方法請參見 定制热词。
nls_config.resources	array[object]	否	熱詞資源設定，用於 v1 版本模型。功能與 vocabulary_id 相同，但設定方式不同：resources 是一個物件陣列，其每個元素包含 resource_id 和 resource_type 欄位： - resource_id：string 類型，熱詞 ID。 - resource_type：string 類型，取值為固定字串 "asr_phrase"。範例：{ "nls_config": { "resources": [ { "resource_id": "xxxxxxxxxxxx", "resource_type": "asr_phrase" } ] } } 熱詞的使用方法請參見 Paraformer 語音識別熱詞客製化與管理。

關鍵介面

NativeNui

initialize

初始化語音識別 SDK 執行個體。在呼叫 release 前禁止重複初始化。

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

• 方法簽章

public initialize(callback: INativeNuiCallback,
                  parameters: string,
                  level: number,
                  save_log: boolean = false): number

• 參數說明

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

• 傳回值說明

setParams

以 JSON 格式設定語音識別效果參數。請在 startDialog 之前呼叫。

• 方法簽章

public setParams(params: string): number

• 參數說明

參數	類型	說明
params	string	語音識別效果參數。

• 傳回值說明

startDialog

開始識別。

• 方法簽章

public startDialog(vad_mode: Constants.VadMode, dialog_params: string): number

• 參數說明

參數	類型	說明
vad_mode	Constants.VadMode	VAD 模式。固定為 Constants.VadMode.TYPE_P2T。
dialog_params	string	當 連接與控制參數 的 apikey 參數對應的 臨時 API Key 過期時，可在此處進行更新。內容為 JSON 格式：typescript { "apikey": "st-****" }

• 傳回值說明

stopDialog

結束識別，呼叫該介面後，伺服器將返回最終識別結果並結束任務。

• 方法簽章

public stopDialog(): number

• 傳回值說明

cancelDialog

立即結束識別，呼叫該介面後，不等待伺服器返回最終識別結果就立即結束任務。

• 方法簽章

public cancelDialog(): number

• 傳回值說明

release

釋放 SDK 的所有內部資源。呼叫後，SDK 執行個體將不可用；如需再次使用，必須重新呼叫 initialize 進行初始化。

• 方法簽章

public release(): number

• 傳回值說明

GetVersion

取得當前 SDK 版本資訊。

• 方法簽章

public GetVersion(): string

• 傳回值說明

當前 SDK 版本資訊。

INativeNuiCallback

用於監聽即時語音識別過程中的事件、音訊狀態、音量和日誌等回調。

onNuiEventCallback

監聽識別事件並取得語音識別結果。

• 方法簽章

onNuiEventCallback: (event: Constants.NuiEvent, resultCode: number, arg2: number,
                    kwsResult: KwsResult, asrResult: AsrResult) => void;

• 參數說明

參數	類型	說明
event	Constants.NuiEvent	回呼事件。
resultCode	number	僅在出現 EVENT_ASR_ERROR 事件時有效。
asrResult	AsrResult	語音識別結果。
kwsResult	KwsResult	語音喚醒功能。無需關注此參數。
arg2	number	保留參數。

onNuiAudioStateChanged

監聽音訊狀態變化，以確定何時開始、暫停或停止錄音。

• 方法簽章

onNuiAudioStateChanged: (state: Constants.AudioState) => void

• AudioState 狀態說明

狀態	說明
STATE_OPEN	互動啟動，可以開啟錄音裝置進行錄音。
STATE_PAUSE	互動暫停，可以暫停錄音。
STATE_CLOSE	互動停止，可以徹底關閉錄音裝置。

onNuiAudioRMSChanged

監聽錄音音量變化，可用於 UI 展示。

• 方法簽章

onNuiAudioRMSChanged: (val: number) => number

• 參數說明

參數	類型	說明
val	number	錄音資料的音量值。輸出範圍一般為 [-160, 0]。

onNuiNeedAudioData

識別開始後，該回調會被連續觸發，用於持續提供待識別的音訊資料。

• 方法簽章

onNuiNeedAudioData: (buffer: ArrayBuffer) => number

• 參數說明

參數	類型	說明
buffer	ArrayBuffer	填入的音訊資料。SDK 會按 buffer.byteLength 取得期望讀取的位元組數。

• 傳回值說明

實際填入的位元組數。返回 <=0 表示出錯或無資料。

onNuiLogTrackCallback

監聽 SDK 的追蹤日誌，用於問題定位和除錯。

onNuiLogTrackCallback: (level: Constants.LogLevel, log: string) => void

Constants.NuiEvent

HarmonyOS SDK 中事件類型透過 Constants.NuiEvent 列舉定義，以下列出即時語音識別相關的事件：

事件	說明
EVENT_TRANSCRIBER_STARTED	任務啟動成功。
EVENT_VAD_START	任務啟動後即觸發此事件。不代表偵測到人聲起點。
EVENT_VAD_END	偵測到人聲終點。
EVENT_ASR_PARTIAL_RESULT	語音識別中間結果。
EVENT_ASR_RESULT	完整的語音識別結果。
EVENT_ASR_ERROR	語音識別過程中發生錯誤。
EVENT_MIC_ERROR	因連續 2 秒未收到任何音訊資料而觸發。
EVENT_SENTENCE_START	偵測到一句話開始。
EVENT_SENTENCE_END	偵測到一句話結束，此時會返回一句完整的識別結果。
EVENT_TRANSCRIBER_COMPLETE	語音識別結束。

輔助類型

Constants.LogLevel

level 參數的取值列舉：

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

音訊裝置管理

與 Android 使用 AudioRecord 不同，HarmonyOS 透過 @kit.AudioKit 的 AudioCapturer 進行音訊擷取。本產品範例已封裝為 AudioRecorder.ets 工具類別，可直接重複使用。

• 建立：audio.createAudioCapturer(capturerOptions) 非同步建立，取樣率固定 16kHz、16bit、單聲道（SAMPLE_RATE_16000/CHANNEL_1/SAMPLE_FORMAT_S16LE/ENCODING_TYPE_RAW）。
• 資料事件：capturer.on('readData', (buffer: ArrayBuffer) => void) 持續獲得錄音資料，資料須先緩入佇列，由 onNuiNeedAudioData 回調按需拉取。
• 狀態事件：capturer.on('stateChange', (state: audio.AudioState) => void)，STATE_RUNNING 表示開始錄音，STATE_STOPPED 表示停止。
• 控制：start() 開始、stop() 停止、release() 釋放。

權限宣告

使用錄音功能需在 module.json5 中宣告麥克風權限：

{
  "requestPermissions": [
    { "name": "ohos.permission.MICROPHONE" }
  ]
}