文档理解产线使用教程¶

1. 文档理解产线介绍¶

文档理解产线是基于视觉-语言模型（VLM）打造的先进文档处理技术，旨在突破传统文档处理的局限。传统方法依赖固定模板或预定义规则解析文档，而该产线借助VLM的多模态能力，仅需输入文档图片和用户问题，即可通过融合视觉与语言信息，精准回答用户提问。这种技术无需针对特定文档格式预训练，能够灵活应对多样化文档内容，显著提升文档处理的泛化性与实用性，在智能问答、信息提取等场景中具有广阔应用前景。本产线目前暂不支持对VLM模型的二次开发，后续计划支持。

文档理解产线中包含以下1个模块。每个模块均可独立进行训练和推理，并包含多个模型。有关详细信息，请点击相应模块以查看文档。

文档类视觉语言模型模块

在本产线中，您可以根据下方的基准测试数据选择使用的模型。

文档类视觉语言模型模块：

模型	模型下载链接	模型存储大小（GB）	模型总分	介绍
PP-DocBee-2B	推理模型	4.2	765	PP-DocBee 是飞桨团队自研的一款专注于文档理解的多模态大模型，在中文文档理解任务上具有卓越表现。该模型通过近 500 万条文档理解类多模态数据集进行微调优化，各种数据集包括了通用VQA类、OCR类、图表类、text-rich文档类、数学和复杂推理类、合成数据类、纯文本数据等，并设置了不同训练数据配比。在学术界权威的几个英文文档理解评测榜单上，PP-DocBee基本都达到了同参数量级别模型的SOTA。在内部业务中文场景类的指标上，PP-DocBee也高于目前的热门开源和闭源模型。
PP-DocBee-7B	推理模型	15.8	-
PP-DocBee2-3B	推理模型	7.6	852	PP-DocBee2 是飞桨团队自研的一款专注于文档理解的多模态大模型，在PP-DocBee的基础上进一步优化了基础模型，并引入了新的数据优化方案，提高了数据质量，使用自研数据合成策略生成的少量的47万数据便使得PP-DocBee2在中文文档理解任务上表现更佳。在内部业务中文场景类的指标上，PP-DocBee2相较于PP-DocBee提升了约11.4%，同时也高于目前的同规模热门开源和闭源模型。

注：以上模型总分为内部评估集模型测试结果，内部评估集所有图像分辨率 (height, width) 为 (1680,1204)，共1196条数据，包括了财报、法律法规、理工科论文、说明书、文科论文、合同、研报等场景，暂时未有计划公开。

如果您更注重模型的精度，请选择精度较高的模型；如果您更在意模型的推理速度，请选择推理速度较快的模型；如果您关注模型的存储大小，请选择存储体积较小的模型。

2. 快速开始¶

在本地使用文档理解产线前，请确保您已经按照安装教程完成了wheel包安装。安装完成后，可以在本地使用命令行体验或 Python 集成。

2.1 命令行方式体验¶

一行命令即可快速体验 doc_understanding 产线效果：

paddleocr doc_understanding -i "{'image': 'https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/medal_table.png', 'query': '识别这份表格的内容, 以markdown格式输出'}"

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

参数	参数说明	参数类型	默认值
`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`
`save_path`	指定推理结果文件保存的路径。如果设置为`None`, 推理结果将不会保存到本地。	`str`	`None`
`doc_understanding_model_name`	文档理解模型的名称。如果设置为`None`, 将会使用产线默认模型。	`str`	`None`
`doc_understanding_model_dir`	文档理解模型的目录路径。如果设置为`None`, 将会下载官方模型。	`str`	`None`
`doc_understanding_batch_size`	文档理解模型的批处理大小。如果设置为 `None`, 将默认设置批处理大小为`1`。	`int`	`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`
`enable_hpi`	是否启用高性能推理。	`bool`	`False`
`use_tensorrt`	是否使用 TensorRT 进行推理加速。	`bool`	`False`
`min_subgraph_size`	最小子图大小，用于优化模型子图的计算。	`int`	`3`
`precision`	计算精度，如 fp32、fp16。	`str`	`fp32`
`enable_mkldnn`	是否启用 MKL-DNN 加速库。如果设置为`None`, 将默认启用。	`bool`	`None`
`cpu_threads`	在 CPU 上进行推理时使用的线程数。	`int`	`8`
`paddlex_config`	PaddleX产线配置文件路径。	`str`	`None`

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

