Hugging Face's logo

Transformers documentation

モデル

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

モデル

ベースクラス PreTrainedModel は、ローカルファイルまたはディレクトリから、あるいはライブラリが提供する事前学習モデルの設定（HuggingFace の Hub からダウンロード）からモデルを読み込み/保存するための共通メソッドを実装しています。

PreTrainedModel は、すべてのモデルで共通の以下のいくつかのメソッドを実装しています。

  • 語彙に新しいトークンが追加された場合、入力トークン埋め込みをリサイズします

各モデルに共通するその他のメソッドは、ModuleUtilsMixinとGenerationMixinで定義されています。

PreTrainedModel

class transformers.PreTrainedModel

< >

( config: PreTrainedConfig*inputs**kwargs )

すべてのモデルの基底クラス。

PreTrainedModel は、モデルの構成の保存を管理し、モデルの読み込み、ダウンロード、保存の処理を行うほか、すべてのモデルに共通するいくつかのメソッドを提供します。

  • 入力埋め込みをリサイズする

クラス属性（派生クラスによって上書きされます）:

  • config_class (PreTrainedConfig) — このモデルアーキテクチャの構成クラスとして使用する PreTrainedConfig のサブクラス
  • base_model_prefix (str) — 同一アーキテクチャの派生クラスにおいて、ベースモデルの上にモジュールを追加する場合、ベースモデルに関連付けられた属性を示す文字列。
  • main_input_name (str) — モデルの主な入力の名前（NLPモデルでは通常input_ids、ビジョンモデルではpixel_values、音声モデルではinput_values）。
  • can_record_outputs (dict):

push_to_hub

< >

( repo_id: strcommit_message: str | None = Nonecommit_description: str | None = Noneprivate: bool | None = Nonetoken: bool | str | None = Nonerevision: str | None = Nonecreate_pr: bool = Falsemax_shard_size: int | str | None = '50GB'tags: list[str] | None = None )

パラメータ

  • repo_id (str) — モデルをプッシュするリポジトリの名前です。特定の組織にプッシュする場合は、組織名を含む必要があります。
  • commit_message (str, 省略可) — プッシュ時にコミットするメッセージ。デフォルトは "Upload model" です。
  • commit_description (str, 省略可) — 作成されるコミットの説明
  • private (bool、省略可) — リポジトリを非公開にするかどうか。None（デフォルト）の場合、組織のデフォルトが非公開でない限り、リポジトリは公開になります。リポジトリが既に存在する場合、この値は無視されます。
  • token (bool または str、省略可) — リモートファイルの HTTP ベアラ認証に使用するトークン。True（デフォルト）の場合、hf auth login を実行した際に生成されたトークン（~/.huggingface に保存）が使用されます。
  • revision (str、省略可) — アップロードしたファイルをプッシュするブランチ。
  • create_pr (bool、省略可、デフォルトはFalse) — アップロードしたファイルを含む PR を作成するか、直接コミットするかどうかを指定します。
  • max_shard_size (int または str、省略可能、デフォルトは "50GB") — モデルにのみ適用されます。シャード化される前のチェックポイントの最大サイズです。シャード化されたチェックポイントは、それぞれがこのサイズ未満になります。文字列で指定する場合は、数字の後に単位（"5MB" など）を続ける必要があります。
  • tags (list[str]、省略可) — Hub にプッシュするタグのリストです。

モデルファイルを🤗 Model Hubにアップロードします。

例:

from transformers import AutoModel

model = AutoModel.from_pretrained("google-bert/bert-base-cased")

# Push the model to your namespace with the name "my-finetuned-bert".
model.push_to_hub("my-finetuned-bert")

# Push the model to an organization with the name "my-finetuned-bert".
model.push_to_hub("huggingface/my-finetuned-bert")

activation_checkpointing_disable

< >

( )

現在のモデルのアクティベーションチェックポイントを無効にします。

activation_checkpointing_enable

< >

( activation_checkpointing_kwargs = Noneevery_n_layers: int = 1offload: bool = False )

パラメータ

  • every_n_layers (int、省略可、デフォルト値は 1)— every_n_layers 層ごとにデコーダー層のチェックポイントのみを保存し、その他の層はアクティベーションを保持したままにします。 1 を指定するとすべての層でチェックポイントが行われ、これは通常の一括処理（オールオアナッシング）の動作です。より大きな値を指定すると、メモリを速度と引き換えに節約できます。フルチェックポイントによって解放されるメモリが未使用のままになる場合は、このトレードオフが有効です。
  • offload (bool、任意、デフォルトは False) — 再計算用に保存されるアクティベーションを、アクセラレーター上ではなく、ピン留めされたホストメモリに保持します。これにより、layers x sequence x hidden バイトのデバイスメモリが解放されます。長いシーケンス長ではこれが支配的な要因となりますが、フォワードパスでデバイスからホストへのコピー、バックワードパスでホストからデバイスへのコピーが発生します。これらのコピーはどちらもコンピュートストリーム上で実行されるため、ステップの速度が低下します。
  • activation_checkpointing_kwargs (dict, 任意) — torch.utils.checkpoint.checkpoint 関数に渡す追加のキーワード引数。

現在のモデルに対してアクティベーション・チェックポイントを有効にします。

モジュールの __call__ メソッドを forward の代わりに渡すのは、__call__ がモジュールのすべてのフックをアタッチするからです。https://discuss.pytorch.org/t/any-different-between-model-input-and-model-forward-input/3690/2

add_model_tags

