PaddleSpeech WebSocket 服务层源码解析:`paddlespeech.server.ws` 模块的流式 ASR / TTS 接口设计

原创2026-09-23 10:20:211,991 阅读
文章标签:语音音频人工智能深度学习

PaddleSpeech WebSocket 服务层源码解析:paddlespeech.server.ws 模块的流式 ASR / TTS 接口设计

本文以 PaddleSpeech 仓库中 docs/source/api/paddlespeech.server.ws.rst 文档所描述的 paddlespeech.server.ws 包为骨架,深入剖析其子模块 asr_api.py、tts_api.py 与 api.py 的源码实现,并结合服务端配置文件与 demos/streaming_asr_server、demos/streaming_tts_server 两个实战示例,完整还原基于 WebSocket 协议的流式语音识别与流式语音合成的接口设计、连接管理、信令协议与部署方式。读完本文,你将掌握 PaddleSpeech 在线语音服务的路由挂载机制、ASR/TTS 的 WebSocket 信令交互流程,以及如何通过命令行与 Python API 一键启动流式服务。

一、paddlespeech.server.ws 包在服务架构中的定位

paddlespeech.server.ws 是 PaddleSpeech Serving 体系中专门负责 WebSocket 协议接入层 的 Python 包,位于 paddlespeech/server/ws 目录,仅包含三个文件:

文件 职责
init.py 包初始化(空实现,仅含许可证头)
api.py 路由聚合器,按 engine_list 动态挂载 ASR / TTS 子路由
asr_api.py 流式语音识别 WebSocket 端点 /paddlespeech/asr/streaming
tts_api.py 流式语音合成 WebSocket 端点 /paddlespeech/tts/streaming 及采样率查询接口

从依赖关系看,ws 包直接调用 paddlespeech/server/engine/engine_pool.py 中定义的全局引擎池 get_engine_pool(),从池中取出 asr / tts 引擎实例后再创建连接处理器(Connection Handler)。整个调用链为:

FastAPI/Starlette WebSocket 请求
        │
        ▼
paddlespeech.server.ws.asr_api / tts_api(接入层,本文主题)
        │
        ▼
engine_pool['asr'] / engine_pool['tts'](引擎池)
        │
        ▼
engine.asr.online / engine.tts.online 引擎及 ConnectionHandler(推理层)

也就是说,ws 层不直接做模型推理,而是负责协议解析、连接生命周期管理、信令分发,并把音频/文本数据转交给引擎层的连接处理器去完成特征提取、解码与合成。

二、路由聚合:api.py 的 setup_router 机制

api.py 的核心是一个工厂式函数 setup_router(api_list: List):

_router = APIRouter()

def setup_router(api_list: List):
    """setup router for fastapi
    Args:
        api_list (List): [asr, tts]
    Returns:
        APIRouter
    """
    for api_name in api_list:
        if api_name == 'asr':
            _router.include_router(asr_router)
        elif api_name == 'tts':
            _router.include_router(tts_router)
        else:
            pass

    return _router

要点解读:

  • 该函数接收一个字符串列表 api_list,按名称决定是否将 asr_router、tts_router 挂载到统一的 _router 上;
  • api_list 的来源是服务端配置中的任务类型。结合 engine_pool.py 的 init_engine_pool 可以看到,配置中的 engine_list 形如 "asr_online"(<speech task>_<engine type>),引擎池按下划线拆分后的第一个单词(asr、tts、cls、text、vector)作为键;
  • 从代码结构可以推断,setup_router 与引擎池初始化配合使用:只有配置中启用了某个引擎类型,对应的 WebSocket 路由才会被挂载,从而实现“按需加载”的服务能力;
  • 目前 ws 层只实现了 asr 与 tts 两类 WebSocket 路由,其他任务(分类、文本、声纹等)在 ws 包中没有对应端点。

三、流式语音识别 WebSocket 端点:asr_api.py

3.1 端点定义与连接建立

asr_api.py 用 FastAPI 装饰器定义了流式 ASR 端点:

