PaddleOCR-VL 天数 GPU 部署实战：环境准备、FastDeploy 推理服务与 Docker Compose 服务化部署全指南-酒店常州论坛

PaddleOCR-VL 天数 GPU 部署实战：环境准备、FastDeploy 推理服务与 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

本篇技术指南以 PaddleOCR 官方《PaddleOCR-VL 天数 GPU 使用教程》为核心，系统讲解 PaddleOCR-VL 系列模型（如 PaddleOCR-VL-1.6）在天数（Iluvatar）GPU 上的完整落地路径。读完本文，你将掌握四件事：如何通过官方 Docker 镜像或手动安装搭建天数 GPU 本地运行环境；如何以device="iluvatar_gpu"快速跑通 CLI 与 Python API 推理；如何启动基于 FastDeploy 的 VLM 推理服务并接入客户端；以及如何通过 Docker Compose 完成生产级服务化部署与产线配置调整。

说明：除非另有说明，本文中的"PaddleOCR-VL"均指 PaddleOCR-VL 系列模型（如 PaddleOCR-VL-1.6 等）。目前官方已在天数天垓 150 上完成精度与速度验证；鉴于硬件环境的多样性，其他天数 GPU 的兼容性尚未验证，官方欢迎社区用户在不同硬件上进行测试并反馈运行结果。

一、天数 GPU 上支持的使用目标与阅读路线

在动手之前，先根据你的目标确认阅读路线。天数 GPU 当前支持四类使用目标：

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

对照主教程中的 PaddleOCR-VL 推理方式与硬件支持矩阵，天数 GPU 在推理方式上的关键结论是：本地推理仅支持 PaddlePaddle 推理引擎（✅），PaddlePaddle + FastDeploy 组合亦受支持（✅）；而 Transformers、vLLM、SGLang、llama.cpp 等路径在天数 GPU 上均处于 🚧（适配中或待进一步验证）或 ❌ 状态。因此本文所有示例均围绕 PaddlePaddle 与 FastDeploy 展开。

二、本地运行环境准备

搭建 PaddleOCR-VL 本地运行环境有两种方式，任选其一即可：

方法一：使用官方 Docker 镜像（强烈推荐，可最大程度减少环境问题）。
方法二：手动安装推理引擎和 PaddleOCR。

需要注意的是，当前天数 GPU 的本地推理仅支持 PaddlePaddle 推理引擎，官方 Docker 镜像与手动安装均以此为前提。

2.1 方法一：使用官方 Docker 镜像

推荐使用官方 Docker 镜像（要求 Docker 版本 >= 19.03），启动命令如下：

docker run -it \ --user root \ --privileged \ -v /usr/src:/usr/src \ -v /lib/modules:/lib/modules \ -v /dev:/dev \ --cap-add SYS_PTRACE \ --pid host \ --shm-size 64g \ --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-iluvatar-gpu \ /bin/bash # 在容器中调用 PaddleOCR CLI 或 Python API

镜像约 37 GB。启动命令中的几个关键参数均与天数 GPU 的驱动/设备访问方式强相关：--privileged、--cap-add SYS_PTRACE、--pid host用于授予容器足够的设备与调试权限；-v /dev:/dev将宿主机设备透传进容器；-v /usr/src:/usr/src与-v /lib/modules:/lib/modules用于挂载内核模块与源码目录，这在天数 GPU 等非 NVIDIA 加速卡场景下是访问驱动与底层运行时（如 CoreX 软件栈）的必要条件。

若需在无法连接互联网的环境中启动服务，请将镜像更换为离线版本：

ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-iluvatar-gpu-offline

离线镜像约 39 GB，内置了官方模型，拉取后无需再联网下载权重。

标签说明：后缀为latest-xxx的镜像对应最新版本。若本地已存在同名latest镜像但希望使用最新功能或修复，建议先执行一次docker pull更新镜像。若希望使用特定版本的 PaddleOCR 镜像，可将标签中的latest替换为版本号paddleocr<major>.<minor>，例如：ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:paddleocr3.4-iluvatar-gpu-offline

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

无法使用 Docker 时，可手动安装推理引擎与 PaddleOCR。官方验证过的 Python 版本范围为 3.9–3.13，并强烈推荐在虚拟环境中安装以避免依赖冲突，例如使用 Python venv 标准库：

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

