PaddleOCR安装部署及模型微调

1. 安装PaddlePaddle

请参考下述命令，使用飞桨框架官方 Docker 镜像，创建一个名为 paddle 的容器，并将当前工作目录映射到容器内的 /paddle 目录：

（1）拉取预安装 PaddlePaddle 的镜像：

docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddle:3.1.0-gpu-cuda11.8-cudnn8.9

（2）用镜像构建并进入Docker容器：

docker run --gpus all --shm-size=8g --network=host --name paddle -it -v $PWD:/paddle ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddle:3.1.0-gpu-cuda11.8-cudnn8.9 /bin/bash

或先创建一个后台容器，再进入该容器：

docker run -id --gpus all --shm-size=8g --network=host --name paddle -v $PWD:/paddle ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddle:3.1.0-gpu-cuda11.8-cudnn8.9

docker exec -it paddle /bin/bash

若您在安装后发现无法安装PyYAML,可通过如下命令修复：

python -m pip install --ignore-installed PyYAML

安装完成后，使用以下命令可以验证 PaddlePaddle 是否安装成功：

python -c "import paddle; print(paddle.__version__)"

如果已安装成功，将输出以下内容：

3.1.0

2. 安装paddleocr

首先，需要确保环境中安装有符合要求的 CUDA 与 cuDNN。目前 PaddleOCR 仅支持与 CUDA 11.8 + cuDNN 8.9 兼容的 CUDA 和 cuDNN版本。如果使用飞桨官方镜像，则镜像中的 CUDA 和 cuDNN 版本已经是满足要求的，无需额外安装。

建议安装的 CUDA 和 cuDNN 版本与环境中存在的 Python 包版本保持一致，以避免不同版本的库共存导致的潜在问题。可以通过如下方式可以查看 CUDA 和 cuDNN 相关 Python 包的版本：

# CUDA 相关 Python 包版本
pip list | grep nvidia-cuda
# cuDNN 相关 Python 包版本
pip list | grep nvidia-cudnn

如果只希望使用 PaddleOCR 的推理功能，请参考 安装推理包；如果还希望进行模型训练、导出等，请参考 安装训练依赖。在同一环境中安装推理包和训练依赖是允许的，无需进行环境隔离。

2.1 安装推理包

从 PyPI 安装最新版本 PaddleOCR 推理包：

python -m pip install paddleocr

或者从源码安装（默认为开发分支）：

python -m pip install "git+https://github.com/PaddlePaddle/PaddleOCR.git"

2.2 安装训练依赖

要进行模型训练、导出等，需要首先将仓库克隆到本地：

# 推荐方式
git clone https://github.com/PaddlePaddle/PaddleOCR

# （可选）切换到指定分支
git checkout release/3.0

# 如果因为网络问题无法克隆成功，也可选择使用码云上的仓库：
git clone https://gitee.com/paddlepaddle/PaddleOCR

# 注：码云托管代码可能无法实时同步本 GitHub 项目更新，存在3~5天延时，请优先使用推荐方式。

执行如下命令安装依赖：

python -m pip install -r requirements.txt

3. 开发集成/部署

如果通用 OCR 产线可以达到您对产线推理速度和精度的要求，您可以直接进行开发集成/部署。

您可以将通用 OCR 产线直接应用在您的Python项目中，此外，PaddleOCR 也提供了其他两种部署方式，详细说明如下：

（1）高性能推理：在实际生产环境中，许多应用对部署策略的性能指标（尤其是响应速度）有着较严苛的标准，以确保系统的高效运行与用户体验的流畅性。为此，PaddleOCR 提供高性能推理功能，旨在对模型推理及前后处理进行深度性能优化，实现端到端流程的显著提速，详细的高性能推理流程请参考高性能推理。

（2）服务化部署：服务化部署是实际生产环境中常见的一种部署形式。通过将推理功能封装为服务，客户端可以通过网络请求来访问这些服务，以获取推理结果。详细的产线服务化部署流程请参考服务化部署。

