PaddleOCR/docs/version3.x/pipeline_usage/PaddleOCR-VL.md

comments
true

PaddleOCR-VL介绍

PaddleOCR-VL 是一款先进、高效的文档解析模型，专为文档中的元素识别设计。其核心组件为 PaddleOCR-VL-0.9B，这是一种紧凑而强大的视觉语言模型（VLM），它由 NaViT 风格的动态分辨率视觉编码器与 ERNIE-4.5-0.3B 语言模型组成，能够实现精准的元素识别。该模型支持 109 种语言，并在识别复杂元素（如文本、表格、公式和图表）方面表现出色，同时保持极低的资源消耗。通过在广泛使用的公开基准与内部基准上的全面评测，PaddleOCR-VL 在页级级文档解析与元素级识别均达到 SOTA 表现。它显著优于现有的基于Pipeline方案和文档解析多模态方案以及先进的通用多模态大模型，并具备更快的推理速度。这些优势使其非常适合在真实场景中落地部署。

1. 环境准备

安装 PaddlePaddle 和 PaddleOCR:

python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
python -m pip install -U "paddleocr[doc-parser]"
python -m pip install https://paddle-whl.bj.bcebos.com/nightly/cu126/safetensors/safetensors-0.6.2.dev0-cp38-abi3-linux_x86_64.whl

对于 Windows 用户，请使用 WSL 或者 Docker 进行环境搭建。

2. 快速开始

PaddleOCR-VL 支持 CLI 命令行方式和 Python API 两种使用方式，其中 CLI 命令行方式更简单，适合快速验证功能，而 Python API 方式更灵活，适合集成到现有项目中。

2.1 命令行方式体验

一行命令即可快速体验 PaddleOCR-VL 产线效果：

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

# 通过 --use_doc_orientation_classify 指定是否使用文档方向分类模型
paddleocr doc_parser -i ./paddleocr_vl_demo.png --use_doc_orientation_classify True

# 通过 --use_doc_unwarping 指定是否使用文本图像矫正模块
paddleocr doc_parser -i ./paddleocr_vl_demo.png --use_doc_unwarping True

# 通过 --use_layout_detection 指定是否使用版面区域检测排序模块
paddleocr doc_parser -i ./paddleocr_vl_demo.png --use_layout_detection False

命令行支持更多参数设置，点击展开以查看命令行参数的详细说明

