PaddleSpeech CLS 音频分类 RESTful API 深度解析：从 FastAPI 路由到引擎调用的完整服务链路-育师

人工智能
语音
音频

【免费下载链接】PaddleSpeech

Easy-to-use Speech Toolkit including Self-Supervised Learning model, SOTA/Streaming ASR with punctuation, Streaming TTS with text frontend, Speaker Verification System, End-to-End Speech Translation and Keyword Spotting. Won NAACL2022 Best Demo Award.

项目地址：https://gitcode.com/gh_mirrors/pa/PaddleSpeech

点击查看免费下载

导读

本文围绕 PaddleSpeech 服务端 RESTful 体系中的 CLS（音频分类）模块展开，以paddlespeech.server.restful.cls_api模块为核心，完整拆解其 HTTP 接口设计、请求/响应模型、后端引擎分派机制与 topk 后处理逻辑。读者将掌握如何通过paddlespeech_client cls命令或 Python API 调用音频分类服务，理解cls_python（动态图推理）与cls_inference（Paddle Inference 静态图推理）两种引擎的差异，并能独立修改application.yaml配置部署自己的 CLS 服务。

一、模块定位：CLS 服务在 RESTful 体系中的位置

PaddleSpeech 服务端在 paddlespeech/server/restful 目录下按"一个语音任务一个 API 模块"的方式组织 RESTful 接口，包含asr_api.py、tts_api.py、cls_api.py、text_api.py、vector_api.py与acs_api.py。其中cls_api.py专司音频分类任务（Audio Classification，缩写 CLS），对外暴露两个 HTTP 端点：

GET /paddlespeech/cls/help：返回服务能力说明（输入输出格式提示）；
POST /paddlespeech/cls：接收 base64 编码的音频并返回 Top-K 分类结果。

这些模块各自声明一个 FastAPIAPIRouter，最终由 api.py 中的setup_router(api_list)按服务端启动时配置的engine_list决定挂载哪些路由。从源码看，engine_list中出现的任务名（如cls_python中的cls）会通过_router.include_router(cls_router)被注册进 FastAPI 应用，因此 CLS 路由能否生效，取决于 application.yaml 中engine_list是否包含cls_python或cls_inference。

二、接口契约：请求模型与响应模型

2.1 请求模型 CLSRequest

在 request.py 中，CLS 请求体由CLSRequest（继承pydantic.BaseModel）定义，仅含两个字段：

字段	类型	必填	默认值	说明
`audio`	str	是	无	音频文件内容的 base64 编码字符串
`topk`	int	否	1	返回分类得分最高的前 K 个类别

一个典型的请求体示例（源码注释中给出）为：

{ "audio": "exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf...", "topk": 1 }

注意audio字段必须是base64 编码后的 wav 音频字节串，服务端在 cls_api.py 中通过base64.b64decode(request_body.audio)解码为原始字节后交给后端引擎处理。

2.2 响应模型 CLSResponse

CLS 的响应结构在 response.py 中由三个 Pydantic 模型分层定义：

CLSResults：单条分类结果，包含class_name（类别名）与prob（该类别得分）；
CLSResult：整体结果，包含topk（回显请求参数）与results（List[CLSResults]）；
CLSResponse：统一响应外壳，包含success、code、message、result四部分。

源码注释中的响应示例：

{ "success": true, "code": 0, "message": { "description": "success" }, "result": { "topk": 1, "results": [ { "class": "Speech", "prob": 0.9027184844017029 } ] } }

2.3 统一错误响应

当请求处理抛出异常时，cls_api.py 会调用failed_response()构造错误响应。错误码定义于 paddlespeech/server/utils/errors.py：

错误码	枚举名	含义
200	`SERVER_OK`	成功
400	`SERVER_PARAM_ERR`	输入参数非法
404	`SERVER_TASK_NOT_EXIST`	任务不存在
500	`SERVER_INTERNAL_ERR`	内部错误
502	`SERVER_NETWORK_ERR`	网络异常
509	`SERVER_UNKOWN_ERR`	未知错误

