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

이 모델은 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을 개선하여 여러 문서 이미지 이해 벤치마크에서 최첨단(state-of-the-art) 결과를 달성합니다:

스캔 문서에서 정보 추출: FUNSD 데이터셋(30,000개 이상의 단어로 구성된 199개의 주석 달린 양식의 모음), CORD 데이터셋(학습용 800개, 검증용 100개, 테스트용 100개의 영수증 모음), SROIE 데이터셋(학습용 626개, 테스트용 347개의 영수증 모음) 및 Kleister-NDA 데이터셋(EDGAR 데이터베이스에서 가져온 비밀유지계약서 모음으로, 학습용 254개 문서, 검증용 83개 문서, 테스트용 203개 문서 포함).
문서 이미지 분류: RVL-CDIP 데이터셋(16개 클래스 중 하나에 속하는 400,000개의 이미지 모음).
문서 시각 질의응답: 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은 self-attention 레이어의 attention score에 상대 1차원 attention bias와 공간 2차원 attention bias를 모두 추가합니다. 자세한 내용은 논문 5페이지에서 확인할 수 있습니다.
LayoutLMv2 모델을 RVL-CDIP, FUNSD, DocVQA, CORD에 사용하는 방법에 대한 데모 노트북은 여기에서 찾을 수 있습니다.
LayoutLMv2는 시각적 백본으로 Facebook AI의 Detectron2 패키지를 사용합니다. 설치 방법은 이 링크를 참고하세요.
input_ids 외에도 forward()는 image와 bbox라는 두 가지 추가 입력을 기대합니다. image 입력은 텍스트 토큰이 나타나는 원본 문서 이미지에 해당합니다. 모델은 각 문서 이미지의 크기가 224x224인 것을 기대합니다. 즉, 문서 이미지의 배치(batch)가 있는 경우 image는 (batch_size, 3, 224, 224) 형태의 텐서여야 합니다. 이는 torch.Tensor 또는 Detectron2.structures.ImageList일 수 있습니다. 채널 정규화는 모델이 수행하므로 사용자가 수행할 필요가 없습니다. 주목할 점은 시각적 백본(visual backbone)이 RGB 대신 BGR 채널을 기대한다는 것입니다. Detectron2의 모든 모델은 BGR 형식으로 사전 학습되었기 때문입니다. bbox 입력은 입력 텍스트 토큰의 바운딩 박스(즉, 2D 위치)입니다. 이는 LayoutLMModel와 동일합니다. 이러한 바운딩 박스는 Google의 Tesseract와 같은 외부 OCR 엔진을 사용하여 얻을 수 있습니다(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는 토큰이 나타나는 원본 문서의 너비와 높이를 나타냅니다(이미지 리사이징 전). 예를 들어 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 속성과 동일한 형상을 가진 저해상도 특징 맵을 얻습니다. 이 특징 맵은 평탄화되어 이미지 토큰 시퀀스로 변환됩니다. 특징 맵의 크기는 기본적으로 7x7이므로 49개의 이미지 토큰이 생성됩니다. 이 이미지 토큰은 텍스트 토큰과 연결된 후 Transformer 인코더를 통과합니다. 따라서 텍스트 토큰을 최대 길이까지 패딩하는 경우, 모델의 마지막 숨겨진 상태(last hidden states)의 길이는 512 + 49 = 561이 됩니다. 더 일반적으로, 마지막 숨겨진 상태의 형상은 seq_length + image_feature_pool_shape[0] * config.image_feature_pool_shape[1]입니다.
from_pretrained()를 호출하면 초기화되지 않은 매개변수 이름의 긴 목록이 포함된 경고가 출력됩니다. 이는 문제가 되지 않습니다. 해당 매개변수는 배치 정규화(batch normalization) 통계값이며, 커스텀 데이터셋으로 파인튜닝을 수행할 때 값이 설정되기 때문입니다.
분산 환경에서 모델을 학습하려면, 시각적 백본의 배치 정규화 레이어를 올바르게 동기화하도록 모델에서 synchronize_batch_norm을 호출해야 합니다.

또한, LayoutLMv2의 다국어 버전인 LayoutXLM도 있습니다. 자세한 내용은 LayoutXLM 문서 페이지에서 확인하실 수 있습니다.

리소스

LayoutLMv2를 시작하는 데 도움이 되는 공식 Hugging Face 및 커뮤니티(🌎로 표시) 리소스 목록입니다. 여기에 포함할 리소스를 제출하고 싶으시면 Pull Request를 열어 주시면 검토하겠습니다! 기존 리소스와 중복되지 않고 새로운 것을 보여주는 것이 이상적입니다.

Text Classification

RVL-CDIP 데이터셋에서 텍스트 분류를 위해 LayoutLMv2를 파인튜닝하는 방법에 대한 노트북입니다.
참고: 텍스트 분류 작업 가이드

Question Answering

DocVQA 데이터셋에서 질의응답을 위해 LayoutLMv2를 파인튜닝하는 방법에 대한 노트북입니다.
참고: 질문 답변 작업 가이드
참고: 문서 질의응답 작업 가이드

Token Classification

CORD 데이터셋에서 토큰 분류를 위해 LayoutLMv2를 파인튜닝하는 방법에 대한 노트북입니다.
FUNSD 데이터셋에서 토큰 분류를 위해 LayoutLMv2를 파인튜닝하는 방법을 소개하는 노트북입니다.
참고: 토큰 분류 작업 가이드

사용법: 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는 내부적으로 Google의 Tesseract OCR 엔진을 감싸는 Python 래퍼인 PyTesseract를 사용합니다. 원하는 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을 직접 수행하려면 이미지 프로세서를 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: 토큰 분류(학습), apply_ocr=False

토큰 분류 작업(FUNSD, CORD, SROIE, Kleister-NDA 등)의 경우, 모델을 학습시키기 위해 해당 단어 라벨을 제공할 수도 있습니다. 프로세서가 이를 토큰 수준의 labels로 변환합니다. 기본적으로 단어의 첫 번째 워드피이스만 라벨을 부여하고, 나머지 워드피이스에는 PyTorch의 CrossEntropyLoss의 ignore_index인 -100을 부여합니다. 단어의 모든 워드피이스에 라벨을 부여하려면, 토크나이저를 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] question tokens [SEP] word tokens [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

class transformers.LayoutLMv2ImageProcessor

preprocess

LayoutLMv2ImageProcessorPil

클래스 transformers.LayoutLMv2ImageProcessorPil

preprocess

LayoutLMv2Tokenizer

클래스 transformers.LayoutLMv2Tokenizer

__call__

save_vocabulary

LayoutLMv2Processor

클래스 transformers.LayoutLMv2Processor

__call__

LayoutLMv2Model

클래스 transformers.LayoutLMv2Model

forward

LayoutLMv2ForSequenceClassification

class transformers.LayoutLMv2ForSequenceClassification

forward

LayoutLMv2ForTokenClassification

클래스 transformers.LayoutLMv2ForTokenClassification

forward

LayoutLMv2ForQuestionAnswering

클래스 transformers.LayoutLMv2ForQuestionAnswering

forward

call

call