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

Model ini dipublikasikan di HF papers pada 2020-12-29 dan disumbangkan ke Hugging Face Transformers pada 2021-08-30.

LayoutLMV2

Ikhtisar

Model LayoutLMV2 diusulkan dalam LayoutLMv2: Multi-modal Pre-training for Visually-Rich Document Understanding oleh 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 meningkatkan LayoutLM untuk memperoleh hasil state-of-the-art di berbagai benchmark pemahaman gambar dokumen:

ekstraksi informasi dari dokumen hasil pindaian: dataset FUNSD (kumpulan 199 formulir anotasi yang berisi lebih dari 30.000 kata), dataset CORD (kumpulan 800 struk untuk pelatihan, 100 untuk validasi, dan 100 untuk pengujian), dataset SROIE (kumpulan 626 struk untuk pelatihan dan 347 struk untuk pengujian) dan dataset Kleister-NDA (kumpulan perjanjian kerahasiaan dari basis data EDGAR, termasuk 254 dokumen untuk pelatihan, 83 dokumen untuk validasi, dan 203 dokumen untuk pengujian).
klasifikasi dokumen: dataset RVL-CDIP (kumpulan 400.000 gambar yang termasuk ke dalam salah satu dari 16 kelas).
visual question answering dokumen: dataset DocVQA (kumpulan 50.000 pertanyaan yang didefinisikan pada 12.000+ gambar dokumen).

Abstrak dari makalah tersebut adalah sebagai berikut:

Pre-training teks dan tata letak telah terbukti efektif dalam berbagai tugas pemahaman dokumen yang kaya secara visual berkat arsitektur modelnya yang efektif serta keunggulan dari dokumen pindai/digital berskala besar tanpa label. Dalam makalah ini, kami memperkenalkan LayoutLMv2 dengan melakukan pre-training teks, tata letak, dan gambar dalam kerangka kerja multi-modal, di mana arsitektur model dan tugas pre-training baru dimanfaatkan. Secara spesifik, LayoutLMv2 tidak hanya menggunakan tugas pemodelan visual-bahasa yang ter-masker yang sudah ada, tetapi juga tugas penyelarasan teks-gambar dan pencocokan teks-gambar yang baru pada tahap pre-training, di mana interaksi lintas-modalitas dipelajari dengan lebih baik. Sementara itu, model ini juga mengintegrasikan mekanisme self-attention yang sadar spasial ke dalam arsitektur Transformer, sehingga model dapat sepenuhnya memahami hubungan posisi relatif di antara blok teks yang berbeda. Hasil eksperimen menunjukkan bahwa LayoutLMv2 melampaui baseline yang kuat dan mencapai hasil state-of-the-art baru pada berbagai tugas pemahaman dokumen yang kaya secara visual, termasuk 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), dan DocVQA (0.7295 -> 0.8672). Model LayoutLMv2 yang telah di-pre-train tersedia secara publik di this https URL.

LayoutLMv2 bergantung pada detectron2, torchvision dan tesseract. Jalankan berikut untuk menginstalnya:

python -m pip install 'git+https://github.com/facebookresearch/detectron2.git'
python -m pip install torchvision tesseract

(Jika Anda mengembangkan untuk LayoutLMv2, perhatikan bahwa menjalankan doctests juga memerlukan instalasi paket-paket ini.)

Tips penggunaan

Perbedaan utama antara LayoutLMv1 dan LayoutLMv2 adalah bahwa yang terakhir mengintegrasikan visual embeddings selama pre-training (sedangkan LayoutLMv1 hanya menambahkan visual embeddings selama fine-tuning).
LayoutLMv2 menambahkan bias perhatian relatif 1D serta bias perhatian spasial 2D ke skor perhatian pada lapisan self-attention. Detailnya dapat ditemukan di halaman 5 makalah.
Notebook demo tentang cara menggunakan model LayoutLMv2 pada RVL-CDIP, FUNSD, DocVQA, dan CORD dapat ditemukan di sini.
LayoutLMv2 menggunakan paket Detectron2 dari Facebook AI untuk tulang punggung visualnya. Lihat tautan ini untuk instruksi instalasi.
Selain input_ids, forward() mengharapkan 2 input tambahan, yaitu image dan bbox. Input image sesuai dengan gambar dokumen asli tempat token teks tersebut muncul. Model mengharapkan setiap gambar dokumen berukuran 224x224. Ini berarti jika Anda memiliki batch gambar dokumen, image harus berupa tensor dengan bentuk (batch_size, 3, 224, 224). Ini bisa berupa torch.Tensor atau Detectron2.structures.ImageList. Anda tidak perlu menormalisasi channel, karena hal ini dilakukan oleh model. Penting untuk dicatat bahwa visual backbone mengharapkan channel BGR alih-alih RGB, karena semua model di Detectron2 dilatih sebelumnya menggunakan format BGR. Input bbox adalah kotak pembatas (yaitu posisi 2D) dari token teks input. Ini identik dengan LayoutLMModel. Kotak pembatas ini dapat diperoleh menggunakan mesin OCR eksternal seperti Tesseract dari Google (ada wrapper Python yang tersedia). Setiap kotak pembatas harus dalam format (x0, y0, x1, y1), di mana (x0, y0) sesuai dengan posisi sudut kiri atas pada kotak pembatas, dan (x1, y1) merepresentasikan posisi sudut kanan bawah. Perhatikan bahwa kotak pembatas terlebih dahulu perlu dinormalisasi ke skala 0-1000. Untuk menormalisasi, Anda dapat menggunakan fungsi berikut:

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