其中ServerBaseException会携带具体错误码与消息透传，其余未知异常统一按SERVER_UNKOWN_ERR（509）处理。

三、请求处理主流程：POST /paddlespeech/cls 逐行解析

cls_api.py 中cls()函数的处理链路可分为五个阶段：

解码音频：audio_data = base64.b64decode(request_body.audio)，将 base64 字符串还原为原始音频字节流；
获取引擎：调用get_engine_pool()取得全局引擎池，再以engine_pool['cls']取出 CLS 引擎单例；
按引擎类型分派：根据cls_engine.engine_type动态导入对应实现：
- "python"→ 导入paddlespeech.server.engine.cls.python.cls_engine中的PaddleCLSConnectionHandler（动态图推理）；
- "inference"→ 导入paddlespeech.server.engine.cls.paddleinference.cls_engine中的PaddleCLSConnectionHandler（Paddle Inference 静态图推理）；
- 其他取值直接记录错误并sys.exit(-1)，日志明确提示 "Offline cls engine only support python or inference."；
执行推理：connection_handler.run(audio_data)内部完成前处理（特征提取）与模型推理，随后connection_handler.postprocess(request_body.topk)计算 Top-K 分类结果；
组装响应：将topk与results放入统一 JSON 结构返回，HTTP 响应模型为Union[CLSResponse, ErrorResponse]。

值得关注的是，引擎池的引入使所有 RESTful 任务共享同一套"按任务名取引擎"的机制，CLS 引擎在服务启动阶段即被初始化一次（单例），请求到达时直接复用，避免重复加载模型。

四、后端引擎：python 与 paddleinference 两种实现对比

4.1 python 引擎（动态图）

paddlespeech/server/engine/cls/python/cls_engine.py 中的CLSEngine.init()完成三件事：设置设备（优先取配置device，否则paddle.get_device()）、初始化CLSServerExecutor（复用 CLI 推理器 paddlespeech/cli/cls/infer.py）、通过_init_from_path(model, cfg_path, ckpt_path, label_file)加载模型。加载模型时若未显式指定路径，会以model_type + '-32k'（如panns_cnn14-32k）为 tag 自动从CommonTaskResource下载预训练资源。

PaddleCLSConnectionHandler的推理实现为：

preprocess(io.BytesIO(audio_data))：把解码后的字节流包装成BytesIO，交给 infer.py 中的preprocess，内部通过soundfile_load读取音频，再用LogMelSpectrogram提取梅尔对数谱特征，最终转置为[B, 1, T, N]形状存入self._inputs['feats']；
infer()：self.model(self._inputs['feats'])直接以动态图前向计算得到 logits；
postprocess(topk)：assert topk <= len(self._label_list)校验 topk 不越界后，对 logits 按得分降序取前topk个索引，映射为{class_name, prob}列表返回。

4.2 inference 引擎（Paddle Inference 静态图）

paddlespeech/server/engine/cls/paddleinference/cls_engine.py 面向部署场景，使用静态图预测：

_init_from_path支持显式指定model_path（pdmodel）、params_path（pdiparams）、cfg_path、label_file；未指定时同样按model_type + '-32k'自动下载资源；
通过init_predictor(model_file, params_file, predictor_conf)创建 Paddle Inference 预测器，predictor_conf中的device、switch_ir_optim、glog_info、summary等参数可配置运行行为；
infer()使用run_model(self.predictor, [feats.numpy()])执行静态图推理，结果存入self._outputs['logits']。

两种引擎的postprocess逻辑完全一致，唯一区别是动态图用result.numpy()、静态图用np.squeeze(logits, axis=0)取数值。这保证了上层cls_api.py无需感知引擎差异，只需依赖engine_type做一次模块导入分派。

五、服务端配置：application.yaml 中的 CLS 配置项

CLS 服务端的全部配置集中在 application.yaml。顶层engine_list决定启动哪些任务，CLS 相关取值有cls_python与cls_inference两种。

cls_python（动态图引擎）配置项：