@router.websocket('/paddlespeech/asr/streaming')
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()

    engine_pool = get_engine_pool()
    asr_model = engine_pool['asr']

    connection_handler = None
    try:
        while True:
            assert websocket.application_state == WebSocketState.CONNECTED
            message = await websocket.receive()
            websocket._raise_on_disconnect(message)
            ...

流程拆解:

  1. await websocket.accept():接受 WebSocket 握手,完成协议升级;
  2. 获取引擎实例:从全局引擎池取出 asr 引擎(engine_pool['asr']);
  3. 延迟创建连接处理器:connection_handler 初始为 None,只有客户端发送 start 信令时才通过 asr_model.new_handler() 创建(注释中保留了旧版 PaddleASRConnectionHanddler 的写法,实际代码已改为引擎自身的工厂方法);
  4. 消息循环:通过 websocket.receive() 持续接收客户端消息,直到收到 end 信令或连接断开。这里直接复用了 Starlette 的 _raise_on_disconnect 来检测断连异常。

3.2 文本信令协议:start / end / 异常兜底

每次循环中,代码先判断消息中是否包含 "text" 字段(对应 JSON 信令帧),然后解析其中的 signal 字段(asr_api.py):

信令 服务端行为 服务端响应
start 调用 asr_model.new_handler() 创建连接处理器,准备接收 PCM 音频 {"status": "ok", "signal": "server_ready"}
end 对剩余音频做最终解码(decode(is_finished=True))、重打分(rescoring())、取结果与字级时间戳、reset() 重置连接 {"status": "ok", "signal": "finished", "result": ..., "times": ...},随后 break 退出循环
无 signal 字段或未知值 忽略该帧 {"status": "ok", "message": "no valid json data"}

end 信令的响应中同时包含两个关键字段:

  • result:整句最终识别文本;
  • times:字级时间戳列表,每项形如 {"w": "我", "bg": 0.0, "ed": 0.7},bg 为起始秒、ed 为结束秒。

3.3 二进制音频帧与端点检测

当消息包含 "bytes" 字段时,即为一段 PCM 音频数据(asr_api.py):

elif "bytes" in message:
    message = message["bytes"]
    connection_handler.extract_feat(message)
    connection_handler.decode(is_finished=False)

    if connection_handler.endpoint_state:
        logger.info("endpoint: detected and rescoring.")
        connection_handler.rescoring()
        word_time_stamp = connection_handler.get_word_time_stamp()

    asr_results = connection_handler.get_result()

    if connection_handler.endpoint_state:
        if connection_handler.continuous_decoding:
            logger.info("endpoint: continue decoding")
            connection_handler.reset_continuous_decoding()
        else:
            logger.info("endpoint: exit decoding")
            resp = {"status": "ok", "signal": "finished", 'result': asr_results, 'times': word_time_stamp}
            await websocket.send_json(resp)
            break

    resp = {'result': asr_results}
    await websocket.send_json(resp)

核心机制:

  • 特征提取与解码:每收到一段 PCM,先 extract_feat(message) 提取特征,再 decode(is_finished=False) 做增量解码;
  • 端点检测(endpoint detection):解码后检查 connection_handler.endpoint_state,若检测到端点则立即 rescoring()(重打分)并取出字级时间戳;
  • 连续解码开关:continuous_decoding 决定检测到端点后的行为——为 True 时调用 reset_continuous_decoding() 继续解码下一条语句(适用于长音频连续识别);为 False 时直接回发 finished 信令并结束本轮连接;
  • 增量返回部分结果:未触发端点时,每包音频都会回发 {'result': asr_results},客户端因此可以看到识别文本随语音输入逐字增长。

3.4 断开处理

整个循环被 try/except WebSocketDisconnect 包裹,连接异常断开时记录错误日志(asr_api.py),由 FastAPI/Starlette 完成资源回收。

四、流式语音合成 WebSocket 端点:tts_api.py

4.1 引擎类型选择

tts_api.py 在建立连接后根据引擎类型动态导入连接处理器:

