Skip to main content

Paraformer即時語音辨識Python SDK

本文介紹Paraformer即時語音辨識Python SDK的參數和介面細節。

本文檔僅適用於華北2(北京)地區。如需使用模型,需使用華北2(北京)地區的API Key。
阿里雲百鍊為華北2(北京)地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com。{WorkspaceId}需要替換為真實的Workspace ID。現有網域名稱仍可正常使用。
使用者指南:關於模型介紹和選型建議請參見即時語音辨識-Fun-ASR/Paraformer。

前提條件

已開通服務並擷取與配置 API Key。請配置API Key到環境變數,而非寫入程式碼在代碼中,防範因代碼泄露導致的安全風險。
當您需要為第三方應用或使用者提供臨時存取權限,或者希望嚴格控制敏感性資料訪問、刪除等高風險操作時,建議使用臨時鑒權Token。與長期有效 API Key 相比,臨時鑒權 Token 具備時效性短(60秒)、安全性高的特點,適用於臨時調用情境,能有效降低API Key泄露的風險。使用方式:在代碼中,將原本用於鑒權的 API Key 替換為擷取到的臨時鑒權 Token 即可。

模型列表

paraformer-realtime-v2paraformer-realtime-8k-v2
適用情境直播、會議等情境電話客服、語音信箱等 8kHz 音訊識別情境
採樣率任意8kHz
語種中文(包含中文普通話和各種方言)、英文、日語、韓語、德語、法語、俄語支援的中文方言:上海話、吳語、閩南語、東北話、甘肅話、貴州話、河南話、湖北話、湖南話、江西話、寧夏話、山西話、陝西話、山東話、四川話、天津話、雲南話、粵語中文
標點符號預測預設支援,無需配置預設支援,無需配置
逆文本正則化(ITN)預設支援,無需配置預設支援,無需配置
定製熱詞參見定製熱詞參見定製熱詞
指定待識別語種通過language_hints參數指定不支援
情感識別不支援
情感識別遵循如下約束:
  • 僅限paraformer-realtime-8k-v2模型。
  • 必須關閉語義斷句(可通過請求參數semantic_punctuation_enabled控制)。語義斷句預設為關閉狀態。
  • 只有在識別結果(RecognitionResult)的is_sentence_end方法返回結果為True時才顯示情感識別結果。
情感識別結果擷取方式:通過單句資訊(Sentence)的emo_tag和emo_confidence欄位分別擷取當前句子的情感和情感信賴度。

快速開始

核心資源(client.audio.asr)提供了非流式調用和雙向流式調用介面。請根據實際需求選擇合適的調用方式:
  • 非流式調用(recognize_file):針對本地檔案進行識別,SDK自動分塊發送音頻並驅動到任務結束。適合處理錄製好的音頻。
  • 雙向流式調用:可直接對音頻流進行識別,並即時輸出結果。音頻流可以來自外部裝置(如麥克風)或從本地檔案讀取。適合需要即時反饋的情境。

非流式調用

提交單個語音即時轉寫任務,通過傳入本地檔案的方式同步阻塞地拿到轉寫結果。 調用核心資源(client.audio.asr)的recognize_file方法綁定請求參數並傳入本地檔案路徑,迭代服務端事件擷取識別結果(RecognitionResult)。
import os
import dashscope

