文档理解产线使用教程¶
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%，同时也高于目前的同规模热门开源和闭源模型。 |
如果您更注重模型的精度，请选择精度较高的模型；如果您更在意模型的推理速度，请选择推理速度较快的模型；如果您关注模型的存储大小，请选择存储体积较小的模型。
2. 快速开始¶
在本地使用文档理解产线前，请确保您已经按照安装教程完成了wheel包安装。如果您希望选择性安装依赖，请参考安装教程中的相关说明。该产线对应的依赖分组为 doc-parser。安装完成后，可以在本地使用命令行体验或 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 |
文档理解模型的batch size。如果设置为None，将默认设置batch size为1。 |
int |
|
device |
用于推理的设备。支持指定具体卡号：
|
str |
|
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 |
None |
doc_understanding_model_dir |
文档理解模型的目录路径。如果设置为None，将会下载官方模型。 |
str|None |
None |
doc_understanding_batch_size |
文档理解模型的batch size。如果设置为None，将默认设置batch size为1。 |
int|None |
None |
device |
用于推理的设备。支持指定具体卡号：
|
str|None |
None |
paddlex_config |
PaddleX产线配置文件路径。 | str|None |
None |
（2）调用 文档理解产线 产线对象的 predict() 方法进行推理预测，该方法会返回一个结果列表。
另外，产线还提供了 predict_iter() 方法。两者在参数接受和结果返回方面是完全一致的，区别在于 predict_iter() 返回的是一个 generator，能够逐步处理和获取预测结果，适合处理大型数据集或希望节省内存的场景。可以根据实际需求选择使用这两种方法中的任意一种。
以下是 predict() 方法的参数及其说明：
| 参数 | 参数说明 | 参数类型 | 默认值 |
|---|---|---|---|
input |
待预测数据，目前仅支持dict类型的输入
|
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://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. 二次开发¶
当前产线暂时不支持微调训练，仅支持推理集成。关于该产线的微调训练，计划在未来支持。