PaddleOCR-VL 昆仑芯 XPU 部署与推理实战：从环境准备到服务化部署完整指南-开发者社区

PaddleOCR-VL 昆仑芯 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

PaddleOCR-VL 是 PaddleOCR 面向文档智能解析推出的视觉语言模型系列，采用"版面分析 + VLM 识别"两阶段流程，将图像与 PDF 文档转化为可供 LLM 直接消费的结构化数据。本文以 PaddleOCR 官方昆仑芯 XPU 使用教程为核心，完整讲解在昆仑芯 P800 等 XPU 设备上从本地环境准备、命令行/Python 快速推理、FastDeploy VLM 推理服务，到 Docker Compose 服务化部署与产线配置调整的端到端流程，并辅以仓库源码（Dockerfile、compose.yaml、产线配置）进行底层印证。读完本文，你将掌握在昆仑芯 XPU 上完整落地 PaddleOCR-VL 文档解析能力的每一步操作。

硬件支持范围与阅读路径

PaddleOCR-VL 已在昆仑芯 P800上完成精度与速度验证；鉴于硬件环境的多样性，其他昆仑芯 XPU 型号的兼容性尚未验证，欢迎社区用户在更多硬件上测试并反馈结果。在昆仑芯 XPU 上，可使用的推理方式与目标如下：

目标	本硬件上的支持情况	从哪里开始阅读
本地直接推理	支持	阅读第 1 节"本地运行环境准备"和第 2 节"快速开始"。
客户端 + VLM 推理服务	支持	先完成本地直接推理，再阅读第 3 节"使用 VLM 推理服务"。
完整 API 服务	支持 Docker Compose 部署	先阅读第 4.1 节，再继续阅读第 4.2 节客户端调用部分和第 4.3 节产线配置调整部分。
模型微调	支持	阅读第 5 节"模型微调"。

从主教程的推理方式与硬件支持矩阵可以看到，昆仑芯 XPU 上PaddlePaddle与PaddlePaddle + FastDeploy两种推理方式为"✅ 支持"状态，而 Transformers、vLLM、SGLang 等路径在 XPU 上均为"🚧 适配中或待进一步验证"。因此本文所有示例均围绕 PaddlePaddle 引擎与 FastDeploy 后端展开，与仓库中昆仑芯专用镜像（latest-kunlunxin-xpu系列）的定位完全一致。

需要特别强调的是：PaddleOCR-VL 的完整能力必须依赖"版面分析 + VLM 识别"协同的完整流程，单独调用 VLM 组件（例如直接请求 vLLM / FastDeploy 服务的裸接口）并不等于运行 PaddleOCR-VL，这一点在主教程中有明确说明，后续章节会反复涉及这一概念。

1. 本地运行环境准备

昆仑芯 XPU 本地运行环境有两种准备方式，任选一种即可：

本地运行环境准备方式	状态	说明
官方 Docker 镜像	支持并提供步骤	见 1.1 节。
手动安装推理引擎和 PaddleOCR	支持并提供步骤	见 1.2 节。

官方强烈推荐采用 Docker 镜像方式，以最大程度减少环境问题。注意：昆仑芯 XPU 本地推理仅支持 PaddlePaddle 推理引擎。

1.1 方法一：使用 Docker 镜像

要求 Docker 版本 >= 19.03，执行以下命令启动 PaddleOCR-VL 运行环境：

docker run \ -it \ --network host \ --user root \ --privileged \ --shm-size 64g \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-kunlunxin-xpu \ /bin/bash # 在容器中调用 PaddleOCR CLI 或 Python API

参数要点说明：

--network host：使用宿主机网络，便于容器内服务被外部访问；
--privileged与--shm-size 64g：XPU 设备访问与共享内存所需，VLM 推理对共享内存有较高要求；
latest-kunlunxin-xpu：对应最新版本的在线镜像，大小约13 GB。

如需在无法连接互联网的环境中启动服务，请将镜像更换为离线版本ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-kunlunxin-xpu-offline（大小约15 GB，镜像内已内置 PaddleOCR-VL 所需模型与字体资源）。

镜像标签约定（TIP）
标签后缀为latest-xxx的镜像对应最新版本；
若本地已有同名latest镜像，但希望使用最新功能或修复，建议先重新执行docker pull更新镜像；
如需特定版本，可将latest替换为版本号paddleocr<major>.<minor>，例如ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:paddleocr3.3-kunlunxin-xpu-offline。

