PaddleSpeech WebSocket 服务层源码解析:`paddlespeech.server.ws` 模块的流式 ASR / TTS 接口设计
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)
...
流程拆解:
await websocket.accept():接受 WebSocket 握手,完成协议升级;- 获取引擎实例:从全局引擎池取出
asr引擎(engine_pool['asr']); - 延迟创建连接处理器:
connection_handler初始为None,只有客户端发送start信令时才通过asr_model.new_handler()创建(注释中保留了旧版PaddleASRConnectionHanddler的写法,实际代码已改为引擎自身的工厂方法); - 消息循环:通过
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 支持两种引擎后端:
online:基于 Paddle 动态图/静态图推理的在线 TTS 引擎(源码路径 paddlespeech/server/engine/tts/online/python);online-onnx:基于 ONNX Runtime 的在线 TTS 引擎(源码路径 paddlespeech/server/engine/tts/online/onnx),配置注释说明其推理速度更快(见 tts_online_application.yaml)。
4.2 连接生命周期与 session
/paddlespeech/tts/streaming 端点的信令处理(tts_api.py):
start:生成一个uuid.uuid1().hex会话 IDsession,创建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 服务层设计的几个核心原则:
- 信令与数据分离:文本帧(JSON 信令)与二进制帧(PCM 音频)通过
text/bytes字段区分,同一个连接上交替传输,无需额外建立数据通道; - 延迟创建、按需销毁:连接处理器在收到
start信令时才创建,end或端点结束或断连时销毁,每个 WebSocket 连接独占一个处理器实例,互不干扰; - 增量返回:ASR 逐包返回部分识别结果、TTS 逐帧返回合成音频,这是实现低首包延迟的基础;
- 端点检测与连续解码:通过
endpoint_state与continuous_decoding的组合,支持“整句结束即返回、长音频连续识别”两种模式; - 配置驱动路由:
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。