跳转到主要内容
实时

Fun-ASR realtime Python SDK

实时语音识别 Python SDK

使用指南: 模型选择请参见实时语音识别

快速开始

Recognition 类支持非流式和双向流式两种调用方式。
  • 非流式调用: 识别本地文件,一次性返回完整结果。
  • 双向流式调用: 识别音频流并实时返回结果。音频流可来自麦克风或本地文件。

非流式调用

提交单个音频文件的语音识别任务,阻塞等待直到返回结果。 实例化 Recognition 类,设置请求参数,调用 call 获取识别结果 (RecognitionResult)
示例使用的音频文件:asr_example.wav
from http import HTTPStatus
import dashscope
from dashscope.audio.asr import Recognition
import os

# 如果未配置环境变量,请将下一行替换为:dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

dashscope.base_websocket_api_url='wss://dashscope.aliyuncs.com/api-ws/v1/inference'

recognition = Recognition(model='fun-asr-realtime',
                          format='wav',
                          sample_rate=16000,
                          callback=None)
result = recognition.call('asr_example.wav')
if result.status_code == HTTPStatus.OK:
  print('识别结果:')
  print(result.get_sentence())
else:
  print('错误:', result.message)

print(
  '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
  .format(
    recognition.get_last_request_id(),
    recognition.get_first_package_delay(),
    recognition.get_last_package_delay(),
  ))

双向流式调用

提交语音识别任务,通过回调接收结果。
1

启动流式识别

2

发送音频

反复调用 send_audio_frame 发送来自本地文件或设备(如麦克风)的二进制音频数据。服务端通过 on_event 回调实时返回结果。每段音频约 100 ms,大小 1-16 KB。
3

停止识别

调用 stop 结束识别。该方法会阻塞等待,直到触发 on_completeon_error
  • 识别麦克风语音
  • 识别本地音频文件
import os
import signal  # 用于处理键盘事件(按 Ctrl+C 终止录音)
import sys

import dashscope
import pyaudio
from dashscope.audio.asr import *

mic = None
stream = None

# 设置录音参数
sample_rate = 16000  # 采样率(Hz)
channels = 1  # 单声道
dtype = 'int16'  # 数据类型
format_pcm = 'pcm'  # 音频数据格式
block_size = 3200  # 每个缓冲区的帧数


# 实时语音识别回调
class Callback(RecognitionCallback):
  def on_open(self) -> None:
    global mic
    global stream
    print('RecognitionCallback open.')
    mic = pyaudio.PyAudio()
    stream = mic.open(format=pyaudio.paInt16,
                          channels=1,
                          rate=16000,
                          input=True)

  def on_close(self) -> None:
    global mic
    global stream
    print('RecognitionCallback close.')
    stream.stop_stream()
    stream.close()
    mic.terminate()
    stream = None
    mic = None

  def on_complete(self) -> None:
    print('RecognitionCallback completed.')  # 识别完成

  def on_error(self, result: RecognitionResult) -> None:
    print('RecognitionCallback task_id: ', result.request_id)
    print('RecognitionCallback error: ', result.message)
    # 如果音频流正在运行,停止并关闭
    if 'stream' in globals() and stream.is_active():
      stream.stop()
      stream.close()
    # 强制退出程序
    sys.exit(1)

  def on_event(self, result: RecognitionResult) -> None:
    sentence = result.get_sentence()
    if 'text' in sentence:
      print('RecognitionCallback text: ', sentence['text'])
      if RecognitionResult.is_sentence_end(sentence):
        print(
          'RecognitionCallback sentence end, request_id:%s, usage:%s'
          % (result.get_request_id(), result.get_usage(sentence)))


def signal_handler(sig, frame):
  print('按下 Ctrl+C,停止识别...')
  # 停止识别
  recognition.stop()
  print('识别已停止。')
  print(
    '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
    .format(
      recognition.get_last_request_id(),
      recognition.get_first_package_delay(),
      recognition.get_last_package_delay(),
    ))
  # 强制退出程序
  sys.exit(0)


# 主函数
if __name__ == '__main__':
  # 如果未配置环境变量,请将下一行替换为:dashscope.api_key = "sk-xxx"
  dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

  dashscope.base_websocket_api_url='wss://dashscope.aliyuncs.com/api-ws/v1/inference'

  # 创建识别回调
  callback = Callback()

  # 异步模式调用识别服务,可自定义识别参数,如 model、format、sample_rate
  recognition = Recognition(
    model='fun-asr-realtime',
    format=format_pcm,
    # 'pcm', 'wav', 'mp3', 'opus', 'speex', 'aac', 'amr'。支持的格式请参见文档。
    sample_rate=sample_rate,
    # 支持 16000。
    semantic_punctuation_enabled=False,
    callback=callback)

  # 启动识别
  recognition.start()

  signal.signal(signal.SIGINT, signal_handler)
  print("按 Ctrl+C 停止录音和识别...")
  # 创建键盘监听,直到按下 Ctrl+C

  while True:
    if stream:
      data = stream.read(3200, exception_on_overflow=False)
      recognition.send_audio_frame(data)
    else:
      break

  recognition.stop()

请求参数

Recognition 类的构造函数(__init__)中设置请求参数。
参数类型默认值是否必选说明
modelstr-实时语音识别模型。
sample_rateint-音频采样率,单位 Hz。支持 16000 Hz。
formatstr-音频格式:pcm、wav、mp3、opus、speex、aac、amr。