从仓库中的昆仑芯镜像构建文件 pipeline.Dockerfile 可以看到官方镜像的构成逻辑：基础镜像基于device/paddle-xpu:ubuntu20-x86_64-gcc84-py310，先安装paddlepaddle-xpu==3.2.1（来源为飞桨官方 xpu-p800 稳定源），再安装paddleocr[doc-parser]与paddlex[serving]，并预置中文字体（fonts-noto-cjk、fonts-wqy-microhei等）以及离线模式下预下载的 UVDoc、PP-LCNet_x1_0_doc_ori、PP-DocLayoutV3、PaddleOCR-VL-1.6 四个模型包。这解释了为什么离线镜像体积更大却能在断网环境中直接运行。

1.2 方法二：手动安装推理引擎和 PaddleOCR

若无法使用 Docker，可手动安装。本文档验证过的 Python 版本范围为3.9–3.13，且强烈建议在虚拟环境中安装以避免依赖冲突：

# 创建虚拟环境 python -m venv .venv_paddleocr # 激活环境 source .venv_paddleocr/bin/activate

执行如下命令完成安装：

python -m pip install paddlepaddle-xpu==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/xpu-p800/ python -m pip install -U "paddleocr[doc-parser]"

请注意安装 3.2.1 及以上版本的飞桨框架。该版本号与仓库 pipeline.Dockerfile 及 vlm.Dockerfile 中锁定的paddlepaddle-xpu==3.2.1完全一致，这也是 XPU 上已验证可用的最低版本要求。paddleocr[doc-parser]额外引入文档解析所需的依赖集合，其中包含 PaddleOCR-VL 产线的核心功能包。

2. 快速开始

PaddleOCR-VL 在昆仑芯 XPU 上的快速开始与主教程一致，唯一区别是必须显式指定device="xpu"。

2.1 CLI 命令行体验

首次运行会自动下载官方模型，请确保环境可联网并预留下载与初始化时间。建议附加--save_path ./output便于在本地查看结果：

# 昆仑芯 XPU paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --device xpu --save_path ./output

执行成功后，终端会打印结构化结果，同时结果文件保存到当前目录output中。doc_parser命令支持丰富的调节参数，其中与 XPU 推理强相关的关键参数包括：

--device：指定推理设备，XPU 写法为xpu或带卡号的xpu:0（表示第 1 块 XPU）；不设置时默认优先使用本地 GPU 0 号设备，无 GPU 则回退 CPU；
--use_doc_orientation_classify True：启用文档方向分类模块（默认关闭）；
--use_doc_unwarping True：启用文本图像矫正模块（默认关闭）；
--use_layout_detection False：关闭版面分析模块（默认开启）。注意：关闭后仅执行 VLM 识别，不构成完整 PaddleOCR-VL 流程；
--use_chart_recognition/--use_seal_recognition：图表解析与印章识别开关（默认关闭）；
--layout_threshold：版面模型得分阈值，取0-1浮点数；
--layout_unclip_ratio：版面检测框扩张系数，支持浮点数或横纵两个方向的扩张系数；
--layout_merge_bboxes_mode：重叠检测框过滤模式，large保留外框、small保留内框、union全部保留；
--layout_shape_mode：版面结果几何形状表示模式，rect/quad/poly/auto（默认auto）；
--use_queues：是否启用内部队列异步流水线（默认开启），对页数较多的 PDF 或大量文件的目录处理效率提升明显；
--engine：推理引擎，XPU 场景使用默认值（等价于paddle）即可，支持paddle_static/paddle_dynamic等取值，详见推理引擎与配置说明。

2.2 Python 脚本方式集成

在项目中集成时，通过PaddleOCRVL对象完成推理，初始化时传入device="xpu"：

from pathlib import Path from paddleocr import PaddleOCRVL output_dir = Path("./output") output_dir.mkdir(parents=True, exist_ok=True) # 昆仑芯 XPU pipeline = PaddleOCRVL(device="xpu") # 可选功能开关示例： # pipeline = PaddleOCRVL(device="xpu", use_doc_orientation_classify=True) # pipeline = PaddleOCRVL(device="xpu", use_doc_unwarping=True) # pipeline = PaddleOCRVL(device="xpu", use_layout_detection=False) 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_path=output_dir) # 保存 JSON 结果 res.save_to_markdown(save_path=output_dir) # 保存 Markdown 结果 res.save_to_word(save_path=output_dir) # 保存 Word 结果

