Transformers 中 PP-Chart2Table 图表转表格多模态模型实战指南

PP-Chart2Table 是 PaddlePaddle 团队开发、于 2026 年 3 月 20 日正式合入 🤗 Transformers 的开源多模态图表解析模型，面向中英文图表，可端到端地将柱状图、折线图、饼图等解析为结构化数据表格。本文以官方模型文档 pp_chart2table.md 为骨架，结合仓库内 配置实现、图像处理器与处理器实现 及 集成测试，带你掌握如何使用 Pipeline / AutoModel 完成单图与批量推理，并深入理解其底层视觉塔与语言模型融合结构及预处理管线。

模型概览：定位与核心技术

PP-Chart2Table（PaddlePaddle Chart to Table）是 PaddlePaddle 团队发布的多模态模型，专注于中英文图表解析任务。根据 模型文档 中的描述，其高性能主要来自三项技术设计：

1. 创新的“Shuffled Chart Data Retrieval”训练任务：通过打乱图表数据检索的训练范式，配合精细化的 token masking 策略，显著提升图表到数据表格的转换效率；
2. 先进的数据合成管线：以高质量种子数据为基座，结合 RAG（检索增强生成）与 LLM persona 设计，构建更丰富、更多样的训练集；
3. 两阶段蒸馏流程：面向大规模无标注且分布外（out-of-distribution，OOD）的真实场景数据，保证模型在真实世界数据上的鲁棒性与泛化能力。

在本文所处仓库中，PP-Chart2Table 拥有完整的模型目录实现与配套测试：src/transformers/models/pp_chart2table/、tests/models/pp_chart2table/。其中 modular_pp_chart2table.py 是模型的模块化定义源文件（仓库 CI 会由它自动生成其余 configuration_/image_processing_/processing_ 等文件），而 modeling 层则由 Got-OCR2 架构承载，这一点在后续“架构解读”与“Auto API 注册”部分会展开。

模型架构：视觉塔 + 语言模型的融合设计

模型文档 指出，PP-Chart2Table 采用多模态融合架构：

• Vision Tower（视觉塔）：负责图表图像的视觉特征抽取；
• Language Model（语言模型）：负责表格结构的文本序列生成；
• 二者协同实现端到端的图表→表格转换。

从源码中可以印证这一设计并补充关键细节：

• 在配置类中，PPChart2TableConfig 通过 sub_configs 声明了两个子配置：文本侧使用 text_config（经由 CONFIG_MAPPING 解析为 Qwen2 语言模型配置），视觉侧使用 PPChart2TableVisionConfig（base_config_key = "vision_config"），见 configuration_pp_chart2table.py；
• 当 text_config 未指定时，默认按 Qwen2 参数构建：vocab_size=151860、hidden_size=1024、intermediate_size=2816、24 层 Transformer、16 个注意力头、最大位置编码长度 32768、RoPE theta 为 1e6，且启用 KV cache（use_cache=True）；
• 值得注意的是，PPChart2TableConfig 虽拥有独立的 model_type = "pp_chart2table" 与独立权重，但其底层生成架构复用 Got-OCR2：其模块化文件中的示例明确注明“underlying architecture is Got Ocr 2”，modular_pp_chart2table.py 中 PPChart2TableConfig 直接继承自 GotOcr2Config；
• 视觉塔采用类 SAM 的 ViT 设计，核心参数在 PPChart2TableVisionConfig 中定义（详见下文配置速查表）。

快速上手：环境与模型加载

PP-Chart2Table 通过标准的 AutoModelForImageTextToText / AutoProcessor 加载。仓库中的注册关系如下：

• 建模自动映射："pp_chart2table" → GotOcr2ForConditionalGeneration（见 modeling_auto.py）；
• 配置自动映射："pp_chart2table" → PPChart2TableConfig、处理器映射 → PPChart2TableProcessor（见 auto_mappings.py 与 auto_mappings.py）；
• 图像处理器按后端注册了 PIL 版（PPChart2TableImageProcessorPil）与 torchvision 版（PPChart2TableImageProcessor）两套实现（见 auto_mappings.py）。

因此运行时只需安装较新版本的 transformers 与图像后端（Pillow 或 torchvision 之一），无需安装 PaddlePaddle 本体。使用的模型权重仓库名为 PaddlePaddle/PP-Chart2Table_safetensors，首次加载会自动下载权重与处理器配置。

单图推理：从图表到表格

模型文档 给出了两条等价路线：高层 Pipeline 与 底层 AutoModel。两种方式内部都依赖 PPChart2TableProcessor，它通过 chat template 在内部硬编码了 “Chart to table” 指令，因此用户只需按多模态对话（含图片 URL）的格式组织输入，无需手写任务提示词。

方式一：使用 Pipeline（推荐快速体验）

from transformers import pipeline


pipe = pipeline("image-text-to-text", model="PaddlePaddle/PP-Chart2Table_safetensors")

# PPChart2TableProcessor uses hardcoded "Chart to table" instruction internally via chat template
conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "image",
                "url": "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/chart_parsing_02.png",
            },
        ],
    },
]
result = pipe(text=conversation)
print(result[0]["generated_text"])

