Transformers 4.37 中文文档（八十六）（1）

原文：huggingface.co/docs/transformers

DePlot

原文：huggingface.co/docs/transformers/v4.37.2/en/model_doc/deplot

概述

DePlot 是由 Fangyu Liu, Julian Martin Eisenschlos, Francesco Piccinno,  Syrine Krichene, Chenxi Pang, Kenton Lee, Mandar Joshi, Wenhu Chen,  Nigel Collier, Yasemin Altun 在论文DePlot: One-shot visual language reasoning by plot-to-table translation中提出的。

该论文的摘要如下：

图表等视觉语言在人类世界中无处不在。理解图表和图表需要强大的推理能力。先前的最先进（SOTA）模型至少需要数万个训练示例，它们的推理能力仍然非常有限，特别是对于复杂的人类编写的查询。本文提出了视觉语言推理的第一个一次性解决方案。我们将视觉语言推理的挑战分解为两个步骤：（1）图表到文本的翻译，以及（2）对翻译文本进行推理。该方法的关键是一个名为  DePlot 的模态转换模块，它将图表或图表的图像转换为线性化表格。然后可以直接使用 DePlot  的输出来提示预训练的大型语言模型（LLM），利用 LLM 的少量推理能力。为了获得  DePlot，我们通过建立统一的任务格式和度量标准，对绘图到表格任务进行了标准化，并在此任务上端到端地训练 DePlot。然后可以将  DePlot 与 LLM 一起以即插即用的方式使用。与在超过 28k 数据点上微调的 SOTA 模型相比，DePlot+LLM  仅通过一次提示就实现了对人类编写查询的图表 QA 任务的微调 SOTA 的 24.0%的改进。

DePlot 是使用Pix2Struct架构训练的模型。您可以在Pix2Struct 文档中找到有关Pix2Struct的更多信息。DePlot 是Pix2Struct架构的视觉问答子集。它在图像上呈现输入问题并预测答案。

使用示例

目前 DePlot 有一个检查点可用：

• google/deplot：在 ChartQA 数据集上微调的 DePlot

from transformers import AutoProcessor, Pix2StructForConditionalGeneration
import requests
from PIL import Image
model = Pix2StructForConditionalGeneration.from_pretrained("google/deplot")
processor = AutoProcessor.from_pretrained("google/deplot")
url = "https://raw.githubusercontent.com/vis-nlp/ChartQA/main/ChartQA%20Dataset/val/png/5090.png"
image = Image.open(requests.get(url, stream=True).raw)
inputs = processor(images=image, text="Generate underlying data table of the figure below:", return_tensors="pt")
predictions = model.generate(**inputs, max_new_tokens=512)
print(processor.decode(predictions[0], skip_special_tokens=True))

微调

要微调 DePlot，请参考 pix2struct 的fine-tuning 笔记本。对于Pix2Struct模型，我们发现使用 Adafactor 和余弦学习率调度程序对模型进行微调可以实现更快的收敛：

from transformers.optimization import Adafactor, get_cosine_schedule_with_warmup
optimizer = Adafactor(self.parameters(), scale_parameter=False, relative_step=False, lr=0.01, weight_decay=1e-05)
scheduler = get_cosine_schedule_with_warmup(optimizer, num_warmup_steps=1000, num_training_steps=40000)

DePlot 是使用Pix2Struct架构训练的模型。有关 API 参考，请参阅Pix2Struct文档。

Donut

原文链接：huggingface.co/docs/transformers/v4.37.2/en/model_doc/donut

概述

Donut 模型是由 Geewook Kim、Teakgyu Hong、Moonbin Yim、Jeongyeon  Nam、Jinyoung Park、Jinyeong Yim、Wonseok Hwang、Sangdoo Yun、Dongyoon  Han、Seunghyun Park  提出的，用于执行文档理解任务，如文档图像分类、表单理解和视觉问答的图像变压器编码器和自回归文本变压器解码器。

该论文的摘要如下：