Di sini, width dan height sesuai dengan lebar dan tinggi dokumen asli tempat token tersebut muncul (sebelum gambar di-resize). Nilai-nilai tersebut dapat diperoleh, misalnya, menggunakan pustaka Python Image Library (PIL) sebagai berikut:

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

Namun, model ini menyertakan LayoutLMv2Processor yang benar-benar baru, yang dapat digunakan untuk langsung menyiapkan data untuk model (termasuk penerapan OCR di baliknya). Informasi lebih lanjut dapat ditemukan di bagian “Penggunaan” di bawah.

Secara internal, LayoutLMv2Model akan mengirimkan input image melalui visual backbone-nya untuk mendapatkan peta fitur dengan resolusi lebih rendah, yang bentuknya sama dengan atribut image_feature_pool_shape dari LayoutLMv2Config. Peta fitur ini kemudian diratakan (flattened) untuk mendapatkan urutan token gambar. Karena ukuran peta fitur secara default adalah 7x7, maka diperoleh 49 token gambar. Token-token ini kemudian digabungkan (concatenated) dengan token teks, dan dikirimkan melalui encoder Transformer. Artinya, last hidden states dari model akan memiliki panjang 512 + 49 = 561, jika Anda melakukan padding pada token teks hingga panjang maksimum. Secara lebih umum, last hidden states akan memiliki bentuk seq_length + image_feature_pool_shape[0] * config.image_feature_pool_shape[1].
Saat memanggil from_pretrained(), peringatan akan dicetak dengan daftar panjang nama parameter yang tidak diinisialisasi. Ini bukan masalah, karena parameter tersebut adalah statistik batch normalization, yang akan memiliki nilai saat fine-tuning pada dataset kustom.
Jika Anda ingin melatih model dalam lingkungan terdistribusi, pastikan untuk memanggil synchronize_batch_norm pada model agar lapisan normalisasi batch dari tulang punggung visual tersinkronkan dengan benar.

Selain itu, ada LayoutXLM, yaitu versi multibahasa dari LayoutLMv2. Informasi lebih lanjut dapat ditemukan di halaman dokumentasi LayoutXLM.

Sumber daya

Daftar sumber resmi Hugging Face dan komunitas (ditandai dengan 🌎) untuk membantu Anda memulai dengan LayoutLMv2. Jika Anda tertarik untuk mengirimkan sumber agar disertakan di sini, silakan buka Pull Request dan kami akan meninjaunya! Sumber tersebut sebaiknya mendemonstrasikan sesuatu yang baru, bukan menduplikasi sumber yang sudah ada.

Text Classification

Notebook tentang cara melakukan finetuning LayoutLMv2 untuk klasifikasi teks pada dataset RVL-CDIP.
Lihat juga: Panduan tugas klasifikasi teks

Question Answering

Notebook tentang cara melakukan finetuning LayoutLMv2 untuk question-answering pada dataset DocVQA.
Lihat juga: Panduan tugas question answering
Lihat juga: Panduan tugas menjawab pertanyaan dokumen

Token Classification

Notebook tentang cara melakukan finetuning LayoutLMv2 untuk token-classification pada dataset CORD.
Notebook tentang cara melakukan finetuning LayoutLMv2 untuk token-classification pada dataset FUNSD.
Lihat juga: Panduan tugas klasifikasi token

Penggunaan: LayoutLMv2Processor

Cara termudah untuk menyiapkan data untuk model adalah dengan menggunakan LayoutLMv2Processor, yang secara internal menggabungkan image processor (LayoutLMv2ImageProcessor) dan tokenizer (LayoutLMv2Tokenizer atau LayoutLMv2TokenizerFast). Image processor menangani modalitas gambar, sedangkan tokenizer menangani modalitas teks. Processor menggabungkan keduanya, yang ideal untuk model multi-modal seperti LayoutLMv2. Perhatikan bahwa Anda masih dapat menggunakan keduanya secara terpisah, jika Anda hanya ingin menangani satu modalitas.

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)

