Transformers documentation

LayoutLMV2

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

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

Эта модель была опубликована в HF papers 29.12.2020 и добавлена в Hugging Face Transformers 30.08.2021.

LayoutLMV2

Обзор

Модель LayoutLMV2 была предложена в статье LayoutLMv2: Multi-modal Pre-training for Visually-Rich Document Understanding (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 улучшает LayoutLM и обеспечивает наилучшие результаты на нескольких бенчмарках понимания изображений документов:

извлечение информации из отсканированных документов: набор данных FUNSD (коллекция из 199 размеченных форм, содержащих более 30 000 слов), набор данных CORD (коллекция из 800 чеков для обучения, 100 для валидации и 100 для тестирования), набор данных SROIE (коллекция из 626 чеков для обучения и 347 чеков для тестирования) и набор данных Kleister-NDA (коллекция соглашений о неразглашении из базы данных EDGAR, включающая 254 документа для обучения, 83 документа для валидации и 203 документа для тестирования).
классификация изображений документов: набор данных RVL-CDIP (коллекция из 400 000 изображений, относящихся к одному из 16 классов).
document visual question answering: набор данных DocVQA (сборник из 50 000 вопросов, заданных на 12 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 доступна по адресу this 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 добавляет к скорингу внимания в слоях само-внимания как относительное одномерное смещение внимания, так и пространственное двумерное смещение внимания. Подробности приведены на странице 5 статьи.
Демо-ноутбуки с примерами использования модели LayoutLMv2 на наборах данных RVL-CDIP, FUNSD, DocVQA и CORD можно найти здесь.
LayoutLMv2 использует пакет Detectron2 от Facebook AI в качестве визуального бэкбона. Инструкции по установке приведены по этой ссылке.
Помимо input_ids, forward() ожидает два дополнительных входа, а именно image и bbox. Вход image соответствует исходному изображению документа, в котором встречаются токены текста. Модель ожидает, что каждое изображение документа имеет размер 224x224. Это означает, что если у вас есть батч изображений документов, image должен быть тензором формы (batch_size, 3, 224, 224). Это может быть torch.Tensor или Detectron2.structures.ImageList. Вам не нужно нормализовать каналы, так как это делает модель. Важно отметить, что визуальный бэкбон ожидает каналы BGR, а не RGB, поскольку все модели в Detectron2 предварительно обучены в формате BGR. Вход bbox — это ограничивающие рамки (т. е. 2D-координаты) входных токенов текста. Это идентично LayoutLMModel. Их можно получить с помощью внешнего OCR-движка, такого как Tesseract от Google (доступна обёртка для 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


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 через визуальный бэкбон, чтобы получить карту признаков с пониженным разрешением, форма которой равна атрибуту image_feature_pool_shape объекта LayoutLMv2Config. Затем эта карта признаков разворачивается в последовательность токенов изображения. Поскольку размер карты признаков по умолчанию составляет 7x7, получается 49 токенов изображения. Далее они конкатенируются с текстовыми токенами и прогоняются через кодировщик Transformer. Это означает, что последние скрытые состояния модели будут иметь длину 512 + 49 = 561, если вы дополните текстовые токены до максимальной длины. Более общо, форма последних скрытых состояний будет seq_length + image_feature_pool_shape[0] * config.image_feature_pool_shape[1].
При вызове from_pretrained() будет выведено предупреждение с длинным списком имён параметров, которые не были инициализированы. Это не проблема, так как эти параметры представляют собой статистику батч-нормализации, которая получит значения при дообучении на собственном наборе данных.
Если вы хотите обучать модель в распределённой среде, убедитесь, что вызываете synchronize_batch_norm для модели, чтобы корректно синхронизировать слои batch normalization визуального бэкбона.

Кроме того, существует LayoutXLM — многоязычная версия LayoutLMv2. Дополнительную информацию можно найти на странице документации LayoutXLM.

Ресурсы

Список официальных ресурсов Hugging Face и сообщества (отмечены значком 🌎), которые помогут вам начать работу с LayoutLMv2. Если вы хотите предложить ресурс для включения в этот список, пожалуйста, создайте Pull Request, и мы его рассмотрим! В идеале ресурс должен демонстрировать что-то новое, а не дублировать существующий.

Text Classification

Ноутбук о том, как дообучить LayoutLMv2 для классификации текста на наборе данных RVL-CDIP.
См. также: Руководство по задаче классификации текста

Question Answering

Ноутбук о том, как дообучить LayoutLMv2 для задачи извлечения ответов на вопросы на наборе данных DocVQA.
См. также: Руководство по задаче вопрос-ответ
См. также: Руководство по задаче вопросно-ответной обработки документов

Token Classification

Ноутбук о том, как дообучить LayoutLMv2 для классификации токенов на наборе данных CORD.
Ноутбук с описанием того, как дообучить LayoutLMv2 для классификации токенов на наборе данных FUNSD.
См. также: Руководство по задаче классификации токенов

Использование: 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, которые преобразуют их в токеновые input_ids, attention_mask, token_type_ids, bbox. Необязательно, можно передать в процессор метки слов, которые будут преобразованы в токеновые labels.

LayoutLMv2Processor использует PyTesseract — Python-обёртку над движком OCR Tesseract от Google. Обратите внимание, что вы можете использовать собственный движок OCR и самостоятельно предоставлять слова и нормализованные рамки. Для этого необходимо инициализировать LayoutLMv2ImageProcessor с параметром apply_ocr, установленным в False.

Всего процессор поддерживает 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 самостоятельно, инициализируйте image processor с параметром apply_ocr, установленным в False. В этом случае вам нужно самостоятельно передать в processor слова и соответствующие им (нормализованные) bounding boxes.

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: классификация токенов (обучение), apply_ocr=False

Для задач классификации токенов (таких как FUNSD, CORD, SROIE, Kleister-NDA) можно также предоставить соответствующие метки слов для обучения модели. Процессор затем преобразует их в метки на уровне токенов labels. По умолчанию он присваивает метку только первому wordpiece слова, а остальные wordpiece помечает значением -100, что является ignore_index для CrossEntropyLoss в PyTorch. Если вы хотите, чтобы все wordpiece слова были промаркированы, вы можете инициализировать токенизатор с параметром 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

класс transformers.LayoutLMv2Config

LayoutLMv2ImageProcessor

класс transformers.LayoutLMv2ImageProcessor

preprocess

LayoutLMv2ImageProcessorPil

класс transformers.LayoutLMv2ImageProcessorPil

preprocess

LayoutLMv2Tokenizer

класс transformers.LayoutLMv2Tokenizer

__call__

save_vocabulary

LayoutLMv2Processor

класс transformers.LayoutLMv2Processor

__call__

LayoutLMv2Model

класс transformers.LayoutLMv2Model

forward

LayoutLMv2ForSequenceClassification

класс transformers.LayoutLMv2ForSequenceClassification

forward

LayoutLMv2ForTokenClassification

класс transformers.LayoutLMv2ForTokenClassification

forward

LayoutLMv2ForQuestionAnswering

класс transformers.LayoutLMv2ForQuestionAnswering

forward

call

call