针对多页 PDF，可以逐页推理后调用restructure_pages()完成跨页表格合并、多级标题重建与多页结果拼接：

input_file = "./your_pdf_file.pdf" pipeline = PaddleOCRVL(device="xpu") output = pipeline.predict(input=input_file) pages_res = list(output) # 合并跨页表格 # output = pipeline.restructure_pages(pages_res, merge_tables=True) # 合并跨页表格，重建多级标题 # output = pipeline.restructure_pages(pages_res, merge_tables=True, relevel_titles=True) # 合并跨页表格，重建多级标题，合并多页结果为一页 output = pipeline.restructure_pages(pages_res, merge_tables=True, relevel_titles=True, concatenate_pages=True) for res in output: res.print() res.save_to_json(save_path=output_dir) res.save_to_markdown(save_path=output_dir)

处理多个文件时，建议将包含文件的目录路径或文件路径列表传入predict以最大化处理效率：

# 传入目录路径 output = pipeline.predict("imgs") # 或传入文件路径列表 output = pipeline.predict(["imgs/file1.png", "imgs/file2.png", "imgs/file3.png"])

PaddleOCRVL对象的关键构造参数（XPU 场景常用）说明如下：

参数	说明	类型	默认值
`pipeline_version`	产线版本，可选`"v1"`、`"v1.5"`、`"v1.6"`	`str`	`"v1.6"`
`layout_detection_model_name`/`layout_detection_model_dir`	版面分析模型名称 / 目录，为`None`时下载官方模型	`str\\|None`	`None`
`vl_rec_model_name`/`vl_rec_model_dir`	多模态识别（VLM）模型名称 / 目录	`str\\|None`	`None`
`use_doc_orientation_classify`	是否启用文档方向分类	`bool\\|None`	`None`（初始化为`False`）
`use_doc_unwarping`	是否启用文本图像矫正	`bool\\|None`	`None`（初始化为`False`）
`use_layout_detection`	是否启用版面分析	`bool\\|None`	`None`（初始化为`True`）
`use_chart_recognition`/`use_seal_recognition`	图表解析 / 印章识别开关	`bool\\|None`	`None`（初始化为`False`）
`device`	推理设备，XPU 写法为`xpu`或`xpu:0`	`str\\|None`	`None`
`use_queues`	是否启用内部队列异步流水线	`bool\\|None`	`None`（初始化为`True`）

predict()方法的参数与实例化参数含义基本一致，调用时传参优先级更高；此外还支持repetition_penalty、temperature、top_p、min_pixels、max_pixels、max_new_tokens等 VLM 采样与图像分辨率控制参数，以及vlm_extra_args（可针对 OCR / 表格 / 图表 / 公式 / 印章分别设置min_pixels/max_pixels分辨率范围）。

提示：CLI 与 Python API 方式主要用于快速验证，其推理速度、显存占用及稳定性未必满足生产要求。生产环境强烈建议使用专门的 VLM 推理服务，即下一节内容。

3. 使用 VLM 推理服务

对于昆仑芯 XPU，通过 VLM 推理服务接入专用后端可以提升默认配置下的推理性能，更好地满足生产需求。示例使用FastDeploy作为 VLM 推理服务后端（与昆仑芯镜像paddleocr-genai-fastdeploy-server:latest-kunlunxin-xpu的定位一致）。

IMPORTANT：本节启动的服务仅负责 PaddleOCR-VL 流程中的VLM 推理环节，不提供完整的端到端文档解析 API。强烈不建议直接通过 HTTP 请求或 OpenAI 客户端调用该服务处理文档图像。若需部署具备 PaddleOCR-VL 完整能力的服务，请阅读第 4 节"服务化部署"。

3.1 启动 VLM 推理服务

昆仑芯 XPU 上支持的启动方式如下：

启动方式	状态	说明
官方 Docker 镜像	支持并提供步骤	本节提供 FastDeploy 推理服务的启动步骤。
通过 PaddleOCR CLI 安装依赖后启动	当前不支持	当前硬件不支持该路径。
直接使用推理加速框架启动	未验证	可通过 FastDeploy 后端启动，但尚未验证直接使用 FastDeploy 原生方式启动。

使用官方 Docker 镜像启动 FastDeploy 推理服务（要求 Docker 版本 >= 19.03）：

docker run \ -it \ --network host \ --user root \ --privileged \ --shm-size 64g \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-fastdeploy-server:latest-kunlunxin-xpu \ paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend fastdeploy