随后执行如下命令完成安装：

python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ python -m pip install paddle-iluvatar-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/ixuca/ python -m pip install -U "paddleocr[doc-parser]"

请注意安装 3.2.0 及以上版本的飞桨框架。其中paddle-iluvatar-gpu是飞桨面向天数 GPU（IXUCA 软件栈）发布的专属安装包，其内部署了天数加速卡的算子实现与运行时适配层；paddleocr[doc-parser]是 PaddleOCR-VL 所需的基础依赖集合，包含文档解析产线（版面分析、VLM 识别、Markdown 导出等）的完整 Python 包。

从仓库中的天数 GPU 镜像构建文件 vlm.Dockerfile 可以看到，官方镜像内部同样基于paddle-ixuca基础镜像安装fastdeploy_iluvatar_gpu==2.4.0.dev0（来源为https://www.paddlepaddle.org.cn/packages/stable/ixuca/），并设置了数个天数 GPU 特有的环境变量：

PADDLE_XCCL_BACKEND=iluvatar_gpu：指定飞桨集合通信（XCCL）后端；
FD_SAMPLING_CLASS=rejection：FastDeploy 的采样实现选择；
LD_PRELOAD=/usr/local/corex/lib64/libcuda.so.1：预加载天数 CoreX 软件栈提供的 CUDA 兼容层动态库。

这些细节说明天数 GPU 的 PaddleOCR-VL 部署与 NVIDIA GPU 在驱动栈层面存在本质差异，直接复用 NVIDIA 镜像或安装包无法工作。

三、快速开始：本地直接推理

天数 GPU 上的快速开始与主教程《PaddleOCR-VL 使用教程》第 2 节完全一致，唯一区别在于必须指定device="iluvatar_gpu"（可带卡号，如iluvatar_gpu:0）。

3.1 CLI 命令行方式

paddleocr doc_parser -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png --device iluvatar_gpu --save_path ./output

首次运行时，PaddleOCR-VL 会自动下载官方模型，请确保环境可联网并预留一定的下载和初始化时间。--save_path ./output用于将结构化结果、Markdown、JSON 等保存到本地便于查看。

常用扩展参数（全部继承自主教程 CLI 参数体系）：

--use_doc_orientation_classify True：启用文档方向分类模块；
--use_doc_unwarping True：启用文本图像矫正模块；
--use_layout_detection False：关闭版面分析（此时需配合--prompt_label使用）；
--pipeline_version v1.5：指定产线版本，可选v1、v1.5、v1.6，默认v1.6。

3.2 Python API 方式

from pathlib import Path from paddleocr import PaddleOCRVL output_dir = Path("./output") output_dir.mkdir(parents=True, exist_ok=True) # 天数 GPU pipeline = PaddleOCRVL(device="iluvatar_gpu") 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，每页会单独处理并生成独立的 Markdown 文件。如需跨页表格合并、重建多级标题或合并多页结果，可使用restructure_pages()：

pipeline = PaddleOCRVL(device="iluvatar_gpu") output = pipeline.predict(input="./your_pdf_file.pdf") pages_res = list(output) output = pipeline.restructure_pages(pages_res) # 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) # + 合并为单页

提醒：本节方法主要用于快速验证，其推理速度、显存占用与稳定性未必满足生产要求。若需部署至生产环境，强烈建议使用第 4 节的专用 VLM 推理服务。

四、使用 VLM 推理服务（FastDeploy 后端）

"客户端 + VLM 推理服务"模式的核心思路是：客户端继续负责版面分析等完整流程中的其他环节，仅将 VLM 推理交给专用服务处理。对于天数 GPU，这通常用于提升默认配置下的推理性能，以更好满足生产需求。

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

4.1 启动 VLM 推理服务

天数 GPU 上可用的启动方式如下表：

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

因此天数 GPU 上请使用官方 Docker 镜像（要求 Docker 版本 >= 19.03）启动 FastDeploy 推理服务：

docker run -it \ --user root \ --privileged \ -v /usr/src:/usr/src \ -v /lib/modules:/lib/modules \ -v /dev:/dev \ --cap-add SYS_PTRACE \ --pid host \ --shm-size 64g \ --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-fastdeploy-server:latest-iluvatar-gpu \ paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend fastdeploy

