PaddleSpeech 在线 ASR ONNX 引擎深度解析:流式语音识别服务核心模块
PaddleSpeech 在线 ASR ONNX 引擎深度解析:流式语音识别服务核心模块
导读
本文以 PaddleSpeech 官方 API 文档中 paddlespeech.server.engine.asr.online.onnx.asr_engine 模块(对应 RST 文档 docs/source/api/paddlespeech.server.engine.asr.online.onnx.asr_engine.rst)为主线,完整解析 PaddleSpeech 在线(流式)语音识别服务中基于 ONNX Runtime 推理的引擎实现。该模块是 paddlespeech_server 流式 ASR 服务(asr_online-onnx 引擎类型)的核心:它负责 WebSocket 连接的会话管理、PCM 音频分片接收与 FBank 特征流式提取、DeepSpeech2 模型的逐帧块(chunk)ONNX 前向推理、CTC 流式解码以及部分结果(partial result)的实时回传。读完本文,你将掌握该模块三个核心类(PaddleASRConnectionHanddler、ASRServerExecutor、ASREngine)的职责划分与调用链,理解 ws_ds2_application.yaml 中每个配置项的语义,并能够独立搭建一个可用的流式语音识别服务。
一、模块定位:RST API 文档指向的引擎实现
关联文档本身是 Sphinx automodule 指令生成的 API 引用页面,其主体内容即 asr_engine.py 模块。该文件位于 paddlespeech/server/engine/asr/online/onnx/ 目录下,与 Paddle Inference 在线引擎(online/paddleinference)并列,二者共用同一套 WebSocket 服务协议,区别仅在于推理后端:
onnx引擎:通过onnxruntime加载 ONNX 格式的静态图模型(当前仓库实际支持deepspeech2系模型);paddleinference引擎:通过 Paddle Inference 加载 PDModel/PDParams。
模块顶部通过 __all__ 声明了对外暴露的 3 个类:
__all__ = ['PaddleASRConnectionHanddler', 'ASRServerExecutor', 'ASREngine']
其中 PaddleASRConnectionHanddler 是每个 WebSocket 连接一个的会话处理器,ASRServerExecutor 负责模型资源的加载与 ONNX 会话创建,ASREngine 则是继承自单例基类的全局引擎门面。下面逐一展开。
二、ASREngine:单例引擎门面与初始化流程
ASREngine 继承自 base_engine.py 中的 BaseEngine(metaclass=Singleton,即整个进程内引擎实例唯一),并重写了基类中默认 pass 的 init / run / preprocess / postprocess 等接口:
class ASREngine(BaseEngine):
"""ASR model resource
Args:
metaclass: Defaults to Singleton.
"""
对于在线引擎而言,preprocess、run、postprocess 三个方法均直接抛出 NotImplementedError("Online not using this.")——这是因为在线服务的"处理"不在引擎层同步执行,而是分散到每个 WebSocket 连接对应的 PaddleASRConnectionHanddler 中进行(见下文第三节)。这是理解该模块设计的关键:引擎负责全局资源,Handler 负责连接级状态。
ASREngine.init(config) 的完整初始化流程如下:
- 保存服务配置
self.config = config,创建ASRServerExecutor实例; - 从配置读取
device(缺省使用paddle.get_device()),并调用paddle.set_device(device)完成设备设置;失败时打印错误日志并sys.exit(-1),日志中明确提示"如果所有 GPU 或 XPU 已被占用,可将 server 设置为 'cpu'"; - 调用
init_model(),将服务配置中的model_type、am_model、am_params、lang、sample_rate、cfg_path、decode_method、num_decoding_left_chunks、am_predictor_conf逐项透传给执行器的_init_from_path; - 初始化失败则返回
False,成功则输出Initialize ASR server engine successfully on device: %s。
def new_handler(self):
"""New handler from model."""
return PaddleASRConnectionHanddler(self)
new_handler() 是引擎提供给 WebSocket 层的唯一入口:每当客户端发起一次新的 start 信号,asr_api.py 就会调用 asr_model.new_handler() 生成一个全新的会话处理器,实现多连接之间的状态隔离。
三、ASRServerExecutor:ONNX 会话与模型资源管理
ASRServerExecutor 继承自 paddlespeech/cli/asr/infer.py 中的 ASRExecutor(CLI 推理执行器的服务端变体),在构造时即绑定任务资源描述:
class ASRServerExecutor(ASRExecutor):
def __init__(self):
super().__init__()
self.task_resource = CommonTaskResource(
task='asr', model_format='onnx', inference_mode='online')
CommonTaskResource 会在模型资源目录(MODEL_HOME,默认 ~/.paddlespeech/models)中按 model_type-lang-sample_rate 拼接的 tag(如 deepspeech2online_wenetspeech-zh-16k)查找或自动下载对应模型,并读取 res_dict 中记录的 cfg_path、onnx_model、lm_url、lm_md5 等资源映射。
3.1 _init_from_path:按标签定位资源
该方法依次完成:参数合法性校验(model_type、lang、sample_rate 任一为空即报错返回 False)、根据 sample_rate 生成 16k/8k 采样率标记、调用 set_task_model(model_tag=tag) 定位资源目录、确定模型配置文件 cfg_path 与 ONNX 模型文件 am_model 的绝对路径(若配置项为空则从资源字典中取默认值)。
值得注意的两个细节:
assert am_params is None, "am_params not used in onnx engine":ONNX 引擎不使用am_params(静态图参数已固化进 ONNX 文件),传入即断言失败;- 若配置中指定了
spm_model_prefix(SentencePiece 前缀),会拼接资源目录得到完整路径,供TextFeaturizer使用。
3.2 配置文件与词表加载
随后用 yacs 的 CfgNode 加载模型 yaml:
self.config = CfgNode(new_allowed=True)
self.config.merge_from_file(self.cfg_path)
self.vocab = self.config.vocab_filepath
self.text_feature = TextFeaturizer(
unit_type=self.config.unit_type,
vocab=self.config.vocab_filepath,
spm_model_prefix=self.config.spm_model_prefix)
TextFeaturizer 负责把解码出的 token id 序列还原为文本(token 到汉字/词元的映射),在 Handler 中作为共享资源被复用。
3.3 update_config 与语言模型下载
DeepSpeech2 的 CTC 解码依赖外部语言模型(lang_model_path),因此 update_config 会把 decode.lang_model_path 改写为 MODEL_HOME/language_model/ 下的绝对路径,并依据 task_resource.res_dict 中的 lm_url/lm_md5 调用 download_lm 自动下载校验。
3.4 init_model:创建 ONNX Runtime 会话
def init_model(self) -> None:
if "deepspeech2" in self.model_type:
self.am_predictor = onnx_infer.get_sess(
model_path=self.am_model, sess_conf=self.am_predictor_conf)
会话创建委托给 onnx_infer.py 的 get_sess,其内部策略如下:
- 默认开启
ORT_ENABLE_ALL图优化,仅当配置graph_optimization_level: 0时降级为ORT_DISABLE_ALL; - 执行模式固定为
ORT_SEQUENTIAL(顺序执行); - Provider 选择:默认
CPUExecutionProvider;若sess_conf["device"]含"gpu"则解析gpu:id中的设备号并启用CUDAExecutionProvider;若同时配置use_trt: 1则切换为TensorrtExecutionProvider(注意源码注释提示 fastspeech2/mb_melgan 尚不能使用 TRT); - 线程数控制:优先读取
cpu_threads,否则读intra_op_num_threads(节点内并行线程),另有inter_op_num_threads(跨节点并行线程),缺省均为 0(由 ONNX Runtime 自行决定)。
四、PaddleASRConnectionHanddler:连接级流式识别会话
PaddleASRConnectionHanddler 是该模块的核心工作类,每个 WebSocket 连接持有一个实例,负责从原始 PCM 字节流到最终识别文本的全过程。构造函数首先从引擎共享的执行器中取出模型级资源:
self.model_type = self.asr_engine.executor.model_type
self.sample_rate = self.asr_engine.executor.sample_rate
self.text_feature = self.asr_engine.executor.text_feature
同时从模型配置的 preprocess_config.process[0] 中读取 win_length(帧窗长,样本数)与 n_shift(帧移,样本数),并断言 fs == sample_rate(模型配置采样率必须与服务采样率一致),由此计算出毫秒级的帧移:
self.frame_shift_in_ms = int(self.n_shift / self.preprocess_conf.process[0]['fs'] * 1000)
4.1 状态变量与重置
Handler 维护了丰富的连接级状态,全部在 reset() 中初始化:
| 状态分组 | 变量 | 语义 |
|---|---|---|
| DeepSpeech2 隐状态 | chunk_state_h_box / chunk_state_c_box |
形状 (num_rnn_layers, 1, rnn_layer_size) 的 RNN 初始 hidden/cell 状态,用 float32 零初始化 |
| 全局计数 | num_samples / num_frames |
累积收到的样本数 / 累积特征帧数 |
| 帧偏移 | global_frame_offset |
连续解码场景下用于对齐下一句的帧偏移 |
| 端点检测 | endpoint_state |
是否检测到端点(当前 DS2 在线引擎置 False) |
| 特征缓存 | remained_wav / cached_feat |
未消费完的 PCM 残段 / 累积的 FBank 特征张量 |
| 输出缓存 | result_transcripts |
部分/最终解码结果列表 |
model_reset() 仅清空音频与特征缓存;output_reset() 把 result_transcripts 复位为 [''];reset_continuous_decoding() 则把 global_frame_offset 前进到当前 num_frames 并清空缓存,用于连续解码(一句话结束、端点触发后无缝开启下一句)。
4.2 extract_feat:PCM 分片 → 流式 FBank
这是整个在线链路的数据入口,输入是 WebSocket 收到的原始 PCM bytes:
def extract_feat(self, samples: ByteString):
samples = np.frombuffer(samples, dtype=np.int16)
assert samples.ndim == 1
self.num_samples += samples.shape[0]
实现要点:
np.frombuffer(samples, dtype=np.int16)把字节串解释为 16-bit 有符号整型 PCM 采样(因此客户端必须以sample_width=2、16kHz 单声道编码发送数据);- 新分片与
remained_wav拼接后统一送入Transformation(来自 paddlespeech/audio/transform/transformation.py),按模型preprocess_config完成分帧加窗与 FBank 提取,得到(1, T, D)特征并追加到cached_feat; - 滑窗消费:本次提取消耗
num_frames帧,于是remained_wav = remained_wav[n_shift * num_frames:]丢弃已消费样本,保证下一次调用只处理"新产生的"音频——这是流式特征提取与整段离线提取的本质区别; - 若剩余样本不足一个
win_length窗长,直接返回 0,等待更多数据。
4.3 init_decoder:CTC 解码器装配
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,
grad_norm_type=self.model_config.get('ctc_grad_norm_type', None))
随后用解码参数初始化解码器(在线场景 decode_batch_size 固定为 1):
self.decoder.init_decoder(
1, 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)
同时源码中有断言 ds2 model not support endpoint(continuous_decoding 必须为 False),说明当前 ONNX 引擎对 DeepSpeech2 采用"一句一断"的流式模式,不支持 VAD 端点续说。
4.4 decode:滑动窗口逐块前向
decode(is_finished) 是流式解码的核心。对 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
解码逻辑:
- 若
cached_feat为空,提示"no audio feat, please input more pcm data"并返回; - 未结束(
is_finished=False)时要求缓存帧数 ≥decoding_window(7 帧),否则提示继续输入 PCM; - 结束(
is_finished=True)时要求至少context(7)帧,且只处理最后一小段(left_frames = context); - 以
stride=4为步长在[0, num_frames - left_frames + 1)范围内滑窗,每个窗口x_chunk = self.cached_feat[:, cur:end, :]送入decode_one_chunk; - 全部窗口解码完成后,
cached_feat只保留末尾cached_feature_num帧,供下一次调用衔接上下文。
4.5 decode_one_chunk:ONNX 前向与 CTC 状态推进
@paddle.no_grad()
def decode_one_chunk(self, x_chunk, x_chunk_lens):
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]
要点:
- ONNX 模型的 4 个输入为
chunk_state_c_box、chunk_state_h_box、audio_chunk_lens、audio_chunk,4 个输出为softmax_0.tmp_0、tmp_5、concat_0.tmp_0、concat_1.tmp_0(源码日志中的实际名称),即"概率、长度、新 hidden、新 cell"; - 更新后的 RNN 隐状态直接回写
self.chunk_state_h_box/self.chunk_state_c_box,作为下一块的初始状态——隐状态的跨块传递是流式解码能够保持上下文的关键; - 每块概率经
self.decoder.next(...)推进 CTC 解码器状态,再decode()取 best/beam 结果,其中trans_best[0]作为该连接当前的部分识别文本返回。
get_result() 返回 result_transcripts[0](空时返回 ''),get_word_time_stamp() 当前返回空列表,rescoring() 为预留接口(DS2 在线引擎暂未实现二遍重打分)。
五、WebSocket API 接入层:引擎如何被驱动
引擎本身不直接面对网络。服务端在 asr_api.py 中注册了 WebSocket 路由 /paddlespeech/asr/streaming,与 Handler 的配合流程如下:
await websocket.accept()建立连接后,从引擎池取出全局asr引擎实例;- 循环接收消息:
text消息为控制信号(JSON),bytes消息为 PCM 音频数据; - 收到
start信号 →connection_handler = asr_model.new_handler()创建新的会话处理器,回{"status": "ok", "signal": "server_ready"}; - 收到
bytes数据 → 依次调用extract_feat(message)与decode(is_finished=False),随后通过get_result()取得当前部分结果并回传{"result": asr_results}——这就是客户端能持续拿到中间结果的原因; - 收到
end信号 →decode(is_finished=True)处理尾部数据、rescoring()、取最终结果与时间戳,回{"status": "ok", "signal": "finished", "result": ..., "times": ...}后break断开循环,并调用connection_handler.reset()复位会话状态。
若配置了端点检测(endpoint_state 为真),bytes 分支还会在端点命中时触发 rescoring,并根据 continuous_decoding 决定是 reset_continuous_decoding() 续听下一句,还是直接以 finished 信号结束本次连接(当前 DS2 ONNX 引擎不启用该路径)。
六、服务配置详解:ws_ds2_application.yaml
仓库中与 ONNX 在线引擎配套的服务配置为 paddlespeech/server/conf/ws_ds2_application.yaml(demo 目录下有同名副本 demos/streaming_asr_server/conf/ws_ds2_application.yaml,其 README 提示使用该配置需 onnxruntime>=1.11.0)。核心配置项如下:
protocol: 'websocket'
engine_list: ['asr_online-onnx']
asr_online-onnx:
model_type: 'deepspeech2online_wenetspeech'
am_model: # ONNX 静态图模型文件路径 [可选,缺省用资源目录内默认模型]
am_params: # ONNX 引擎不使用,必须为空
lang: 'zh'
sample_rate: 16000
cfg_path: # 模型 yaml 路径 [可选]
decode_method:
num_decoding_left_chunks:
force_yes: True
device: 'cpu' # cpu 或 gpu:id
am_predictor_conf: # onnxruntime InferenceSession 参数
device: 'cpu' # 'gpu:id' 或 'cpu'
graph_optimization_level: 0 # 0=关闭图优化(ORT_DISABLE_ALL),默认开 ORT_ENABLE_ALL
intra_op_num_threads: 0 # 节点内并行线程数
inter_op_num_threads: 0 # 跨节点并行线程数
log_severity_level: 2 # 0:Verbose 1:Info 2:Warning 3:Error 4:Fatal
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
要点解读(与源码对应):
engine_list: ['asr_online-onnx']决定启动哪个引擎类型;配置注释明确websocket only support online engine type,流式服务仅支持 WebSocket 协议,不支持 HTTP;am_predictor_conf直接对应onnx_infer.get_sess的sess_conf:graph_optimization_level控制图优化开关(源码中99为默认值、0为关闭)、device决定 CPU/CUDA/TensorRT provider 选择、线程数与日志级别透传给ort.SessionOptions;chunk_buffer_conf中window_n/shift_n与 Handler 解码时使用的context=7、subsampling=4保持一致(frame_duration_ms由shift_n / sample_rate * 1000推得),客户端应据此切分发送的 PCM 包。
七、实战:搭建并调用流式 ASR 服务
7.1 启动服务端
按 demos/streaming_asr_server/README_cn.md 的指引,在 demos/streaming_asr_server 目录下执行:
# 启动 ONNX 在线 ASR 服务(使用 DeepSpeech2 模型)
paddlespeech_server start --config_file ./conf/ws_ds2_application.yaml
启动过程会输出类似以下的日志(以服务端 Initialize ASR server engine successfully 与 Uvicorn running on http://0.0.0.0:8090 为成功标志):
[INFO] - create the online asr engine instance
[INFO] - paddlespeech_server set the device: cpu
[INFO] - Initialize ASR server engine successfully.
INFO: Uvicorn running on http://0.0.0.0:8090 (Press CTRL+C to quit)
首次启动会自动下载 deepspeech2online_wenetspeech-zh-16k 模型及其配套语言模型(资源存放于 ~/.paddlespeech/models,即 MODEL_HOME),可通过 --help 查看 config_file(默认 ./conf/application.yaml)与 log_file(默认 ./log/paddlespeech.log)等参数。
7.2 调用客户端
准备一个与模型采样率一致的 16kHz WAV 文件,然后:
paddlespeech_client asr_online --server_ip 127.0.0.1 --port 8090 --input ./zh.wav
客户端常用参数(详见 demo README):server_ip(默认 127.0.0.1)、port(默认 8090)、input(必填,待识别音频)、sample_rate(默认 16000)、lang(默认 zh_cn)、audio_format(默认 wav),以及可选的标点预测服务 punc.server_ip / punc.server_port。初次使用客户端响应时间会略长(涉及模型加载)。
7.3 协议视角的一句话总结
一次完整的识别会话 = 客户端发 start(服务端返回 server_ready)→ 客户端持续推送 PCM bytes(服务端每包回传当前 partial result)→ 客户端发 end(服务端回 finished 并携带最终文本)→ 连接关闭。这一协议与 PaddleASRConnectionHanddler 的 extract_feat → decode → get_result 状态机一一对应。
八、模块级调用链总览
从源码结构可以归纳出 ONNX 在线 ASR 引擎的完整调用链:
paddlespeech_server start --config_file ws_ds2_application.yaml
└─ ServerExecutor → 引擎池注册 ASREngine(单例)
└─ ASREngine.init(config)
└─ ASRServerExecutor._init_from_path(...)
├─ CommonTaskResource.set_task_model(tag) # 定位/下载模型
├─ CfgNode.merge_from_file(cfg_path) # 模型 yaml
├─ TextFeaturizer(...) # token→文本
├─ update_config() + download_lm(...) # 语言模型
└─ init_model() → onnx_infer.get_sess(...) # ONNX Runtime 会话
└─ ASREngine.new_handler() (每次 WebSocket start 信号)
└─ PaddleASRConnectionHanddler(asr_engine)
├─ init_decoder(): CTCDecoder + init_decoder(...)
└─ 循环: extract_feat(pcm) → decode(is_finished=False)
└─ decode_one_chunk(x_chunk, lens)
├─ am_predictor.run(...) # ONNX 前向,隐状态回传
└─ decoder.next/decode → partial result
└─ decode(is_finished=True) → get_result() # 最终文本
其中 BaseEngine 单例机制(base_engine.py)保证模型全局只加载一次,而 new_handler() 为每个连接创建独立状态副本,兼顾了资源复用与会话隔离。
九、小结
paddlespeech.server.engine.asr.online.onnx.asr_engine 是 PaddleSpeech 流式语音识别服务在 ONNX 推理后端下的完整实现:ASREngine 以单例方式承载全局资源,ASRServerExecutor 完成模型定位、配置加载与 ONNX Runtime 会话创建,PaddleASRConnectionHanddler 则在连接级别完成 PCM→FBank 流式特征提取、DS2 滑动窗口逐块前向、CTC 流式解码与部分结果输出。配合 asr_api.py 的 WebSocket 协议层与 ws_ds2_application.yaml 的服务配置,即可快速搭建低延迟的流式中文语音识别服务。理解该模块的窗口滑动、隐状态传递与缓存管理机制,也是将其移植到其他模型(如 conformer 在线模型)或自定义后端的基础。