PaddleOCR 基于 PaddleHub Serving 的服务化部署实战从模型安装、服务启动到请求调用与自定义扩展【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCRPaddleOCR 提供一套开箱即用的 HTTP 服务化部署方案基于 PaddleHub Serving将文本检测、方向分类、文本识别、表格识别、版面分析、PP-Structure 与关键信息抽取等能力封装为独立的服务模块一键安装、一行启动通过 JSON Base64 的 HTTP 接口对外提供 OCR 能力。本文将以deploy/hubserving目录下的官方部署文档为主线结合仓库源码逐层拆解服务包结构、模型准备、服务启动的两种方式命令行与配置文件、预测请求的发送与返回结果格式并给出自定义服务模块的完整改造流程帮助你快速把 PaddleOCR 模型变成一个可被任意业务系统调用的线上服务。1. 服务部署方式与服务包结构PaddleOCR 提供 2 种服务部署方式基于 PaddleHub Serving 的部署代码路径为deploy/hubserving即本文讲解的方式基于 PaddleServing 的部署代码路径为deploy/pdserving适用于对服务化性能有更高要求的场景。deploy/hubserving目录下共包含九种服务包覆盖从单一 OCR 子任务到整套文档结构化分析的全链路请根据实际需求选择相应服务包安装和启动deploy/hubserving/ └─ ocr_cls 文本方向分类模块服务包 └─ ocr_det 文本检测模块服务包 └─ ocr_rec 文本识别模块服务包 └─ ocr_system 文本检测文本方向分类文本识别串联服务包 └─ structure_layout 版面分析服务包 └─ structure_table 表格识别服务包 └─ structure_system PP-Structure服务包 └─ kie_ser 关键信息抽取-SER服务包 └─ kie_ser_re 关键信息抽取-SERRE服务包每个服务包内均包含 3 个文件以 2 阶段串联服务包deploy/hubserving/ocr_system为例deploy/hubserving/ocr_system/ └─ __init__.py 空文件必选 └─ config.json 配置文件可选使用配置启动服务时作为参数传入 └─ module.py 主模块必选包含服务的完整逻辑 └─ params.py 参数文件必选包含模型路径、前后处理参数等参数其中module.py是服务的灵魂它继承paddlehub.Module通过moduleinfo声明模块名与版本并实现_initialize加载模型、predict推理逻辑与serving_methodHTTP 服务入口三个核心方法见 module.py。params.py则以read_params()函数集中管理所有模型路径与推理参数见 params.py。2. 快速启动服务以下步骤以「检测 识别 2 阶段串联服务」为例如果只需要检测服务或识别服务将相应文件路径替换即可。2.1 安装 PaddleHubPaddleHub 需要python3.6.2推荐使用百度镜像源安装pip3 install paddlehub2.1.0 --upgrade -i https://mirror.baidu.com/pypi/simple2.2 下载推理模型安装服务模块前需要准备推理模型并放到正确路径。默认使用的是PP-OCRv3 模型默认模型路径如下表所示| 模型 | 路径 | | ------- | - | | 检测模型 |./inference/PP-OCRv3_mobile_det_infer/| | 识别模型 |./inference/ch_PP-OCRv3_rec_infer/| | 方向分类器 |./inference/ch_ppocr_mobile_v2.0_cls_infer/| | 版面分析模型 |./inference/picodet_lcnet_x1_0_fgd_layout_infer/| | 表格结构识别模型 |./inference/ch_ppstructure_mobile_v2.0_SLANet_infer/| | 关键信息抽取SER模型 |./inference/ser_vi_layoutxlm_xfund_infer/| | 关键信息抽取RE模型 |./inference/re_vi_layoutxlm_xfund_infer/|模型路径可在各服务包的params.py中查看和修改。例如 ocr_system/params.py 中cfg.det_model_dir ./inference/PP-OCRv3_mobile_det_infer/定义了检测模型目录cfg.rec_model_dir定义了识别模型目录。更多模型可以从 PaddleOCR 提供的模型库中下载见 docs/version2.x/ppstructure 目录下的模型列表文档也可以替换成自己训练或转换好的推理模型。2.3 安装服务模块在 Linux 环境Windows 环境请将/替换为\下执行hub install安装所需模块当前共提供以下 9 个服务模块| 服务模块 | 命令 | | ------- | - | | 检测 |hub install deploy/hubserving/ocr_det| | 分类 |hub install deploy/hubserving/ocr_cls| | 识别 |hub install deploy/hubserving/ocr_rec| | 检测识别串联 |hub install deploy/hubserving/ocr_system| | 表格识别 |hub install deploy/hubserving/structure_table| | PP-Structure |hub install deploy/hubserving/structure_system| | 版面分析 |hub install deploy/hubserving/structure_layout| | 关键信息抽取SER |hub install deploy/hubserving/kie_ser| | 关键信息抽取SERRE |hub install deploy/hubserving/kie_ser_re|2.4 启动服务2.4.1 命令行命令启动仅支持 CPU启动命令hub serving start --modules Module1Version1, Module2Version2, ... \ --port 8866 \ --use_multiprocess \ --workers \参数说明参数用途--modules/-mPaddleHub Serving 预安装模型以多个ModuleVersion键值对的形式列出当不指定 Version 时默认选择最新版本--port/-p服务端口默认为 8866--use_multiprocess是否启用并发方式默认为单进程方式推荐多核 CPU 机器使用此方式Windows 操作系统只支持单进程方式--workers在并发方式下指定的并发任务数默认为2*cpu_count-1其中cpu_count为 CPU 核数例如启动串联服务hub serving start -m ocr_system这样即完成了一个服务化 API 的部署默认使用端口号 8866。2.4.2 配置文件启动支持 CPU、GPU启动命令hub serving start -c config.json其中config.json格式如下完整示例{ modules_info: { ocr_system: { init_args: { version: 1.0.0, use_gpu: true }, predict_args: { } } }, port: 8868, use_multiprocess: false, workers: 2 }init_args中的可配参数与module.py中的_initialize函数接口一致。以 ocr_system/module.py 为例_initialize(use_gpuFalse, enable_mkldnnFalse)即对应init_args中可传入的use_gpu、enable_mkldnn字段。当use_gpu为true时表示使用 GPU 启动服务代码内部会读取CUDA_VISIBLE_DEVICES环境变量并设置cfg.gpu_mem 8000约 8GB 显存预留。predict_args中的可配参数与module.py中的predict函数接口一致。注意事项使用配置文件启动服务时其他命令行参数会被忽略如果使用 GPU 预测即use_gpu置为true则需要在启动服务之前设置CUDA_VISIBLE_DEVICES环境变量例如export CUDA_VISIBLE_DEVICES0use_gpu不可与use_multiprocess同时为true。例如使用 GPU 3 号卡启动串联服务export CUDA_VISIBLE_DEVICES3 hub serving start -c deploy/hubserving/ocr_system/config.json3. 发送预测请求配置好服务端后可使用仓库自带的测试脚本发送预测请求python tools/test_hubserving.py --server_urlserver_url --image_dirimage_path脚本需要传入以下参数参数定义见 test_hubserving.pyserver_url服务地址格式为http://[ip_address]:[port]/predict/[module_name]。例如使用配置文件分别启动了分类、检测、识别、检测分类识别 3 阶段、表格识别、PP-Structure、版面分析、KIE-SER、KIE-SERRE 服务并为每个服务修改了端口那么发送请求的 URL 将分别是http://127.0.0.1:8865/predict/ocr_det http://127.0.0.1:8866/predict/ocr_cls http://127.0.0.1:8867/predict/ocr_rec http://127.0.0.1:8868/predict/ocr_system http://127.0.0.1:8869/predict/structure_table http://127.0.0.1:8870/predict/structure_system http://127.0.0.1:8870/predict/structure_layout http://127.0.0.1:8871/predict/kie_ser http://127.0.0.1:8872/predict/kie_ser_reimage_dir测试图像路径可以是单张图片路径也可以是图像集合目录路径脚本内部通过get_image_file_list递归收集目录下所有图片visualize是否可视化结果默认为Falseoutput可视化结果保存路径默认为./hubserving_result。访问示例python tools/test_hubserving.py --server_urlhttp://127.0.0.1:8868/predict/ocr_system --image_dir./doc/imgs/ --visualizefalse从源码看test_hubserving.py 的核心调用链为读取图片二进制 →base64.b64encode编码 → 以{images: [base64串]}的 JSON 结构通过requests.post发送到server_url→ 从响应中取res r.json()[results][0]并打印。服务端收到请求后在serving_method中调用base64_to_cv2解码还原图像再进入predict完成推理见 module.py因此任意语言的 HTTP 客户端只要遵循相同的 JSON Base64 协议即可接入该服务。4. 返回结果格式说明返回结果为列表list列表中的每一项为词典dict词典一共可能包含以下字段字段名称数据类型意义anglestr文本角度textstr文本内容confidencefloat文本识别置信度或文本角度分类置信度text_regionlist文本位置坐标htmlstr表格的 html 字符串regionslist版面分析表格识别OCR 的结果每一项为一个 list包含表示区域坐标的bbox区域类型的type和区域结果的res三个字段layoutlist版面分析的结果每一项一个 dict包含版面区域坐标的bbox区域类型的labelser_reslist关键信息抽取 SER语义实体识别结果re_reslist关键信息抽取 RE关系抽取结果不同模块返回的字段不同例如文本识别服务模块的返回结果不含text_region字段具体对应关系如下字段名/模块名ocr_detocr_clsocr_recocr_systemstructure_tablestructure_systemstructure_layoutkie_serkie_ser_reangle✔✔text✔✔✔✔✔confidence✔✔✔✔✔✔text_region✔✔✔✔✔html✔✔regions✔✔layout✔ser_res✔re_res✔以串联服务为例ocr_system/module.py 中predict对每张图返回一个列表其中每个元素为{text: ..., confidence: float(score), text_region: dt_boxes[dno].astype(np.int32).tolist()}text_region是整数坐标列表便于前端直接绘制检测框。而表格识别服务structure_table/module.py返回的是{html: res[html]}即表格的 HTML 字符串版面分析服务structure_layout/module.py返回{layout: res}其中每个区域的bbox已被转换为 list 类型以便 JSON 序列化。说明如果需要增加、删除、修改返回字段可在相应模块的module.py文件中进行修改完整流程参考下一节「自定义修改服务模块」。5. 自定义修改服务模块如果需要修改服务逻辑一般需要操作以下步骤以修改deploy/hubserving/ocr_system为例停止服务hub serving stop --port/-p XXXX到deploy/hubserving/ocr_system下的module.py和params.py等文件中根据实际需求修改代码。例如如果需要替换部署服务所用的模型则需要到params.py中修改模型路径参数det_model_dir和rec_model_dir如果需要关闭文本方向分类器则将参数use_angle_cls置为False。当然同时可能还需要修改其他相关参数请根据实际情况修改调试。强烈建议修改后先直接运行module.py调试能正确运行预测后再启动服务测试。各服务包的module.py末尾均带有if __name__ __main__自测入口例如直接运行python deploy/hubserving/ocr_system/module.py即可对本机图片执行预测见 module.py。注意PP-OCRv3 识别模型使用的图片输入 shape 为3,48,320因此需要修改params.py中的cfg.rec_image_shape 3, 48, 320见 ocr_system/params.py如果不使用 PP-OCRv3 识别模型则无需修改该参数。可选如果想要重命名模块需要更改module.py文件中的以下行deploy/hubserving/ocr_system/module.py中from deploy.hubserving.ocr_system.params import read_params里的ocr_system见 module.pymoduleinfo装饰器nameocr_system中的ocr_system见 module.py。可选可能需要删除__pycache__目录以强制刷新 CPython 缓存find deploy/hubserving/ocr_system -name __pycache__ -exec rm -r {} \;安装修改后的新服务包hub install deploy/hubserving/ocr_system重新启动服务hub serving start -m ocr_system5.1 params.py 参数全景源码级解析以 ocr_system/params.py 为例read_params()返回一个Config对象集中定义了三大子任务的全部关键参数检测器DB 算法参数参数默认值说明det_algorithmDB检测算法可切换为 EAST 等det_model_dir./inference/PP-OCRv3_mobile_det_infer/检测模型目录det_limit_side_len960检测时图像最长边/最短边的缩放限制det_limit_typemax限制类型max表示按最长边缩放det_db_thresh0.3DB 二值化阈值det_db_box_thresh0.5DB 检测框阈值过滤低分框det_db_unclip_ratio1.6检测框扩张系数use_dilationFalse是否使用膨胀det_db_score_modefastDB 分数计算模式识别器CRNN 算法参数参数默认值说明rec_algorithmCRNN识别算法rec_model_dir./inference/ch_PP-OCRv3_rec_infer/识别模型目录rec_image_shape3, 48, 320识别输入 shape对应 PP-OCRv3rec_batch_num6识别批大小影响吞吐与显存max_text_length25单行文本最大长度rec_char_dict_path./ppocr/utils/ppocr_keys_v1.txt字符字典路径use_space_charTrue是否启用空格字符方向分类器参数参数默认值说明use_angle_clsTrue是否启用方向分类置False可关闭cls_model_dir./inference/ch_ppocr_mobile_v2.0_cls_infer/分类模型目录cls_image_shape3, 48, 192分类输入 shapelabel_list[0, 180]分类类别标签cls_batch_num30分类批大小cls_thresh0.9方向分类置信度阈值此外还有drop_score 0.5过滤低置信度结果、use_pdserving False、use_tensorrt False等开关参数。值得注意的是各服务包之间存在参数复用关系例如 kie_ser/params.py 直接from deploy.hubserving.ocr_system.params import read_params as pp_ocr_read_params继承 OCR 全套参数再叠加 SER 特有的ser_model_dir、ser_dict_path、vis_font_path、ocr_order_method等 KIE 参数。5.2 配置合并机制进阶原理从 module.py 的merge_configs可以看到服务的配置合并机制代码先备份并清空sys.argv调用parse_args()获取工具默认参数再用vars(read_params())中params.py定义的参数逐项覆盖cfg.__setattr__(key, update_cfg_map[key])最后恢复sys.argv。这意味着params.py中定义的参数拥有最高优先级会覆盖tools/infer/utility.py中的命令行默认值——理解了这一机制你在自定义服务时就清楚改哪个文件、生效优先级如何。6. 快速自测与常见排查建议模型路径报错启动服务报找不到模型时优先检查params.py中det_model_dir、rec_model_dir、cls_model_dir是否指向真实存在的推理模型目录且目录名与params.py中的配置完全一致。GPU 启动失败use_gpu: true时必须在启动前export CUDA_VISIBLE_DEVICES卡号且不能与use_multiprocess: true同时开启见 module.py 中对该环境变量的强制校验逻辑。识别结果异常若换用非 PP-OCRv3 识别模型需同步调整rec_image_shape若字典与模型不匹配检查rec_char_dict_path指向的字典文件默认ppocr/utils/ppocr_keys_v1.txt。端口占用不同服务模块共用一个端口时会冲突建议按第 3 节给出的端口规划为每个服务分配独立端口。联调验证修改代码后先python deploy/hubserving/ocr_system/module.py直接跑通本地预测再走hub serving stop → hub install → hub serving start完整流程可显著减少线上排障成本。测试图片也可使用仓库tests/test_files目录下自带的样例图片。7. 总结基于 PaddleHub Serving 的部署方式让 PaddleOCR 从「命令行推理工具」升级为「标准 HTTP 服务」九种服务包覆盖检测、分类、识别、表格、版面、PP-Structure 与关键信息抽取全场景module.py params.py config.json的三文件结构使服务逻辑与配置解耦既能命令行一键启动也能通过配置文件灵活切换 CPU/GPU 与并发策略tools/test_hubserving.py给出了开箱即用的客户端示例返回字段矩阵清晰定义了各模块的输出契约。配合本文第 5 节的改造流程与params.py参数解析你可以按业务需求自由替换模型、调整前后处理参数、增删返回字段快速搭建起属于自己的 OCR 服务化平台。【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考