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

原文：huggingface.co/docs/transformers

LayoutLM

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

概述

LayoutLM 模型是由 Yiheng Xu，Minghao Li，Lei Cui，Shaohan Huang，Furu Wei 和 Ming Zhou 在论文LayoutLM: Pre-training of Text and Layout for Document Image Understanding中提出的。这是一种简单但有效的文本和布局预训练方法，用于文档图像理解和信息提取任务，如表单理解和收据理解。它在几个下游任务上取得了最先进的结果：

• 表单理解：FUNSD数据集（包含 199 个带有超过 30,000 个单词的注释表单）。
  
• 收据理解：SROIE数据集（包含 626 张收据用于训练和 347 张收据用于测试）。
  
• 文档图像分类：RVL-CDIP数据集（包含 400,000 张图像，属于 16 个类别之一）。
  

论文摘要如下：

近年来，预训练技术在各种 NLP 任务中取得了成功。尽管预训练模型在 NLP  应用中被广泛使用，但它们几乎完全专注于文本级别的操作，而忽略了对于文档图像理解至关重要的布局和样式信息。在本文中，我们提出了  LayoutLM，以共同建模扫描文档图像中文本和布局信息之间的交互，这对于许多真实世界的文档图像理解任务（如从扫描文档中提取信息）是有益的。此外，我们还利用图像特征将单词的视觉信息整合到  LayoutLM  中。据我们所知，这是文本和布局首次在单个框架中共同学习以进行文档级预训练。它在几个下游任务中取得了最新的最先进结果，包括表单理解（从 70.72  到 79.27）、收据理解（从 94.02 到 95.24）和文档图像分类（从 93.07 到 94.42）。

使用提示

• 除了input_ids之外，forward()还需要输入bbox，这是输入标记的边界框（即 2D 位置）。这些可以使用外部 OCR 引擎（如 Google 的Tesseract）获取（有一个Python 包装器可用）。每个边界框应该采用（x0，y0，x1，y1）格式，其中（x0，y0）对应于边界框左上角的位置，（x1，y1）表示右下角的位置。请注意，首先需要将边界框归一化为 0-1000 的比例。要进行归一化，可以使用以下函数：

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对应于标记出现的原始文档的宽度和高度。可以使用 Python Image Library（PIL）库来获取这些，例如：

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 进行文档理解微调的博文。
  
• 一篇关于如何仅使用 Hugging Face Transformers 对 LayoutLM 进行文档理解微调的博文。
  
• 关于如何在 FUNSD 数据集上使用图像嵌入来微调 LayoutLM 模型的笔记本。
  
• 另请参阅：文档问答任务指南
  

文本分类

• 关于如何在 RVL-CDIP 数据集上微调 LayoutLM 用于序列分类的笔记本。
  
• 文本分类任务指南
  

标记分类

• 关于如何在 FUNSD 数据集上微调 LayoutLM 用于标记分类的笔记本。
  
• 标记分类任务指南
  

其他资源

• 掩码语言建模任务指南

🚀 部署

• 关于如何使用 Hugging Face 推理端点部署 LayoutLM的博客文章。

LayoutLMConfig

class transformers.LayoutLMConfig

<来源>

( vocab_size = 30522 hidden_size = 768 num_hidden_layers = 12 num_attention_heads = 12 intermediate_size = 3072 hidden_act = 'gelu' hidden_dropout_prob = 0.1 attention_probs_dropout_prob = 0.1 max_position_embeddings = 512 type_vocab_size = 2 initializer_range = 0.02 layer_norm_eps = 1e-12 pad_token_id = 0 position_embedding_type = 'absolute' use_cache = True max_2d_position_embeddings = 1024 **kwargs )

参数

• vocab_size (int, optional, defaults to 30522) — LayoutLM 模型的词汇表大小。定义了可以由传递给 LayoutLMModel 的inputs_ids表示的不同标记。
  
• hidden_size (int, optional, defaults to 768) — 编码器层和池化器层的维度。
  
• num_hidden_layers (int, optional, defaults to 12) — Transformer 编码器中的隐藏层数量。
  
• num_attention_heads (int, optional, defaults to 12) — Transformer 编码器中每个注意力层的注意力头数。
  
• intermediate_size (int, optional, defaults to 3072) — Transformer 编码器中“中间”（即前馈）层的维度。
  
