PaddleOCR-VL 在 Intel Arc GPU 上的部署与使用全指南【免费下载链接】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本指南以 PaddleOCR 仓库中的 PaddleOCR-VL Intel Arc GPU 使用教程 为主体结合仓库内的 Intel Arc 加速器编排文件、环境变量配置、vLLM 服务 Dockerfile 与 产线配置文件 等源码级证据展开帮助你从零开始在 Intel Arc GPU 上跑通 PaddleOCR-VL 的文档解析能力。本教程是 PaddleOCR-VL 在 Intel Arc GPU 上的使用指南覆盖从本地运行环境准备、VLM 推理服务启动到 Docker Compose 服务化部署的完整链路并附带产线配置调整与模型微调的扩展说明。读完本文你将掌握如何在 Intel Arc GPU 上通过 vLLM 后端加速 PaddleOCR-VL 的 VLM 推理环节如何用 Docker Compose 一键部署完整的文档解析 API 服务以及如何按需调整端口、GPU 亲和性、批处理大小等关键参数。INFO除非另有说明本文提到的 PaddleOCR-VL 均指 PaddleOCR-VL 系列模型如 PaddleOCR-VL-1.6 等若特指 PaddleOCR-VL v1 版本将另行明确标注。硬件支持现状与阅读路径PaddleOCR-VL 已在 Intel Arc B60 Pro 上完成精度、速度验证鉴于硬件环境的多样性其他 Intel Arc GPU 的兼容性尚未验证欢迎社区用户在不同硬件上测试并反馈运行结果。从主教程的 推理方式与硬件支持矩阵 可以看出Intel Arc GPU 目前仅对PaddlePaddle vLLM组合路径给出✅支持而 PaddlePaddle 原生推理仍标记为适配中或待进一步验证其余组合Transformers、SGLang、FastDeploy、llama.cpp 等均为或❌。这意味着不能走本地直接推理路径当前硬件不支持在本地直接用飞桨/Transformers 跑完整 PaddleOCR-VL 流程必须依赖 vLLM 推理服务版面分析模型在客户端本地推理VLM 组件由独立的 vLLM 服务承担二者组合成完整的 客户端 VLM 推理服务 路径。不同使用目标对应不同的阅读起点请按下表导航目标本硬件上的支持情况从哪里开始阅读本地直接推理当前不支持请改走客户端 VLM 推理服务路径从第 1 节本地运行环境准备开始然后阅读第 3 节。客户端 VLM 推理服务支持从第 1 节本地运行环境准备开始然后阅读第 3 节使用 VLM 推理服务。完整 API 服务支持 Docker Compose 部署先阅读第 4.1 节再继续阅读第 4.2 节客户端调用部分和第 4.3 节产线配置调整部分。模型微调支持阅读第 5 节模型微调。1. 本地运行环境准备本地运行环境准备有两种方式任选其一即可方法一使用官方 Docker 镜像方法二手动安装推理引擎和 PaddleOCR。官方文档强烈推荐采用 Docker 镜像方式以最大程度减少可能出现的环境问题。本地运行环境准备方式状态说明官方 Docker 镜像支持并提供步骤见 1.1。手动安装推理引擎和 PaddleOCR支持并提供步骤见 1.2。1.1 方法一使用 Docker 镜像使用官方 Docker 镜像要求 Docker 版本 19.03启动容器docker run -it \ --user root \ --device /dev:/dev \ --shm-size 64g \ --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-intel-gpu \ /bin/bash # 在容器中调用 PaddleOCR CLI 或 Python API几个关键参数的含义--user root以 root 用户进入容器避免权限问题仓库中的 Dockerfile 也保留了以paddleocr普通用户运行的可选路径参见 vlm.Dockerfile--device /dev:/dev将宿主机的/dev设备目录透传给容器使容器内的 Intel Arc GPU通过 XPU 驱动暴露的设备节点可被访问--shm-size 64g为容器分配 64 GB 共享内存。VLM 推理服务与产线服务之间有大量图像数据在进程/容器间传递充足的共享内存是避免 OOM 或随机崩溃的关键--network host使用宿主机网络便于服务端口如 8080、8118直接对外暴露。离线环境说明若需在无法连接互联网的环境中启动服务请将镜像标签更换为离线版本ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-intel-gpu-offline。两者的体积差异明显在线版镜像约 31 GB离线版约 33 GB多出的部分为预置的官方模型权重。TIP标签后缀为latest-xxx的镜像对应最新版本如果本地已有旧的latest镜像但希望使用最新功能或修复建议先执行一次docker pull更新镜像。如需使用特定版本 PaddleOCR 对应的镜像可将标签中的latest替换为版本号paddleocrmajor.minor例如ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:paddleocr3.4-intel-gpu-offline。1.2 方法二手动安装推理引擎和 PaddleOCR无法使用 Docker 时可以手动安装推理引擎和 PaddleOCR。文档验证过的 Python 版本范围为3.9–3.13。需要注意的是当前硬件本地推理仅提供 PaddlePaddle 安装步骤其他推理引擎如 Transformers尚在适配验证中。强烈推荐在虚拟环境中安装避免依赖冲突例如使用 Python venv 标准库# 创建虚拟环境 python -m venv .venv_paddleocr # 激活环境 source .venv_paddleocr/bin/activate然后执行如下命令完成安装python -m pip install paddlepaddle3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ python -m pip install -U paddleocr[doc-parser]请注意安装 3.2.0 及以上版本的飞桨框架。第二条命令中的paddleocr[doc-parser]是 PaddleOCR-VL 文档解析产线所需的扩展依赖集合主教程中 x64 CPU / NVIDIA GPU 路径使用完全一致的安装命令见 PaddleOCR-VL 使用教程 1.2 节区别仅在于飞桨框架的安装源。2. 快速开始当前硬件暂不支持本地直接推理路径因此本节在 Intel Arc GPU 教程中不做展开。如需使用当前硬件加速方案请直接阅读下一节采用 vLLM 推理服务路径。作为背景补充在主教程中快速开始介绍的是paddleocr doc_parser命令行与PaddleOCRVLPython API 两种方式默认在本地用飞桨框架推理见 PaddleOCR-VL 使用教程第 2 节。这套流程在 Intel Arc GPU 上暂时不可用因此你必须把 VLM 环节外置为服务也就是下一节的内容。3. 使用 VLM 推理服务本节介绍如何通过 VLM 推理服务完成客户端 VLM 推理服务的组合路径。在当前硬件文档中示例使用vLLM作为 VLM 推理服务后端——这与硬件支持矩阵中 Intel Arc GPU 仅支持PaddlePaddle vLLM的结论完全一致。IMPORTANT按照本节说明启动的服务仅负责 PaddleOCR-VL 流程中的 VLM 推理环节不提供完整的端到端文档解析 API。强烈不建议直接通过 HTTP 请求或使用 OpenAI 客户端调用该服务处理文档图像。若你需要部署具备 PaddleOCR-VL 完整能力的服务请参考第 4 节的服务化部署部分。这是因为完整的 PaddleOCR-VL 流程 版面分析 VLM 识别两阶段协同详见 主教程开篇的流程说明单独调用 VLM 会丢失版面信息无法复现官方精度。当前硬件支持的启动方式如下启动方式状态说明官方 Docker 镜像支持并提供步骤本节提供 vLLM 推理服务的启动步骤。通过 PaddleOCR CLI 安装依赖后启动当前不支持当前硬件不支持该路径。直接使用推理加速框架启动未验证当前硬件可通过 vLLM 后端启动 VLM 推理服务但尚未验证直接使用 vLLM 原生方式启动的路径。3.1 启动 VLM 推理服务PaddleOCR 提供了官方 Docker 镜像用于快速启动 vLLM 推理服务要求 Docker 版本 19.03docker run -it \ --name paddleocr_vllm \ --user root \ --device /dev:/dev \ --shm-size 64g \ --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-intel-gpu \ paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend vllm命令拆解镜像paddleocr-genai-vllm-server:latest-intel-gpu是 vLLM 推理服务专用镜像。从 vlm.Dockerfile 可以看到它基于intel/llm-scaler-vllm:0.11.1-b7Intel 针对其硬件优化过的 vLLM 发行版并安装paddleocr3.4.0,3.5与paddlex3.4.0,3.5paddleocr genai_server是 PaddleOCR 提供的通用大模型推理服务命令--model_name PaddleOCR-VL-1.6-0.9B指定加载的 VLM 模型--host 0.0.0.0 --port 8118将服务监听在 8118 端口便于客户端访问--backend vllm显式指定使用 vLLM 后端。离线环境将镜像更换为ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-intel-gpu-offline在线版约 30 GB离线版约 32 GB。离线版镜像在构建阶段即把PaddleOCR-VL-1.6_infer模型权重预置到${HOME}/.paddlex/official_models见 vlm.Dockerfile 中BUILD_FOR_OFFLINEtrue的逻辑。自定义 vLLM 服务端参数启动服务时提供了一套默认参数。如需调整显存占用等更多参数可参考 主教程 3.3.1 服务端参数调整 创建配置文件挂载到容器中并用backend_config指定docker run -it \ --name paddleocr_vllm \ --user root \ --device /dev:/dev \ --shm-size 64g \ --network host \ -v ./vllm_config.yml:/tmp/vllm_config.yml \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-intel-gpu \ 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标签对应最新版本希望使用最新功能或修复时建议先docker pull更新。如需特定版本将latest替换为paddleocrmajor.minor例如ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:paddleocr3.4-intel-gpu-offline。3.2 客户端使用方法客户端调用方式即版面分析在本地执行、VLM 请求指向外部服务请参考 PaddleOCR-VL 使用教程 - 3.2 客户端使用方法。核心思想是在PaddleOCRVL实例化或predict调用时通过vl_rec_backend/vl_rec_server_url等参数将 VLM 组件指向本机 8118 端口的 vLLM 服务从而完成 PaddlePaddle客户端版面分析 vLLMVLM 服务 的组合。3.3 性能调优性能调优建议请参考 PaddleOCR-VL 使用教程 - 3.3 性能调优。结合产线配置文件见 pipeline_config_vllm.yaml可以看到与性能直接相关的可调项包括batch_size产线级默认 64与VLRecognition.batch_size默认 4096决定并发送入 VLM 服务的请求批量规模use_queues: True启用内部队列后数据加载如 PDF 页面渲染、版面分析处理、VLM 推理分别在独立线程中异步执行并通过队列传递数据对多页 PDF 或大量文件场景尤其高效vLLM 服务端参数如显存占用、max_model_len等通过 3.1 节的backend_config配置文件调整。4. 服务化部署服务化部署是把 PaddleOCR-VL 变成可供业务系统直接调用的完整 API 服务。当前硬件支持的部署方式如下部署方式状态说明Docker Compose 部署支持并提供步骤见 4.1。手动部署当前不支持当前硬件不支持该路径。IMPORTANT本节介绍的 PaddleOCR-VL 服务与第 3 节的 VLM 推理服务有所区别后者仅负责完整流程中的一个环节VLM 推理并作为前者的底层服务被调用。Docker Compose 方案会同时拉起这两个服务并编排好它们之间的依赖关系。4.1 使用 Docker Compose 部署此方式基于 vLLM 框架对 VLM 推理进行加速更适合生产环境部署。具体流程如下从仓库 deploy/paddleocr_vl_docker/accelerators/intel-gpu/ 目录获取compose.yaml与.env两个文件并下载到本地仓库内对应文件为 compose.yaml 与 .env在compose.yaml和.env文件所在目录下执行以下命令启动服务器默认监听 8080 端口# 必须在 compose.yaml 和 .env 文件所在的目录中执行 docker compose up提示compose.yaml中使用的镜像标签通常由.env中的API_IMAGE_TAG_SUFFIX和VLM_IMAGE_TAG_SUFFIX控制默认使用latest-intel-gpu-offline等标签。如需确保拉取到最新的latest镜像可先在当前目录执行docker compose pull再执行docker compose up。如需使用特定版本 PaddleOCR 对应的镜像可将这两个环境变量中的latest替换为版本号paddleocrmajor.minor例如paddleocr3.3-intel-gpu-offline。启动成功后paddleocr-vl-api容器将输出类似如下日志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 文件中涉及的镜像导出并传输至离线机器导入即可在离线环境下启动服务。工作原理Docker Compose 通过读取.env和compose.yaml配置先后启动 2 个容器——底层 VLM 推理服务paddleocr-vlm-server与 PaddleOCR-VL 产线服务paddleocr-vl-api。从 compose.yaml 可以看到关键编排细节paddleocr-vl-api通过depends_on等待paddleocr-vlm-server的service_healthy健康检查通过后才启动避免产线服务先于 VLM 服务就绪产线服务以paddlex --serve --pipeline /home/paddleocr/pipeline_config_${VLM_BACKEND}.yaml启动其中${VLM_BACKEND}默认由.env提供为vllm对应加载 pipeline_config_vllm.yaml该产线配置中VLRecognition.genai_config设置为backend: vllm-server、server_url: http://paddleocr-vlm-server:8080/v1即产线服务通过 Compose 内部 DNS 名称访问 VLM 服务两个容器都配置了devices: /dev:/dev、shm_size: 64g、user: root与restart: unless-stopped。.env文件中包含的环境变量含义如下仓库内实际内容见 .envAPI_IMAGE_TAG_SUFFIX启动产线服务使用的镜像的标签后缀默认latest-intel-gpu-offlineVLM_BACKENDVLM 推理后端默认vllmVLM_IMAGE_TAG_SUFFIX启动 VLM 推理服务使用的镜像的标签后缀默认latest-intel-gpu-offline。自定义 Compose 配置示例1. 更改 PaddleOCR-VL 服务的端口编辑compose.yaml中的paddleocr-vl-api.ports来更改端口。例如将服务端口更换为 8111paddleocr-vl-api: ... ports: - - 8080:8080 - 8111:8080 ...2. 指定 PaddleOCR-VL 服务所使用的 GPU编辑compose.yaml中的environment来更改所使用的 GPU。例如使用卡 1 进行部署paddleocr-vl-api: ... environment: - XPU_AFFINITY_MASK: 1 ... paddleocr-vlm-server: ... environment: - XPU_AFFINITY_MASK: 1 ...Intel Arc GPU 在容器中以 XPU 设备形式暴露XPU_AFFINITY_MASK用于指定容器内可用的设备序号需要同时为产线服务与 VLM 服务设置保证二者使用同一张卡。3. 调整 VLM 服务端配置参考 主教程 3.3.1 服务端参数调整 生成配置文件后将以下paddleocr-vlm-server.volumes和paddleocr-vlm-server.command字段增加到你的compose.yaml中。请将/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. 调整产线相关配置如模型路径、批处理大小、部署设备等参考 主教程 4.4 产线配置调整说明见本文 4.3 节。4.2 客户端调用方式客户端调用方式请参考 PaddleOCR-VL 使用教程 - 4.3 客户端调用方式。服务化部署完成后业务系统通过 HTTP 请求访问 8080 端口或你自定义的端口上传图像/PDF 并获取结构化解析结果JSON / Markdown 等。4.3 产线配置调整说明NOTE若无需调整产线配置可忽略本小节。调整服务化部署的 PaddleOCR-VL 配置只需三步获取配置文件 → 修改配置文件 → 应用配置文件。4.3.1 获取配置文件使用 Docker Compose 部署时根据后端下载对应的产线配置文件仓库内已提供vLLMpipeline_config_vllm.yamlFastDeploypipeline_config_fastdeploy.yaml。若是手动部署路径可执行以下命令生成产线配置文件paddlex --get_pipeline_config PaddleOCR-VL4.3.2 修改配置文件使用加速框架提升 VLM 推理性能如需使用 vLLM 等加速框架提升 VLM 推理性能可在产线配置文件中修改VLRecognition.genai_config.backend和VLRecognition.genai_config.server_url字段例如VLRecognition: ... genai_config: backend: vllm-server server_url: http://localhost:8118/v1Docker Compose 方案默认已使用加速框架pipeline_config_vllm.yaml 中server_url指向http://paddleocr-vlm-server:8080/v1。启用文档图像预处理功能默认配置启动的服务不支持文档预处理功能客户端调用该功能将返回错误信息。如需启用将use_doc_preprocessor设置为True并使用修改后的配置启动服务。该字段控制DocPreprocessor子产线文档方向分类PP-LCNet_x1_0_doc_ori与文本图像矫正UVDoc是否启用两个子模型默认均开启内部开关见 pipeline_config_vllm.yaml。禁用结果可视化功能服务默认返回可视化结果这会引入额外开销。如需禁用在产线配置文件中添加如下配置Serving为顶层字段Serving: visualize: False此外也可在请求体中设置visualize字段为false针对单次请求禁用可视化。配置以 URL 形式返回二进制内容服务默认以 Base64 编码内联返回响应中的图像等二进制内容。如需改为 URL 形式返回可添加如下配置Serving为顶层字段Serving: return_urls: True extra: file_storage: type: bos endpoint: https://bj.bcebos.com bucket_name: some-bucket ak: xxx sk: xxx key_prefix: deploy url_expires_in: 3600目前支持将生成的文件存储至百度智能云对象存储BOS并返回 URL参数说明如下endpoint访问域名必须配置ak/sk百度智能云 AK/SK必须配置bucket_name存储空间名称必须配置key_prefixObject key 的统一前缀connection_timeout_in_mills请求超时时间单位毫秒url_expires_inURL 有效期单位秒-1表示永不过期。限制 PDF 与多页 TIFF 解析页数服务默认处理完整的 PDF 文件多页 TIFFfileType1会按页展开后逐页处理。生产环境中页数过多可能影响稳定性导致超时或资源占用过高建议设置页数上限Serving: extra: max_num_input_imgs: 页数限制例如 100max_num_input_imgs同时限制 PDF 与多页 TIFF 的最大处理页数设置为null时不限制pipeline_config_vllm.yaml 默认即为null。4.3.3 应用配置文件使用 Docker Compose 部署时设置 Compose 文件中services.paddleocr-vl-api.volumes字段将产线配置文件挂载到/home/paddleocr目录services: paddleocr-vl-api: ... volumes: - ./pipeline_config_vllm.yaml:/home/paddleocr/pipeline_config_vllm.yaml ...在生产环境中也可以自行构建镜像将配置文件打包进镜像。手动部署时则在启动服务时用--pipeline参数指定自定义配置文件路径。5. 模型微调若 PaddleOCR-VL 在特定业务场景中的精度表现未达预期推荐使用 ERNIEKit 套件对视觉语言模型例如 PaddleOCR-VL-0.9B进行有监督微调SFT具体操作步骤参考 ERNIEKit 官方文档中的paddleocr_vl_sft说明。目前暂不支持对版面分析排序模型进行微调。6. 仓库资源速查以下是本文涉及的核心仓库文件便于继续深入阅读与二次开发用途仓库相对路径Intel Arc GPU 使用教程本文主体docs/version3.x/pipeline_usage/PaddleOCR-VL-Intel-Arc-GPU.mdPaddleOCR-VL 主教程含硬件支持矩阵、参数表、微调说明docs/version3.x/pipeline_usage/PaddleOCR-VL.mdIntel Arc GPU Compose 编排文件deploy/paddleocr_vl_docker/accelerators/intel-gpu/compose.yamlIntel Arc GPU 环境变量配置deploy/paddleocr_vl_docker/accelerators/intel-gpu/.envvLLM 服务镜像构建文件deploy/paddleocr_vl_docker/accelerators/intel-gpu/vlm.Dockerfile产线镜像构建文件deploy/paddleocr_vl_docker/accelerators/intel-gpu/pipeline.DockerfilevLLM 后端产线配置文件deploy/paddleocr_vl_docker/pipeline_config_vllm.yamlFastDeploy 后端产线配置文件deploy/paddleocr_vl_docker/pipeline_config_fastdeploy.yaml总结在 Intel Arc GPU 上使用 PaddleOCR-VL 的关键要点可以概括为三条一是明确硬件边界——当前仅PaddlePaddle vLLM路径受支持因此本地直接推理和手动部署在 Intel Arc 上暂不可用二是用好官方 Docker 生态——从单容器的 vLLM 推理服务第 3 节到双容器的 Docker Compose 完整 API 服务第 4 节官方镜像已针对 Intel 硬件完成验证与优化离线镜像还预置了模型权重可平滑支撑内网环境三是善用配置化调优——端口、GPU 亲和性XPU_AFFINITY_MASK、VLM 服务端参数、产线批处理与页数限制等均可通过compose.yaml、.env与产线 YAML 声明式调整。如果你手头恰好有一块 Intel Arc GPU按本文第 1 → 3 → 4 节的路径即可快速跑通从单机验证到生产部署的完整链路。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考