PaddleSpeech 在线 ASR ONNX 引擎深度解析:基于 onnxruntime 的流式语音识别服务端实现

原创2026-09-22 10:45:411,945 阅读
文章标签:语音音频人工智能深度学习

PaddleSpeech 在线 ASR ONNX 引擎深度解析:基于 onnxruntime 的流式语音识别服务端实现

本文围绕 PaddleSpeech 服务端模块 paddlespeech.server.engine.asr.online.onnx 展开,系统讲解该引擎的类结构、流式解码流程、onnxruntime 推理配置以及 WebSocket 服务端对接方式。读完本文,你将掌握 PaddleSpeech 在线语音识别服务端 ONNX 引擎的完整调用链,能够读懂 asr_engine.py 的核心实现,并基于 ws_ds2_application.yaml 独立部署一套基于 DeepSpeech2 在线模型与 ONNX Runtime 的流式 ASR 服务。

一、模块定位:在线 ASR 的三种引擎之一

PaddleSpeech 服务端(paddlespeech/server)为 ASR 提供了多种引擎形态,从 application.yaml 中的注释可以看到,服务端引擎以 <speech task>_<engine type> 命名,其中 ASR 任务可选 asr_python(Python 动态图推理)、asr_inference(Paddle Inference 离线推理)等;而在 WebSocket 在线服务场景下,则存在 asr_online-onnx、asr_online-inference、asr_online(即 asr_online-python)三种在线引擎。

本文关联文档 docs/source/api/paddlespeech.server.engine.asr.online.onnx.rst 所指向的 paddlespeech/server/engine/asr/online/onnx 包,正是其中基于 ONNX Runtime(onnxruntime) 的在线 ASR 引擎实现。该包由两个文件构成:

  • init.py:包入口,仅包含 LICENSE 头与包的 __all__ 声明;
  • asr_engine.py:核心实现,对外导出三个类——PaddleASRConnectionHanddler、ASRServerExecutor、ASREngine。

从 asr_engine.py 的 __all__ 声明可以确认,该模块的公共 API 即为上述三个类。值得注意的是,从源码判断,当前 ONNX 在线引擎仅支持 DeepSpeech2 在线模型(deepspeech2online_wenetspeech 等),对 conformer 等模型会抛出 ValueError / NotImplementedError,这一点在后续各节会反复出现。

二、三个核心类:连接处理器、执行器与引擎

2.1 ASREngine:单例引擎,承载模型资源与生命周期

ASREngine 继承自 BaseEngine,而 BaseEngine 使用 pattern_singleton.Singleton 元类,保证全服务只有一个 ASR 引擎实例(服务端所有 WebSocket 连接共享同一份模型资源)。

ASREngine 的核心方法是 init(config) 与 init_model():

def init(self, config: dict) -> bool:
    self.config = config
    self.executor = ASRServerExecutor()
    ...
    self.device = self.config.get("device", paddle.get_device())
    paddle.set_device(self.device)
    ...
    if not self.init_model():
        return False
    return True

init 负责三件事:保存服务端配置、创建 ASRServerExecutor 执行器、设置 device(配置文件中 device: 'cpu' 或 gpu:id)。若设备设置失败,会直接 sys.exit(-1) 并提示检查 yaml 中 device 参数。

ASREngine.init_model() 则将配置中的各项参数透传给执行器的 _init_from_path:

self.executor._init_from_path(
    model_type=self.config.model_type,
    am_model=self.config.am_model,
    am_params=self.config.am_params,
    lang=self.config.lang,
    sample_rate=self.config.sample_rate,
    cfg_path=self.config.cfg_path,
    decode_method=self.config.decode_method,
    num_decoding_left_chunks=self.config.num_decoding_left_chunks,
    am_predictor_conf=self.config.am_predictor_conf)

由于是纯在线(streaming)推理,ASREngine 的 preprocess、run、postprocess 三个方法均直接 raise NotImplementedError("Online not using this.")——在线引擎不遵循"预处理-推理-后处理"的离线三段式,而是通过 new_handler() 为每个 WebSocket 连接创建独立的 PaddleASRConnectionHanddler 实例:

def new_handler(self):
    return PaddleASRConnectionHanddler(self)

2.2 ASRServerExecutor:模型加载与资源初始化