3.1 高性能推理

在实际生产环境中，许多应用对部署策略的性能指标（尤其是响应速度）有着较严苛的标准，以确保系统的高效运行与用户体验的流畅性。PaddleOCR 提供高性能推理能力，让用户无需关注复杂的配置和底层细节，一键提升模型的推理速度。具体而言，PaddleOCR 的高性能推理功能能够：

结合先验知识自动选择合适的推理后端（Paddle Inference、OpenVINO、ONNX Runtime、TensorRT等），并配置加速策略（如增大推理线程数、设置 FP16 精度推理）；
根据需要自动将飞桨静态图模型转换为 ONNX 格式，以使用更优的推理后端实现加速。

3.1.1 安装Paddle2ONNX插件

PaddleX 的 Paddle2ONNX 插件提供了将飞桨静态图模型转化到 ONNX 格式模型的能力，底层使用 Paddle2ONNX。

paddlex --install paddle2onnx

3.1.2 安装高性能推理依赖

高性能推理插件支持处理 飞桨静态图（.pdmodel、 .json）、ONNX（.onnx）、华为 OM（.om） 等多种模型格式。对于 ONNX 模型，可以使用 Paddle2ONNX 插件转换得到。如果模型目录中存在多种格式的模型，PaddleX 会根据需要自动选择，并可能进行自动模型转换。

通过 PaddleOCR CLI 安装高性能推理所需依赖：

paddleocr install_hpi_deps {设备类型}

支持的设备类型包括：

cpu：仅使用 CPU 推理。目前支持 Linux 系统、x86-64 架构处理器、Python 3.8-3.12。
gpu：使用 CPU 或 NVIDIA GPU 推理。目前支持 Linux 系统、x86-64 架构处理器、Python 3.8-3.12。如果希望使用完整的高性能推理功能，还需要确保环境中安装有符合要求的 TensorRT。

同一环境中只应该存在一种设备类型的依赖。对于 Windows 系统，目前建议在 Docker 容器或者 WSL 环境中安装。

推荐使用飞桨官方 Docker 镜像安装高性能推理依赖。 各设备类型对应的镜像如下：

cpu：ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddle:3.0.0
gpu：
- CUDA 11.8：ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddle:3.0.0-gpu-cuda11.8-cudnn8.9-trt8.6

应确保环境中安装有符合要求的 TensorRT，否则 Paddle Inference TensorRT 子图引擎将不可用，程序可能无法取得最佳推理性能。目前 PaddleOCR 仅支持 TensorRT 8.6.1.6，请参考 TensorRT 文档安装 TensorRT。示例如下：

# 下载 TensorRT tar 文件
wget https://developer.nvidia.com/downloads/compute/machine-learning/tensorrt/secure/8.6.1/tars/TensorRT-8.6.1.6.Linux.x86_64-gnu.cuda-11.8.tar.gz
# 解压 TensorRT tar 文件
tar xvf TensorRT-8.6.1.6.Linux.x86_64-gnu.cuda-11.8.tar.gz
# 安装 TensorRT wheel 包
python -m pip install TensorRT-8.6.1.6/python/tensorrt-8.6.1-cp310-none-linux_x86_64.whl
# 添加 TensorRT 的 `lib` 目录的绝对路径到 LD_LIBRARY_PATH 中
vim ~/.bashrc
# 编辑.bashrc配置文件，添加以下内容：
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/paddle/TensorRT-8.6.1.6/lib"
# 保存文件后，运行以下命令使配置生效：
source ~/.bashrc

3.1.2 执行高性能推理

对于 PaddleOCR CLI，指定 --enable_hpi 为 True 即可执行高性能推理。例如：

paddleocr ocr --enable_hpi True ...