< >

( tags: list[str] | str )

パラメータ

  • tags (Union[list[str], str]) — モデルに注入する対象のタグ

Hugging Face Hub にプッシュされるモデルにカスタムタグを追加します。モデルに既存のタグがある場合は、それらを上書きしません。

例:

from transformers import AutoModel

model = AutoModel.from_pretrained("google-bert/bert-base-cased")

model.add_model_tags(["custom", "custom-bert"])

# Push the model to your namespace with the name "my-custom-bert".
model.push_to_hub("my-custom-bert")

can_generate

< >

( ) → bool

戻り値

bool

このモデルが.generate()でシーケンスを生成できるかどうか。

.generate()、またはそれに類似したインターフェースを持つ GenerationMixin を介してシーケンスを生成できるかどうかを返します。

内部では、この関数が True を返すクラスでは、生成に固有の変更がトリガーされます。 例えば、モデルインスタンスには設定済みの generation_config 属性が設定されます。

cuda

( *args**kwargs )

ドット区切りパス（例: torch.float32）のモック値: 属性アクセスのチェーン、呼び出しはパススルーデコレータとして動作し、repr はドット区切りパスを返し、ベースクラスとして使用するとプレーンな type ベースに置き換えられます（PEP 560 の __mro_entries__）。これにより、実際のサブクラスは通常のメタクラスを保持し、inspect.signature はモックの __init__ ではなく、実際の __init__ を読み取ります。

dequantize

< >

( dtype = None )

量子化手法によって量子化されている場合、デクォンタイズをサポートしている場合は、モデルをデクォンタイズする可能性があります。

disable_input_require_grads

< >

( )

_require_grads_hookを削除します。

enable_input_require_grads

< >

( )

入力埋め込みの勾配を有効にします。モデルの重みを固定したまま、アダプター重みのファインチューニングを行う場合に便利です。

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLike | None*model_argsconfig: transformers.configuration_utils.PreTrainedConfig | str | os.PathLike | None = Nonecache_dir: str | os.PathLike | None = Noneignore_mismatched_sizes: bool = Falseforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'use_safetensors: bool | None = Noneweights_only: bool = Truefusion_config: dict[str, bool | dict[str, typing.Any]] | None = Nonedisable_mmap: bool | None = None**kwargs )

パラメータ

  • pretrained_model_name_or_path (str または os.PathLike, 省略可) — 以下のいずれかです:
    • huggingface.co のモデルリポジトリにホストされている事前学習済みモデルの model id を示す文字列。
    • ディレクトリへのパス。このディレクトリには、save_pretrained()を使用して保存されたモデルの重みが含まれます。例: ./my_model_directory/。save_pretrained(..., distributed_checkpoint=True)で保存されたディレクトリは検出され、分散チェックポイント（DCP）によって読み込まれます。これにより、モデルの現在のメッシュと配置が保持されます。この機能にはtorch>=2.7が必要であり、厳密な読み込みが行われます。つまり、すべてのモデルキーがチェックポイントに存在する必要があります。
    • None は、設定と状態辞書の両方を提供する場合（それぞれキーワード引数 config と state_dict を使用する場合）です。
  • model_args (位置引数のシーケンス、任意) — 残りのすべての位置引数は、基盤となるモデルの __init__ メソッドに渡されます。
  • config (Union[PreTrainedConfig, str, os.PathLike], 省略可) — 以下のいずれかです:

    自動読み込みされる設定の代わりに使用するモデルの設定。設定は、次の場合に自動読み込みされます:

    • モデルは、ライブラリによって提供されるモデルです（事前学習済みモデルのmodel id文字列で読み込まれます）。
    • モデルはsave_pretrained()を使用して保存されており、保存ディレクトリを指定することで再読み込みされます。
    • モデルは、ローカルディレクトリをpretrained_model_name_or_pathとして指定して読み込まれ、そのディレクトリ内にconfig.jsonという名前の設定JSONファイルが見つかった場合です。
  • state_dict (dict[str, torch.Tensor], 省略可) — 保存された重みファイルから読み込まれる state dictionary の代わりに使用する state dictionary。事前学習済みの設定からモデルを作成しつつ、独自の重みをロードしたい場合にこのオプションを使用できます。ただし、この場合は save_pretrained() と from_pretrained() を使用した方がよりシンプルな方法ではないかを確認することをお勧めします。

    このオプションは、事前学習済みの設定からモデルを作成しつつ、独自の重みをロードしたい場合に使用できます。ただし、この場合は、save_pretrained()とfrom_pretrained()を使用する方がよりシンプルな方法ではないかを確認することをお勧めします。

  • cache_dir (Union[str, os.PathLike], 任意) — 標準のキャッシュを使用しない場合、ダウンロードした事前学習済みモデルの構成をキャッシュするディレクトリのパス。
  • ignore_mismatched_sizes (bool、任意、デフォルトはFalse) — チェックポイントの重みの一部がモデルの重みとサイズが異なる場合（例えば、3ラベルのチェックポイントから10ラベルのモデルをインスタンス化する場合など）に、エラーを発生させるかどうかを指定します。
  • force_download (bool、任意、デフォルトは False) — モデルの重みと設定ファイルを（再）ダウンロードを強制するかどうか。キャッシュされたバージョンが存在する場合でも、それを上書きします。
  • proxies (dict[str, str]、省略可) — プロトコルまたはエンドポイントごとに使用するプロキシサーバーの辞書です。例: {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}。各リクエストでこれらのプロキシが使用されます。
  • output_loading_info(bool, optional, デフォルトは False) — 欠落キー、予期しないキー、エラーメッセージを含む辞書を返すかどうかを指定します。
  • local_files_only(bool, 任意、デフォルトは False) — ローカルファイルのみを対象とするかどうか（モデルのダウンロードを試みないかどうか）。
  • token (str または bool、省略可) — リモートファイルの HTTP ベアラ認証に使用するトークンです。True の場合、または指定されていない場合は、hf auth login を実行した際に生成されたトークン（~/.huggingface に保存）が使用されます。
  • revision (str, 省略可, デフォルトは "main") — 使用する特定のモデルのバージョンです。huggingface.co ではモデルやその他の成果物を保存するために git ベースのシステムを使用しているため、ブランチ名、タグ名、またはコミット ID を指定できます。したがって、 revision には git で許可される任意の識別子を指定できます。

    Hub で作成した pull request をテストするには、revision="refs/pr/<pr_number>" を渡すことができます。

  • attn_implementation (str, 省略可) — モデルで使用されるアテンションの実装（関連する場合）。

    以下の形式の HF カーネル参照を受け入れます:

    /[@][:]
    • とは、"/"および":"以外の任意の文字列です。
    • “@”は任意です（ブランチ、タグ、またはコミット）。例: “@main”、“@v1.2.0”、“@abc123”。
    • ”:” は省略可能で、カーネルリポジトリ内の関数を選択します。
    • 両方のオプションは、@revisionが先、:kernel_nameが後という順序で同時に出現する場合があります。
    • 先頭にある「|」プレフィックス（例: “flash|…”）を意図的に許可しています。これは、コードが読み込み前にこれを除去するためです。ここでは、文字クラス内で「|」は除外されていません。

    一致する例: “org/model” “org/model@main” “org/model:custom_kernel” “org/model@v1.2.3:custom_kernel”

  • experts_implementation (str, 省略可) — モデルで使用するエキスパートの実装（関連する場合）。以下のいずれかを指定できます:

    デフォルトでは、モデルがサポートしている場合、"grouped_mm" が使用されます。サポートされていない場合のデフォルトは、手動の "eager" 実装です。

