Transformers documentation
TrOCR
このモデルは2021年9月21日にHF papersで公開され、2021年10月13日にHugging Face Transformersに貢献されました。
TrOCR
TrOCRは、画像理解とテキスト生成の両方に対応するテキスト認識モデルです。画像処理や文字生成のために個別のモデルを必要としません。TrOCRは、transformerを用いて視覚的理解とテキスト生成を処理する、シンプルな単一のエンドツーエンドシステムです。
すべての元の TrOCR チェックポイントは、Microsoft 組織の下で確認できます。
TrOCR architecture. Taken from the original paper. このモデルは nielsr によって提供されました。
TrOCR モデルの詳細については、右側のサイドバーをクリックしてください。画像やテキストの異なるタスクに TrOCR を適用する方法の例がさらに示されています。
以下の例では、AutoModel クラスを使用して文字認識 (OCR) を実行する方法を示しています。
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)量子化
Quantization は、重みを低精度で表現することで、大規模モデルのメモリ負荷を軽減します。利用可能な Quantization バックエンドの詳細については、Quantization の概要を参照してください。
以下の例では、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 フレームワーク内で使用されます。
リソース
- TrOCRによるドキュメントAIの高速化に関するブログ記事。
- Document AIをTrOCRで実現する方法に関するブログ記事。
- Seq2SeqTrainerを使用してIAM Handwriting DatabaseでTrOCRをファインチューニングする方法を示すノートブック。
- TrOCR 手書き文字認識のインタラクティブデモです。
- TrOCR による推論に関するノートブックと Gradio デモ。
- IAMテストセットでのTrOCRの評価に関するノートブック。
TrOCRConfig
class 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) — デコーダー内の「中間」層（フィードフォワード層と呼ばれることが多い）の次元数。 - 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) — アテンション確率のドロップアウト率です。 - activation_dropout (
Union[float, int]、任意、デフォルトは0.0) — 全結合層内の活性化に対する dropout 率です。 - decoder_start_token_id (
int、任意、デフォルトは2) — エンコーダー・デコーダーモデルがbosとは異なるトークンでデコーディングを開始する場合、そのトークンの ID。 - 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) — 語彙内でパディングに使用されるトークン ID。 - bos_token_id (
int、任意、デフォルトは0) — 語彙におけるストリーム開始に使用されるトークン ID。 - eos_token_id (
Union[int, list[int]]、任意、デフォルトは2) — 語彙内でストリーム終了に使用されるトークン ID。 - 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
class 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.models.trocr.processing_trocr.TrOCRProcessorKwargs'> ) → ~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_tensors (
strまたは TensorType, 省略可) — 設定すると、特定のフレームワークのテンソルを返します。使用可能な値は以下の通りです:'pt': PyTorchのtorch.Tensorオブジェクトを返します。'np': NumPyのnp.ndarrayオブジェクトを返します。
- **kwargs (ProcessingKwargs、任意) — 各モダリティ（テキスト、画像、動画、音声）の追加処理オプション。モデル固有のパラメータは上記にリストされています。サポートされている引数の完全なリストについては、TypedDictクラスを参照してください。
戻り値
~image_processing_base.BatchFeature
- data (
dict) — call メソッド（‘pixel_values’ など）によって返される、リスト/配列/テンソルの辞書。 - tensor_type (
Union[None, str, TensorType]、省略可) — 初期化時に PyTorch/Numpy の Tensor 内の整数リストを変換するために、ここで tensor_type を指定できます。
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) — 次のいずれかです:- 文字列、huggingface.co上のモデルリポジトリにホストされている事前学習済みfeature_extractorのmodel id
- save_pretrained() メソッドを使用して保存されたフィーチャーエクストラクターファイルを含むディレクトリへのパス。例:
./my_model_directory/ - 保存されたフィーチャーエクストラクターの
./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 ファイルとトークナイザーのファイルを保存するディレクトリです（存在しない場合は作成されます）。 - push_to_hub (
bool、省略可、デフォルトはFalse) — モデルを保存した後、Hugging Face モデルハブにプッシュするかどうかを指定します。プッシュ先のリポジトリはrepo_idで指定できます（指定しない場合、save_directoryの名前があなたのネームスペース内でデフォルトとして使用されます）。 - kwargs (
dict[str, Any]、省略可) — push_to_hub() メソッドに渡される追加のキーワード引数。
このプロセッサ（フィーチャーエクストラクター、トークナイザーなど）の属性を指定されたディレクトリに保存し、from_pretrained() メソッドによって再読み込みできるようにします。
このクラスメソッドは、save_pretrained()とsave_pretrained()を呼び出すだけです。詳細については、上記のメソッドのドキュメント文字列を参照してください。
このメソッドは、すべての引数を PreTrainedTokenizer の batch_decode() に転送します。詳細については、このメソッドのドキュメント文字列を参照してください。
このメソッドは、すべての引数を PreTrainedTokenizer の decode() に転送します。詳細については、このメソッドのドキュメント文字列を参照してください。
TrOCRForCausalLM
クラス transformers.TrOCRForCausalLM
< source >( config: TrOCRConfig )
パラメータ
- config (TrOCRConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
言語モデリングヘッドを備えた TrOCR デコーダー。EncoderDecoderModel のデコーダー部分として使用でき、
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、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] = Nonepast_key_values: 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), 、省略可) — 語彙における入力シーケンスのトークンインデックスです。デフォルトではパディングは無視されます。インデックスは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 です。
- past_key_values (
~cache_utils.Cache, 省略可) — 逐次デコードを高速化するために使用できる、事前計算された隠れ状態(自己アテンションブロックおよびクロスアテンションブロックのキーとバリュー)。通常、これはデコードの以前の段階でモデルが返したpast_key_valuesであり、use_cache=Trueまたはconfig.use_cache=True.入力として許可されるのは Cache インスタンスのみです。kv cache ガイドを参照してください。
past_key_valuesが渡されない場合、デフォルトで DynamicCache が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。
past_key_valuesを使用する場合、すべてのinput_ids（形状(batch_size, sequence_length)）ではなく、このモデルに過去のキー・バリュー状態が与えられていない未処理のinput_ids（形状(batch_size, unprocessed_length)）のみを入力することになります。 - inputs_embeds (
torch.Tensor、形状(batch_size, sequence_length, hidden_size)、任意) —input_idsを渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込み参照行列よりも、input_idsのインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。 - labels (
torch.LongTensor、shape(batch_size, sequence_length)、任意) — マスク言語モデリング損失を計算するためのラベルです。インデックスは[0, ..., config.vocab_size]の範囲内であるか、-100 である必要があります（input_idsの docstring を参照）。インデックスが-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 を返すかどうかを指定します。詳細は、返されるテンソルのhidden_statesを参照してください。 - return_dict (
bool, 任意) — プレーンなタプルではなく ModelOutput を返すかどうか。
戻り値
CausalLMOutputWithCrossAttentions または tuple(torch.Tensor)
torch.Tensor のタプル（return_dict=False が渡された場合、または config.return_dict=False の場合）または CausalLMOutputWithCrossAttentions。設定（TrOCRConfig）と入力に応じて、さまざまな要素で構成されます。
TrOCRForCausalLMのforwardメソッドは、__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のタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は(batch_size, sequence_length, hidden_size)です。各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
attentions (
tuple(torch.Tensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返されます) —torch.Tensorのタプル（各レイヤーごとに1つ）、形状は(batch_size, num_heads, sequence_length, sequence_length)。アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
cross_attentions (
tuple(torch.Tensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返されます)—torch.Tensorのタプル（各レイヤーごとに1つ）、形状は(batch_size, num_heads, sequence_length, sequence_length)です。アテンションのsoftmax後のクロスアテンションの重み。クロスアテンションヘッドにおける加重平均の計算に使用されます。
past_key_values (
Cache、任意、use_cache=Trueが渡された場合またはconfig.use_cache=Trueの場合に返されます) — Cache のインスタンスです。詳細については、kv cache ガイドを参照してください。シーケンシャルなデコーディングを高速化するために使用できる（
past_key_values入力参照）、事前計算済みの hidden-states（アテンションブロック内のキーとバリュー）が含まれます。
例:
>>> 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'