参数	参数说明	参数类型	默认值
input	待预测数据，必填。 如图像文件或者PDF文件的本地路径：/root/data/img.jpg；如URL链接，如图像文件或PDF文件的网络URL：示例；如本地目录，该目录下需包含待预测图像，如本地路径：/root/data/(当前不支持目录中包含PDF文件的预测，PDF文件需要指定到具体文件路径)。	str
save_path	指定推理结果文件保存的路径。如果不设置，推理结果将不会保存到本地。	str
layout_detection_model_name	版面区域检测排序模型名称。如果不设置，将会使用产线默认模型。	str
layout_detection_model_dir	版面区域检测排序模型的目录路径。如果不设置，将会下载官方模型。	str
layout_threshold	版面模型得分阈值。0-1 之间的任意浮点数。如果不设置，将使用产线初始化的该参数值。	float
layout_nms	版面检测是否使用后处理NMS。如果不设置，将使用产线初始化的该参数值，默认初始化为True。	bool
layout_unclip_ratio	版面区域检测模型检测框的扩张系数。 任意大于 0 浮点数。如果不设置，将使用产线初始化的该参数值。	float
layout_merge_bboxes_mode	版面检测中模型输出的检测框的合并处理模式。 large，设置为large时，表示在模型输出的检测框中，对于互相重叠包含的检测框，只保留外部最大的框，删除重叠的内部框； small，设置为small，表示在模型输出的检测框中，对于互相重叠包含的检测框，只保留内部被包含的小框，删除重叠的外部框； union，不进行框的过滤处理，内外框都保留； 如果不设置，将使用产线初始化的该参数值。	str
vl_rec_model_name	多模态识别模型名称。如果不设置，将会使用产线默认模型。	str
vl_rec_model_dir	多模态识别模型目录路径。如果不设置，将会下载官方模型。	str
vl_rec_backend	多模态识别模型使用的推理后端。	str
vl_rec_server_url	如果多模态识别模型使用推理服务，该参数用于指定服务器URL。	str
vl_rec_max_concurrency	如果多模态识别模型使用推理服务，该参数用于指定最大并发请求数。	str
doc_orientation_classify_model_name	文档方向分类模型的名称。如果不设置，将会使用产线默认模型。	str
doc_orientation_classify_model_dir	文档方向分类模型的目录路径。如果不设置，将会下载官方模型。	str
doc_unwarping_model_name	文本图像矫正模型的名称。如果不设置，将会使用产线默认模型。	str
doc_unwarping_model_dir	文本图像矫正模型的目录路径。如果不设置，将会下载官方模型。	str
use_doc_orientation_classify	是否加载并使用文档方向分类模块。如果不设置，将使用产线初始化的该参数值，默认初始化为False。	bool
use_doc_unwarping	是否加载并使用文本图像矫正模块。如果不设置，将使用产线初始化的该参数值，默认初始化为False。	bool
use_layout_detection	是否加载并使用版面区域检测排序模块。如果不设置，将使用产线初始化的该参数值，默认初始化为True。	bool
use_chart_recognition	是否加载并使用图表解析模块。如果不设置，将使用产线初始化的该参数值，默认初始化为False。	bool
format_block_content	控制是否将 block_content 中的内容格式化为Markdown格式。如果不设置，将使用产线初始化的该参数值，默认初始化为False。	bool
use_queues	用于控制是否启用内部队列。当设置为 True 时，数据加载（如将 PDF 页面渲染为图像）、版面检测模型处理以及 VLM 推理将分别在独立线程中异步执行，通过队列传递数据，从而提升效率。对于页数较多的 PDF 文档，或是包含大量图像或 PDF 文件的目录，这种方式尤其高效。	bool
prompt_label	VL模型的 prompt 类型设置，当且仅当 use_layout_detection=False 时生效。	str
repetition_penalty	VL模型采样使用的重复惩罚参数。	float
temperature	VL模型采样使用的温度参数。	float
top_p	VL模型采样使用的top-p参数。	float
min_pixels	VL模型预处理图像时允许的最小像素数。	int
max_pixels	VL模型预处理图像时允许的最大像素数。	int
device	用于推理的设备。支持指定具体卡号： CPU：如 cpu 表示使用 CPU 进行推理； GPU：如 gpu:0 表示使用第 1 块 GPU 进行推理； NPU：如 npu:0 表示使用第 1 块 NPU 进行推理； XPU：如 xpu:0 表示使用第 1 块 XPU 进行推理； MLU：如 mlu:0 表示使用第 1 块 MLU 进行推理； DCU：如 dcu:0 表示使用第 1 块 DCU 进行推理； 如果不设置，将默认使用产线初始化的该参数值，初始化时，会优先使用本地的 GPU 0号设备，如果没有，则使用 CPU 设备。	str
enable_hpi	是否启用高性能推理。	bool	False
use_tensorrt	是否启用 Paddle Inference 的 TensorRT 子图引擎。如果模型不支持通过 TensorRT 加速，即使设置了此标志，也不会使用加速。 对于 CUDA 11.8 版本的飞桨，兼容的 TensorRT 版本为 8.x（x>=6），建议安装 TensorRT 8.6.1.6。	bool	False
precision	计算精度，如 fp32、fp16。	str	fp32
enable_mkldnn	是否启用 MKL-DNN 加速推理。如果 MKL-DNN 不可用或模型不支持通过 MKL-DNN 加速，即使设置了此标志，也不会使用加速。	bool	True
mkldnn_cache_capacity	MKL-DNN 缓存容量。	int	10
cpu_threads	在 CPU 上进行推理时使用的线程数。	int	8
paddlex_config	PaddleX产线配置文件路径。	str

运行结果会被打印到终端上，默认配置的 PaddleOCR-VL 产线的运行结果如下：

👉点击展开

