本文介紹Paraformer即時語音辨識Python SDK的參數和介面細節。
前提條件
模型列表
| paraformer-realtime-v2 | paraformer-realtime-8k-v2 | |
|---|---|---|
| 適用情境 | 直播、會議等情境 | 電話客服、語音信箱等 8kHz 音訊識別情境 |
| 採樣率 | 任意 | 8kHz |
| 語種 | 中文(包含中文普通話和各種方言)、英文、日語、韓語、德語、法語、俄語支援的中文方言:上海話、吳語、閩南語、東北話、甘肅話、貴州話、河南話、湖北話、湖南話、江西話、寧夏話、山西話、陝西話、山東話、四川話、天津話、雲南話、粵語 | 中文 |
| 標點符號預測 | 預設支援,無需配置 | 預設支援,無需配置 |
| 逆文本正則化(ITN) | 預設支援,無需配置 | 預設支援,無需配置 |
| 定製熱詞 | 參見定製熱詞 | 參見定製熱詞 |
| 指定待識別語種 | 通過language_hints參數指定 | 不支援 |
| 情感識別 | 不支援 |
點擊查看使用方式 情感識別遵循如下約束:
emo_tag和emo_confidence欄位分別擷取當前句子的情感和情感信賴度。 |
快速開始
核心資源(client.audio.asr)提供了非流式調用和雙向流式調用介面。請根據實際需求選擇合適的調用方式:
- 非流式調用(
recognize_file):針對本地檔案進行識別,SDK自動分塊發送音頻並驅動到任務結束。適合處理錄製好的音頻。 - 雙向流式調用:可直接對音頻流進行識別,並即時輸出結果。音頻流可以來自外部裝置(如麥克風)或從本地檔案讀取。適合需要即時反饋的情境。
非流式調用
提交單個語音即時轉寫任務,通過傳入本地檔案的方式同步阻塞地拿到轉寫結果。
調用核心資源(client.audio.asr)的recognize_file方法綁定請求參數並傳入本地檔案路徑,迭代服務端事件擷取識別結果(RecognitionResult)。
點擊查看完整樣本
點擊查看完整樣本
recognize_file逐個產出服務端事件(Dict[str, Any]):事件類型位於event['header']['event'],識別文本位於event['payload']['output']['sentence'](sentence_end為true表示該句已結束,begin_time / end_time為時間戳記、words為字時間戳記等欄位見單句資訊(Sentence))。心跳與空文本事件仍會產出,可按需忽略。雙向流式會話中除events()外,還可通過results()只迭代識別結果幀(返回類型化的識別結果(RecognitionResult),心跳幀已過濾),詳見get_sentence方法說明。雙向流式調用
提交單個語音即時轉寫任務,通過迭代事件的方式流式輸出即時識別結果。
-
啟動流式語音辨識
調用核心資源(
client.audio.asr)的recognize方法建立識別會話並綁定請求參數,進入with上下文(自動調用start方法建立串連並發送任務)啟動流式語音辨識。 -
串流
迴圈調用會話的
send_audio_frame方法,將從本地檔案或裝置(如麥克風)讀取的二進位音頻流分段發送至服務端。發送與接收需並發進行:接收線程通過事件迭代(events()/results())迭代服務端事件,將識別結果即時返回給用戶端。 建議每次發送的音頻時間長度約為100毫秒,資料大小保持在1KB至16KB之間。 -
結束處理
調用會話的
stop方法結束語音辨識。 該方法只通知服務端輸入結束;接收線程需繼續消費events()直到task-finished事件以獲得最後的識別結果和統計資訊。ws層的錯誤會以DashScopeError異常拋出,可在發送/接收處使用try/except捕獲。
點擊查看完整樣本
點擊查看完整樣本
並發調用
在Python中,由於存在全域解譯器鎖,同一時刻只有一個線程可以執行Python代碼(雖然某些效能導向的庫可能會去除此限制)。如果您想更好地利用多核心電腦的計算資源,推薦您使用multiprocessing或concurrent.futures.ProcessPoolExecutor。 多線程在較高並發下會顯著增加SDK調用延遲。
請求參數
請求參數通過核心資源(client.audio.asr)的recognize/recognize_file方法進行設定:model、format、sample_rate、vocabulary_id、disfluency_removal_enabled為具名參數,其餘參數(如language_hints、semantic_punctuation_enabled)通過parameters字典傳入。
參數 | 類型 | 預設值 | 是否必須 | 說明 |
|---|---|---|---|---|
model | str | - | 是 | 用於即時語音辨識的模型(參見模型列表)。 |
sample_rate | int | - | 是 | 設定待識別音頻採樣率(單位Hz)。 因模型而異:
|
format | str | - | 是 | 設定待識別音頻格式。 支援的音頻格式:pcm、wav、mp3、opus、speex、aac、amr。 opus/speex:必須使用Ogg封裝; wav:必須為PCM編碼; amr:僅支援AMR-NB類型。 |
vocabulary_id | str | - | 否 | 設定熱詞ID,若未設定則不生效。v2及更高版本模型設定熱詞ID時使用該欄位。 在本次語音辨識中,將應用與該熱詞ID對應的熱詞資訊。具體使用方法請參見定製熱詞。 |
disfluency_removal_enabled | bool | False | 否 | 設定是否過濾語氣詞:
|
language_hints | list[str] | ["zh", "en"] | 否 | 設定待識別語言代碼。如果無法提前確定語種,可不設定,模型會自動識別語種。 目前支援的語言代碼:
該參數僅對支援多語言的模型生效(參見模型列表)。 |
semantic_punctuation_enabled | bool | False | 否 | 設定是否開啟語義斷句,預設關閉。
語義斷句準確性更高,適合會議轉寫情境;VAD(Voice Activity Detection,語音活動檢測)斷句延遲較低,適合互動情境。 通過調整 該參數僅在模型為v2及更高版本時生效。 |
max_sentence_silence | int | 800 | 否 | 設定VAD(Voice Activity Detection,語音活動檢測)斷句的靜音時間長度閾值(單位為ms)。 當一段語音後的靜音時間長度超過該閾值時,系統會判定該句子已結束。 參數範圍為200ms至6000ms,預設值為800ms。 該參數僅在 |
multi_threshold_mode_enabled | bool | False | 否 | 該開關開啟時(true)可以防止VAD斷句切割過長。預設關閉。 該參數僅在 |
punctuation_prediction_enabled | bool | True | 否 | 設定是否在識別結果中自動添加標點:
該參數僅在模型為v2及更高版本時生效。 |
heartbeat | bool | False | 否 | 當需要與服務端保持長串連時,可通過該開關進行控制:
該參數僅在模型為v2及更高版本時生效。 該欄位自 SDK 1.23.1 引入,2.0.1 及以上版本已包含。 |
inverse_text_normalization_enabled | bool | True | 否 | 設定是否開啟ITN(Inverse Text Normalization,逆文本正則化)。 預設開啟(true)。開啟後,中文數字將轉換為阿拉伯數字。 該參數僅在模型為v2及更高版本時生效。 |
介面參考
核心資源(client.audio.asr)
即時語音辨識能力掛載在client.audio.asr資源上:recognize建立雙向流式識別會話(Recognition),recognize_file對本地檔案一次性識別。
| 成員方法 | 方法簽名 | 說明 |
|---|---|---|
| recognize | 建立雙向流式識別會話,進入with上下文時自動調用start建立串連並發送任務。發送音頻與消費事件需並發進行(配合send_audio_frame、events()/results()和stop使用)。 | |
| recognize_file | 基於本地檔案的非流式調用:自動分塊發送音頻並驅動到任務結束,逐個產出服務端事件。該方法要求所識別檔案具有可讀許可權。 | |
| start | 開始語音辨識:建立串連、發送任務並等待task-started。進入with上下文時自動調用,啟動成功後才能發送音頻。 | |
| send_audio_frame | 推送音頻。每次推送的音頻流不宜過大或過小,建議每包音頻時間長度為100ms左右,大小在1KB~16KB之間。識別結果通過事件迭代(events()/results())擷取。 | |
| stop | 停止語音辨識:只通知服務端輸入結束,接收線程需繼續消費events()直到task-finished事件。 | |
| events / results | 迭代服務端事件:events()產出原始事件dict(識別文本位於payload.output.sentence);results()只產出識別結果幀,返回識別結果(RecognitionResult)類型化對象(心跳幀已過濾)。 | |
| close | 關閉識別會話。退出with上下文時自動調用。 | |
| request_id / first_package_delay / last_package_delay | 擷取request_id、首包延遲(從發送第一包音頻到收到首包識別結果延遲)和尾包延遲(發送stop指令到最後一包識別結果下發耗時)。在任務完成後使用,會話關閉後仍可讀取。 |
事件迭代(events()/results())
雙向流式調用時,服務端會通過事件的方式,將關鍵流程資訊和資料返回給用戶端。您需要在接收線程中迭代會話的events()(原始事件dict)或results()(類型化識別結果幀),處理服務端返回的資訊或者資料。
點擊查看樣本
點擊查看樣本
| 事件/迭代方法 | 產出內容 | 傳回值 | 描述 |
|---|---|---|---|
task-started事件 | 無 | 由start()內部讀取,啟動返回時保存在last_response中,不會由events()再次產出。 | |
event:服務端事件dict | 迭代器 | 當服務有回複時產出事件。識別結果位於payload.output.sentence,可能為心跳或空文本事件,應用可按需忽略。請由一個接收線程持續消費,不要並發建立多個讀取者。 | |
result:識別結果(RecognitionResult) | 迭代器 | 只產出識別結果幀(心跳幀已過濾),全部識別結果返回後迭代結束。 | |
DashScopeError異常 | 無 | 發生異常時在發送/接收線程中拋出,可使用try/except捕獲。 | |
task-finished事件 | 無 | 當服務已經完成全部識別後由events()產出,隨後迭代結束;發送stop()後仍須讀取此事件。 |
響應結果
識別結果(RecognitionResult)
RecognitionResult代表會話results()迭代產出的一次識別結果幀(雙向流式調用與非流式調用均可使用;events()產出的是原始事件dict,如需該類型化視圖請改用results())。
| 成員方法 | 方法簽名 | 說明 |
|---|---|---|
| get_sentence | 擷取當前識別的句子及時間戳記資訊,此方法傳回型別為Dict[str, Any](單句資訊)。詳情請參見單句資訊(Sentence)。 | |
| request_id | 當前事件對應的請求request_id。 | |
| is_sentence_end | 判斷當前句子是否已經結束(句子攜帶end_time時為True)。 |
單句資訊(Sentence)
Sentence類成員如下:
參數 | 類型 | 說明 |
|---|---|---|
begin_time | int | 句子開始時間,單位為ms。 |
end_time | int | 句子結束時間,單位為ms。 |
text | str | 識別文本。 |
words | 字時間戳記資訊(Word)的list集合 | 字時間戳記資訊。 |
emo_tag | str | 當前句子的情感:
情感識別遵循如下約束:
|
emo_confidence | float | 當前句子識別情感的信賴度,取值範圍:[0.0,1.0]。值越大表示信賴度越高。 情感識別遵循如下約束:
|
字時間戳記資訊(Word)
Word類成員如下:
參數 | 類型 | 說明 |
|---|---|---|
begin_time | int | 字開始時間,單位為ms。 |
end_time | int | 字結束時間,單位為ms。 |
text | str | 字。 |
punctuation | str | 標點。 |