PaddleOCR 昆仑 XPU 环境安装教程从飞桨开发镜像到容器化推理部署【免费下载链接】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昆仑 XPUKunlun XPU是百度昆仑芯推出的 AI 加速硬件PaddleOCR 当前已支持昆仑 R200/R300 等芯片并在昆仑芯 P800 上完成了 PaddleOCR-VL 的精度与速度验证。本文以仓库文档 昆仑 XPU 飞桨安装教程 为主线完整讲解基于飞桨官方昆仑 XPU 开发镜像的环境搭建、飞桨 wheel 包安装、安装验证并结合仓库源码与部署资源补充 PaddleOCR 安装、快速推理、模型微调与服务化部署的实战方案。读完本文你将能够在昆仑 XPU 硬件上独立完成从零搭建到跑通 OCR 训练与推理的全过程。1. 背景PaddleOCR 对昆仑 XPU 的支持范围PaddleOCR 对昆仑 XPU 的支持建立在飞桨PaddlePaddle框架之上。由于各硬件平台的底层运行环境差异较大官方推荐的路径是直接使用飞桨官方发布的昆仑 XPU 开发镜像该镜像已预装昆仑基础运行环境库XREXilinx/昆仑 Runtime Environment避免手动配置驱动与运行库的繁琐过程。需要明确的是本文档主要介绍基于飞桨框架的环境安装与使用方式若你计划使用其他推理引擎如 ONNX Runtime、TensorRT 等请按照对应引擎的官方文档完成安装与配置。从仓库源码看PaddleOCR 的训练与推理侧都明确支持 XPU 设备。推理侧在 tools/infer/utility.py 中定义了--use_gpu与--use_xpu两个互斥参数当args.use_xpu为真时会调用config.enable_xpu(10 * 1024 * 1024)为 Paddle Inference 配置 XPU 运行环境见 tools/infer/utility.py训练侧则通过Global.use_xpuTrue开关切换设备。此外仓库还提供了专门的 XPU 训练推理测试脚本 test_tipc/test_train_inference_python_xpu.sh其内部通过sed -i s/use_gpu/use_xpu/g等操作将 TIPC 配置文件中的设备参数替换为 XPU印证了训练、推理方法与 GPU 相同仅需修改设备参数的设计原则。2. Docker 环境准备考虑到不同机器的环境差异官方推荐使用飞桨官方发布的昆仑 XPU 开发镜像。注意此镜像仅为开发环境不包含预编译的飞桨安装包飞桨本体需要按下一节另行安装。2.1 拉取镜像根据宿主机 CPU 架构选择对应标签docker pull registry.baidubce.com/device/paddle-xpu:ubuntu20-x86_64-gcc84-py310 # X86 架构 docker pull registry.baidubce.com/device/paddle-xpu:kylinv10-aarch64-gcc82-py310 # ARM 架构标签语义说明ubuntu20-x86_64-gcc84-py310Ubuntu 20.04 系统、x86_64 架构、GCC 8.4 编译、Python 3.10kylinv10-aarch64-gcc82-py310麒麟 V10 系统、aarch64ARM架构、GCC 8.2 编译、Python 3.10。这一基础镜像在仓库的 XPU 部署资源中被直接复用例如 deploy/paddleocr_vl_docker/accelerators/kunlunxin-xpu/pipeline.Dockerfile 的FROM即基于ccr-2vdh3abv-pub.cnc.bj.baidubce.com/device/paddle-xpu:ubuntu20-x86_64-gcc84-py310构建。2.2 启动容器参考如下命令启动容器docker run -it --namexxx -m 81920M --memory-swap81920M \ --shm-size128G --privileged --nethost \ -v $(pwd):/workspace -w /workspace \ registry.baidubce.com/device/paddle-xpu:$(uname -m)-py310 bash各参数的作用如下参数含义-it以交互模式启动便于在容器内执行命令--namexxx为容器命名替换为你的实际名称-m 81920M --memory-swap81920M限制容器内存为 80 GiB并同步设置 swap 上限保证大模型训练/推理时的内存稳定性--shm-size128G增大/dev/shm共享内存避免 PyTorch/Paddle 多进程 DataLoader 因共享内存不足报错--privileged授予容器宿主机设备访问权限XPU 设备直通必需--nethost使用宿主机网络方便分布式训练与服务端口访问-v $(pwd):/workspace -w /workspace将当前目录挂载到容器/workspace并作为工作目录$(uname -m)-py310按宿主机架构拼接镜像标签提示原文档使用$(uname -m)-py310动态拼接镜像标签实际可用的完整标签以 2.1 节docker pull时的具体标签如ubuntu20-x86_64-gcc84-py310为准建议直接指定完整标签以避免拉取失败。3. 安装飞桨 PaddlePaddle 包当前官方提供Python 3.10的 wheel 安装包。若你确有其他 Python 版本的需求可以参考飞桨官方安装文档自行编译安装不在本文范围内。3.1 安装 wheel 包按宿主机架构选择对应的 wheel 地址pip install https://paddle-whl.bj.bcebos.com/paddlex/xpu/paddlepaddle_xpu-2.6.1-cp310-cp310-linux_x86_64.whl # X86 架构 pip install https://paddle-whl.bj.bcebos.com/paddlex/xpu/paddlepaddle_xpu-2.6.1-cp310-cp310-linux_aarch64.whl # ARM 架构几点说明包名为paddlepaddle_xpu版本号2.6.1文件名中的cp310表示 Python 3.10 兼容的 CPython 构建linux_x86_64/linux_aarch64分别对应 X86 与 ARM 架构必须与 2.1 节拉取的镜像架构一致该版本对应 XPU 后端的飞桨框架仓库 deploy/paddleocr_vl_docker/accelerators/kunlunxin-xpu/pipeline.Dockerfile 在构建 PaddleOCR-VL XPU 镜像时使用的是更高版本paddlepaddle-xpu3.2.1来自https://www.paddlepaddle.org.cn/packages/stable/xpu-p800/源说明 XPU 后端的飞桨版本随功能迭代在持续演进安装时以官方当前提供的 wheel 为准。3.2 验证安装安装完成之后运行如下命令验证飞桨能否正确加载并识别 XPU 设备python -c import paddle; paddle.utils.run_check()预期得到如下输出结果PaddlePaddle is installed successfully! Lets start deep learning with PaddlePaddle now.出现上述输出即代表飞桨 XPU 版本安装成功可以进入下一步 PaddleOCR 的安装与使用。4. 安装 PaddleOCR 并验证 XPU 快速推理飞桨安装完成后参考 PaddleOCR 安装教程 安装 PaddleOCR。安装完毕后可直接通过命令行在 XPU 上体验 OCR 产线推理默认使用 PP-OCRv5 模型将设备名指定为xpu即可paddleocr ocr -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png --device xpuPP-StructureV3 文档解析产线同理paddleocr pp_structurev3 -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/pp_structure_v3_demo.png --device xpu在代码中只需通过device参数即可完成设备切换from paddleocr import PaddleOCR ocr PaddleOCR(devicexpu) result ocr.predict(./general_ocr_002.png) for res in result: res.print() res.save_to_img(output) res.save_to_json(output)PP-StructureV3 产线推理from paddleocr import PPStructureV3 pipeline PPStructureV3(devicexpu) output pipeline.predict(./pp_structure_v3_demo.png) for res in output: res.print() # 打印预测的结构化输出 res.save_to_json(save_pathoutput) # 保存当前图像的结构化 json 结果 res.save_to_markdown(save_pathoutput) # 保存当前图像的 markdown 格式结果在昆仑 XPU 上PaddleOCR 的快速推理与模型微调支持三大特色能力文字识别模型 PP-OCRv5、文档解析方案 PP-StructureV3 与 PP-ChatOCRv4。更多产线使用细节可参考 通用OCR产线使用教程 与 PP-StructureV3产线使用教程。5. 在 XPU 上进行模型微调如果对预训练模型的效果不满意可以在产线模型上进行模型微调。昆仑 XPU 的训练方式与 GPU 完全一致仅需在启动命令中通过-o覆盖配置项Global.use_gpuFalse Global.use_xpuTrue同时设置 XPU 相关的环境变量export FLAGS_use_stride_kernel0 export BKCL_FORCE_SYNC1 export BKCL_TIMEOUT1800 export XPU_BLACK_LISTpad3d,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_gpuFalse Global.use_xpuTrue各环境变量的作用环境变量作用FLAGS_use_stride_kernel0关闭 stride kernel规避 XPU 后端部分算子的兼容问题BKCL_FORCE_SYNC1强制百度集合通信库BKCLBaidu Kunlun Communication Library同步保证多卡训练数据一致性BKCL_TIMEOUT1800设置 BKCL 通信超时时间秒避免多卡训练时通信卡死XPU_BLACK_LISTpad3d,pad3d_grad将pad3d及其梯度算子加入黑名单改由 CPU 或其他后端执行其中-c configs/rec/PP-OCRv5/PP-OCRv5_mobile_rec.yml指向仓库中的 PP-OCRv5 移动端识别训练配置--devices 0,1,2,3表示使用 0~3 号 XPU 卡进行分布式训练。仓库的 test_tipc/test_train_inference_python_xpu.sh 正是通过批量替换配置中的use_gpu → use_xpu、关闭benchmark因 AutoLog 依赖 nvidia-smi等步骤将完整的 TIPC 训练推理流程迁移到 XPU 上执行可作为大规模 XPU 训练验证的参考实现。6. 服务化部署PaddleOCR-VL 在昆仑 XPU 上的 Docker Compose 方案除了本地推理与微调仓库还提供了 PaddleOCR-VL 在昆仑芯 XPU 上的完整服务化部署方案详见 PaddleOCR-VL 昆仑芯 XPU 使用教程。该教程明确PaddleOCR-VL 已在昆仑芯 P800 上完成精度、速度验证鉴于硬件环境的多样性其他昆仑芯 XPU 的兼容性尚未验证欢迎社区用户测试反馈。部署资源位于 deploy/paddleocr_vl_docker/accelerators/kunlunxin-xpu/compose.yaml 定义了两个容器paddleocr-vl-api产线服务通过paddlex --serve --pipeline ... --device xpu启动默认监听 8080 端口并带 healthcheck与paddleocr-vlm-server底层 VLM 推理服务默认通过.env中的VLM_BACKEND选择vllm或fastdeploy后端pipeline.Dockerfile 基于 XPU 开发镜像安装paddlepaddle-xpu3.2.1与paddleocr[doc-parser]并内置中文字体与离线模型资源CMD默认以--device xpu启动服务。部署流程# 在 compose.yaml 与 .env 所在目录执行 docker compose up启动后若看到类似输出即成功paddleocr-vl-api | INFO: Started server process [1] paddleocr-vl-api | INFO: Waiting for application startup. paddleocr-vl-api | INFO: Application startup complete. paddleocr-vl-api | INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRLC to quit)如需调整使用的 XPU 卡可在compose.yaml中为两个服务分别添加XPU_VISIBLE_DEVICES环境变量例如XPU_VISIBLE_DEVICES: 1指定使用卡 1如需修改服务端口调整paddleocr-vl-api.ports即可。7. 常见问题与注意事项docker run拉不到镜像或标签不存在优先使用docker pull中给出的完整标签如ubuntu20-x86_64-gcc84-py310$(uname -m)-py310仅为便捷写法不代表完整标签。验证命令输出异常paddle.utils.run_check()若未输出PaddlePaddle is installed successfully! ...请确认 wheel 架构x86_64 / aarch64与镜像架构一致且容器以--privileged方式启动以便访问 XPU 设备。Python 版本受限当前官方仅提供 Python 3.10 的 XPU wheel其他版本需参考飞桨官方文档自行编译。训练算子兼容问题微调时务必按第 5 节设置XPU_BLACK_LISTpad3d,pad3d_grad等环境变量否则可能出现算子不支持导致的训练中断。推理结果异常在 XPU 上使用产线推理时若个别模型主要是 PP-StructureV3 产线在少量样本上存在精度误差可以尝试调整配置文件中的模型或参考 PaddleOCR 多硬件使用指南 中介绍的 ONNX/OM 高性能推理方案。8. 总结本文完整复现了 昆仑 XPU 飞桨安装教程 的全部内容基于飞桨官方昆仑 XPU 开发镜像搭建 Docker 环境、安装 Python 3.10 的paddlepaddle_xpuwheel 包、并通过paddle.utils.run_check()验证安装。在此基础上结合仓库源码与部署资源进一步覆盖了 PaddleOCR 在 XPU 上的快速推理、模型微调含 BKCL/XPU 环境变量与 PaddleOCR-VL 的 Docker Compose 服务化部署。整套方案的核心理念是XPU 上的使用方式与 GPU 完全一致只需把设备参数从 GPU 切换为 XPU这也是 PaddleOCR 多硬件使用指南 贯穿始终的原则。【免费下载链接】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），仅供参考