理解文档图像（例如发票）是一项核心但具有挑战性的任务，因为它需要复杂的功能，如阅读文本和对文档的整体理解。当前的视觉文档理解（VDU）方法将阅读文本的任务外包给现成的光学字符识别（OCR）引擎，并专注于使用  OCR 输出进行理解任务。尽管这种基于 OCR 的方法表现出有希望的性能，但它们存在以下问题：1）使用 OCR 的计算成本高；2）OCR  模型在语言或文档类型上的不灵活性；3）OCR 错误传播到后续过程。为了解决这些问题，在本文中，我们介绍了一种名为 Donut 的新型无 OCR  VDU 模型，代表文档理解变压器。作为无 OCR VDU  研究的第一步，我们提出了一个简单的架构（即变压器）和一个预训练目标（即交叉熵损失）。Donut  在概念上简单而有效。通过大量实验和分析，我们展示了一个简单的无 OCR VDU 模型 Donut，在速度和准确性方面在各种 VDU  任务上取得了最先进的性能。此外，我们提供了一个合成数据生成器，帮助模型在各种语言和领域中进行灵活的预训练。

Donut 高层概述。摘自原始论文。

此模型由nielsr贡献。原始代码可在此处找到。

使用提示

• 开始使用 Donut 的最快方法是查看教程笔记本，展示了如何在推理时使用模型以及在自定义数据上进行微调。
  
• Donut 始终在 VisionEncoderDecoder 框架内使用。
  

推理示例

Donut 的VisionEncoderDecoder模型接受图像作为输入，并利用 generate()来自动生成给定输入图像的文本。

DonutImageProcessor 类负责预处理输入图像，[XLMRobertaTokenizer/XLMRobertaTokenizerFast]解码生成的目标标记为目标字符串。DonutProcessor 将 DonutImageProcessor 和[XLMRobertaTokenizer/XLMRobertaTokenizerFast]包装成一个单一实例，既提取输入特征又解码预测的标记 ID。

• 逐步文档图像分类

>>> import re
>>> from transformers import DonutProcessor, VisionEncoderDecoderModel
>>> from datasets import load_dataset
>>> import torch
>>> processor = DonutProcessor.from_pretrained("naver-clova-ix/donut-base-finetuned-rvlcdip")
>>> model = VisionEncoderDecoderModel.from_pretrained("naver-clova-ix/donut-base-finetuned-rvlcdip")
>>> device = "cuda" if torch.cuda.is_available() else "cpu"
>>> model.to(device)
>>> # load document image
>>> dataset = load_dataset("hf-internal-testing/example-documents", split="test")
>>> image = dataset[1]["image"]
>>> # prepare decoder inputs
>>> task_prompt = "<s_rvlcdip>"
>>> decoder_input_ids = processor.tokenizer(task_prompt, add_special_tokens=False, return_tensors="pt").input_ids
>>> pixel_values = processor(image, return_tensors="pt").pixel_values
>>> outputs = model.generate(
...     pixel_values.to(device),
...     decoder_input_ids=decoder_input_ids.to(device),
...     max_length=model.decoder.config.max_position_embeddings,
...     pad_token_id=processor.tokenizer.pad_token_id,
...     eos_token_id=processor.tokenizer.eos_token_id,
...     use_cache=True,
...     bad_words_ids=[[processor.tokenizer.unk_token_id]],
...     return_dict_in_generate=True,
... )
>>> sequence = processor.batch_decode(outputs.sequences)[0]
>>> sequence = sequence.replace(processor.tokenizer.eos_token, "").replace(processor.tokenizer.pad_token, "")
>>> sequence = re.sub(r"<.*?>", "", sequence, count=1).strip()  # remove first task start token
>>> print(processor.token2json(sequence))
{'class': 'advertisement'}

• 逐步文档解析