• hidden_act (str or function, optional, defaults to "gelu") — 编码器和池化器中的非线性激活函数（函数或字符串）。如果是字符串，支持"gelu"、"relu"、"silu"和"gelu_new"。
  
• hidden_dropout_prob (float, optional, defaults to 0.1) — 嵌入层、编码器和池化器中所有全连接层的丢弃概率。
  
• attention_probs_dropout_prob (float, optional, defaults to 0.1) — 注意力概率的丢弃比率。
  
• max_position_embeddings (int, optional, defaults to 512) — 此模型可能使用的最大序列长度。通常将其设置为较大的值以防万一（例如，512、1024 或 2048）。
  
• type_vocab_size (int, optional, defaults to 2) — 传递给 LayoutLMModel 的token_type_ids的词汇表大小。
  
• initializer_range (float, optional, defaults to 0.02) — 用于初始化所有权重矩阵的截断正态初始化器的标准差。
  
• layer_norm_eps (float, optional, defaults to 1e-12) — 层归一化层使用的 epsilon。
  
• pad_token_id (int, optional, defaults to 0) — 用于填充input_ids的值。
  
• position_embedding_type (str, optional, defaults to "absolute") — 位置嵌入的类型。选择"absolute"、"relative_key"、"relative_key_query"中的一个。对于位置嵌入，请使用"absolute"。有关"relative_key"的更多信息，请参考具有相对位置表示的自注意力（Shaw 等人）。有关"relative_key_query"的更多信息，请参考[使用更好的相对位置嵌入改进 Transformer 模型（Huang 等人）]中的方法 4（https://arxiv.org/abs/2009.13658）。
  
• use_cache (bool, optional, defaults to True) — 模型是否应返回最后的键/值注意力（并非所有模型都使用）。仅在config.is_decoder=True时相关。
  
• max_2d_position_embeddings (int, optional, defaults to 1024) — 2D 位置嵌入可能使用的最大值。通常将其设置为较大的值以防万一（例如，1024）。
  

这是配置类，用于存储 LayoutLMModel 的配置。它用于根据指定的参数实例化 LayoutLM 模型，定义模型架构。使用默认值实例化配置将产生类似于 LayoutLM microsoft/layoutlm-base-uncased架构的配置。

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

示例：

>>> 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

class transformers.LayoutLMTokenizer

<来源>

( vocab_file do_lower_case = True do_basic_tokenize = True never_split = None unk_token = '[UNK]' sep_token = '[SEP]' pad_token = '[PAD]' cls_token = '[CLS]' mask_token = '[MASK]' tokenize_chinese_chars = True strip_accents = None **kwargs )

参数

• vocab_file (str) — 包含词汇表的文件。
  
• do_lower_case (bool, optional, defaults to True) — 是否在标记化时将输入转换为小写。
  
• do_basic_tokenize (bool, optional, defaults to True) — 是否在 WordPiece 之前进行基本标记化。
  
• never_split (Iterable, optional) — 在标记化过程中永远不会被拆分的标记集合。仅在do_basic_tokenize=True时生效。
  
• unk_token (str, optional, defaults to "[UNK]") — 未知标记。词汇表中不存在的标记无法转换为 ID，而是设置为此标记。
  
• sep_token (str, optional, defaults to "[SEP]") — 分隔符标记，在从多个序列构建序列时使用，例如用于序列分类的两个序列或用于文本和问题的问题回答。它也用作使用特殊标记构建的序列的最后一个标记。
  
• pad_token (str, optional, defaults to "[PAD]") — 用于填充的标记，例如在批处理不同长度的序列时使用。
  
• cls_token (str, optional, defaults to "[CLS]") — 分类器标记，用于进行序列分类（对整个序列进行分类，而不是每个标记的分类）。在构建带有特殊标记的序列时，它是序列的第一个标记。
  
• mask_token (str, optional, defaults to "[MASK]") — 用于屏蔽值的标记。这是在使用掩码语言建模训练此模型时使用的标记。这是模型将尝试预测的标记。
  
• tokenize_chinese_chars (bool, optional, defaults to True) — 是否对中文字符进行标记化。
  对于日语，这可能应该被停用（请参阅此问题）。
  
• strip_accents (bool, optional) — 是否去除所有重音符号。如果未指定此选项，则将由lowercase的值确定（与原始 LayoutLM 中的情况相同）。
  

构建一个基于 WordPiece 的 LayoutLM 分词器。

