Transformers documentation
Model Vision Encoder Decoder
Model ini dipublikasikan di HF papers pada 2021-09-21 dan disumbangkan ke Hugging Face Transformers pada 2021-10-13.
Model Vision Encoder Decoder
Ikhtisar
VisionEncoderDecoderModel dapat digunakan untuk menginisialisasi model image-to-text dengan model visi berbasis Transformer yang sudah terlatih sebelumnya sebagai encoder (mis. ViT, BEiT, DeiT, Swin) dan model bahasa yang sudah terlatih sebelumnya sebagai decoder (mis. RoBERTa, GPT2, BERT, DistilBERT).
Efektivitas inisialisasi model dari gambar ke urutan teks dengan checkpoint yang telah dilatih sebelumnya telah ditunjukkan dalam (misalnya) TrOCR: Transformer-based Optical Character Recognition with Pre-trained Models oleh Minghao Li, Tengchao Lv, Lei Cui, Yijuan Lu, Dinei Florencio, Cha Zhang, Zhoujun Li, Furu Wei.
Setelah VisionEncoderDecoderModel tersebut dilatih/di-fine-tune, model ini dapat disimpan/dimuat seperti model lainnya (lihat contoh di bawah untuk informasi lebih lanjut).
Salah satu contoh aplikasi adalah image captioning, di mana encoder digunakan untuk meng-encode gambar, kemudian model bahasa autoregressive menghasilkan caption. Contoh lain adalah optical character recognition. Lihat TrOCR, yang merupakan instance dari VisionEncoderDecoderModel.
Menginisialisasi secara acak VisionEncoderDecoderModel dari konfigurasi model
VisionEncoderDecoderModel dapat diinisialisasi secara acak dari konfigurasi encoder dan decoder. Pada contoh berikut, kami menunjukkan cara melakukannya menggunakan konfigurasi ViTModel bawaan untuk encoder
dan konfigurasi BertForCausalLM bawaan untuk decoder.
from transformers import BertConfig, VisionEncoderDecoderConfig, VisionEncoderDecoderModel, ViTConfig
config_encoder = ViTConfig()
config_decoder = BertConfig()
config = VisionEncoderDecoderConfig.from_encoder_decoder_configs(config_encoder, config_decoder)
model = VisionEncoderDecoderModel(config=config)Mengeinisialisasi VisionEncoderDecoderModel dari encoder yang sudah dilatih sebelumnya dan decoder yang sudah dilatih sebelumnya
VisionEncoderDecoderModel dapat diinisialisasi dari checkpoint encoder pretrained dan checkpoint decoder pretrained. Perhatikan bahwa model visi berbasis Transformer yang sudah pretrained, misalnya Swin, dapat berfungsi sebagai encoder, dan model auto-encoding pretrained, misalnya BERT, model bahasa kausal pretrained, misalnya GPT2, serta bagian decoder pretrained dari model sequence-to-sequence, misalnya decoder dari BART, dapat digunakan sebagai decoder.
Tergantung pada arsitektur yang Anda pilih sebagai decoder, lapisan cross-attention mungkin diinisialisasi secara acak.
Menginisialisasi VisionEncoderDecoderModel dari checkpoint encoder dan decoder pretrained memerlukan model untuk dihaluskan (fine-tuned) pada tugas downstream, sebagaimana telah ditunjukkan dalam artikel blog Warm-starting-encoder-decoder.
Untuk melakukannya, kelas VisionEncoderDecoderModel menyediakan metode VisionEncoderDecoderModel.from_encoder_decoder_pretrained().
from transformers import VisionEncoderDecoderModel
model = VisionEncoderDecoderModel.from_encoder_decoder_pretrained(
"microsoft/swin-base-patch4-window7-224-in22k", "google-bert/bert-base-uncased"
)Memuat checkpoint VisionEncoderDecoderModel yang sudah ada dan melakukan inferensi
Untuk memuat checkpoint hasil fine-tuning dari kelas VisionEncoderDecoderModel, VisionEncoderDecoderModel menyediakan metode from_pretrained(...) sama seperti arsitektur model lainnya di Transformers.
Untuk melakukan inferensi, gunakan metode generate, yang memungkinkan generasi teks secara autoregresif. Metode ini mendukung berbagai bentuk decoding, seperti greedy, beam search, dan multinomial sampling.
import requests
from PIL import Image
from transformers import GPT2TokenizerFast, ViTImageProcessor, VisionEncoderDecoderModel
# load a fine-tuned image captioning model and corresponding tokenizer and image processor
model = VisionEncoderDecoderModel.from_pretrained("nlpconnect/vit-gpt2-image-captioning", device_map="auto")
tokenizer = GPT2TokenizerFast.from_pretrained("nlpconnect/vit-gpt2-image-captioning")
image_processor = ViTImageProcessor.from_pretrained("nlpconnect/vit-gpt2-image-captioning")
# let's perform inference on an image
url = "http://images.cocodataset.org/val2017/000000039769.jpg"
image = Image.open(requests.get(url, stream=True).raw)
pixel_values = image_processor(image, return_tensors="pt").to(model.device).pixel_values
# autoregressively generate caption (uses greedy decoding by default)
generated_ids = model.generate(pixel_values)
generated_text = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0]
print(generated_text)
a cat laying on a blanket next to a cat laying on a bedPelatihan
Setelah model dibuat, model tersebut dapat dihaluskan (fine-tuned) serupa dengan BART, T5, atau model encoder-decoder lainnya pada dataset pasangan (gambar, teks).
Seperti yang dapat Anda lihat, hanya 2 input yang diperlukan oleh model untuk menghitung loss: pixel_values (yaitu
gambar) dan labels (yaitu input_ids dari urutan target yang telah dikodekan).
from datasets import load_dataset
from transformers import BertTokenizer, VisionEncoderDecoderModel, ViTImageProcessor
image_processor = ViTImageProcessor.from_pretrained("google/vit-base-patch16-224-in21k")
tokenizer = BertTokenizer.from_pretrained("google-bert/bert-base-uncased")
model = VisionEncoderDecoderModel.from_encoder_decoder_pretrained(
"google/vit-base-patch16-224-in21k", "google-bert/bert-base-uncased"
)
model.config.decoder_start_token_id = tokenizer.cls_token_id
model.config.pad_token_id = tokenizer.pad_token_id
dataset = load_dataset("huggingface/cats-image")
image = dataset["test"]["image"][0]
pixel_values = image_processor(image, return_tensors="pt").to(model.device).pixel_values
labels = tokenizer(
"an image of two cats chilling on a couch",
return_tensors="pt",
).input_ids
# the forward function automatically creates the correct decoder_input_ids
loss = model(pixel_values=pixel_values, labels=labels).lossModel ini disumbangkan oleh nielsr.
VisionEncoderDecoderConfig
kelas transformers.VisionEncoderDecoderConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0id2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Noneis_encoder_decoder: bool = Trueencoder: transformers.configuration_utils.PreTrainedConfig | dict | None = Nonedecoder: transformers.configuration_utils.PreTrainedConfig | dict | None = None )
Parameter
- is_encoder_decoder (
bool, opsional, defaultnyaTrue) — Apakah model digunakan sebagai encoder/decoder atau tidak. - encoder (
Union[~configuration_utils.PreTrainedConfig, dict], opsional) — Objek config atau dictionary dari backbone encoder. - decoder (
Union[~configuration_utils.PreTrainedConfig, dict], opsional) — Objek config atau dictionary dari backbone decoder.
Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari model Vision Encoder Decoder. Kelas ini digunakan untuk membuat instans model Vision Encoder Decoder berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari None
Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.
Contoh:
>>> from transformers import BertConfig, ViTConfig, VisionEncoderDecoderConfig, VisionEncoderDecoderModel
>>> # Initializing a ViT & BERT style configuration
>>> config_encoder = ViTConfig()
>>> config_decoder = BertConfig()
>>> config = VisionEncoderDecoderConfig(encoder=config_encoder, decoder=config_decoder)
>>> # Initializing a ViTBert model (with random weights) from a ViT & google-bert/bert-base-uncased style configurations
>>> model = VisionEncoderDecoderModel(config=config)
>>> # Accessing the model configuration
>>> config_encoder = model.config.encoder
>>> config_decoder = model.config.decoder
>>> # set decoder config to causal lm
>>> config_decoder.is_decoder = True
>>> config_decoder.add_cross_attention = True
>>> # Saving the model, including its configuration
>>> model.save_pretrained("my-model")
>>> # loading model and config from pretrained folder
>>> encoder_decoder_config = VisionEncoderDecoderConfig.from_pretrained("my-model")
>>> model = VisionEncoderDecoderModel.from_pretrained("my-model", config=encoder_decoder_config)from_encoder_decoder_configs
< source >( encoder_config: PreTrainedConfigdecoder_config: PreTrainedConfig**kwargs ) → VisionEncoderDecoderConfig
Mengembalikan
Instans dari objek konfigurasi
Instansiasi VisionEncoderDecoderConfig (atau kelas turunan) dari konfigurasi model encoder yang telah dilatih sebelumnya dan konfigurasi model decoder.
VisionEncoderDecoderModel
kelas transformers.VisionEncoderDecoderModel
< source >( config: transformers.configuration_utils.PreTrainedConfig | None = Noneencoder: transformers.modeling_utils.PreTrainedModel | None = Nonedecoder: transformers.modeling_utils.PreTrainedModel | None = None )
Parameter
- config (PreTrainedConfig, opsional) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.
- encoder (
PreTrainedModel, opsional) — Model encoder yang akan digunakan. - decoder (
PreTrainedModel, opsional) — Model decoder yang akan digunakan.
Model Vision Encoder Decoder polos yang menghasilkan hidden-states mentah tanpa head spesifik di atasnya.
Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)
Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = Nonedecoder_input_ids: typing.Optional[torch.LongTensor] = Nonedecoder_attention_mask: typing.Optional[torch.BoolTensor] = Noneencoder_outputs: tuple[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Nonedecoder_inputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Noneoutput_attentions: bool | None = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → Seq2SeqLMOutput or tuple(torch.Tensor)
Parameter
- pixel_values (
torch.Tensordengan bentuk(batch_size, num_channels, image_size, image_size), opsional) — Tensor yang sesuai dengan gambar input. Nilai piksel dapat diperoleh menggunakanimage_processor_class. Lihatimage_processor_class.__call__untuk detailnya (processor_classmenggunakanimage_processor_classuntuk memproses gambar). - decoder_input_ids (
torch.LongTensordengan bentuk(batch_size, target_sequence_length), opsional) — Indeks token dari urutan input decoder dalam kosakata. Indeks dapat diperoleh menggunakan PreTrainedTokenizer. Lihat PreTrainedTokenizer.encode() dan PreTrainedTokenizer.call() untuk detailnya. Apa itu input ID? Jika past_key_values digunakan, secara opsional hanya decoder_input_ids terakhir yang perlu diinput (lihat past_key_values). Untuk pelatihan, decoder_input_ids dibuat secara otomatis oleh model dengan menggeser label ke kanan, mengganti -100 dengan pad_token_id, dan menambahkan decoder_start_token_id di depannya.Indeks dapat diperoleh menggunakan PreTrainedTokenizer. Lihat PreTrainedTokenizer.encode() dan PreTrainedTokenizer.call() untuk detailnya.
Jika
past_key_valuesdigunakan, secara opsional hanyadecoder_input_idsterakhir yang perlu diinput (lihatpast_key_values).Untuk pelatihan,
decoder_input_idsdibuat secara otomatis oleh model dengan menggeserlabelske kanan, mengganti -100 denganpad_token_id, dan menambahkandecoder_start_token_iddi awal. - decoder_attention_mask (
torch.BoolTensordengan bentuk(batch_size, target_sequence_length), opsional) — Perilaku default: menghasilkan tensor yang mengabaikan token pad didecoder_input_ids. Mask kausal juga akan digunakan secara default. - encoder_outputs (
tuple[torch.Tensor], opsional) — Tuple terdiri dari (last_hidden_state, opsional:hidden_states, opsional:attentions)last_hidden_statedengan bentuk(batch_size, sequence_length, hidden_size), opsional) adalah rangkaian hidden-states pada keluaran lapisan terakhir encoder. Digunakan dalam cross-attention decoder. - past_key_values (
~cache_utils.Cache, opsional) — Hidden-states yang sudah dihitung sebelumnya (key dan values di blok self-attention dan di blok cross-attention) yang dapat digunakan untuk mempercepat decoding berurutan. Ini biasanya terdiri daripast_key_valuesyang dikembalikan oleh model pada tahap decoding sebelumnya, ketikause_cache=Trueatauconfig.use_cache=True.Hanya instance Cache yang diizinkan sebagai input, lihat panduan kv cache kami. Jika tidak ada
past_key_valuesyang diteruskan, DynamicCache akan diinisialisasi secara default.Model akan menghasilkan format cache yang sama dengan yang diberikan sebagai input.
Jika
past_key_valuesdigunakan, pengguna diharapkan hanya memasukkaninput_idsyang belum diproses (yang tidak memiliki state past key value yang diberikan ke model ini) dengan bentuk(batch_size, unprocessed_length)alih-alih semuainput_idsdengan bentuk(batch_size, sequence_length). - decoder_inputs_embeds (
torch.Tensordengan bentuk(batch_size, target_sequence_length, hidden_size), opsional) — Secara opsional, alih-alih meneruskandecoder_input_ids, Anda dapat memilih untuk langsung meneruskan representasi tertanam. Hal ini berguna jika Anda ingin memiliki kendali lebih atas cara mengonversi indeksdecoder_input_idsmenjadi vektor terkait, dibandingkan dengan matriks pencarian penanaman internal model. - labels (
torch.LongTensordengan bentuk(batch_size, sequence_length), opsional) — Label untuk menghitung kerugian pemodelan bahasa tersembunyi (masked language modeling loss) untuk decoder. Indeks harus berada dalam[-100, 0, ..., config.vocab_size](lihat docstringinput_ids). Token dengan indeks yang disetel ke-100diabaikan (ditutupi), kerugian hanya dihitung untuk token dengan label dalam[0, ..., config.vocab_size] - use_cache (
bool, opsional) — Jika diset keTrue, state kunci-nilaipast_key_valuesakan dikembalikan dan dapat digunakan untuk mempercepat decoding (lihatpast_key_values). - output_attentions (
bool, opsional) — Apakah akan mengembalikan tensor attentions dari semua lapisan attention. Lihatattentionsdi bawah tensor yang dikembalikan untuk detail lebih lanjut. - output_hidden_states (
bool, opsional) — Apakah akan mengembalikan hidden states dari semua lapisan. Lihathidden_statesdi bawah tensor yang dikembalikan untuk detail lebih lanjut. - return_dict (
bool, opsional) — Apakah akan mengembalikan ModelOutput alih-alih tuple biasa.
Mengembalikan
Seq2SeqLMOutput atau tuple(torch.Tensor)
Seq2SeqLMOutput atau tuple dari
torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai
elemen tergantung pada konfigurasi (VisionEncoderDecoderConfig) dan input.
Metode forward dari VisionEncoderDecoderModel menimpa metode khusus __call__.
Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance
Modulesetelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.
loss (
torch.Tensordengan bentuk(1,), opsional, dikembalikan saatlabelsdisediakan) — Loss pemodelan bahasa.logits (
torch.Tensordengan bentuk(batch_size, sequence_length, config.vocab_size)) — Skor prediksi dari kepala pemodelan bahasa (skor untuk setiap token kosakata sebelum SoftMax).past_key_values (
EncoderDecoderCache, opsional, dikembalikan ketikause_cache=Truediteruskan atau ketikaconfig.use_cache=True) — Ini adalah instance EncoderDecoderCache. Untuk detail lebih lanjut, lihat panduan kv cache kami.Mengandung hidden-states yang telah dihitung sebelumnya (key dan values di blok self-attention dan di blok cross-attention) yang dapat digunakan (lihat input
past_key_values) untuk mempercepat decoding berurutan.decoder_hidden_states (
tuple(torch.Tensor), opsional, dikembalikan saatoutput_hidden_states=Truedilewatkan atau saatconfig.output_hidden_states=True) — Tuple daritorch.Tensor(satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk(batch_size, sequence_length, hidden_size).Hidden-states dari decoder pada output setiap layer ditambah output embedding awal.
decoder_attentions (
tuple(torch.Tensor), opsional, dikembalikan saatoutput_attentions=Truedilewatkan atau saatconfig.output_attentions=True) — Tuple daritorch.Tensor(satu untuk setiap lapisan) dengan bentuk(batch_size, num_heads, sequence_length, sequence_length).Bobot perhatian dari decoder, setelah softmax perhatian, yang digunakan untuk menghitung rata-rata berbobot di kepala self-attention.
cross_attentions (
tuple(torch.Tensor), opsional, dikembalikan saatoutput_attentions=Truedilewatkan atau saatconfig.output_attentions=True) — Tuple daritorch.Tensor(satu untuk setiap layer) dengan bentuk(batch_size, num_heads, sequence_length, sequence_length).Bobot perhatian dari lapisan cross-attention decoder, setelah softmax perhatian, yang digunakan untuk menghitung rata-rata berbobot di kepala cross-attention.
encoder_last_hidden_state (
torch.Tensordengan bentuk(batch_size, sequence_length, hidden_size), opsional) — Urutan hidden-states pada keluaran lapisan terakhir dari encoder model.encoder_hidden_states (
tuple(torch.Tensor), opsional, dikembalikan ketikaoutput_hidden_states=Truedilewatkan atau ketikaconfig.output_hidden_states=True) — Tuple daritorch.Tensor(satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk(batch_size, sequence_length, hidden_size).Hidden-states dari encoder pada output setiap layer ditambah output embedding awal.
encoder_attentions (
tuple(torch.Tensor), opsional, dikembalikan saatoutput_attentions=Truedilewatkan atau saatconfig.output_attentions=True) — Tuple daritorch.Tensor(satu untuk setiap lapisan) dengan bentuk(batch_size, num_heads, sequence_length, sequence_length).Bobot perhatian dari encoder, setelah softmax perhatian, yang digunakan untuk menghitung rata-rata berbobot di kepala self-attention.
Contoh:
>>> from transformers import AutoProcessor, VisionEncoderDecoderModel
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from PIL import Image
>>> import torch
>>> processor = AutoProcessor.from_pretrained("microsoft/trocr-base-handwritten")
>>> model = VisionEncoderDecoderModel.from_pretrained("microsoft/trocr-base-handwritten")
>>> # load image from the IAM dataset
>>> url = "https://fki.tic.heia-fr.ch/static/img/a01-122-02.jpg"
>>> with httpx.stream("GET", url) as response:
... image = Image.open(BytesIO(response.read())).convert("RGB")
>>> # training
>>> model.config.decoder_start_token_id = processor.tokenizer.eos_token_id
>>> model.config.pad_token_id = processor.tokenizer.pad_token_id
>>> model.config.vocab_size = model.config.decoder.vocab_size
>>> pixel_values = processor(image, return_tensors="pt").pixel_values
>>> text = "hello world"
>>> labels = processor.tokenizer(text, return_tensors="pt").input_ids
>>> outputs = model(pixel_values=pixel_values, labels=labels)
>>> loss = outputs.loss
>>> # inference (generation)
>>> generated_ids = model.generate(pixel_values)
>>> generated_text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]from_encoder_decoder_pretrained
< source >( encoder_pretrained_model_name_or_path: str | None = Nonedecoder_pretrained_model_name_or_path: str | None = None*model_args**kwargs )
Parameter
- encoder_pretrained_model_name_or_path (
str, opsional) — Informasi yang diperlukan untuk memulai image encoder. Bisa berupa:- Sebuah string, yaitu model id dari model pretrained yang dihosting di dalam repositori model di huggingface.co. Contoh:
google/vit-base-patch16-224-in21k. - Path ke direktori yang berisi bobot model yang disimpan menggunakan
save_pretrained(), misalnya
./my_model_directory/.
- Sebuah string, yaitu model id dari model pretrained yang dihosting di dalam repositori model di huggingface.co. Contoh:
- decoder_pretrained_model_name_or_path (
str, opsional, default keNone) — Informasi yang diperlukan untuk memulai text decoder. Bisa berupa:- String, model id dari model pretrained yang dihosting di dalam model repo di huggingface.co.
- Path ke direktori yang berisi bobot model yang disimpan menggunakan
save_pretrained(), misalnya
./my_model_directory/.
- model_args (argumen posisional lainnya, opsional) —
Semua argumen posisional lainnya akan diteruskan ke metode
__init__model yang mendasarinya. - kwargs (sisa kamus argumen kata kunci, opsional) —
Dapat digunakan untuk memperbarui objek konfigurasi (setelah dimuat) dan menginisiasi model (mis.,
output_attentions=True).- Untuk memperbarui konfigurasi encoder, gunakan prefiks encoder_ untuk setiap parameter konfigurasi.
- Untuk memperbarui konfigurasi decoder, gunakan prefiks decoder_ untuk setiap parameter konfigurasi.
- Untuk memperbarui konfigurasi model induk, jangan gunakan awalan untuk setiap parameter konfigurasi.
Berperilaku berbeda tergantung pada apakah
configdisediakan atau dimuat secara otomatis.
Instansiasi encoder dan decoder dari satu atau dua kelas dasar pustaka dari checkpoint model pretrained.
Model secara default diatur dalam mode evaluasi menggunakan model.eval() (modul Dropout dinonaktifkan). Untuk melatih model, Anda perlu terlebih dahulu mengembalikannya ke mode pelatihan dengan model.train().
Contoh:
>>> from transformers import VisionEncoderDecoderModel
>>> # initialize a vit-bert from a pretrained ViT and a pretrained BERT model. Note that the cross-attention layers will be randomly initialized
>>> model = VisionEncoderDecoderModel.from_encoder_decoder_pretrained(
... "google/vit-base-patch16-224-in21k", "google-bert/bert-base-uncased"
... )
>>> # saving model after fine-tuning
>>> model.save_pretrained("./vit-bert")
>>> # load fine-tuned model
>>> model = VisionEncoderDecoderModel.from_pretrained("./vit-bert")