PaddleSpeech 在线 ASR ONNX 引擎深度解析:基于 onnxruntime 的流式语音识别服务端实现
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]
处理逻辑分四步:
- 音频累积:新到达的 PCM 与历史残留
remained_wav拼接(np.concatenate),不足一窗(win_length)时直接返回 0,等待更多数据; - 特征计算:对累积音频做
self.preprocessing(remained_wav, **preprocess_args)(即 FBank),转为(1, T, D)的 Paddle Tensor; - 特征缓存:新特征按时间轴拼接到
cached_feat,并在首次计算时记录self.device = self.cached_feat.place; - 滑动窗口更新:
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。
八、源码阅读路线图
若希望深入该模块,建议按以下路径阅读:
- asr_engine.py:模块主体,三个核心类的完整实现;
- onnx_infer.py:onnxruntime 会话工厂,理解 Provider 与线程配置;
- ws_ds2_application.yaml:ONNX 在线引擎的官方配置模板;
- asr_api.py:WebSocket 端点与信号协议;
- base_engine.py:
BaseEngine单例基类; - paddlespeech/s2t/modules/ctc.py:
CTCDecoder前缀束搜索实现,对应decoder.next/decoder.decode的底层原理。
通过上述文件,你可以完整还原"PCM 流入 → FBank 提取 → 分块 ONNX 前向 → CTC 束搜索 → 部分/最终文本回流"的整条在线识别链路,并据此定制自己的流式 ASR 服务。