>>> import re
>>> from transformers import DonutProcessor, VisionEncoderDecoderModel
>>> from datasets import load_dataset
>>> import torch
>>> processor = DonutProcessor.from_pretrained("naver-clova-ix/donut-base-finetuned-cord-v2")
>>> model = VisionEncoderDecoderModel.from_pretrained("naver-clova-ix/donut-base-finetuned-cord-v2")
>>> device = "cuda" if torch.cuda.is_available() else "cpu"
>>> model.to(device)
>>> # load document image
>>> dataset = load_dataset("hf-internal-testing/example-documents", split="test")
>>> image = dataset[2]["image"]
>>> # prepare decoder inputs
>>> task_prompt = "<s_cord-v2>"
>>> decoder_input_ids = processor.tokenizer(task_prompt, add_special_tokens=False, return_tensors="pt").input_ids
>>> pixel_values = processor(image, return_tensors="pt").pixel_values
>>> outputs = model.generate(
...     pixel_values.to(device),
...     decoder_input_ids=decoder_input_ids.to(device),
...     max_length=model.decoder.config.max_position_embeddings,
...     pad_token_id=processor.tokenizer.pad_token_id,
...     eos_token_id=processor.tokenizer.eos_token_id,
...     use_cache=True,
...     bad_words_ids=[[processor.tokenizer.unk_token_id]],
...     return_dict_in_generate=True,
... )
>>> sequence = processor.batch_decode(outputs.sequences)[0]
>>> sequence = sequence.replace(processor.tokenizer.eos_token, "").replace(processor.tokenizer.pad_token, "")
>>> sequence = re.sub(r"<.*?>", "", sequence, count=1).strip()  # remove first task start token
>>> print(processor.token2json(sequence))
{'menu': {'nm': 'CINNAMON SUGAR', 'unitprice': '17,000', 'cnt': '1 x', 'price': '17,000'}, 'sub_total': {'subtotal_price': '17,000'}, 'total': {'total_price': '17,000', 'cashprice': '20,000', 'changeprice': '3,000'}}

• 逐步文档视觉问答（DocVQA）

>>> import re
>>> from transformers import DonutProcessor, VisionEncoderDecoderModel
>>> from datasets import load_dataset
>>> import torch
>>> processor = DonutProcessor.from_pretrained("naver-clova-ix/donut-base-finetuned-docvqa")
>>> model = VisionEncoderDecoderModel.from_pretrained("naver-clova-ix/donut-base-finetuned-docvqa")
>>> device = "cuda" if torch.cuda.is_available() else "cpu"
>>> model.to(device)
>>> # load document image from the DocVQA dataset
>>> dataset = load_dataset("hf-internal-testing/example-documents", split="test")
>>> image = dataset[0]["image"]
>>> # prepare decoder inputs
>>> task_prompt = "<s_docvqa><s_question>{user_input}</s_question><s_answer>"
>>> question = "When is the coffee break?"
>>> prompt = task_prompt.replace("{user_input}", question)
>>> decoder_input_ids = processor.tokenizer(prompt, add_special_tokens=False, return_tensors="pt").input_ids
>>> pixel_values = processor(image, return_tensors="pt").pixel_values
>>> outputs = model.generate(
...     pixel_values.to(device),
...     decoder_input_ids=decoder_input_ids.to(device),
...     max_length=model.decoder.config.max_position_embeddings,
...     pad_token_id=processor.tokenizer.pad_token_id,
...     eos_token_id=processor.tokenizer.eos_token_id,
...     use_cache=True,
...     bad_words_ids=[[processor.tokenizer.unk_token_id]],
...     return_dict_in_generate=True,
... )
>>> sequence = processor.batch_decode(outputs.sequences)[0]
>>> sequence = sequence.replace(processor.tokenizer.eos_token, "").replace(processor.tokenizer.pad_token, "")
>>> sequence = re.sub(r"<.*?>", "", sequence, count=1).strip()  # remove first task start token
>>> print(processor.token2json(sequence))
{'question': 'When is the coffee break?', 'answer': '11-14 to 11:39 a.m.'}

查看model hub以查找 Donut 检查点。

训练

请参阅教程笔记本。

DonutSwinConfig

class transformers.DonutSwinConfig

<来源>

( image_size = 224 patch_size = 4 num_channels = 3 embed_dim = 96 depths = [2, 2, 6, 2] num_heads = [3, 6, 12, 24] window_size = 7 mlp_ratio = 4.0 qkv_bias = True hidden_dropout_prob = 0.0 attention_probs_dropout_prob = 0.0 drop_path_rate = 0.1 hidden_act = 'gelu' use_absolute_embeddings = False initializer_range = 0.02 layer_norm_eps = 1e-05 **kwargs )

参数

• image_size (int, optional, defaults to 224) — 每个图像的大小（分辨率）。
  
• patch_size (int, optional, defaults to 4) — 每个补丁的大小（分辨率）。
  
• num_channels (int, optional, defaults to 3) — 输入通道数。
  
