PaddleOCR/docs/version3.x/pipeline_usage/doc_understanding.md

comments
true

文档理解产线使用教程

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	待预测数据，必填。如"{'image': 'https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/medal_table.png', 'query': '识别这份表格的内容, 以markdown格式输出'}"。	str
save_path	指定推理结果文件保存的路径。如果不设置，推理结果将不会保存到本地。	str
doc_understanding_model_name	文档理解模型的名称。如果不设置，将会使用产线默认模型。	str
doc_understanding_model_dir	文档理解模型的目录路径。如果不设置，将会下载官方模型。	str
doc_understanding_batch_size	文档理解模型的批处理大小。如果设置为None，将默认设置批处理大小为1。	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	是否使用 TensorRT 进行推理加速。	bool	False
min_subgraph_size	最小子图大小，用于优化模型子图的计算。	int	3
precision	计算精度，如 fp32、fp16。	str	fp32
enable_mkldnn	是否启用 MKL-DNN 加速库。	bool	True
cpu_threads	在 CPU 上进行推理时使用的线程数。	int	8
paddlex_config	PaddleX产线配置文件路径。	str

运行结果会被打印到终端上，默认配置的 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 加速库。	bool	True
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

（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. 二次开发

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