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

文档理解产线中包含以下1个模块。每个模块均可独立进行训练和推理，并包含多个模型。有关详细信息，请点击相应模块以查看文档。 - [文档类视觉语言模型模块](../module_usage/doc_vlm.md) 在本产线中，您可以根据下方的基准测试数据选择使用的模型。 > 推理耗时仅包含模型推理耗时，不包含前后处理耗时。

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

模型	模型下载链接	模型存储大小（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. 快速开始在本地使用文档理解产线前，请确保您已经按照[安装教程](../installation.md)完成了wheel包安装。如果您希望选择性安装依赖，请参考安装教程中的相关说明。该产线对应的依赖分组为 `doc-parser`。安装完成后，可以在本地使用命令行体验或 Python 集成。 **请注意，如果在执行过程中遇到程序失去响应、程序异常退出、内存资源耗尽、推理速度极慢等问题，请尝试参考文档调整配置，例如关闭不需要使用的功能或使用更轻量的模型。** ### 2.1 命令行方式体验一行命令即可快速体验 doc_understanding 产线效果： ```bash 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`	含义：文档理解模型的batch size。说明：如果不设置，将默认设置batch size为`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：如 `metax_gpu:0` 表示使用第 1 块沐曦 GPU 进行推理；天数 GPU：如 `iluvatar_gpu:0` 表示使用第 1 块天数 GPU 进行推理；如果不设置，将默认使用产线初始化的该参数值，初始化时，会优先使用本地的 GPU 0号设备，如果没有，则使用 CPU 设备。	`str`
`engine`	含义：推理引擎。说明：支持 `None`（默认值）、`paddle`、`paddle_dynamic`。保持为默认值 `None` 时，PaddleOCR 保留旧版本的行为，在大多数配置下等价于 `paddle`。详细说明、取值、兼容性规则与示例请参见推理引擎与配置说明。	`str\|None`	`None`
`enable_hpi`	含义：是否启用高性能推理。	`bool`	`None`
`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`	`10`
`paddlex_config`	含义：PaddleX产线配置文件路径。	`str`

运行结果会被打印到终端上，默认配置的 doc_understanding 产线的运行结果如下： ```bash {'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脚本方式集成命令行方式是为了快速体验查看效果，一般来说，在项目中，往往需要通过代码集成，您可以通过几行代码即可完成产线的快速推理，推理代码如下： ```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`	`None`
`doc_understanding_model_dir`	含义：文档理解模型的目录路径。说明：如果不设置，将会下载官方模型。	`str\|None`	`None`
`doc_understanding_batch_size`	含义：文档理解模型的batch size。说明：如果设置为`None`，将默认设置batch size为`1`。	`int\|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 进行推理；沐曦 GPU：如 `metax_gpu:0` 表示使用第 1 块沐曦 GPU 进行推理；天数 GPU：如 `iluvatar_gpu:0` 表示使用第 1 块天数 GPU 进行推理； None：如果设置为`None`，将默认使用产线初始化的该参数值，初始化时，会优先使用本地的 GPU 0号设备，如果没有，则使用 CPU 设备。	`str\|None`	`None`
`engine`	含义：推理引擎。说明：支持 `None`（默认值）、`paddle`、`paddle_dynamic`。保持为默认值 `None` 时，PaddleOCR 保留旧版本的行为，在大多数配置下等价于 `paddle`。详细说明、取值、兼容性规则与示例请参见推理引擎与配置说明。	`str\|None`	`None`
`engine_config`	含义：推理引擎配置。说明：推荐与 `engine` 搭配使用。详细字段、兼容性规则与示例请参见推理引擎与配置说明。	`dict\|None`	`None`
`paddlex_config`	含义：PaddleX产线配置文件路径。	`str\|None`	`None`

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

参数	参数说明	参数类型	默认值
`input`	含义：待预测数据，目前仅支持dict类型的输入。说明： 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脚本方式](#22-python) 中的示例代码。此外，PaddleOCR 也提供了其他两种部署方式，详细说明如下： 🚀 高性能推理：在实际生产环境中，许多应用对部署策略的性能指标（尤其是响应速度）有着较严苛的标准，以确保系统的高效运行与用户体验的流畅性。为此，PaddleOCR 提供高性能推理功能，旨在对模型推理及前后处理进行深度性能优化，实现端到端流程的显著提速，详细的高性能推理流程请参考[高性能推理](../inference_deployment/local_inference/high_performance_inference.md)。 ☁️ 服务化部署：服务化部署是实际生产环境中常见的一种部署形式。通过将推理功能封装为服务，客户端可以通过网络请求来访问这些服务，以获取推理结果。详细的产线服务化部署流程请参考[服务化部署](../inference_deployment/serving/serving.md)。以下是基础服务化部署的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://127.0.0.1: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. 二次开发当前产线暂时不支持微调训练，仅支持推理集成。关于该产线的微调训练，计划在未来支持。