对于 PaddleOCR Python API，在初始化产线对象或者模块对象时，设置 enable_hpi 为 True 即可在调用推理方法时执行高性能推理。例如：

from paddleocr import PaddleOCR
pipeline = PaddleOCR(enable_hpi=True)
result = pipeline.predict(...)

对于 PaddleX CLI，指定--use_hpip开启高性能推理。例如：

paddlex --serve --pipeline OCR --use_hpip --port 8081

或

paddlex --serve --pipeline /paddle/PaddleOCR.yaml --use_hpip --port 8081

3.1.3 相关说明

对于部分模型，在首次执行高性能推理时，可能需要花费较长时间完成推理引擎的构建。推理引擎相关信息将在第一次构建完成后被缓存在模型目录，后续可复用缓存中的内容以提升初始化速度。
目前，由于使用的不是静态图格式模型、存在不支持算子等原因，部分模型可能无法获得推理加速。
在进行高性能推理时，PaddleOCR 会自动处理模型格式的转换，并尽可能选择最优的推理后端。同时，PaddleOCR 也支持用户指定 ONNX 模型。有关如何飞桨静态图模型转换为 ONNX 格式，可参考获取 ONNX 模型。
PaddleOCR 的高性能推理能力依托于 PaddleX 及其高性能推理插件。通过传入自定义 PaddleX 产线配置文件，可以对推理后端等进行配置。请参考使用 PaddleX 产线配置文件和 PaddleX 高性能推理指南了解如何调整高性能推理配置。

3.2 服务化部署

3.2.1 安装依赖

执行如下命令，通过 PaddleX CLI 安装 PaddleX 服务化部署插件：

paddlex --install serving

3.2.2 运行服务器

通过 PaddleX CLI 运行服务器：

paddlex --serve --pipeline {PaddleX 产线注册名或产线配置文件路径} [{其他命令行选项}]

以通用 OCR 产线为例：

paddlex --serve --pipeline OCR

可以看到类似以下展示的信息：

INFO:     Started server process [63108]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

如需调整配置（如模型路径、batch size、部署设备等），可指定 --pipeline 为自定义配置文件。请参考 PaddleOCR 与 PaddleX 了解 PaddleOCR 产线与 PaddleX 产线注册名的对应关系，以及 PaddleX 产线配置文件的获取与修改方式。

与服务化部署相关的命令行选项如下：

名称	说明
`--pipeline`	PaddleX 产线注册名或产线配置文件路径。
`--device`	产线部署设备。默认情况下，当 GPU 可用时，将使用 GPU；否则使用 CPU。
`--host`	服务器绑定的主机名或 IP 地址。默认为 `0.0.0.0`。
`--port`	服务器监听的端口号。默认为 `8080`。
`--use_hpip`	如果指定，则使用高性能推理。请参考高性能推理文档了解更多信息。
`--hpi_config`	高性能推理配置。请参考高性能推理文档了解更多信息。

3.2.3 调用服务

PaddleOCR 产线使用教程中的 “开发集成/部署”部分提供了服务的 API 参考与多语言调用示例。

4. 二次开发

如果通用OCR 产线提供的默认模型权重在您的场景中，精度或速度不满意，您可以尝试利用您自己拥有的特定领域或应用场景的数据对现有模型进行进一步的微调，以提升通用OCR 产线的在您的场景中的识别效果。

4.1 模型微调

通用 OCR 产线包含若干模块，模型产线的效果如果不及预期，可能来自于其中任何一个模块。您可以对识别效果差的图片进行分析，进而确定是哪个模块存在问题，并参考以下表格中对应的微调教程链接进行模型微调。

情形	微调模块	微调参考链接
整图旋转矫正不准	文档图像方向分类模块	链接
图像扭曲矫正不准	文本图像矫正模块	暂不支持微调
文本行旋转矫正不准	文本行方向分类模块	链接
文本漏检	文本检测模块	链接
文本内容不准	文本识别模块	链接