• embed_dim (int, optional, defaults to 96) — 补丁嵌入的维度。
  
• depths (list(int), optional, defaults to [2, 2, 6, 2]) — Transformer 编码器中每层的深度。
  
• num_heads (list(int), optional, defaults to [3, 6, 12, 24]) — Transformer 编码器每层的注意力头数。
  
• window_size (int, optional, defaults to 7) — 窗口大小。
  
• mlp_ratio (float, optional, defaults to 4.0) — MLP 隐藏维度与嵌入维度的比率。
  
• qkv_bias (bool, optional, defaults to True) — 是否为查询、键和值添加可学习的偏置。
  
• hidden_dropout_prob (float, optional, defaults to 0.0) — 嵌入层和编码器中所有全连接层的 dropout 概率。
  
• attention_probs_dropout_prob (float, optional, defaults to 0.0) — 注意力概率的 dropout 比率。
  
• drop_path_rate (float, optional, defaults to 0.1) — 随机深度率。
  
• hidden_act (str or function, optional, defaults to "gelu") — 编码器中的非线性激活函数（函数或字符串）。如果是字符串，支持"gelu"、"relu"、"selu"和"gelu_new"。
  
• use_absolute_embeddings (bool, optional, defaults to False) — 是否将绝对位置嵌入添加到补丁嵌入中。
  
• initializer_range (float, optional, defaults to 0.02) — 用于初始化所有权重矩阵的截断正态初始化器的标准差。
  
• layer_norm_eps (float, optional, defaults to 1e-05) — 层归一化层使用的 epsilon。
  

这是用于存储 DonutSwinModel 配置的配置类。根据指定的参数实例化一个 Donut 模型，定义模型架构。使用默认值实例化配置将产生类似于 Donut naver-clova-ix/donut-base架构的配置。

配置对象继承自 PretrainedConfig，可用于控制模型输出。阅读 PretrainedConfig 的文档以获取更多信息。

示例：

>>> from transformers import DonutSwinConfig, DonutSwinModel
>>> # Initializing a Donut naver-clova-ix/donut-base style configuration
>>> configuration = DonutSwinConfig()
>>> # Randomly initializing a model from the naver-clova-ix/donut-base style configuration
>>> model = DonutSwinModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.config

DonutImageProcessor

class transformers.DonutImageProcessor

<来源>

( do_resize: bool = True size: Dict = None resample: Resampling = <Resampling.BILINEAR: 2> do_thumbnail: bool = True do_align_long_axis: bool = False do_pad: bool = True do_rescale: bool = True rescale_factor: Union = 0.00392156862745098 do_normalize: bool = True image_mean: Union = None image_std: Union = None **kwargs )

参数

• do_resize (bool, optional, defaults to True) — 是否将图像的（高度，宽度）尺寸调整为指定的size。可以被preprocess方法中的do_resize覆盖。
  
• size (Dict[str, int] optional, defaults to {"shortest_edge" -- 224}): 调整大小后的图像尺寸。图像的最短边被调整为 size[“shortest_edge”]，最长边被调整以保持输入的长宽比。可以被preprocess方法中的size覆盖。
  
• resample (PILImageResampling, optional, defaults to Resampling.BILINEAR) — 如果调整图像大小，要使用的重采样滤波器。可以被preprocess方法中的resample覆盖。
  
• do_thumbnail (bool, optional, defaults to True) — 是否使用缩略图方法调整图像大小。
  
• do_align_long_axis (bool，可选，默认为 False) — 是否通过旋转 90 度来使图像的长轴与 size 的长轴对齐。
  
• do_pad (bool，可选，默认为 True) — 是否填充图像。如果在 preprocess 中将 random_padding 设置为 True，则每个图像都会在每一侧填充随机数量的填充，直到批次中最大的图像尺寸。否则，所有图像都会填充到批次中最大的图像尺寸。
  
• do_rescale (bool，可选，默认为 True) — 是否按照指定的比例因子 rescale_factor 重新调整图像。可以被 preprocess 方法中的 do_rescale 覆盖。
  
• rescale_factor (int 或 float，可选，默认为 1/255) — 如果重新调整图像，则使用的比例因子。可以被 preprocess 方法中的 rescale_factor 覆盖。
  
