Transformers documentation
Модели Vision Encoder Decoder
Эта модель была опубликована в HF papers 21.09.2021 и добавлена в Hugging Face Transformers 13.10.2021.
Модели Vision Encoder Decoder
Обзор
Модель VisionEncoderDecoderModel позволяет инициализировать модель image-to-text, используя в качестве энкодера (например ViT, BEiT, DeiT, Swin) любую предобученную модель зрения на основе Transformer, а в качестве декодера (например RoBERTa, GPT2, BERT, DistilBERT) — любую предобученную языковую модель.
Эффективность инициализации моделей «изображение в последовательность текста» с использованием предобученных контрольных точек была продемонстрирована, например, в работе TrOCR: Transformer-based Optical Character Recognition with Pre-trained Models авторов Minghao Li, Tengchao Lv, Lei Cui, Yijuan Lu, Dinei Florencio, Cha Zhang, Zhoujun Li, Furu Wei.
После обучения/дообучения такой модели VisionEncoderDecoderModel её можно сохранить/загрузить так же, как и любые другие модели (см. примеры ниже для получения дополнительной информации).
Примером приложения является генерация описаний изображений, в которой энкодер используется для кодирования изображения, после чего авторегрессионная языковая модель генерирует описание. Другой пример — распознавание символов. См. TrOCR, который является экземпляром VisionEncoderDecoderModel.
Случайная инициализация VisionEncoderDecoderModel из конфигураций модели
VisionEncoderDecoderModel может быть инициализирован случайным образом на основе конфигураций энкодера и декодера. В примере ниже показано, как это сделать, используя конфигурацию ViTModel по умолчанию для энкодера и конфигурацию BertForCausalLM по умолчанию для декодера.
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)Инициализация VisionEncoderDecoderModel из предобученного энкодера и предобученного декодера
VisionEncoderDecoderModel может быть инициализирован из предобученной контрольной точки энкодера и предобученной контрольной точки декодера. Обратите внимание, что в качестве энкодера может использоваться любая предобученная модель зрения на основе Transformer, например Swin, а в качестве декодера — как предобученные автоэнкодерные модели, например BERT, так и предобученные каузальные языковые модели, например GPT2, а также предобученная часть декодера моделей sequence-to-sequence, например декодер BART.
В зависимости от выбранной архитектуры декодера слои кросс-внимания могут быть инициализированы случайными значениями.
Инициализация VisionEncoderDecoderModel из предобученных контрольных точек энкодера и декодера требует дообучения модели на целевой задаче, как показано в статье в блоге Warm-starting-encoder-decoder.
Для этого класс VisionEncoderDecoderModel предоставляет метод 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"
)Загрузка существующей контрольной точки VisionEncoderDecoderModel и выполнение инференса
Для загрузки дообученных контрольных точек класса VisionEncoderDecoderModel VisionEncoderDecoderModel предоставляет метод from_pretrained(...), как и любая другая архитектура модели в Transformers.
Для выполнения инференса используется метод generate, который позволяет генерировать текст авто-регрессивно. Этот метод поддерживает различные способы декодирования, такие как жадный поиск, beam search и мультиномиальное сэмплирование.
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 bedОбучение
После создания модель можно дообучать аналогично BART, T5 или любой другой encoder-decoder модели на наборе данных пар (изображение, текст).
Как видно, для вычисления функции потерь модели требуются только два входа: pixel_values (то есть
изображения) и labels (то есть input_ids закодированной целевой последовательности).
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).lossЭта модель была добавлена пользователем nielsr.
VisionEncoderDecoderConfig
класс 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 )
Параметры
- is_encoder_decoder (
bool, необязательный, по умолчаниюTrue) — Указывает, используется ли модель в качестве энкодера/декодера. - encoder (
Union[~configuration_utils.PreTrainedConfig, dict], необязательный) — Объект конфигурации или словарь конфигурации encoder-бэкбона. - decoder (
Union[~configuration_utils.PreTrainedConfig, dict], необязательный) — Объект конфигурации или словарь конфигурации декодера.
Это класс конфигурации для хранения конфигурации модели Vision Encoder Decoder. Он используется для создания модели Vision Encoder Decoder в соответствии с указанными аргументами, определяющими архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации None
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
Примеры:
>>> 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
Возвращает
Экземпляр объекта конфигурации
Создайте экземпляр VisionEncoderDecoderConfig (или производного класса) на основе конфигурации предобученной модели-энкодера и конфигурации модели-декодера.
VisionEncoderDecoderModel
класс transformers.VisionEncoderDecoderModel
< source >( config: transformers.configuration_utils.PreTrainedConfig | None = Noneencoder: transformers.modeling_utils.PreTrainedModel | None = Nonedecoder: transformers.modeling_utils.PreTrainedModel | None = None )
Параметры
- config (PreTrainedConfig, optional) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с помощью файла конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().
- encoder (
PreTrainedModel, необязательный) — Модель-энкодер, которую следует использовать. - decoder (
PreTrainedModel, необязательный) — Модель декодера, которую следует использовать.
Модель Vision Encoder Decoder, выводящая «сырые» скрытые состояния без какого-либо специализированного слоя на выходе.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
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)
Параметры
- pixel_values (
torch.Tensorформы(batch_size, num_channels, image_size, image_size), необязательный) — Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощьюimage_processor_class. Подробности см. вimage_processor_class.__call__(processor_classиспользуетimage_processor_classдля обработки изображений). - decoder_input_ids (
torch.LongTensorформы(batch_size, target_sequence_length), необязательный) — Индексы токенов входной последовательности декодера в словаре. Индексы можно получить с помощью PreTrainedTokenizer. Подробности — в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call(). Что такое входные идентификаторы? Если используется past_key_values, необязательно вводить все decoder_input_ids — достаточно только последних (см. past_key_values). При обучении decoder_input_ids автоматически создаются моделью путём сдвига labels вправо, замены -100 на pad_token_id и добавления в начало decoder_start_token_id.Индексы можно получить с помощью PreTrainedTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().
Что такое входные идентификаторы?
Если используется
past_key_values, то в качестве входных данных можно указать только последниеdecoder_input_ids(см.past_key_values).Для обучения
decoder_input_idsавтоматически создаются моделью путём сдвигаlabelsвправо, замены -100 наpad_token_idи добавления в началоdecoder_start_token_id. - decoder_attention_mask (
torch.BoolTensorформы(batch_size, target_sequence_length), необязательный) — Поведение по умолчанию: генерировать тензор, игнорирующий токены заполнения вdecoder_input_ids. По умолчанию также будет использоваться каузальная маска. - encoder_outputs (
tuple[torch.Tensor], необязательный) — Кортеж состоит из (last_hidden_state, необязательный:hidden_states, необязательный:attentions)last_hidden_stateформы(batch_size, sequence_length, hidden_size), необязательный) представляет собой последовательность скрытых состояний на выходе последнего слоя энкодера. Используется в кросс-внимании декодера. - past_key_values (
~cache_utils.Cache, необязательный) — Предвычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно этоpast_key_values, возвращённые моделью на предыдущем этапе декодирования, когдаuse_cache=Trueилиconfig.use_cache=True.В качестве входного параметра допускается только экземпляр Cache, см. наше руководство по кэшу KV. Если
past_key_valuesне переданы, по умолчанию будет инициализирован DynamicCache.Модель будет выводить тот же формат кэша, который был передан на вход.
Если используются
past_key_values, ожидается, что пользователь передаст только необработанныеinput_ids(те, для которых в этой модели ещё не заданы состояния прошлых ключей и значений) формы(batch_size, unprocessed_length), а не всеinput_idsформы(batch_size, sequence_length). - decoder_inputs_embeds (
torch.Tensorформы(batch_size, target_sequence_length, hidden_size), необязательный) — При необходимости вместо передачиdecoder_input_idsможно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексыdecoder_input_idsпреобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели. - labels (
torch.LongTensorформы(batch_size, sequence_length), необязательный) — Метки для вычисления потерь маскированного языкового моделирования для декодера. Индексы должны находиться в диапазоне[-100, 0, ..., config.vocab_size](см. docstringinput_ids). Токены с индексами, установленными в-100, игнорируются (маскируются); потери вычисляются только для токенов с метками в диапазоне[0, ..., config.vocab_size] - use_cache (
bool, необязательный) — Если установлено вTrue, возвращаются состояния ключей и значенийpast_key_values, которые можно использовать для ускорения декодирования (см.past_key_values). - output_attentions (
bool, необязательный) — Указывает, следует ли возвращать тензоры внимания всех слоев внимания. Подробности см. в описанииattentionsв разделе возвращаемых тензоров. - output_hidden_states (
bool, необязательный) — Указывает, следует ли возвращать скрытые состояния всех слоев. Подробности см. в описанииhidden_statesсреди возвращаемых тензоров. - return_dict (
bool, необязательный) — Указывает, следует ли возвращать ModelOutput вместо обычного кортежа.
Возвращает
Seq2SeqLMOutput или tuple(torch.Tensor)
Объект Seq2SeqLMOutput или кортеж
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (VisionEncoderDecoderConfig) и входных данных.
Метод forward модели VisionEncoderDecoderModel переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
loss (
torch.Tensorформы(1,), необязательный, возвращается, если заданlabels) — Потери языковой модели.logits (
torch.Tensorформы(batch_size, sequence_length, config.vocab_size)) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).past_key_values (
EncoderDecoderCache, необязательный, возвращается при передачеuse_cache=Trueили когдаconfig.use_cache=True) — это экземпляр EncoderDecoderCache. Подробнее см. в нашем руководстве по кэшу kv.Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать (см. вход
past_key_values) для ускорения последовательного декодирования.decoder_hidden_states (
tuple(torch.Tensor), необязательный, возвращается при передачеoutput_hidden_states=Trueили приconfig.output_hidden_states=True) — Кортеж изtorch.Tensor(один для вывода эмбеддингов, если у модели есть слой эмбеддингов, + один для вывода каждого слоя) формы(batch_size, sequence_length, hidden_size).Скрытые состояния декодера на выходе каждого слоя, а также выходные значения начального слоя встраивания.
decoder_attentions (
tuple(torch.Tensor), необязательный, возвращается при передачеoutput_attentions=Trueили когдаconfig.output_attentions=True) — Кортежtorch.Tensor(по одному на каждый слой) формы(batch_size, num_heads, sequence_length, sequence_length).Веса внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
cross_attentions (
tuple(torch.Tensor), необязательный, возвращается при передачеoutput_attentions=Trueили приconfig.output_attentions=True) — Кортежtorch.Tensor(по одному на каждый слой) формы(batch_size, num_heads, sequence_length, sequence_length).Веса внимания кросс-внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах кросс-внимания.
encoder_last_hidden_state (
torch.Tensorформы(batch_size, sequence_length, hidden_size), необязательный) — Последовательность скрытых состояний на выходе последнего слоя энкодера модели.encoder_hidden_states (
tuple(torch.Tensor), необязательный, возвращается, если переданоoutput_hidden_states=Trueили еслиconfig.output_hidden_states=True) — Кортежtorch.Tensor(один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы(batch_size, sequence_length, hidden_size).Скрытые состояния кодировщика на выходе каждого слоя, а также выходные значения начального слоя встраиваний.
encoder_attentions (
tuple(torch.Tensor), необязательный, возвращается при передачеoutput_attentions=Trueили приconfig.output_attentions=True) — Кортежtorch.Tensor(по одному на каждый слой) формы(batch_size, num_heads, sequence_length, sequence_length).Веса внимания энкодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
Примеры:
>>> 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 )
Параметры
- encoder_pretrained_model_name_or_path (
str, необязательный) — Информация, необходимая для инициализации image encoder. Может быть одним из следующих:- Строка, model id предобученной модели, размещённой в репозитории моделей на huggingface.co. Пример:
google/vit-base-patch16-224-in21k. - Путь к каталогу, содержащему веса модели, сохранённые с помощью
save_pretrained(), например,
./my_model_directory/.
- Строка, model id предобученной модели, размещённой в репозитории моделей на huggingface.co. Пример:
- decoder_pretrained_model_name_or_path (
str, необязательный, по умолчаниюNone) — Необходимые данные для инициализации тектового декодера. Может быть одним из:- Строка, model id предобученной модели, размещенной в репозитории моделей на huggingface.co.
- Путь к каталогу, содержащему веса модели, сохранённые с помощью
save_pretrained(), например,
./my_model_directory/.
- model_args (остальные позиционные аргументы, необязательные) —
Все оставшиеся позиционные аргументы передаются в метод
__init__базовой модели. - kwargs (остальные именованные аргументы, необязательный) —
Можно использовать для обновления объекта конфигурации (после его загрузки) и инициализации модели (например,
output_attentions=True).- Чтобы обновить конфигурацию энкодера, используйте префикс encoder_ для каждого параметра конфигурации.
- Чтобы обновить конфигурацию декодера, используйте префикс decoder_ для каждого параметра конфигурации.
- Чтобы обновить конфигурацию родительской модели, не используйте префикс для каждого параметра конфигурации.
Поведение зависит от того, предоставлен ли
configили он загружается автоматически.
Создайте энкодер и декодер из одного или двух базовых классов библиотеки на основе контрольных точек предобученной модели.
По умолчанию модель переводится в режим оценки с помощью model.eval() (модули Dropout отключаются). Для обучения модели необходимо сначала вернуть её в режим обучения с помощью model.train().
Пример:
>>> 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")