在线镜像约 38 GB；离线版本镜像paddleocr-genai-fastdeploy-server:latest-iluvatar-gpu-offline约 40 GB，适合无法连接互联网的环境。
paddleocr genai_server是 PaddleOCR 提供的统一推理服务启动命令，支持参数：--model_name（模型名称）、--model_dir（模型目录）、--host（服务器主机名）、--port（端口号）、--backend（后端名称，可选vllm、sglang、fastdeploy）、--backend_config（指定包含后端配置的 YAML 文件）。

自定义服务端参数

启动 FastDeploy 推理服务时默认参数已预置，若有调整显存占用等需求，可参考主教程 3.3.1 服务端参数调整创建配置文件（例如调整gpu-memory-utilization、max-concurrency等字段），挂载到容器中并用--backend_config指定：

docker run -it \ --user root \ --privileged \ -v /usr/src:/usr/src \ -v /lib/modules:/lib/modules \ -v /dev:/dev \ --cap-add SYS_PTRACE \ --pid host \ --shm-size 64g \ --network host \ -v ./fastdeploy_config.yml:/tmp/fastdeploy_config.yml \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-fastdeploy-server:latest-iluvatar-gpu \ 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

版本标签规则与第 2 节相同：latest-xxx为最新版；可用paddleocr<major>.<minor>指定版本，例如paddleocr3.4-iluvatar-gpu-offline。

4.2 客户端使用方法

VLM 推理服务启动后，客户端即可通过 PaddleOCR 调用该服务。CLI 方式通过--vl_rec_backend指定后端类型（此处为fastdeploy-server），通过--vl_rec_server_url指定服务地址，并同样指定--device iluvatar_gpu：

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

Python API 方式则是在创建PaddleOCRVL对象时传入对应参数：

from paddleocr import PaddleOCRVL pipeline = PaddleOCRVL( device="iluvatar_gpu", vl_rec_backend="fastdeploy-server", vl_rec_server_url="http://localhost:8118/v1", ) output = pipeline.predict("https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png")

如需指定服务端模型名称或鉴权，可追加vl_rec_api_model_name与vl_rec_api_key参数。注意：客户端仍需要调用版面分析模型并完成其他流程环节，因此建议在加速设备上运行客户端以获得稳定高效的表现；第 4.1 节的 Docker 环境仅适用于启动服务，不适用于客户端。

4.3 性能调优

性能调优思路与主教程 3.3 性能调优一致，核心要点如下：

服务端参数调整：通过--backend_config传入 YAML 配置，调整如gpu-memory-utilization、max-num-seqs等框架参数；也可用支持进程替换的 shell（如 Bash）直接传入配置项而无需创建文件。
客户端并发调整：PaddleOCR 会将单张或多张输入图像中的子图分组并对服务器发起并发请求，因此并发请求数对性能影响显著。CLI 与 Python API 可通过vl_rec_max_concurrency调整最大并发数；服务化部署可修改产线配置文件中VLRecognition.genai_config.max_concurrency字段。
调优方向：当客户端与 VLM 推理服务为 1 对 1 且服务端资源充足时，可适当增加并发数以提升性能；若服务端需支持多个客户端或计算资源有限，则应降低并发数，避免资源过载导致服务异常。

五、服务化部署：Docker Compose 方案

本节介绍的 PaddleOCR-VL 完整服务与上一节的 VLM 推理服务有本质区别：后者仅负责完整流程中的一个环节（VLM 推理），并作为前者的底层服务被调用。完整服务暴露端到端的文档解析 API，且基于 FastDeploy 对 VLM 推理进行加速，更适合生产环境。

天数 GPU 上的部署方式支持情况：Docker Compose 部署支持并提供步骤；手动部署当前不支持。

5.1 使用 Docker Compose 部署

分别获取 Compose 文件与环境变量配置文件并下载到本地：
- deploy/paddleocr_vl_docker/accelerators/iluvatar-gpu/compose.yaml
- deploy/paddleocr_vl_docker/accelerators/iluvatar-gpu/.env
在compose.yaml和.env文件所在目录下执行以下命令启动服务器，默认监听8080端口：

