PaddleOCR HubServing Docker 部署指南：把 OCR 服务快速打包成可调用的 Restful API
【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR
本篇技术指南围绕 PaddleOCR 仓库中 Docker 化部署文档 展开，讲解如何利用 Docker 将 PaddleOCR 的ocr_system模块打包为镜像，并在 CPU/GPU 环境下以 HubServing 模式启动、测试一个标准的 OCR Restful API 服务。读完本文，你可以独立完成镜像制作、容器启动、端口验证，以及通过 curl 发送 Base64 图片请求并解析结构化识别结果，同时理解服务背后的模块代码与关键可调参数。
一、部署方案总览：HubServing 模式是如何工作的
该方案的目标是：通过 Docker 技术，把 PaddleOCR 服务打包成镜像，以便在 Docker 或 K8s 环境中快速发布上线。文档中说明，当前实现的是基于 HubServing 模式的部署（作者同时计划后续增加 PaddleServing 模式的部署）。
从源码结构看，整个服务由三部分组成：
- PaddleHub 服务模块：deploy/hubserving/ocr_system/module.py 定义了名为
ocr_system的 PaddleHub 模块（@moduleinfo(name="ocr_system", version="1.0.0")）。其核心逻辑是：serving_method是对外暴露的 serving 入口（@serving装饰器），先把请求中的 Base64 字符串通过base64_to_cv2解码为图像数组，再调用predict；predict逐张调用TextSystem（来自 tools/infer/predict_system.py），即完整的"检测 + 方向分类 + 识别"OCR 流水线，输出text、confidence、text_region（四点多边形坐标）三类字段；_initialize在启用 GPU 时会强制检查环境变量CUDA_VISIBLE_DEVICES，未正确设置会抛出RuntimeError，并把显存上限cfg.gpu_mem设为 8000 MB。
- 运行参数配置：deploy/hubserving/ocr_system/params.py 中的
read_params()定义了全部推理参数（详见第六节），merge_configs会在启动时用这些值覆盖默认配置。 - 服务清单：deploy/hubserving/ocr_system/config.json 指定服务端口
"port": 8868、工作进程数"workers": 2，并在init_args中声明"use_gpu": true（GPU 镜像中生效；CPU 场景需要容器内无可用 GPU 或相应调整）。
Dockerfile 的CMD正是把这三者串起来的一条命令：
hub install deploy/hubserving/ocr_system/ && hub serving start -m ocr_system二、实施前提准备
按照文档要求，开始之前需要先安装以下基本组件：
| 组件 | 说明 |
|---|---|
| Docker 环境 | 必需，用于构建与运行镜像 |
| 显卡驱动 + CUDA 10.0+ | 仅 GPU 版本需要 |
| NVIDIA Container Toolkit | GPU 版本需要；Docker 19.03 以上版本可跳过此步 |
| cuDNN 7.6+ | 仅 GPU 版本需要 |
从 GPU 版 Dockerfile 的基础镜像registry.baidubce.com/paddlepaddle/paddle:2.0.0-gpu-cuda10.1-cudnn7也可以印证：官方 GPU 镜像按 CUDA 10.1 + cuDNN 7 环境制作，与上述前提一致。
三、制作镜像
仓库为 CPU 和 GPU 分别提供了 Dockerfile，位于 deploy/docker/hubserving/cpu/Dockerfile 与 deploy/docker/hubserving/gpu/Dockerfile，两者结构相同，区别仅在基础镜像：
- CPU：
FROM registry.baidubce.com/paddlepaddle/paddle:2.0.0 - GPU：
FROM registry.baidubce.com/paddlepaddle/paddle:2.0.0-gpu-cuda10.1-cudnn7
Dockerfile 的构建步骤可以拆分为四段：
- 安装依赖（基于 Python 3.7）：升级 pip、安装
paddlehub； - 拉取代码：
git clone https://github.com/PaddlePaddle/PaddleOCR.git /PaddleOCR，然后安装仓库requirements.txt中的依赖； - 下载推理模型：为文本检测、方向分类、文本识别三个模型分别执行
ADD {link}+tar xf解压到/PaddleOCR/inference/。注意 Dockerfile 中的{link}与{file}是模板占位符，构建前需要替换为实际的模型下载地址与文件名。Dockerfile 中的注释明确说明：默认使用轻量版（mobile）模型，如需换成高精度（server）版本，例如把检测模型从ch_ppocr_mobile_v2.0_det_infer改为ch_ppocr_server_v2.0_det_infer，同时记得同步修改 params.py 中对应的det_model_dir字段，否则会出现模型目录不一致的问题； - 暴露端口与启动命令：
EXPOSE 8868，并以hub install ... && hub serving start -m ocr_system作为容器启动命令。
制作镜像的具体操作（文档以 CPU 为例，GPU 版本替换关键字即可）：
# a. 切换至 Dockerfile 目录（需区分 cpu 或 gpu 版本） cd deploy/docker/hubserving/cpu # b. 生成镜像 docker build -t paddleocr:cpu .四、启动 Docker 容器
启动方式按 CPU/GPU 与 Docker 版本区分，共三种命令：
CPU 版本
sudo docker run -dp 8868:8868 --name paddle_ocr paddleocr:cpuGPU 版本（基于 NVIDIA Container Toolkit）
sudo nvidia-docker run -dp 8868:8868 --name paddle_ocr paddleocr:gpuGPU 版本（Docker 19.03 及以上，可直接使用--gpus参数）
sudo docker run -dp 8868:8868 --gpus all --name paddle_ocr paddleocr:gpu说明：中文文档中该条命令写为
-dp 8868:8869，与英文版 README.md 的8868:8868不一致，属于文档笔误。容器内服务监听的是 8868 端口（见 config.json 的"port": 8868与 Dockerfile 的EXPOSE 8868），宿主机端口映射应保持两端一致。
检查服务运行情况：执行
docker logs -f paddle_ocr当日志中出现Successfully installed ocr_system和Running on http://0.0.0.0:8868等信息时，表示服务启动成功。
五、测试服务：从 Base64 编码到返回结果解析
服务就绪后，测试分为三步：
a. 计算待识别图片的 Base64 编码。可借助任意 Base64 图片编码工具（在线工具或本地脚本均可）。
b. 发送服务请求。仓库提供了完整的示例请求文件 deploy/docker/hubserving/sample_request.txt，其中包含一张真实图片的 Base64 编码与可直接执行的 curl 命令。请求的基本格式为：
curl -H "Content-Type:application/json" -X POST --data "{\"images\": [\"填入图片Base64编码(需要删除'data:image/jpg;base64,'前缀)\"]}" http://localhost:8868/predict/ocr_system两个要点：
- 请求体是 JSON，字段名为
images，值为 Base64 字符串数组（支持一次传多张图）；如果 Base64 带有data:image/jpg;base64,前缀，需要先删除，因为模块侧的base64_to_cv2（tools/infer/utility.py）只做纯 Base64 解码； - 接口路径为
/predict/ocr_system，即 HubServing 的predict路由加上模块名。注意sample_request.txt末尾示例写的是localhost:8866，实际服务端口应以 8868 为准（同样以 config.json 与启动日志为准）。
c. 解析返回结果。调用成功时返回如下结构：
{"msg":"","results":[[{"confidence":0.8403433561325073,"text":"约定","text_region":[[345,377],[641,390],[634,540],[339,528]]},{"confidence":0.8131805658340454,"text":"最终相遇","text_region":[[356,532],[624,530],[624,596],[356,598]]}]],"status":"0"}字段含义与 module.py 中predict的组装逻辑一一对应：
| 字段 | 含义 | 来源 |
|---|---|---|
msg | 错误信息，正常时为空字符串 | HubServing 框架 |
status | 状态码，"0"表示成功 | HubServing 框架 |
results | 二维数组，外层对应请求中的每张图片，内层对应该图识别出的每条文本 | predict按图片循环追加 |
results[i][j].text | 识别出的文本 | rec_res |
results[i][j].confidence | 该条文本的置信度（浮点数） | float(score) |
results[i][j].text_region | 文本区域的四个顶点坐标[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]，即旋转矩形多边形 | dt_boxes[dno].astype(np.int32).tolist() |
六、参数深度解析：params.py 决定了服务识别能力
hub serving start启动时，module.py 的merge_configs会用 params.py 中read_params()的返回值逐项覆盖parse_args的默认配置。这些参数直接决定了服务的模型选择与识别行为：
文本检测（DB 算法）
cfg.det_algorithm = "DB" cfg.det_model_dir = "./inference/PP-OCRv3_mobile_det_infer/" cfg.det_limit_side_len = 960 # 缩放后最长边限制 cfg.det_limit_type = "max" # 按最长边缩放 cfg.det_db_thresh = 0.3 # 概率图二值化阈值 cfg.det_db_box_thresh = 0.5 # 多边形框得分阈值，低于此值的框被丢弃 cfg.det_db_unclip_ratio = 1.6 # 多边形外扩比例 cfg.use_dilation = False cfg.det_db_score_mode = "fast"文本识别（CRNN）
cfg.rec_algorithm = "CRNN" cfg.rec_model_dir = "./inference/ch_PP-OCRv3_rec_infer/" cfg.rec_image_shape = "3, 48, 320" # 识别输入形状 cfg.rec_batch_num = 6 # 识别批大小 cfg.max_text_length = 25 cfg.rec_char_dict_path = "./ppocr/utils/ppocr_keys_v1.txt" # 字符字典 cfg.use_space_char = True方向分类器
cfg.use_angle_cls = True # 启用 180° 方向分类 cfg.cls_model_dir = "./inference/ch_ppocr_mobile_v2.0_cls_infer/" cfg.cls_image_shape = "3, 48, 192" cfg.label_list = ["0", "180"] cfg.cls_batch_num = 30 cfg.cls_thresh = 0.9其他开关
cfg.use_pdserving = False # 是否使用 PaddleServing 推理后端 cfg.use_tensorrt = False # 是否启用 TensorRT 加速 cfg.drop_score = 0.5 # 结果过滤阈值，置信度低于该值的文本框将被丢弃调优要点（均可直接修改 params.py 后重新构建镜像）：
- 模型精度与速度取舍：
det_model_dir/rec_model_dir/cls_model_dir决定使用哪个推理模型。Dockerfile 注释给出了 mobile 与 server 版本互换的操作方法，并强调必须同步修改 params.py 中的目录字段； - 检测召回：
det_db_box_thresh降低可增加召回但可能引入误检，det_db_thresh、det_db_unclip_ratio影响多边形连通区域与外扩范围； - 结果噪声控制：
drop_score是最终结果的置信度过滤线； - 模型下载 URL：params.py 末尾还保留了
det_model_url/rec_model_url/cls_model_url三个 HTTPS 模型地址，可配合 Dockerfile 的ADD {link}占位符完成模型下载。
七、注意事项与适用前提
- 版本前提：Dockerfile 标注
Version: 2.0.0，基础镜像为 PaddlePaddle 2.0.0 系列，环境基于 Python 3.7，服务模块绑定的是 v2.x 推理链路（TextSystem、PP-OCRv3/v2.0 推理模型）。该部署方案适用于 v2.x 系列的模型与推理格式，不能直接等同于仓库当前 3.x 新 API 的运行环境，使用前提以文档和 Dockerfile 实际内容为准； - GPU 环境要求：若镜像以
use_gpu: true初始化（见 config.json），_initialize会检查CUDA_VISIBLE_DEVICES环境变量，未设置或格式不正确将直接报RuntimeError。GPU 容器需通过nvidia-docker或 Docker 19.03+ 的--gpus all方式启动，使该环境变量正确注入； - 端口一致性：镜像内固定监听 8868（
EXPOSE 8868+"port": 8868）。docker run的端口映射、curl 请求地址三者需保持一致；中文文档8868:8869与示例请求文件中的8866均应按 8868 修正理解； - 模型占位符：Dockerfile 中的
ADD {link}与tar xf ... {file}为模板形式，执行docker build前必须替换为真实可下载的模型链接与文件名，否则构建会失败； - 部署模式范围：当前 Docker 方案仅覆盖 HubServing 模式，PaddleServing 模式部署在文档中属于后续计划。
综合来看，这套"文档 + Dockerfile + 服务模块"的组合，为 PaddleOCR v2.x 提供了一条从源码到 Restful API 的标准路径：改params.py控制行为、换 Dockerfile 占位符控制模型、docker build/run/logs三步完成发布与验证。
【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
