PaddleSpeech 在线 ASR ONNX 引擎深度解析:流式语音识别服务核心模块

原创2026-09-22 13:52:511,678 阅读
文章标签:语音音频人工智能深度学习

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) 的完整初始化流程如下:

  1. 保存服务配置 self.config = config,创建 ASRServerExecutor 实例;
  2. 从配置读取 device(缺省使用 paddle.get_device()),并调用 paddle.set_device(device) 完成设备设置;失败时打印错误日志并 sys.exit(-1),日志中明确提示"如果所有 GPU 或 XPU 已被占用,可将 server 设置为 'cpu'";
  3. 调用 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;
  4. 初始化失败则返回 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]

实现要点:

  1. np.frombuffer(samples, dtype=np.int16) 把字节串解释为 16-bit 有符号整型 PCM 采样(因此客户端必须以 sample_width=2、16kHz 单声道编码发送数据);
  2. 新分片与 remained_wav 拼接后统一送入 Transformation(来自 paddlespeech/audio/transform/transformation.py),按模型 preprocess_config 完成分帧加窗与 FBank 提取,得到 (1, T, D) 特征并追加到 cached_feat;
  3. 滑窗消费:本次提取消耗 num_frames 帧,于是 remained_wav = remained_wav[n_shift * num_frames:] 丢弃已消费样本,保证下一次调用只处理"新产生的"音频——这是流式特征提取与整段离线提取的本质区别;
  4. 若剩余样本不足一个 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]

要点:

  1. 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";
  2. 更新后的 RNN 隐状态直接回写 self.chunk_state_h_box / self.chunk_state_c_box,作为下一块的初始状态——隐状态的跨块传递是流式解码能够保持上下文的关键;
  3. 每块概率经 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 的配合流程如下:

  1. await websocket.accept() 建立连接后,从引擎池取出全局 asr 引擎实例;
  2. 循环接收消息:text 消息为控制信号(JSON),bytes 消息为 PCM 音频数据;
  3. 收到 start 信号 → connection_handler = asr_model.new_handler() 创建新的会话处理器,回 {"status": "ok", "signal": "server_ready"};
  4. 收到 bytes 数据 → 依次调用 extract_feat(message) 与 decode(is_finished=False),随后通过 get_result() 取得当前部分结果并回传 {"result": asr_results}——这就是客户端能持续拿到中间结果的原因;
  5. 收到 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 在线模型)或自定义后端的基础。

登录后查看全文
PaddleSpeech