离线环境请将镜像更换为ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-fastdeploy-server:latest-kunlunxin-xpu-offline（在线镜像约 53 GB，离线镜像约 55 GB）。版本固定镜像示例：paddleocr-genai-fastdeploy-server:paddleocr3.3-kunlunxin-xpu-offline。

若需调整服务端参数（如显存占用），请按主教程 3.3.1 服务端参数调整创建配置文件，挂载进容器并用--backend_config指定：

docker run \ -it \ --rm \ --network host \ --user root \ --privileged \ --shm-size 64G \ -v ./fastdeploy_config.yml:/tmp/fastdeploy_config.yml \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-fastdeploy-server:latest-kunlunxin-xpu \ paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend fastdeploy --backend_config /tmp/fastdeploy_config.yml

paddleocr genai_server命令支持--model_name（模型名称）、--model_dir（模型目录）、--host（主机名）、--port（端口）、--backend（后端，可选vllm/sglang/fastdeploy）、--backend_config（YAML 后端配置文件）等参数。从仓库 vlm.Dockerfile 可以看到，昆仑芯 VLM 服务镜像基于fastdeploy-xpu:2.3.0，安装fastdeploy_xpu与paddlepaddle_xpu专用 wheel 后，容器默认 CMD 即执行paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8080 --backend fastdeploy。

3.2 客户端使用方法

客户端调用方式与主教程 3.2 客户端使用方法一致，在昆仑芯 XPU 上运行客户端时需指定device="xpu"。

核心思路是：客户端继续负责版面分析等完整流程中的其他环节，仅将 VLM 推理交给专用服务处理。通过vl_rec_backend指定后端类型（本硬件使用fastdeploy-server），通过vl_rec_server_url指定服务地址：

paddleocr doc_parser --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png \ --device xpu \ --vl_rec_backend fastdeploy-server \ --vl_rec_server_url http://localhost:8118/v1

Python API 方式：

pipeline = PaddleOCRVL(device="xpu", vl_rec_backend="fastdeploy-server", vl_rec_server_url="http://localhost:8118/v1")

如需指定服务端模型名称与鉴权信息，可追加vl_rec_api_model_name与vl_rec_api_key参数。

3.3 性能调优

性能调优请参考主教程 3.3 性能调优，核心手段包括：

服务端参数调整：通过--backend_config传入 YAML 配置文件调整 FastDeploy 的显存占用、并发等参数；
客户端并发调整：PaddleOCR 会将来自单张或多张输入图像中的子图分组并对服务器发起并发请求，因此并发数对性能影响显著。CLI 与 Python API 通过vl_rec_max_concurrency调整最大并发请求数；服务化部署则修改产线配置中VLRecognition.genai_config.max_concurrency字段。当客户端与 VLM 服务为 1 对 1 且服务端资源充足时可适当增大并发，反之应降低并发以避免资源过载。

4. 服务化部署

服务化部署将 PaddleOCR-VL 以完整 API 服务的形式对外提供。注意本节服务与上一节的 VLM 推理服务有本质区别：VLM 推理服务只负责完整流程中的一个环节（VLM 推理），并作为本节服务的底层服务被调用。

昆仑芯 XPU 支持的部署方式：

部署方式	状态	说明
Docker Compose 部署	支持并提供步骤	见 4.1 节。
手动部署	当前不支持	当前硬件不支持该路径。

4.1 使用 Docker Compose 部署

首先从仓库获取 Compose 文件与环境变量配置文件：

Compose 文件：deploy/paddleocr_vl_docker/accelerators/kunlunxin-xpu/compose.yaml
环境变量文件：deploy/paddleocr_vl_docker/accelerators/kunlunxin-xpu/.env

将两个文件下载到同一目录后执行（必须在 compose.yaml 和 .env 所在目录执行），默认监听8080端口：

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 CTRL+C to quit)

部署原理与镜像编排

该方案基于 FastDeploy 框架对 VLM 推理进行加速，更适合生产环境部署。Docker Compose 通过读取.env和compose.yaml，先后启动 2 个容器：paddleocr-vlm-server（底层 VLM 推理服务）与paddleocr-vl-api（PaddleOCR-VL 产线服务）。

从仓库 compose.yaml 源码可以看到两个关键细节：

