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 包版本 |
如果只希望使用 PaddleOCR 的推理功能，请参考 安装推理包；如果还希望进行模型训练、导出等，请参考 安装训练依赖。在同一环境中安装推理包和训练依赖是允许的，无需进行环境隔离。
2.1 安装推理包
从 PyPI 安装最新版本 PaddleOCR 推理包：
python -m pip install paddleocr |
或者从源码安装（默认为开发分支）：
python -m pip install "git+https://github.com/PaddlePaddle/PaddleOCR.git" |
2.2 安装训练依赖
要进行模型训练、导出等，需要首先将仓库克隆到本地：
# 推荐方式 |
执行如下命令安装依赖：
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.0gpu：- CUDA 11.8：
ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddle:3.0.0-gpu-cuda11.8-cudnn8.9-trt8.6
- CUDA 11.8：
应确保环境中安装有符合要求的 TensorRT，否则 Paddle Inference TensorRT 子图引擎将不可用，程序可能无法取得最佳推理性能。目前 PaddleOCR 仅支持 TensorRT 8.6.1.6，请参考 TensorRT 文档 安装 TensorRT。示例如下：
# 下载 TensorRT tar 文件 |
3.1.2 执行高性能推理
对于 PaddleOCR CLI，指定 --enable_hpi 为 True 即可执行高性能推理。例如：
paddleocr ocr --enable_hpi True ... |
对于 PaddleOCR Python API，在初始化产线对象或者模块对象时，设置 enable_hpi 为 True 即可在调用推理方法时执行高性能推理。例如：
from paddleocr import PaddleOCR |
对于 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] |
如需调整配置（如模型路径、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）准备数据集
# 下载示例数据集 |
（2）下载预训练模型
# 下载 PP-OCRv5_server_det 预训练模型 |
（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: |
执行以下命令进行模型训练：
#单卡训练 |
模型训练完成后，训练好的模型权重会保存在./output/PP-OCRv5_server_det目录下。
（4）模型评估
打开PP-OCRv5_server_det.yml文件，将pretrained_model的路径设置为本地路径。若使用自行训练保存的模型，请注意修改路径和文件名为{path/to/weights}/{model_name}。
Global: |
执行以下命令进行模型评估：
python PaddleOCR/tools/eval.py -c PaddleOCR/configs/det/PP-OCRv5/PP-OCRv5_server_det.yml |
（5）模型导出
打开PP-OCRv5_server_det.yml文件，修改以下内容：
Global: |
执行以下命令导出模型：
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/ |
至此，文本检测模型微调完成，该静态图模型可以直接集成到 PaddleOCR 的 API 中。
4.1.2 文本识别模型微调
如果文本识别模型在您的场景上效果仍然不理想，您可以尝试以下步骤进行模型微调。
首先，您需要准备文本识别的数据集，可采用PPOCRLabel标注工具，并参考文本识别 Demo 数据的格式准备，准备好后，即可按照以下步骤进行模型训练和导出，导出后，可以将模型快速集成到上述 API 中。此处以文本识别 Demo 数据为例，在训练模型之前，请确保已经按照安装文档安装了 PaddleOCR 所需要的依赖。
（1）准备数据集
# 下载示例数据集 |
（2）下载预训练模型
# 下载 PP-OCRv5_server_rec 预训练模型 |
（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: |
执行以下命令进行模型训练：
#单卡训练 |
模型训练完成后，训练好的模型权重会保存在./output/PP-OCRv5_server_rec目录下。
（4）模型评估
打开PP-OCRv5_server_rec.yml文件，将pretrained_model的路径设置为本地路径。若使用自行训练保存的模型，请注意修改路径和文件名为{path/to/weights}/{model_name}。
Global: |
执行以下命令进行模型评估：
python PaddleOCR/tools/eval.py -c PaddleOCR/configs/rec/PP-OCRv5/PP-OCRv5_server_rec.yml |
（5）模型导出
打开PP-OCRv5_server_rec.yml文件，修改以下内容：
Global: |
执行以下命令导出模型：
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/ |
至此，文本识别模型微调完成，该静态图模型可以直接集成到 PaddleOCR 的 API 中。
4.2 模型应用
当您使用私有数据集完成微调训练后，可获得本地模型权重文件，然后可以通过参数指定本地模型保存路径的方式，或者通过自定义产线配置文件的方式，使用微调后的模型权重。
4.2.1 通过参数指定本地模型路径
在初始化产线对象时，通过参数指定本地模型路径。以文本检测模型微调后的权重的使用方法为例，示例如下：
命令行方式:
# 通过 --text_detection_model_dir 指定本地模型路径 |
脚本方式：
from paddleocr import PaddleOCR |
4.2.2 通过配置文件指定本地模型路径
1.获取产线配置文件
可调用 PaddleOCR 中 通用 OCR 产线对象的 export_paddlex_config_to_yaml 方法，将当前产线配置导出为 YAML 文件：
from paddleocr import PaddleOCR |
2.修改配置文件
在得到默认的产线配置文件后，将微调后模型权重的本地路径替换至产线配置文件中的对应位置即可。例如
...... |
在产线配置文件中，不仅包含 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 |
5. 常见问题与解决方案
5.1 性能优化问题
Q: GPU推理速度慢怎么办？
A: 可以通过以下方式优化：
（1）启用高性能推理：设置enable_hpi=True，自动选择最优加速策略 ；
（2）启用TensorRT加速：设置use_tensorrt=True，需要CUDA 11.8+和TensorRT 8.6+ ；
（3）使用半精度：设置precision="fp16"，可以显著提升速度 ；
（4）调整批处理大小：根据显存大小设置合适的batch_size ；
（5）使用轻量模型：在精度要求不高时使用 PP-OCRv6_small/PP-OCRv6_tiny 等轻量级模型。
Q: GPU内存不足（CUDA out of memory）怎么办？
A: 可以通过以下方式解决：
（1）减小批处理大小：将batch_size设置为1 ；
（2）减小图像尺寸：设置det_limit_side_len=640 ；
（3）启用内存优化：设置enable_memory_optim=True ；
（4）限制GPU内存使用：设置gpu_mem=200 ；
（5）使用轻量模型：切换到 PP-OCRv6_small/PP-OCRv6_tiny 等轻量级模型。
5.2 检测精度问题
Q: 检测框不准确或漏检怎么办？
A: 可以通过以下方式优化：
（1）调整检测参数：
model = TextDetection( |
（2）使用更精确的后处理模式：设置det_db_score_mode="slow" ；
（3）启用膨胀处理：设置use_dilation=True。
5.3 模型选择建议
Q: 如何选择合适的模型？
A: 根据应用场景选择：
- 服务器高精度场景：使用
PP-OCRv6_medium或PP-OCRv5_server系列，精度最高； - 移动端部署：使用
PP-OCRv6_small或PP-OCRv5_mobile系列，兼顾精度与效率； - 端侧/IoT：使用
PP-OCRv6_tiny系列，模型最小； - 实时处理：使用
PP-OCRv6_small或PP-OCRv6_tiny系列，推理更快； - 多语言识别：拉丁语系等可使用
PP-OCRv6系列； - 阿拉伯文、西里尔文、天城文等语系请使用
PP-OCRv5系列。
5.4 参数调优建议
Q: 如何调优检测参数？
A: 通过参数limit_type和limit_side_len来对图片的尺寸进行限制，limit_type可选参数为[max, min]，limit_side_len 为正整数，一般设置为 32 的倍数，比如 960。
如果输入图形分辨率不大，建议使用limit_type=min 和 limit_side_len=960 节省计算资源的同时能获得最佳检测效果。如果输入图片的分辨率比较大，而且想使用更大的分辨率预测，可以设置 limit_side_len 为想要的值，比如 1216。
Q: 不同场景的参数配置建议？
高精度配置：
limit_side_len=1216,thresh=0.3,box_thresh=0.5,unclip_ratio=1.5高速度配置：
limit_side_len=640,thresh=0.5,box_thresh=0.7,unclip_ratio=1.2平衡配置：
limit_side_len=960,thresh=0.4,box_thresh=0.6,unclip_ratio=1.5
5.5 错误处理
Q: 模型加载失败怎么办？
（1）检查模型路径是否正确 ；
（2）确保模型文件完整（inference.pdmodel, inference.pdiparams, inference.json）；
（3）设置模型下载源：os.environ['PADDLE_PDX_MODEL_SOURCE'] = 'BOS' ；
（4）使用本地模型：指定model_dir参数。
Q: 输入数据格式错误怎么办？
（1）检查图像文件是否存在 ；
（2）确保图像格式正确（支持PNG、JPG、JPEG）；
（3）验证图像尺寸（最小10x10像素）；
（4）检查图像是否为3通道格式。