此分词器继承自 PreTrainedTokenizer，其中包含大部分主要方法。用户应参考此超类以获取有关这些方法的更多信息。

build_inputs_with_special_tokens

<来源>

( token_ids_0: List token_ids_1: Optional = None ) → export const metadata = 'undefined';List[int]

参数

• token_ids_0 (List[int]) — 将添加特殊标记的 ID 列表。
  
• token_ids_1 (List[int], 可选) — 序列对的第二个 ID 列表（可选）。
  

返回

List[int]

带有适当特殊标记的 input IDs 列表。

通过连接和添加特殊标记，从序列或序列对构建用于序列分类任务的模型输入。一个 LayoutLM 序列的格式如下：

• 单个序列：[CLS] X [SEP]
  
• 序列对：[CLS] A [SEP] B [SEP]
  

convert_tokens_to_string

<来源>

( tokens )

将一系列标记（字符串）转换为单个字符串。

create_token_type_ids_from_sequences

<来源>

( token_ids_0: List token_ids_1: Optional = None ) → export const metadata = 'undefined';List[int]

参数

• token_ids_0 (List[int]) — ID 列表。
  
• token_ids_1 (List[int], 可选) — 序列对的第二个 ID 列表（可选）。
  

返回

List[int]

根据给定序列的 token type IDs 列表。

从传递的两个序列创建一个用于序列对分类任务的掩码。一个 LayoutLM 序列

序列掩码的格式如下：

0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1
| first sequence    | second sequence |

如果token_ids_1为None，则此方法仅返回掩码的第一部分（0）。

get_special_tokens_mask

<来源>

( token_ids_0: List token_ids_1: Optional = None already_has_special_tokens: bool = False ) → export const metadata = 'undefined';List[int]

参数

• token_ids_0 (List[int]) — ID 列表。
  
• token_ids_1 (List[int], 可选) — 序列对的第二个 ID 列表（可选）。
  
• already_has_special_tokens (bool, 可选, 默认为 False) — 标记列表是否已经使用特殊标记格式化为模型。
  

返回

List[int]

一个整数列表，范围为[0, 1]：1 表示特殊标记，0 表示序列标记。

从没有添加特殊标记的标记列表中检索序列 ID。当使用分词器的prepare_for_model方法添加特殊标记时，将调用此方法。

LayoutLMTokenizerFast

class transformers.LayoutLMTokenizerFast

<来源>

( vocab_file = None tokenizer_file = None do_lower_case = True unk_token = '[UNK]' sep_token = '[SEP]' pad_token = '[PAD]' cls_token = '[CLS]' mask_token = '[MASK]' tokenize_chinese_chars = True strip_accents = None **kwargs )

参数

• vocab_file (str) — 包含词汇表的文件。
  
• do_lower_case (bool, 可选, 默认为 True) — 在分词时是否将输入转换为小写。
  
• unk_token (str, 可选, 默认为 "[UNK]") — 未知标记。词汇表中没有的标记无法转换为 ID，而是设置为此标记。
  
• sep_token (str, 可选, 默认为 "[SEP]") — 分隔符标记，在构建来自多个序列的序列时使用，例如用于序列分类的两个序列或用于文本和问题的问题回答。也用作使用特殊标记构建的序列的最后一个标记。
  
• pad_token (str, 可选, 默认为 "[PAD]") — 用于填充的标记，例如在批处理不同长度的序列时使用。
  
• cls_token (str, 可选, 默认为 "[CLS]") — 在进行序列分类（整个序列而不是每个标记的分类）时使用的分类器标记。构建时是序列的第一个标记。
  
• mask_token (str, optional, defaults to "[MASK]") — 用于屏蔽值的标记。这是在使用掩码语言建模训练此模型时使用的标记。这是模型将尝试预测的标记。
  
• clean_text (bool, optional, defaults to True) — 是否在标记化之前清理文本，通过删除任何控制字符并将所有空格替换为经典空格。
  
• tokenize_chinese_chars (bool, optional, defaults to True) — 是否对中文字符进行分词。对于日语，这可能应该被禁用（参见此问题）。
  
• strip_accents (bool, optional) — 是否去除所有重音符号。如果未指定此选项，则将由lowercase的值确定（与原始 LayoutLM 中相同）。
  
• wordpieces_prefix (str, optional, defaults to "##") — 子词的前缀。
  

构建一个“快速”LayoutLM 标记器（由 HuggingFace 的tokenizers库支持）。基于 WordPiece。