# 以下為華北2(北京)地區的配置,調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。
client = dashscope.Client(
    # 若沒有將API Key配置到環境變數中,請將下行替換為自己的API Key:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# 識別本地語音檔案:recognize_file自動分塊發送音頻並驅動到任務結束
for event in client.audio.asr.recognize_file(
        '{YOUR_AUDIO_FILE}',
        model='paraformer-realtime-v2',
        format='wav',
        sample_rate=16000,
        # “language_hints”只支援paraformer-realtime-v2模型
        parameters={'language_hints': ['zh', 'en']}):
    payload = event.get('payload') or {}
    sentence = (payload.get('output') or {}).get('sentence') or {}
    if sentence.get('text') and not sentence.get('heartbeat'):
        print('識別結果:', sentence['text'])
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方法說明。

雙向流式調用

提交單個語音即時轉寫任務,通過迭代事件的方式流式輸出即時識別結果。
  1. 啟動流式語音辨識 調用核心資源(client.audio.asr)的recognize方法建立識別會話並綁定請求參數,進入with上下文(自動調用start方法建立串連並發送任務)啟動流式語音辨識。
  2. 串流 迴圈調用會話的send_audio_frame方法,將從本地檔案或裝置(如麥克風)讀取的二進位音頻流分段發送至服務端。發送與接收需並發進行:接收線程通過事件迭代(events()/results())迭代服務端事件,將識別結果即時返回給用戶端。 建議每次發送的音頻時間長度約為100毫秒,資料大小保持在1KB至16KB之間。
  3. 結束處理 調用會話的stop方法結束語音辨識。 該方法只通知服務端輸入結束;接收線程需繼續消費events()直到task-finished事件以獲得最後的識別結果和統計資訊。ws層的錯誤會以DashScopeError異常拋出,可在發送/接收處使用try/except捕獲。
import os
import signal  # for keyboard events handling (press "Ctrl+C" to terminate recording)
import sys

import dashscope
import pyaudio
from concurrent.futures import ThreadPoolExecutor

# 以下為華北2(北京)地區的配置,調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。
client = dashscope.Client(
    # 若沒有將API Key配置到環境變數中,請將下行替換為自己的API Key:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

mic = None
stream = None

# Set recording parameters
sample_rate = 16000  # sampling rate (Hz)
channels = 1  # mono channel
dtype = 'int16'  # data type
format_pcm = 'pcm'  # the format of the audio data
block_size = 3200  # number of frames per buffer

# Real-time speech recognition event receiver
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('Recognition text: ', sentence['text'])
            if sentence.get('sentence_end'):
                print(
                    'Recognition sentence end, request_id:%s, usage:%s'
                    % (rec.request_id, rec.usage))

def signal_handler(sig, frame):
    print('Ctrl+C pressed, stop recognition ...')
    # Stop recognition
    recognition.stop()
    print('Recognition stopped.')
    print(
        '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
        .format(
            recognition.request_id,
            recognition.first_package_delay,
            recognition.last_package_delay,
        ))
    # Forcefully exit the program
    sys.exit(0)

# main function
if __name__ == '__main__':
    print('Initializing ...')

    signal.signal(signal.SIGINT, signal_handler)
    print("Press 'Ctrl+C' to stop recording and recognition...")

    # Call recognition service, you can customize the recognition parameters, like model, format,
    # sample_rate
    with client.audio.asr.recognize(
            model='paraformer-realtime-v2',
            format=format_pcm,
            # 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr', you can check the supported formats in the document
            sample_rate=sample_rate,
            # support 8000, 16000
            parameters={'semantic_punctuation_enabled': False},
    ) as recognition:
        # Open the microphone
        mic = pyaudio.PyAudio()
        stream = mic.open(format=pyaudio.paInt16,
                          channels=1,
                          rate=16000,
                          input=True)
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, recognition)
            try:
                # Send audio from the microphone until "Ctrl+C" is pressed
                while stream:
                    data = stream.read(3200, exception_on_overflow=False)
                    recognition.send_audio_frame(data)
                recognition.stop()
                receiver.result()
            finally:
                # close must run inside the pool context to unblock the receiver
                recognition.close()
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None

並發調用

在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)。

因模型而異:

  • paraformer-realtime-v2支援任意採樣率。

  • paraformer-realtime-8k-v2僅支援8000Hz採樣率。

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

否

設定是否過濾語氣詞:

  • true:過濾語氣詞

  • false(預設):不過濾語氣詞

language_hints

list[str]

["zh", "en"]

否

