PaddleOCR-VL Hygon DCU 部署与使用完整指南从环境搭建到服务化推理【免费下载链接】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/PaddleOCRPaddleOCR-VL 是 PaddleOCR 推出的文档解析模型系列如 PaddleOCR-VL-1.6它通过版面分析 VLM 识别两阶段流水线将整页文档图像解析为结构化的 Markdown/JSON 结果。本指南以海光 DCUHygon K100AI为目标硬件完整覆盖从本地运行环境准备、快速开始、vLLM 加速推理服务、Docker Compose 生产级部署到模型微调的端到端流程。读完本文你将能够在海光 DCU 机器上独立搭建并调优 PaddleOCR-VL 推理环境并能根据实际业务场景选择本地直推、客户端 VLM 服务或完整 API 服务三种部署形态。说明本教程中的PaddleOCR-VL均指 PaddleOCR-VL 模型系列如 PaddleOCR-VL-1.6涉及 PaddleOCR-VL v1 专属特性时会单独注明。硬件支持概况与工作流选型PaddleOCR-VL 已在海光 K100AI 上完成精度与速度验证但由于硬件型号多样其他海光 DCU 型号的兼容性尚未确认。官方欢迎社区在不同硬件上测试并反馈结果。根据目标不同可按下表选择阅读路径各节编号与本文一致目标该硬件上的支持情况阅读章节本地直推支持第 1 节本地运行环境准备 第 2 节快速开始客户端 VLM 推理服务支持先完成本地直推再阅读第 3 节使用 VLM 推理服务完整 API 服务支持Docker Compose 部署先阅读 4.1再阅读 4.2 客户端调用与 4.3 流水线配置模型微调支持第 5 节模型微调从 PaddleOCR-VL 推理方法与硬件支持矩阵 可以看到在海光 DCU 上PaddlePaddle 推理引擎与 PaddlePaddle vLLM 组合均为 ✅ 支持状态而 Transformers 引擎及 PaddlePaddle SGLang、FastDeploy 等组合仍处于 开发或待验证状态。这意味着海光 DCU 的推荐推理路径是本地使用 PaddlePaddle 引擎直推生产环境使用 PaddlePaddle版面分析 vLLMVLM 识别的组合。1. 本地运行环境准备在 DCU 上搭建 PaddleOCR-VL 本地运行环境有两种方式本地环境搭建方式状态说明官方 Docker 镜像支持按本指南步骤操作见 1.1手动安装推理引擎与 PaddleOCR支持按本指南步骤操作见 1.2官方强烈推荐使用 Docker 镜像以最大限度规避环境相关问题。1.1 方式一使用 Docker 镜像使用官方 Docker 镜像启动容器要求 Docker 版本 19.03docker run -it \ --rm \ --user root \ --privileged \ --device /dev/kfd \ --device /dev/dri \ --device /dev/mkfd \ --group-add video \ --cap-add SYS_PTRACE \ --security-opt seccompunconfined \ -v /opt/hyhal/:/opt/hyhal/:ro \ --shm-size 64g \ --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-hygon-dcu \ /bin/bash # 在容器内调用 PaddleOCR CLI 或 Python API上述命令中的关键参数说明--device /dev/kfd、--device /dev/dri、--device /dev/mkfd将 DCU 设备节点透传进容器--group-add video加入 video 用户组以获取显卡访问权限-v /opt/hyhal/:/opt/hyhal/:ro只读挂载海光 HAL 驱动运行库Hygon HAL--shm-size 64gvLLM 等推理框架需要较大的共享内存--network host使用宿主机网络便于服务端口直连。离线环境若无外网可将镜像替换为离线版ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-hygon-dcu-offline约 24 GB在线版约 22 GB。TIPlatest-xxx标签对应最新版本若本地已有同名latest镜像且希望获取新特性或修复建议先执行docker pull。如需指定 PaddleOCR 版本可将标签中的latest替换为paddleocrmajor.minor例如ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:paddleocr3.3-hygon-dcu-offline。1.2 方式二手动安装推理引擎与 PaddleOCR无法使用 Docker 时可手动安装推理引擎与 PaddleOCR官方验证的 Python 版本范围为 3.9–3.13。需要注意该硬件上的本地推理目前仅支持 PaddlePaddle 推理引擎。强烈建议在虚拟环境中安装 PaddleOCR-VL 以避免依赖冲突例如使用 Python venv# 创建虚拟环境 python -m venv .venv_paddleocr # 激活环境 source .venv_paddleocr/bin/activate执行以下命令完成安装python -m pip install paddlepaddle-dcu3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/dcu/ python -m pip install -U paddleocr[doc-parser]注意请安装 PaddlePaddle 3.2.1 及以上版本。paddleocr[doc-parser]是 PaddleOCR-VL 所需的扩展安装项其中doc-parser提供文档解析流水线相关的依赖。2. 快速开始在 DCU 上快速开始的方式与 PaddleOCR-VL 使用教程 - 2. Quick Start 完全一致唯一区别是必须显式指定devicedcu。PaddleOCR-VL 支持 CLI 与 Python API 两种调用方式CLI 适合快速验证Python API 适合集成进现有工程。2.1 命令行使用首次运行时会自动下载官方模型文件请确保当前环境可访问外网并预留模型下载与初始化的时间。建议首次运行时加上--save_path ./output以便在本地查看保存结果# Hygon DCU paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --device dcu --save_path ./output执行成功后终端会打印结构化结果指定--save_path后结果文件会保存在当前工作目录的output目录下便于检查与调试。常用开关参数示例# 启用文档方向分类模块 paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --use_doc_orientation_classify True --save_path ./output # 启用文档矫正去弯曲模块 paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --use_doc_unwarping True --save_path ./output # 关闭版面分析与排序模块此时将仅由 VLM 直接识别整图 paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --use_layout_detection False --save_path ./output几个核心 CLI 参数的默认行为参数含义类型默认值pipeline_version指定流水线版本strv1.6可选v1、v1.5、v1.6layout_threshold版面模型置信度阈值取值 0–1float0.5layout_merge_bboxes_mode检测框合并模式large保留最外大框/small保留最内小框/union内外框均保留str由流水线初始化use_doc_orientation_classify是否启用文档方向分类boolFalseuse_doc_unwarping是否启用文档矫正boolFalseuse_layout_detection是否启用版面分析模块boolTrueuse_chart_recognition是否启用图表解析boolFalseuse_seal_recognition是否启用印章识别boolFalseuse_ocr_for_image_block是否对图片块内文字做 OCRboolFalseformat_block_content是否将block_content格式化为 MarkdownboolFalsemerge_layout_blocks是否合并跨栏/上下错落栏目的版面框boolTruemarkdown_ignore_labelsMarkdown 中需忽略的版面标签list[number,footnote,header,header_image,footer,footer_image,aside_text]use_queues是否启用内部队列异步流水boolTruedevice推理设备DCU 上为dcu或dcu:0指定卡号str默认优先 GPU 0不可用则回退 CPUlayout_shape_mode版面结果的几何表示rect/quad/poly/autostrauto说明快速开始章节的方法主要用于快速验证其推理速度、显存占用与稳定性未必满足生产环境要求。生产部署强烈建议使用专用 VLM 推理服务方法见第 3 节。2.2 Python 脚本集成在实际项目中通常通过代码集成模型仅需几行代码即可运行 PaddleOCR-VL 推理from pathlib import Path from paddleocr import PaddleOCRVL output_dir Path(./output) output_dir.mkdir(parentsTrue, exist_okTrue) # Hygon DCU指定 devicedcu pipeline PaddleOCRVL(devicedcu) # 可选项 # pipeline PaddleOCRVL(devicedcu, use_doc_orientation_classifyTrue) # 启用文档方向分类 # pipeline PaddleOCRVL(devicedcu, use_doc_unwarpingTrue) # 启用文档矫正 # pipeline PaddleOCRVL(devicedcu, use_layout_detectionFalse) # 关闭版面分析 output pipeline.predict(https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png) for res in output: res.print() # 打印结构化预测结果 res.save_to_json(save_pathoutput_dir) # 保存 JSON 结构化结果 res.save_to_markdown(save_pathoutput_dir) # 保存 Markdown 结果 res.save_to_word(save_pathoutput) # 保存 Word 结果多页 PDF 重组PDF 的每一页会被独立处理并生成独立的 Markdown 文件。若需要跨页合并表格、重建多级标题或合并多页结果使用restructure_pagesfrom pathlib import Path from paddleocr import PaddleOCRVL input_file ./your_pdf_file.pdf output_dir Path(./output) output_dir.mkdir(parentsTrue, exist_okTrue) pipeline PaddleOCRVL(devicedcu) output pipeline.predict(inputinput_file) pages_res list(output) output pipeline.restructure_pages(pages_res) # output pipeline.restructure_pages(pages_res, merge_tablesTrue) # 跨页合并表格 # output pipeline.restructure_pages(pages_res, merge_tablesTrue, relevel_titlesTrue) # 跨页合并表格 重建多级标题 # output pipeline.restructure_pages(pages_res, merge_tablesTrue, relevel_titlesTrue, concatenate_pagesTrue) # 再合并多页 for res in output: res.print() res.save_to_json(save_pathoutput_dir) res.save_to_markdown(save_pathoutput_dir)批量处理处理多个文件时推荐把目录路径或文件路径列表传给predict以最大化处理效率# imgs 目录下包含 file1.png、file2.png、file3.png output pipeline.predict(imgs) # 或传入文件路径列表 output pipeline.predict([imgs/file1.png, imgs/file2.png, imgs/file3.png]) # 以上两种方式都优于逐文件循环调用 predict3. 使用 VLM 推理服务本节介绍如何将 PaddleOCR-VL 接入独立的 VLM 推理服务后端。其核心思想是客户端继续承担版面分析等流水线其他阶段仅将 VLM 识别阶段委托给专用服务。在海光 DCU 上这通常用于在生产环境中提升推理性能。本硬件指南以 vLLM 作为 VLM 推理服务后端示例。IMPORTANT 本节启动的服务只负责 PaddleOCR-VL 工作流中的 VLM 推理阶段不提供完整的端到端文档解析 API。强烈不建议通过 HTTP 请求或 OpenAI 客户端直接调用该服务来处理文档图像。如需部署具备完整 PaddleOCR-VL 能力的服务请参考第 4 节服务部署。3.1 启动 VLM 推理服务DCU 上支持的启动方式启动方式状态说明官方 Docker 镜像支持按本指南操作本节给出 vLLM 服务启动步骤通过 PaddleOCR CLI 安装依赖并启动当前不支持该硬件暂不支持此路径直接用加速框架启动未验证该硬件可通过 vLLM 后端启动服务但原生 vLLM 直接启动未验证PaddleOCR 提供了用于快速启动 vLLM 推理服务的 Docker 镜像要求 Docker 19.03docker run -it \ --user root \ --privileged \ --device /dev/kfd \ --device /dev/dri \ --device /dev/mkfd \ --group-add video \ --cap-add SYS_PTRACE \ --security-opt seccompunconfined \ -v /opt/hyhal/:/opt/hyhal/:ro \ --shm-size 64g \ --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-hygon-dcu \ paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend vllm离线环境将镜像替换为ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-hygon-dcu-offline约 27 GB在线版约 25 GB。调整服务端参数启动 vLLM 推理服务时内置了一套默认参数。如需调整 GPU 显存占用等参数可参考主教程的 3.3.1 服务端参数调整 创建配置文件挂载进容器并用backend_config指定docker run -it \ --rm \ --user root \ --privileged \ --device /dev/kfd \ --device /dev/dri \ --device /dev/mkfd \ --group-add video \ --cap-add SYS_PTRACE \ --security-opt seccompunconfined \ -v /opt/hyhal/:/opt/hyhal/:ro \ -v ./vllm_config.yml:/tmp/vllm_config.yml \ --shm-size 64g \ --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-dcu \ paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend vllm --backend_config /tmp/vllm_config.ymlTIPlatest-xxx标签对应最新版本指定 PaddleOCR 版本时将latest替换为paddleocrmajor.minor例如ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:paddleocr3.3-hygon-dcu-offline。3.2 客户端使用方法客户端调用方式请参考 PaddleOCR-VL 使用教程 - 3.2 客户端使用方法。若客户端运行在本硬件上务必指定devicedcu。3.3 性能调优请参考 PaddleOCR-VL 使用教程 - 3.3 性能调优其中包含服务端参数调整如 GPU 显存占用、并发等与客户端并发控制vl_rec_max_concurrency的详细说明。4. 服务部署DCU 上支持的部署方式部署方式状态说明Docker Compose 部署支持按本指南操作见 4.1手动部署当前不支持该硬件暂不支持此路径IMPORTANT本节介绍的 PaddleOCR-VL 服务与上一节的 VLM 推理服务不同后者只负责完整流程中的一部分即 VLM 推理并作为底层服务被前者调用。4.1 使用 Docker Compose 部署Docker Compose 会依次启动两个容器底层 VLM 推理服务与 PaddleOCR-VL 服务pipeline 服务并使用 vLLM 加速 VLM 推理更适合生产环境部署。具体的 Compose 文件与镜像构建定义位于仓库 deploy/paddleocr_vl_docker/accelerators/hygon-dcu/ 目录下。具体流程下载 Compose 文件与环境变量配置文件到本地compose.yaml与.envcompose.yaml可在 deploy/paddleocr_vl_docker/accelerators/hygon-dcu/compose.yaml 查看.env文件与之一同放置。在compose.yaml与.env所在目录执行以下命令启动服务默认监听8080端口# 必须在 compose.yaml 和 .env 所在目录执行 docker compose upTIPcompose.yaml使用的镜像标签通常由.env中的API_IMAGE_TAG_SUFFIX与VLM_IMAGE_TAG_SUFFIX控制默认形如latest-hygon-dcu-offline。为确保拉取到最新的latest镜像可在docker compose up前先执行docker compose pull。 若要使用指定 PaddleOCR 版本的镜像将变量中的latest替换为paddleocrmajor.minor例如paddleocr3.3-hygon-dcu-offline。启动成功后终端会输出类似以下日志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)离线部署除拉取镜像外该方式启动后无需联网。离线环境可先在联网机器上拉取 Compose 涉及的全部镜像、导出并传输到离线机器上导入即可离线启动服务。.env文件中各环境变量的含义- API_IMAGE_TAG_SUFFIX用于启动 pipeline 服务的镜像标签后缀。 - VLM_BACKENDVLM 推理后端。 - VLM_IMAGE_TAG_SUFFIX用于启动 VLM 推理服务的镜像标签后缀。仓库中的 compose.yaml 展示了两个服务的完整定义paddleocr-vl-apipipeline 服务默认映射8080:8080通过VLM_BACKEND环境变量选择后端并执行paddlex --serve --pipeline /home/paddleocr/pipeline_config_${VLM_BACKEND}.yaml --device dcu与paddleocr-vlm-serverVLM 推理服务二者均透传 DCU 设备、只读挂载/opt/hyhal/、设置shm_size: 64g并通过 healthcheck 保证paddleocr-vl-api在 VLM 服务就绪后才启动depends_onservice_healthy。按需修改 compose.yaml1. 修改 PaddleOCR-VL 服务的端口编辑compose.yaml中的paddleocr-vl-api.ports。例如将服务端口改为 8111paddleocr-vl-api: ... ports: - - 8080:8080 - 8111:8080 ...2. 指定 PaddleOCR-VL 服务使用的 DCU 卡编辑compose.yaml中的environment。例如使用 1 号卡部署paddleocr-vl-api: ... environment: - HIP_VISIBLE_DEVICES: 1 ... paddleocr-vlm-server: ... environment: - HIP_VISIBLE_DEVICES: 1 ...3. 调整 VLM 服务端配置参照主教程 3.3.1 服务端参数调整 生成配置文件后在compose.yaml中添加paddleocr-vlm-server.volumes与paddleocr-vlm-server.command字段并将/path/to/your_config.yaml替换为实际配置路径paddleocr-vlm-server: ... volumes: /path/to/your_config.yaml:/home/paddleocr/vlm_server_config.yaml command: paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend vllm --backend_config /home/paddleocr/vlm_server_config.yaml ...4. 调整 pipeline 相关配置模型路径、batch size、部署设备等参考主教程 4.4 Pipeline 配置调整说明。仓库中的 pipeline_config_vllm.yaml 是 vLLM 后端对应的默认 pipeline 配置示例展示了batch_size、use_queues、LayoutDetection版面分析子模块模型为PP-DocLayoutV3含threshold、layout_nms、layout_unclip_ratio及按类别配置的layout_merge_bboxes_mode与VLRecognitionVLM 识别子模块model_name: PaddleOCR-VL-1.6-0.9B通过genai_config指向 vLLM 服务地址等字段的结构。4.2 客户端调用方法服务以 HTTP 接口对外提供完整文档解析能力调用方式请参考 PaddleOCR-VL 使用教程 - 4.3 客户端调用。核心接口约定如下HTTP 请求方法为 POST请求体与响应体均为 JSON。主要操作infer版面解析对应POST /layout-parsing。请求体必填字段为file图片或 PDF 的 URL或文件内容的 Base64 编码支持多页 TIFF 逐页处理可选字段包括fileType0表示 PDF1表示图片缺省时按 URL 推断、useDocOrientationClassify、useDocUnwarping、useLayoutDetection、useChartRecognition、useSealRecognition、useOcrForImageBlock、layoutThreshold、layoutNms、layoutUnclipRatio、layoutMergeBboxesMode等均与PaddleOCRVL.predict方法的同名参数对应。请求成功时响应状态码为200响应体含logId请求 UUID、errorCode固定0、errorMsg固定Success与result操作结果请求失败时errorCode与状态码一致errorMsg为错误描述。4.3 Pipeline 配置调整说明请参考 PaddleOCR-VL 使用教程 - 4.4 Pipeline 配置调整说明。核心可调项包括批量大小batch_size、是否启用内部队列use_queues对多页 PDF/大批量图片尤其有效、版面分析阈值与 NMS、VLM 服务地址与最大并发数等。5. 模型微调若在特定业务场景下 PaddleOCR-VL 的精度未达预期官方推荐使用 ERNIEKit 套件对 VLM如 PaddleOCR-VL-0.9B进行有监督微调SFT详细步骤见 ERNIEKit 官方文档中的 PaddleOCR-VL SFT 指南。当前尚不支持对版面分析与排序模型进行微调。补充从源码视角理解本指南的关键实现PaddleOCRVL类paddleocr包对外暴露的文档解析流水线入口类文档解析流水线模块位于 paddleocr/_pipelines/ 目录devicedcu等参数即在该类初始化时生效。paddleocr genai_server命令对应paddleocr包内的 CLI 入口paddleocr/_cli.py用于以指定后端--backend vllm与模型--model_name PaddleOCR-VL-1.6-0.9B启动 VLM 推理服务。Docker Compose 编排完整定义见 deploy/paddleocr_vl_docker/accelerators/hygon-dcu/compose.yaml配套的镜像构建文件pipeline.Dockerfile与vlm.Dockerfile位于同目录pipeline 服务启动命令paddlex --serve --pipeline /home/paddleocr/pipeline_config_${VLM_BACKEND}.yaml --device dcu表明其基于 PaddleX 的--serve模式对外提供 API。常见问题与注意事项务必使用完整流水线PaddleOCR-VL 的价值在于版面分析 VLM 识别的完整流水线。仅单独运行 VLM 组件例如直接用 Transformers 跑 PaddleOCR-VL-0.9B或直接向 vLLM 等服务发请求并非完整的 PaddleOCR-VL 流水线可能无法复现官方报告的精度也可能产生较多幻觉文本。若遇到上述问题请首先确认是否使用了完整流水线。设备参数DCU 上所有本地推理与客户端调用均需显式指定devicedcuCLI 为--device dcu可通过dcu:0指定具体卡号。版本要求手动安装路径下 PaddlePaddle 需为 3.2.1 及以上Python 验证范围为 3.9–3.13。镜像标签latest-xxx为最新版本离线镜像带-offline后缀指定版本用paddleocrmajor.minor替换latest。生产环境选型快速开始第 2 节仅用于验证生产环境请使用第 3 节的 VLM 推理服务或第 4 节的 Docker Compose 完整服务部署。【免费下载链接】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），仅供参考 PaddleOCR-VL Hygon DCU 部署与使用完整指南：从环境搭建到服务化推理
PaddleOCR-VL Hygon DCU 部署与使用完整指南从环境搭建到服务化推理【免费下载链接】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/PaddleOCRPaddleOCR-VL 是 PaddleOCR 推出的文档解析模型系列如 PaddleOCR-VL-1.6它通过版面分析 VLM 识别两阶段流水线将整页文档图像解析为结构化的 Markdown/JSON 结果。本指南以海光 DCUHygon K100AI为目标硬件完整覆盖从本地运行环境准备、快速开始、vLLM 加速推理服务、Docker Compose 生产级部署到模型微调的端到端流程。读完本文你将能够在海光 DCU 机器上独立搭建并调优 PaddleOCR-VL 推理环境并能根据实际业务场景选择本地直推、客户端 VLM 服务或完整 API 服务三种部署形态。说明本教程中的PaddleOCR-VL均指 PaddleOCR-VL 模型系列如 PaddleOCR-VL-1.6涉及 PaddleOCR-VL v1 专属特性时会单独注明。硬件支持概况与工作流选型PaddleOCR-VL 已在海光 K100AI 上完成精度与速度验证但由于硬件型号多样其他海光 DCU 型号的兼容性尚未确认。官方欢迎社区在不同硬件上测试并反馈结果。根据目标不同可按下表选择阅读路径各节编号与本文一致目标该硬件上的支持情况阅读章节本地直推支持第 1 节本地运行环境准备 第 2 节快速开始客户端 VLM 推理服务支持先完成本地直推再阅读第 3 节使用 VLM 推理服务完整 API 服务支持Docker Compose 部署先阅读 4.1再阅读 4.2 客户端调用与 4.3 流水线配置模型微调支持第 5 节模型微调从 PaddleOCR-VL 推理方法与硬件支持矩阵 可以看到在海光 DCU 上PaddlePaddle 推理引擎与 PaddlePaddle vLLM 组合均为 ✅ 支持状态而 Transformers 引擎及 PaddlePaddle SGLang、FastDeploy 等组合仍处于 开发或待验证状态。这意味着海光 DCU 的推荐推理路径是本地使用 PaddlePaddle 引擎直推生产环境使用 PaddlePaddle版面分析 vLLMVLM 识别的组合。1. 本地运行环境准备在 DCU 上搭建 PaddleOCR-VL 本地运行环境有两种方式本地环境搭建方式状态说明官方 Docker 镜像支持按本指南步骤操作见 1.1手动安装推理引擎与 PaddleOCR支持按本指南步骤操作见 1.2官方强烈推荐使用 Docker 镜像以最大限度规避环境相关问题。1.1 方式一使用 Docker 镜像使用官方 Docker 镜像启动容器要求 Docker 版本 19.03docker run -it \ --rm \ --user root \ --privileged \ --device /dev/kfd \ --device /dev/dri \ --device /dev/mkfd \ --group-add video \ --cap-add SYS_PTRACE \ --security-opt seccompunconfined \ -v /opt/hyhal/:/opt/hyhal/:ro \ --shm-size 64g \ --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-hygon-dcu \ /bin/bash # 在容器内调用 PaddleOCR CLI 或 Python API上述命令中的关键参数说明--device /dev/kfd、--device /dev/dri、--device /dev/mkfd将 DCU 设备节点透传进容器--group-add video加入 video 用户组以获取显卡访问权限-v /opt/hyhal/:/opt/hyhal/:ro只读挂载海光 HAL 驱动运行库Hygon HAL--shm-size 64gvLLM 等推理框架需要较大的共享内存--network host使用宿主机网络便于服务端口直连。离线环境若无外网可将镜像替换为离线版ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-hygon-dcu-offline约 24 GB在线版约 22 GB。TIPlatest-xxx标签对应最新版本若本地已有同名latest镜像且希望获取新特性或修复建议先执行docker pull。如需指定 PaddleOCR 版本可将标签中的latest替换为paddleocrmajor.minor例如ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:paddleocr3.3-hygon-dcu-offline。1.2 方式二手动安装推理引擎与 PaddleOCR无法使用 Docker 时可手动安装推理引擎与 PaddleOCR官方验证的 Python 版本范围为 3.9–3.13。需要注意该硬件上的本地推理目前仅支持 PaddlePaddle 推理引擎。强烈建议在虚拟环境中安装 PaddleOCR-VL 以避免依赖冲突例如使用 Python venv# 创建虚拟环境 python -m venv .venv_paddleocr # 激活环境 source .venv_paddleocr/bin/activate执行以下命令完成安装python -m pip install paddlepaddle-dcu3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/dcu/ python -m pip install -U paddleocr[doc-parser]注意请安装 PaddlePaddle 3.2.1 及以上版本。paddleocr[doc-parser]是 PaddleOCR-VL 所需的扩展安装项其中doc-parser提供文档解析流水线相关的依赖。2. 快速开始在 DCU 上快速开始的方式与 PaddleOCR-VL 使用教程 - 2. Quick Start 完全一致唯一区别是必须显式指定devicedcu。PaddleOCR-VL 支持 CLI 与 Python API 两种调用方式CLI 适合快速验证Python API 适合集成进现有工程。2.1 命令行使用首次运行时会自动下载官方模型文件请确保当前环境可访问外网并预留模型下载与初始化的时间。建议首次运行时加上--save_path ./output以便在本地查看保存结果# Hygon DCU paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --device dcu --save_path ./output执行成功后终端会打印结构化结果指定--save_path后结果文件会保存在当前工作目录的output目录下便于检查与调试。常用开关参数示例# 启用文档方向分类模块 paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --use_doc_orientation_classify True --save_path ./output # 启用文档矫正去弯曲模块 paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --use_doc_unwarping True --save_path ./output # 关闭版面分析与排序模块此时将仅由 VLM 直接识别整图 paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --use_layout_detection False --save_path ./output几个核心 CLI 参数的默认行为参数含义类型默认值pipeline_version指定流水线版本strv1.6可选v1、v1.5、v1.6layout_threshold版面模型置信度阈值取值 0–1float0.5layout_merge_bboxes_mode检测框合并模式large保留最外大框/small保留最内小框/union内外框均保留str由流水线初始化use_doc_orientation_classify是否启用文档方向分类boolFalseuse_doc_unwarping是否启用文档矫正boolFalseuse_layout_detection是否启用版面分析模块boolTrueuse_chart_recognition是否启用图表解析boolFalseuse_seal_recognition是否启用印章识别boolFalseuse_ocr_for_image_block是否对图片块内文字做 OCRboolFalseformat_block_content是否将block_content格式化为 MarkdownboolFalsemerge_layout_blocks是否合并跨栏/上下错落栏目的版面框boolTruemarkdown_ignore_labelsMarkdown 中需忽略的版面标签list[number,footnote,header,header_image,footer,footer_image,aside_text]use_queues是否启用内部队列异步流水boolTruedevice推理设备DCU 上为dcu或dcu:0指定卡号str默认优先 GPU 0不可用则回退 CPUlayout_shape_mode版面结果的几何表示rect/quad/poly/autostrauto说明快速开始章节的方法主要用于快速验证其推理速度、显存占用与稳定性未必满足生产环境要求。生产部署强烈建议使用专用 VLM 推理服务方法见第 3 节。2.2 Python 脚本集成在实际项目中通常通过代码集成模型仅需几行代码即可运行 PaddleOCR-VL 推理from pathlib import Path from paddleocr import PaddleOCRVL output_dir Path(./output) output_dir.mkdir(parentsTrue, exist_okTrue) # Hygon DCU指定 devicedcu pipeline PaddleOCRVL(devicedcu) # 可选项 # pipeline PaddleOCRVL(devicedcu, use_doc_orientation_classifyTrue) # 启用文档方向分类 # pipeline PaddleOCRVL(devicedcu, use_doc_unwarpingTrue) # 启用文档矫正 # pipeline PaddleOCRVL(devicedcu, use_layout_detectionFalse) # 关闭版面分析 output pipeline.predict(https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png) for res in output: res.print() # 打印结构化预测结果 res.save_to_json(save_pathoutput_dir) # 保存 JSON 结构化结果 res.save_to_markdown(save_pathoutput_dir) # 保存 Markdown 结果 res.save_to_word(save_pathoutput) # 保存 Word 结果多页 PDF 重组PDF 的每一页会被独立处理并生成独立的 Markdown 文件。若需要跨页合并表格、重建多级标题或合并多页结果使用restructure_pagesfrom pathlib import Path from paddleocr import PaddleOCRVL input_file ./your_pdf_file.pdf output_dir Path(./output) output_dir.mkdir(parentsTrue, exist_okTrue) pipeline PaddleOCRVL(devicedcu) output pipeline.predict(inputinput_file) pages_res list(output) output pipeline.restructure_pages(pages_res) # output pipeline.restructure_pages(pages_res, merge_tablesTrue) # 跨页合并表格 # output pipeline.restructure_pages(pages_res, merge_tablesTrue, relevel_titlesTrue) # 跨页合并表格 重建多级标题 # output pipeline.restructure_pages(pages_res, merge_tablesTrue, relevel_titlesTrue, concatenate_pagesTrue) # 再合并多页 for res in output: res.print() res.save_to_json(save_pathoutput_dir) res.save_to_markdown(save_pathoutput_dir)批量处理处理多个文件时推荐把目录路径或文件路径列表传给predict以最大化处理效率# imgs 目录下包含 file1.png、file2.png、file3.png output pipeline.predict(imgs) # 或传入文件路径列表 output pipeline.predict([imgs/file1.png, imgs/file2.png, imgs/file3.png]) # 以上两种方式都优于逐文件循环调用 predict3. 使用 VLM 推理服务本节介绍如何将 PaddleOCR-VL 接入独立的 VLM 推理服务后端。其核心思想是客户端继续承担版面分析等流水线其他阶段仅将 VLM 识别阶段委托给专用服务。在海光 DCU 上这通常用于在生产环境中提升推理性能。本硬件指南以 vLLM 作为 VLM 推理服务后端示例。IMPORTANT 本节启动的服务只负责 PaddleOCR-VL 工作流中的 VLM 推理阶段不提供完整的端到端文档解析 API。强烈不建议通过 HTTP 请求或 OpenAI 客户端直接调用该服务来处理文档图像。如需部署具备完整 PaddleOCR-VL 能力的服务请参考第 4 节服务部署。3.1 启动 VLM 推理服务DCU 上支持的启动方式启动方式状态说明官方 Docker 镜像支持按本指南操作本节给出 vLLM 服务启动步骤通过 PaddleOCR CLI 安装依赖并启动当前不支持该硬件暂不支持此路径直接用加速框架启动未验证该硬件可通过 vLLM 后端启动服务但原生 vLLM 直接启动未验证PaddleOCR 提供了用于快速启动 vLLM 推理服务的 Docker 镜像要求 Docker 19.03docker run -it \ --user root \ --privileged \ --device /dev/kfd \ --device /dev/dri \ --device /dev/mkfd \ --group-add video \ --cap-add SYS_PTRACE \ --security-opt seccompunconfined \ -v /opt/hyhal/:/opt/hyhal/:ro \ --shm-size 64g \ --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-hygon-dcu \ paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend vllm离线环境将镜像替换为ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-hygon-dcu-offline约 27 GB在线版约 25 GB。调整服务端参数启动 vLLM 推理服务时内置了一套默认参数。如需调整 GPU 显存占用等参数可参考主教程的 3.3.1 服务端参数调整 创建配置文件挂载进容器并用backend_config指定docker run -it \ --rm \ --user root \ --privileged \ --device /dev/kfd \ --device /dev/dri \ --device /dev/mkfd \ --group-add video \ --cap-add SYS_PTRACE \ --security-opt seccompunconfined \ -v /opt/hyhal/:/opt/hyhal/:ro \ -v ./vllm_config.yml:/tmp/vllm_config.yml \ --shm-size 64g \ --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-dcu \ paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend vllm --backend_config /tmp/vllm_config.ymlTIPlatest-xxx标签对应最新版本指定 PaddleOCR 版本时将latest替换为paddleocrmajor.minor例如ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:paddleocr3.3-hygon-dcu-offline。3.2 客户端使用方法客户端调用方式请参考 PaddleOCR-VL 使用教程 - 3.2 客户端使用方法。若客户端运行在本硬件上务必指定devicedcu。3.3 性能调优请参考 PaddleOCR-VL 使用教程 - 3.3 性能调优其中包含服务端参数调整如 GPU 显存占用、并发等与客户端并发控制vl_rec_max_concurrency的详细说明。4. 服务部署DCU 上支持的部署方式部署方式状态说明Docker Compose 部署支持按本指南操作见 4.1手动部署当前不支持该硬件暂不支持此路径IMPORTANT本节介绍的 PaddleOCR-VL 服务与上一节的 VLM 推理服务不同后者只负责完整流程中的一部分即 VLM 推理并作为底层服务被前者调用。4.1 使用 Docker Compose 部署Docker Compose 会依次启动两个容器底层 VLM 推理服务与 PaddleOCR-VL 服务pipeline 服务并使用 vLLM 加速 VLM 推理更适合生产环境部署。具体的 Compose 文件与镜像构建定义位于仓库 deploy/paddleocr_vl_docker/accelerators/hygon-dcu/ 目录下。具体流程下载 Compose 文件与环境变量配置文件到本地compose.yaml与.envcompose.yaml可在 deploy/paddleocr_vl_docker/accelerators/hygon-dcu/compose.yaml 查看.env文件与之一同放置。在compose.yaml与.env所在目录执行以下命令启动服务默认监听8080端口# 必须在 compose.yaml 和 .env 所在目录执行 docker compose upTIPcompose.yaml使用的镜像标签通常由.env中的API_IMAGE_TAG_SUFFIX与VLM_IMAGE_TAG_SUFFIX控制默认形如latest-hygon-dcu-offline。为确保拉取到最新的latest镜像可在docker compose up前先执行docker compose pull。 若要使用指定 PaddleOCR 版本的镜像将变量中的latest替换为paddleocrmajor.minor例如paddleocr3.3-hygon-dcu-offline。启动成功后终端会输出类似以下日志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)离线部署除拉取镜像外该方式启动后无需联网。离线环境可先在联网机器上拉取 Compose 涉及的全部镜像、导出并传输到离线机器上导入即可离线启动服务。.env文件中各环境变量的含义- API_IMAGE_TAG_SUFFIX用于启动 pipeline 服务的镜像标签后缀。 - VLM_BACKENDVLM 推理后端。 - VLM_IMAGE_TAG_SUFFIX用于启动 VLM 推理服务的镜像标签后缀。仓库中的 compose.yaml 展示了两个服务的完整定义paddleocr-vl-apipipeline 服务默认映射8080:8080通过VLM_BACKEND环境变量选择后端并执行paddlex --serve --pipeline /home/paddleocr/pipeline_config_${VLM_BACKEND}.yaml --device dcu与paddleocr-vlm-serverVLM 推理服务二者均透传 DCU 设备、只读挂载/opt/hyhal/、设置shm_size: 64g并通过 healthcheck 保证paddleocr-vl-api在 VLM 服务就绪后才启动depends_onservice_healthy。按需修改 compose.yaml1. 修改 PaddleOCR-VL 服务的端口编辑compose.yaml中的paddleocr-vl-api.ports。例如将服务端口改为 8111paddleocr-vl-api: ... ports: - - 8080:8080 - 8111:8080 ...2. 指定 PaddleOCR-VL 服务使用的 DCU 卡编辑compose.yaml中的environment。例如使用 1 号卡部署paddleocr-vl-api: ... environment: - HIP_VISIBLE_DEVICES: 1 ... paddleocr-vlm-server: ... environment: - HIP_VISIBLE_DEVICES: 1 ...3. 调整 VLM 服务端配置参照主教程 3.3.1 服务端参数调整 生成配置文件后在compose.yaml中添加paddleocr-vlm-server.volumes与paddleocr-vlm-server.command字段并将/path/to/your_config.yaml替换为实际配置路径paddleocr-vlm-server: ... volumes: /path/to/your_config.yaml:/home/paddleocr/vlm_server_config.yaml command: paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend vllm --backend_config /home/paddleocr/vlm_server_config.yaml ...4. 调整 pipeline 相关配置模型路径、batch size、部署设备等参考主教程 4.4 Pipeline 配置调整说明。仓库中的 pipeline_config_vllm.yaml 是 vLLM 后端对应的默认 pipeline 配置示例展示了batch_size、use_queues、LayoutDetection版面分析子模块模型为PP-DocLayoutV3含threshold、layout_nms、layout_unclip_ratio及按类别配置的layout_merge_bboxes_mode与VLRecognitionVLM 识别子模块model_name: PaddleOCR-VL-1.6-0.9B通过genai_config指向 vLLM 服务地址等字段的结构。4.2 客户端调用方法服务以 HTTP 接口对外提供完整文档解析能力调用方式请参考 PaddleOCR-VL 使用教程 - 4.3 客户端调用。核心接口约定如下HTTP 请求方法为 POST请求体与响应体均为 JSON。主要操作infer版面解析对应POST /layout-parsing。请求体必填字段为file图片或 PDF 的 URL或文件内容的 Base64 编码支持多页 TIFF 逐页处理可选字段包括fileType0表示 PDF1表示图片缺省时按 URL 推断、useDocOrientationClassify、useDocUnwarping、useLayoutDetection、useChartRecognition、useSealRecognition、useOcrForImageBlock、layoutThreshold、layoutNms、layoutUnclipRatio、layoutMergeBboxesMode等均与PaddleOCRVL.predict方法的同名参数对应。请求成功时响应状态码为200响应体含logId请求 UUID、errorCode固定0、errorMsg固定Success与result操作结果请求失败时errorCode与状态码一致errorMsg为错误描述。4.3 Pipeline 配置调整说明请参考 PaddleOCR-VL 使用教程 - 4.4 Pipeline 配置调整说明。核心可调项包括批量大小batch_size、是否启用内部队列use_queues对多页 PDF/大批量图片尤其有效、版面分析阈值与 NMS、VLM 服务地址与最大并发数等。5. 模型微调若在特定业务场景下 PaddleOCR-VL 的精度未达预期官方推荐使用 ERNIEKit 套件对 VLM如 PaddleOCR-VL-0.9B进行有监督微调SFT详细步骤见 ERNIEKit 官方文档中的 PaddleOCR-VL SFT 指南。当前尚不支持对版面分析与排序模型进行微调。补充从源码视角理解本指南的关键实现PaddleOCRVL类paddleocr包对外暴露的文档解析流水线入口类文档解析流水线模块位于 paddleocr/_pipelines/ 目录devicedcu等参数即在该类初始化时生效。paddleocr genai_server命令对应paddleocr包内的 CLI 入口paddleocr/_cli.py用于以指定后端--backend vllm与模型--model_name PaddleOCR-VL-1.6-0.9B启动 VLM 推理服务。Docker Compose 编排完整定义见 deploy/paddleocr_vl_docker/accelerators/hygon-dcu/compose.yaml配套的镜像构建文件pipeline.Dockerfile与vlm.Dockerfile位于同目录pipeline 服务启动命令paddlex --serve --pipeline /home/paddleocr/pipeline_config_${VLM_BACKEND}.yaml --device dcu表明其基于 PaddleX 的--serve模式对外提供 API。常见问题与注意事项务必使用完整流水线PaddleOCR-VL 的价值在于版面分析 VLM 识别的完整流水线。仅单独运行 VLM 组件例如直接用 Transformers 跑 PaddleOCR-VL-0.9B或直接向 vLLM 等服务发请求并非完整的 PaddleOCR-VL 流水线可能无法复现官方报告的精度也可能产生较多幻觉文本。若遇到上述问题请首先确认是否使用了完整流水线。设备参数DCU 上所有本地推理与客户端调用均需显式指定devicedcuCLI 为--device dcu可通过dcu:0指定具体卡号。版本要求手动安装路径下 PaddlePaddle 需为 3.2.1 及以上Python 验证范围为 3.9–3.13。镜像标签latest-xxx为最新版本离线镜像带-offline后缀指定版本用paddleocrmajor.minor替换latest。生产环境选型快速开始第 2 节仅用于验证生产环境请使用第 3 节的 VLM 推理服务或第 4 节的 Docker Compose 完整服务部署。【免费下载链接】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），仅供参考