企业官网建设流程全解析

PaddleOCR 昆仑 XPU 部署指南：基于 PaddlePaddle 的 R200/R300 环境安装与验证全流程

【免费下载链接】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

昆仑 XPU（Kunlun Xin Processing Unit）是面向 AI 计算场景的高性能处理器，PaddleOCR 已支持昆仑 R200/R300 等芯片，用户可以在 XPU 设备上完成 OCR 模型的训练与推理。本文基于 paddlepaddle_install_XPU.en.md 展开，系统讲解从 Docker 开发环境准备、PaddlePaddle XPU 版安装到环境验证的完整流程，并结合仓库源码说明设备切换机制与注意事项。读完本文，你将掌握在 X86 与 ARM（麒麟）两种架构下快速搭建昆仑 XPU 深度学习环境，并让 PaddleOCR 在 XPU 上运行的基本能力。

1. 支持范围与整体思路

PaddleOCR 目前支持昆仑R200 / R300等芯片。考虑到不同服务器环境（驱动、固件、系统库）差异较大，官方强烈推荐使用飞桨官方发布的昆仑 XPU 开发镜像作为基础环境，该镜像已经预装了昆仑基础运行环境库（XRE，即 Kunlun Runtime Environment），可以规避大量底层环境兼容性问题。

整体安装路径如下：

1. 拉取昆仑 XPU 开发镜像并启动容器（镜像不包含预编译的飞桨安装包，仅提供开发环境）；
2. 在容器内通过 pip 安装对应架构的 PaddlePaddle XPU wheel 包；
3. 运行paddle.utils.run_check()验证飞桨与 XPU 是否就绪；
4. 安装 PaddleOCR 并切换到 XPU 设备运行。

需要注意的是，本文档介绍的是基于飞桨（PaddlePaddle）框架的安装与使用方式；如果你计划使用其他推理引擎（如 TensorRT、ONNX Runtime 等），请参考对应引擎的官方安装与配置文档。

2. Docker 环境准备

2.1 拉取开发镜像

根据宿主机的 CPU 架构选择对应镜像，镜像仓库统一为registry.baidubce.com/device/paddle-xpu：

# X86 架构 docker pull registry.baidubce.com/device/paddle-xpu:ubuntu20-x86_64-gcc84-py310 # ARM 架构（麒麟 V10 操作系统） docker pull registry.baidubce.com/device/paddle-xpu:kylinv10-aarch64-gcc82-py310

两个镜像的差异主要体现在三个方面：

• 基础系统：X86 镜像基于 Ubuntu 20.04，ARM 镜像基于麒麟 V10（Kylin V10），后者面向国产化服务器场景；
• 编译器：分别为 gcc84 与 gcc82；
• Python 版本：两者均为 Python 3.10。

从仓库的 TIPC 测试脚本 test_tipc/test_train_inference_python_xpu.sh 中可以看到，XPU 后端此前长期基于 Python 3.9 运行（脚本中有python has been updated to version 3.9 for xpu backend的注释），而当前开发镜像已将 Python 升级到 3.10，这也是 wheel 包按cp310提供的原因。

2.2 启动容器

参考如下命令启动容器（按需修改--name等参数）：

docker run -it --name=xxx -m 81920M --memory-swap=81920M \ --shm-size=128G --privileged --net=host \ -v $(pwd):/workspace -w /workspace \ registry.baidubce.com/device/paddle-xpu:$(uname -m)-py310 bash

各关键参数说明：

注意：镜像实际的完整 tag 名称是ubuntu20-x86_64-gcc84-py310与kylinv10-aarch64-gcc82-py310，若$(uname -m)-py310方式拉取失败，请直接使用 2.1 节中的完整镜像名。

3. 安装 PaddlePaddle XPU 版

3.1 pip 安装 wheel 包

当前官方提供Python 3.10的 wheel 安装包。如果你需要其他 Python 版本，可以参照飞桨官方文档自行编译安装（XPU 版飞桨需要带有 XPU 编译选项的定制构建）。

按宿主机架构选择对应安装包：

# X86 架构 pip install https://paddle-whl.bj.bcebos.com/paddlex/xpu/paddlepaddle_xpu-2.6.1-cp310-cp310-linux_x86_64.whl # ARM 架构 pip install https://paddle-whl.bj.bcebos.com/paddlex/xpu/paddlepaddle_xpu-2.6.1-cp310-cp310-linux_aarch64.whl

安装包信息速览：

3.2 验证安装

安装完成后，运行以下命令验证飞桨与 XPU 设备是否工作正常：

python -c "import paddle; paddle.utils.run_check()"

预期输出：

PaddlePaddle is installed successfully! Let's start deep learning with PaddlePaddle now.

看到该输出即说明飞桨 XPU 版安装成功，底层 XPU 设备已可以被飞桨正常调用。

4. 安装 PaddleOCR

XPU 环境就绪后，接下来安装 PaddleOCR 本体（即安装paddleocrPython 包），建议在容器内执行：

python -m pip install paddleocr