4.1.1 文本检测模型微调

如果文本检测模型在您的场景上效果仍然不理想，您可以尝试以下步骤进行模型微调。

首先，您需要准备文本检测的数据集，可采用PPOCRLabel标注工具，并参考文本检测 Demo 数据的格式准备，准备好后，即可按照以下步骤进行模型训练和导出，导出后，可以将模型快速集成到上述 API 中。此处以文本检测 Demo 数据为例，在训练模型之前，请确保已经按照安装文档安装了 PaddleOCR 所需要的依赖。

（1）准备数据集

# 下载示例数据集
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/ocr_det_dataset_examples.tar
tar -xf ocr_det_dataset_examples.tar

（2）下载预训练模型

# 下载 PP-OCRv5_server_det 预训练模型
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/PP-OCRv5_server_det_pretrained.pdparams

（3）修改PP-OCRv5_server_det 配置文件，进行模型训练

PaddleOCR 对代码进行了模块化，训练 PP-OCRv5_server_det 检测模型时需要使用 PP-OCRv5_server_det 的配置文件，配置文件的位置：PaddleOCR/configs/det/PP-OCRv5/PP-OCRv5_server_det.yml，打开PP-OCRv5_server_det.yml文件，修改以下内容：

Global:
  ...
  save_model_dir: ./output/PP-OCRv5_server_det #训练后的模型权重存储路径
  ...
  pretrained_model: /official_pretrained_model/PP-OCRv5_server_det_pretrained.pdparams #预训练模型路径
  ...
...
Train:
  dataset:
    ...
    data_dir: /paddle/ocr_det_dataset_examples/ #数据集根目录
    label_file_list:
      - /paddle/ocr_det_dataset_examples/train.txt #训练集标注文件
    ...
...
Eval:
  dataset:
    ...
    data_dir: /paddle/ocr_det_dataset_examples/ #数据集根目录
    label_file_list:
      - /paddle/ocr_det_dataset_examples/val.txt #验证集标注文件
    ...
...

执行以下命令进行模型训练：

#单卡训练
python PaddleOCR/tools/train.py -c PaddleOCR/configs/det/PP-OCRv5/PP-OCRv5_server_det.yml

#多卡训练，通过--gpus参数指定卡号
python -m paddle.distributed.launch --gpus '0,1,2,3' PaddleOCR/tools/train.py -c PaddleOCR/configs/det/PP-OCRv5/PP-OCRv5_server_det.yml

模型训练完成后，训练好的模型权重会保存在./output/PP-OCRv5_server_det目录下。

（4）模型评估

打开PP-OCRv5_server_det.yml文件，将pretrained_model的路径设置为本地路径。若使用自行训练保存的模型，请注意修改路径和文件名为{path/to/weights}/{model_name}。

Global:
  ...
  pretrained_model: ./output/PP-OCRv5_server_det/best_accuracy.pdparams #训练好的模型路径
  ...
...

执行以下命令进行模型评估：

python PaddleOCR/tools/eval.py -c PaddleOCR/configs/det/PP-OCRv5/PP-OCRv5_server_det.yml

（5）模型导出

打开PP-OCRv5_server_det.yml文件，修改以下内容：

Global:
  ...
  save_inference_dir: ./PP-OCRv5_server_det_infer/ #模型导出的存储目录
  ...
...

执行以下命令导出模型：

python PaddleOCR/tools/export_model.py -c PaddleOCR/configs/det/PP-OCRv5/PP-OCRv5_server_det.yml

导出模型后，静态图模型会存放于当前目录的./PP-OCRv5_server_det_infer/中，在该目录下，您将看到如下文件：

./PP-OCRv5_server_det_infer/
├── inference.json
├── inference.pdiparams
├── inference.yml

至此，文本检测模型微调完成，该静态图模型可以直接集成到 PaddleOCR 的 API 中。

4.1.2 文本识别模型微调