大規模モデル推論のパラメータ

  • dtype (str または torch.dtype, 省略可能, デフォルトは "auto") — デフォルトの torch_dtype をオーバーライドし、特定の dtype. のオプションは以下の通りです。

    1. torch.float16 または torch.bfloat16 または torch.float: 指定された dtype で読み込みます。モデルに config.dtype が存在する場合でも無視します。指定されない場合

      • モデルはtorch.float(fp32)で読み込まれます。

    2. "auto" - モデルの config.json ファイル内の dtype または torch_dtype エントリが使用されるよう試行されます。このエントリが見つからない場合は、チェックポイント内の最初の浮動小数点型の重みの dtype を確認し、それを dtype として使用します。これにより、モデルはトレーニング終了時に保存された dtype で読み込まれます。ただし、これはモデルがどのようにトレーニングされたかを示す指標としては使用できません。半精度の dtype でトレーニングされたものの、fp32 で保存されている場合があるためです。

    3. torch.dtype として有効な文字列。例えば、“float32” はモデルを torch.float32 で読み込み、“float16” は torch.float16 で読み込む、などです。

    一部のモデルでは、学習時に使用されたdtypeが不明な場合があります。その場合は、モデルの論文を確認するか、著者に連絡して、モデルカードにこの情報を追加し、ハブ上のconfig.jsonにdtypeまたはtorch_dtypeエントリを挿入してもらうことを検討してください。

  • device_map (str または dict[str, Union[int, str, torch.device]] または int または torch.device, 省略可) — 各サブモジュールをどのデバイスに配置するかを指定するマップです。パラメータやバッファの名前ごとに細かく指定する必要はなく、特定のモジュール名が指定された場合、そのモジュールのすべてのサブモジュールが同じデバイスに送信されます。デバイスのみを渡す場合（e.g., "cpu", "cuda:1", "mps", または、モデルが割り当てられる GPU の ordinal rank、例えば 1) ）、デバイスマップはモデル全体をそのデバイスにマッピングします。 device_map = 0 を渡すと、モデル全体を GPU 0 に配置することを意味します。Accelerate が最も最適化された device_map を自動的に計算するには、device_map="auto" を設定してください。各オプションの詳細については、デバイスマップの設計を参照してください。

    Accelerate が最も最適化された device_map を自動的に計算するようにするには、device_map="auto" を設定します。各オプションの詳細については、デバイスマップの設計を参照してください。

  • max_memory (Dict, 任意) — device_map を使用する場合、デバイス識別子から最大メモリ量への辞書です。未設定の場合、各 GPU の利用可能な最大メモリと、利用可能な CPU RAM がデフォルトとして使用されます。
  • distributed_config (DistributedConfig、任意) — テンソル並列または FSDP2 を用いたネイティブな分散ロードの設定です。 DistributedConfig(tp_size=N) を渡すことでモデルに定義済みのテンソル並列プランを使用し、 DistributedConfig(tp_plan=...) を渡すことでテンソル並列プランを指定し、 DistributedConfig(fsdp_size=N) を渡すことで FSDP2 を使用します。 tp_size > 1 または fsdp_size > 1 の場合、torchrun と初期化済みのプロセスグループが必要です。 device_map とは排他的です。
  • device_mesh (torch.distributed.DeviceMesh、任意) — torch のデバイスメッシュです。指定しない場合、デフォルトでワールドサイズが使用されます。現時点ではテンソル並列にのみ使用されます。 指定する場合、次元が 1 以上の場合には、"tp" という名前の次元を含む必要があります。この次元がテンソル並列に使用されます。
  • offload_folder (str または os.PathLike、省略可) — device_map に "disk" という値が含まれている場合、重みをオフロードするフォルダを指定します。
  • offload_buffers (bool、任意) — モデルパラメータのバッファをオフロードするかどうかを指定します。
  • quantization_config (Union[QuantizationConfigMixin,Dict], 任意) — 量子化の設定パラメータの辞書、または量子化用の QuantizationConfigMixin オブジェクト（例: bitsandbytes、gptq）。
  • subfolder (str、任意、デフォルトは "") — huggingface.co 上のモデルリポジトリのサブフォルダ内に該当するファイルが配置されている場合、ここにフォルダ名を指定できます。
  • variant (str, 任意) — 指定した場合、variant ファイル名から重みをロードします。例 pytorch_model..bin.
  • use_safetensors (bool、任意、デフォルトはNone) — safetensorsチェックポイントを使用するかどうか。デフォルトはNoneです。指定されず、かつsafetensorsがインストールされていない場合、Falseに設定されます。
  • weights_only (bool、省略可能、デフォルトは True) — unpickler がテンソル、プリミティブ型、辞書、および torch.serialization.add_safe_globals() 経由で追加された型のみを読み込むように制限されるかどうかを示します。 False に設定すると、ラッパーのテンソルサブクラスの重みを読み込むことができます。
  • disable_mmap (bool, 省略可) — safetensors チェックポイントを読み込む際にメモリマッピングを無効にするかどうか。None（デフォルト）の場合、チェックポイントが hf-mount FUSE ファイルシステム（HF Spaces/Endpoints で使用）上に存在すると、mmap と並列ページフォールトがデッドロックを引き起こし得るため、自動的に True に設定されます。True の場合、ファイルを完全にメモリへ読み込み、safetensors.torch.load で解析します。False の場合、常にデフォルトのメモリマップドローダーが使用されます。
  • fusion_config (dict[str, bool | dict[str, Any]], 省略可) — モデルのインスタンス化の前に適用される任意のフュージョン設定です。各キーはフュージョンファミリーを有効化し、その値はデフォルトのオプションでそのフュージョンを有効にする True または、ファミリー固有のオプションの辞書のいずれかです。例えば、{"patch_embeddings": True} はパッチ埋め込みのフュージョンを有効にします。これは出力がわずかに変化し得るため、推論の最適化としてのみ使用すべきです。省略した場合、from_pretrained() は利用可能な場合に config.fusion_config にフォールバックします。詳細については、docs/source/en/fusion_mapping.md のフュージョンマッピングガイドを参照してください。
  • key_mapping (`dict[str, str], optional) — Hub 上で Transformers アーキテクチャと互換性のあるモデルを使用する場合、重み名称の潜在的なマッピングです。ただし、適切に変換されていない場合に限ります。
  • kwargs (残りのキーワード引数の辞書、 省略可) — 設定オブジェクト（読み込み後）を更新し、モデルを初期化するために使用できます（例： output_attentions=True). が提供されるかどうかによって動作が異なります： config config で設定が提供されている場合、**kwargs は基盤となるモデルの __init__ メソッドに直接渡されます（設定への関連する更新はすべて完了しているものと仮定します）。設定が提供されていない場合、kwargs はまず設定クラスの初期化関数（from_pretrained()）に渡されます。kwargs の各キーが設定属性に対応している場合、その属性は指定された kwargs の値で上書きされます。設定属性に対応しない残りのキーは、基盤となるモデルの __init__ 関数に渡されます。
    • config で設定が提供されている場合、**kwargs は、基盤となるモデルの __init__ メソッドに直接渡されます（設定への関連するすべての更新がすでに完了しているものと仮定しています）。
    • 設定が提供されない場合、kwargs はまず設定クラスの初期化関数 (from_pretrained()) に渡されます。kwargs の各キーのうち、設定属性に対応するものは、指定された kwargs の値でその属性を上書きするために使用されます。設定属性に対応しない残りのキーは、基盤となるモデルの __init__ 関数に渡されます。

事前学習済みのモデル設定から、事前学習済みの PyTorch モデルをインスタンス化します。

モデルはデフォルトでmodel.eval()によって評価モードに設定されています（Dropoutモジュールは無効化されます）。モデルを学習するには、まずmodel.train()でトレーニングモードに戻す必要があります。

The warning Weights from XXX not initialized from pretrained model means that the weights of XXX do not come pretrained with the rest of the model. It is up to you to train those weights with a downstream fine-tuning task.

警告 Weights from XXX not used in YYY は、レイヤー XXX が YYY によって使用されていないことを示しており、そのためこれらの重みは破棄されます。

ファイアウォールが設定された環境でこのメソッドを使用するには、特別な“offline-mode”を有効にしてください。

例:

>>> from transformers import BertConfig, BertModel

>>> # Download model and configuration from huggingface.co and cache.
>>> model = BertModel.from_pretrained("google-bert/bert-base-uncased")
>>> # Model was saved using *save_pretrained('./test/saved_model/')* (for example purposes, not runnable).
>>> model = BertModel.from_pretrained("./test/saved_model/")
>>> # Update configuration during loading.
>>> model = BertModel.from_pretrained("google-bert/bert-base-uncased", output_attentions=True)
>>> assert model.config.output_attentions == True

get_compiled_call

< >

( compile_config: transformers.generation.configuration_utils.CompileConfig | None )

torch.compile された self.__call__ のバージョンを返します。これは、推論時にコンパイル済み/未コンパイルの forward を動的に切り替える場合に有用です。特に、prefill（新しい形状でグラフを再計算することを避けるため、コンパイル済みバージョンを使用したくない）と反復デコーディング（静的形状でコンパイル済みバージョンの高速化効果を享受したい）の切り替えに役立ちます。

get_decoder

< >

( )

decoderモジュールのベストエフォートによる検索。

試行の順序（現在の利用の約85%をカバー）：

  1. self.decoder/self.language_model/self.text_model
  2. self.base_model（多くのラッパーはデコーダーをここに格納します）
  3. self.base_model.get_decoder()（ネストされたラッパー）
  4. fallback: 個別のルールが必要な少数の特殊なモデルに対して例外を送出する

get_encoder

< >

( modality: str | None = None )

encoderモジュールのベストエフォートによる検索。modality引数が指定された場合、マルチモーダルモデルにおいてモダリティ固有のエンコーダー（例：“image_encoder”）を検索します。デフォルトでは、モデルにテキストエンコーダーが存在する場合はそれを返し、存在しない場合はselfを返します。

modalityの値として指定できるのは、“image”、“video”、“audio”です。

get_expanded_tied_weights_keys

< >

( all_submodels: bool = False )

現在のモデルの拡張されたtied weightキー（モジュールや正規表現パターンを含む場合）を返します。all_submodels=Trueの場合、すべてのサブモデルに対して再帰的に処理されます（つまり、すべてのサブモデルのconfig値を再チェックします）。

ほとんどのモデルでは、埋め込みの結合のみを必要とするため、モデルには _tied_weights_keys = {"lm_head.weight": "model.embed_tokens.weight"} という内部プロパティがあります。この場合、マッピングはすでに「展開済み」、つまり完全なパラメータをすでに含んでおり、この関数は単にそのプロパティのコピーを返します。より複雑なパターン、例えば DFineForObjectDetection の場合、以下の属性があります。

_tied_weights_keys = {
    r"bbox_embed.(?![0])\d+": "bbox_embed.0",
    r"class_embed.(?![0])\d+": "class_embed.0",
    "model.decoder.class_embed": "class_embed",
    "model.decoder.bbox_embed": "bbox_embed",
}
In this case, the function looks up all the model's parameters and buffers, and matches all the params,

以下を返します:

{
    'bbox_embed.1.layers.0.bias': 'bbox_embed.0.layers.0.bias',
    'bbox_embed.1.layers.0.weight': 'bbox_embed.0.layers.0.weight',
    'bbox_embed.1.layers.1.bias': 'bbox_embed.0.layers.1.bias',
    'bbox_embed.1.layers.1.weight': 'bbox_embed.0.layers.1.weight',
    'bbox_embed.1.layers.2.bias': 'bbox_embed.0.layers.2.bias',
    'bbox_embed.1.layers.2.weight': 'bbox_embed.0.layers.2.weight',
    'bbox_embed.2.layers.0.bias': 'bbox_embed.0.layers.0.bias',
    'bbox_embed.2.layers.0.weight': 'bbox_embed.0.layers.0.weight',
    ...
    'class_embed.1.bias': 'class_embed.0.bias',
    'class_embed.1.weight': 'class_embed.0.weight',
    'class_embed.2.bias': 'class_embed.0.bias',
    'class_embed.2.weight': 'class_embed.0.weight',
    ...
    'model.decoder.class_embed.0.bias': 'class_embed.0.bias',
    'model.decoder.class_embed.0.weight': 'class_embed.0.weight',
    'model.decoder.class_embed.1.bias': 'class_embed.0.bias',
    'model.decoder.class_embed.1.weight': 'class_embed.0.weight',
    ...
    'model.decoder.bbox_embed.0.layers.0.bias': 'bbox_embed.0.layers.0.bias',
    'model.decoder.bbox_embed.0.layers.0.weight': 'bbox_embed.0.layers.0.weight',
    'model.decoder.bbox_embed.0.layers.1.bias': 'bbox_embed.0.layers.1.bias',
    'model.decoder.bbox_embed.0.layers.1.weight': 'bbox_embed.0.layers.1.weight',
    ...
}
i.e. all the parameters matching the regex and modules patterns in `_tied_weights_keys`

get_experts_implementation

< >

( )

このモデルおよびそのサブモデルのexperts実装を、set_experts_implementationが受け付ける形式のdictとして返します（このモデルには""、各サブconfigには1エントリずつ）。これはset_experts_implementationの逆操作であり、例えば現在の実装のスナップショットを撮って後で復元する場合に使用します。

get_memory_footprint

< >

( return_buffers = True )

パラメータ

  • return_buffers (bool、省略可能、デフォルトは True) — メモリフットプリントの計算において、バッファテンソルのサイズを返すかどうかを指定します。バッファとは、勾配を必要とせず、パラメータとして登録されていないテンソルです。例えば、バッチノルム層の平均値や標準偏差などが該当します。詳細は https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2 を参照してください。

モデルのメモリフットプリントを取得します。現在のモデルのメモリフットプリントをバイト単位で返します。 現在のモデルのメモリフットプリントをベンチマークし、テストを設計するのに便利です。PyTorch のディスカッションから着想を得た解決策です: https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2

get_parameter_or_buffer

< >

( target: str )

target で指定されたパラメータまたはバッファが存在する場合はそれを返し、存在しない場合はエラーをスローします。これは get_parameter() と get_buffer() を1つの便利な関数にまとめたものです。ターゲットが _extra_state 属性である場合、モジュールによって提供される追加の状態を返します。なお、target がモデルのリーフである場合のみ動作することに注意してください。

gradient_checkpointing_disable

< >

( )

activation_checkpointing_disable()の非推奨エイリアスです。v6で削除されます。

gradient_checkpointing_enable

< >

( gradient_checkpointing_kwargs = None**kwargs )

activation_checkpointing_enable()の非推奨エイリアスです。v6で削除されます。

init_weights

< >

( )

必要に応じて、重みを初期化して結合します。カスタムのPreTrainedModelを使用する場合は、_init_weights内で初期化ロジックを実装する必要があります。

initialize_weights

< >

( )

これはself.apply(self._initialize_weights)を呼び出すことと同等ですが、複合モデルを正しく処理します。 この関数は、モジュールグラフに沿って再帰を進めるにつれて、各モジュールに対して正しいinit_weights関数を動的にディスパッチします。任意の数のサブモデルを処理できます。これがない場合、すべての複合モデルは、最外層の_init_weights内で明示的にすべてのサブモデルに対して2回目の再帰を行う必要があり、非常にエラーが発生しやすく非効率になります。

is_custom_code

< >

( )

現在のモデルがカスタムコードかどうかを返します。つまり、ハブから読み込まれたコード、またはユーザー固有のモジュール/セッションで定義されたコードのいずれかです。

is_remote_code

< >

( )

現在のモデルがカスタムコード（つまり、ハブから読み込まれたコード）であるか、register_for_auto_class によって登録されたクラスであるかを返します。

mark_tied_weights_as_initialized

< >

( loading_info )

後で結合（上書き）されるため、そのパラメータを初期化することを避けるために、結合対象のパラメータに_is_hf_initializedフラグを追加します。 ほとんどのembeddingが結合されており、それらは巨大なパラメータ（語彙数はしばしば256k）であるため、これらは非常に重要です。 それらに対して初期化を実行するのは非常にコストが高いためです。

named_non_persistent_buffers

< >

( recurse: bool = Trueremove_duplicate: bool = True )

named_buffersと同様に、非永続的なバッファのみを生成します。永続的かどうかを判断するのが必ずしも直感的ではないため、便利です。

post_init

< >

( )

各 Transformer モデルの初期化の最後に実行されるメソッドです。モデルのモジュールが正しく初期化された後に実行する必要があるコード（重みの初期化など）を実行するために使用されます。また、複合モデル（つまり、トップレベルのモデルが子モデルからこれらのプロパティを知る必要がある場合）において、並列化計画、tied_weights_keys、_keep_in_fp32_modules などのすべての静的プロパティを正しく取得するためにも使用されます。

register_for_auto_class

< >

( auto_class = 'AutoModel' )

パラメータ

  • auto_class (str または type、省略可、デフォルトは "AutoModel") — この新しいモデルを登録する auto クラスです。

このクラスを指定された auto クラスに登録します。これは、ライブラリ内のモデルはすでに auto クラスにマッピングされているため、カスタムモデルでのみ使用すべきです。

resize_token_embeddings

< >

( new_num_tokens: int | None = Nonepad_to_multiple_of: int | None = Nonemean_resizing: bool = True ) → torch.nn.Embedding

パラメータ

  • new_num_tokens (int, 省略可) — 埋め込み行列の新しいトークン数です。サイズを大きくすると、末尾に新しく初期化されたベクトルが追加されます。サイズを小さくすると、末尾からベクトルが削除されます。指定されなかった場合、またはNoneの場合、何もしずにモデルのtorch.nn.Embeddingモジュールへのポインタをそのまま返します。
  • pad_to_multiple_of (int, 省略可能) — 設定した場合、埋め込み行列を指定された値の倍数にパディングします。 new_num_tokens が None に設定されている場合、埋め込みを pad_to_multiple_of.

    これは、計算能力が>= 7.5（Volta）のNVIDIAハードウェアでTensor Coresの使用を有効にするために、また、シーケンス長が128の倍数であることで恩恵を受けるTPUにおいて特に有用です。この詳細や、リサイズに適切な値の選択に関するヘルプについては、このガイドを参照してください: https://docs.nvidia.com/deeplearning/performance/dl-performance-matrix-multiplication/index.html#requirements-tc

  • mean_resizing (bool) — 旧埋め込みの平均と共分散を持つ多変量正規分布から追加された埋め込みを初期化するか、平均がゼロで標準偏差が config.initializer_range.

    mean_resizingをTrueに設定することは、因果言語モデルの埋め込みサイズを拡大する際に有用です。この設定により、新しい埋め込みを元の埋め込みの平均値で初期化することで、新しい埋め込みを追加する前後の次のトークン確率間のKLダイバージェンスが低減されるため、生成されるトークンの確率に影響を与えません。詳細については、この記事を参照してください: https://nlp.stanford.edu/~johnhew/vocab-expansion.html

戻り値

torch.nn.Embedding

モデルの入力トークン Embeddings Module へのポインタ。

new_num_tokens != config.vocab_size の場合、モデルの入力トークン埋め込み行列をリサイズします。

モデルクラスにtie_weights()メソッドがある場合、その後で重みの埋め込みを結合します。

save_pretrained

< >

( save_directory: str | os.PathLikeis_main_process: bool = Truestate_dict: dict | None = Nonepush_to_hub: bool = Falsemax_shard_size: int | str = '50GB'variant: str | None = Nonetoken: str | bool | None = Nonesave_peft_format: bool = Truesave_original_format: bool = Truedistributed_checkpoint: bool = False**kwargs )

パラメータ

  • save_directory (str または os.PathLike) — 保存先ディレクトリ。存在しない場合は作成されます。
  • is_main_process (bool、省略可、デフォルトは True) — この関数を呼び出しているプロセスがメインプロセスかどうかを示します。TPU などの分散学習環境では、すべてのプロセスでこの関数を呼び出す必要があるため、この引数が役立ちます。この場合、競合状態を避けるために、メインプロセスでのみ is_main_process=True を設定してください。
  • state_dict (torch.Tensor のネストされた辞書) — 保存するモデルの状態辞書です。デフォルトでは self.state_dict() が使用されますが、モデルの一部のみを保存する場合や、モデルの状態辞書を復元する際に特別な注意が必要になる場合（モデル並列化を使用している場合など）に使用できます。
  • push_to_hub (bool、省略可、デフォルトは False) — モデルを保存した後、Hugging Face モデルハブにプッシュするかどうかを指定します。プッシュ先のリポジトリは repo_id で指定できます（指定しない場合、save_directory の名前があなたのネームスペース内でデフォルトとして使用されます）。
  • max_shard_size (int または str, 省略可, デフォルトは "50GB") — シャード化されるチェックポイントの最大サイズです。シャード化されたチェックポイントのサイズは、このサイズ未満になります。文字列で指定する場合は、数字の後に単位（例： "5MB").

    モデルの単一の重みがmax_shard_sizeより大きい場合、その重みはmax_shard_sizeを超える独自のチェックポイントシャードに格納されます。

  • variant (str, 省略可) — 指定した場合、重みは model..safetensors の形式で保存されます。
  • token (str または bool、省略可) — リモートファイルの HTTP ベアラ認証に使用するトークンです。True の場合、または指定されていない場合は、hf auth login を実行した際に生成されたトークン（~/.huggingface に保存）が使用されます。
  • save_peft_format (bool、省略可、デフォルトはTrue) — PEFT ライブラリとの後方互換性のため、モデルにアダプター重みがアタッチされている場合、アダプターの state dict のすべてのキーにbase_model.modelをプレフィックスとして付与する必要があります。上級ユーザーは、save_peft_formatをFalseに設定することで、この動作を無効にできます。
  • save_original_format (bool、省略可、デフォルトはTrue) — transformersの以前のバージョンとの後方互換性のために、逆マッピング付きでチェックポイントを保存できます。モデルが None のレガシーチェックポイントから読み込まれた場合でも、逆マッピングは存在する必要があります。
  • distributed_checkpoint (bool、任意、デフォルトは False) — FSDP または TP によるシャード化されたモデルを保存する際に、重みを CPU に集約する代わりに、分散チェックポイント (DCP) として safetensors を書き出します。すべてのランクがこのメソッドを呼び出す必要があります。 False の場合、書き出し前に gather_full_state_dict を介してランク 0 で重みを CPU に集約します。 トレーニングの保存と再開を目的としており、save_pretrained の全機能を利用したい場合は False に設定してください。push_to_hub=True の場合、ランク 0 がチェックポイントを consolidated/ サブディレクトリに集約し、そのディレクトリをアップロードします。 torch>=2.7 が必要です。
  • kwargs (dict[str, Any]、省略可) — push_to_hub() メソッドに渡される追加のキーワード引数。

モデルとその設定ファイルをディレクトリに保存し、from_pretrained()クラスメソッドを使って再読み込みできるようにします。

set_attn_implementation

< >

( attn_implementation: str | dictallow_all_kernels: bool = False )

パラメータ

  • attn_implementation (str または dict) — このモデルに設定するアテンション実装です。str の場合は、関連するすべてのサブモデルにディスパッチされます。dict の場合は、キーが sub_configs の名前となり、各サブモデルが対応する値をディスパッチします（自身およびその中にネストされたすべてのサブモデルに対して）。値自体も同じ形式の dict であり、そのサブモデルの sub_configs をターゲットにできます（ネストされた attn_implementation dict を用いて config を初期化する場合と同様です）。
  • allow_all_kernels (bool, 任意) — attn_implementation が kernels-community ハブリポジトリ外のカスタムカーネルである場合、検証されていないハブリポジトリからカーネルを読み込むかどうかを指定します。

このモデルのattn_implementationに要求された値を設定します。

set_decoder

< >

( decoder )

対称的なセッター。get_decoderで使用される参照ロジックを反映しています。

set_encoder

< >

( encodermodality: str | None = None )

対称的なセッター。get_encoderで使用される参照ロジックを反映しています。

set_experts_implementation

< >

( experts_implementation: str | dict )

パラメータ

  • experts_implementation (str または dict) — このモデルに設定する experts の実装です。str の場合は、関連するすべてのサブモデルにディスパッチされます。dict の場合は、キーが sub_configs の名前となり、各サブモデルが対応する値をディスパッチします。

このモデルに、要求されたexperts_implementationを設定します。

set_use_kernels

< >

( use_kernelskernel_config: transformers.utils.kernel_config.KernelConfig | None = Nonemode: Mode | None = None )

パラメータ

  • use_kernels (bool) — モデルの一部のレイヤーをカーネル化するためにkernelsライブラリを使用するかどうか。
  • kernel_config (KernelConfig、省略可) — モデルをカーネル化するために使用するカーネル設定です。None の場合、デフォルトのカーネルマッピングが使用されます。
  • mode (Mode、省略可) — kernelize 実行時に適用するモードです。省略時は、内部の training フラグに基づいて、トレーニングモードまたは推論モードのいずれかがデフォルトとして使用されます。

モデルの一部のレイヤーをカーネル化するためにkernelsライブラリを使用するかどうかを設定します。

tie_weights

< >

( missing_keys: set[str] | None = Nonerecompute_mapping: bool = True )

モデルの重みを結合します。recompute_mapping=False（内部から呼び出される場合のデフォルト）の場合、結合対象のパラメータの {target: source} 対応関係を含む model.all_tied_weights_keys 属性に依存します。 recompute_mapping=True の場合、結合が必要なパラメータを決定するために、すべての内部サブモデルとその設定を再確認します。これは、__init__ や from_pretrained の外で model.tie_weights() が単独で呼び出される場合のデフォルトであり、設定の値がどこかで変更された場合に備えています。

from_pretrained の実行中、タイイングは対称的である点にご注意ください。マッピングが「tie target -> source」と指定されている場合でも、source がチェックポイントに存在せずtarget が存在する場合は、実際に存在するパラメータにすべてをタイイングできるように、source と target を入れ替えます。

へ

( *args**kwargs )

ドット区切りパス（例: torch.float32）のモック値: 属性アクセスのチェーン、呼び出しはパススルーデコレータとして動作し、repr はドット区切りパスを返し、ベースクラスとして使用するとプレーンな type ベースに置き換えられます（PEP 560 の __mro_entries__）。これにより、実際のサブクラスは通常のメタクラスを保持し、inspect.signature はモックの __init__ ではなく、実際の __init__ を読み取ります。

warn_if_padding_and_no_attention_mask

< >

( input_idsattention_mask )

入力に input_ids が含まれており、パディングが含まれているように見えるが、アテンションマスクが指定されていない場合、一度だけ警告を表示します。

カスタムモデルには、superfast init が特定のモデルに適用可能かどうかを決定する _supports_assign_param_buffer も含める必要があります。このプロパティが必要かどうかの判断材料として、test_save_and_load_from_pretrained が失敗する場合があります。その場合は、これを False に設定してください。

ModuleUtilsMixin

クラス transformers.modeling_utils.ModuleUtilsMixin

< >

( )

torch.nn.Modulesでミックスインとして使用するいくつかのユーティリティ。

num_parameters

< >

( only_trainable: bool = Falseexclude_embeddings: bool = False ) → int

パラメータ

  • only_trainable (bool、省略可、デフォルトはFalse) — 学習可能なパラメータの数のみを返すかどうか
  • exclude_embeddings (bool、任意、デフォルトはFalse) — 埋め込みパラメータ以外の数値のみを返すかどうか

戻り値

int

パラメータの数。

モジュール内のパラメータ数（オプションで、学習可能または非埋め込み）を取得します。

Hub へのプッシュ

class transformers.utils.PushToHubMixin

< >

( )

モデルやトークナイザーをハブにプッシュする機能を含む Mixin です。

push_to_hub

< >

( repo_id: strcommit_message: str | None = Nonecommit_description: str | None = Noneprivate: bool | None = Nonetoken: bool | str | None = Nonerevision: str | None = Nonecreate_pr: bool = Falsemax_shard_size: int | str | None = '50GB'tags: list[str] | None = None )

パラメータ

  • repo_id (str) — {object}をプッシュするリポジトリの名前です。特定の組織にプッシュする場合は、組織名を含む必要があります。
  • commit_message (str, 省略可) — プッシュ時にコミットするメッセージ。デフォルトは "Upload {object}" です。
  • commit_description (str, 省略可) — 作成されるコミットの説明
  • private (bool、省略可) — リポジトリを非公開にするかどうか。None（デフォルト）の場合、組織のデフォルトが非公開でない限り、リポジトリは公開になります。リポジトリが既に存在する場合、この値は無視されます。
  • token (bool または str、省略可) — リモートファイルの HTTP ベアラ認証に使用するトークン。True（デフォルト）の場合、hf auth login を実行した際に生成されたトークン（~/.huggingface に保存）が使用されます。
  • revision (str、省略可) — アップロードしたファイルをプッシュするブランチ。
  • create_pr (bool、省略可、デフォルトはFalse) — アップロードしたファイルを含む PR を作成するか、直接コミットするかどうかを指定します。
  • max_shard_size (int または str、省略可能、デフォルトは "50GB") — モデルにのみ適用されます。シャード化される前のチェックポイントの最大サイズです。シャード化されたチェックポイントは、それぞれがこのサイズ未満になります。文字列で指定する場合は、数字の後に単位（"5MB" など）を続ける必要があります。
  • tags (list[str]、省略可) — Hub にプッシュするタグのリストです。

{object_files} を 🤗 Model Hub にアップロードします。

例:

from transformers import {object_class}

{object} = {object_class}.from_pretrained("google-bert/bert-base-cased")

# Push the {object} to your namespace with the name "my-finetuned-bert".
{object}.push_to_hub("my-finetuned-bert")

# Push the {object} to an organization with the name "my-finetuned-bert".
{object}.push_to_hub("huggingface/my-finetuned-bert")
Update on GitHub

←ログ出力 テキスト生成→