# 必须在 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 CTRL+C to quit)

提示：compose.yaml中使用的镜像标签通常由.env中的API_IMAGE_TAG_SUFFIX和VLM_IMAGE_TAG_SUFFIX控制，默认使用latest-iluvatar-gpu-offline等标签。如需确保拉取到最新镜像，可先执行docker compose pull再执行docker compose up。若希望使用特定版本，可将这两个环境变量中的latest替换为paddleocr<major>.<minor>，例如paddleocr3.3-iluvatar-gpu-offline。

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

Compose 架构与 .env 环境变量

Docker Compose 通过读取.env与compose.yaml配置，先后启动 2 个容器：paddleocr-vlm-server（底层 VLM 推理服务）与paddleocr-vl-api（PaddleOCR-VL 产线服务）。从仓库中的 iluvatar-gpu/compose.yaml 可以看到：

paddleocr-vl-api容器的启动命令为paddlex --serve --pipeline /home/paddleocr/pipeline_config_${VLM_BACKEND}.yaml --device iluvatar_gpu，并通过depends_on+healthcheck（curl -f http://localhost:8080/health）等待 VLM 服务就绪；
两个容器均配置了privileged: true、cap_add: [SYS_PTRACE]、pid: host、shm_size: 64g，并挂载/usr/src、/lib/modules、/dev，与第 2 节 Docker 运行参数保持一致；
.env中默认VLM_BACKEND=fastdeploy，即天数 GPU 默认以 FastDeploy 作为 VLM 推理后端。

.env文件中各环境变量含义如下：

API_IMAGE_TAG_SUFFIX：启动产线服务（paddleocr-vl-api）使用的镜像的标签后缀。
VLM_BACKEND：VLM 推理后端，天数 GPU 上使用fastdeploy。
VLM_IMAGE_TAG_SUFFIX：启动 VLM 推理服务（paddleocr-vlm-server）使用的镜像的标签后缀。

常见自定义需求

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

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

2. 指定 PaddleOCR-VL 服务所使用的 GPU：编辑compose.yaml中两个服务的environment。例如需要使用卡 1 进行部署：

paddleocr-vl-api: ... environment: + - CUDA_VISIBLE_DEVICES: 1 ... paddleocr-vlm-server: ... environment: + - CUDA_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. 调整产线相关配置（如模型路径、批处理大小、部署设备等）：参考第 5.3 节"产线配置调整说明"。

5.2 客户端调用方式

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

POST /layout-parsing：进行版面解析（infer 操作）。请求体为 JSON，必填字段为file（服务器可访问的图像/PDF 文件 URL，或文件内容的 Base64 编码结果）；可选字段包括fileType（0=PDF，1=图像，含 TIFF，多页时按页处理）、useDocOrientationClassify、useDocUnwarping、useLayoutDetection、useChartRecognition、useSealRecognition、useOcrForImageBlock、layoutThreshold、layoutNms、layoutUnclipRatio、layoutMergeBboxesMode、layoutShapeMode、promptLabel、formatBlockContent、repetitionPenalty、temperature、topP、minPixels、maxPixels、maxNewTokens、mergeLayoutBlocks、markdownIgnoreLabels、vlmExtraArgs、prettifyMarkdown（默认 true）、showFormulaNumber（默认 false）、restructurePages（默认 false）、mergeTables、relevelTitles、returnMarkdownImages（默认 true）、outputFormats（当前仅支持"docx"）、visualize等。成功时响应体包含logId、errorCode（固定 0）、errorMsg（固定 "Success"）与result；result.layoutParsingResults为数组，图像输入长度为 1，PDF 输入长度等于实际处理的页数。
POST /restructure-pages：重构多页结果。请求体必填pages数组（每个元素含prunedResult与markdownImages），可选mergeTables、relevelTitles、concatenatePages、prettifyMarkdown、showFormulaNumber、returnMarkdownImages、outputFormats。

以 Python 为例的完整调用流程（先layout-parsing逐页解析，再restructure-pages合并重建并落盘 Markdown）：