此标记器继承自 PreTrainedTokenizerFast，其中包含大多数主要方法。用户应参考此超类以获取有关这些方法的更多信息。

build_inputs_with_special_tokens

<来源>

( token_ids_0 token_ids_1 = None ) → export const metadata = 'undefined';List[int]

参数

• token_ids_0 (List[int]) — 将添加特殊标记的 ID 列表。
  
• token_ids_1 (List[int], optional) — 序列对的可选第二个 ID 列表。
  

返回

List[int]

具有适当特殊标记的 input IDs 列表。

从序列或序列对构建用于序列分类任务的模型输入，通过连接和添加特殊标记。一个 LayoutLM 序列具有以下格式：

• 单个序列：[CLS] X [SEP]
  
• 序列对：[CLS] A [SEP] B [SEP]
  

create_token_type_ids_from_sequences

<来源>

( token_ids_0: List token_ids_1: Optional = None ) → export const metadata = 'undefined';List[int]

参数

• token_ids_0 (List[int]) — ID 列表。
  
• token_ids_1 (List[int], optional) — 序列对的可选第二个 ID 列表。
  

返回

List[int]

根据给定序列的 token type IDs 列表。

从传递的两个序列创建用于序列对分类任务的掩码。一个 LayoutLM 序列

序列掩码具有以下格式：

0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1
| first sequence    | second sequence |

如果token_ids_1为None，则此方法仅返回掩码的第一部分（0s）。

PytorchHide Pytorch 内容

LayoutLMModel

class transformers.LayoutLMModel

<来源>

( config )

参数

• config (LayoutLMConfig) — 具有模型所有参数的模型配置类。使用配置文件初始化不会加载与模型关联的权重，只加载配置。查看 from_pretrained()方法以加载模型权重。

裸的 LayoutLM 模型变压器输出原始隐藏状态，没有特定的头部。LayoutLM 模型由 Yiheng Xu、Minghao Li、Lei Cui、Shaohan Huang、Furu Wei 和 Ming Zhou 在LayoutLM: Pre-training of Text and Layout for Document Image Understanding中提出。

此模型是 PyTorch torch.nn.Module子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档以获取有关一般用法和行为的所有相关信息。

forward

<来源>

( input_ids: Optional = None bbox: Optional = None attention_mask: Optional = None token_type_ids: Optional = None position_ids: Optional = None head_mask: Optional = None inputs_embeds: Optional = None encoder_hidden_states: Optional = None encoder_attention_mask: Optional = None output_attentions: Optional = None output_hidden_states: Optional = None return_dict: Optional = None ) → export const metadata = 'undefined';transformers.modeling_outputs.BaseModelOutputWithPoolingAndCrossAttentions or tuple(torch.FloatTensor)

参数

• input_ids (torch.LongTensor of shape (batch_size, sequence_length)) — 词汇表中输入序列标记的索引。
  可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。
  什么是输入 ID？
  
• bbox (torch.LongTensor of shape (batch_size, sequence_length, 4), optional) — 每个输入序列标记的边界框。选择范围为[0, config.max_2d_position_embeddings-1]。每个边界框应该是(x0, y0, x1, y1)格式的归一化版本，其中(x0, y0)对应于边界框左上角的位置，(x1, y1)表示右下角的位置。有关归一化，请参阅概述。
  
• attention_mask (torch.FloatTensor of shape (batch_size, sequence_length), optional) — 用于避免在填充标记索引上执行注意力的掩码。选择在[0, 1]范围内的掩码值：1表示未被掩盖的标记，0表示被掩盖的标记。
  什么是注意力掩码？
  
• token_type_ids (torch.LongTensor of shape (batch_size, sequence_length), optional) — 段标记索引，指示输入的第一部分和第二部分。索引选择在[0, 1]：0对应于句子 A标记，1对应于句子 B标记
  什么是标记类型 ID？
  
• position_ids (torch.LongTensor of shape (batch_size, sequence_length), optional) — 每个输入序列标记在位置嵌入中的位置索引。选择范围为[0, config.max_position_embeddings - 1]。
  什么是位置 ID？
  
• head_mask (torch.FloatTensor of shape (num_heads,) or (num_layers, num_heads), optional) — 用于使自注意力模块的选定头部失效的掩码。选择的掩码值在[0, 1]范围内：1表示头部未被掩盖，0表示头部被掩盖。
  