{'res': {'input_path': 'paddleocr_vl_demo.png', 'page_index': None, 'model_settings': {'use_doc_preprocessor': False, 'use_layout_detection': True, 'use_chart_recognition': False, 'format_block_content': False}, 'layout_det_res': {'input_path': None, 'page_index': None, 'boxes': [{'cls_id': 6, 'label': 'doc_title', 'score': 0.9636914134025574, 'coordinate': [np.float32(131.31366), np.float32(36.450516), np.float32(1384.522), np.float32(127.984665)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9281806349754333, 'coordinate': [np.float32(585.39465), np.float32(158.438), np.float32(930.2184), np.float32(182.57469)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9840355515480042, 'coordinate': [np.float32(9.023666), np.float32(200.86115), np.float32(361.41583), np.float32(343.8828)]}, {'cls_id': 14, 'label': 'image', 'score': 0.9871416091918945, 'coordinate': [np.float32(775.50574), np.float32(200.66502), np.float32(1503.3807), np.float32(684.9304)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9801855087280273, 'coordinate': [np.float32(9.532196), np.float32(344.90594), np.float32(361.4413), np.float32(440.8244)]}, {'cls_id': 17, 'label': 'paragraph_title', 'score': 0.9708921313285828, 'coordinate': [np.float32(28.040405), np.float32(455.87976), np.float32(341.7215), np.float32(520.7117)]}, {'cls_id': 24, 'label': 'vision_footnote', 'score': 0.9002962708473206, 'coordinate': [np.float32(809.0692), np.float32(703.70044), np.float32(1488.3016), np.float32(750.5238)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9825374484062195, 'coordinate': [np.float32(8.896561), np.float32(536.54895), np.float32(361.05237), np.float32(655.8058)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9822263717651367, 'coordinate': [np.float32(8.971573), np.float32(657.4949), np.float32(362.01715), np.float32(774.625)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9767460823059082, 'coordinate': [np.float32(9.407074), np.float32(776.5216), np.float32(361.31067), np.float32(846.82874)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9868153929710388, 'coordinate': [np.float32(8.669495), np.float32(848.2543), np.float32(361.64703), np.float32(1062.8568)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9826608300209045, 'coordinate': [np.float32(8.8025055), np.float32(1063.8615), np.float32(361.46588), np.float32(1182.8524)]}, {'cls_id': 22, 'label': 'text', 'score': 0.982555627822876, 'coordinate': [np.float32(8.820602), np.float32(1184.4663), np.float32(361.66394), np.float32(1302.4507)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9584776759147644, 'coordinate': [np.float32(9.170288), np.float32(1304.2161), np.float32(361.48898), np.float32(1351.7483)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9782056212425232, 'coordinate': [np.float32(389.1618), np.float32(200.38202), np.float32(742.7591), np.float32(295.65146)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9844875931739807, 'coordinate': [np.float32(388.73303), np.float32(297.18463), np.float32(744.00024), np.float32(441.3034)]}, {'cls_id': 17, 'label': 'paragraph_title', 'score': 0.9680547714233398, 'coordinate': [np.float32(409.39468), np.float32(455.89386), np.float32(721.7174), np.float32(520.9387)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9741666913032532, 'coordinate': [np.float32(389.71606), np.float32(536.8138), np.float32(742.7112), np.float32(608.00165)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9840384721755981, 'coordinate': [np.float32(389.30988), np.float32(609.39636), np.float32(743.09247), np.float32(750.3231)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9845995306968689, 'coordinate': [np.float32(389.13272), np.float32(751.7772), np.float32(743.058), np.float32(894.8815)]}, {'cls_id': 22, 'label': 'text', 'score': 0.984852135181427, 'coordinate': [np.float32(388.83267), np.float32(896.0371), np.float32(743.58215), np.float32(1038.7345)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9804865717887878, 'coordinate': [np.float32(389.08478), np.float32(1039.9119), np.float32(742.7585), np.float32(1134.4897)]}, {'cls_id': 22, 'label': 'text', 'score': 0.986461341381073, 'coordinate': [np.float32(388.52643), np.float32(1135.8137), np.float32(743.451), np.float32(1352.0085)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9869391918182373, 'coordinate': [np.float32(769.8341), np.float32(775.66235), np.float32(1124.9813), np.float32(1063.207)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9822869896888733, 'coordinate': [np.float32(770.30383), np.float32(1063.938), np.float32(1124.8295), np.float32(1184.2192)]}, {'cls_id': 17, 'label': 'paragraph_title', 'score': 0.9689218997955322, 'coordinate': [np.float32(791.3042), np.float32(1199.3169), np.float32(1104.4521), np.float32(1264.6985)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9713128209114075, 'coordinate': [np.float32(770.4253), np.float32(1279.6072), np.float32(1124.6917), np.float32(1351.8672)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9236552119255066, 'coordinate': [np.float32(1153.9058), np.float32(775.5814), np.float32(1334.0654), np.float32(798.1581)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9857938885688782, 'coordinate': [np.float32(1151.5197), np.float32(799.28015), np.float32(1506.3619), np.float32(991.1156)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9820687174797058, 'coordinate': [np.float32(1151.5686), np.float32(991.91095), np.float32(1506.6023), np.float32(1110.8875)]}, {'cls_id': 22, 'label': 'text', 'score': 0.9866049885749817, 'coordinate': [np.float32(1151.6919), np.float32(1112.1301), np.float32(1507.1611), np.float32(1351.9504)]}]}}}

运行结果参数说明可以参考2.2 Python脚本方式集成中的结果解释。

注：由于产线的默认模型较大，推理速度可能较慢，建议实际推理使用3. 使用推理加速框架提升 VLM 推理性能方式进行快速推理。

2.2 Python脚本方式集成

命令行方式是为了快速体验查看效果，一般来说，在项目中，往往需要通过代码集成，您可以通过几行代码即可完成产线的快速推理，推理代码如下：

from paddleocr import PaddleOCRVL

pipeline = PaddleOCRVL()
# pipeline = PaddleOCRVL(use_doc_orientation_classify=True) # 通过 use_doc_orientation_classify 指定是否使用文档方向分类模型
# pipeline = PaddleOCRVL(use_doc_unwarping=True) # 通过 use_doc_unwarping 指定是否使用文本图像矫正模块
# pipeline = PaddleOCRVL(use_layout_detection=False) # 通过 use_layout_detection 指定是否使用版面区域检测排序模块
output = pipeline.predict("./paddleocr_vl_demo.png")
for res in output:
    res.print() ## 打印预测的结构化输出
    res.save_to_json(save_path="output") ## 保存当前图像的结构化json结果
    res.save_to_markdown(save_path="output") ## 保存当前图像的markdown格式的结果

如果是 PDF 文件，会将 PDF 的每一页单独处理，每一页的 Markdown 文件也会对应单独的结果。如果希望整个 PDF 文件转换为 Markdown 文件，建议使用以下的方式运行：

from pathlib import Path
from paddleocr import PaddleOCRVL

input_file = "./your_pdf_file.pdf"
output_path = Path("./output")

pipeline = PaddleOCRVL()
output = pipeline.predict(input=input_file)

markdown_list = []
markdown_images = []

for res in output:
    md_info = res.markdown
    markdown_list.append(md_info)
    markdown_images.append(md_info.get("markdown_images", {}))

markdown_texts = pipeline.concatenate_markdown_pages(markdown_list)

mkd_file_path = output_path / f"{Path(input_file).stem}.md"
mkd_file_path.parent.mkdir(parents=True, exist_ok=True)

with open(mkd_file_path, "w", encoding="utf-8") as f:
    f.write(markdown_texts)

for item in markdown_images:
    if item:
        for path, image in item.items():
            file_path = output_path / path
            file_path.parent.mkdir(parents=True, exist_ok=True)
            image.save(file_path)

注：

• 在示例代码中，use_doc_orientation_classify、use_doc_unwarping 参数默认均设置为 False，分别表示关闭文档方向分类、文本图像矫正功能，如果需要使用这些功能，可以手动设置为 True。

在上述 Python 脚本中，执行了如下几个步骤：

（1）实例化产线对象，具体参数说明如下：

参数	参数说明	参数类型	默认值
layout_detection_model_name	版面区域检测排序模型名称。如果设置为None，将会使用产线默认模型。	str|None	None
layout_detection_model_dir	版面区域检测排序模型的目录路径。如果设置为None，将会下载官方模型。	str|None	None
layout_threshold	版面模型得分阈值。 float：0-1 之间的任意浮点数； dict： {0:0.1} key为类别ID，value为该类别的阈值； None：如果设置为None，将使用产线初始化的该参数值。	float|dict|None	None
layout_nms	版面检测是否使用后处理NMS。如果设置为None，将使用产线初始化的该参数值。	bool|None	None
layout_unclip_ratio	版面区域检测模型检测框的扩张系数。 float：任意大于 0 浮点数； Tuple[float,float]：在横纵两个方向各自的扩张系数； dict，dict的key为int类型，代表cls_id, value为tuple类型，如{0: (1.1, 2.0)}，表示将模型输出的第0类别检测框中心不变，宽度扩张1.1倍，高度扩张2.0倍； None：如果设置为None，将使用产线初始化的该参数值。	float|Tuple[float,float]|dict|None	None
layout_merge_bboxes_mode	版面区域检测的重叠框过滤方式。 str：large，small，union，分别表示重叠框过滤时选择保留大框，小框还是同时保留； dict： dict的key为int类型，代表cls_id，value为str类型，如{0: "large", 2: "small"}，表示对第0类别检测框使用large模式，对第2类别检测框使用small模式； None：如果设置为None，将使用产线初始化的该参数值。	str|dict|None	None
vl_rec_model_name	多模态识别模型名称。如果设置为None，将会使用产线默认模型。	str|None	None
vl_rec_model_dir	多模态识别模型目录路径。如果设置为None，将会下载官方模型。	str|None	None
vl_rec_backend	多模态识别模型使用的推理后端。	int|None	None
vl_rec_server_url	如果多模态识别模型使用推理服务，该参数用于指定服务器URL。	str|None	None
vl_rec_max_concurrency	如果多模态识别模型使用推理服务，该参数用于指定最大并发请求数。	str|None	None
doc_orientation_classify_model_name	文档方向分类模型的名称。如果设置为None，将会使用产线默认模型。	str|None	None
doc_orientation_classify_model_dir	文档方向分类模型的目录路径。如果设置为None，将会下载官方模型。	str|None	None
doc_unwarping_model_name	文本图像矫正模型的名称。如果设置为None，将会使用产线默认模型。	str|None	None
doc_unwarping_model_dir	文本图像矫正模型的目录路径。如果设置为None，将会下载官方模型。	str|None	None
use_doc_orientation_classify	是否加载并使用文档方向分类模块。如果设置为None，将使用产线初始化的该参数值，默认初始化为False。	bool|None	None
use_doc_unwarping	是否加载并使用文本图像矫正模块。如果设置为None，将使用产线初始化的该参数值，默认初始化为False。	bool|None	None
use_layout_detection	是否加载并使用版面区域检测排序模块。如果设置为None，将使用产线初始化的该参数值，默认初始化为True。	bool|None	None
use_chart_recognition	是否加载并使用图表解析模块。如果设置为None，将使用产线初始化的该参数值，默认初始化为False。	bool|None	None
format_block_content	控制是否将 block_content 中的内容格式化为Markdown格式。如果设置为None，将使用产线初始化的该参数值，默认初始化为False。	bool|None	None
device	用于推理的设备。支持指定具体卡号： CPU：如 cpu 表示使用 CPU 进行推理； GPU：如 gpu:0 表示使用第 1 块 GPU 进行推理； NPU：如 npu:0 表示使用第 1 块 NPU 进行推理； XPU：如 xpu:0 表示使用第 1 块 XPU 进行推理； MLU：如 mlu:0 表示使用第 1 块 MLU 进行推理； DCU：如 dcu:0 表示使用第 1 块 DCU 进行推理； None：如果设置为None，初始化时，会优先使用本地的 GPU 0号设备，如果没有，则使用 CPU 设备。	str|None	None
enable_hpi	是否启用高性能推理。	bool	False
use_tensorrt	是否启用 Paddle Inference 的 TensorRT 子图引擎。如果模型不支持通过 TensorRT 加速，即使设置了此标志，也不会使用加速。 对于 CUDA 11.8 版本的飞桨，兼容的 TensorRT 版本为 8.x（x>=6），建议安装 TensorRT 8.6.1.6。	bool	False
precision	计算精度，如 fp32、fp16。	str	"fp32"
enable_mkldnn	是否启用 MKL-DNN 加速推理。如果 MKL-DNN 不可用或模型不支持通过 MKL-DNN 加速，即使设置了此标志，也不会使用加速。	bool	True
mkldnn_cache_capacity	MKL-DNN 缓存容量。	int	10
cpu_threads	在 CPU 上进行推理时使用的线程数。	int	8
paddlex_config	PaddleX产线配置文件路径。	str|None	None

（2）调用 PaddleOCR-VL 产线对象的 predict() 方法进行推理预测，该方法会返回一个结果列表。另外，产线还提供了 predict_iter() 方法。两者在参数接受和结果返回方面是完全一致的，区别在于 predict_iter() 返回的是一个 generator，能够逐步处理和获取预测结果，适合处理大型数据集或希望节省内存的场景。可以根据实际需求选择使用这两种方法中的任意一种。以下是 predict() 方法的参数及其说明：

参数	参数说明	参数类型	默认值
input	待预测数据，支持多种输入类型，必填。 Python Var：如 numpy.ndarray 表示的图像数据 str：如图像文件或者PDF文件的本地路径：/root/data/img.jpg；如URL链接，如图像文件或PDF文件的网络URL：示例；如本地目录，该目录下需包含待预测图像，如本地路径：/root/data/(当前不支持目录中包含PDF文件的预测，PDF文件需要指定到具体文件路径) list：列表元素需为上述类型数据，如[numpy.ndarray, numpy.ndarray]，["/root/data/img1.jpg", "/root/data/img2.jpg"]，["/root/data1", "/root/data2"]。	Python Var|str|list
use_doc_orientation_classify	是否在推理时使用文档方向分类模块。设置为None表示使用实例化参数，否则该参数优先级更高。	bool|None	None
use_doc_unwarping	是否在推理时使用文本图像矫正模块。设置为None表示使用实例化参数，否则该参数优先级更高。	bool|None	None
use_layout_detection	是否在推理时使用版面区域检测排序模块。设置为None表示使用实例化参数，否则该参数优先级更高。	bool|None	None
use_chart_recognition	是否在推理时使用图表解析模块。设置为None表示使用实例化参数，否则该参数优先级更高。	bool|None	None
layout_threshold	参数含义与实例化参数基本相同。设置为None表示使用实例化参数，否则该参数优先级更高。	float|dict|None	None
layout_nms	参数含义与实例化参数基本相同。设置为None表示使用实例化参数，否则该参数优先级更高。	bool|None	None
layout_unclip_ratio	参数含义与实例化参数基本相同。设置为None表示使用实例化参数，否则该参数优先级更高。	float|Tuple[float,float]|dict|None	None
layout_merge_bboxes_mode	参数含义与实例化参数基本相同。设置为None表示使用实例化参数，否则该参数优先级更高。	str|dict|None	None
use_queues	用于控制是否启用内部队列。当设置为 True 时，数据加载（如将 PDF 页面渲染为图像）、版面检测模型处理以及 VLM 推理将分别在独立线程中异步执行，通过队列传递数据，从而提升效率。对于页数较多的 PDF 文档，或是包含大量图像或 PDF 文件的目录，这种方式尤其高效。	bool|None	None
prompt_label	VL模型的 prompt 类型设置，当且仅当 use_layout_detection=False 时生效。	str|None	None
format_block_content	参数含义与实例化参数基本相同。设置为None表示使用实例化参数，否则该参数优先级更高。	bool|None	None
repetition_penalty	VL模型采样使用的重复惩罚参数。	float|None	None
temperature	VL模型采样使用的温度参数。	float|None	None
top_p	VL模型采样使用的top-p参数。	float|None	None
min_pixels	VL模型预处理图像时允许的最小像素数。	int|None	None
max_pixels	VL模型预处理图像时允许的最大像素数。	int|None	None

（3）对预测结果进行处理：每个样本的预测结果均为对应的Result对象，且支持打印、保存为图片、保存为json文件的操作:

方法	方法说明	参数	参数类型	参数说明	默认值
print()	打印结果到终端	format_json	bool	是否对输出内容进行使用 JSON 缩进格式化。	True
		indent	int	指定缩进级别，以美化输出的 JSON 数据，使其更具可读性，仅当 format_json 为 True 时有效。	4
		ensure_ascii	bool	控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时，所有非 ASCII 字符将被转义；False 则保留原始字符，仅当format_json为True时有效。	False
save_to_json()	将结果保存为json格式的文件	save_path	str	保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致。	无
		indent	int	指定缩进级别，以美化输出的 JSON 数据，使其更具可读性，仅当 format_json 为 True 时有效。	4
		ensure_ascii	bool	控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时，所有非 ASCII 字符将被转义；False 则保留原始字符，仅当format_json为True时有效。	False
save_to_img()	将中间各个模块的可视化图像保存在png格式的图像	save_path	str	保存的文件路径，支持目录或文件路径。	无
save_to_markdown()	将图像或者PDF文件中的每一页分别保存为markdown格式的文件	save_path	str	保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致	无
		pretty	bool	是否美化 markdown 输出结果，将图表等进行居中操作，使 markdown 渲染后更美观。	True
		show_formula_number	bool	控制是否在 markdown 中将保留公式编号。设置为 True 时，保留全部公式编号；False 则仅保留公式	False
save_to_html()	将文件中的表格保存为html格式的文件	save_path	str	保存的文件路径，支持目录或文件路径。	无
save_to_xlsx()	将文件中的表格保存为xlsx格式的文件	save_path	str	保存的文件路径，支持目录或文件路径。	无

• 调用print() 方法会将结果打印到终端，打印到终端的内容解释如下：

  • input_path: (str) 待预测图像或者PDF的输入路径

  • page_index: (Union[int, None]) 如果输入是PDF文件，则表示当前是PDF的第几页，否则为 None

  • model_settings: (Dict[str, bool]) 配置产线所需的模型参数

    • use_doc_preprocessor: (bool) 控制是否启用文档预处理子产线
    • use_seal_recognition: (bool) 控制是否启用印章文本识别子产线
    • use_table_recognition: (bool) 控制是否启用表格识别子产线
    • use_formula_recognition: (bool) 控制是否启用公式识别子产线

  • doc_preprocessor_res: (Dict[str, Union[List[float], str]]) 文档预处理结果dict，仅当use_doc_preprocessor=True时存在

    • input_path: (str) 文档预处理子产线接受的图像路径，当输入为numpy.ndarray时，保存为None，此处为None
    • page_index: None，此处的输入为numpy.ndarray，所以值为None
    • model_settings: (Dict[str, bool]) 文档预处理子产线的模型配置参数
      • use_doc_orientation_classify: (bool) 控制是否启用文档图像方向分类子模块
      • use_doc_unwarping: (bool) 控制是否启用文本图像扭曲矫正子模块
    • angle: (int) 文档图像方向分类子模块的预测结果，启用时返回实际角度值

  • parsing_res_list: (List[Dict]) 解析结果的列表，每个元素为一个字典，列表顺序为解析后的阅读顺序。

    • block_bbox: (np.ndarray) 版面区域的边界框。
    • block_label: (str) 版面区域的标签，例如text, table等。
    • block_content: (str) 内容为版面区域内的内容。
    • block_id: (int) 版面区域的索引，用于显示版面排序结果。
    • block_order (int) 版面区域的顺序，用于显示版面阅读顺序,对于非排序部分，默认值为 None。

  • overall_ocr_res: (Dict[str, Union[List[str], List[float], numpy.ndarray]]) 全局 OCR 结果的dict

    • input_path: (Union[str, None]) 图像OCR子产线接受的图像路径，当输入为numpy.ndarray时，保存为None

    • page_index: None，此处的输入为numpy.ndarray，所以值为None

    • model_settings: (Dict) OCR子产线的模型配置参数

    • dt_polys: (List[numpy.ndarray]) 文本检测的多边形框列表。每个检测框由4个顶点坐标构成的numpy数组表示，数组shape为(4, 2)，数据类型为int16

    • dt_scores: (List[float]) 文本检测框的置信度列表

    • text_det_params: (Dict[str, Dict[str, int, float]]) 文本检测模块的配置参数

      • limit_side_len: (int) 图像预处理时的边长限制值
      • limit_type: (str) 边长限制的处理方式
      • thresh: (float) 文本像素分类的置信度阈值
      • box_thresh: (float) 文本检测框的置信度阈值
      • unclip_ratio: (float) 文本检测框的膨胀系数
      • text_type: (str) 文本检测的类型，当前固定为"general"

    • text_type: (str) 文本检测的类型，当前固定为"general"

    • textline_orientation_angles: (List[int]) 文本行方向分类的预测结果。启用时返回实际角度值（如[0,0,1]

    • text_rec_score_thresh: (float) 文本识别结果的过滤阈值

    • rec_texts: (List[str]) 文本识别结果列表，仅包含置信度超过text_rec_score_thresh的文本

    • rec_scores: (List[float]) 文本识别的置信度列表，已按text_rec_score_thresh过滤

    • rec_polys: (List[numpy.ndarray]) 经过置信度过滤的文本检测框列表，格式同dt_polys

  • formula_res_list: (List[Dict[str, Union[numpy.ndarray, List[float], str]]]) 公式识别结果列表，每个元素为一个dict

    • rec_formula: (str) 公式识别结果
    • rec_polys: (numpy.ndarray) 公式检测框，shape为(4, 2)，dtype为int16
    • formula_region_id: (int) 公式所在的区域编号

  • seal_res_list: (List[Dict[str, Union[numpy.ndarray, List[float], str]]]) 印章文本识别结果列表，每个元素为一个dict

    • input_path: (str) 印章图像的输入路径
    • page_index: None，此处的输入为numpy.ndarray，所以值为None
    • model_settings: (Dict) 印章文本识别子产线的模型配置参数
    • dt_polys: (List[numpy.ndarray]) 印章检测框列表，格式同dt_polys
    • text_det_params: (Dict[str, Dict[str, int, float]]) 印章检测模块的配置参数, 具体参数含义同上
    • text_type: (str) 印章检测的类型，当前固定为"seal"
    • text_rec_score_thresh: (float) 印章文本识别结果的过滤阈值
    • rec_texts: (List[str]) 印章文本识别结果列表，仅包含置信度超过text_rec_score_thresh的文本
    • rec_scores: (List[float]) 印章文本识别的置信度列表，已按text_rec_score_thresh过滤
    • rec_polys: (List[numpy.ndarray]) 经过置信度过滤的印章检测框列表，格式同dt_polys
    • rec_boxes: (numpy.ndarray) 检测框的矩形边界框数组，shape为(n, 4)，dtype为int16。每一行表示一个矩形

  • table_res_list: (List[Dict[str, Union[numpy.ndarray, List[float], str]]]) 表格识别结果列表，每个元素为一个dict

    • cell_box_list: (List[numpy.ndarray]) 表格单元格的边界框列表
    • pred_html: (str) 表格的HTML格式字符串
    • table_ocr_pred: (dict) 表格的OCR识别结果
      • rec_polys: (List[numpy.ndarray]) 单元格的检测框列表
      • rec_texts: (List[str]) 单元格的识别结果
      • rec_scores: (List[float]) 单元格的识别置信度
      • rec_boxes: (numpy.ndarray) 检测框的矩形边界框数组，shape为(n, 4)，dtype为int16。每一行表示一个矩形

• 调用save_to_json() 方法会将上述内容保存到指定的 save_path 中，如果指定为目录，则保存的路径为save_path/{your_img_basename}_res.json，如果指定为文件，则直接保存到该文件中。由于 json 文件不支持保存numpy数组，因此会将其中的 numpy.array 类型转换为列表形式。

• 调用save_to_img() 方法会将可视化结果保存到指定的 save_path 中，如果指定为目录，则会将版面区域检测可视化图像、全局OCR可视化图像、版面阅读顺序可视化图像等内容保存，如果指定为文件，则直接保存到该文件中。(产线通常包含较多结果图片，不建议直接指定为具体的文件路径，否则多张图会被覆盖，仅保留最后一张图)

• 调用save_to_markdown() 方法会将转化后的 Markdown 文件保存到指定的 save_path 中，保存的文件路径为save_path/{your_img_basename}.md，如果输入是 PDF 文件，建议直接指定目录，否责多个 markdown 文件会被覆盖。

此外，也支持通过属性获取带结果的可视化图像和预测结果，具体如下：

属性	属性说明
json	获取预测的 json 格式的结果
img	获取格式为 dict 的可视化图像
markdown	获取格式为 dict 的 markdown 结果

• json 属性获取的预测结果为dict类型的数据，相关内容与调用 save_to_json() 方法保存的内容一致。
• img 属性返回的预测结果是一个dict类型的数据。其中，键分别为 layout_det_res、overall_ocr_res、text_paragraphs_ocr_res、formula_res_region1、table_cell_img 和 seal_res_region1，对应的值是 Image.Image 对象：分别用于显示版面区域检测、OCR、OCR文本段落、公式、表格和印章结果的可视化图像。如果没有使用可选模块，则dict中只包含 layout_det_res。
• markdown 属性返回的预测结果是一个dict类型的数据。其中，键分别为 markdown_texts 、 markdown_images和page_continuation_flags，对应的值分别是 markdown 文本，在 Markdown 中显示的图像（Image.Image 对象）和用于标识当前页面第一个元素是否为段开始以及最后一个元素是否为段结束的bool元组。

3. 使用推理加速框架提升 VLM 推理性能

默认配置下的推理性能未经过充分优化，可能无法满足实际生产需求。PaddleOCR 支持通过 vLLM、SGLang 等推理加速框架提升 VLM 的推理性能，从而加快产线推理速度。使用流程主要分为两个步骤：

1. 启动 VLM 推理服务；
2. 配置 PaddleOCR 产线，作为客户端调用 VLM 推理服务。

3.1 启动 VLM 推理服务

3.1.1 使用 Docker 镜像

PaddleOCR 提供了 Docker 镜像，用于快速启动 vLLM 推理服务。可使用以下命令启动服务：

docker run \
    -it \
    --rm \
    --gpus all \
    --network host \
    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddlex-genai-vllm-server

服务默认监听 8080 端口。

启动容器时可传入参数覆盖默认配置，参数与 paddleocr genai_server 命令一致（详见下一小节）。例如：

docker run \
    -it \
    --rm \
    --gpus all \
    --network host \
    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddlex-genai-vllm-server \
    paddlex_genai_server --model_name PaddleOCR-VL-0.9B --host 0.0.0.0 --port 8118 --backend vllm

3.1.2 通过 PaddleOCR CLI 安装和使用

由于推理加速框架可能与飞桨框架存在依赖冲突，建议在虚拟环境中安装。以 vLLM 为例：

# 创建虚拟环境
python -m venv .venv
# 激活环境
source .venv/bin/activate
# 安装 PaddleOCR
python -m pip install "paddleocr[doc-parser]"
# 安装推理加速服务依赖
paddleocr install_genai_server_deps vllm

paddleocr install_genai_server_deps 命令用法：

paddleocr install_genai_server_deps <推理加速框架名称>

当前支持的框架名称为 vllm 和 sglang，分别对应 vLLM 和 SGLang。

安装完成后，可通过 paddleocr genai_server 命令启动服务：

paddleocr genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --port 8118

该命令支持的参数如下：

参数	说明
--model_name	模型名称
--model_dir	模型目录
--host	服务器主机名
--port	服务器端口号
--backend	后端名称，即使用的推理加速框架名称，可选 vllm 或 sglang
--backend_config	可指定 YAML 文件，包含后端配置

3.2 客户端使用方法

启动 VLM 推理服务后，客户端即可通过 PaddleOCR 调用该服务。

3.2.1 CLI 调用

可通过 --vl_rec_backend 指定后端类型（vllm-server 或 sglang-server），通过 --vl_rec_server_url 指定服务地址，例如：

paddleocr doc_parser --input paddleocr_vl_demo.png --vl_rec_backend vllm-server --vl_rec_server_url http://127.0.0.1:8118/v1

3.2.2 Python API 调用

创建 PaddleOCRVL 对象时传入 vl_rec_backend 和 vl_rec_server_url 参数：

pipeline = PaddleOCRVL(vl_rec_backend="vllm-server", vl_rec_server_url="http://127.0.0.1:8118/v1")

3.2.3 服务化部署

可在配置文件中修改 VLRecognition.genai_config.backend 和 VLRecognition.genai_config.server_url 字段，例如：

VLRecognition:
  ...
  genai_config:
    backend: vllm-server
    server_url: http://127.0.0.1:8118/v1

3.3 性能调优

默认配置是在单张 NVIDIA A100 上进行调优的，并假设客户端独占服务，因此可能不适用于其他环境。如果用户在实际使用中遇到性能问题，可以尝试以下优化方法。

3.3.1 服务端参数调整

不同推理加速框架支持的参数不同，可参考各自官方文档了解可用参数及其调整时机：

• vLLM 官方参数调优指南
• SGLang 超参数调整文档

PaddleOCR VLM 推理服务支持通过配置文件进行调参。以下示例展示如何调整 vLLM 服务器的 gpu-memory-utilization 和 max-num-seqs 参数：

1. 创建 YAML 文件 vllm_config.yaml，内容如下：

   gpu-memory-utilization: 0.3
   max-num-seqs: 128
   

2. 启动服务时指定配置文件路径，例如使用 paddleocr genai_server 命令：

   paddleocr genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --backend_config vllm_config.yaml
   

如果使用支持进程替换（process substitution）的 shell（如 Bash），也可以无需创建配置文件，直接在启动服务时传入配置项：

paddleocr genai_server --model_name PaddleOCR-VL-0.9B --backend vllm --backend_config <(echo -e 'gpu-memory-utilization: 0.3\nmax-num-seqs: 128')

3.3.2 客户端参数调整

PaddleOCR 会将来自单张或多张输入图像中的子图分组并对服务器发起并发请求，因此并发请求数对性能影响显著。

• 对 CLI 和 Python API，可通过 vl_rec_max_concurrency 参数调整最大并发请求数；
• 对服务化部署，可修改配置文件中 VLRecognition.genai_config.max_concurrency 字段。

当客户端与 VLM 推理服务为 1 对 1 且服务端资源充足时，可适当增加并发数以提升性能；若服务端需支持多个客户端或计算资源有限，则应降低并发数，以避免资源过载导致服务异常。

3.3.3 常用硬件性能调优建议

以下配置均针对客户端与 VLM 推理服务为 1 对 1 的场景。

NVIDIA RTX 3060

• 服务端
  • vLLM：gpu-memory-utilization=0.8