if tts_engine.engine_type == "online":
    from paddlespeech.server.engine.tts.online.python.tts_engine import PaddleTTSConnectionHandler
elif tts_engine.engine_type == "online-onnx":
    from paddlespeech.server.engine.tts.online.onnx.tts_engine import PaddleTTSConnectionHandler
else:
    logger.error("Online tts engine only support online or online-onnx.")
    sys.exit(-1)

即流式 TTS 支持两种引擎后端:

4.2 连接生命周期与 session

/paddlespeech/tts/streaming 端点的信令处理(tts_api.py):

  • start:生成一个 uuid.uuid1().hex 会话 ID session,创建 PaddleTTSConnectionHandler(tts_engine),回发 {"status": 0, "signal": "server ready", "session": session};
  • end:将 connection_handler 置空,回发 {"status": 0, "signal": "connection will be closed", "session": session} 后 break 关闭连接;
  • 其他信令:回发 {"status": 0, "signal": "no valid json data"}。

4.3 文本合成与流式音频返回

当消息中没有 signal 但包含 text 字段时,进入合成流程(tts_api.py):

elif 'text' in message:
    text = message["text"]
    spk_id = message["spk_id"]

    wav_generator = connection_handler.run(sentence=text, spk_id=spk_id)

    while True:
        try:
            tts_results = next(wav_generator)
            resp = {"status": 1, "audio": tts_results}
            await websocket.send_json(resp)
        except StopIteration as e:
            resp = {"status": 2, "audio": ''}
            await websocket.send_json(resp)
            logger.info("Complete the synthesis of the audio streams")
            break
        except Exception as e:
            resp = {"status": -1, "audio": ''}
            await websocket.send_json(resp)
            break

要点:

  • 合成是边推理边发送的:connection_handler.run() 返回一个生成器 wav_generator,每次 next() 产出一段已合成的音频帧,立即通过 send_json 推送给客户端;
  • 状态码语义:1 表示音频数据帧,2 表示合成完成(StopIteration),-1 表示合成异常;
  • 请求帧需要同时携带 text(待合成文本)与 spk_id(说话人 ID);
  • 由于是流式合成,客户端可以做到“首包响应即播放”,这正是流式 TTS 低延迟体验的关键。

4.4 采样率查询接口

除 WebSocket 端点外,tts_api.py 还暴露了一个 HTTP GET 端点:

@router.get("/paddlespeech/tts/streaming/samplerate")
def get_samplerate():
    ...
    sample_rate = tts_engine.sample_rate
    response = {"sample_rate": sample_rate}
    ...

客户端可在建立合成连接前查询引擎的合成采样率,用于配置播放设备或音频格式转换。

五、配套配置文件:从 engine_list 到 protocol 的完整约定

ws 层路由的启用与否、引擎类型的选择,全部由服务端 YAML 配置驱动。仓库中与 WebSocket 服务直接相关的配置如下:

配置文件 用途 协议 引擎
paddlespeech/server/conf/ws_conformer_application.yaml 流式 ASR(Conformer 在线模型) websocket asr_online
paddlespeech/server/conf/ws_conformer_wenetspeech_application_faster.yaml 流式 ASR(更快但精度略降的配置) websocket asr_online
paddlespeech/server/conf/ws_ds2_application.yaml 流式 ASR(DeepSpeech2 + ONNX) websocket asr_online-onnx
paddlespeech/server/conf/tts_online_application.yaml 流式 TTS(HTTP 或 WebSocket 可切换) http(可改 websocket) tts_online-onnx
demos/streaming_tts_server/conf/tts_online_ws_application.yaml 流式 TTS(WebSocket 专用配置) websocket tts_online-onnx

以流式 ASR 配置 ws_conformer_application.yaml 为例,关键参数如下:

host: 0.0.0.0
port: 8090
protocol: 'websocket'          # websocket 仅支持在线(online)引擎类型
engine_list: ['asr_online']    # 任务_引擎类型