{'res': {'image': 'https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/medal_table.png', 'query': '识别这份表格的内容, 以markdown格式输出', 'result': '| 名次 | 国家/地区 | 金牌 | 银牌 | 铜牌 | 奖牌总数 |\n| --- | --- | --- | --- | --- | --- |\n| 1 | 中国（CHN） | 48 | 22 | 30 | 100 |\n| 2 | 美国（USA） | 36 | 39 | 37 | 112 |\n| 3 | 俄罗斯（RUS） | 24 | 13 | 23 | 60 |\n| 4 | 英国（GBR） | 19 | 13 | 19 | 51 |\n| 5 | 德国（GER） | 16 | 11 | 14 | 41 |\n| 6 | 澳大利亚（AUS） | 14 | 15 | 17 | 46 |\n| 7 | 韩国（KOR） | 13 | 11 | 8 | 32 |\n| 8 | 日本（JPN） | 9 | 8 | 8 | 25 |\n| 9 | 意大利（ITA） | 8 | 9 | 10 | 27 |\n| 10 | 法国（FRA） | 7 | 16 | 20 | 43 |\n| 11 | 荷兰（NED） | 7 | 5 | 4 | 16 |\n| 12 | 乌克兰（UKR） | 7 | 4 | 11 | 22 |\n| 13 | 肯尼亚（KEN） | 6 | 4 | 6 | 16 |\n| 14 | 西班牙（ESP） | 5 | 11 | 3 | 19 |\n| 15 | 牙买加（JAM） | 5 | 4 | 2 | 11 |\n'}}

2.2 Python脚本方式集成¶

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

from paddleocr import DocUnderstanding

pipeline = DocUnderstanding()
output = pipeline.predict(
    {
        "image": "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/medal_table.png",
        "query": "识别这份表格的内容, 以markdown格式输出"
    }
)
for res in output:
    res.print() ## 打印预测的结构化输出
    res.save_to_json("./output/")

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

（1）通过 DocUnderstanding() 实例化文档理解产线产线对象，具体参数说明如下：

参数	参数说明	参数类型	默认值
`doc_understanding_model_name`	文档理解模型的名称。如果设置为`None`, 将会使用产线默认模型。	`str`	`None`
`doc_understanding_model_dir`	文档理解模型的目录路径。如果设置为`None`, 将会下载官方模型。	`str`	`None`
`doc_understanding_batch_size`	文档理解模型的批处理大小。如果设置为 `None`, 将默认设置批处理大小为`1`。	`int`	`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`
`enable_hpi`	是否启用高性能推理。	`bool`	`False`
`use_tensorrt`	是否使用 TensorRT 进行推理加速。	`bool`	`False`
`min_subgraph_size`	最小子图大小，用于优化模型子图的计算。	`int`	`3`
`precision`	计算精度，如 fp32、fp16。	`str`	`fp32`
`enable_mkldnn`	是否启用 MKL-DNN 加速库。如果设置为`None`, 将默认启用。	`bool`	`None`
`cpu_threads`	在 CPU 上进行推理时使用的线程数。	`int`	`8`
`paddlex_config`	PaddleX产线配置文件路径。	`str`	`None`

（2）调用文档理解产线产线对象的 predict() 方法进行推理预测，该方法会返回一个结果列表。

另外，产线还提供了 predict_iter() 方法。两者在参数接受和结果返回方面是完全一致的，区别在于 predict_iter() 返回的是一个 generator，能够逐步处理和获取预测结果，适合处理大型数据集或希望节省内存的场景。可以根据实际需求选择使用这两种方法中的任意一种。

以下是 predict() 方法的参数及其说明：