• inputs_embeds (torch.FloatTensor of shape (batch_size, sequence_length, hidden_size), optional) — 可选地，您可以选择直接传递嵌入表示而不是传递input_ids。如果您想要更多控制如何将input_ids索引转换为相关向量，这将非常有用，而不是使用模型的内部嵌入查找矩阵。
  
• output_attentions (bool, optional) — 如果设置为True，则返回所有注意力层的注意力张量。有关更多详细信息，请参阅返回张量下的attentions。
  
• output_hidden_states (bool, optional) — 如果设置为True，则返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量下的hidden_states。
  
• return_dict (bool, optional) — 如果设置为True，模型将返回一个 ModelOutput 而不是一个普通的元组。
  

返回

transformers.modeling_outputs.BaseModelOutputWithPoolingAndCrossAttentions 或tuple(torch.FloatTensor)

一个 transformers.modeling_outputs.BaseModelOutputWithPoolingAndCrossAttentions 或者一个torch.FloatTensor的元组（如果传递了return_dict=False或者当config.return_dict=False时），包括根据配置（LayoutLMConfig）和输入而定的各种元素。

• last_hidden_state（形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor） — 模型最后一层的隐藏状态序列。
  
• pooler_output（形状为(batch_size, hidden_size)的torch.FloatTensor） — 序列中第一个标记（分类标记）的最后一层隐藏状态（经过用于辅助预训练任务的层进一步处理后）。例如，对于 BERT 系列模型，这返回经过线性层和 tanh 激活函数处理后的分类标记。线性层的权重是在预训练期间从下一个句子预测（分类）目标中训练的。
  
• hidden_states（tuple(torch.FloatTensor)，可选，当传递output_hidden_states=True或者当config.output_hidden_states=True时返回） — 形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor元组（如果模型有嵌入层，则为嵌入的输出一个 + 每个层的输出一个）。
  模型在每个层的输出的隐藏状态加上可选的初始嵌入输出。
  
• attentions（tuple(torch.FloatTensor)，可选，当传递output_attentions=True或者当config.output_attentions=True时返回） — 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每个层一个）。
  注意力 softmax 之后的注意力权重，用于计算自注意力头中的加权平均值。
  
• cross_attentions（tuple(torch.FloatTensor)，可选，当传递output_attentions=True和config.add_cross_attention=True或者当config.output_attentions=True时返回） — 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每个层一个）。
  解码器的交叉注意力层的注意力权重，在注意力 softmax 之后，用于计算交叉注意力头中的加权平均值。
  
• past_key_values（tuple(tuple(torch.FloatTensor))，可选，当传递use_cache=True或者当config.use_cache=True时返回） — 长度为config.n_layers的tuple(torch.FloatTensor)元组，每个元组有 2 个形状为(batch_size, num_heads, sequence_length, embed_size_per_head)的张量，如果config.is_encoder_decoder=True还有额外的 2 个形状为(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)的张量。
  包含预先计算的隐藏状态（自注意力块中的键和值以及在交叉注意力块中可选地如果config.is_encoder_decoder=True）可以用来加速顺序解码的（见past_key_values输入）。
  

LayoutLMModel 的前向方法，覆盖了__call__特殊方法。

虽然前向传递的步骤需要在这个函数内定义，但应该在之后调用Module实例而不是这个，因为前者负责运行预处理和后处理步骤，而后者会默默地忽略它们。

示例：

>>> 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

class transformers.LayoutLMForMaskedLM

< source >

( config )

参数

• config（LayoutLMConfig）— 模型配置类，包含模型的所有参数。使用配置文件初始化不会加载与模型关联的权重，只加载配置。查看 from_pretrained()方法以加载模型权重。

在顶部带有语言建模头的 LayoutLM 模型。LayoutLM 模型是由 Yiheng Xu、Minghao Li、Lei Cui、Shaohan Huang、Furu Wei 和 Ming Zhou 在LayoutLM: Pre-training of Text and Layout for Document Image Understanding中提出的。

此模型是 PyTorch torch.nn.Module子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档以获取有关一般用法和行为的所有相关信息。

forward

<来源>

( input_ids: Optional = None bbox: Optional = None attention_mask: Optional = None token_type_ids: Optional = None position_ids: Optional = None head_mask: Optional = None inputs_embeds: Optional = None labels: Optional = None encoder_hidden_states: Optional = None encoder_attention_mask: Optional = None output_attentions: Optional = None output_hidden_states: Optional = None return_dict: Optional = None ) → export const metadata = 'undefined';transformers.modeling_outputs.MaskedLMOutput or tuple(torch.FloatTensor)