asr_online:
    model_type: 'conformer_online_multicn'
    am_model:                   # AM 静态模型 pdmodel 文件 [可选]
    am_params:                  # AM 静态模型 pdiparams 文件 [可选]
    lang: 'zh'
    sample_rate: 16000
    cfg_path:
    decode_method:
    num_decoding_left_chunks: -1   # -1 表示使用全部左侧块(全局注意力)
    force_yes: True
    device: cpu                    # cpu 或 gpu:id
    continuous_decoding: True      # 检测到端点后是否继续解码

    am_predictor_conf:             # 推理器配置
        switch_ir_optim: True
        glog_info: False
        summary: True

    chunk_buffer_conf:             # 音频分块缓冲参数
        window_n: 7                # 帧
        shift_n: 4                 # 帧
        window_ms: 25              # 毫秒
        shift_ms: 10               # 毫秒
        sample_rate: 16000
        sample_width: 2            # 2 字节(16bit PCM)

参数含义说明:

  • engine_list 是服务启动的核心:init_engine_pool 会逐个实例化列表中的引擎(engine_pool.py),而 setup_router 则依据同样的任务名决定挂载哪些 WebSocket 路由;
  • protocol: 'websocket' 明确声明该服务只支持 WebSocket 协议。demo 文档也特别强调:流式语音识别服务只支持 websocket 协议,不支持 http 协议(见 demos/streaming_asr_server/README_cn.md);
  • continuous_decoding: True 直接对应 asr_api.py 中端点检测后的分支逻辑(3.3 节),启用后长音频可连续识别;
  • chunk_buffer_conf 定义了服务端从 PCM 流中切分块(chunk)的窗口/移位参数,直接决定端到端延迟与识别精度之间的平衡。

流式 TTS 配置(tts_online_ws_application.yaml)中还有一组流式合成特有的参数:

am: 'fastspeech2_cnndecoder_csmsc_onnx'   # 声学模型,cnndecoder 版本支持流式 AM 推理
am_block: 72
am_pad: 12                                # am_pad 设为 12 时流式合成效果与非流式一致
voc: 'mb_melgan_csmsc_onnx'               # 声码器,mb_melgan / hifigan 均支持流式推理
voc_block: 36
voc_pad: 14                               # mb_melgan 建议 14(等价于非流式),最小可到 7
voc_upsample: 300                         # 应与 voc 配置中的 n_shift 一致

注释中的取值建议非常关键:am_pad=12、voc_pad=14 时流式合成音频与非流式完全一致;voc_pad 最低可降到 7,音频听感仍正常——这是做延迟调优时的直接依据。

六、端到端实战:启动 WebSocket 流式服务并调用

6.1 流式 ASR(WebSocket)

服务端启动(在 PaddleSpeech/demos/streaming_asr_server 目录下):

# 命令行方式(推荐),默认 CPU,改 device 参数可部署到 GPU
paddlespeech_server start --config_file ./conf/ws_conformer_wenetspeech_application.yaml

# 更快的解码速度,但精度略降
paddlespeech_server start --config_file ./conf/ws_conformer_wenetspeech_application_faster.yaml

客户端调用:

paddlespeech_client asr_online --server_ip 127.0.0.1 --port 8090 --input ./zh.wav

客户端参数(摘自 demos/streaming_asr_server/README_cn.md):

  • server_ip:服务端 IP,默认 127.0.0.1;
  • port:服务端口,默认 8090;
  • input(必填):待识别音频,必须是 WAV 格式且采样率与模型一致(16k);
  • sample_rate:音频采样率,默认 16000;
  • lang:语言,默认 zh_cn;
  • audio_format:音频格式,默认 wav;
  • punc.server_ip / punc.server_port:标点预测服务地址(可选,默认 None)。

客户端运行时会打印逐步累积的识别结果,最终帧形如:

client final receive msg={'status': 'ok', 'signal': 'finished',
'result': '我认为跑步最重要的就是给我带来了身体健康',
'times': [{'w': '我', 'bg': 0.0, 'ed': 0.7}, ...]}

注意,初次连接时服务端需要加载模型,响应时间会略长;127.0.0.1 不可达时应替换为实际服务 IP。