設定待識別語言代碼。如果無法提前確定語種,可不設定,模型會自動識別語種。

目前支援的語言代碼:

  • zh: 中文

  • en: 英文

  • ja: 日語

  • yue: 粵語

  • ko: 韓語

  • de:德語

  • fr:法語

  • ru:俄語

該參數僅對支援多語言的模型生效(參見模型列表)。

semantic_punctuation_enabled

bool

False

否

設定是否開啟語義斷句,預設關閉。

  • true:開啟語義斷句,關閉VAD(Voice Activity Detection,語音活動檢測)斷句。

  • false(預設):開啟VAD(Voice Activity Detection,語音活動檢測)斷句,關閉語義斷句。

語義斷句準確性更高,適合會議轉寫情境;VAD(Voice Activity Detection,語音活動檢測)斷句延遲較低,適合互動情境。

通過調整semantic_punctuation_enabled參數,可以靈活切換語音辨識的斷句方式以適應不同情境需求。

該參數僅在模型為v2及更高版本時生效。

max_sentence_silence

int

800

否

設定VAD(Voice Activity Detection,語音活動檢測)斷句的靜音時間長度閾值(單位為ms)。

當一段語音後的靜音時間長度超過該閾值時,系統會判定該句子已結束。

參數範圍為200ms至6000ms,預設值為800ms。

該參數僅在semantic_punctuation_enabled參數為false(VAD斷句)且模型為v2及更高版本時生效。

multi_threshold_mode_enabled

bool

False

否

該開關開啟時(true)可以防止VAD斷句切割過長。預設關閉。

該參數僅在semantic_punctuation_enabled參數為false(VAD斷句)且模型為v2及更高版本時生效。

punctuation_prediction_enabled

bool

True

否

設定是否在識別結果中自動添加標點:

  • true(預設):是

  • false:否

該參數僅在模型為v2及更高版本時生效。

heartbeat

bool

False

否

當需要與服務端保持長串連時,可通過該開關進行控制:

  • true:在持續發送靜音音訊情況下,可保持與服務端的串連不中斷。

  • false(預設):即使持續發送靜音音頻,串連也將在一定時間後因逾時而斷開。

    靜音音頻指的是在音頻檔案或資料流中沒有聲音訊號的內容。靜音音頻可以通過多種方法產生,例如使用音頻編輯軟體如Audacity或Adobe Audition,或者通過命令列工具如FFmpeg。

該參數僅在模型為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
def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition
建立雙向流式識別會話,進入with上下文時自動調用start建立串連並發送任務。發送音頻與消費事件需並發進行(配合send_audio_frame、events()/results()和stop使用)。
recognize_file
def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]
基於本地檔案的非流式調用:自動分塊發送音頻並驅動到任務結束,逐個產出服務端事件。該方法要求所識別檔案具有可讀許可權。
start
def start(self)
開始語音辨識:建立串連、發送任務並等待task-started。進入with上下文時自動調用,啟動成功後才能發送音頻。
send_audio_frame
def send_audio_frame(self, buffer: bytes)
推送音頻。每次推送的音頻流不宜過大或過小,建議每包音頻時間長度為100ms左右,大小在1KB~16KB之間。識別結果通過事件迭代(events()/results())擷取。
stop
def stop(self)
停止語音辨識:只通知服務端輸入結束,接收線程需繼續消費events()直到task-finished事件。
events / results
def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]
迭代服務端事件:events()產出原始事件dict(識別文本位於payload.output.sentence);results()只產出識別結果幀,返回識別結果(RecognitionResult)類型化對象(心跳幀已過濾)。
close
def close(self)
關閉識別會話。退出with上下文時自動調用。
request_id / first_package_delay / last_package_delay
rec.request_id
rec.first_package_delay
rec.last_package_delay
擷取request_id、首包延遲(從發送第一包音頻到收到首包識別結果延遲)和尾包延遲(發送stop指令到最後一包識別結果下發耗時)。在任務完成後使用,會話關閉後仍可讀取。