要点说明：

• pipeline("image-text-to-text", ...) 会自动装配合适的处理器与生成配置；
• conversation 采用 ChatML 风格的多模态对话结构，content 内可混排图片与文本；
• 此处 url 为在线图片地址（PaddleX 官方演示图）。Pipeline 会负责下载图片并喂给图像处理器。

方式二：使用 AutoModel（更可控）

from transformers import AutoModelForImageTextToText, AutoProcessor


model_path = "PaddlePaddle/PP-Chart2Table_safetensors"
model = AutoModelForImageTextToText.from_pretrained(
    model_path,
    device_map="auto",
)
processor = AutoProcessor.from_pretrained(model_path)

# PPChart2TableProcessor uses hardcoded "Chart to table" instruction internally via chat template
conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "image",
                "url": "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/chart_parsing_02.png",
            },
        ],
    },
]

inputs = processor.apply_chat_template(
    conversation,
    tokenize=True,
    add_generation_prompt=True,
    truncation=True,
    return_dict=True,
    return_tensors="pt",
).to(model.device)

generated_ids = model.generate(**inputs, do_sample=False, max_new_tokens=256)
generated_ids_trimmed = [out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)]
result = processor.batch_decode(generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False)
print(result)

这段代码的完整调用链，正是 集成测试 验证的真实路径：processor.apply_chat_template(...tokenize=True...) → model.generate(...) → processor.batch_decode(...)。测试中还给出了该演示图预期的解析结果片段（简体中文表格行），例如 年份 | 单家五星级旅游饭店年平均营收 (百万元) | 单家五星级旅游饭店年平均利润 (百万元)，说明模型输出是使用 | 分隔单元格的 Markdown 风格表格文本。

参数解读：

参数	作用
apply_chat_template	将多模态对话按模型的 chat template 组装为完整提示（含硬编码的 “Chart to table” 指令）
tokenize=True	同时完成图像预处理与文本 tokenize（由 processor 内部 image_processor + tokenizer 协作）
add_generation_prompt=True	追加生成起始符，为模型生成做准备
do_sample=False	采用贪心解码，保证表格解析结果确定性、可复现
max_new_tokens	限制生成的新 token 数；图表规模较大时可适当调高（如 256）
generated_ids_trimmed	截去输入前缀，仅保留新生成的部分再解码

批量推理

图表解析往往需要批处理多张图片以提升吞吐。apply_chat_template 天然支持列表输入，Pipeline 同样支持传入对话列表。

使用 Pipeline

from transformers import pipeline


pipe = pipeline("image-text-to-text", model="PaddlePaddle/PP-Chart2Table_safetensors")

# PPChart2TableProcessor uses hardcoded "Chart to table" instruction internally via chat template
conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "image",
                "url": "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/chart_parsing_02.png",
            },
        ],
    },
]
result = pipe(text=[conversation, conversation])
print(result[0][0]["generated_text"])

注意：批量时 result[0] 是“每个输入的结果列表”，因此访问 result[0][0] 取出第一条对话的生成文本。

使用 AutoModel

from transformers import AutoModelForImageTextToText, AutoProcessor


model_path = "PaddlePaddle/PP-Chart2Table_safetensors"
model = AutoModelForImageTextToText.from_pretrained(
    model_path,
    device_map="auto",
)
processor = AutoProcessor.from_pretrained(model_path)

# PPChart2TableProcessor uses hardcoded "Chart to table" instruction internally via chat template
conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "image",
                "url": "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/chart_parsing_02.png",
            },
        ],
    },
]

batch_conversation = [conversation, conversation]
inputs = processor.apply_chat_template(
    batch_conversation,
    tokenize=True,
    add_generation_prompt=True,
    truncation=True,
    return_dict=True,
    return_tensors="pt",
).to(model.device)

generated_ids = model.generate(**inputs, do_sample=False, max_new_tokens=256)
generated_ids_trimmed = [out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)]
result = processor.batch_decode(generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False)
print(result)

底层路线把整个 batch 统一走一次 apply_chat_template 得到批量 inputs，之后逐条裁剪前缀并解码。集成测试 中对两条相同对话组成的 batch 给出了逐条一致的解析断言，可用于快速自测批量路径的可用性。

提示：批量推理时不同图片最好保持相近分辨率与复杂度。processor 侧已默认开启 truncation=True，可避免超长文本溢出；若显存有限，可减小 batch 或调低 max_new_tokens。

预处理管线源码解读

图像处理器：PPChart2TableImageProcessor 与 PIL 版

PP-Chart2Table 拥有两套后端一致的图像处理器：

• PPChart2TableImageProcessor：基于 TorchvisionBackend 的实现，见 image_processing_pp_chart2table.py；
• PPChart2TableImageProcessorPil：基于 Pillow 的纯 Python 实现（无需额外编译依赖），见 image_processing_pil_pp_chart2table.py。

两者的预处理默认值完全一致（定义于模块化源文件 modular_pp_chart2table.py）：