Singkatnya, seseorang dapat memberikan gambar dokumen (dan mungkin data tambahan) ke LayoutLMv2Processor, dan ia akan membuat input yang diharapkan oleh model. Secara internal, prosesor pertama kali menggunakan LayoutLMv2ImageProcessor untuk menerapkan OCR pada gambar guna mendapatkan daftar kata dan kotak pembatas yang dinormalisasi, serta untuk mengubah ukuran gambar ke ukuran tertentu agar mendapatkan input image. Kata-kata dan kotak pembatas yang dinormalisasi tersebut kemudian diberikan ke LayoutLMv2Tokenizer atau LayoutLMv2TokenizerFast, yang mengubahnya menjadi input_ids, attention_mask, token_type_ids, bbox pada tingkat token. Secara opsional, seseorang dapat memberikan label kata ke prosesor, yang kemudian diubah menjadi labels pada tingkat token.

LayoutLMv2Processor menggunakan PyTesseract, sebuah wrapper Python untuk mesin OCR Tesseract dari Google, di baliknya. Perhatikan bahwa Anda tetap dapat menggunakan mesin OCR pilihan Anda sendiri, dan menyediakan kata-kata serta kotak ternormalisasi sendiri. Hal ini memerlukan inisialisasi LayoutLMv2ImageProcessor dengan apply_ocr diatur ke False.

Secara total, terdapat 5 kasus penggunaan yang didukung oleh prosesor. Di bawah ini, kami mencantumkan semuanya. Perhatikan bahwa masing-masing kasus penggunaan ini berfungsi untuk input berbatch maupun non-berbatch (kami mengilustrasikannya untuk input non-berbatch).

Kasus penggunaan 1: klasifikasi gambar dokumen (pelatihan, inferensi) + klasifikasi token (inferensi), apply_ocr = True

Ini adalah kasus paling sederhana, di mana prosesor (sebenarnya pemroses gambar) akan melakukan OCR pada gambar untuk mendapatkan kata-kata dan kotak pembatas yang dinormalisasi.

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

Kasus penggunaan 2: klasifikasi gambar dokumen (pelatihan, inferensi) + klasifikasi token (inferensi), apply_ocr=False

Jika seseorang ingin melakukan OCR sendiri, mereka dapat menginisialisasi image processor dengan apply_ocr diatur ke False. Dalam hal itu, mereka harus menyediakan kata-kata dan bounding box (ternormalisasi) yang sesuai sendiri ke processor.

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

Kasus penggunaan 3: klasifikasi token (pelatihan), apply_ocr=False

Untuk tugas klasifikasi token (seperti FUNSD, CORD, SROIE, Kleister-NDA), Anda juga dapat menyediakan label kata yang sesuai untuk melatih model. Prosesor kemudian akan mengonversi label ini menjadi labels pada tingkat token. Secara default, prosesornya hanya akan memberi label pada wordpiece pertama dari sebuah kata, dan memberi label -100 pada wordpiece sisanya, yang merupakan ignore_index dari CrossEntropyLoss PyTorch. Jika Anda ingin semua wordpiece dari sebuah kata diberi label, Anda dapat menginisialisasi tokenizer dengan only_label_first_subword yang diatur ke 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'])

Kasus penggunaan 4: visual question answering (inferensi), apply_ocr=True

Untuk tugas visual question answering (seperti DocVQA), Anda dapat memberikan pertanyaan ke processor. Secara default, processor akan menerapkan OCR pada gambar, dan membuat [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'])

Kasus penggunaan 5: visual question answering (inferensi), apply_ocr=False

Untuk tugas visual question answering (seperti DocVQA), Anda dapat memberikan pertanyaan ke processor. Jika Anda ingin melakukan OCR sendiri, Anda dapat memberikan kata-kata dan bounding box (ternormalisasi) Anda sendiri ke processor.

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

Ikhtisar

Tips penggunaan

Sumber daya

Penggunaan: LayoutLMv2Processor

LayoutLMv2Config

kelas transformers.LayoutLMv2Config

LayoutLMv2ImageProcessor

kelas transformers.LayoutLMv2ImageProcessor

praproses

LayoutLMv2ImageProcessorPil

kelas transformers.LayoutLMv2ImageProcessorPil

praproses

LayoutLMv2Tokenizer

kelas transformers.LayoutLMv2Tokenizer

__call__

save_vocabulary

LayoutLMv2Processor

kelas transformers.LayoutLMv2Processor

__call__

LayoutLMv2Model

kelas transformers.LayoutLMv2Model

forward

LayoutLMv2ForSequenceClassification

kelas transformers.LayoutLMv2ForSequenceClassification

forward

LayoutLMv2ForTokenClassification

kelas transformers.LayoutLMv2ForTokenClassification

forward

LayoutLMv2ForQuestionAnswering

kelas transformers.LayoutLMv2ForQuestionAnswering

forward

call

call