PaddleSpeech 文本标点预测服务 text_api 模块深度解析与 RESTful 接口实战

PaddleSpeech 文本标点预测服务 text_api 模块深度解析与 RESTful 接口实战【免费下载链接】PaddleSpeechEasy-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/PaddleSpeechPaddleSpeech 服务端paddlespeech_server内置了基于 HTTP 协议的文本处理能力其中text_api模块负责对外暴露**标点预测Punctuation Restoration / text task: punc**的 RESTful 接口接收一段无标点的中文文本返回补全标点后的结果可用于 ASR 转写文本的后期处理、字幕生成、聊天文本美化等场景。本文以 docs/source/api/paddlespeech.server.restful.text_api.rst 对应的 text_api.py 模块为切入点结合请求/响应模型、引擎池、文本引擎、服务端配置与客户端实现从接口契约到源码调用链给出完整讲解。读完本文你将能够独立启动一个带标点预测能力的 PaddleSpeech 离线服务并正确构造 HTTP 请求与解析响应。text_api 模块在 PaddleSpeech 服务架构中的位置PaddleSpeech 的服务端采用 FastAPI Uvicorn 搭建RESTful 层按语音任务拆分为多个独立的路由模块text_api是其中之一。在 api.py 的setup_router中根据启动配置传入的 api 列表动态挂载各路由elif api_name.lower() text: _router.include_router(text_router)也就是说只有当服务配置的engine_list中显式包含text_python时text 路由才会被注册并对外提供标点预测能力默认配置 application.yaml 中engine_list: [asr_python, tts_python, cls_python, text_python, vector_python]已包含它。text_api模块本身非常精简核心是一个APIRouter实例和两个接口函数text_api.py方法路径作用GET/paddlespeech/text/help返回接口说明与字段示例便于探测服务是否可用POST/paddlespeech/text提交待标点文本返回补全标点后的结果接口契约请求体与响应体模型请求体 TextRequest标点预测的请求非常简单只包含一个必填字段textrequest.pyclass TextRequest(BaseModel): text: str该模型由 Pydantic 定义FastAPI 会自动完成请求体的 JSON 校验与反序列化。一个合法的 POST 请求体示例{ text: 我认为跑步最重要的就是给我带来了身体健康 }响应体 TextResponse正常响应由三层结构组成response.py最外层包含success与code中间message为描述信息result中通过punc_text字段返回补全标点后的文本{ success: true, code: 200, message: { description: success }, result: { punc_text: 我认为跑步最重要的就是给我带来了身体健康。 } }异常响应 ErrorResponse当请求处理失败时接口返回统一的错误结构response.py{ success: false, code: 509, message: { description: Unknown error occurred. } }ErrorResponse只有success、code、message三层不含result。接口的返回类型声明为Union[TextResponse, ErrorResponse]text_api.pyFastAPI 据此生成 OpenAPI 文档。接口处理流程源码解读/paddlespeech/text的 POST 处理函数内部逻辑分为三步text_api.py值得注意的一个细节是该函数在源码中的命名为asr这是历史遗留命名但函数签名与行为完全服务于 text 任务不影响接口使用。提取请求文本从request_body.text取出原始字符串并打印服务端日志。从引擎池获取 text 引擎并执行推理通过get_engine_pool()拿到全局引擎池按text键取出TextEngine实例再包装成PaddleTextConnectionHandler调用run(text)完成一次完整的预处理—推理—后处理流程。构造响应若推理结果punc_text为None例如模型未输出有效标点则回退为原始text原样返回保证接口在任何情况下都有稳定的响应结构随后按success/code/message/result四层结构封装 JSON 返回。help接口则直接返回一个静态 JSON其中result.punc_text字段标注为 The punctuation text content向调用方明示该服务返回的字段含义text_api.py。异常与错误码映射处理函数对异常做了两级兜底text_api.py捕获ServerBaseException按异常携带的error_code与msg生成失败响应兜底捕获BaseException统一映射为ErrorCode.SERVER_UNKOWN_ERR值为 509并打印完整 traceback 便于排查。错误码枚举定义在 errors.pyfailed_response会依据错误码自动填充对应的默认描述errors.py错误码常量含义200SERVER_OK成功400SERVER_PARAM_ERR输入参数不合法404SERVER_TASK_NOT_EXIST任务不存在500SERVER_INTERNAL_ERR内部错误502SERVER_NETWORK_ERR网络异常509SERVER_UNKOWN_ERR未知错误引擎池与 TextEngine 初始化链路RESTful 层本身不持有模型模型统一由引擎池管理。init_engine_pool遍历配置中的engine_list将task_engine_type拆分为引擎名与类型通过EngineFactory创建引擎并调用initengine_pool.py。因此text_python会被解析为enginetext、engine_typepython这也是text_api中engine_pool[text]能取到TextEngine的原因。TextEngine.inittext_engine.py完成以下工作设备设置优先使用配置中的device如gpu:0或cpu缺省时回退到paddle.get_device()并调用paddle.set_device生效失败时打印错误日志并返回False服务启动流程随即中断。执行器创建实例化TextServerExecutor它是 CLI 层TextExecutor的薄包装见 infer.py。模型加载分流依据config.model_type是否包含fast关键字选择两条初始化路径含fast如ernie_linear_p3_wudao_fast类模型走_init_from_path_new使用ErnieLinear(**config[model])从cfg_path直接构建模型并从ckpt_path加载权重tokenizer 使用ernie-3.0-mini-zhinfer.py不含fast如默认的ernie_linear_p3_wudao走_init_from_path通过task_resource自动解析模型资源tokenizer 使用ernie-1.0infer.py。无论哪条路径都会从vocab_file逐行读取标点符号表到self._punc_list供后处理阶段把模型输出的标签映射回标点字符。PaddleTextConnectionHandler一次标点预测的完整推理PaddleTextConnectionHandler负责处理每个请求text_engine.py构造时从执行器中取出task、model、tokenizer、_punc_list并用两个OrderedDict暂存中间结果。对外入口run(text)串联三步1. 预处理 preprocess只支持task punc其余任务抛出NotImplementedErrortext_engine.py调用TextExecutor._clean_text清洗文本先lower()转小写再用正则剔除除字母、数字、汉字以外的字符并删除输入中已存在的标点_punc_list中除首项外的全部字符防止干扰模型判断infer.py断言清洗后文本非空空文本直接视为非法输入调用 tokenizer 对逐字列表做分词return_lengthTrue且is_split_into_wordsTrue得到input_ids、token_type_idsseg_ids与seq_len存入_inputs。2. 模型推理 infer将input_ids、seg_ids转为 Paddle Tensor 并增加 batch 维度送入ErnieLinear模型得到logits取最后一个维度上的argmax得到每个 token 的标点类别预测text_engine.py。整个过程通过paddle.no_grad()关闭梯度计算。3. 后处理 postprocess把预测标签还原为带标点的文本text_engine.py用convert_ids_to_tokens把input_ids还原为 token 序列同时截取对应的预测标签去掉首尾的特殊 token逐 token 拼接字符当标签l ! 0即非无标点类时追加标点fast 模型使用_punc_list[l - 1]因新训练流程在_punc_list头部插入了 0 占位非 fast 模型直接使用_punc_list[l]infer.py最终返回形如我认为跑步最重要的就是给我带来了身体健康。的字符串。服务端配置application.yaml 中的 text_python标点预测引擎的配置段位于 application.yaml################################### Text ######################################### ################### text task: punc; engine_type: python ####################### text_python: task: punc model_type: ernie_linear_p3_wudao lang: zh sample_rate: 16000 cfg_path: # [optional] ckpt_path: # [optional] vocab_file: # [optional] device: # set gpu:id or cpu各字段含义与作用配置项说明task文本任务类型当前仅支持punc标点预测model_type模型标识默认ernie_linear_p3_wudao可选ernie_linear_p7_wudao及带fast后缀的快速版本决定初始化路径与 tokenizer 选择lang语言默认zhCLI 执行器支持zh/en两个取值infer.pysample_rate采样率默认 16000文本任务实际不消费音频该字段为统一配置格式保留cfg_path/ckpt_path/vocab_file模型配置、权重与标点词表路径均标注为 optional缺省时由task_resource按model_type-task-lang自动下载并定位预训练资源infer.pydevice推理设备写gpu:0或cpu留空则使用paddle.get_device()启动服务时使用paddlespeech_server start --config_file ./conf/application.yaml若在容器环境中客户端无法访问服务可将配置中的host从0.0.0.0改为本机实际 IP。可用paddlespeech_server stats --task text查看该任务支持的全部模型清单。客户端调用实战命令行方式推荐仓库提供的示例脚本 text_client.sh 展示了最简调用paddlespeech_client text --server_ip 127.0.0.1 --port 8090 --input 今天的天气真好啊你下午有空吗我想约你一起去吃饭更完整的用法见 README_cn.mdpaddlespeech_client text --server_ip 127.0.0.1 --port 8090 --input 我认为跑步最重要的就是给我带来了身体健康客户端参数定义在TextClientExecutorpaddlespeech_client.py参数默认值是否必填说明--server_ip127.0.0.1否服务端 IP--port8090否服务端口--input无是待标点预测的文本内容期望输出服务端返回punc_text客户端直接打印文本并统计响应耗时[2022-05-09 18:19:04,397] [ INFO] - The punc text: 我认为跑步最重要的就是给我带来了身体健康。 [2022-05-09 18:19:04,397] [ INFO] - Response time 0.092407 s.首次调用需要下载并加载模型资源响应时间会略长属正常现象。Python API 方式同样复用TextClientExecutorpaddlespeech_client.pyfrom paddlespeech.server.bin.paddlespeech_client import TextClientExecutor textclient_executor TextClientExecutor() res textclient_executor( input我认为跑步最重要的就是给我带来了身体健康, server_ip127.0.0.1, port8090) print(res) # 我认为跑步最重要的就是给我带来了身体健康。从源码可以看到TextClientExecutor.__call__内部构造url http:// server_ip : str(port) /paddlespeech/text以{text: input}作为 JSON 请求体发起requests.post再解析响应中的result.punc_text返回。这一过程与 RESTful 层text_api的接口定义严格对应也可直接用任意 HTTP 工具如 curl以同样方式调用curl -X POST http://127.0.0.1:8090/paddlespeech/text \ -H Content-Type: application/json \ -d {text: 今天天气真好啊}使用场景与边界说明标点预测接口最常见的落地场景是与 ASR 服务串联ASR 输出的转写文本通常没有标点将文本送入/paddlespeech/text后即可获得可读性更强的带标点文本便于生成字幕、会议纪要与对话日志。在使用中需注意以下前提与限制服务端与客户端通过 HTTP 通信engine_list中必须包含text_python才会注册该接口输入文本会被_clean_text清洗小写化、剔除标点与非中英数字符清洗后为空会触发断言错误并返回失败响应模型加载依赖网络下载预训练资源或本地配置cfg_path/ckpt_path/vocab_file首次启动需保持网络可达推理设备通过device配置控制GPU 资源紧张时可显式设为cpu相关模块的单元测试与集成验证集中在 tests/unit/server 目录可作为二次开发与回归验证的参考。小结paddlespeech.server.restful.text_api是 PaddleSpeech 离线服务体系中文本处理能力的 HTTP 出口接口设计遵循统一的success/code/message/result四层结构内部通过引擎池 TextEnginePaddleTextConnectionHandler完成从文本清洗、ERNIE 序列标注到标点还原的完整链路。理解这一模块后你既可以基于paddlespeech_client快速接入标点预测能力也可以参照 text_api.py 的写法在 api.py 的路由框架内扩展自己的文本类服务接口。【免费下载链接】PaddleSpeechEasy-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考