paddleocr-vl-api使用depends_on+condition: service_healthy确保 VLM 服务健康后再启动产线服务；
产线服务的启动命令为paddlex --serve --pipeline /home/paddleocr/pipeline_config_${VLM_BACKEND}.yaml --device xpu，其中${VLM_BACKEND}来自.env，即产线配置文件名随后端动态切换。

仓库中的 .env 默认内容为：

API_IMAGE_TAG_SUFFIX=latest-kunlunxin-xpu-offline VLM_BACKEND=fastdeploy VLM_IMAGE_TAG_SUFFIX=latest-kunlunxin-xpu-offline

.env中各环境变量含义：

API_IMAGE_TAG_SUFFIX：启动产线服务使用的镜像的标签后缀；
VLM_BACKEND：VLM 推理后端；
VLM_IMAGE_TAG_SUFFIX：启动 VLM 推理服务使用的镜像的标签后缀。

提示：镜像标签默认使用latest-kunlunxin-xpu-offline等离线标签。如需确保拉取到最新latest镜像，可先执行docker compose pull再docker compose up；如需特定版本，可将两个后缀中的latest替换为paddleocr<major>.<minor>，例如paddleocr3.3-kunlunxin-xpu-offline。

离线部署说明

除拉取镜像外，此方式启动服务器后无需连接互联网。若需在离线环境中部署，可先在联网机器上拉取 Compose 涉及的镜像，导出并传输至离线机器导入，即可在离线环境启动服务。

常见自定义修改

1. 更改 PaddleOCR-VL 服务的端口

编辑compose.yaml中paddleocr-vl-api.ports。例如将服务端口更换为 8111：

paddleocr-vl-api: ... ports: - - 8080:8080 + - 8111:8080 ...

2. 指定服务所使用的 XPU

编辑compose.yaml中两个服务的environment。例如使用卡 1 进行部署：

paddleocr-vl-api: ... environment: + - XPU_VISIBLE_DEVICES: 1 ... paddleocr-vlm-server: ... environment: + - XPU_VISIBLE_DEVICES: 1 ...

3. 调整 VLM 服务端配置

参考主教程 3.3.1 服务端参数调整生成配置文件后，在compose.yaml中增加paddleocr-vlm-server的volumes与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 fastdeploy --backend_config /home/paddleocr/vlm_server_config.yaml ...

4. 调整产线相关配置（模型路径、批处理大小、部署设备等）

参考主教程 4.4 产线配置调整说明（本文 4.3 节亦有摘要）。

4.2 客户端调用方式

服务化部署的客户端调用方式（含 API 参考与多语言调用示例）与主教程 4.3 客户端调用方式一致。核心接口如下：

POST /layout-parsing：进行版面解析（infer），请求体支持file（图像/PDF 的 URL 或 Base64 编码内容）、fileType（0 表示 PDF，1 表示图像含 TIFF）、useLayoutDetection、layoutThreshold、promptLabel、temperature、minPixels/maxPixels、maxNewTokens、prettifyMarkdown、restructurePages、outputFormats（当前仅支持"docx"）、visualize等字段；
POST /restructure-pages：重构多页结果，请求体支持pages、mergeTables、relevelTitles、concatenatePages等字段。

请求成功时响应体包含logId、errorCode（固定 0）、errorMsg（固定 "Success"）与result字段；result.layoutParsingResults中每个元素包含prunedResult、markdown（含text与images）、outputImages、inputImage、exports等字段，图像类二进制内容默认以 Base64 内联返回。Python 调用最小示例：