cls_python: # model choices=['panns_cnn14', 'panns_cnn10', 'panns_cnn6'] model: 'panns_cnn14' cfg_path: # [optional] Config of cls task. ckpt_path: # [optional] Checkpoint file of model. label_file: # [optional] Label file of cls task. device: # set 'gpu:id' or 'cpu'

cls_inference（静态图引擎）配置项：

cls_inference: # model_type choices=['panns_cnn14', 'panns_cnn10', 'panns_cnn6'] model_type: 'panns_cnn14' cfg_path: model_path: # the pdmodel file of am static model [optional] params_path: # the pdiparams file of am static model [optional] label_file: # [optional] Label file of cls task. predictor_conf: device: # set 'gpu:id' or 'cpu' switch_ir_optim: True glog_info: False # True -> print glog summary: True # False -> do not show predictor config

参数说明：

model/model_type：可选panns_cnn14、panns_cnn10、panns_cnn6（PANNs 系列音频分类模型），默认panns_cnn14；
cfg_path：特征提取配置（yaml），留空则使用预训练资源自带的默认配置；
ckpt_path（python 引擎）/model_path、params_path（inference 引擎）：模型权重路径，留空自动下载；
label_file：类别标签文件，每行一个类别名，与 logits 索引一一对应；
device：gpu:id或cpu，留空使用 Paddle 默认设备。

配置文件中的特征提取相关参数（如sample_rate、n_fft、hop_length、n_mels等）实际由cfg_path指向的 yaml 中feature字段控制，并在 infer.py 的preprocess中生效，服务端部署时通常无需改动。

六、客户端调用实战

6.1 准备示例音频与启动服务

CLS 客户端调用可复用demos/speech_server/README_cn.md中给出的示例音频zh.wav。服务端启动命令为：

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

确保engine_list中包含cls_python或cls_inference。

6.2 命令行方式（推荐）

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

参数说明（对应 paddlespeech_client.py 中CLSClientExecutor的定义）：

server_ip：服务端 IP，默认127.0.0.1；
port：服务端口，默认8090；
input（必填）：待分类的音频文件路径；
topk：返回 Top-K 分类结果，默认1。

使用paddlespeech_client cls --help可查看全部参数。官方 README 中的真实运行输出如下（模型panns_cnn14，音频zh.wav）：

[2022-03-09 20:44:39,974] [ INFO] - {'success': True, 'code': 200, 'message': {'description': 'success'}, 'result': {'topk': 1, 'results': [{'class_name': 'Speech', 'prob': 0.9027184844017029}]}} [2022-03-09 20:44:39,975] [ INFO] - Response time 0.104360 s.

6.3 Python API 方式

from paddlespeech.server.bin.paddlespeech_client import CLSClientExecutor clsclient_executor = CLSClientExecutor() res = clsclient_executor( input="./zh.wav", server_ip="127.0.0.1", port=8090, topk=1) print(res.json())

从源码看，CLSClientExecutor.__call__内部将音频文件用wav2base64(input)编码为 base64，组装 JSON 体{"audio": audio, "topk": topk}后requests.post到http://<server_ip>:<port>/paddlespeech/cls，与cls_api.py接收的请求契约完全对应。

6.4 快速验证脚本

仓库同时提供了现成的调用脚本 demos/speech_server/cls_client.sh，内容即：

paddlespeech_client cls --server_ip 127.0.0.1 --port 8090 --input ./zh.wav --topk 1

七、一次完整请求的时序总结

综合前文源码分析，一次 CLS RESTful 请求的完整链路为：

客户端将 wav 音频 base64 编码，连同topk以 JSON 形式 POST 至/paddlespeech/cls；
cls_api.cls()解码音频字节，从引擎池取出 CLS 引擎，按engine_type动态导入对应的PaddleCLSConnectionHandler；
handler 依次执行preprocess（soundfile 读音频 + LogMelSpectrogram 特征提取）、infer（动态图或静态图前向）、postprocess（topk 排序与标签映射）；
结果封装为{success, code, message, result:{topk, results:[{class_name, prob}]}}返回；任何异常经failed_response转为统一错误 JSON。