Transformers documentation
TrOCR
Эта модель была опубликована в HF papers 21.09.2021 и добавлена в Hugging Face Transformers 13.10.2021.
TrOCR
TrOCR — это модель распознавания текста, предназначенная как для понимания изображений, так и для генерации текста. Она не требует отдельных моделей для обработки изображений или генерации символов. TrOCR представляет собой простую сквозную систему, использующую трансформер для выполнения задач визуального понимания и генерации текста.
Все исходные контрольные точки TrOCR можно найти в организации Microsoft.
TrOCR architecture. Taken from the original paper. Эта модель была добавлена пользователем nielsr.
Щёлкните по моделям TrOCR в боковой панели справа, чтобы увидеть больше примеров применения TrOCR к различным задачам работы с изображениями и текстом.
Приведённый ниже пример демонстрирует, как выполнять распознавание символов (OCR) с помощью класса AutoModel.
import requests
from PIL import Image
from transformers import TrOCRProcessor, VisionEncoderDecoderModel
processor = TrOCRProcessor.from_pretrained("microsoft/trocr-base-handwritten")
model = VisionEncoderDecoderModel.from_pretrained("microsoft/trocr-base-handwritten", device_map="auto")
# load image from the IAM dataset
url = "https://fki.tic.heia-fr.ch/static/img/a01-122-02.jpg"
image = Image.open(requests.get(url, stream=True).raw).convert("RGB")
pixel_values = processor(image, return_tensors="pt").to(model.device).pixel_values
generated_ids = model.generate(pixel_values)
generated_text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
print(generated_text)Квантование
Квантование снижает нагрузку на память при работе с большими моделями, представляя веса в пониженной точности. Подробнее о доступных бэкендах квантования см. в обзоре Квантование.
Приведённый ниже пример использует bitsandbytes для квантования весов до 8 бит.
# pip install bitsandbytes accelerate
from transformers import TrOCRProcessor, VisionEncoderDecoderModel, BitsandBytesConfig
import requests
from PIL import Image
# Set up the quantization configuration
quantization_config = BitsandBytesConfig(load_in_8bit=True)
# Use a large checkpoint for a more noticeable impact
processor = TrOCRProcessor.from_pretrained("microsoft/trocr-large-handwritten")
model = VisionEncoderDecoderModel.from_pretrained(
"microsoft/trocr-large-handwritten",
quantization_config=quantization_config
device_map="auto")
# load image from the IAM dataset
url = "[https://fki.tic.heia-fr.ch/static/img/a01-122-02.jpg](https://fki.tic.heia-fr.ch/static/img/a01-122-02.jpg)"
image = Image.open(requests.get(url, stream=True).raw).convert("RGB")
pixel_values = processor(image, return_tensors="pt").to(model.device).pixel_values
generated_ids = model.generate(pixel_values)
generated_text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
print(generated_text)Примечания
- TrOCR объединяет ViTImageProcessor/DeiTImageProcessor и RobertaTokenizer/XLMRobertaTokenizer в единый экземпляр TrOCRProcessor для обработки изображений и текста.
- TrOCR всегда используется в рамках фреймворка VisionEncoderDecoder.
Ресурсы
- Блог о ускорении Document AI с помощью TrOCR.
- Блог о том, как использовать Document AI с TrOCR.
- Ноутбук о том, как дообучить TrOCR на базе рукописных текстов IAM с помощью Seq2SeqTrainer.
- Интерактивная демонстрация распознавания рукописных символов с помощью TrOCR.
- Ноутбук по инференсу с TrOCR и демо на Gradio.
- Ноутбук по оценке TrOCR на тестовом наборе IAM.
TrOCRConfig
класс transformers.TrOCRConfig
< 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 = 0is_encoder_decoder: bool = Falseid2label: 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 = Nonevocab_size: int = 50265d_model: int = 1024decoder_layers: int = 12decoder_attention_heads: int = 16decoder_ffn_dim: int = 4096activation_function: str = 'gelu'max_position_embeddings: int = 512dropout: float | int = 0.1attention_dropout: float | int = 0.0activation_dropout: float | int = 0.0decoder_start_token_id: int = 2init_std: float = 0.02decoder_layerdrop: float | int = 0.0use_cache: bool = Truescale_embedding: bool = Falseuse_learned_position_embeddings: bool = Truelayernorm_embedding: bool = Truepad_token_id: int | None = 1bos_token_id: int | None = 0eos_token_id: int | list[int] | None = 2cross_attention_hidden_size: int | None = Noneis_decoder: bool = Falsetie_word_embeddings: bool = True )
Параметры
- vocab_size (
int, необязательный, по умолчанию50265) — Размер словаря модели. Определяет количество различных токенов, которые могут быть представлены вinput_ids. - d_model (
int, необязательный, по умолчанию1024) — Размер слоев кодировщика и пулер-слоя. - decoder_layers (
int, необязательный, по умолчанию12) — Количество скрытых слоев в декодере Transformer. Если не задано, будет использовано то же значение, что и уnum_layers. - decoder_attention_heads (
int, необязательный, по умолчанию16) — Количество головок внимания в каждом слое внимания декодера Transformer. - decoder_ffn_dim (
int, необязательный, по умолчанию4096) — Размерность «промежуточного» (часто называемого feed-forward) слоя в декодере. - activation_function (
str, необязательный, по умолчаниюgelu) — Нелинейная функция активации (функция или строка) в декодере. Например,"gelu","relu","silu"и т. д. - max_position_embeddings (
int, необязательный, по умолчанию512) — Максимальная длина последовательности, с которой может использоваться эта модель. - dropout (
Union[float, int], необязательный, по умолчанию0.1) — Коэффициент для всех слоёв dropout. - attention_dropout (
Union[float, int], необязательный, по умолчанию0.0) — Коэффициент dropout для вероятностей внимания. - activation_dropout (
Union[float, int], необязательный, по умолчанию0.0) — Коэффициент dropout для активаций внутри полносвязного слоя. - decoder_start_token_id (
int, необязательный, по умолчанию2) — Если модель encoder-decoder начинает декодирование с токена, отличного отbos, то идентификатор этого токена. - init_std (
float, необязательный, по умолчанию0.02) — Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов. - decoder_layerdrop (
Union[float, int], необязательный, по умолчанию0.0) — Вероятность LayerDrop для декодера. Подробности — в [статье о LayerDrop](см. https://huggingface.co/papers/1909.11556). - use_cache (
bool, необязательный, по умолчаниюTrue) — Указывает, должен ли модель возвращать последние ключи/значения внимания (не используется во всех моделях). Актуально только еслиconfig.is_decoder=Trueили если модель является генеративной моделью только с декодером. - scale_embedding (
bool, необязательный, по умолчаниюFalse) — Указывает, следует ли масштабировать эмбеддинги, деля их на sqrt(d_model). - use_learned_position_embeddings (
bool, необязательный, по умолчаниюTrue) — Использовать ли обучаемые позиционные эмбеддинги. Если нет, будут использоваться синусоидальные позиционные эмбеддинги. - layernorm_embedding (
bool, необязательный, по умолчаниюTrue) — Использовать ли layernorm после эмбеддингов слов и позиций. - pad_token_id (
int, необязательный, по умолчанию1) — Идентификатор токена, используемого для дополнения (padding) в словаре. - bos_token_id (
int, необязательный, по умолчанию0) — Идентификатор токена, используемого для обозначения начала потока в словаре. - eos_token_id (
Union[int, list[int]], необязательный, по умолчанию2) — Идентификатор токена, используемого для обозначения конца потока в словаре. - cross_attention_hidden_size (
int, необязательный) — Размер скрытого слоя выходов энкодера, проецируемый в пространство ключей/значений кросс-внимания декодера. Используется, когда у энкодера и декодера разные размеры скрытого слоя. - is_decoder (
bool, необязательный, по умолчаниюFalse) — Указывает, используется ли модель в качестве декодера. ЕслиFalse, модель используется как энкодер. - tie_word_embeddings (
bool, необязательный, по умолчаниюTrue) — Определяет, следует ли связывать веса эмбеддингов согласно маппингуtied_weights_keysмодели.
Это класс конфигурации для хранения настроек модели TrocrModel. Он используется для создания экземпляра модели Trocr в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации microsoft/trocr-base-handwritten
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
Пример:
>>> from transformers import TrOCRConfig, TrOCRForCausalLM
>>> # Initializing a TrOCR-base style configuration
>>> configuration = TrOCRConfig()
>>> # Initializing a model (with random weights) from the TrOCR-base style configuration
>>> model = TrOCRForCausalLM(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configTrOCRProcessor
класс transformers.TrOCRProcessor
< source >( image_processor = Nonetokenizer = None**kwargs )
Создаёт TrOCRProcessor, который объединяет процессор изображений и токенизатор в единый процессор.
TrOCRProcessor предоставляет все возможности ViTImageProcessor и XLMRobertaTokenizer. Подробнее см. в документации ~ViTImageProcessor и ~XLMRobertaTokenizer.
__call__
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> ) → ~image_processing_base.BatchFeature
Параметры
- images (
Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], необязательный) — Изображение для предобработки. Ожидается одно изображение или батч изображений со значениями пикселей в диапазоне от 0 до 255. Если передаются изображения со значениями пикселей в диапазоне от 0 до 1, установитеdo_rescale=False. - text (
Union[str, list[str], list[list[str]]], необязательный) — Последовательность или батч последовательностей для кодирования. Каждая последовательность может быть строкой или списком строк (предварительно токенизированная строка). Если вы передаёте предварительно токенизированный вход, установитеis_split_into_words=True, чтобы избежать неоднозначности с батчированными входами. - return_mm_token_type_ids (
bool, kwargs) — Следует ли возвращать идентификаторы типов мультимодальных токенов, указывающие на позиции мультимодальных плейсхолдер-токенов. - return_text_replacement_offsets (
bool, kwargs) — Возвращать ли смещения символов для каждого мультимодального плейсхолдера и его замены. - return_tensors (
strили TensorType, необязательный) — Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:'pt': возвращает объектыtorch.TensorPyTorch.'np': возвращает объекты NumPynp.ndarray.
- **kwargs (ProcessingKwargs, optional) — Дополнительные параметры обработки для каждой модальности (текст, изображения, видео, аудио). Специфичные для модели параметры перечислены выше; полный список поддерживаемых аргументов см. в классе TypedDict.
Возвращает
~image_processing_base.BatchFeature
- data (
dict) — Словарь списков/массивов/тензоров, возвращаемый методом call (‘pixel_values’ и т. д.). - tensor_type (
Union[None, str, TensorType], необязательный) — Здесь можно указать tensor_type, чтобы при инициализации преобразовать списки целых чисел в тензоры PyTorch/Numpy.
from_pretrained
< source >( pretrained_model_name_or_path: str | os.PathLikecache_dir: str | os.PathLike | None = Noneforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'**kwargs )
Параметры
- pretrained_model_name_or_path (
strилиos.PathLike) — Это может быть:- строка, model id предобученного feature_extractor, размещенного в репозитории модели на huggingface.co.
- путь к каталогу, содержащему файл feature extractor, сохранённый с помощью метода
save_pretrained(), например,
./my_model_directory/. - путь к сохранённому JSON-файлу экстрактора признаков, например,
./my_model_directory/preprocessor_config.json.
- **kwargs —
Дополнительные именованные аргументы, передаваемые как в
from_pretrained(), так и в
~tokenization_utils_base.PreTrainedTokenizer.from_pretrained.
Создайте экземпляр процессора, связанного с предобученной моделью.
Этот метод класса просто вызывает метод from_pretrained() экстрактора признаков, метод ImageProcessingMixin процессора изображений и метод
~tokenization_utils_base.PreTrainedTokenizer.from_pretrainedтокенизатора. Подробности см. в строках документации указанных методов.
save_pretrained
< source >( save_directorypush_to_hub: bool = False**kwargs )
Параметры
- save_directory (
strилиos.PathLike) — Каталог, в котором будут сохранены JSON-файл feature extractor и файлы токенизатора (каталог будет создан, если он не существует). - push_to_hub (
bool, необязательный, по умолчаниюFalse) — Указывает, следует ли после сохранения отправить вашу модель в Hugging Face model hub. С помощьюrepo_idможно указать репозиторий, в который нужно отправить модель (по умолчанию используется имяsave_directoryв вашем пространстве имён). - kwargs (
dict[str, Any], необязательный) — Дополнительные именованные аргументы, передаваемые в метод push_to_hub().
Сохраняет атрибуты этого процессора (извлекатель признаков, токенизатор…) в указанную директорию, чтобы его можно было загрузить повторно с помощью метода from_pretrained().
Этот метод класса просто вызывает save_pretrained() и save_pretrained(). Подробности см. в строках документации методов, описанных выше.
Этот метод передаёт все свои аргументы в batch_decode() класса PreTrainedTokenizer. Подробности см. в docstring этого метода.
Этот метод передаёт все свои аргументы в decode() класса PreTrainedTokenizer. Подробности см. в docstring этого метода.
TrOCRForCausalLM
класс transformers.TrOCRForCausalLM
< source >( config: TrOCRConfig )
Параметры
- config (TrOCRConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с помощью файла конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().
Декодер TrOCR с головой языковой модели. Может использоваться в качестве декодерной части EncoderDecoderModel и
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneencoder_hidden_states: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonecache: transformers.cache_utils.Cache | None = Noneinputs_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 ) → CausalLMOutputWithCrossAttentions or tuple(torch.Tensor)
Параметры
- input_ids (
torch.LongTensorформы(batch_size, sequence_length), , необязательный) — Индексы токенов входной последовательности в словаре. По умолчанию токены отсечки (padding) игнорируются.Индексы можно получить с помощью AutoTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().
- attention_mask (
torch.Tensorформы(batch_size, sequence_length), , необязательный) — Маска для исключения токенов-заполнителей из внимания. Значения маски из диапазона[0, 1]:- 1 для токенов, которые не замаскированы,
- 0 для токенов, которые замаскированы.
- encoder_hidden_states (
torch.Tensorформы(batch_size, sequence_length, hidden_size), необязательный) — Последовательность скрытых состояний на выходе последнего слоя энкодера. Используется в кросс-внимании, если модель настроена как декодер. - encoder_attention_mask (
torch.LongTensorформы(batch_size, sequence_length), , необязательный) — Маска для исключения внимания к индексам токенов заполнения во входных данных энкодера. Эта маска используется в кросс-внимании, если модель настроена как декодер. Значения маски из[0, 1]:- 1 для токенов, которые не замаскированы,
- 0 для токенов, которые замаскированы.
- cache (
~cache_utils.Cache, необязательный) — Предвычисленные скрытые состояния (ключи и значения в блоках self-attention и cross-attention), которые можно использовать для ускорения последовательного декодирования. Обычно этоcache, возвращённый моделью на предыдущем этапе декодирования, когдаuse_cache=Trueилиconfig.use_cache=True.В качестве входного параметра допускается только экземпляр Cache, см. наше руководство по кэшированию KV. Если не переданы
cache, по умолчанию будет инициализирован DynamicCache.Модель будет выводить тот же формат кэша, который был передан на вход.
Если используются
cache, от пользователя ожидается ввод только необработанныхinput_ids(тех, для которых не заданы их прошлые состояния ключей и значений для этой модели) формы(batch_size, unprocessed_length)вместо всехinput_idsформы(batch_size, sequence_length). - inputs_embeds (
torch.Tensorформы(batch_size, sequence_length, hidden_size), необязательный) — При необходимости, вместо передачиinput_idsможно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексыinput_idsпреобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели. - labels (
torch.LongTensorформы(batch_size, sequence_length), необязательный) — Метки для вычисления потерь языковой модели. Индексы должны быть в диапазоне[0, ..., config.vocab_size]или -100 (см.input_idsдокументацию). Токены с индексами, установленными в-100игнорируются (маскируются), потери вычисляются только для токенов с метками в диапазоне[0, ..., config.vocab_size].Метки не сдвигаются внутри модели.
labels[..., i]является целевым значением дляlogits[..., i, :], поэтому для предсказания следующего токена метки должны уже быть сдвинуты на одну позицию влево относительноinput_ids. - use_cache (
bool, необязательный) — Если установлено вTrue, возвращаются состояния ключей и значенийcache, которые можно использовать для ускорения декодирования (см.cache). - output_attentions (
bool, необязательный) — Указывает, следует ли возвращать тензоры внимания всех слоев внимания. Подробности см. в описанииattentionsв разделе возвращаемых тензоров. - output_hidden_states (
bool, необязательный) — Указывает, следует ли возвращать скрытые состояния всех слоев. Подробности см. в описанииhidden_statesсреди возвращаемых тензоров. - return_dict (
bool, необязательный) — Указывает, следует ли возвращать ModelOutput вместо обычного кортежа.
Возвращает
CausalLMOutputWithCrossAttentions или tuple(torch.Tensor)
torch.Tensor (если передано return_dict=False или если config.return_dict=False) или CausalLMOutputWithCrossAttentions, содержащий различные элементы в зависимости от конфигурации (None) и входных данных.
Метод forward класса TrOCRForCausalLM переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
loss (
torch.Tensorформы(1,), необязательный, возвращается, если заданlabels) — Потери языковой модели (для предсказания следующего токена).logits (
torch.Tensorформы(batch_size, sequence_length, config.vocab_size)) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).hidden_states (
tuple(torch.Tensor), optional, возвращается, если переданоoutput_hidden_states=Trueили еслиconfig.output_hidden_states=True) — кортеж изtorch.Tensor(один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы(batch_size, sequence_length, hidden_size).Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
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 внимания, используемые для вычисления взвешенного среднего в головах кросс-внимания.
cache (
Cache, необязательный, возвращается при передачеuse_cache=Trueили когдаconfig.use_cache=True) — это экземпляр Cache. Подробнее см. в нашем руководстве по кэшированию KV.Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках внимания), которые можно использовать (см. вход
cache) для ускорения последовательного декодирования.
Пример:
>>> from transformers import (
... TrOCRConfig,
... TrOCRProcessor,
... TrOCRForCausalLM,
... ViTConfig,
... ViTModel,
... VisionEncoderDecoderModel,
... )
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from PIL import Image
>>> # TrOCR is a decoder model and should be used within a VisionEncoderDecoderModel
>>> # init vision2text model with random weights
>>> encoder = ViTModel(ViTConfig())
>>> decoder = TrOCRForCausalLM(TrOCRConfig())
>>> model = VisionEncoderDecoderModel(encoder=encoder, decoder=decoder)
>>> # If you want to start from the pretrained model, load the checkpoint with `VisionEncoderDecoderModel`
>>> processor = TrOCRProcessor.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")
>>> pixel_values = processor(image, return_tensors="pt").pixel_values
>>> text = "industry, ' Mr. Brown commented icily. ' Let us have a"
>>> # 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
>>> labels = processor.tokenizer(text, return_tensors="pt").input_ids
>>> outputs = model(pixel_values, labels=labels)
>>> loss = outputs.loss
>>> round(loss.item(), 2)
5.30
>>> # inference
>>> generated_ids = model.generate(pixel_values)
>>> generated_text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
>>> generated_text
'industry, " Mr. Brown commented icily. " Let us have a'