import base64 import requests BASE_URL = "http://localhost:8080" image_path = "./demo.jpg" with open(image_path, "rb") as file: image_data = base64.b64encode(file.read()).decode("ascii") payload = { "file": image_data, # Base64 编码的文件内容或者文件 URL "fileType": 1, # 文件类型，1 表示图像文件 } response = requests.post(BASE_URL + "/layout-parsing", json=payload) assert response.status_code == 200, (response.status_code, response.text) result = response.json()["result"]

4.3 产线配置调整说明

服务化部署的 PaddleOCR-VL 产线配置调整只需三步：获取配置文件 → 修改配置文件 → 应用配置文件。若无需调整可忽略本节。

获取配置文件

Docker Compose 部署时，根据后端下载对应的产线配置文件：

FastDeploy：deploy/paddleocr_vl_docker/pipeline_config_fastdeploy.yaml（昆仑芯 XPU 场景）
vLLM：deploy/paddleocr_vl_docker/pipeline_config_vllm.yaml

以仓库 pipeline_config_fastdeploy.yaml 为例，其顶层关键字段包括：

pipeline_name: PaddleOCR-VL-1.6：产线名称；
batch_size: 64与use_queues: True：批量大小与内部队列异步流水线；
use_doc_preprocessor: False、use_layout_detection: True、use_chart_recognition: False、use_seal_recognition: False、format_block_content: False、merge_layout_blocks: True：各功能模块开关；
markdown_ignore_labels：Markdown 中忽略的版面标签，默认忽略number、footnote、header、header_image、footer、footer_image、aside_text；
SubModules.LayoutDetection：版面分析模型配置（model_name: PP-DocLayoutV3、threshold: 0.3、layout_nms: True、layout_unclip_ratio: [1.0, 1.0]、按类别区分的layout_merge_bboxes_mode字典）；
SubModules.VLRecognition：VLM 识别配置（model_name: PaddleOCR-VL-1.6-0.9B、batch_size: 4096，以及genai_config.backend: fastdeploy-server、genai_config.server_url: http://paddleocr-vlm-server:8080/v1——注意 Compose 部署下客户端通过容器服务名访问底层 VLM 服务）；
SubPipelines.DocPreprocessor：文档预处理子产线（文档方向分类 PP-LCNet_x1_0_doc_ori + 图像矫正 UVDoc，默认未启用）；
Serving.extra.max_num_input_imgs: null：PDF 与多页 TIFF 的最大处理页数限制。

常用修改项

加速 VLM 推理：可在产线配置中修改VLRecognition.genai_config.backend与server_url字段指向自建 VLM 服务；Docker Compose 方案默认已使用加速框架。

启用文档图像预处理：默认配置启动的服务不支持文档预处理功能，若客户端调用会返回错误。如需启用，将use_doc_preprocessor设为True并使用修改后的配置重启服务。

禁用结果可视化：服务默认返回可视化结果（有额外开销），可在配置顶层添加：

Serving: visualize: False

也可在单次请求体中将visualize设为false。

以 URL 形式返回二进制内容：默认图像等二进制内容以 Base64 内联返回，如需改为 URL 形式（目前支持百度智能云 BOS），在配置顶层添加：

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

其中endpoint、ak、sk、bucket_name为必填；url_expires_in为 URL 有效期（秒），-1表示永不过期。

限制 PDF 与多页 TIFF 解析页数：为避免页数过多导致超时或资源占用过高，可限制最大处理页数：

Serving: extra: max_num_input_imgs: 100 # 同时限制 PDF 与多页 TIFF；设为 null 表示不限制

应用配置文件

Docker Compose 部署时，设置compose.yaml中services.paddleocr-vl-api.volumes，将产线配置挂载到/home/paddleocr目录：

services: paddleocr-vl-api: ... volumes: - ./pipeline_config_fastdeploy.yaml:/home/paddleocr/pipeline_config_fastdeploy.yaml ...

生产环境中也可自行构建镜像，将配置文件打包进镜像。

5. 模型微调

若 PaddleOCR-VL 在特定业务场景中的精度表现未达预期，推荐使用ERNIEKit 套件对视觉语言模型（如 PaddleOCR-VL-0.9B）进行有监督微调（SFT），具体操作步骤请参考主教程 5. 模型微调所引用的 ERNIEKit 官方文档。目前暂不支持对版面分析排序模型进行微调。

总结

在昆仑芯 XPU 上使用 PaddleOCR-VL 的核心要点可归纳为四条主线：

环境准备：优先使用官方 Docker 镜像（在线latest-kunlunxin-xpu约 13 GB / 离线-offline约 15 GB），手动安装则需 Python 3.9–3.13 +paddlepaddle-xpu>=3.2.1+paddleocr[doc-parser]；
本地推理：CLI 与 Python API 均需显式指定device="xpu"，且务必使用完整的"版面分析 + VLM 识别"流程，不要绕过版面分析单独调用 VLM；
生产提速：通过 FastDeploy 后端镜像（paddleocr-genai-fastdeploy-server:latest-kunlunxin-xpu，约 53 GB）启动 VLM 推理服务，客户端以vl_rec_backend=fastdeploy-server接入；
服务化部署：以docker compose up一键拉起 VLM 服务 + 产线服务双容器，默认监听 8080 端口，通过.env控制镜像标签与后端，通过产线配置文件（pipeline_config_fastdeploy.yaml）精细化调整批处理、功能开关、并发与页数限制。