参数	参数说明	参数类型	默认值
`input`	待预测数据，目前仅支持字典类型的输入 Python Dict：如PP-DocBee的输入形式为: `{"image":/path/to/image, "query": user question}` ,分别表示输入的图像和对应的用户问题	`Python Dict`
`device`	与实例化时的参数相同。	`str`	`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`

调用print() 方法会将结果打印到终端，打印到终端的内容解释如下：
- image: (str) 图像的输入路径
- query: (str) 针对输入图像的问题
- result: (str) 模型的输出结果
调用save_to_json() 方法会将上述内容保存到指定的save_path中，如果指定为目录，则保存的路径为save_path/{your_img_basename}_res.json，如果指定为文件，则直接保存到该文件中。
此外，也支持通过属性获取带结果的可视化图像和预测结果，具体如下：

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

json 属性获取的预测结果为dict类型的数据，相关内容与调用 save_to_json() 方法保存的内容一致。

3. 开发集成/部署¶

如果产线可以达到您对产线推理速度和精度的要求，您可以直接进行开发集成/部署。

若您需要将产线直接应用在您的Python项目中，可以参考 2.2 Python脚本方式中的示例代码。

此外，PaddleOCR 也提供了其他两种部署方式，详细说明如下：

🚀 高性能推理：在实际生产环境中，许多应用对部署策略的性能指标（尤其是响应速度）有着较严苛的标准，以确保系统的高效运行与用户体验的流畅性。为此，PaddleOCR 提供高性能推理功能，旨在对模型推理及前后处理进行深度性能优化，实现端到端流程的显著提速，详细的高性能推理流程请参考高性能推理。

☁️ 服务化部署：服务化部署是实际生产环境中常见的一种部署形式。通过将推理功能封装为服务，客户端可以通过网络请求来访问这些服务，以获取推理结果。详细的产线服务化部署流程请参考服务化部署。

以下是基础服务化部署的API参考与多语言服务调用示例：

API参考

对于服务提供的主要操作：

HTTP请求方法为POST。
请求体和响应体均为JSON数据（JSON对象）。
当请求处理成功时，响应状态码为200，响应体的属性如下：

名称	类型	含义
`logId`	`string`	请求的UUID。
`errorCode`	`integer`	错误码。固定为`0`。
`errorMsg`	`string`	错误说明。固定为`"Success"`。
`result`	`object`	操作结果。

当请求处理未成功时，响应体的属性如下：

名称	类型	含义
`logId`	`string`	请求的UUID。
`errorCode`	`integer`	错误码。与响应状态码相同。
`errorMsg`	`string`	错误说明。

服务提供的主要操作如下：

infer

对输入消息进行推理生成响应。

POST /document-understanding

说明以上接口别名/chat/completion，openai兼容的接口

请求体的属性如下：

名称	类型	含义	是否必填	默认值
`model`	`string`	要使用的模型名称	是	-
`messages`	`array`	对话消息列表	是	-
`max_tokens`	`integer`	生成的最大token数	否	1024
`temperature`	`float`	采样温度	否	0.1
`top_p`	`float`	核心采样概率	否	0.95
`stream`	`boolean`	是否流式输出	否	false
`max_image_tokens`	`int`	图像的最大输入token数	否	None

messages中的每个元素为一个object，具有如下属性：

名称	类型	含义	是否必填
`role`	`string`	消息角色（user/assistant/system）	是
`content`	`string`或`array`	消息内容（文本或图文混合）	是

当content为数组时，每个元素为一个object，具有如下属性：

名称	类型	含义	是否必填	默认值
`type`	`string`	内容类型（text/image_url）	是	-
`text`	`string`	文本内容（当type为text时）	条件必填	-
`image_url`	`string`或`object`	图片URL或对象（当type为image_url时）	条件必填	-

当image_url为对象时，具有如下属性：

名称	类型	含义	是否必填	默认值
`url`	`string`	图片URL	是	-
`detail`	`string`	图片细节处理方式（low/high/auto）	否	auto

请求处理成功时，响应体的result具有如下属性：

名称	类型	含义
`id`	`string`	请求ID
`object`	`string`	对象类型（chat.completion）
`created`	`integer`	创建时间戳
`choices`	`array`	生成结果选项
`usage`	`object`	token使用情况