如果文本识别模型在您的场景上效果仍然不理想，您可以尝试以下步骤进行模型微调。

首先，您需要准备文本识别的数据集，可采用PPOCRLabel标注工具，并参考文本识别 Demo 数据的格式准备，准备好后，即可按照以下步骤进行模型训练和导出，导出后，可以将模型快速集成到上述 API 中。此处以文本识别 Demo 数据为例，在训练模型之前，请确保已经按照安装文档安装了 PaddleOCR 所需要的依赖。

（1）准备数据集

# 下载示例数据集
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/ocr_rec_dataset_examples.tar
tar -xf ocr_rec_dataset_examples.tar

（2）下载预训练模型

# 下载 PP-OCRv5_server_rec 预训练模型
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/PP-OCRv5_server_rec_pretrained.pdparams

（3）修改PP-OCRv5_server_rec 配置文件，进行模型训练

PaddleOCR 对代码进行了模块化，训练 PP-OCRv5_server_rec 识别模型时需要使用 PP-OCRv5_server_rec 的配置文件，配置文件的位置：PaddleOCR/configs/rec/PP-OCRv5/PP-OCRv5_server_rec.yml，打开PP-OCRv5_server_rec.yml文件，修改以下内容：

Global:
  ...
  save_model_dir: ./output/PP-OCRv5_server_rec #训练后的模型权重存储路径
  ...
  pretrained_model: /official_pretrained_model/PP-OCRv5_server_rec_pretrained.pdparams #预训练模型路径
  ...
...
Train:
  dataset:
    ...
    data_dir: /paddle/ocr_rec_dataset_examples/ #数据集根目录
    label_file_list:
      - /paddle/ocr_rec_dataset_examples/train.txt #训练集标注文件
    ...
...
Eval:
  dataset:
    ...
    data_dir: /paddle/ocr_rec_dataset_examples/ #数据集根目录
    label_file_list:
      - /paddle/ocr_rec_dataset_examples/val.txt #验证集标注文件
    ...
...

执行以下命令进行模型训练：

#单卡训练
python PaddleOCR/tools/train.py -c PaddleOCR/configs/rec/PP-OCRv5/PP-OCRv5_server_rec.yml

#多卡训练，通过--gpus参数指定卡号
python -m paddle.distributed.launch --gpus '0,1,2,3' PaddleOCR/tools/train.py -c PaddleOCR/configs/rec/PP-OCRv5/PP-OCRv5_server_rec.yml

模型训练完成后，训练好的模型权重会保存在./output/PP-OCRv5_server_rec目录下。

（4）模型评估

打开PP-OCRv5_server_rec.yml文件，将pretrained_model的路径设置为本地路径。若使用自行训练保存的模型，请注意修改路径和文件名为{path/to/weights}/{model_name}。

Global:
  ...
  pretrained_model: ./output/PP-OCRv5_server_rec/best_accuracy.pdparams #训练好的模型路径
  ...
...

执行以下命令进行模型评估：

python PaddleOCR/tools/eval.py -c PaddleOCR/configs/rec/PP-OCRv5/PP-OCRv5_server_rec.yml

（5）模型导出

打开PP-OCRv5_server_rec.yml文件，修改以下内容：

Global:
  ...
  save_inference_dir: ./PP-OCRv5_server_rec_infer/ #模型导出的存储目录
  ...
...

执行以下命令导出模型：

python PaddleOCR/tools/export_model.py -c PaddleOCR/configs/rec/PP-OCRv5/PP-OCRv5_server_rec.yml

导出模型后，静态图模型会存放于当前目录的./PP-OCRv5_server_rec_infer/中，在该目录下，您将看到如下文件：

./PP-OCRv5_server_rec_infer/
├── inference.json
├── inference.pdiparams
├── inference.yml

至此，文本识别模型微调完成，该静态图模型可以直接集成到 PaddleOCR 的 API 中。