参数

• input_ids（形状为(batch_size, sequence_length)的torch.LongTensor）— 词汇表中输入序列标记的索引。
  可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode()和 PreTrainedTokenizer.call()。
  什么是输入 ID？
  
• bbox（形状为(batch_size, sequence_length, 4)的torch.LongTensor，可选）— 每个输入序列标记的边界框。在范围[0, config.max_2d_position_embeddings-1]中选择。每个边界框应该是(x0, y0, x1, y1)格式的归一化版本，其中(x0, y0)对应于边界框左上角的位置，(x1, y1)表示右下角的位置。有关归一化，请参阅概述。
  
• attention_mask（形状为(batch_size, sequence_length)的torch.FloatTensor，可选）— 用于避免在填充标记索引上执行注意力的掩码。掩码值在[0, 1]中选择：1表示未被掩码的标记，0表示被掩码的标记。
  什么是注意力掩码？
  
• token_type_ids（形状为(batch_size, sequence_length)的torch.LongTensor，可选）— 段标记索引，用于指示输入的第一部分和第二部分。索引在[0, 1]中选择：0对应于句子 A的标记，1对应于句子 B的标记
  什么是 token type IDs？
  
• position_ids（形状为(batch_size, sequence_length)的torch.LongTensor，可选）— 每个输入序列标记在位置嵌入中的位置索引。在范围[0, config.max_position_embeddings - 1]中选择。
  什么是位置 ID？
  
• head_mask（形状为(num_heads,)或(num_layers, num_heads)的torch.FloatTensor，可选）— 用于使自注意力模块中的选定头部失效的掩码。掩码值在[0, 1]中选择：1表示头部未被掩码，0表示头部被掩码。
  
• inputs_embeds（形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor，可选）— 可选地，您可以选择直接传递嵌入表示，而不是传递input_ids。如果您想要更多控制如何将input_ids索引转换为相关向量，而不是使用模型的内部嵌入查找矩阵，这将非常有用。
  
• output_attentions（bool，可选）— 如果设置为True，则返回所有注意力层的注意力张量。有关更多详细信息，请参阅返回的张量下的attentions。
  
• output_hidden_states（bool，可选）— 如果设置为True，则返回所有层的隐藏状态。有关更多详细信息，请参见返回张量下的hidden_states。
  
• return_dict（bool，可选）— 如果设置为True，模型将返回一个 ModelOutput 而不是一个普通元组。
  
• labels（形状为(batch_size, sequence_length)的torch.LongTensor，可选）— 用于计算掩码语言建模损失的标签。索引应在[-100, 0, ..., config.vocab_size]内（参见input_ids文档字符串）。索引设置为-100的标记将被忽略（掩码），损失仅计算具有标签在[0, ..., config.vocab_size]内的标记。
  

返回

transformers.modeling_outputs.MaskedLMOutput 或tuple(torch.FloatTensor)

一个 transformers.modeling_outputs.MaskedLMOutput 或一个torch.FloatTensor元组（如果传递return_dict=False或config.return_dict=False时）包含根据配置（LayoutLMConfig）和输入的各种元素。

• loss（形状为(1,)的torch.FloatTensor，可选，当提供labels时返回）— 掩码语言建模（MLM）损失。
  
• logits（形状为(batch_size, sequence_length, config.vocab_size)的torch.FloatTensor）— 语言建模头部的预测分数（SoftMax 之前每个词汇标记的分数）。
  
• hidden_states（tuple(torch.FloatTensor)，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回）— 形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor元组（一个用于嵌入的输出，如果模型有一个嵌入层，+ 一个用于每个层的输出）。
  模型在每一层输出的隐藏状态以及可选的初始嵌入输出。
  
• attentions（tuple(torch.FloatTensor)，可选，当传递output_attentions=True或config.output_attentions=True时返回）— 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每个层一个）。
  注意力 softmax 后的注意力权重，用于计算自注意力头中的加权平均值。
  

LayoutLMForMaskedLM 的前向方法，覆盖了__call__特殊方法。

虽然前向传递的步骤需要在此函数内定义，但应该在此之后调用Module实例，而不是这个，因为前者负责运行预处理和后处理步骤，而后者会默默地忽略它们。

示例：

>>> 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

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