choices中的每个元素为一个Choice对象，具有如下属性：

名称	类型	含义	可选值
`finish_reason`	`string`	模型停止生成token的原因	`stop`（自然停止） `length`（达到最大token数） `tool_calls`（调用了工具） `content_filter`（内容过滤） `function_call`（调用了函数，已弃用）
`index`	`integer`	选项在列表中的索引	-
`logprobs`	`object` \| `null`	选项的log概率信息	-
`message`	`ChatCompletionMessage`	模型生成的聊天消息	-

message对象具有如下属性：

名称	类型	含义	备注
`content`	`string` \| `null`	消息内容	可能为空
`refusal`	`string` \| `null`	模型生成的拒绝消息	当内容被拒绝时提供
`role`	`string`	消息作者角色	固定为`"assistant"`
`audio`	`object` \| `null`	音频输出数据	当请求音频输出时提供了解更多
`function_call`	`object` \| `null`	应调用的函数名称和参数	已弃用，推荐使用`tool_calls`
`tool_calls`	`array` \| `null`	模型生成的工具调用	如函数调用等

usage对象具有如下属性：

名称	类型	含义
`prompt_tokens`	`integer`	提示token数
`completion_tokens`	`integer`	生成token数
`total_tokens`	`integer`	总token数

result示例如下：

{
    "id": "ed960013-eb19-43fa-b826-3c1b59657e35",
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "message": {
                "content": "| 名次 | 国家/地区 | 金牌 | 银牌 | 铜牌 | 奖牌总数 |\n| --- | --- | --- | --- | --- | --- |\n| 1 | 中国（CHN） | 48 | 22 | 30 | 100 |\n| 2 | 美国（USA） | 36 | 39 | 37 | 112 |\n| 3 | 俄罗斯（RUS） | 24 | 13 | 23 | 60 |\n| 4 | 英国（GBR） | 19 | 13 | 19 | 51 |\n| 5 | 德国（GER） | 16 | 11 | 14 | 41 |\n| 6 | 澳大利亚（AUS） | 14 | 15 | 17 | 46 |\n| 7 | 韩国（KOR） | 13 | 11 | 8 | 32 |\n| 8 | 日本（JPN） | 9 | 8 | 8 | 25 |\n| 9 | 意大利（ITA） | 8 | 9 | 10 | 27 |\n| 10 | 法国（FRA） | 7 | 16 | 20 | 43 |\n| 11 | 荷兰（NED） | 7 | 5 | 4 | 16 |\n| 12 | 乌克兰（UKR） | 7 | 4 | 11 | 22 |\n| 13 | 肯尼亚（KEN） | 6 | 4 | 6 | 16 |\n| 14 | 西班牙（ESP） | 5 | 11 | 3 | 19 |\n| 15 | 牙买加（JAM） | 5 | 4 | 2 | 11 |\n",
                "role": "assistant"
            }
        }
    ],
    "created": 1745218041,
    "model": "pp-docbee",
    "object": "chat.completion"
}

多语言调用服务示例

Python

openai接口调用示例

import base64
from openai import OpenAI

API_BASE_URL = "http://0.0.0.0:8080"

# 初始化OpenAI客户端
client = OpenAI(
    api_key='xxxxxxxxx',
    base_url=f'{API_BASE_URL}'
)

#图片转base64函数
def encode_image(image_path):
  with open(image_path, "rb") as image_file:
    return base64.b64encode(image_file.read()).decode('utf-8')

#输入图片路径
image_path = "medal_table.png"

#原图片转base64
base64_image = encode_image(image_path)

#提交信息至PP-DocBee模型
response = client.chat.completions.create(
    model="pp-docbee",#选择模型
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content":[
                {
                    "type": "text",
                    "text": "识别这份表格的内容,输出html格式的内容"
                },
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}
                },
            ]
        },
    ],
)
content = response.choices[0].message.content
print('Reply:', content)

4. 二次开发¶

当前产线暂时不支持微调训练，仅支持推理集成。关于该产线的微调训练，计划在未来支持。