• do_normalize (bool，可选，默认为 True) — 是否对图像进行归一化。可以被 preprocess 方法中的 do_normalize 覆盖。
  
• image_mean (float 或 List[float]，可选，默认为 IMAGENET_STANDARD_MEAN) — 如果对图像进行归一化，则使用的均值。这是一个浮点数或与图像通道数相同长度的浮点数列表。可以被 preprocess 方法中的 image_mean 参数覆盖。
  
• image_std (float 或 List[float]，可选，默认为 IMAGENET_STANDARD_STD) — 图像标准差。
  

构建一个 Donut 图像处理器。

preprocess

< source >

( images: Union do_resize: bool = None size: Dict = None resample: Resampling = None do_thumbnail: bool = None do_align_long_axis: bool = None do_pad: bool = None random_padding: bool = False do_rescale: bool = None rescale_factor: float = None do_normalize: bool = None image_mean: Union = None image_std: Union = None return_tensors: Union = None data_format: Optional = <ChannelDimension.FIRST: 'channels_first'> input_data_format: Union = None **kwargs )

参数

• images (ImageInput) — 要预处理的图像。期望单个图像或批量图像，像素值范围为 0 到 255。如果传入像素值在 0 到 1 之间的图像，请设置 do_rescale=False。
  
• do_resize (bool，可选，默认为 self.do_resize) — 是否调整图像大小。
  
• size (Dict[str, int]，可选，默认为 self.size) — 调整大小后的图像尺寸。图像的最短边被调整为 min(size[“height”], size[“width”])，最长边被调整以保持输入的长宽比。
  
• resample (int，可选，默认为 self.resample) — 如果调整图像大小，则使用的重采样滤波器。这可以是 PILImageResampling 枚举值之一。仅当 do_resize 设置为 True 时才会生效。
  
• do_thumbnail (bool，可选，默认为 self.do_thumbnail) — 是否使用缩略图方法调整图像大小。
  
• do_align_long_axis (bool，可选，默认为 self.do_align_long_axis) — 是否通过旋转 90 度来使图像的长轴与 size 的长轴对齐。
  
• do_pad (bool，可选，默认为 self.do_pad) — 是否填充图像。如果在 preprocess 中将 random_padding 设置为 True，则每个图像都会在每一侧填充随机数量的填充，直到批次中最大的图像尺寸。否则，所有图像都会填充到批次中最大的图像尺寸。
  
• random_padding (bool，可选，默认为 self.random_padding) — 在填充图像时是否使用随机填充。如果为 True，则批次中的每个图像都会在每一侧填充随机数量的填充，直到批次中最大的图像尺寸。
  
• do_rescale (bool，可选，默认为 self.do_rescale) — 是否重新调整图像像素值。
  
• rescale_factor (float，可选，默认为 self.rescale_factor) — 如果 do_rescale 设置为 True，则用于重新调整图像的重新调整因子。
  
• do_normalize (bool，可选，默认为 self.do_normalize) — 是否对图像进行归一化。
  
• image_mean (float 或 List[float]，可选，默认为 self.image_mean) — 用于归一化的图像均值。
  
• image_std (float 或 List[float]，可选，默认为 self.image_std) — 用于归一化的图像标准差。
  
• return_tensors (str 或 TensorType，可选) — 要返回的张量类型。可以是以下之一：

• 未设置：返回一个 np.ndarray 列表。
  
• TensorType.TENSORFLOW或'tf'：返回类型为tf.Tensor的批处理。
  
• TensorType.PYTORCH或'pt'：返回类型为torch.Tensor的批处理。
  
• TensorType.NUMPY或'np'：返回类型为np.ndarray的批处理。
  
• TensorType.JAX或'jax'：返回类型为jax.numpy.ndarray的批处理。
  

• data_format（ChannelDimension或str，可选，默认为ChannelDimension.FIRST）— 输出图片的通道维度格式。可以是以下之一：

• ChannelDimension.FIRST：图片格式为（通道数，高度，宽度）。
  
• ChannelDimension.LAST：图片格式为（高度，宽度，通道数）。
  
• 未设置：默认为输入图片的通道维度格式。
  

• input_data_format（ChannelDimension或str，可选）— 输入图片的通道维度格式。如果未设置，将从输入图片中推断通道维度格式。可以是以下之一：