属性	默认值	说明
size	{"height": 1024, "width": 1024}	将图表缩放到 1024×1024（与视觉塔 image_size=1024 对齐）
resample	3（BICUBIC）	缩放时使用的重采样算法
do_resize / do_rescale / do_normalize	均为 True	依次执行 resize → 像素值缩放 → 归一化
image_mean	[0.48145466, 0.4578275, 0.40821073]	归一化均值（与 CLIP 系列视觉编码器一致的统计量）
image_std	[0.26862954, 0.26130258, 0.27577711]	归一化标准差

这些默认值在绝大多数真实图表图片上无需改动；若输入为超长图表，建议自行用长边等比缩放再调用，而非直接改变 size，以免破坏归一化语义。

处理器：PPChart2TableProcessor

PPChart2TableProcessor 继承自 ProcessorMixin，将图像处理器与 tokenizer 打包为统一入口，见 processing_pp_chart2table.py。其模块化源码还显式约束了调用方式：当 images 或 text 任一项缺失时直接抛出 ValueError——即“有图有文”是图表解析的硬性前提，这与其端到端“图→表”任务性质一致。

此外，模块化定义中两个图像处理类与处理器类都带有 auto_docstring(checkpoint="PaddlePaddle/PP-Chart2Table_safetensors")，意味着 help() 与类文档字符串会自动嵌入该权重仓库的使用说明与超参上下文，方便交互式查阅。

配置速查：PPChart2TableConfig 关键字段

从 configuration_pp_chart2table.py 可提取整份顶层配置默认值：

字段	默认值	含义
model_type	"pp_chart2table"	注册的模型类型标识，Auto API 据此分发
vision_config	PPChart2TableVisionConfig()	视觉塔子配置（缺省时自动构建）
text_config	默认 Qwen2 配置	文本侧语言模型子配置（缺省时自动按 Qwen2 参数构建）
image_token_index	151859	图像占位 token 在词表中的索引（与 vocab_size=151860 呼应）
image_seq_length	576	每张图映射成的视觉 token 数量
tie_word_embeddings	True	输入/输出词嵌入共享

其中 attribute_map 将 image_token_id 映射到 image_token_index，用于兼容历史字段名。

视觉塔子配置 PPChart2TableVisionConfig 的默认值速查：

字段	默认值	含义
hidden_size	768	Transformer encoder 隐藏维度
output_channels	256	Patch Encoder 输出通道维度
num_hidden_layers	12	编码器层数
num_attention_heads	12	注意力头数
num_channels	3	输入图像通道数（RGB）
image_size	1024	输入图像尺寸
patch_size	16	Patch 尺寸（1024/16 即视觉 token 网格，与 576 视觉 token 的分配逻辑相关）
use_abs_pos / use_rel_pos	True / True	是否使用绝对/相对位置编码
window_size	14	相对位置注意力窗口大小
global_attn_indexes	[2, 5, 8, 11]	采用全局注意力的层索引（与 SAM 风格分层注意力一致）
mlp_dim	3072	Transformer encoder 中 MLP 维度

关于图像分辨率与 image_seq_length 的关系，可以推断：配置将视觉 token 数固定为 576，输入图片经图像处理器统一 resize 至 1024×1024 后再 patch 化，视觉 token 总量在预处理端被规整为固定长度，从而为文本侧解码提供稳定的视觉上下文长度。

进阶话题与实用建议

• 如何查看完整文档字符串：PPChart2TableConfig、PPChart2TableImageProcessor、PPChart2TableImageProcessorPil、PPChart2TableProcessor 在 模型文档 中通过 [[autodoc]] 指令自动注入 docstring，可在 Python 中调用 help(...) 查看每个类/方法的完整签名、默认值与逐参说明。
• 分布式/多卡加载：官方示例已使用 device_map="auto"，配合 device_map 可自动切分模型权重以适配多卡；generated_ids_trimmed 的写法保证了解码结果与输入严格对齐，这一模式在 batch 场景同样适用。
• 结合 PaddleX 生态：模型权重托管于 PaddlePaddle/PP-Chart2Table_safetensors，但 Transformers 侧为“仅推理加载”的独立实现（自带 safetensors 权重）。需要训练或微调时，应以 PaddleX/PaddleNLP 侧说明为准，本仓库实现定位为 Transformers 生态下的标准推理接入。
• 可靠性验证：仓库自带 建模集成测试、预处理测试 与 图像处理测试，分别覆盖 chat template 组装、单图/批量解码结果与图像预处理正确性，可作为接入生产前的回归基准。

结语

PP-Chart2Table 在 Transformers 仓库中的落地是一次完整的“模型文档 + 模块化定义 + Auto 注册 + 双后端图像预处理 + 集成测试”工程实践。通过 pipeline("image-text-to-text") 一行即可完成中英文图表解析，而底层 AutoModelForImageTextToText + apply_chat_template 的调用链则在提供细粒度控制的同时，与仓库集成测试严格对齐，便于工程验证与二次封装。无论你是做财务图表抽取、科研数据还原还是文档结构化，都可以从本文的配置速查与源码指引出发，快速把它接入自己的数据处理流水线。