# LayoutLM

[LayoutLM](https://huggingface.co/papers/1912.13318) 同时学习文本和文档布局，而不仅仅关注文本。它整合了来自文档图像的单词位置布局信息和视觉特征。

您可以在 [LayoutLM](https://huggingface.co/collections/microsoft/layoutlm-6564539601de72cb631d0902) 集合中找到所有原始的 LayoutLM 检查点。

> [!TIP]
> 点击右侧边栏中的 LayoutLM 模型，以查看将 LayoutLM 应用于不同视觉和语言任务的更多示例。

以下示例演示了如何使用 [AutoModel](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoModel) 类进行问答。

```python
import torch
from datasets import load_dataset

from transformers import AutoTokenizer, LayoutLMForQuestionAnswering

tokenizer = AutoTokenizer.from_pretrained("impira/layoutlm-document-qa", add_prefix_space=True)
model = LayoutLMForQuestionAnswering.from_pretrained("impira/layoutlm-document-qa", device_map="auto")

dataset = load_dataset("nielsr/funsd", split="train")
example = dataset[0]
question = "what's his name?"
words = example["words"]
boxes = example["bboxes"]

encoding = tokenizer(
    question.split(),
    words,
    is_split_into_words=True,
    return_token_type_ids=True,
    return_tensors="pt"
)
bbox = []
for i, s, w in zip(encoding.input_ids[0], encoding.sequence_ids(0), encoding.word_ids(0)):
    if s == 1:
        bbox.append(boxes[w])
    elif i == tokenizer.sep_token_id:
        bbox.append([1000] * 4)
    else:
        bbox.append([0] * 4)
encoding["bbox"] = torch.tensor([bbox])

word_ids = encoding.word_ids(0)
outputs = model(**encoding)
loss = outputs.loss
start_scores = outputs.start_logits
end_scores = outputs.end_logits
start, end = word_ids[start_scores.argmax(-1)], word_ids[end_scores.argmax(-1)]
print(" ".join(words[start : end + 1]))
```

## 备注

- 原始的 LayoutLM 并未设计统一的处理流程。相反，它期望从外部 OCR 引擎（如 [Pytesseract](https://pypi.org/project/pytesseract/)）获取预处理后的文本（`words`）和边界框（`boxes`），并将它们作为额外输入提供给分词器。

- [forward()](/docs/transformers/v5.23.0/zh/model_doc/layoutlm#transformers.LayoutLMModel.forward) 方法期望输入 `bbox`（输入标记的边界框）。每个边界框的格式应为 `(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
from PIL import Image

# Document can be a png, jpg, etc. PDFs must be converted to images.
image = Image.open(name_of_your_document).convert("RGB")

width, height = image.size
```

## 资源

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

- 阅读 [使用 Keras 和 Hugging Face Transformers 微调 LayoutLM 以实现文档理解](https://www.philschmid.de/fine-tuning-layoutlm-keras) 以了解更多信息。
- 阅读 [仅使用 Hugging Face Transformers 对 LayoutLM 进行微调以实现文档理解](https://www.philschmid.de/fine-tuning-layoutlm) 以获取更多信息。
- 请参阅此 [notebook](https://colab.research.google.com/github/NielsRogge/Transformers-Tutorials/blob/master/LayoutLM/Add_image_embeddings_to_LayoutLM.ipynb)，了解如何微调 LayoutLM 的实用示例。
- 请参阅此 [notebook](https://colab.research.google.com/github/NielsRogge/Transformers-Tutorials/blob/master/LayoutLM/Fine_tuning_LayoutLMForSequenceClassification_on_RVL_CDIP.ipynb)，了解如何微调 LayoutLM 以进行序列分类的示例。
- 请参阅此 [notebook](https://github.com/NielsRogge/Transformers-Tutorials/blob/master/LayoutLM/Fine_tuning_LayoutLMForTokenClassification_on_FUNSD.ipynb)，了解如何微调 LayoutLM 以进行 token 分类的示例。
- 阅读 [使用 Hugging Face Inference Endpoints 部署 LayoutLM](https://www.philschmid.de/inference-endpoints-layoutlm)，了解如何部署 LayoutLM。

## LayoutLMConfig[[transformers.LayoutLMConfig]]

#### transformers.LayoutLMConfig[[transformers.LayoutLMConfig]]

```python
transformers.LayoutLMConfig(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, eos_token_id: int | list[int] | None = None, bos_token_id: int | None = None, use_cache: bool = True, max_2d_position_embeddings: int = 1024, tie_word_embeddings: bool = True)
```

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

**参数：**

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。

eos_token_id (`Union[int, list[int]]`，*可选*)：词汇表中用于表示流结束（end-of-stream）的 Token ID。

bos_token_id (`int`, *可选*) : 词表中用于表示流开始的 Token id。

use_cache (`bool`，*可选*，默认为 `True`)：模型是否应返回最后的键/值注意力（并非所有模型都使用）。仅当 `config.is_decoder=True` 或模型为仅解码器生成模型时相关。

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

tie_word_embeddings (`bool`，*可选*，默认为 `True`)：是否根据模型的 `tied_weights_keys` 映射来绑定权重嵌入。

这是用于存储 LayoutLMModel 配置的类。它根据指定的参数实例化 Layoutlm 模型，并定义模型架构。使用默认值实例化配置将生成与 [microsoft/layoutlm-base-uncased](https://huggingface.co/microsoft/layoutlm-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 LayoutLMConfig, LayoutLMModel

>>> # Initializing a LayoutLM configuration
>>> configuration = LayoutLMConfig()

>>> # Initializing a model (with random weights) from the configuration
>>> model = LayoutLMModel(configuration)

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

## LayoutLMTokenizer[[transformers.BertTokenizer]]

#### transformers.BertTokenizer[[transformers.BertTokenizer]]

```python
transformers.BertTokenizer(vocab: str | dict[str, int] | None = None, do_lower_case: bool = True, unk_token: str = '[UNK]', sep_token: str = '[SEP]', pad_token: str = '[PAD]', cls_token: str = '[CLS]', mask_token: str = '[MASK]', tokenize_chinese_chars: bool = True, strip_accents: bool | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/bert/tokenization_bert.py#L41)

**参数：**

vocab (`str` 或 `dict[str, int]`，*可选*) : 自定义词汇表。如果未提供，则从 `vocab_file` 加载词汇表。

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]"`)：用于掩码值的标记。这是在通过掩码语言建模训练该模型时所使用的标记，也是模型将尝试预测的标记。

tokenize_chinese_chars (`bool`，*可选*，默认为 `True`)：是否对汉字进行分词。

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

构建一个 BERT 分词器（由 HuggingFace 的 tokenizers 库提供支持）。基于 WordPiece。

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

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

```python
__call__(text: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_pair: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, text_pair_target: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None, add_special_tokens: bool = True, padding: bool | str | PaddingStrategy = False, truncation: bool | str | TruncationStrategy | None = None, max_length: int | None = None, stride: int = 0, is_split_into_words: bool = False, pad_to_multiple_of: int | None = None, padding_side: str | None = None, return_tensors: str | 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, tokenizer_kwargs: dict[str, Any] | None = None, **kwargs)
```

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

**参数：**

text (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

text_pair (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

text_target (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码为目标文本的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）的形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

text_pair_target (`str`、`list[str]`、`list[list[str]]`、*可选*)：要编码为目标文本的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果以字符串列表（预分词）的形式提供序列，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

tokenizer_kwargs (`dict[str, Any]`, *可选*) : 传递给 tokenizer 的额外 kwargs。这些 kwargs 将与显式参数及其他 kwargs 合并，其中显式参数具有更高的优先级。

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)，*可选*，默认为 `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 的数量。

is_split_into_words (`bool`，*可选*，默认为 `False`)：输入是否已经预先分词（例如，已拆分为单词）。如果设置为 `True`，分词器将假设输入已经拆分为单词（例如，通过按空白字符拆分），然后对其进行分词。这对于 NER 或 token 分类很有用。

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

padding_side (`str`, *可选*) : 模型应应用填充的一侧。应在 ['right', 'left'] 中进行选择。默认值取自同名的类属性。

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回张量而不是 Python 整数列表。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 Numpy `np.ndarray` 对象。

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()` 方法

**返回：** [BatchEncoding](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.BatchEncoding)

一个包含以下字段的 [BatchEncoding](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.BatchEncoding)：

- **input_ids** -- 输入模型的 token id 列表。

  [什么是输入 ID？](../glossary#input-ids)

- **token_type_ids** -- 要输入模型的 token 类型 ID 列表（当 `return_token_type_ids=True` 或 `self.model_input_names` 中包含 *"token_type_ids"* 时）。

  [什么是 token type ID？](../glossary#token-type-ids)

- **attention_mask** -- 指定模型应关注哪些 token 的索引列表（当 `return_attention_mask=True` 或 *"attention_mask"* 位于 `self.model_input_names` 中时）。

  [什么是注意力掩码？](../glossary#attention-mask)

- **overflowing_tokens** -- 溢出 token 序列的列表（当指定了 `max_length` 且 `return_overflowing_tokens=True` 时）。
- **num_truncated_tokens** -- 被截断的 token 数量（当指定了 `max_length` 且 `return_overflowing_tokens=True` 时）。
- **special_tokens_mask** -- 由 0 和 1 组成的列表，其中 1 表示添加的特殊标记，0 表示常规序列标记（当 `add_special_tokens=True` 且 `return_special_tokens_mask=True` 时）。
- **length** -- 输入的长度（当 `return_length=True` 时）

用于对一条或多条序列，或一对或多对序列进行分词并准备输入模型的主要方法。

## LayoutLMModel[[transformers.LayoutLMModel]]

#### transformers.LayoutLMModel[[transformers.LayoutLMModel]]

```python
transformers.LayoutLMModel(config: LayoutLMConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlm/modeling_layoutlm.py#L413)

**参数：**

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

原始的 Layoutlm 模型，输出原始隐藏状态，顶部未添加任何特定的分类头。

该模型继承自 [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.LayoutLMModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, bbox: typing.Optional[torch.LongTensor] = 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/layoutlm/modeling_layoutlm.py#L431)

**参数：**

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) 表示右下角的位置。有关归一化的说明，请参阅 [概述](#Overview)。

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`），其包含的元素取决于配置（[LayoutLMConfig](/docs/transformers/v5.23.0/zh/model_doc/layoutlm#transformers.LayoutLMConfig)）和输入。

[LayoutLMModel](/docs/transformers/v5.23.0/zh/model_doc/layoutlm#transformers.LayoutLMModel) 的 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 AutoTokenizer, LayoutLMModel
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("microsoft/layoutlm-base-uncased")
>>> model = LayoutLMModel.from_pretrained("microsoft/layoutlm-base-uncased")

>>> words = ["Hello", "world"]
>>> normalized_word_boxes = [637, 773, 693, 782], [698, 773, 733, 782]

>>> token_boxes = []
>>> for word, box in zip(words, normalized_word_boxes):
...     word_tokens = tokenizer.tokenize(word)
...     token_boxes.extend([box] * len(word_tokens))
>>> # add bounding boxes of cls + sep tokens
>>> token_boxes = [[0, 0, 0, 0]] + token_boxes + [[1000, 1000, 1000, 1000]]

>>> encoding = tokenizer(" ".join(words), return_tensors="pt")
>>> input_ids = encoding["input_ids"]
>>> attention_mask = encoding["attention_mask"]
>>> token_type_ids = encoding["token_type_ids"]
>>> bbox = torch.tensor([token_boxes])

>>> outputs = model(
...     input_ids=input_ids, bbox=bbox, attention_mask=attention_mask, token_type_ids=token_type_ids
... )

>>> last_hidden_states = outputs.last_hidden_state
```

## LayoutLMForMaskedLM[[transformers.LayoutLMForMaskedLM]]

#### transformers.LayoutLMForMaskedLM[[transformers.LayoutLMForMaskedLM]]

```python
transformers.LayoutLMForMaskedLM(config: LayoutLMConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlm/modeling_layoutlm.py#L529)

**参数：**

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

带有`language modeling`头的Layoutlm模型。

该模型继承自 [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.LayoutLMForMaskedLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, bbox: typing.Optional[torch.LongTensor] = 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/layoutlm/modeling_layoutlm.py#L554)

**参数：**

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) 表示右下角的位置。有关归一化的说明，请参阅 [概述](#Overview)。

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` 索引转换为对应的向量，这将非常有用。

labels (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于计算掩码语言建模损失的标签。索引应在 `[-100, 0, ..., config.vocab_size]` 范围内（参见 `input_ids` 的文档字符串）。索引设置为 `-100` 的令牌将被忽略（掩码），损失仅针对标签在 `[0, ..., config.vocab_size]` 范围内的令牌进行计算。

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

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

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

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

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 掩码语言建模（MLM）损失。
- **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。
- **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 AutoTokenizer, LayoutLMForMaskedLM
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("microsoft/layoutlm-base-uncased")
>>> model = LayoutLMForMaskedLM.from_pretrained("microsoft/layoutlm-base-uncased")

>>> words = ["Hello", "[MASK]"]
>>> normalized_word_boxes = [637, 773, 693, 782], [698, 773, 733, 782]

>>> token_boxes = []
>>> for word, box in zip(words, normalized_word_boxes):
...     word_tokens = tokenizer.tokenize(word)
...     token_boxes.extend([box] * len(word_tokens))
>>> # add bounding boxes of cls + sep tokens
>>> token_boxes = [[0, 0, 0, 0]] + token_boxes + [[1000, 1000, 1000, 1000]]

>>> encoding = tokenizer(" ".join(words), return_tensors="pt")
>>> input_ids = encoding["input_ids"]
>>> attention_mask = encoding["attention_mask"]
>>> token_type_ids = encoding["token_type_ids"]
>>> bbox = torch.tensor([token_boxes])

>>> labels = tokenizer("Hello world", return_tensors="pt")["input_ids"]

>>> outputs = model(
...     input_ids=input_ids,
...     bbox=bbox,
...     attention_mask=attention_mask,
...     token_type_ids=token_type_ids,
...     labels=labels,
... )

>>> loss = outputs.loss
```

## LayoutLMForSequenceClassification[[transformers.LayoutLMForSequenceClassification]]

#### transformers.LayoutLMForSequenceClassification[[transformers.LayoutLMForSequenceClassification]]

```python
transformers.LayoutLMForSequenceClassification(config: LayoutLMConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlm/modeling_layoutlm.py#L646)

**参数：**

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

在顶部带有序列分类头的 LayoutLM 模型（在池化输出之上添加一个线性层），例如用于文档图像分类任务，如 [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.LayoutLMForSequenceClassification.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, bbox: typing.Optional[torch.LongTensor] = 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/layoutlm/modeling_layoutlm.py#L660)

**参数：**

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) 表示右下角的位置。有关归一化的说明，请参阅 [概述](#Overview)。

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` 索引转换为对应的向量，这将非常有用。

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`），其包含的元素取决于配置（[LayoutLMConfig](/docs/transformers/v5.23.0/zh/model_doc/layoutlm#transformers.LayoutLMConfig)）和输入。

[LayoutLMForSequenceClassification](/docs/transformers/v5.23.0/zh/model_doc/layoutlm#transformers.LayoutLMForSequenceClassification) 的 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 AutoTokenizer, LayoutLMForSequenceClassification
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("microsoft/layoutlm-base-uncased")
>>> model = LayoutLMForSequenceClassification.from_pretrained("microsoft/layoutlm-base-uncased")

>>> words = ["Hello", "world"]
>>> normalized_word_boxes = [637, 773, 693, 782], [698, 773, 733, 782]

>>> token_boxes = []
>>> for word, box in zip(words, normalized_word_boxes):
...     word_tokens = tokenizer.tokenize(word)
...     token_boxes.extend([box] * len(word_tokens))
>>> # add bounding boxes of cls + sep tokens
>>> token_boxes = [[0, 0, 0, 0]] + token_boxes + [[1000, 1000, 1000, 1000]]

>>> encoding = tokenizer(" ".join(words), return_tensors="pt")
>>> input_ids = encoding["input_ids"]
>>> attention_mask = encoding["attention_mask"]
>>> token_type_ids = encoding["token_type_ids"]
>>> bbox = torch.tensor([token_boxes])
>>> sequence_label = torch.tensor([1])

>>> outputs = model(
...     input_ids=input_ids,
...     bbox=bbox,
...     attention_mask=attention_mask,
...     token_type_ids=token_type_ids,
...     labels=sequence_label,
... )

>>> loss = outputs.loss
>>> logits = outputs.logits
```

## LayoutLMForTokenClassification[[transformers.LayoutLMForTokenClassification]]

#### transformers.LayoutLMForTokenClassification[[transformers.LayoutLMForTokenClassification]]

```python
transformers.LayoutLMForTokenClassification(config: LayoutLMConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlm/modeling_layoutlm.py#L770)

**参数：**

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

在隐藏状态输出之上添加一个用于 token 分类的头部（即一个线性层），例如用于序列标注（信息抽取）任务，如 [FUNSD](https://guillaumejaume.github.io/FUNSD/) 数据集和 [SROIE](https://rrc.cvc.uab.es/?ch=13) 数据集的 LayoutLM 模型。

该模型继承自 [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.LayoutLMForTokenClassification.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, bbox: typing.Optional[torch.LongTensor] = 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/layoutlm/modeling_layoutlm.py#L784)

**参数：**

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) 表示右下角的位置。有关归一化的说明，请参阅 [概述](#Overview)。

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` 索引转换为对应的向量，这将非常有用。

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`），其包含的元素取决于配置（[LayoutLMConfig](/docs/transformers/v5.23.0/zh/model_doc/layoutlm#transformers.LayoutLMConfig)）和输入。

[LayoutLMForTokenClassification](/docs/transformers/v5.23.0/zh/model_doc/layoutlm#transformers.LayoutLMForTokenClassification) 的 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 AutoTokenizer, LayoutLMForTokenClassification
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("microsoft/layoutlm-base-uncased")
>>> model = LayoutLMForTokenClassification.from_pretrained("microsoft/layoutlm-base-uncased")

>>> words = ["Hello", "world"]
>>> normalized_word_boxes = [637, 773, 693, 782], [698, 773, 733, 782]

>>> token_boxes = []
>>> for word, box in zip(words, normalized_word_boxes):
...     word_tokens = tokenizer.tokenize(word)
...     token_boxes.extend([box] * len(word_tokens))
>>> # add bounding boxes of cls + sep tokens
>>> token_boxes = [[0, 0, 0, 0]] + token_boxes + [[1000, 1000, 1000, 1000]]

>>> encoding = tokenizer(" ".join(words), return_tensors="pt")
>>> input_ids = encoding["input_ids"]
>>> attention_mask = encoding["attention_mask"]
>>> token_type_ids = encoding["token_type_ids"]
>>> bbox = torch.tensor([token_boxes])
>>> token_labels = torch.tensor([1, 1, 0, 0]).unsqueeze(0)  # batch size of 1

>>> outputs = model(
...     input_ids=input_ids,
...     bbox=bbox,
...     attention_mask=attention_mask,
...     token_type_ids=token_type_ids,
...     labels=token_labels,
... )

>>> loss = outputs.loss
>>> logits = outputs.logits
```

## LayoutLMForQuestionAnswering[[transformers.LayoutLMForQuestionAnswering]]

#### transformers.LayoutLMForQuestionAnswering[[transformers.LayoutLMForQuestionAnswering]]

```python
transformers.LayoutLMForQuestionAnswering(config: LayoutLMConfig, has_visual_segment_embedding = True)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/layoutlm/modeling_layoutlm.py#L870)

**参数：**

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

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

带有跨度分类头的 Layoutlm 变换器，用于 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.LayoutLMForQuestionAnswering.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, bbox: typing.Optional[torch.LongTensor] = 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/layoutlm/modeling_layoutlm.py#L888)

**参数：**

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) 表示右下角的位置。有关归一化的说明，请参阅 [概述](#Overview)。

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` 索引转换为对应的向量，这将非常有用。

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`），其包含的元素取决于配置（[LayoutLMConfig](/docs/transformers/v5.23.0/zh/model_doc/layoutlm#transformers.LayoutLMConfig)）和输入。

[LayoutLMForQuestionAnswering](/docs/transformers/v5.23.0/zh/model_doc/layoutlm#transformers.LayoutLMForQuestionAnswering) 的 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 后的注意力权重，用于在自注意力头中计算加权平均值。

示例：

在下面的示例中，我们为 LayoutLM 模型准备了一个问题 + 上下文对。它将给出模型认为的答案预测（即从图像中解析出的文本内答案所在的片段）。

```python
>>> from transformers import AutoTokenizer, LayoutLMForQuestionAnswering
>>> from datasets import load_dataset
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("impira/layoutlm-document-qa", add_prefix_space=True)
>>> model = LayoutLMForQuestionAnswering.from_pretrained("impira/layoutlm-document-qa", revision="1e3ebac")

>>> dataset = load_dataset("nielsr/funsd", split="train")
>>> example = dataset[0]
>>> question = "what's his name?"
>>> words = example["words"]
>>> boxes = example["bboxes"]

>>> encoding = tokenizer(
...     question.split(), words, is_split_into_words=True, return_token_type_ids=True, return_tensors="pt"
... )
>>> bbox = []
>>> for i, s, w in zip(encoding.input_ids[0], encoding.sequence_ids(0), encoding.word_ids(0)):
...     if s == 1:
...         bbox.append(boxes[w])
...     elif i == tokenizer.sep_token_id:
...         bbox.append([1000] * 4)
...     else:
...         bbox.append([0] * 4)
>>> encoding["bbox"] = torch.tensor([bbox])

>>> word_ids = encoding.word_ids(0)
>>> outputs = model(**encoding)
>>> loss = outputs.loss
>>> start_scores = outputs.start_logits
>>> end_scores = outputs.end_logits
>>> start, end = word_ids[start_scores.argmax(-1)], word_ids[end_scores.argmax(-1)]
>>> print(" ".join(words[start : end + 1]))
M. Hamann P. Harper, P. Martinez
```