如需从源码运行（例如使用仓库中的训练/推理脚本与配置），可先克隆仓库再安装依赖：

git clone https://github.com/PaddlePaddle/PaddleOCR cd PaddleOCR python -m pip install -r requirements.txt

更完整的安装选项（如paddleocr[all]全量依赖）可参考 PaddleOCR 安装教程。

5. 在 XPU 上使用 PaddleOCR

安装完成后，PaddleOCR 在 XPU 上的训练与推理方式与 GPU 基本一致，只需要把设备参数从 GPU 切换为 XPU 即可。

5.1 命令行快速推理

# 默认使用 PP-OCRv5 模型，--device 指定为 xpu:0 paddleocr ocr -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png --device xpu:0

其中--device参数支持cpu、gpu、npu、xpu及带编号的形式（如xpu:0），在 paddleocr/_common_args.py 中统一解析并透传给底层推理引擎。更多 OCR 产线使用说明见 通用 OCR 产线使用教程。

5.2 Python 代码推理

from paddleocr import PaddleOCR ocr = PaddleOCR(device="xpu:0") result = ocr.predict("./general_ocr_002.png") for res in result: res.print() res.save_to_img("output") res.save_to_json("output")

5.3 模型微调训练（XPU）

若对预训练模型效果不满意，可基于仓库训练脚本在 XPU 上进行微调。参考多硬件使用指南 multi_devices_use_guide.md 中的 XPU 微调示例：

export FLAGS_use_stride_kernel=0 export BKCL_FORCE_SYNC=1 export BKCL_TIMEOUT=1800 export XPU_BLACK_LIST=pad3d,pad3d_grad python3 -m paddle.distributed.launch --devices '0,1,2,3' \ tools/train.py -c configs/rec/PP-OCRv5/PP-OCRv5_mobile_rec.yml \ -o Global.use_gpu=False Global.use_xpu=True

其中：

• BKCL_FORCE_SYNC=1：强制 BKCL（百度昆仑通信库）同步执行，保证多卡通信结果一致；
• BKCL_TIMEOUT=1800：设置 BKCL 通信超时时间（秒），避免多卡训练偶发卡死；
• XPU_BLACK_LIST=pad3d,pad3d_grad：将pad3d及其反向算子加入黑名单，改用 CPU 实现，规避部分算子在高精度场景下的数值问题；
• Global.use_xpu=True：在配置中显式启用 XPU 设备。

6. 源码层面的设备支持机制

从仓库源码可以进一步印证 XPU 支持的具体实现方式：

（1）设备互斥与编译检查：在 tools/program.py 的check_device()函数中，训练/评估入口会对各设备开关做互斥与可用性校验。当use_gpu与use_xpu同时为真时会报错提示；当设置use_xpu=True但当前飞桨并非 XPU 编译版时（paddle.device.is_compiled_with_xpu()返回 False），会提示用户安装 XPU 版飞桨或改回 CPU 运行——这正对应了本文第 3 节必须安装paddlepaddle_xpuwheel 包的原因。

（2）设备选择逻辑：在 tools/program.py 中，训练脚本会依次读取Global.use_gpu / use_xpu / use_npu / use_mlu等配置项，并根据优先级构造device = "xpu:{0}".format(os.getenv("FLAGS_selected_xpus", 0))，即默认使用xpu:0，也可通过环境变量FLAGS_selected_xpus指定具体卡号。

（3）TIPC 自动化验证：仓库提供了 XPU 专用的端到端测试脚本 test_tipc/test_train_inference_python_xpu.sh，脚本会将 TIPC 配置中的use_gpu批量替换为use_xpu、关闭 MKLDNN 与 benchmark（AutoLog 依赖 nvidia-smi），并针对rec_r31_sar、rec_mtb_nrtr等模型调整 epoch 与卡数配置，最终复用test_tipc/test_train_inference_python.sh完成 XPU 上的训练与推理回归验证。

7. 常见问题与注意事项

1. PaddlePaddle is installed successfully未出现：多为 XPU 驱动/XRE 未正确加载，确认容器以--privileged启动，且宿主机已安装对应版本的昆仑驱动与 XRE 库（开发镜像默认已包含）。
2. 报错 "your paddle is not compiled with xpu"：说明当前安装的是 CPU 版飞桨，需要按第 3 节重新安装 XPU 版 wheel 包，并在配置中将use_xpu置为 True。
3. 多卡训练卡死或结果不一致：检查是否设置了BKCL_FORCE_SYNC=1与合理的BKCL_TIMEOUT值。
4. 精度异常：可尝试将pad3d、pad3d_grad等算子加入XPU_BLACK_LIST，强制回退到 CPU 实现；如需其他 Python 版本，请参考飞桨官方文档自行编译 XPU 版安装包。

以上即昆仑 XPU 上搭建 PaddleOCR 环境并完成验证的完整流程。安装完成后，PaddleOCR 的检测、识别、文档解析等能力均可通过--device xpu:0（或代码中的device="xpu:0"）无缝切换到昆仑芯片上运行。

【免费下载链接】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