Transformers documentation

LayoutLMV2

Transformers

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

该模型于 2020-12-29 在 HF papers 上发布，并于 2021-08-30 贡献至 Hugging Face Transformers。

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 中提出。LayoutLMV2 改进了 LayoutLM，在多个文档图像理解基准测试中取得了最先进的结果：

从扫描文档中进行信息抽取：FUNSD 数据集（包含 199 份已标注的表单，共计超过 30,000 个单词）、CORD 数据集（包含 800 张用于训练的收据、100 张用于验证的收据和 100 张用于测试的收据）、SROIE 数据集（包含 626 张用于训练的收据和 347 张用于测试的收据）以及 Kleister-NDA 数据集（包含来自 EDGAR 数据库的保密协议，其中 254 份文档用于训练，83 份文档用于验证，203 份文档用于测试）。
文档图像分类：RVL-CDIP 数据集（包含 40 万张图像，每张图像属于 16 个类别之一）。
文档视觉问答：DocVQA 数据集（包含在 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。运行以下命令进行安装：

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 注意力偏置。详细信息请参见论文第 5 页。
关于如何在 RVL-CDIP、FUNSD、DocVQA 和 CORD 上使用 LayoutLMv2 模型的演示笔记本，可在此处找到。
LayoutLMv2 使用 Facebook AI 的 Detectron2 包作为其视觉骨干网络。有关安装说明，请参阅此链接。
除了 input_ids 之外，forward() 还需要两个额外的输入，即 image 和 bbox。image 输入对应于文本 token 所在的原始文档图像。模型要求每个文档图像的尺寸为 224x224。这意味着，如果您有一批文档图像，image 应该是一个形状为 (batch_size, 3, 224, 224) 的张量。它可以是 torch.Tensor 或 Detectron2.structures.ImageList。您无需对通道进行归一化，因为模型会自行处理。需要注意的是，视觉骨干网络期望的是 BGR 通道而非 RGB，因为 Detectron2 中的所有模型都是使用 BGR 格式进行预训练的。bbox 输入是输入文本 token 的边界框（即 2D 位置）。这与 LayoutLMModel 相同。您可以使用外部 OCR 引擎（例如 Google 的 Tesseract，有可用的 Python wrapper）来获取这些边界框。每个边界框应采用 (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 对应于 token 所在的原始文档的宽度和高度（在调整图像大小之前）。例如，可以使用 Python Image Library (PIL) 库按以下方式获取：

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，可直接用于为模型准备数据（内部会应用 OCR）。更多信息请参见下方的“使用方法”部分。

在内部，LayoutLMv2Model 会将 image 输入通过其视觉骨干网络进行处理，以获得一个分辨率更低的特征图，其形状等于 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() 时，会打印一条警告，其中包含一个很长的未初始化参数名称列表。这没有问题，因为这些参数是批归一化统计量，在针对自定义数据集进行微调时它们会获得相应的值。
如果要在分布式环境中训练模型，请确保在模型上调用 synchronize_batch_norm，以正确同步视觉骨干网络中的批归一化层。

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

资源

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

Text Classification

一个关于如何在 RVL-CDIP 数据集上微调 LayoutLMv2 以进行文本分类的笔记本。
另请参阅：文本分类任务指南

Question Answering

一个关于如何针对 DocVQA 数据集微调 LayoutLMv2 以进行问答任务的笔记本。
另请参阅：问答任务指南
另请参阅：文档问答任务指南

Token Classification

一个关于如何在 CORD 数据集上微调 LayoutLMv2 以进行 token 分类的笔记本。
一个关于如何在 FUNSD 数据集上微调 LayoutLMv2 以进行 token 分类的笔记本。
另请参阅：Token 分类任务指南

用法：LayoutLMv2Processor

为模型准备数据最简单的方式是使用 LayoutLMv2Processor，它在内部组合了一个图像处理器（LayoutLMv2ImageProcessor）和一个分词器（LayoutLMv2Tokenizer 或 LayoutLMv2TokenizerFast）。图像处理器负责处理图像模态，而分词器负责处理文本模态。处理器将两者结合在一起，这对于 LayoutLMv2 这样的多模态模型来说非常理想。请注意，如果你只想处理其中一种模态，仍然可以单独使用这两者。

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，它会生成模型所需的输入。在内部，处理器首先使用 LayoutLMv2ImageProcessor 对图像执行 OCR，以获取单词列表和归一化边界框，同时将图像调整为指定大小，从而得到 image 输入。随后，这些单词和归一化边界框会被提供给 LayoutLMv2Tokenizer 或 LayoutLMv2TokenizerFast，由它们将其转换为 token 级别的 input_ids、attention_mask、token_type_ids 和 bbox。可选地，可以向处理器提供单词标签，这些标签会被转换为 token 级别的 labels。

LayoutLMv2Processor 底层使用了 PyTesseract，这是 Google Tesseract OCR 引擎的 Python 封装。请注意，您仍然可以使用自己选择的 OCR 引擎，并自行提供单词和归一化框。这需要在使用 apply_ocr 设置为 False 的情况下初始化 LayoutLMv2ImageProcessor。

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

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

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

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。在这种情况下，需要自行向处理器提供单词及其对应的（归一化）边界框。

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 标注标签，并将其余 wordpiece 标记为 -100，即 PyTorch 中 CrossEntropyLoss 的 ignore_index。如果你希望单词的所有 wordpiece 都被标注，可以将 tokenizer 初始化时 only_label_first_subword 设置为 False。

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] 问题标记 [SEP] 单词标记 [SEP]。

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，可以向处理器提供你自己的单词和（归一化的）边界框。

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'])

Transformers

LayoutLMV2

概述

使用技巧

资源

用法：LayoutLMv2Processor

LayoutLMv2Config

class transformers.LayoutLMv2Config

LayoutLMv2ImageProcessor

class transformers.LayoutLMv2ImageProcessor

预处理

LayoutLMv2ImageProcessorPil

class transformers.LayoutLMv2ImageProcessorPil

预处理

LayoutLMv2Tokenizer

class transformers.LayoutLMv2Tokenizer

__call__

save_vocabulary

LayoutLMv2Processor

class transformers.LayoutLMv2Processor

__call__

LayoutLMv2Model

class transformers.LayoutLMv2Model

forward

LayoutLMv2ForSequenceClassification

class transformers.LayoutLMv2ForSequenceClassification

forward

LayoutLMv2ForTokenClassification

class transformers.LayoutLMv2ForTokenClassification

forward

LayoutLMv2ForQuestionAnswering

类 transformers.LayoutLMv2ForQuestionAnswering

forward

call

call