Transformers documentation
UVDoc
このモデルは2026年3月21日にHugging Face Transformersに貢献されました。
UVDoc
概要
UVDoc テキスト画像補正の主な目的は、画像に対して幾何学的変換を適用し、文書の歪み、傾き、透視変形などの問題を修正することです。
使用方法
単一入力推論
以下の例では、AutoImageProcessorとUVDocModelを使用してUVDocで文書画像を補正する方法を示しています。
import requests
from PIL import Image
from transformers import AutoImageProcessor, AutoModel
model_path = "PaddlePaddle/UVDoc_safetensors"
model = AutoModel.from_pretrained(
model_path,
device_map="auto",
)
image_processor = AutoImageProcessor.from_pretrained(model_path)
image = Image.open(requests.get("https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/paddle_doc_test.jpg", stream=True).raw)
inputs = image_processor(images=image, return_tensors="pt").to(model.device)
outputs = model(**inputs)
result = image_processor.post_process_document_rectification(outputs.last_hidden_state, inputs["original_images"])
print(result)バッチ推論
UVDoc を用いたバッチド文書補正の実行方法は以下の通りです。
import requests
from PIL import Image
from transformers import AutoImageProcessor, AutoModel
model_path = "PaddlePaddle/UVDoc_safetensors"
model = AutoModel.from_pretrained(
model_path
device_map="auto",
)
image_processor = AutoImageProcessor.from_pretrained(model_path)
image = Image.open(requests.get("https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/paddle_doc_test.jpg", stream=True).raw)
inputs = image_processor(images=[image, image], return_tensors="pt").to(model.device)
outputs = model(**inputs)
result = image_processor.post_process_document_rectification(outputs.last_hidden_state, inputs["original_images"])
print(result)UVDocConfig
class transformers.UVDocConfig
< 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 = Nonebackbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonehidden_act: str = 'prelu'padding_mode: str = 'reflect'kernel_size: int = 5bridge_connector: list[int] | tuple[int, ...] = (128, 128)out_point_positions2D: Sequence = ((128, 32), (32, 2)) )
パラメータ
- backbone_config (
Union[dict, ~configuration_utils.PreTrainedConfig], 任意) — バックボーンモデルの設定です。 - hidden_act (
str、任意、デフォルトはprelu) — デコーダーで使用する非線形活性化関数（関数または文字列）です。例えば、"gelu"、"relu"、"silu"などです。 - padding_mode (
str、任意、デフォルトは"reflect") — 畳み込み層のパディングモード。サポートされているモードは"reflect"、"constant"、"replicate"です。 - kernel_size (
int、任意、デフォルトは 5) — バックボーンネットワークの畳み込み層におけるカーネルサイズ。 - bridge_connector (
list[int] | tuple[int, ...]、任意、デフォルトは(128, 128)) — ブリッジコネクタの設定。[in_channels, out_channels] の形式で指定します。 - out_point_positions2D (
Sequence[list[int] | tuple[int, ...]]、任意、デフォルトは((128, 32), (32, 2))) — 出力点位置2Dレイヤーの設定。形式は [in_channels, out_channels] です。
これは UVDocModel の設定を保存するための設定クラスです。指定された引数に基づいて Uvdoc モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、PaddlePaddle/UVDoc_safetensors と同様の設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
UVDocModel
class transformers.UVDocModel
< source >( config: UVDocConfig )
パラメータ
- config (UVDocConfig) — モデルのすべてのパラメータを含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
モデルは生ドキュメント画像（ピクセル値）を入力として受け取り、UVDocバックボーンを通じて空間変換パラメータを予測し、補正（リファイン）されたドキュメント画像テンソルを出力します。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
forward
< source >( pixel_values: FloatTensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithNoAttention or tuple(torch.FloatTensor)
パラメータ
- pixel_values (
torch.FloatTensor、shape(batch_size, num_channels, image_size, image_size)) — 入力画像に対応するテンソルです。ピクセル値は UVDocImageProcessor を使用して取得できます。詳細については UVDocImageProcessor.call() を参照してください（processor_classは画像の処理に UVDocImageProcessor を使用します）。
戻り値
BaseModelOutputWithNoAttention または tuple(torch.FloatTensor)
BaseModelOutputWithNoAttention または、return_dict=False が渡された場合、または config.return_dict=False の場合、torch.FloatTensor のタプル。設定（UVDocConfig）や入力に応じて、さまざまな要素で構成されます。
UVDocModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
last_hidden_state (
torch.FloatTensor、shape(batch_size, num_channels, height, width)) — モデルの最終層の出力における隠れ状態のシーケンス。hidden_states (
tuple(torch.FloatTensor)、optional、output_hidden_states=Trueが渡された場合またはconfig.output_hidden_states=Trueの場合に返される) —torch.FloatTensorのタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は(batch_size, num_channels, height, width)です。各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
UVDocBackboneConfig
クラス transformers.UVDocBackboneConfig
< 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 = None_out_features: list[str] | None = None_out_indices: list[int] | None = Noneresnet_head: Sequence = ((3, 32), (32, 32))resnet_configs: Sequence = (((32, 32, 1, False), (32, 32, 3, False), (32, 32, 3, False)), ((32, 64, 1, True), (64, 64, 3, False), (64, 64, 3, False), (64, 64, 3, False)), ((64, 128, 1, True), (128, 128, 3, False), (128, 128, 3, False), (128, 128, 3, False), (128, 128, 3, False), (128, 128, 3, False)))stage_configs: Sequence = (((128, 1),), ((128, 2),), ((128, 5),), ((128, 8), (128, 3), (128, 2)), ((128, 12), (128, 7), (128, 4)), ((128, 18), (128, 12), (128, 6)))kernel_size: int = 5 )
パラメータ
- resnet_head (
Sequence[list[int] | tuple[int, ...]]、任意、デフォルトは((3, 32), (32, 32))) — ResNet ヘッド層の設定。形式は [in_channels, out_channels] です。 - resnet_configs (
Sequence[Sequence[tuple[int, int, int, bool] | list[int | bool]]]、optional、デフォルトは(((32, 32, 1, False), -- (32, 32, 3, False), (32, 32, 3, False)), ((32, 64, 1, True), (64, 64, 3, False), (64, 64, 3, False), (64, 64, 3, False)), ((64, 128, 1, True), (128, 128, 3, False), (128, 128, 3, False), (128, 128, 3, False), (128, 128, 3, False), (128, 128, 3, False)))): ResNet の各ステージの設定です。形式は [in_channels, out_channels, dilation_value, downsample] です。 - stage_configs (
Sequence[Sequence[tuple[int, …] | list[int]]], 任意、デフォルトは(((128, 1),), ((128, 2),), -- ((128, 5),), ((128, 8),(128, 3),(128, 2),), ((128, 12), (128, 7), (128, 4),), ((128, 18), (128, 12), (128, 6),),)): ブリッジモジュールの各ステージの設定を、[in_channels, dilation_value] の形式で指定します。 内側のシーケンスは 1 つのブリッジブロックに対応し、外側のシーケンスはブリッジステージごとにブロックをグループ化します。 - kernel_size (
int、任意、デフォルトは5) — 畳み込みカーネルのサイズです。
これは UVDocModel の設定を保存するための設定クラスです。指定された引数に基づいて Uvdoc モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、PaddlePaddle/UVDoc_safetensors と同様の設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
UVDocBackbone
class transformers.UVDocBackbone
< source >( config: UVDocBackboneConfig )
パラメータ
- config (UVDocBackboneConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
特徴量抽出用のUVDocバックボーンモデル。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
forward
< source >( pixel_values: FloatTensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BackboneOutput or tuple(torch.FloatTensor)
パラメータ
- pixel_values (
torch.FloatTensor、shape(batch_size, num_channels, image_size, image_size)) — 入力画像に対応するテンソルです。ピクセル値は UVDocImageProcessor を使用して取得できます。詳細は UVDocImageProcessor.call() を参照してください（processor_classは画像の処理に UVDocImageProcessor を使用します）。
戻り値
BackboneOutput または tuple(torch.FloatTensor)
BackboneOutput、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（UVDocConfig）と入力に応じて、さまざまな要素で構成されます。
UVDocBackboneのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
feature_maps (
tuple(torch.FloatTensor)、形状(batch_size, num_channels, height, width)) — 各ステージのフィーチャマップ。hidden_states (
tuple(torch.FloatTensor)、任意、output_hidden_states=Trueが渡された場合またはconfig.output_hidden_states=Trueの場合に返されます)—torch.FloatTensorのタプル（埋め込みの出力用 1 つ + 各層の出力用 1 つ）。形状は(batch_size, sequence_length, hidden_size)または(batch_size, num_channels, height, width)で、バックボーンによって異なります。各ステージの出力におけるモデルのHidden-states、および初期の埋め込み出力。
attentions (
tuple(torch.FloatTensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返される) —torch.FloatTensorのタプル（レイヤーごとに1つ）、形状は(batch_size, num_heads, sequence_length, sequence_length)。バックボーンがアテンションを使用する場合にのみ適用されます。アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
UVDocBridge
UVDocImageProcessor
クラス transformers.UVDocImageProcessor
< source >( **kwargs: *<class 'transformers.processing_utils.ImagesKwargs'> )
パラメータ
- do_convert_rgb (
bool、kwargs、任意) — 画像を RGB に変換するかどうかを指定します。 - do_resize (
bool、kwargs、任意、デフォルトはTrue) — 画像をリサイズするかどうか。 - size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs、デフォルトは{'height' -- 712, 'width': 488}): モデルへの最大入力サイズを指定します。 - default_to_square (
bool、kwargs、任意、デフォルトはTrue) — size が int の場合、リサイズ時に正方形の画像をデフォルトとするかどうかを指定します。 - crop_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) —center_cropを適用した後の出力画像のサイズ。 - resample (
Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, デフォルトは2) — 画像のリサイズ時に使用するリサンプリングフィルタです。PILImageResamplingの列挙型のいずれかを使用できます。do_resizeがTrueに設定されている場合のみ、効果が現れます。 - do_rescale (
bool、kwargs、任意、デフォルトはTrue) — 画像をリスケールするかどうかを指定します。 - rescale_factor (
float、kwargs、任意、デフォルト値は0.00392156862745098) —do_rescaleがTrueに設定されている場合、画像をリスケールするための係数です。 - do_normalize (
bool, kwargs, optional) — 画像を正規化するかどうかを指定します。 - image_mean (
Union[float, list[float], tuple[float, ...]]、kwargs、optional) — 正規化に使用する画像の平均値。do_normalizeがTrueに設定されている場合のみ有効です。 - image_std (
Union[float, list[float], tuple[float, ...]], kwargs, optional) — 正規化に使用する画像の標準偏差。do_normalizeがTrueに設定されている場合のみ有効です。 - do_pad (
bool, kwargs, optional) — 画像をパディングするかどうかを指定します。パディングは、バッチ内の最大サイズに合わせるか、画像ごとに固定の正方形サイズに合わせるかのいずれかで行われます。具体的なパディング戦略はモデルによって異なります。 - pad_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 画像をパディングする{"height": int, "width" int}のサイズです。前処理に提供されるすべての画像サイズより大きくなければなりません。pad_sizeが指定されない場合、バッチ内の最大の幅と高さにパディングされます。do_pad=True.の場合のみ適用されます。 - do_center_crop (
bool, kwargs, optional) — 画像を中央クロップするかどうかを指定します。 - data_format (
Union[str, ~image_utils.ChannelDimension]、kwargs、任意) — サポートされているのはChannelDimension.FIRSTのみです。slow processors との互換性のために追加されました。 - input_data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 省略可) — 入力画像のチャネル次元の形式です。設定されていない場合、入力画像からチャネル次元の形式が推測されます。次のいずれかになります:"channels_first"またはChannelDimension.FIRST: (num_channels, height, width) 形式の画像。"channels_last"またはChannelDimension.LAST: (高さ, 幅, チャネル数) 形式の画像。"none"またはChannelDimension.NONE: (height, width) 形式の画像。
- device (
Annotated[Union[str, torch.device, NoneType], None], kwargs) — 動画を処理するデバイスです。未設定の場合、入力動画からデバイスが推論されます。 - return_tensors (
Annotated[str | ~utils.generic.TensorType | None, None], kwargs) —'pt'に設定されている場合はスタックされたテンソルを返し、それ以外の場合はテンソルのリストを返します。 - disable_grouping (
bool、kwargs、任意) — サイズごとに画像をグループ化してバッチ処理するのではなく、個別に処理するためにグループ化を無効にするかどうか。None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている経験則に基づいています。 - image_seq_length (
int、kwargs、任意) — 入力内の各画像に使用される画像トークンの数です。 後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。'pt'に設定されている場合はスタックされたテンソルを返し、それ以外の場合はテンソルのリストを返します。 - disable_grouping (
bool、kwargs、任意) — サイズごとに画像をグループ化してバッチ処理するのではなく、個別に処理するためにグループ化を無効にするかどうか。None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている経験則に基づいています。 - image_seq_length (
int、kwargs、任意) — 入力内の各画像に使用される画像トークンの数です。 後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。'pt'に設定されている場合はスタックされたテンソルを返し、それ以外の場合はテンソルのリストを返します。 - disable_grouping (
bool、kwargs、任意) — サイズごとに画像をグループ化してバッチ処理するのではなく、個別に処理するためにグループ化を無効にするかどうか。None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている経験則に基づいています。 - image_seq_length (
int、kwargs、任意) — 入力内の各画像に使用される画像トークンの数です。 後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。'pt'に設定されている場合はスタックされたテンソルを返し、それ以外の場合はテンソルのリストを返します。 - disable_grouping (
bool、kwargs、任意) — サイズごとに画像をグループ化してバッチ処理するのではなく、個別に処理するためにグループ化を無効にするかどうか。None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている経験則に基づいています。 - image_seq_length (
int、kwargs、任意) — 入力内の各画像に使用される画像トークンの数です。 後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。'pt'に設定されている場合はスタックされたテンソルを返し、それ以外の場合はテンソルのリストを返します。 - disable_grouping (
bool、kwargs、任意) — サイズごとに画像をグループ化してバッチ処理するのではなく、個別に処理するためにグループ化を無効にするかどうか。None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている経験則に基づいています。 - image_seq_length (
int、kwargs、任意) — 入力内の各画像に使用される画像トークンの数です。 後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。'pt'に設定されている場合はスタックされたテンソルを返し、それ以外の場合はテンソルのリストを返します。 - disable_grouping (
bool、kwargs、任意) — サイズごとに画像をグループ化してバッチ処理するのではなく、個別に処理するためにグループ化を無効にするかどうか。None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている経験則に基づいています。 - image_seq_length (
int、kwargs、任意) — 入力内の各画像に使用される画像トークンの数です。 後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。'pt'に設定されている場合はスタックされたテンソルを返し、それ以外の場合はテンソルのリストを返します。 - disable_grouping (
bool、kwargs、任意) — サイズごとに画像をグループ化してバッチ処理するのではなく、個別に処理するためにグループ化を無効にするかどうか。None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている経験則に基づいています。 - image_seq_length (
int、kwargs、任意) — 入力内の各画像に使用される画像トークンの数です。 後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。'pt'に設定されている場合はスタックされたテンソルを返し、それ以外の場合はテンソルのリストを返します。 - disable_grouping (
bool、kwargs、任意) — サイズごとに画像をグループ化してバッチ処理するのではなく、個別に処理するためにグループ化を無効にするかどうか。None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている経験則に基づいています。 - image_seq_length (
int、kwargs、任意) — 入力内の各画像に使用される画像トークンの数です。 後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。 - Returns が
'pt'に設定されている場合はスタックされたテンソルを、それ以外の場合はテンソルのリストを返します。 —
UVDocImageProcessorの画像プロセッサを構築します。
disable_grouping (bool, kwargs, optional):
サイズによる画像のグループ化を無効にし、バッチ処理ではなく個別に処理するかどうかを指定します。
None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている実証的な観察に基づいています。
image_seq_length (int, kwargs, optional):
入力内の各画像に使用される画像トークンの数です。
後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。
post_process_document_rectification
< source >( prediction: Tensororiginal_images: listscale: float = 255.0 ) → List of dictionaries containing rectified images. Each dictionary has
文書補正の予測結果を後処理し、補正済み画像に変換します。