# LayoutLMV2

## 概述

LayoutLMV2 模型由 Yang Xu、Yiheng Xu、Tengchao Lv、Lei Cui、Furu Wei、Guoxin Wang、Yijuan Lu、Dinei Florencio、Cha Zhang、Wanxiang Che、Min Zhang 和 Lidong Zhou 在 [LayoutLMv2: Multi-modal Pre-training for Visually-Rich Document Understanding](https://huggingface.co/papers/2012.14740) 中提出。LayoutLMV2 改进了 [LayoutLM](layoutlm)，在多个文档图像理解基准测试中取得了最先进的结果：

- 从扫描文档中进行信息提取：[FUNSD](https://guillaumejaume.github.io/FUNSD/) 数据集（包含 199 份已标注的表单，共计超过 30,000 个单词）、[CORD](https://github.com/clovaai/cord) 数据集（包含 800 张用于训练的收据、100 张用于验证的收据和 100 张用于测试的收据）、[SROIE](https://rrc.cvc.uab.es/?ch=13) 数据集（包含 626 张用于训练的收据和 347 张用于测试的收据）以及 [Kleister-NDA](https://github.com/applicaai/kleister-nda) 数据集（包含来自 EDGAR 数据库的保密协议，其中 254 份文档用于训练，83 份用于验证，203 份用于测试）。
- 文档图像分类：[RVL-CDIP](https://www.cs.cmu.edu/~aharley/rvl-cdip/) 数据集（包含 40 万张图像，属于 16 个类别之一）。
- 文档视觉问答：[DocVQA](https://huggingface.co/papers/2007.00398) 数据集（包含在 12,000 多张文档图像上定义的 50,000 个问题）。

该论文的摘要如下：

*文本和布局的预训练凭借其有效的模型架构以及大规模无标注扫描/原生数字文档的优势，已被证明在多种视觉丰富的文档理解任务中行之有效。在本文中，我们提出了 LayoutLMv2，通过在一个多模态框架中预训练文本、布局和图像，并利用了新的模型架构和预训练任务。具体而言，LayoutLMv2 在预训练阶段不仅使用了现有的掩码视觉-语言建模任务，还引入了新的文本-图像对齐和文本-图像匹配任务，从而更好地学习跨模态交互。同时，它将空间感知自注意力机制整合到 Transformer 架构中，使模型能够充分理解不同文本块之间的相对位置关系。实验结果表明，LayoutLMv2 优于强大的基线模型，并在多种下游视觉丰富的文档理解任务上取得了新的最先进结果，包括 FUNSD（0.7895 -> 0.8420）、CORD（0.9493 -> 0.9601）、SROIE（0.9524 -> 0.9781）、Kleister-NDA（0.834 -> 0.852）、RVL-CDIP（0.9443 -> 0.9564）和 DocVQA（0.7295 -> 0.8672）。预训练的 LayoutLMv2 模型已在此 https URL 公开提供。*

LayoutLMv2 依赖于 `detectron2`、`torchvision` 和 `tesseract`。运行以下命令进行安装：

```bash
python -m pip install 'git+https://github.com/facebookresearch/detectron2.git'
python -m pip install torchvision tesseract
```

（如果您正在为 LayoutLMv2 进行开发，请注意，通过 doctests 还需要安装这些包。）

## 使用技巧

- LayoutLMv1 和 LayoutLMv2 的主要区别在于，后者在预训练阶段引入了视觉嵌入（而 LayoutLMv1 仅在微调阶段添加视觉嵌入）。
- LayoutLMv2 在自注意力层的注意力分数中同时添加了相对 1D 注意力偏置和空间 2D 注意力偏置。详细信息请参见[论文](https://huggingface.co/papers/2012.14740)第 5 页。
- 关于如何在 RVL-CDIP、FUNSD、DocVQA 和 CORD 上使用 LayoutLMv2 模型的演示笔记本，可在[此处](https://github.com/NielsRogge/Transformers-Tutorials)找到。
- LayoutLMv2 使用 Facebook AI 的 [Detectron2](https://github.com/facebookresearch/detectron2/) 包作为其视觉骨干网络。有关安装说明，请参阅 [此链接](https://detectron2.readthedocs.io/en/latest/tutorials/install.html)。
- 除了 `input_ids` 之外，[forward()](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Model.forward) 还需要两个额外的输入，即 `image` 和 `bbox`。`image` 输入对应于文本标记所在的原始文档图像。模型要求每个文档图像的尺寸为 224x224。这意味着，如果您有一批文档图像，`image` 应该是一个形状为 (batch_size, 3, 224, 224) 的张量。它可以是 `torch.Tensor` 或 `Detectron2.structures.ImageList`。您不需要对通道进行归一化，因为模型会执行此操作。需要注意的是，视觉骨干网络期望的是 BGR 通道而不是 RGB，因为 Detectron2 中的所有模型都是使用 BGR 格式进行预训练的。`bbox` 输入是输入文本标记的边界框（即 2D 位置）。这与 [LayoutLMModel](/docs/transformers/v5.23.0/zh/model_doc/layoutlm#transformers.LayoutLMModel) 相同。您可以使用外部 OCR 引擎（例如 Google 的 [Tesseract](https://github.com/tesseract-ocr/tesseract)，有可用的 [Python wrapper](https://pypi.org/project/pytesseract/)）来获取这些边界框。每个边界框应采用 (x0, y0, x1, y1) 格式，其中 (x0, y0) 对应于边界框左上角的位置，(x1, y1) 表示右下角的位置。请注意，首先需要将边界框归一化到 0-1000 的尺度上。要进行归一化，您可以使用以下函数：

```python
def normalize_bbox(bbox, width, height):
    return [
        int(1000 * (bbox[0] / width)),
        int(1000 * (bbox[1] / height)),
        int(1000 * (bbox[2] / width)),
        int(1000 * (bbox[3] / height)),
    ]
```

在此，`width` 和 `height` 对应于该 token 所在的原始文档（在调整图像大小之前）的宽度和高度。例如，可以使用 Python Image Library (PIL) 库按以下方式获取这些值：

```python
from PIL import Image

image = Image.open(
    "name_of_your_document - can be a png, jpg, etc. of your documents (PDFs must be converted to images)."
)

width, height = image.size
```

不过，该模型包含一个全新的 [LayoutLMv2Processor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Processor)，可用于直接为模型准备数据（包括在底层应用 OCR）。更多信息请参阅下方的“使用方法”部分。

- 在内部，[LayoutLMv2Model](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Model) 会将 `image` 输入通过其视觉骨干网络进行处理，以获得一个分辨率更低的特征图，其形状等于 [LayoutLMv2Config](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Config) 的 `image_feature_pool_shape` 属性。随后，该特征图会被展平，从而得到一系列图像 token。由于特征图的尺寸默认为 7x7，因此会得到 49 个图像 token。这些图像 token 接着与文本 token 拼接在一起，并送入 Transformer 编码器。这意味着，如果你将文本 token 填充至最大长度，模型的最后一层隐藏状态的长度将为 512 + 49 = 561。更一般地，最后一层隐藏状态的形状为 `seq_length` + `image_feature_pool_shape[0]` * `config.image_feature_pool_shape[1]`。
- 调用 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 时，会打印一条警告，其中包含一个很长的未初始化参数名称列表。这没有问题，因为这些参数是批归一化统计量，在针对自定义数据集进行微调时它们会具有相应的值。
- 如果要在分布式环境中训练模型，请确保在模型上调用 `synchronize_batch_norm`，以正确同步视觉骨干网络的批归一化层。

此外，还有 LayoutXLM，它是 LayoutLMv2 的多语言版本。更多信息请参阅 [LayoutXLM 的文档页面](layoutxlm)。

## 资源

以下是来自 Hugging Face 官方和社区（以 🌎 标识）的资源列表，可帮助您快速上手 LayoutLMv2。如果您希望提交资源以收录于此，欢迎随时发起 Pull Request，我们将进行审核！理想情况下，该资源应展示一些新内容，而非重复现有资源。

- 一个关于如何[在 RVL-CDIP 数据集上微调 LayoutLMv2 以进行文本分类](https://colab.research.google.com/github/NielsRogge/Transformers-Tutorials/blob/master/LayoutLMv2/RVL-CDIP/Fine_tuning_LayoutLMv2ForSequenceClassification_on_RVL_CDIP.ipynb)的笔记本。
- 另请参阅：[文本分类任务指南](../tasks/sequence_classification)

- 一个关于如何[针对 DocVQA 数据集微调 LayoutLMv2 以进行问答任务](https://colab.research.google.com/github/NielsRogge/Transformers-Tutorials/blob/master/LayoutLMv2/DocVQA/Fine_tuning_LayoutLMv2ForQuestionAnswering_on_DocVQA.ipynb)的笔记本。
- 另请参阅：[问答任务指南](../tasks/question_answering)
- 另请参阅：[文档问答任务指南](../tasks/document_question_answering)

- 一个关于如何[在 CORD 数据集上微调 LayoutLMv2 以进行 token 分类](https://colab.research.google.com/github/NielsRogge/Transformers-Tutorials/blob/master/LayoutLMv2/CORD/Fine_tuning_LayoutLMv2ForTokenClassification_on_CORD.ipynb)的笔记本。
- 一个关于如何[在 FUNSD 数据集上微调 LayoutLMv2 以进行 token 分类](https://colab.research.google.com/github/NielsRogge/Transformers-Tutorials/blob/master/LayoutLMv2/FUNSD/Fine_tuning_LayoutLMv2ForTokenClassification_on_FUNSD_using_HuggingFace_Trainer.ipynb)的笔记本。
- 另请参阅：[Token 分类任务指南](../tasks/token_classification)

## 用法：LayoutLMv2Processor

为模型准备数据最简单的方式是使用 [LayoutLMv2Processor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Processor)，它在内部组合了图像处理器（[LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor)）和分词器（[LayoutLMv2Tokenizer](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Tokenizer) 或 [LayoutLMv2TokenizerFast](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Tokenizer)）。图像处理器负责处理图像模态，而分词器负责处理文本模态。处理器将两者结合在一起，这对于像 LayoutLMv2 这样的多模态模型来说非常理想。请注意，如果你只想处理单一模态，仍然可以分别使用这两者。

```python
from transformers import LayoutLMv2ImageProcessor, LayoutLMv2Processor, LayoutLMv2TokenizerFast

image_processor = LayoutLMv2ImageProcessor()  # apply_ocr is set to True by default
tokenizer = LayoutLMv2TokenizerFast.from_pretrained("microsoft/layoutlmv2-base-uncased")
processor = LayoutLMv2Processor(image_processor, tokenizer)
```

简而言之，可以将文档图像（以及可能的附加数据）提供给 [LayoutLMv2Processor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Processor)，它会生成模型所需的输入。在内部，处理器首先使用 [LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) 对图像应用 OCR，以获取单词列表和归一化边界框，并将图像调整为指定大小，从而得到 `image` 输入。随后，单词和归一化边界框会被提供给 [LayoutLMv2Tokenizer](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Tokenizer) 或 [LayoutLMv2TokenizerFast](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Tokenizer)，将其转换为 token 级别的 `input_ids`、`attention_mask`、`token_type_ids` 和 `bbox`。可选地，可以向处理器提供单词标签，这些标签会被转换为 token 级别的 `labels`。

[LayoutLMv2Processor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Processor) 底层使用了 [PyTesseract](https://pypi.org/project/pytesseract/)，这是 Google Tesseract OCR 引擎的 Python 封装。请注意，您仍然可以使用自己选择的 OCR 引擎，并自行提供单词和归一化框。这需要初始化 [LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) 时将 `apply_ocr` 设置为 `False`。

总共，处理器支持 5 种用例。下面我们将列出所有这些用例。请注意，这些用例均适用于批量和非批量输入（我们以非批量输入为例进行说明）。

**用例 1：文档图像分类（训练、推理）+ 令牌分类（推理），apply_ocr = True**

这是最简单的情况，其中处理器（实际上是图像处理器）将对图像执行 OCR，以获取单词和归一化的边界框。

```python
from PIL import Image

from transformers import LayoutLMv2Processor

processor = LayoutLMv2Processor.from_pretrained("microsoft/layoutlmv2-base-uncased")

image = Image.open(
    "name_of_your_document - can be a png, jpg, etc. of your documents (PDFs must be converted to images)."
).convert("RGB")
encoding = processor(
    image, return_tensors="pt"
)  # you can also add all tokenizer parameters here such as padding, truncation
print(encoding.keys())
# dict_keys(['input_ids', 'token_type_ids', 'attention_mask', 'bbox', 'image'])
```

**用例 2：文档图像分类（训练、推理）+ 令牌分类（推理），apply_ocr=False**

如果希望自行执行 OCR，可以将图像处理器初始化为将 `apply_ocr` 设置为 `False`。在这种情况下，需要自行向处理器提供单词及对应的（归一化）边界框。

```python
from PIL import Image

from transformers import LayoutLMv2Processor

processor = LayoutLMv2Processor.from_pretrained("microsoft/layoutlmv2-base-uncased", revision="no_ocr")

image = Image.open(
    "name_of_your_document - can be a png, jpg, etc. of your documents (PDFs must be converted to images)."
).convert("RGB")
words = ["hello", "world"]
boxes = [[1, 2, 3, 4], [5, 6, 7, 8]]  # make sure to normalize your bounding boxes
encoding = processor(image, words, boxes=boxes, return_tensors="pt").to(model.device)
print(encoding.keys())
# dict_keys(['input_ids', 'token_type_ids', 'attention_mask', 'bbox', 'image'])
```

**用例 3：token 分类（训练），apply_ocr=False**

对于词元分类任务（例如 FUNSD、CORD、SROIE、Kleister-NDA），也可以提供对应的词标签来训练模型。处理器随后会将其转换为词元级别的 `labels`。默认情况下，它只会为单词的第一个子词元（wordpiece）标注标签，并将其余子词元标记为 -100，即 PyTorch 的 CrossEntropyLoss 中的 `ignore_index`。如果您希望为单词的所有子词元都标注标签，可以在初始化分词器时将 `only_label_first_subword` 设置为 `False`。

```python
from PIL import Image

from transformers import LayoutLMv2Processor

processor = LayoutLMv2Processor.from_pretrained("microsoft/layoutlmv2-base-uncased", revision="no_ocr")

image = Image.open(
    "name_of_your_document - can be a png, jpg, etc. of your documents (PDFs must be converted to images)."
).convert("RGB")
words = ["hello", "world"]
boxes = [[1, 2, 3, 4], [5, 6, 7, 8]]  # make sure to normalize your bounding boxes
word_labels = [1, 2]
encoding = processor(image, words, boxes=boxes, word_labels=word_labels, return_tensors="pt").to(model.device)
print(encoding.keys())
# dict_keys(['input_ids', 'token_type_ids', 'attention_mask', 'bbox', 'labels', 'image'])
```

**用例 4：视觉问答（推理），apply_ocr=True**

对于视觉问答任务（例如 DocVQA），您可以向处理器提供一个问题。默认情况下，处理器会对图像应用 OCR，并创建 [CLS] question tokens [SEP] word tokens [SEP]。

```python
from PIL import Image

from transformers import LayoutLMv2Processor

processor = LayoutLMv2Processor.from_pretrained("microsoft/layoutlmv2-base-uncased")

image = Image.open(
    "name_of_your_document - can be a png, jpg, etc. of your documents (PDFs must be converted to images)."
).convert("RGB")
question = "What's his name?"
encoding = processor(image, question, return_tensors="pt").to(model.device)
print(encoding.keys())
# dict_keys(['input_ids', 'token_type_ids', 'attention_mask', 'bbox', 'image'])
```

**用例 5：视觉问答（推理），apply_ocr=False**

对于视觉问答任务（例如 DocVQA），您可以向处理器提供问题。如果您想自行执行 OCR，可以向处理器提供您自己的单词和（归一化的）边界框。

```python
from PIL import Image

from transformers import LayoutLMv2Processor

processor = LayoutLMv2Processor.from_pretrained("microsoft/layoutlmv2-base-uncased", revision="no_ocr")

image = Image.open(
    "name_of_your_document - can be a png, jpg, etc. of your documents (PDFs must be converted to images)."
).convert("RGB")
question = "What's his name?"
words = ["hello", "world"]
boxes = [[1, 2, 3, 4], [5, 6, 7, 8]]  # make sure to normalize your bounding boxes
encoding = processor(image, question, words, boxes=boxes, return_tensors="pt").to(model.device)
print(encoding.keys())
# dict_keys(['input_ids', 'token_type_ids', 'attention_mask', 'bbox', 'image'])
```

## LayoutLMv2Config[[transformers.LayoutLMv2Config]]

#### transformers.LayoutLMv2Config[[transformers.LayoutLMv2Config]]

```python
transformers.LayoutLMv2Config(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vocab_size: int = 30522, hidden_size: int = 768, num_hidden_layers: int = 12, num_attention_heads: int = 12, intermediate_size: int = 3072, hidden_act: str = 'gelu', hidden_dropout_prob: float | int = 0.1, attention_probs_dropout_prob: float | int = 0.1, max_position_embeddings: int = 512, type_vocab_size: int = 2, initializer_range: float = 0.02, layer_norm_eps: float = 1e-12, pad_token_id: int | None = 0, max_2d_position_embeddings: int = 1024, max_rel_pos: int = 128, rel_pos_bins: int = 32, fast_qkv: bool = True, max_rel_2d_pos: int = 256, rel_2d_pos_bins: int = 64, convert_sync_batchnorm: bool = True, image_feature_pool_shape: list[int] | tuple[int, ...] = (7, 7, 256), coordinate_size: int = 128, shape_size: int = 128, has_relative_attention_bias: bool = True, has_spatial_attention_bias: bool = True, has_visual_segment_embedding: bool = False, detectron2_config_args: dict | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/configuration_layoutlmv2.py#L29)

**参数：**

vocab_size (`int`，*可选*，默认值为 `30522`)：模型的词汇表大小。定义了 `input_ids` 可以表示的不同 token 数量。

hidden_size (`int`，*可选*，默认为 `768`)：隐藏表示的维度。

num_hidden_layers (`int`，*可选*，默认为 `12`)：Transformer 解码器中的隐藏层数。

num_attention_heads (`int`，*可选*，默认为 `12`)：Transformer 解码器中每个注意力层的注意力头数量。

intermediate_size (`int`，*可选*，默认值为 `3072`)：MLP 表示的维度。

hidden_act (`str`，*可选*，默认为 `gelu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

hidden_dropout_prob (`Union[float, int]`，*可选*，默认值为 `0.1`)：嵌入层、编码器和池化器中所有全连接层的 dropout 概率。

attention_probs_dropout_prob (`Union[float, int]`，*可选*，默认值为 `0.1`)：注意力概率的 dropout 比率。

max_position_embeddings (`int`，*可选*，默认值为 `512`)：该模型可能使用的最大序列长度。

type_vocab_size (`int`，*可选*，默认为 `2`)：`token_type_ids` 的词汇表大小。

initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

layer_norm_eps (`float`, *可选*，默认为 `1e-12`)：层归一化层所使用的 epsilon。

pad_token_id (`int`，*可选*，默认为 `0`)：词表中用于填充的 Token ID。

max_2d_position_embeddings (`int`，*可选*，默认为 1024)：二维位置嵌入可能使用的最大值。通常建议将其设置为一个较大的值以防万一（例如 1024）。

max_rel_pos (`int`，*可选*，默认为 128)：自注意力机制中使用的最大相对位置数量。

rel_pos_bins (`int`，*可选*，默认为 32)：自注意力机制中使用的相对位置分箱数量。

fast_qkv (`bool`，*可选*，默认为 `True`)：是否使用单个矩阵来自注意力层中的查询、键和值。

max_rel_2d_pos (`int`，*可选*，默认为 256)：自注意力机制中相对 2D 位置的最大数量。

rel_2d_pos_bins (`int`，*可选*，默认为 64)：自注意力机制中二维相对位置分箱的数量。

convert_sync_batchnorm (`bool`, *可选*, 默认为 `True`) : 是否将批归一化层转换为同步批归一化层。

image_feature_pool_shape (`list[int]`，*可选*，默认为 `[7, 7, 256]`)：平均池化特征图的形状。

coordinate_size (`int`，*可选*，默认为 128)：坐标嵌入的维度。

shape_size (`int`，*可选*，默认为 128)：宽度和高度嵌入的维度。

has_relative_attention_bias (`bool`，*可选*，默认为 `True`)：是否在自注意力机制中使用相对注意力偏置。

has_spatial_attention_bias (`bool`, *可选*, 默认为 `True`) : 是否在自注意力机制中使用空间注意力偏置。

has_visual_segment_embedding (`bool`，*可选*，默认为 `False`)：是否添加视觉分段嵌入。

detectron2_config_args (`dict`, *可选*) : 包含 Detectron2 视觉骨干网络配置参数的字典。有关默认值的详细信息，请参阅[此文件](https://github.com/microsoft/unilm/blob/master/layoutlmft/layoutlmft/models/layoutlmv2/detectron2_config.py)。

这是用于存储 LayoutLMv2Model 配置的类。它根据指定的参数实例化 Layoutlmv2 模型，并定义模型架构。使用默认值实例化配置将得到与 [microsoft/layoutlmv2-base-uncased](https://huggingface.co/microsoft/layoutlmv2-base-uncased) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

示例：

```python
>>> from transformers import LayoutLMv2Config, LayoutLMv2Model

>>> # Initializing a LayoutLMv2 microsoft/layoutlmv2-base-uncased style configuration
>>> configuration = LayoutLMv2Config()

>>> # Initializing a model (with random weights) from the microsoft/layoutlmv2-base-uncased style configuration
>>> model = LayoutLMv2Model(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## LayoutLMv2ImageProcessor[[transformers.LayoutLMv2ImageProcessor]]

#### transformers.LayoutLMv2ImageProcessor[[transformers.LayoutLMv2ImageProcessor]]

```python
transformers.LayoutLMv2ImageProcessor(**kwargs: *<class 'transformers.models.layoutlmv2.image_processing_layoutlmv2.LayoutLMv2ImageProcessorKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/image_processing_layoutlmv2.py#L118)

**参数：**

do_convert_rgb (`bool`, *kwargs*, *可选*) : 是否将图像转换为 RGB。

do_resize (`bool`, *kwargs*, *可选*, 默认为 `True`) : 是否调整图像大小。

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*，默认为 `{'height' : 224, 'width': 224}`)：描述输入到模型的最大尺寸。

default_to_square (`bool`，*kwargs*，*可选*，默认为 `True`)：当 size 为整数时，是否在调整大小时默认使用正方形图像。

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 应用 `center_crop` 后输出图像的尺寸。

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*，默认为 `2`) : 如果调整图像大小，则使用的重采样滤波器。它可以是枚举 `PILImageResampling` 中的一个值。仅当 `do_resize` 设置为 `True` 时才会生效。

do_rescale (`bool`, *kwargs*, *可选*) : 是否对图像进行重新缩放。

rescale_factor (`float`, *kwargs*, *可选*，默认为 `None`) : 如果 `do_rescale` 设置为 `True`，则用于重新缩放图像的缩放因子。

do_normalize (`bool`, *kwargs*, *可选*) : 是否对图像进行归一化。

image_mean (`Union[float, list[float], tuple[float, ...]]`，*kwargs*，*可选*)：用于归一化的图像均值。仅当 `do_normalize` 设置为 `True` 时生效。

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *可选*) : 用于归一化的图像标准差。仅当 `do_normalize` 设置为 `True` 时生效。

do_pad (`bool`, *kwargs*, *可选*) : 是否对图像进行填充。填充操作会将图像填充至批次中的最大尺寸，或填充至每张图像的固定正方形尺寸。具体的填充策略取决于模型。

pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 用于将图像填充到的尺寸，格式为 `{"height": int, "width" int}`。该尺寸必须大于预处理中提供的任何图像尺寸。如果未提供 `pad_size`，图像将被填充到批次中最大的高度和宽度。仅在 `do_pad=True.` 时应用。

do_center_crop (`bool`, *kwargs*, *可选*) : 是否对图像进行居中裁剪。

data_format (`Union[str, ~image_utils.ChannelDimension]`，*kwargs*，*可选*)：仅支持 `ChannelDimension.FIRST`。为兼容旧版处理器而添加。

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *可选*) : 输入图像的通道维度格式。如果未设置，则从输入图像中推断通道维度格式。可以是以下之一： - `"channels_first"` 或 `ChannelDimension.FIRST`：图像为 (num_channels, height, width) 格式。 - `"channels_last"` 或 `ChannelDimension.LAST`：图像为 (height, width, num_channels) 格式。 - `"none"` 或 `ChannelDimension.NONE`：图像为 (height, width) 格式。

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*)：用于处理视频的设备。如果未设置，则从输入视频中推断设备。

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : 如果设置为 `'pt'`，则返回堆叠的张量，否则返回张量列表。

disable_grouping (`bool`, *kwargs*, *可选*) : 是否禁用按尺寸对图像进行分组，从而逐个处理图像而非批量处理。如果为 None，则当图像位于 CPU 上时设置为 True，否则设置为 False。此选择基于经验观察，详见此处：https://github.com/huggingface/transformers/pull/38157

image_seq_length (`int`, *kwargs*, *可选*) : 输入中每张图片所使用的图像 token 数量。为向后兼容而添加，但在未来的模型中，应将其设置为处理器的属性。

apply_ocr (`bool`, *kwargs*, *可选*，默认为 `self.apply_ocr`)：是否应用 Tesseract OCR 引擎以获取单词及归一化边界框。可通过 `preprocess` 方法中的 `apply_ocr` 参数进行覆盖。

ocr_lang (`str`, *kwargs*, *可选*) : 供 Tesseract OCR 引擎使用的语言，通过其 ISO 代码指定。默认使用英语。可通过 `preprocess` 方法中的 `ocr_lang` 参数进行覆盖。

tesseract_config (`str`, *kwargs*, *可选*) : 在调用 Tesseract 时转发给 `config` 参数的任何其他自定义配置标志。例如：'--psm 6'。可被 `preprocess` 方法中的 `tesseract_config` 参数覆盖。

构建一个 LayoutLMv2ImageProcessor 图像处理器。

#### preprocess[[transformers.LayoutLMv2ImageProcessor.preprocess]]

```python
preprocess(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']], **kwargs: *<class 'transformers.models.layoutlmv2.image_processing_layoutlmv2.LayoutLMv2ImageProcessorKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/image_processing_layoutlmv2.py#L131)

**参数：**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`) : 要预处理的图像。期望输入单张或一批像素值在 0 到 255 之间的图像。如果传入的图像像素值在 0 到 1 之间，请设置 `do_rescale=False`。

do_convert_rgb (`bool`, *kwargs*, *可选*) : 是否将图像转换为 RGB。

do_resize (`bool`，*kwargs*，*可选*)：是否调整图像大小。

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*)：描述模型的最大输入维度。

default_to_square (`bool`, *kwargs*, *可选*) : 当 size 为 int 时，是否在调整大小时默认使用正方形图像。

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 应用 `center_crop` 后输出图像的尺寸。

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*) : 如果调整图像大小，则使用的重采样滤波器。它可以是枚举 `PILImageResampling` 中的一个值。仅当 `do_resize` 设置为 `True` 时才会生效。

do_rescale (`bool`, *kwargs*, *可选*) : 是否对图像进行重新缩放。

rescale_factor (`float`, *kwargs*, *可选*) : 当 `do_rescale` 设置为 `True` 时，用于对图像进行缩放的缩放因子。

do_normalize (`bool`, *kwargs*, *可选*) : 是否对图像进行归一化。

image_mean (`Union[float, list[float], tuple[float, ...]]`，*kwargs*，*可选*)：用于归一化的图像均值。仅当 `do_normalize` 设置为 `True` 时生效。

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *可选*) : 用于归一化的图像标准差。仅当 `do_normalize` 设置为 `True` 时生效。

do_pad (`bool`, *kwargs*, *可选*) : 是否对图像进行填充。填充操作会将图像填充至批次中的最大尺寸，或填充至每张图像的固定正方形尺寸。具体的填充策略取决于模型。

pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 用于将图像填充到的尺寸，格式为 `{"height": int, "width" int}`。该尺寸必须大于预处理中提供的任何图像尺寸。如果未提供 `pad_size`，图像将被填充到批次中最大的高度和宽度。仅在 `do_pad=True.` 时应用。

do_center_crop (`bool`, *kwargs*, *可选*) : 是否对图像进行居中裁剪。

data_format (`Union[str, ~image_utils.ChannelDimension]`，*kwargs*，*可选*)：仅支持 `ChannelDimension.FIRST`。为兼容旧版处理器而添加。

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *可选*) : 输入图像的通道维度格式。如果未设置，则从输入图像中推断通道维度格式。可以是以下之一： - `"channels_first"` 或 `ChannelDimension.FIRST`：图像为 (num_channels, height, width) 格式。 - `"channels_last"` 或 `ChannelDimension.LAST`：图像为 (height, width, num_channels) 格式。 - `"none"` 或 `ChannelDimension.NONE`：图像为 (height, width) 格式。

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*)：用于处理视频的设备。如果未设置，则从输入视频中推断设备。

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : 如果设置为 `'pt'`，则返回堆叠的张量，否则返回张量列表。

disable_grouping (`bool`, *kwargs*, *可选*) : 是否禁用按尺寸对图像进行分组，从而逐个处理图像而非批量处理。如果为 None，则当图像位于 CPU 上时设置为 True，否则设置为 False。此选择基于经验观察，详见此处：https://github.com/huggingface/transformers/pull/38157

image_seq_length (`int`, *kwargs*, *可选*) : 输入中每张图片所使用的图像 token 数量。为向后兼容而添加，但在未来的模型中，应将其设置为处理器的属性。

apply_ocr (`bool`, *kwargs*, *可选*，默认为 `self.apply_ocr`)：是否应用 Tesseract OCR 引擎以获取单词及归一化边界框。可通过 `preprocess` 方法中的 `apply_ocr` 参数进行覆盖。

ocr_lang (`str`, *kwargs*, *可选*) : 供 Tesseract OCR 引擎使用的语言，通过其 ISO 代码指定。默认使用英语。可通过 `preprocess` 方法中的 `ocr_lang` 参数进行覆盖。

tesseract_config (`str`, *kwargs*, *可选*) : 在调用 Tesseract 时转发给 `config` 参数的任何其他自定义配置标志。例如：'--psm 6'。可被 `preprocess` 方法中的 `tesseract_config` 参数覆盖。

**返回：** `~image_processing_base.BatchFeature`

- **data** (`dict`) -- 由 __call__ 方法返回的列表/数组/张量字典（例如 'pixel_values'）。
- **tensor_type** (`Union[None, str, TensorType]`，*可选*) -- 您可以在此处指定 tensor_type，以便在初始化时将 PyTorch/Numpy 张量中的整数列表进行转换。

## LayoutLMv2ImageProcessorPil[[transformers.LayoutLMv2ImageProcessorPil]]

#### transformers.LayoutLMv2ImageProcessorPil[[transformers.LayoutLMv2ImageProcessorPil]]

```python
transformers.LayoutLMv2ImageProcessorPil(**kwargs: *<class 'transformers.models.layoutlmv2.image_processing_pil_layoutlmv2.LayoutLMv2ImageProcessorKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/image_processing_pil_layoutlmv2.py#L121)

**参数：**

do_convert_rgb (`bool`, *kwargs*, *可选*) : 是否将图像转换为 RGB。

do_resize (`bool`, *kwargs*, *可选*, 默认为 `True`) : 是否调整图像大小。

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*，默认为 `{'height' : 224, 'width': 224}`)：描述输入到模型的最大尺寸。

default_to_square (`bool`，*kwargs*，*可选*，默认为 `True`)：当 size 为整数时，是否在调整大小时默认使用正方形图像。

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 应用 `center_crop` 后输出图像的尺寸。

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*，默认为 `2`) : 如果调整图像大小，则使用的重采样滤波器。它可以是枚举 `PILImageResampling` 中的一个值。仅当 `do_resize` 设置为 `True` 时才会生效。

do_rescale (`bool`, *kwargs*, *可选*) : 是否对图像进行重新缩放。

rescale_factor (`float`, *kwargs*, *可选*，默认为 `None`) : 如果 `do_rescale` 设置为 `True`，则用于重新缩放图像的缩放因子。

do_normalize (`bool`, *kwargs*, *可选*) : 是否对图像进行归一化。

image_mean (`Union[float, list[float], tuple[float, ...]]`，*kwargs*，*可选*)：用于归一化的图像均值。仅当 `do_normalize` 设置为 `True` 时生效。

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *可选*) : 用于归一化的图像标准差。仅当 `do_normalize` 设置为 `True` 时生效。

do_pad (`bool`, *kwargs*, *可选*) : 是否对图像进行填充。填充操作会将图像填充至批次中的最大尺寸，或填充至每张图像的固定正方形尺寸。具体的填充策略取决于模型。

pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 用于将图像填充到的尺寸，格式为 `{"height": int, "width" int}`。该尺寸必须大于预处理中提供的任何图像尺寸。如果未提供 `pad_size`，图像将被填充到批次中最大的高度和宽度。仅在 `do_pad=True.` 时应用。

do_center_crop (`bool`, *kwargs*, *可选*) : 是否对图像进行居中裁剪。

data_format (`Union[str, ~image_utils.ChannelDimension]`，*kwargs*，*可选*)：仅支持 `ChannelDimension.FIRST`。为兼容旧版处理器而添加。

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *可选*) : 输入图像的通道维度格式。如果未设置，则从输入图像中推断通道维度格式。可以是以下之一： - `"channels_first"` 或 `ChannelDimension.FIRST`：图像为 (num_channels, height, width) 格式。 - `"channels_last"` 或 `ChannelDimension.LAST`：图像为 (height, width, num_channels) 格式。 - `"none"` 或 `ChannelDimension.NONE`：图像为 (height, width) 格式。

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*)：用于处理视频的设备。如果未设置，则从输入视频中推断设备。

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : 如果设置为 `'pt'`，则返回堆叠的张量，否则返回张量列表。

disable_grouping (`bool`, *kwargs*, *可选*) : 是否禁用按尺寸对图像进行分组，从而逐个处理图像而非批量处理。如果为 None，则当图像位于 CPU 上时设置为 True，否则设置为 False。此选择基于经验观察，详见此处：https://github.com/huggingface/transformers/pull/38157

image_seq_length (`int`, *kwargs*, *可选*) : 输入中每张图片所使用的图像 token 数量。为向后兼容而添加，但在未来的模型中，应将其设置为处理器的属性。

apply_ocr (`bool`, *kwargs*, *可选*，默认为 `self.apply_ocr`)：是否应用 Tesseract OCR 引擎以获取单词及归一化边界框。可通过 `preprocess` 方法中的 `apply_ocr` 参数进行覆盖。

ocr_lang (`str`, *kwargs*, *可选*) : 供 Tesseract OCR 引擎使用的语言，通过其 ISO 代码指定。默认使用英语。可通过 `preprocess` 方法中的 `ocr_lang` 参数进行覆盖。

tesseract_config (`str`, *kwargs*, *可选*) : 在调用 Tesseract 时转发给 `config` 参数的任何其他自定义配置标志。例如：'--psm 6'。可被 `preprocess` 方法中的 `tesseract_config` 参数覆盖。

构建一个 LayoutLMv2ImageProcessor 图像处理器。

#### preprocess[[transformers.LayoutLMv2ImageProcessorPil.preprocess]]

```python
preprocess(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']], **kwargs: *<class 'transformers.models.layoutlmv2.image_processing_pil_layoutlmv2.LayoutLMv2ImageProcessorKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/image_processing_pil_layoutlmv2.py#L134)

**参数：**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`) : 要预处理的图像。期望输入单张或一批像素值在 0 到 255 之间的图像。如果传入的图像像素值在 0 到 1 之间，请设置 `do_rescale=False`。

do_convert_rgb (`bool`, *kwargs*, *可选*) : 是否将图像转换为 RGB。

do_resize (`bool`，*kwargs*，*可选*)：是否调整图像大小。

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*)：描述模型的最大输入维度。

default_to_square (`bool`, *kwargs*, *可选*) : 当 size 为 int 时，是否在调整大小时默认使用正方形图像。

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 应用 `center_crop` 后输出图像的尺寸。

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*) : 如果调整图像大小，则使用的重采样滤波器。它可以是枚举 `PILImageResampling` 中的一个值。仅当 `do_resize` 设置为 `True` 时才会生效。

do_rescale (`bool`, *kwargs*, *可选*) : 是否对图像进行重新缩放。

rescale_factor (`float`, *kwargs*, *可选*) : 当 `do_rescale` 设置为 `True` 时，用于对图像进行缩放的缩放因子。

do_normalize (`bool`, *kwargs*, *可选*) : 是否对图像进行归一化。

image_mean (`Union[float, list[float], tuple[float, ...]]`，*kwargs*，*可选*)：用于归一化的图像均值。仅当 `do_normalize` 设置为 `True` 时生效。

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *可选*) : 用于归一化的图像标准差。仅当 `do_normalize` 设置为 `True` 时生效。

do_pad (`bool`, *kwargs*, *可选*) : 是否对图像进行填充。填充操作会将图像填充至批次中的最大尺寸，或填充至每张图像的固定正方形尺寸。具体的填充策略取决于模型。

pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 用于将图像填充到的尺寸，格式为 `{"height": int, "width" int}`。该尺寸必须大于预处理中提供的任何图像尺寸。如果未提供 `pad_size`，图像将被填充到批次中最大的高度和宽度。仅在 `do_pad=True.` 时应用。

do_center_crop (`bool`, *kwargs*, *可选*) : 是否对图像进行居中裁剪。

data_format (`Union[str, ~image_utils.ChannelDimension]`，*kwargs*，*可选*)：仅支持 `ChannelDimension.FIRST`。为兼容旧版处理器而添加。

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *可选*) : 输入图像的通道维度格式。如果未设置，则从输入图像中推断通道维度格式。可以是以下之一： - `"channels_first"` 或 `ChannelDimension.FIRST`：图像为 (num_channels, height, width) 格式。 - `"channels_last"` 或 `ChannelDimension.LAST`：图像为 (height, width, num_channels) 格式。 - `"none"` 或 `ChannelDimension.NONE`：图像为 (height, width) 格式。

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*)：用于处理视频的设备。如果未设置，则从输入视频中推断设备。

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : 如果设置为 `'pt'`，则返回堆叠的张量，否则返回张量列表。

disable_grouping (`bool`, *kwargs*, *可选*) : 是否禁用按尺寸对图像进行分组，从而逐个处理图像而非批量处理。如果为 None，则当图像位于 CPU 上时设置为 True，否则设置为 False。此选择基于经验观察，详见此处：https://github.com/huggingface/transformers/pull/38157

image_seq_length (`int`, *kwargs*, *可选*) : 输入中每张图片所使用的图像 token 数量。为向后兼容而添加，但在未来的模型中，应将其设置为处理器的属性。

apply_ocr (`bool`, *kwargs*, *可选*，默认为 `self.apply_ocr`)：是否应用 Tesseract OCR 引擎以获取单词及归一化边界框。可通过 `preprocess` 方法中的 `apply_ocr` 参数进行覆盖。

ocr_lang (`str`, *kwargs*, *可选*) : 供 Tesseract OCR 引擎使用的语言，通过其 ISO 代码指定。默认使用英语。可通过 `preprocess` 方法中的 `ocr_lang` 参数进行覆盖。

tesseract_config (`str`, *kwargs*, *可选*) : 在调用 Tesseract 时转发给 `config` 参数的任何其他自定义配置标志。例如：'--psm 6'。可被 `preprocess` 方法中的 `tesseract_config` 参数覆盖。

**返回：** `~image_processing_base.BatchFeature`

- **data** (`dict`) -- 由 __call__ 方法返回的列表/数组/张量字典（例如 'pixel_values'）。
- **tensor_type** (`Union[None, str, TensorType]`，*可选*) -- 您可以在此处指定 tensor_type，以便在初始化时将 PyTorch/Numpy 张量中的整数列表进行转换。

## LayoutLMv2Tokenizer[[transformers.LayoutLMv2Tokenizer]]

#### transformers.LayoutLMv2Tokenizer[[transformers.LayoutLMv2Tokenizer]]

```python
transformers.LayoutLMv2Tokenizer(vocab: str | dict[str, int] | None = None, do_lower_case = True, unk_token = '[UNK]', sep_token = '[SEP]', pad_token = '[PAD]', cls_token = '[CLS]', mask_token = '[MASK]', cls_token_box = [0, 0, 0, 0], sep_token_box = [1000, 1000, 1000, 1000], pad_token_box = [0, 0, 0, 0], pad_token_label = -100, only_label_first_subword = True, tokenize_chinese_chars = True, strip_accents = None, model_max_length = 512, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/tokenization_layoutlmv2.py#L112)

**参数：**

vocab_file (`str`) : 包含词汇表的文件。

do_lower_case (`bool`，*可选*，默认为 `True`)：分词时是否将输入转换为小写。

unk_token (`str`，*可选*，默认为 `"[UNK]"`)：未知标记。不在词汇表中的标记无法转换为 ID，因此会被设置为该标记。

sep_token (`str`，*可选*，默认为 `"[SEP]"`)：分隔符 token，用于从多个序列构建序列时，例如用于序列分类的两个序列，或用于问答的文本和问题。它也用作使用特殊 token 构建的序列的最后一个 token。

pad_token (`str`，*可选*，默认为 `"[PAD]"`)：用于填充的标记，例如在对长度不同的序列进行批处理时。

cls_token (`str`，*可选*，默认为 `"[CLS]"`)：用于序列分类（对整个序列进行分类，而非逐 token 分类）的分类器 token。当使用特殊 token 构建序列时，它是序列的第一个 token。

mask_token (`str`，*可选*，默认为 `"[MASK]"`)：用于掩码值的标记。这是在通过掩码语言建模训练该模型时所使用的标记，也是模型将尝试预测的标记。

cls_token_box (`List[int]`, *可选*, 默认为 `[0, 0, 0, 0]`) : 用于特殊 [CLS] 标记的边界框。

sep_token_box (`List[int]`, *可选*, 默认为 `[1000, 1000, 1000, 1000]`) : 用于特殊 [SEP] 标记的边界框。

pad_token_box (`List[int]`, *可选*, 默认为 `[0, 0, 0, 0]`) : 用于特殊 [PAD] token 的边界框。

pad_token_label (`int`，*可选*，默认为 -100)：用于填充标记的标签。默认为 -100，即 PyTorch 的 CrossEntropyLoss 的 `ignore_index`。

only_label_first_subword (`bool`，*可选*，默认为 `True`)：如果提供了词标签，是否仅对第一个子词进行标注。

tokenize_chinese_chars (`bool`，*可选*，默认为 `True`)：是否对汉字进行分词。对于日语，建议关闭此功能（参见[此问题](https://github.com/huggingface/transformers/issues/328)）。

strip_accents (`bool`, *可选*) : 是否去除所有重音符号。如果未指定此选项，则将根据 `lowercase` 的值来确定（与原始 LayoutLMv2 相同）。

构建一个“快速”的 LayoutLMv2 分词器（基于 HuggingFace 的 *tokenizers* 库）。基于 WordPiece。

该分词器继承自 [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.TokenizersBackend)，后者包含了大部分主要方法。用户应参考该父类以获取有关这些方法的更多信息。

#### __调用__[[transformers.LayoutLMv2Tokenizer.__call__]]

```python
__call__(text: str | list[str] | list[list[str]], text_pair: list[str] | list[list[str]] | None = None, boxes: list[list[int]] | list[list[list[int]]] | None = None, word_labels: list[int] | list[list[int]] | None = None, add_special_tokens: bool = True, padding: bool | str | transformers.utils.generic.PaddingStrategy = False, truncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy | None = None, max_length: int | None = None, stride: int = 0, pad_to_multiple_of: int | None = None, padding_side: str | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, return_token_type_ids: bool | None = None, return_attention_mask: bool | None = None, return_overflowing_tokens: bool = False, return_special_tokens_mask: bool = False, return_offsets_mapping: bool = False, return_length: bool = False, verbose: bool = True, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/tokenization_layoutlmv2.py#L243)

**参数：**

text (`str`, `List[str]`, `List[List[str]]`) : 要编码的序列或序列批次。每个序列可以是字符串、字符串列表（单个示例的单词或一批示例的问题）或字符串列表的列表（单词批次）。

text_pair (`List[str]`, `List[List[str]]`) : 要编码的序列或序列批次。每个序列应为一个字符串列表（预分词字符串）。

boxes (`List[List[int]]`, `List[List[List[int]]]`) : 单词级边界框。每个边界框应归一化到 0-1000 的尺度上。

word_labels (`List[int]`, `List[List[int]]`, *可选*) : 词级别的整数标签（用于 FUNSD、CORD 等 token 分类任务）。

add_special_tokens (`bool`，*可选*，默认为 `True`)：是否使用相对于其模型的特殊标记对序列进行编码。

padding (`bool`、`str` 或 [PaddingStrategy](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.utils.PaddingStrategy)，*可选*，默认为 `False`)：启用并控制填充。接受以下值： - `True` 或 `'longest'`：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。 - `'max_length'`：填充至由参数 `max_length` 指定的最大长度，或者如果未提供该参数，则填充至模型可接受的最大输入长度。 - `False` 或 `'do_not_pad'`（默认值）：不进行填充（即可以输出包含不同长度序列的批次）。

truncation (`bool`、`str` 或 [TruncationStrategy](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy)，*optional*，默认为 `False`)：启用并控制截断。接受以下值： - `True` 或 `'longest_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将逐个 token 进行截断，从该对中最长的序列中移除一个 token。 - `'only_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第一个序列。 - `'only_second'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第二个序列。 - `False` 或 `'do_not_truncate'`（默认）：不截断（即，可以输出序列长度大于模型最大允许输入大小的批次）。

max_length (`int`, *可选*) : 控制截断/填充参数之一所使用的最大长度。如果未设置或设置为 `None`，当截断/填充参数需要最大长度时，将使用预定义的最大模型长度。如果模型没有特定的最大输入长度（例如 XLNet），则禁用截断/填充至最大长度的功能。

stride (`int`，*可选*，默认为 0)：如果与 `max_length` 一起设置为某个数值，则当 `return_overflowing_tokens=True` 时，返回的溢出 token 将包含来自截断序列末尾的若干 token，以在截断序列和溢出序列之间提供一定的重叠。该参数的值定义了重叠 token 的数量。

pad_to_multiple_of (`int`，*可选*)：如果设置，则将序列填充为所提供值的倍数。这对于在计算能力 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 的使用特别有用。

return_token_type_ids (`bool`，*可选*)：是否返回 token type ID。如果保持默认值，则根据特定 tokenizer 的默认设置返回 token type ID，该设置由 `return_outputs` 属性定义。[什么是 token type ID？](../glossary#token-type-ids)

return_attention_mask (`bool`，*可选*)：是否返回注意力掩码。如果保持默认值，将根据特定分词器的默认设置返回注意力掩码，该设置由 `return_outputs` 属性定义。[什么是注意力掩码？](../glossary#attention-mask)

return_overflowing_tokens (`bool`，*可选*，默认为 `False`)：是否返回溢出的 token 序列。如果提供了输入 id 的序列对（或序列对的批次），并且 `truncation_strategy = longest_first` 或 `True`，则会引发错误，而不是返回溢出的 token。

return_special_tokens_mask (`bool`，*可选*，默认为 `False`)：是否返回特殊标记掩码信息。

return_offsets_mapping (`bool`，*可选*，默认为 `False`)：是否返回每个 token 的 `(char_start, char_end)`。此功能仅适用于继承自 [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.TokenizersBackend) 的快速分词器；如果使用 Python 分词器，此方法将抛出 `NotImplementedError`。

return_length (`bool`，*可选*，默认为 `False`)：是否返回编码后输入的长度。

verbose (`bool`，*可选*，默认为 `True`)：是否打印更多信息和警告。

- ****kwargs** : 传递给 `self.tokenize()` 方法

用于对一条或多条序列，或一对或多对序列进行分词并准备供模型使用的主要方法，这些序列带有词级归一化边界框以及可选的标签。

#### save_vocabulary[[transformers.LayoutLMv2Tokenizer.save_vocabulary]]

```python
save_vocabulary(save_directory: str, filename_prefix: str | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/tokenization_utils_tokenizers.py#L547)

## LayoutLMv2Processor[[transformers.LayoutLMv2Processor]]

#### transformers.LayoutLMv2Processor[[transformers.LayoutLMv2Processor]]

```python
transformers.LayoutLMv2Processor(image_processor = None, tokenizer = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/processing_layoutlmv2.py#L24)

**参数：**

image_processor (`LayoutLMv2ImageProcessor`)：图像处理器是必需的输入。

tokenizer (`LayoutLMv2Tokenizer`)：分词器是必需的输入。

构建一个 LayoutLMv2Processor，它将图像处理器和分词器封装为单一处理器。

[LayoutLMv2Processor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Processor) 提供了 [LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) 和 [LayoutLMv2Tokenizer](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Tokenizer) 的所有功能。有关更多信息，请参阅 [~LayoutLMv2ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) 和 [~LayoutLMv2Tokenizer](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Tokenizer)。

#### __调用__[[transformers.LayoutLMv2Processor.__call__]]

```python
__call__(images, text: str | list[str] | list[list[str]] = None, text_pair: list[str] | list[list[str]] | None = None, boxes: list[list[int]] | list[list[list[int]]] | None = None, word_labels: list[int] | list[list[int]] | None = None, add_special_tokens: bool = True, padding: bool | str | transformers.utils.generic.PaddingStrategy = False, truncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy = False, max_length: int | None = None, stride: int = 0, pad_to_multiple_of: int | None = None, return_token_type_ids: bool | None = None, return_attention_mask: bool | None = None, return_overflowing_tokens: bool = False, return_special_tokens_mask: bool = False, return_offsets_mapping: bool = False, return_length: bool = False, verbose: bool = True, return_tensors: str | transformers.utils.generic.TensorType | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/processing_layoutlmv2.py#L28)

**参数：**

images (``) : Image to preprocess. Expects a single or batch of images with pixel values ranging from 0 to 255. If passing in images with pixel values between 0 and 1, set `do_rescale=False`.

text (`Union[str, list[str], list[list[str]]]`，*可选*)：要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果传入预分词输入，请设置 `is_split_into_words=True` 以避免与批量输入产生歧义。

text_pair (`str, list[str] or list[int]`，*可选*)：可选的第二个待编码序列。它可以是一个字符串、一个字符串列表（使用 `tokenize` 方法分词后的字符串）或一个整数列表（使用 `convert_tokens_to_ids` 方法转换后的 token ID）。

boxes (`list[list[int]] or list[list[list[int]]]`，*可选*)：词级边界框。每个边界框应归一化到 0-1000 的尺度上。

word_labels (`list[int] or list[list[int]]`, *可选*) : 词级别的整数标签（用于 FUNSD、CORD 等 token 分类任务）。

add_special_tokens (`bool`，*可选*，默认为 `True`)：在编码序列时是否添加特殊标记。此操作将使用底层的 `PretrainedTokenizerBase.build_inputs_with_special_tokens` 函数，该函数定义了哪些标记会自动添加到输入 ID 中。如果您希望自动添加 `bos` 或 `eos` 标记，此功能非常有用。

padding (bool, str 或 [PaddingStrategy](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.utils.PaddingStrategy), *optional*, 默认为 `False`) : 启用并控制填充。接受以下值： - `True` 或 `'longest'`：填充到批次中最长的序列（如果只提供单个序列，则不进行填充）。 - `'max_length'`：填充到由参数 `max_length` 指定的最大长度，或者如果未提供该参数，则填充到模型可接受的最大输入长度。 - `False` 或 `'do_not_pad'`（默认）：不进行填充（即，可以输出包含不同长度序列的批次）。

truncation (bool, str 或 [TruncationStrategy](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *optional*, 默认为 `False`) : 启用并控制截断。接受以下值： - `True` 或 `'longest_first'`：截断至参数 `max_length` 指定的最大长度，或者在未提供该参数时截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将逐个 token 进行截断，从该对中最长的序列中移除一个 token。 - `'only_first'`：截断至参数 `max_length` 指定的最大长度，或者在未提供该参数时截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第一个序列。 - `'only_second'`：截断至参数 `max_length` 指定的最大长度，或者在未提供该参数时截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第二个序列。 - `False` 或 `'do_not_truncate'`（默认）：不截断（即，可以输出序列长度大于模型最大可接受输入大小的批次）。

max_length (`int`, *可选*) : 控制截断/填充参数之一所使用的最大长度。如果未设置或设置为 `None`，当截断/填充参数需要最大长度时，将使用预定义的最大模型长度。如果模型没有特定的最大输入长度（例如 XLNet），则禁用截断/填充至最大长度的功能。

stride (`int`，*可选*，默认为 `0`)：如果与 `max_length` 一起设置为某个数字，则当 `return_overflowing_tokens=True` 时，返回的溢出 token 将包含来自截断序列末尾的若干 token，以在截断序列和溢出序列之间提供一定的重叠。此参数的值定义了重叠 token 的数量。

pad_to_multiple_of (`int`, *可选*) : 如果设置，则将序列填充为所提供值的倍数。需要启用 `padding`。这对于在计算能力为 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 特别有用。

return_token_type_ids (`bool`，*可选*)：是否返回 token type ID。如果保持默认值，则根据特定 tokenizer 的默认设置返回 token type ID，该设置由 `return_outputs` 属性定义。[什么是 token type ID？](../glossary#token-type-ids)

return_attention_mask (`bool`，*可选*)：是否返回注意力掩码。如果保持默认值，将根据特定分词器的默认设置返回注意力掩码，该设置由 `return_outputs` 属性定义。[什么是注意力掩码？](../glossary#attention-mask)

return_overflowing_tokens (`bool`，*可选*，默认为 `False`)：是否返回溢出的 token 序列。如果提供了输入 id 的序列对（或序列对的批次），并且 `truncation_strategy = longest_first` 或 `True`，则会引发错误，而不是返回溢出的 token。

return_special_tokens_mask (`bool`，*可选*，默认为 `False`)：是否返回特殊标记掩码信息。

return_offsets_mapping (`bool`，*可选*，默认为 `False`)：是否返回每个 token 的 `(char_start, char_end)`。此功能仅适用于继承自 [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.TokenizersBackend) 的快速分词器；如果使用 Python 分词器，此方法将抛出 `NotImplementedError`。

return_length (`bool`, *可选*, 默认为 `False`) : 是否返回编码后输入的长度。

verbose (`bool`，*可选*，默认为 `True`)：是否打印更多信息和警告。

return_tensors (`Union[str, ~utils.generic.TensorType]`, *可选*) : 如果设置，将返回特定框架的张量。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 NumPy `np.ndarray` 对象。

**返回：** `~tokenization_utils_base.BatchEncoding`

- **data** (`dict`，*可选*) -- 由 `__call__`/`encode_plus`/`batch_encode_plus` 方法返回的列表/数组/张量字典（'input_ids'、'attention_mask' 等）。
- **encoding**（`tokenizers.Encoding` 或 `Sequence[tokenizers.Encoding]`，*可选*）-- 如果分词器是快速分词器，并且会输出诸如从词/字符空间到 token 空间的映射等附加信息，则 `tokenizers.Encoding` 实例或实例列表（用于批次）将保存这些信息。
- **tensor_type** (`Union[None, str, TensorType]`，*可选*) -- 您可以在此处指定 tensor_type，以便在初始化时将 PyTorch/Numpy 张量中的整数列表进行转换。
- **prepend_batch_axis** (`bool`，*可选*，默认为 `False`) -- 在转换为张量时是否添加批次轴（参见上文中的 `tensor_type`）。请注意，仅当参数 `tensor_type` 被设置时，此参数才会生效，*否则无效*。
- **n_sequences** (`int`, *可选*) -- 每个编码所表示的输入序列数量（`None` 表示未知，`1` 表示单个序列，`2` 表示一对序列）。

## LayoutLMv2Model[[transformers.LayoutLMv2Model]]

#### transformers.LayoutLMv2Model[[transformers.LayoutLMv2Model]]

```python
transformers.LayoutLMv2Model(config: LayoutLMv2Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/modeling_layoutlmv2.py#L551)

**参数：**

config ([LayoutLMv2Config](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Config))：模型配置类，包含模型的所有参数。通过配置文件进行初始化并不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

未添加任何特定头部的裸 Layoutlmv2 模型，输出原始隐藏状态。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.LayoutLMv2Model.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, bbox: typing.Optional[torch.LongTensor] = None, image: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, token_type_ids: typing.Optional[torch.LongTensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/modeling_layoutlmv2.py#L663)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

bbox (`torch.LongTensor`，形状为 `((batch_size, sequence_length), 4)`，*可选*)：每个输入序列中各个 token 的边界框。取值范围为 `[0, config.max_2d_position_embeddings-1]`。每个边界框应为 (x0, y0, x1, y1) 格式的归一化版本，其中 (x0, y0) 对应边界框左上角的位置，(x1, y1) 表示右下角的位置。

image （形状为 `(batch_size, num_channels, height, width)` 的 `torch.Tensor`，或 `tensors` 形状为 `(batch_size, num_channels, height, width)` 的 `detectron.structures.ImageList`）：一批文档图像。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

token_type_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于指示输入中第一和第二部分的段标记索引。索引选自 `[0, 1]`： - 0 对应 *句子 A* 的标记， - 1 对应 *句子 B* 的标记。 [什么是标记类型 ID？](../glossary#token-type-ids)

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

**返回：** [BaseModelOutputWithPooling](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) 或 `tuple(torch.Tensor)`

一个 [BaseModelOutputWithPooling](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[LayoutLMv2Config](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Config)）和输入。

[LayoutLMv2Model](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Model) 的 forward 方法会重写 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。
- **pooler_output**（形状为 `(batch_size, hidden_size)` 的 `torch.Tensor`）-- 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后的结果。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重是在预训练期间通过下一句预测（分类）目标训练得到的。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

示例：

```python
>>> from transformers import AutoProcessor, LayoutLMv2Model, set_seed
>>> from PIL import Image
>>> import torch
>>> from datasets import load_dataset

>>> set_seed(0)

>>> processor = AutoProcessor.from_pretrained("microsoft/layoutlmv2-base-uncased")
>>> model = LayoutLMv2Model.from_pretrained("microsoft/layoutlmv2-base-uncased")

>>> dataset = load_dataset("hf-internal-testing/fixtures_docvqa")
>>> image = dataset["test"][0]["image"]

>>> encoding = processor(image, return_tensors="pt")

>>> outputs = model(**encoding)
>>> last_hidden_states = outputs.last_hidden_state

>>> last_hidden_states.shape
torch.Size([1, 342, 768])
```

## LayoutLMv2ForSequenceClassification[[transformers.LayoutLMv2ForSequenceClassification]]

#### transformers.LayoutLMv2ForSequenceClassification[[transformers.LayoutLMv2ForSequenceClassification]]

```python
transformers.LayoutLMv2ForSequenceClassification(config: LayoutLMv2Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/modeling_layoutlmv2.py#L792)

**参数：**

config ([LayoutLMv2Config](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Config))：模型配置类，包含模型的所有参数。通过配置文件进行初始化并不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

在顶部带有序列分类头的 LayoutLMv2 模型（在 [CLS] token 的最终隐藏状态、平均池化的初始视觉嵌入和平均池化的最终视觉嵌入的拼接之上添加一个线性层，例如用于文档图像分类任务，如 [RVL-CDIP](https://www.cs.cmu.edu/~aharley/rvl-cdip/) 数据集）。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.LayoutLMv2ForSequenceClassification.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, bbox: typing.Optional[torch.LongTensor] = None, image: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, token_type_ids: typing.Optional[torch.LongTensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/modeling_layoutlmv2.py#L806)

**参数：**

input_ids (`torch.LongTensor`，形状为 `batch_size, sequence_length`)：输入序列词元在词汇表中的索引。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

bbox (`torch.LongTensor`，形状为 `(batch_size, sequence_length, 4)`，*可选*) : 每个输入序列中各个标记的边界框。取值范围为 `[0, config.max_2d_position_embeddings-1]`。每个边界框应为 (x0, y0, x1, y1) 格式的归一化版本，其中 (x0, y0) 对应边界框左上角的位置，(x1, y1) 表示右下角的位置。

image （形状为 `(batch_size, num_channels, height, width)` 的 `torch.Tensor`，或 `tensors` 形状为 `(batch_size, num_channels, height, width)` 的 `detectron.structures.ImageList`）：一批文档图像。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

token_type_ids (`torch.LongTensor`，形状为 `batch_size, sequence_length`，*可选*)：用于指示输入中第一和第二部分的段标记索引。索引选自 `[0, 1]`： - 0 对应 *句子 A* 标记， - 1 对应 *句子 B* 标记。 [什么是标记类型 ID？](../glossary#token-type-ids)

position_ids (`torch.LongTensor`，形状为 `batch_size, sequence_length`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.max_position_embeddings - 1]`。[什么是位置 ID？](../glossary#position-ids)

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

labels (`torch.LongTensor`，形状为 `(batch_size,)`，*可选*)：用于计算序列分类/回归损失的标签。索引应在 `[0, ..., config.num_labels - 1]` 范围内。如果 `config.num_labels == 1`，则计算回归损失（均方损失）；如果 `config.num_labels > 1`，则计算分类损失（交叉熵）。

**返回：** [SequenceClassifierOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.SequenceClassifierOutput) 或 `tuple(torch.Tensor)`

一个 [SequenceClassifierOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.SequenceClassifierOutput) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[LayoutLMv2Config](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Config)）和输入。

[LayoutLMv2ForSequenceClassification](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2ForSequenceClassification) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 分类损失（如果 config.num_labels==1，则为回归损失）。
- **logits**（形状为 `(batch_size, config.num_labels)` 的 `torch.Tensor`）-- 分类（或当 config.num_labels==1 时为回归）得分（SoftMax 之前）。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

示例：

```python
>>> from transformers import AutoProcessor, LayoutLMv2ForSequenceClassification, set_seed
>>> from PIL import Image
>>> import torch
>>> from datasets import load_dataset

>>> set_seed(0)

>>> dataset = load_dataset("aharley/rvl_cdip", split="train", streaming=True)
>>> data = next(iter(dataset))
>>> image = data["image"].convert("RGB")

>>> processor = AutoProcessor.from_pretrained("microsoft/layoutlmv2-base-uncased")
>>> model = LayoutLMv2ForSequenceClassification.from_pretrained(
...     "microsoft/layoutlmv2-base-uncased", num_labels=dataset.info.features["label"].num_classes
... )

>>> encoding = processor(image, return_tensors="pt")
>>> sequence_label = torch.tensor([data["label"]])

>>> outputs = model(**encoding, labels=sequence_label)

>>> loss, logits = outputs.loss, outputs.logits
>>> predicted_idx = logits.argmax(dim=-1).item()
>>> predicted_answer = dataset.info.features["label"].names[4]
>>> predicted_idx, predicted_answer  # results are not good without further fine-tuning
(7, 'advertisement')
```

## LayoutLMv2ForTokenClassification[[transformers.LayoutLMv2ForTokenClassification]]

#### transformers.LayoutLMv2ForTokenClassification[[transformers.LayoutLMv2ForTokenClassification]]

```python
transformers.LayoutLMv2ForTokenClassification(config: LayoutLMv2Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/modeling_layoutlmv2.py#L986)

**参数：**

config ([LayoutLMv2Config](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Config))：模型配置类，包含模型的所有参数。通过配置文件进行初始化并不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

在顶部添加了一个用于序列标注（信息提取）任务的令牌分类头（即在隐藏状态文本部分之上的一个线性层）的 LayoutLMv2 模型，例如用于 [FUNSD](https://guillaumejaume.github.io/FUNSD/)、[SROIE](https://rrc.cvc.uab.es/?ch=13)、[CORD](https://github.com/clovaai/cord) 和 [Kleister-NDA](https://github.com/applicaai/kleister-nda) 等任务。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.LayoutLMv2ForTokenClassification.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, bbox: typing.Optional[torch.LongTensor] = None, image: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, token_type_ids: typing.Optional[torch.LongTensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/modeling_layoutlmv2.py#L1000)

**参数：**

input_ids (`torch.LongTensor`，形状为 `batch_size, sequence_length`)：输入序列词元在词汇表中的索引。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

bbox (`torch.LongTensor`，形状为 `(batch_size, sequence_length, 4)`，*可选*) : 每个输入序列中各个标记的边界框。取值范围为 `[0, config.max_2d_position_embeddings-1]`。每个边界框应为 (x0, y0, x1, y1) 格式的归一化版本，其中 (x0, y0) 对应边界框左上角的位置，(x1, y1) 表示右下角的位置。

image （形状为 `(batch_size, num_channels, height, width)` 的 `torch.Tensor`，或 `tensors` 形状为 `(batch_size, num_channels, height, width)` 的 `detectron.structures.ImageList`）：一批文档图像。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

token_type_ids (`torch.LongTensor`，形状为 `batch_size, sequence_length`，*可选*)：用于指示输入中第一和第二部分的段标记索引。索引选自 `[0, 1]`： - 0 对应 *句子 A* 标记， - 1 对应 *句子 B* 标记。 [什么是标记类型 ID？](../glossary#token-type-ids)

position_ids (`torch.LongTensor`，形状为 `batch_size, sequence_length`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.max_position_embeddings - 1]`。[什么是位置 ID？](../glossary#position-ids)

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

labels (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于计算 token 分类损失的标签。索引应在 `[0, ..., config.num_labels - 1]` 范围内。

**返回：** [TokenClassifierOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.TokenClassifierOutput) 或 `tuple(torch.Tensor)`

一个 [TokenClassifierOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.TokenClassifierOutput) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[LayoutLMv2Config](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Config)）和输入。

[LayoutLMv2ForTokenClassification](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2ForTokenClassification) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，在提供 `labels` 时返回) -- 分类损失。
- **logits**（形状为 `(batch_size, sequence_length, config.num_labels)` 的 `torch.Tensor`）-- 分类分数（SoftMax 之前）。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

示例：

```python
>>> from transformers import AutoProcessor, LayoutLMv2ForTokenClassification, set_seed
>>> from PIL import Image
>>> from datasets import load_dataset

>>> set_seed(0)

>>> datasets = load_dataset("nielsr/funsd", split="test")
>>> labels = datasets.features["ner_tags"].feature.names
>>> id2label = {v: k for v, k in enumerate(labels)}

>>> processor = AutoProcessor.from_pretrained("microsoft/layoutlmv2-base-uncased", revision="no_ocr")
>>> model = LayoutLMv2ForTokenClassification.from_pretrained(
...     "microsoft/layoutlmv2-base-uncased", num_labels=len(labels)
... )

>>> data = datasets[0]
>>> image = Image.open(data["image_path"]).convert("RGB")
>>> words = data["words"]
>>> boxes = data["bboxes"]  # make sure to normalize your bounding boxes
>>> word_labels = data["ner_tags"]
>>> encoding = processor(
...     image,
...     words,
...     boxes=boxes,
...     word_labels=word_labels,
...     padding="max_length",
...     truncation=True,
...     return_tensors="pt",
... )

>>> outputs = model(**encoding)
>>> logits, loss = outputs.logits, outputs.loss

>>> predicted_token_class_ids = logits.argmax(-1)
>>> predicted_tokens_classes = [id2label[t.item()] for t in predicted_token_class_ids[0]]
>>> predicted_tokens_classes[:5]  # results are not good without further fine-tuning
['I-HEADER', 'I-HEADER', 'I-QUESTION', 'I-HEADER', 'I-QUESTION']
```

## LayoutLMv2ForQuestionAnswering[[transformers.LayoutLMv2ForQuestionAnswering]]

#### transformers.LayoutLMv2ForQuestionAnswering[[transformers.LayoutLMv2ForQuestionAnswering]]

```python
transformers.LayoutLMv2ForQuestionAnswering(config: LayoutLMv2Config, has_visual_segment_embedding = True)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/modeling_layoutlmv2.py#L1121)

**参数：**

config ([LayoutLMv2Config](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Config))：模型配置类，包含模型的所有参数。通过配置文件进行初始化并不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

has_visual_segment_embedding (`bool`，*可选*，默认为 `True`)：是否添加视觉分段嵌入。

带有跨度分类头的 Layoutlmv2 转换器，用于 SQuAD 等抽取式问答任务（在隐藏状态输出之上添加一个线性层，以计算`span start logits`和`span end logits`）。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.LayoutLMv2ForQuestionAnswering.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, bbox: typing.Optional[torch.LongTensor] = None, image: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, token_type_ids: typing.Optional[torch.LongTensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, start_positions: typing.Optional[torch.LongTensor] = None, end_positions: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlmv2/modeling_layoutlmv2.py#L1139)

**参数：**

input_ids (`torch.LongTensor`，形状为 `batch_size, sequence_length`)：输入序列词元在词汇表中的索引。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

bbox (`torch.LongTensor`，形状为 `(batch_size, sequence_length, 4)`，*可选*) : 每个输入序列中各个标记的边界框。取值范围为 `[0, config.max_2d_position_embeddings-1]`。每个边界框应为 (x0, y0, x1, y1) 格式的归一化版本，其中 (x0, y0) 对应边界框左上角的位置，(x1, y1) 表示右下角的位置。

image （形状为 `(batch_size, num_channels, height, width)` 的 `torch.Tensor`，或 `tensors` 形状为 `(batch_size, num_channels, height, width)` 的 `detectron.structures.ImageList`）：一批文档图像。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

token_type_ids (`torch.LongTensor`，形状为 `batch_size, sequence_length`，*可选*)：用于指示输入中第一和第二部分的段标记索引。索引选自 `[0, 1]`： - 0 对应 *句子 A* 标记， - 1 对应 *句子 B* 标记。 [什么是标记类型 ID？](../glossary#token-type-ids)

position_ids (`torch.LongTensor`，形状为 `batch_size, sequence_length`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.max_position_embeddings - 1]`。[什么是位置 ID？](../glossary#position-ids)

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

start_positions (`torch.LongTensor`，形状为 `(batch_size,)`，*可选*)：用于计算 token 分类损失的标注 span 起始位置（索引）的标签。位置会被截断至序列长度（`sequence_length`）。序列之外的位置在计算损失时不予考虑。

end_positions (`torch.LongTensor`，形状为 `(batch_size,)`，*可选*)：用于计算 token 分类损失的标注 span 结束位置（索引）的标签。位置会被截断至序列长度（`sequence_length`）。序列之外的位置在计算损失时不予考虑。

**返回：** [QuestionAnsweringModelOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.QuestionAnsweringModelOutput) 或 `tuple(torch.Tensor)`

一个 [QuestionAnsweringModelOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.QuestionAnsweringModelOutput) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[LayoutLMv2Config](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2Config)）和输入。

[LayoutLMv2ForQuestionAnswering](/docs/transformers/v5.23.0/zh/model_doc/layoutlmv2#transformers.LayoutLMv2ForQuestionAnswering) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 总跨度提取损失是起始位置和结束位置的交叉熵之和。
- **start_logits**（形状为 `(batch_size, sequence_length)` 的 `torch.Tensor`）-- 跨度起始分数（SoftMax 之前）。
- **end_logits**（形状为 `(batch_size, sequence_length)` 的 `torch.Tensor`）-- 跨度结束分数（SoftMax 之前）。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

示例：

在下面的示例中，我们向 LayoutLMv2 模型提供一张（包含文本的）图像并提问。模型会给出它认为的答案预测（即从图像中解析出的文本内答案所在的片段）。

```python
>>> from transformers import AutoProcessor, LayoutLMv2ForQuestionAnswering, set_seed
>>> import torch
>>> from PIL import Image
>>> from datasets import load_dataset

>>> set_seed(0)
>>> processor = AutoProcessor.from_pretrained("microsoft/layoutlmv2-base-uncased")
>>> model = LayoutLMv2ForQuestionAnswering.from_pretrained("microsoft/layoutlmv2-base-uncased")

>>> dataset = load_dataset("hf-internal-testing/fixtures_docvqa")
>>> image = dataset["test"][0]["image"]
>>> question = "When is coffee break?"
>>> encoding = processor(image, question, return_tensors="pt")

>>> outputs = model(**encoding)
>>> predicted_start_idx = outputs.start_logits.argmax(-1).item()
>>> predicted_end_idx = outputs.end_logits.argmax(-1).item()
>>> predicted_start_idx, predicted_end_idx
(30, 191)

>>> predicted_answer_tokens = encoding.input_ids.squeeze()[predicted_start_idx : predicted_end_idx + 1]
>>> predicted_answer = processor.tokenizer.decode(predicted_answer_tokens)
>>> predicted_answer  # results are not good without further fine-tuning
'44 a. m. to 12 : 25 p. m. 12 : 25 to 12 : 58 p. m. 12 : 58 to 4 : 00 p. m. 2 : 00 to 5 : 00 p. m. coffee break coffee will be served for men and women in the lobby adjacent to exhibit area. please move into exhibit area. ( exhibits open ) trrf general session ( part | ) presiding : lee a. waller trrf vice president " introductory remarks " lee a. waller, trrf vice presi - dent individual interviews with trrf public board members and sci - entific advisory council mem - bers conducted by trrf treasurer philip g. kuehn to get answers which the public refrigerated warehousing industry is looking for. plus questions from'
```

```python
>>> target_start_index = torch.tensor([7])
>>> target_end_index = torch.tensor([14])
>>> outputs = model(**encoding, start_positions=target_start_index, end_positions=target_end_index)
>>> predicted_answer_span_start = outputs.start_logits.argmax(-1).item()
>>> predicted_answer_span_end = outputs.end_logits.argmax(-1).item()
>>> predicted_answer_span_start, predicted_answer_span_end
(30, 191)
```