• "channels_first"或ChannelDimension.FIRST：图片格式为（通道数，高度，宽度）。
  
• "channels_last"或ChannelDimension.LAST：图片格式为（高度，宽度，通道数）。
  
• "none"或ChannelDimension.NONE：图片格式为（高度，宽度）。
  

预处理一张图片或一批图片。

DonutFeatureExtractor

class transformers.DonutFeatureExtractor

<来源>

( *args **kwargs )

__call__

<来源>

( images **kwargs )

预处理一张图片或一批图片。

DonutProcessor

class transformers.DonutProcessor

<来源>

( image_processor = None tokenizer = None **kwargs )

参数

• image_processor（DonutImageProcessor，可选）— DonutImageProcessor 的实例。图像处理器是必需的输入。
  
• tokenizer（[XLMRobertaTokenizer/XLMRobertaTokenizerFast]，可选）— [XLMRobertaTokenizer/XLMRobertaTokenizerFast]的实例。分词器是必需的输入。
  

构建一个 Donut 处理器，将一个 Donut 图像处理器和一个 XLMRoBERTa 分词器包装成一个单一处理器。

DonutProcessor 提供了 DonutImageProcessor 和[XLMRobertaTokenizer/XLMRobertaTokenizerFast]的所有功能。查看更多信息，请参阅call()和 decode()。

__call__

<来源>

( *args **kwargs )

在正常模式下使用时，此方法将所有参数转发到 AutoImageProcessor 的__call__()并返回其输出。如果在上下文as_target_processor()中使用，则此方法将所有参数转发到 DonutTokenizer 的~DonutTokenizer.__call__。有关更多信息，请参阅上述两种方法的文档。

from_pretrained

<来源>

( pretrained_model_name_or_path: Union cache_dir: Union = None force_download: bool = False local_files_only: bool = False token: Union = None revision: str = 'main' **kwargs )

参数

• pretrained_model_name_or_path（str或os.PathLike）— 这可以是：

• 一个字符串，指向 huggingface.co 上托管的预训练特征提取器的模型 id。有效的模型 id 可以位于根级别，如bert-base-uncased，或者在用户或组织名称下进行命名空间化，如dbmdz/bert-base-german-cased。
  
• 一个目录的路径，其中包含使用 save_pretrained()方法保存的特征提取器文件，例如，./my_model_directory/。
  
• 一个保存的特征提取器 JSON 文件的路径或 URL，例如，./my_model_directory/preprocessor_config.json。**kwargs — 传递给 from_pretrained()和~tokenization_utils_base.PreTrainedTokenizer.from_pretrained的额外关键字参数。
  

实例化与预训练模型相关联的处理器。

这个类方法只是调用特征提取器的 from_pretrained()、图像处理器 ImageProcessingMixin 和分词器~tokenization_utils_base.PreTrainedTokenizer.from_pretrained方法。更多信息请参考上述方法的文档字符串。

保存预训练模型

<来源>

( save_directory push_to_hub: bool = False **kwargs )

参数

• save_directory (str 或 os.PathLike) — 将要保存特征提取器 JSON 文件和分词器文件的目录（如果目录不存在，则会创建）。
  
• push_to_hub (bool, 可选, 默认为 False) — 是否在保存后将模型推送到 Hugging Face 模型中心。您可以使用repo_id指定要推送到的存储库（将默认为您的命名空间中的save_directory名称）。
  
• kwargs (Dict[str, Any], 可选) — 传递给 push_to_hub()方法的额外关键字参数。
  

将此处理器的属性（特征提取器、分词器等）保存在指定的目录中，以便可以使用 from_pretrained()方法重新加载。

这个类方法只是调用 save_pretrained()和 save_pretrained()。更多信息请参考上述方法的文档字符串。

批量解码

<来源>

( *args **kwargs )

这个方法将所有参数转发给 DonutTokenizer 的 batch_decode()。更多信息请参考此方法的文档字符串。

解码

<来源>

( *args **kwargs )

这个方法将所有参数转发给 DonutTokenizer 的 decode()。更多信息请参考此方法的文档字符串。

Transformers 4.37 中文文档（八十六）（2）https://developer.aliyun.com/article/1563237