4.2 模型应用

当您使用私有数据集完成微调训练后，可获得本地模型权重文件，然后可以通过参数指定本地模型保存路径的方式，或者通过自定义产线配置文件的方式，使用微调后的模型权重。

4.2.1 通过参数指定本地模型路径

在初始化产线对象时，通过参数指定本地模型路径。以文本检测模型微调后的权重的使用方法为例，示例如下：

命令行方式:

# 通过 --text_detection_model_dir 指定本地模型路径
paddleocr ocr -i ./general_ocr_002.png --text_detection_model_dir your_det_model_path

# 默认使用 PP-OCRv5_server_det 模型作为默认文本检测模型，如果微调的不是该模型，通过 --text_detection_model_name 修改模型名称
paddleocr ocr -i ./general_ocr_002.png --text_detection_model_name PP-OCRv5_mobile_det --text_detection_model_dir your_v5_mobile_det_model_path

脚本方式：

from paddleocr import PaddleOCR

# 通过 text_detection_model_dir 指定本地模型路径
pipeline = PaddleOCR(text_detection_model_dir="./your_det_model_path")

# 默认使用 PP-OCRv5_server_det 模型作为默认文本检测模型，如果微调的不是该模型，通过 text_detection_model_name 修改模型名称
# pipeline = PaddleOCR(text_detection_model_name="PP-OCRv5_mobile_det", text_detection_model_dir="./your_v5_mobile_det_model_path")

4.2.2 通过配置文件指定本地模型路径

1.获取产线配置文件

可调用 PaddleOCR 中通用 OCR 产线对象的 export_paddlex_config_to_yaml 方法，将当前产线配置导出为 YAML 文件：

from paddleocr import PaddleOCR

pipeline = PaddleOCR()
pipeline.export_paddlex_config_to_yaml("PaddleOCR.yaml")

2.修改配置文件

在得到默认的产线配置文件后，将微调后模型权重的本地路径替换至产线配置文件中的对应位置即可。例如

......
SubModules:
  TextDetection:
    box_thresh: 0.6
    limit_side_len: 64
    limit_type: min
    max_side_limit: 4000
    model_dir: null # 替换为微调后的文本测模型权重路径
    model_name: PP-OCRv5_server_det # 如果微调的模型名称与默认模型名称不同，请一并修改此处
    module_name: text_detection
    thresh: 0.3
    unclip_ratio: 1.5
  TextLineOrientation:
    batch_size: 6
    model_dir: null  # 替换为微调后的文本行方向分类模型权重路径
    model_name: PP-LCNet_x1_0_textline_ori # 如果微调的模型名称与默认模型名称不同，请一并修改此处
    module_name: textline_orientation
  TextRecognition:
    batch_size: 6
    model_dir: null # 替换为微调后的文本识模型权重路径
    model_name: PP-OCRv5_server_rec # 如果微调的模型名称与默认模型名称不同，请一并修改此处
    module_name: text_recognition
    score_thresh: 0.0
......

在产线配置文件中，不仅包含 PaddleOCR CLI 和 Python API 支持的参数，还可进行更多高级配置，具体信息可在 PaddleX模型产线使用概览中找到对应的产线使用教程，参考其中的详细说明，根据需求调整各项配置。

3.在 CLI 中加载产线配置文件

在修改完成配置文件后，通过命令行的 --paddlex_config 参数指定修改后的产线配置文件的路径，PaddleOCR 会读取其中的内容作为产线配置。示例如下：

paddleocr ocr --paddlex_config PaddleOCR.yaml ...

4.在 Python API 中加载产线配置文件

初始化产线对象时，可通过 paddlex_config 参数传入 PaddleX 产线配置文件路径或配置dict，PaddleOCR 会读取其中的内容作为产线配置。示例如下：

from paddleocr import PaddleOCR

pipeline = PaddleOCR(paddlex_config="PaddleOCR.yaml")