This page documents how to deploy PaddleOCR models as HTTP prediction services using PaddleHub Serving. It covers the available service modules, their file structure, startup methods, request format, response format, and how to customize a module.
This page covers the legacy deploy/hubserving serving path. For high-performance inference without a service layer, see High-Performance Inference. For C++ deployment, see C++ Inference and Build System. For mobile/edge deployment, see Mobile and Edge Deployment.
PaddleOCR provides a service deployment framework under deploy/hubserving/. Each subdirectory in that path is a self-contained PaddleHub module that wraps one or more inference components and exposes them as an HTTP endpoint.
All modules share the same pattern:
The codebase also references a second deployment option (PaddleServing / deploy/pdserving), but that path is not covered in this page.
Nine service packages are available under deploy/hubserving/:
| Directory | Module Name | Description |
|---|---|---|
ocr_det | ocr_det | Text detection only |
ocr_cls | ocr_cls | Text angle classification only |
ocr_rec | ocr_rec | Text recognition only |
ocr_system | ocr_system | Detection + classification + recognition (3-stage pipeline) |
structure_table | structure_table | Table recognition (HTML output) |
structure_system | structure_system | Full PP-Structure (layout + table + OCR) |
structure_layout | structure_layout | Layout analysis only |
kie_ser | kie_ser | Key Information Extraction (SER) |
kie_ser_re | kie_ser_re | Key Information Extraction (SER + RE) |
Sources: deploy/hubserving/readme_en.md22-34
Each service package contains four files:
deploy/hubserving/<module_name>/
├── __init__.py # Empty, required by PaddleHub
├── config.json # Optional: used to start service with GPU or custom settings
├── module.py # Main module: inference logic, HTTP handler
└── params.py # Model paths and preprocessing parameters
Sources: deploy/hubserving/readme_en.md36-43
params.pyEach module's params.py exposes a single read_params() function returning a Config object with model paths and runtime parameters.
Example from ocr_system:
| Parameter | Default Value |
|---|---|
det_model_dir | ./inference/PP-OCRv3_mobile_det_infer/ |
rec_model_dir | ./inference/ch_PP-OCRv3_rec_infer/ |
cls_model_dir | ./inference/ch_ppocr_mobile_v2.0_cls_infer/ |
rec_image_shape | "3, 48, 320" |
use_angle_cls | True |
drop_score | 0.5 |
use_tensorrt | False |
Sources: deploy/hubserving/ocr_system/params.py24-73
For structural modules, params are layered via inheritance: structure_system/params.py calls table_read_params(), which in turn calls pp_ocr_read_params().
Sources: deploy/hubserving/structure_system/params.py19-33 deploy/hubserving/structure_table/params.py19-30
module.pyEach module.py defines a class decorated with @moduleinfo that extends hub.Module. The three key methods are:
| Method | Purpose |
|---|---|
_initialize(use_gpu, enable_mkldnn) | Creates the inference engine instance |
predict(images, paths) | Runs inference and formats output |
serving_method(images, **kwargs) | HTTP entry point (decorated with @serving), decodes base64 images and calls predict |
The merge_configs() helper in each module merges PaddleHub defaults with the values from params.py.
Sources: deploy/hubserving/ocr_system/module.py47-155
PaddleHub Serving Module Architecture
Sources: deploy/hubserving/ocr_system/module.py47-155 deploy/hubserving/ocr_det/module.py46-155 deploy/hubserving/ocr_rec/module.py44-160 deploy/hubserving/structure_table/module.py48-148
Module class to inference engine binding
Sources: deploy/hubserving/ocr_det/module.py68 deploy/hubserving/ocr_cls/module.py66 deploy/hubserving/ocr_rec/module.py66 deploy/hubserving/ocr_system/module.py69 deploy/hubserving/structure_table/module.py69 deploy/hubserving/structure_system/module.py70
Before installing any module, download inference models and place them at the expected paths:
| Model | Default Path |
|---|---|
| Text detection | ./inference/PP-OCRv3_mobile_det_infer/ |
| Text recognition | ./inference/ch_PP-OCRv3_rec_infer/ |
| Text angle classifier | ./inference/ch_ppocr_mobile_v2.0_cls_infer/ |
| Layout parse model | ./inference/picodet_lcnet_x1_0_fgd_layout_infer/ |
| Table recognition | ./inference/ch_ppstructure_mobile_v2.0_SLANet_infer/ |
| KIE SER model | ./inference/ser_vi_layoutxlm_xfund_infer/ |
| KIE RE model | ./inference/re_vi_layoutxlm_xfund_infer/ |
Model paths are defined in each module's params.py and can be changed there directly.
Sources: deploy/hubserving/readme_en.md59-70
Run from the repository root. Replace the path with the desired module:
| Module | Install command |
|---|---|
| Detection | hub install deploy/hubserving/ocr_det |
| Classification | hub install deploy/hubserving/ocr_cls |
| Recognition | hub install deploy/hubserving/ocr_rec |
| Detection + Cls + Rec | hub install deploy/hubserving/ocr_system |
| Table recognition | hub install deploy/hubserving/structure_table |
| PP-Structure | hub install deploy/hubserving/structure_system |
| Layout analysis | hub install deploy/hubserving/structure_layout |
| KIE (SER) | hub install deploy/hubserving/kie_ser |
| KIE (SER+RE) | hub install deploy/hubserving/kie_ser_re |
Option A: Command line (CPU only)
CLI parameters:
| Parameter | Description |
|---|---|
--modules / -m | Module name(s) and optional version (e.g., ocr_system==1.0.0) |
--port / -p | Port number (default: 8866) |
--use_multiprocess | Enable multi-process mode (not supported on Windows) |
--workers | Number of worker processes (default: 2 * cpu_count - 1) |
Option B: Config file (CPU or GPU)
The config.json format (deploy/hubserving/ocr_system/config.json1-15):
init_args maps to parameters of _initialize() in module.pypredict_args maps to parameters of predict() in module.pyFor GPU serving, set CUDA_VISIBLE_DEVICES before starting:
Note:
use_gpuanduse_multiprocesscannot both betrue.
Sources: deploy/hubserving/readme_en.md88-153 deploy/hubserving/ocr_system/config.json1-15 deploy/hubserving/ocr_det/config.json1-15
| Module | Default Port |
|---|---|
ocr_det | 8865 |
ocr_cls | 8866 |
ocr_rec | 8867 |
ocr_system | 8868 |
structure_table | 8869 |
structure_system | 8870 |
structure_layout | 8870 |
kie_ser | 8871 |
kie_ser_re | 8872 |
These are the ports from the example configurations and are fully configurable.
Sources: deploy/hubserving/readme_en.md170-179
Use tools/test_hubserving.py to test a running service:
| Parameter | Description |
|---|---|
--server_url | Full URL: http://[ip]:[port]/predict/[module_name] |
--image_dir | Path to a single image or a directory of images |
--visualize | Whether to save visualized results (True/False, default False) |
--output | Output directory for visualized results (default: ./hubserving_result) |
The script reads each image, encodes it as base64, POSTs JSON to the server, and logs the response. Visualization logic is handled by draw_server_result() in tools/test_hubserving.py43-72
Sources: tools/test_hubserving.py100-162
Images are encoded with base64.b64encode(image_bytes).decode('utf8'). On the server side, base64_to_cv2() (from tools/infer/utility) decodes them back to numpy arrays.
The response is a list of dicts. The fields returned depend on the module:
| Field | Type | Description | Modules |
|---|---|---|---|
angle | str | Text angle (0 or 180) | ocr_cls, ocr_system |
text | str | Recognized text content | ocr_rec, ocr_system, structure_system, kie_ser, kie_re |
confidence | float | Confidence score | ocr_cls, ocr_rec, ocr_system, structure_system, kie_ser, kie_re |
text_region | list | Bounding box coordinates (list of [x,y] points) | ocr_det, ocr_system, structure_system, kie_ser, kie_re |
html | str | Table as HTML string | structure_table, structure_system |
regions | list | Layout+table+OCR combined result with bbox, type, res | structure_table, structure_system |
layout | list | Layout boxes with bbox and label | structure_layout |
ser_res | varied | SER result | kie_ser |
re_res | varied | RE result | kie_re |
Sources: deploy/hubserving/readme_en.md190-216
To modify inference logic, model paths, or response fields:
Stop the running service:
Edit the module files in deploy/hubserving/<module_name>/:
det_model_dir, rec_model_dir, etc. in params.pyuse_angle_cls = False in params.pypredict() method in module.pyrec_image_shape = "3, 48, 320" is set in params.pyOptionally rename the module by updating:
from deploy.hubserving.ocr_system.params import read_params)name= field in the @moduleinfo decorator at deploy/hubserving/ocr_system/module.py40Clear CPython cache (if needed):
Reinstall the module:
Restart the service:
Tip: Run
module.pydirectly (python deploy/hubserving/ocr_system/module.py) to verify inference is correct before restarting the service.
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.