文档理解产线使用教程¶

1. 文档理解产线介绍¶

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

文档理解产线中包含了文档类视觉语言模型模块，您可以根据下方的基准测试数据选择使用的模型。

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

文档类视觉语言模型模块（可选）：

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

2. 快速开始¶

2.1 本地体验¶

❗ 在本地使用文档理解产线前，请确保您已经按照PaddleX本地安装教程完成了PaddleX的wheel包安装。如果您希望选择性安装依赖，请参考安装教程中的相关说明。该产线对应的依赖分组为 multimodal。

2.1.1 Python脚本方式集成¶

文档理解产线可以通过几行代码即可完成产线的快速推理，推理代码如下：

from paddlex import create_pipeline
pipeline = create_pipeline(pipeline="doc_understanding")
output = pipeline.predict(
    {
        "image": "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/medal_table.png",
        "query": "识别这份表格的内容"
    }
)
for res in output:
    res.print()
    res.save_to_json("./output/")

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

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

参数	参数说明	参数类型	默认值
`pipeline`	产线名称或是产线配置文件路径。如为产线名称，则必须为 PaddleX 所支持的产线。	`str`	`None`
`config`	产线具体的配置信息（如果和`pipeline`同时设置，优先级高于`pipeline`，且要求产线名和`pipeline`一致）。	`dict[str, Any]`	`None`
`device`	产线推理设备。支持指定GPU具体卡号，如“gpu:0”，其他硬件具体卡号，如“npu:0”，CPU如“cpu”。	`str`	`None`
`use_hpip`	是否启用高性能推理插件。如果为 `None`，则使用配置文件中的配置。目前暂不支持。	`bool` \| `None`	无	`None`
`hpi_config`	高性能推理配置。目前暂不支持。	`dict` \| `None`	无	`None`

（2）调用文档理解产线产线对象的 predict() 方法进行推理预测。该方法将返回一个 generator。以下是 predict() 方法的参数及其说明：

参数	参数说明	参数类型	可选项	默认值
`input`	待预测数据，目前仅支持字典类型的输入	`Python Dict`	Python Dict：如PP-DocBee的输入形式为: `{"image":/path/to/image, "query": user question}` ,分别表示输入的图像和对应的用户问题	`None`
`device`	产线推理设备	`str\|None`	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 设备；	`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() 方法保存的内容一致。

此外，您可以获取文档理解产线产线配置文件，并加载配置文件进行预测。可执行如下命令将结果保存在 my_path 中：

paddlex --get_pipeline_config doc_understanding --save_path ./my_path

若您获取了配置文件，即可对文档理解产线各项配置进行自定义，只需要修改 create_pipeline 方法中的 pipeline 参数值为产线配置文件路径即可。示例如下：

from paddlex import create_pipeline
pipeline = create_pipeline(pipeline="./my_path/doc_understanding.yaml")
output = pipeline.predict(
    {
        "image": "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/medal_table.png",
        "query": "识别这份表格的内容"
    }
)
for res in output:
    res.print()
    res.save_to_json("./output/")

注：配置文件中的参数为产线初始化参数，如果希望更改文档理解产线初始化参数，可以直接修改配置文件中的参数，并加载配置文件进行预测。同时，CLI 预测也支持传入配置文件，--pipeline 指定配置文件的路径即可。

3. 开发集成/部署¶

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

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

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

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

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

以下是基础服务化部署的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)

📱 端侧部署：端侧部署是一种将计算和数据处理功能放在用户设备本身上的方式，设备可以直接处理数据，而不需要依赖远程的服务器。PaddleX 支持将模型部署在 Android 等端侧设备上，详细的端侧部署流程请参考PaddleX端侧部署指南。您可以根据需要选择合适的方式部署模型产线，进而进行后续的 AI 应用集成。

4. 二次开发¶

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

5. 多硬件支持¶

当前产线暂时仅支持GPU和CPU推理。关于该产线对于更多硬件的适配，计划在未来支持。