6.2 流式 TTS(WebSocket)

服务端启动(修改 tts_online_application.yaml 将 protocol 设为 websocket,或直接使用 tts_online_ws_application.yaml):

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

客户端调用(--protocol websocket 指定 WebSocket 协议):

paddlespeech_client tts_online --server_ip 127.0.0.1 --port 8092 --protocol websocket --input "您好,欢迎使用百度飞桨语音合成服务。" --output output.wav

客户端参数(摘自 demos/streaming_tts_server/README_cn.md):

  • server_ip:服务端 IP,默认 127.0.0.1;
  • port:服务端口,默认 8092;
  • protocol:可选 [http, websocket],默认 http;
  • input(必填):待合成文本;
  • spk_id:说话人 ID,默认 0(当前代码仅支持单说话人模型,该参数暂不生效);
  • output:合成音频输出路径,默认 None(不保存);
  • play:是否边合成边播放,默认 False;播放需依赖 pyaudio 库。

从客户端日志可以看到流式效果的关键指标——首包响应时间与 RTF:

首包响应:0.2124948501586914 s
尾包响应:3.199106454849243 s
音频时长:3.825 s
RTF: 0.8363677006141812

6.3 Python API 调用方式

除命令行外,两个 demo 都提供了等价的 Python API:

# 服务端
from paddlespeech.server.bin.paddlespeech_server import ServerExecutor

server_executor = ServerExecutor()
server_executor(config_file="./conf/ws_conformer_wenetspeech_application_faster.yaml",
                log_file="./log/paddlespeech.log")
# 流式 ASR 客户端
from paddlespeech.server.bin.paddlespeech_client import ASROnlineClientExecutor

asrclient_executor = ASROnlineClientExecutor()
res = asrclient_executor(input="./zh.wav", server_ip="127.0.0.1",
                         port=8090, sample_rate=16000)
# 流式 TTS 客户端
from paddlespeech.server.bin.paddlespeech_client import TTSOnlineClientExecutor

executor = TTSOnlineClientExecutor()
executor(input="您好,欢迎使用百度飞桨语音合成服务。",
         server_ip="127.0.0.1", port=8092, protocol="websocket",
         spk_id=0, output="./output.wav", play=False)

paddlespeech_server start --help 可查看服务启动参数:--config_file(配置文件,默认 ./conf/application.yaml)与 --log_file(日志文件,默认 ./log/paddlespeech.log)。

七、设计要点总结

从 asr_api.py 与 tts_api.py 的实现可以总结出 PaddleSpeech WebSocket 服务层设计的几个核心原则:

  1. 信令与数据分离:文本帧(JSON 信令)与二进制帧(PCM 音频)通过 text / bytes 字段区分,同一个连接上交替传输,无需额外建立数据通道;
  2. 延迟创建、按需销毁:连接处理器在收到 start 信令时才创建,end 或端点结束或断连时销毁,每个 WebSocket 连接独占一个处理器实例,互不干扰;
  3. 增量返回:ASR 逐包返回部分识别结果、TTS 逐帧返回合成音频,这是实现低首包延迟的基础;
  4. 端点检测与连续解码:通过 endpoint_state 与 continuous_decoding 的组合,支持“整句结束即返回、长音频连续识别”两种模式;
  5. 配置驱动路由:setup_router 与 init_engine_pool 共用 engine_list 语义,任务启停、协议选择(websocket / http)完全由 YAML 决定,无需改动代码。

如需继续深入,可以沿着以下仓库路径阅读:引擎池初始化见 paddlespeech/server/engine/engine_pool.py,ASR 在线引擎与连接处理器见 paddlespeech/server/engine/asr/online,TTS 在线引擎见 paddlespeech/server/engine/tts/online;API 文档的 Sphinx 定义(automodule 指令)位于 docs/source/api/paddlespeech.server.ws.rst 及其子页面 paddlespeech.server.ws.asr_api.rst 与 paddlespeech.server.ws.tts_api.rst。

登录后查看全文
PaddleSpeech