注意: opus/speex 必须使用 Ogg 封装。wav 必须使用 PCM 编码。amr 仅支持 AMR-NB。
vocabulary_idstr-热词表 ID,用于热词定制。参见自定义热词
semantic_punctuation_enabledboolFalse是否启用语义标点。
  • true:使用语义标点(禁用基于 VAD 的标点)。适用于会议转录等对准确率要求高的场景。
  • false(默认):使用 VAD 标点(禁用语义标点)。适用于交互式场景,延迟更低。
max_sentence_silenceint1300VAD 断句的静音阈值,单位 ms。静音超过该值则断句。范围:200-6000 ms。仅在 semantic_punctuation_enabled 为 false 时生效。
multi_threshold_mode_enabledboolFalse防止 VAD 产生过长的分段。仅在 semantic_punctuation_enabled 为 false 时生效。
punctuation_prediction_enabledboolTrue自动为识别结果添加标点。此参数固定为 true,无法通过 SDK 覆盖;识别结果始终包含自动标点。
heartbeatboolFalse保持服务端持久连接:
  • true:持续发送静音音频以保持连接。
  • false(默认):即使持续发送静音音频,60 秒后连接也会超时。静音音频指无声音信号的音频,可通过音频编辑软件(Audacity、Adobe Audition)或 FFmpeg 生成。
需要 SDK 版本 1.23.1 及以上。
language_hintslist[str]["zh", "en"]识别的语言代码。不设置时自动检测。支持的语言代码:
  • fun-asr-realtime、fun-asr-realtime-2025-11-07:zh(中文)、en(英文)、ja(日文)
  • fun-asr-realtime-2025-09-15:zh(中文)、en(英文)
speech_noise_thresholdfloat-语音噪声检测阈值,用于调节 VAD 灵敏度。范围:[-1.0, 1.0]。
  • 接近 -1:降低噪声阈值——更多噪声可能被识别为语音。
  • 接近 +1:提高噪声阈值——部分语音可能被过滤为噪声。
注意: 这是高级参数,调整会显著影响识别质量。请充分测试,并根据音频环境小幅调整(步长 0.1)。
callbackRecognitionCallback-RecognitionCallback 回调接口

核心接口

Recognition

通过 from dashscope.audio.asr import * 导入。
成员方法方法签名说明
calldef call(self, file: str, phrase_id: str = None, **kwargs) -> RecognitionResult对本地文件执行非流式识别。阻塞等待处理完成后返回 RecognitionResult
startdef start(self, phrase_id: str = None, **kwargs)启动流式识别,非阻塞。需配合 send_audio_framestop 使用。
send_audio_framedef send_audio_frame(self, buffer: bytes)发送一个音频帧(每包约 100 ms,1-16 KB)。通过 RecognitionCallbackon_event 回调获取结果。
stopdef stop(self)停止识别。阻塞等待直到所有音频处理完成。
get_last_request_iddef get_last_request_id(self)返回请求 ID。Recognition 对象创建后即可调用。
get_first_package_delaydef get_first_package_delay(self)返回首包延迟(从发送第一个音频包到收到第一个结果的时间)。任务完成后可用。
get_last_package_delaydef get_last_package_delay(self)返回尾包延迟(从调用 stop 到收到最终结果的时间)。任务完成后可用。

回调接口 (RecognitionCallback)

双向流式调用中,服务端通过回调返回数据。实现回调接口以处理响应。
class Callback(RecognitionCallback):
  def on_open(self) -> None:
    print('连接成功')

  def on_event(self, result: RecognitionResult) -> None:
    # 实现接收识别结果的逻辑
    pass

  def on_complete(self) -> None:
    print('任务完成')

  def on_error(self, result: RecognitionResult) -> None:
    print('发生异常:', result)

  def on_close(self) -> None:
    print('连接关闭')


callback = Callback()
方法参数返回值说明
def on_open(self) -> None建立服务端连接时调用。
def on_event(self, result: RecognitionResult) -> NoneresultRecognitionResult返回识别结果时调用。
def on_complete(self) -> None所有结果返回后调用。
def on_error(self, result: RecognitionResult) -> NoneresultRecognitionResult发生错误时调用。
def on_close(self) -> None连接关闭时调用。

响应

识别结果 (RecognitionResult)

RecognitionResult 表示流式调用非流式调用的识别结果。
成员方法方法签名说明
get_sentencedef get_sentence(self) -> Union[Dict[str, Any], List[Any]]返回当前识别的句子及时间戳。在回调中返回单个句子,类型为 Dict[str, Any]。参见句子信息
get_request_iddef get_request_id(self) -> str返回请求 ID。
get_usagedef get_usage(self, sentence: Dict[str, Any]) -> Dict返回该句子的用量信息。
is_sentence_end@staticmethod def is_sentence_end(sentence: Dict[str, Any]) -> bool判断句子是否结束。

句子信息 (Sentence)

参数类型说明
begin_timeint句子开始时间,单位 ms。
end_timeint句子结束时间,单位 ms。
textstr识别文本。
wordsWord 对象列表词级时间戳信息。

词级时间戳信息 (Word)

参数类型说明
begin_timeint词的开始时间,单位 ms。
end_timeint词的结束时间,单位 ms。
textstr词文本。
punctuationstr标点符号。