ASRServerExecutor 继承自 CLI 层的 ASRExecutor(paddlespeech/cli/asr/infer.py),并在构造时声明任务资源类型:

self.task_resource = CommonTaskResource(
    task='asr', model_format='onnx', inference_mode='online')

其关键职责集中在 _init_from_path 与 init_model 中:

(1)模型资源定位与配置加载

_init_from_path 接收 model_type、lang、sample_rate 等参数,并据此拼装模型 tag:sample_rate_str = '16k' if sample_rate == 16000 else '8k',tag = model_type + '-' + lang + '-' + sample_rate_str,例如 deepspeech2online_wenetspeech-zh-16k。随后通过 task_resource.set_task_model(model_tag=tag) 定位预置模型目录,并将 ONNX 模型路径解析为 res_dict<a href="https://link.gitcode.com/i/7bedca57e51fbee641d9166be0d52a79" target="_blank">'onnx_model']([asr_engine.py)。注意这里有一个显式断言 assert am_params is None, "am_params not used in onnx engine"——ONNX 引擎不需要 am_params(pdiparams)权重文件,只有单个 .onnx 静态图文件。

配置以 yacs CfgNode 加载:self.config = CfgNode(new_allowed=True); self.config.merge_from_file(self.cfg_path)。之后用配置中的 unit_type、vocab_filepath、spm_model_prefix 构建 TextFeaturizer(用于 token 与文本互转)。

(2)语言模型下载

update_config 针对 DeepSpeech2 模型会修正语言模型路径,并自动从 task_resource.res_dict 中获取 lm_url / lm_md5 下载语言模型到 MODEL_HOME/language_model 目录:

with UpdateConfig(self.config):
    self.config.decode.lang_model_path = os.path.join(
        MODEL_HOME, 'language_model', self.config.decode.lang_model_path)
lm_url = self.task_resource.res_dict['lm_url']
...
self.download_lm(lm_url, os.path.dirname(self.config.decode.lang_model_path), lm_md5)

(3)ONNX Session 创建

init_model 调用 onnx_infer.py 中的 get_sess 创建 onnxruntime InferenceSession:

self.am_predictor = onnx_infer.get_sess(
    model_path=self.am_model, sess_conf=self.am_predictor_conf)

get_sess 的细节将在第四节专门展开。

2.3 PaddleASRConnectionHanddler:单个连接的流式解码状态机

PaddleASRConnectionHanddler 是每次 WebSocket 连接的核心处理类,它在构造函数中完成一系列初始化:

  • 从 asr_engine.executor 取得 model_type、sample_rate、text_feature(token↔文本映射);
  • 读取模型配置中的 preprocess_config,构建 Transformation 预处理对象,并解析出 win_length(窗长)与 n_shift(帧移,单位均为采样点);
  • 计算 frame_shift_in_ms = n_shift / fs * 1000(毫秒级帧移);
  • 从服务端配置读取 continuous_decoding(连续解码开关,默认 False);
  • 调用 init_decoder() 与 reset()。

状态管理:reset() 会为 DeepSpeech2 初始化 RNN 隐状态 chunk_state_h_box、chunk_state_c_box(形状为 (num_rnn_layers, 1, rnn_layer_size),float32),并调用 decoder.reset_decoder(batch_size=1);同时重置 num_samples、num_frames、global_frame_offset、endpoint_state、remained_wav、cached_feat 以及输出 result_transcripts = ['']。

reset_continuous_decoding() 则用于连续解码场景下,将 global_frame_offset 更新为当前 num_frames 并清空音频/特征缓存,为下一段语音做准备。

三、流式解码全流程:从 PCM 字节流到文本

在线 ASR 的核心是"边收音频边出结果"。PaddleASRConnectionHanddler 通过 extract_feat → decode → decode_one_chunk → CTCDecoder 四个环节完成这一流程。

3.1 extract_feat:PCM 累积与在线 FBank 特征提取

extract_feat(samples) 接收的是服务端 WebSocket 收到的原始 PCM 字节:

samples = np.frombuffer(samples, dtype=np.int16)
assert samples.ndim == 1
self.num_samples += samples.shape[0]

处理逻辑分四步:

  1. 音频累积:新到达的 PCM 与历史残留 remained_wav 拼接(np.concatenate),不足一窗(win_length)时直接返回 0,等待更多数据;
  2. 特征计算:对累积音频做 self.preprocessing(remained_wav, **preprocess_args)(即 FBank),转为 (1, T, D) 的 Paddle Tensor;
  3. 特征缓存:新特征按时间轴拼接到 cached_feat,并在首次计算时记录 self.device = self.cached_feat.place;
  4. 滑动窗口更新:self.remained_wav = self.remained_wav[self.n_shift * num_frames:]——只保留当前已消耗帧移之外的采样点,同时更新 num_frames。

这一"拼接-提取-裁剪"模式是流式特征提取的标准做法,保证了帧边界处特征的连续性。

3.2 decode:按解码窗口切分特征

decode(is_finished=False) 是流式解码的主调度方法,其中针对 DeepSpeech2 定义了三个关键常量:

decoding_chunk_size = 1   # 单次解码的帧数(帧为单位)
context = 7               # 上下文帧数
subsampling = 4           # 时间下采样倍数

由它们派生出:

cached_feature_num = context - subsampling          # 3
decoding_window = (decoding_chunk_size - 1) * subsampling + context  # 7
stride = subsampling * decoding_chunk_size          # 4

即:模型每解码 1 帧输出需要 7 帧上下文输入,滑动步长 4 帧,解码后缓存中仅保留末尾 context - subsampling = 3 帧作为下一轮的上文。这与 ws_ds2_application.yaml 中 chunk_buffer_conf 的 window_n: 7、shift_n: 4、window_ms: 25、shift_ms: 10 完全对应。

调度逻辑的边界条件:

  • 缓存帧数不足 decoding_window 且非结束帧时,返回 (None, None),等待更多 PCM;
  • is_finished=True(收到 end 信号)时,只要缓存不少于 context 帧(7 帧),就继续解码最后一段,left_frames = context;
  • 循环以 stride 步进切块:for cur in range(0, num_frames - left_frames + 1, stride),每次取 x_chunk = cached_feat[:, cur:end, :] 送入 decode_one_chunk;
  • 解码完成后 cached_feat = cached_feat[:, end - cached_feature_num:, :] 更新缓存。

3.3 decode_one_chunk:ONNX 前向与 CTC 解码

decode_one_chunk 用 @paddle.no_grad() 修饰,完成一次单块前向:

input_names = [n.name for n in self.am_predictor.get_inputs()]
output_names = [n.name for n in self.am_predictor.get_outputs()]
...
input_datas = [self.chunk_state_c_box, self.chunk_state_h_box,
               x_chunk_lens, x_chunk]
feeds = dict(zip(input_names, input_datas))
outputs = self.am_predictor.run([*output_names], {**feeds})
output_chunk_probs, output_chunk_lens, \
    self.chunk_state_h_box, self.chunk_state_c_box = outputs
self.decoder.next(output_chunk_probs, output_chunk_lens)
trans_best, trans_beam = self.decoder.decode()
return trans_best[0]

这里可以清楚看到 DeepSpeech2 ONNX 模型的输入输出签名:输入为 chunk_state_c_box、chunk_state_h_box、audio_chunk_lens、audio_chunk 四个张量,输出为 softmax 概率、帧长以及更新后的隐状态 state_h / state_c——RNN 状态在块与块之间持续传递,这正是在线模型能够流式工作的关键。

3.4 CTCDecoder:前缀束搜索与语言模型

init_decoder 中为 DeepSpeech2 构建了 CTCDecoder(paddlespeech/s2t/modules/ctc.py),其参数与模型配置对齐:

self.decoder = CTCDecoder(
    odim=self.model_config.output_dim,       # <blank> 已包含在词表中
    enc_n_units=self.model_config.rnn_layer_size * 2,
    blank_id=self.model_config.blank_id,
    dropout_rate=0.0,
    reduction=True, batch_average=True, ...)
self.decoder.init_decoder(
    decode_batch_size, self.text_feature.vocab_list,
    cfg.decoding_method, cfg.lang_model_path, cfg.alpha, cfg.beta,
    cfg.beam_size, cfg.cutoff_prob, cfg.cutoff_top_n,
    cfg.num_proc_bsearch)

其中 decoding_method、lang_model_path、alpha、beta、beam_size、cutoff_prob、cutoff_top_n、num_proc_bsearch 均来自模型配置文件的 decode 段,语言模型在 update_config 阶段已自动下载。每次 decode_one_chunk 调用 decoder.next(...) 推进前缀束搜索,再通过 decoder.decode() 取出当前最优假设。

最终 get_result() 返回 result_transcripts[0],即当前连接的部分/最终识别结果;get_word_time_stamp() 在 ONNX 引擎中返回空列表。

四、ONNX Runtime 会话配置:onnx_infer.get_sess 详解

ONNX 引擎的推理会话由 paddlespeech/server/utils/onnx_infer.py 的 get_sess 统一创建,其要点如下:

sess_options = ort.SessionOptions()
sess_options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
if sess_conf.get('graph_optimization_level', 99) == 0:
    sess_options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_DISABLE_ALL
sess_options.execution_mode = ort.ExecutionMode.ORT_SEQUENTIAL

providers = ['CPUExecutionProvider']
if "gpu" in sess_conf.get("device", ""):
    device_id = int(sess_conf["device"].split(":")[1])
    providers = [('CUDAExecutionProvider', {'device_id': device_id})]
    if sess_conf.get("use_trt", 0):
        providers = ['TensorrtExecutionProvider']
...
sess = ort.InferenceSession(model_path, providers=providers, sess_options=sess_options)

关键行为:

  • 图优化级别:默认 ORT_ENABLE_ALL;若配置中 graph_optimization_level: 0 则关闭全部图优化(默认配置 ws_ds2_application.yaml 中即设置为 0);
  • 执行模式:固定为 ORT_SEQUENTIAL(顺序执行),适合流式推理;
  • 执行提供方(Provider):默认 CPU;配置 device: 'gpu:id' 时切换到 CUDAExecutionProvider,且若同时设置 use_trt 则使用 TensorrtExecutionProvider(注释提醒 fastspeech2/mb_melgan 尚不支持 TensorRT);
  • 线程数:优先读取 cpu_threads,否则回退到 intra_op_num_threads / inter_op_num_threads(配置中均为 0 时由 onnxruntime 自行决定)。

五、服务端配置:ws_ds2_application.yaml 逐项解析

部署 ONNX 在线 ASR 服务使用 ws_ds2_application.yaml。该文件同时定义了 asr_online-onnx(本主题)与 asr_online-inference(Paddle Inference 版本)两个引擎块,二者共用同一套 chunk_buffer_conf,便于对照。

5.1 服务端全局设置

host: 0.0.0.0
port: 8090
protocol: 'websocket'
engine_list: ['asr_online-onnx']
  • host / port:服务监听地址与端口,默认 0.0.0.0:8090;
  • protocol: 'websocket':在线引擎只支持 WebSocket 协议(文件头注释明确:websocket only support online engine type);
  • engine_list:要加载的引擎列表,在线 ONNX ASR 必须写 asr_online-onnx。

5.2 asr_online-onnx 引擎配置

asr_online-onnx:
    model_type: 'deepspeech2online_wenetspeech'
    am_model:    # 可选,onnx AM 静态模型文件
    am_params:   # 可选,ONNX 引擎不使用
    lang: 'zh'
    sample_rate: 16000
    cfg_path:
    decode_method:
    num_decoding_left_chunks:
    force_yes: True
    device: 'cpu'          # cpu 或 gpu:id
    am_predictor_conf:
        device: 'cpu'
        graph_optimization_level: 0
        intra_op_num_threads: 0
        inter_op_num_threads: 0
        log_severity_level: 2
        log_verbosity_level: 0
    chunk_buffer_conf:
        frame_duration_ms: 85
        sample_rate: 16000
        sample_width: 2
        window_n: 7     # 帧
        shift_n: 4      # 帧
        window_ms: 25   # ms
        shift_ms: 10    # ms

参数含义说明:

参数 含义 说明
model_type 模型类型 当前为 deepspeech2online_wenetspeech,可换其他 ds2 在线模型
am_model ONNX 静态图路径 留空时自动从资源目录取 onnx_model;指定则用绝对路径
am_params AM 权重 ONNX 引擎断言为 None,无需填写
lang 语言 zh,用于拼装模型 tag
sample_rate 采样率 16000 对应 tag 中 16k,8000 对应 8k
cfg_path 模型配置文件 留空则用资源目录内默认配置
device 引擎设备 cpu 或 gpu:id
force_yes 自动确认 下载资源时免交互确认

am_predictor_conf 直接透传给 onnx_infer.get_sess:graph_optimization_level: 0 关闭图优化;intra_op_num_threads / inter_op_num_threads 控制 onnxruntime 节点内/节点间并行线程数;log_severity_level: 2 表示 Warning 级别日志。

chunk_buffer_conf 是流式缓冲的关键参数,与源码 decode 中的常量一一对应:window_n: 7(context)、shift_n: 4(subsampling)、window_ms: 25(窗长 25ms)、shift_ms: 10(帧移 10ms)、sample_width: 2(int16 PCM 双字节)。frame_duration_ms: 85 可理解为缓冲包对应时长(7×10ms 上下文 + 部分填充)。

六、WebSocket 对接:/paddlespeech/asr/streaming 协议

ONNX 在线引擎通过 paddlespeech/server/ws/asr_api.py 暴露 WebSocket 端点 /paddlespeech/asr/streaming,协议交互如下:

1. 建立连接:客户端发起 WebSocket 握手,服务端 await websocket.accept(),并从引擎池取出 ASR 引擎。

2. start 信号:客户端发送 {"signal": "start"},服务端通过 asr_model.new_handler() 创建 PaddleASRConnectionHanddler,回复 {"status": "ok", "signal": "server_ready"}。

3. 音频数据:客户端持续发送二进制 PCM 帧(int16),服务端依次调用:

connection_handler.extract_feat(message)
connection_handler.decode(is_finished=False)
asr_results = connection_handler.get_result()
resp = {'result': asr_results}
await websocket.send_json(resp)

即每收到一包音频就提取特征、增量解码,并把当前部分结果实时回传给客户端。

4. end 信号:客户端发送 {"signal": "end"},服务端执行最终解码并返回完整结果:

connection_handler.decode(is_finished=True)
connection_handler.rescoring()
asr_results = connection_handler.get_result()
connection_handler.reset()
resp = {"status": "ok", "signal": "finished",
        'result': asr_results, 'times': word_time_stamp}

从 asr_api.py 可以看到,ONNX 引擎的 endpoint_state 恒为 False(DeepSpeech2 在线模型不支持端点检测,源码注释明确 "ds2 model not support endpoint"),因此不会走 endpoint 分支,识别完全由客户端 end 信号驱动收尾。

七、启动服务与运行验证

启动 ONNX 在线 ASR 服务只需一条命令(参考 demos/streaming_asr_server/run.sh 的启动方式):

paddlespeech_server start --config_file ./conf/ws_ds2_application.yaml

首次启动时,ASRServerExecutor 会自动下载 DeepSpeech2 在线模型与语言模型到 MODEL_HOME(~/.paddlespeech 目录)并做 MD5 校验。启动成功后日志会输出 Initialize ASR server engine successfully on device: cpu.,随后即可用任意 WebSocket 客户端按第六节协议向 ws://<host>:8090/paddlespeech/asr/streaming 发送 PCM 数据流式获取识别结果。

适用前提与限制:该引擎要求安装 onnxruntime 依赖;当前实现仅支持 DeepSpeech2 在线模型,若在 model_type 中配置 conformer 等模型会报 Not supported;设备方面 CPU 与 GPU(gpu:id)均可,GPU 下还可启用 TensorRT Provider。

八、源码阅读路线图

若希望深入该模块,建议按以下路径阅读:

  1. asr_engine.py:模块主体,三个核心类的完整实现;
  2. onnx_infer.py:onnxruntime 会话工厂,理解 Provider 与线程配置;
  3. ws_ds2_application.yaml:ONNX 在线引擎的官方配置模板;
  4. asr_api.py:WebSocket 端点与信号协议;
  5. base_engine.py:BaseEngine 单例基类;
  6. paddlespeech/s2t/modules/ctc.py:CTCDecoder 前缀束搜索实现,对应 decoder.next / decoder.decode 的底层原理。

通过上述文件,你可以完整还原"PCM 流入 → FBank 提取 → 分块 ONNX 前向 → CTC 束搜索 → 部分/最终文本回流"的整条在线识别链路,并据此定制自己的流式 ASR 服务。

登录后查看全文
PaddleSpeech