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自动分块发送音频并驱动到任务结束。适合处理录制好的音频。
  • 双向流式调用:可直接对音频流进行识别,并实时输出结果。音频流可以来自外部设备(如麦克风)或从本地文件读取。适合需要即时反馈的场景。

非流式调用

提交单个语音实时转写任务,通过传入本地文件的方式同步阻塞地拿到转写结果。
image
调用核心资源(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方法说明。

双向流式调用

提交单个语音实时转写任务,通过迭代事件的方式流式输出实时识别结果。
image
  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,以便进一步排查问题。