事件迭代(events()/results())

雙向流式調用時,服務端會通過事件的方式,將關鍵流程資訊和資料返回給用戶端。您需要在接收線程中迭代會話的events()(原始事件dict)或results()(類型化識別結果幀),處理服務端返回的資訊或者資料。
# 迭代原始事件:識別文本位於 payload.output.sentence
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('識別文本:', sentence['text'])


# 或只迭代識別結果幀(返回 RecognitionResult,心跳幀已過濾)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('識別文本:', sentence['text'])
事件/迭代方法產出內容傳回值描述
event["header"]["event"] == "task-started"
task-started事件無由start()內部讀取,啟動返回時保存在last_response中,不會由events()再次產出。
def events(self) -> Iterator[Dict]
event:服務端事件dict迭代器當服務有回複時產出事件。識別結果位於payload.output.sentence,可能為心跳或空文本事件,應用可按需忽略。請由一個接收線程持續消費,不要並發建立多個讀取者。
def results(self) -> Iterator[RecognitionResult]
result:識別結果(RecognitionResult)迭代器只產出識別結果幀(心跳幀已過濾),全部識別結果返回後迭代結束。
try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
DashScopeError異常無發生異常時在發送/接收線程中拋出,可使用try/except捕獲。
event["header"]["event"] == "task-finished"
task-finished事件無當服務已經完成全部識別後由events()產出,隨後迭代結束;發送stop()後仍須讀取此事件。

響應結果

識別結果(RecognitionResult)

RecognitionResult代表會話results()迭代產出的一次識別結果幀(雙向流式調用與非流式調用均可使用;events()產出的是原始事件dict,如需該類型化視圖請改用results())。
成員方法方法簽名說明
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]
擷取當前識別的句子及時間戳記資訊,此方法傳回型別為Dict[str, Any](單句資訊)。詳情請參見單句資訊(Sentence)。
request_id
result.request_id
當前事件對應的請求request_id。
is_sentence_end
def is_sentence_end(self) -> bool
判斷當前句子是否已經結束(句子攜帶end_time時為True)。

單句資訊(Sentence)

Sentence類成員如下:

參數

類型

說明

begin_time

int

句子開始時間,單位為ms。

end_time

int

句子結束時間,單位為ms。

text

str

識別文本。

words

字時間戳記資訊(Word)的list集合

字時間戳記資訊。

emo_tag

str

當前句子的情感:

  • positive:正面情感,如開心、滿意

  • negative:負面情感,如憤怒、沉悶

  • neutral:無明顯情感

情感識別遵循如下約束:

  • 僅限paraformer-realtime-8k-v2模型。

  • 必須關閉語義斷句(可通過請求參數semantic_punctuation_enabled控制)。語義斷句預設為關閉狀態。

  • 只有在識別結果(RecognitionResult)的is_sentence_end方法返回結果為True時才顯示情感識別結果。

emo_confidence

float

當前句子識別情感的信賴度,取值範圍:[0.0,1.0]。值越大表示信賴度越高。

情感識別遵循如下約束:

  • 僅限paraformer-realtime-8k-v2模型。

  • 必須關閉語義斷句(可通過請求參數semantic_punctuation_enabled控制)。語義斷句預設為關閉狀態。

  • 只有在識別結果(RecognitionResult)的is_sentence_end方法返回結果為True時才顯示情感識別結果。

字時間戳記資訊(Word)

Word類成員如下:

參數

類型

說明

begin_time

int

字開始時間,單位為ms。

end_time

int

字結束時間,單位為ms。

text

str

字。

punctuation

str

標點。

更多範例

更多樣本,請參見GitHub。

錯誤碼

如遇報錯問題,請參見錯誤碼進行排查。 若問題仍未解決,請加入開發人員群反饋遇到的問題,並提供Request ID,以便進一步排查問題。