import base64 import pathlib 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"] pages = [] for i, res in enumerate(result["layoutParsingResults"]): pages.append({"prunedResult": res["prunedResult"], "markdownImages": res["markdown"].get("images")}) payload = {"pages": pages, "concatenatePages": True} response = requests.post(BASE_URL + "/restructure-pages", json=payload) assert response.status_code == 200, (response.status_code, response.text) res = response.json()["result"]["layoutParsingResults"][0] md_dir = pathlib.Path("markdown") md_dir.mkdir(exist_ok=True) (md_dir / "doc.md").write_text(res["markdown"]["text"]) for img_path, img in res["markdown"]["images"].items(): img_path = md_dir / img_path img_path.parent.mkdir(parents=True, exist_ok=True) img_path.write_bytes(base64.b64decode(img)) print(f"Markdown document saved at {md_dir / 'doc.md'}")

说明：响应中涉及图像等二进制内容的字段（如outputImages、inputImage、markdown.images、exports）默认以 Base64 字符串内联返回；当服务端开启 URL 返回模式时，相应字段值变为预签名 URL。

5.3 产线配置调整说明

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

获取配置文件：天数 GPU 采用 Docker Compose 部署，FastDeploy 后端对应的产线配置文件即仓库中的 pipeline_config_fastdeploy.yaml。该文件展示了产线核心参数：pipeline_name: PaddleOCR-VL-1.6、batch_size: 64、use_queues: True、use_doc_preprocessor: False、use_layout_detection: True，其中VLRecognition子模块配置了model_name: PaddleOCR-VL-1.6-0.9B，并通过genai_config.backend: fastdeploy-server、genai_config.server_url: http://paddleocr-vlm-server:8080/v1将 VLM 推理指向 Compose 内部的 FastDeploy 服务容器；LayoutDetection子模块默认使用PP-DocLayoutV3版面分析模型。

修改配置文件，常见调整项包括：

使用加速框架提升 VLM 推理性能：Docker Compose 方案默认已使用 FastDeploy 加速框架，无需额外修改；手动部署场景下可在产线配置中修改VLRecognition.genai_config.backend与server_url字段。
启用文档图像预处理功能：默认配置启动的服务不支持文档预处理功能，客户端调用将返回错误。如需启用，将use_doc_preprocessor设置为True并使用修改后的配置文件启动服务（对应子产线DocPreprocessor内含文档方向分类PP-LCNet_x1_0_doc_ori与文本图像矫正UVDoc两个子模块）。
禁用结果可视化功能：服务默认返回可视化结果会引入额外开销，可在配置中添加顶层字段禁用：

Serving: visualize: False

也可在请求体中设置visualize: false仅对单次请求生效。

配置以 URL 形式返回二进制内容：默认以 Base64 内联返回图像等二进制内容，如需改为 URL 形式，可配置：

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

限制 PDF 与多页 TIFF 解析页数：服务默认处理完整 PDF，多页 TIFF 会逐页展开处理；页数过多可能影响稳定性。可在配置中添加：

Serving: extra: max_num_input_imgs: <页数限制，例如 100>

max_num_input_imgs同时限制 PDF 与多页 TIFF 的最大处理页数，设置为null时不限制（仓库默认即为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 ...

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

六、模型微调

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

七、排查与注意事项速览

精度不可复现 / 大量幻觉文本：首先确认使用的是完整的 PaddleOCR-VL 流程（版面分析 + VLM 识别协同），而不是仅使用其中的 VLM 组件。直接请求第 4 节启动的 FastDeploy 服务、或直接以 Transformers 本地执行 PaddleOCR-VL-0.9B，都不等同于运行完整的 PaddleOCR-VL 流程。
设备指定：天数 GPU 上所有本地推理与客户端调用必须显式指定device="iluvatar_gpu"（可带卡号），否则将回退到默认 GPU 0 或 CPU。
镜像更新：latest-xxx标签对应最新版，升级前先docker pull；离线环境使用-offline后缀镜像。
硬件适配状态：官方目前仅在天数天垓 150 上完成验证，其他天数 GPU 的兼容性尚未验证；本地推理仅支持 PaddlePaddle 引擎，VLM 服务路径仅支持官方 Docker 镜像 + FastDeploy 后端，请以本文各支持矩阵为准，不要套用 NVIDIA GPU 的 vLLM/SGLang 方案。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析