timmのモデルAPI

すべてのtimmモデルはtorch.nn.Moduleであり、forward()の上に共通のインターフェースを共有しています。このインターフェースは、モデルを特徴量抽出器と分類ヘッドに分割し、中間特徴量を公開するとともに、学習（勾配チェックポイント、パラメータのグループ化）や入力解像度の変更のためのフックを提供します。このインターフェースに対して記述されたコードはアーキテクチャを横断して動作し、timmの学習スクリプト、特徴量抽出ラッパー、オプティマイザーファクトリーがすべてのモデルを同じ方法で処理する仕組みになっています。

このページでは、構築されたモデルのインターフェースについて説明します。すべてのモデルが提供する部分、多くのモデルが提供する部分、および特定のファミリーに固有の部分についてです。モデルの作成方法（create_modelの引数、事前学習タグ、事前学習設定）については、モデルのリファレンスで説明しています。

Feature extractor and head

モデルのフォワードパスはforward_head(forward_features(x))です。

• forward_features(x) は、モデルに最終的な norm レイヤーがある場合はそのレイヤーを適用した後の、最終ステージのプーリングされていない出力を返します。これは、畳み込みモデルの場合は NCHW の特徴マップ、ViT スタイルのモデルの場合は NLC のトークン（クラス / レジスタプレフィックストークンを含む）です。
• forward_head(x, pre_logits=False) は、グローバルプーリング（またはトークン選択）、pre-logits 層、および分類器を適用します。pre_logits=True の場合、分類器の前に処理を停止し、プーリングされた特徴を返します。

3つの属性が、関連するサイズを説明します。

import torch
import timm

model = timm.create_model('convnext_atto').eval()
x = torch.randn(2, 3, 224, 224)

features = model.forward_features(x)  # (2, 320, 7, 7), num_features = 320
pooled = model.forward_head(features, pre_logits=True)  # (2, 320), head_hidden_size = 320
logits = model.forward_head(features)  # (2, 1000), same as model(x)

一部のモデルは、単一テンソルの入力と単一テンソルの出力という形式から逸脱しています。マルチブランチモデル（CrossViT、EfficientViM）はforward_featuresからリストを返します。また、NaFlex / Gemma4のViTは、可変解像度に対応するために、追加のパッチ座標および有効性の入力を受け入れます。

分類器

• get_classifier()は、分類器モジュールを返します。
• reset_classifier(num_classes, global_pool=None) 分類器を新しいランダム初期化されたものに置き換えます。
  • num_classes=0 を設定すると、分類器が恒等変換に置き換えられ、プーリングが有効なままの場合、model(x) はプーリングされた特徴量を返します。
  • global_pool は、プーリングも同時に変更します。global_pool='' を設定すると無効化され、num_classes=0 と組み合わせることで、model(x) はプーリングされていない特徴量を返します。
  • global_pool=None は、現在のプーリングを維持します。

num_classes / global_pool を設定してモデルを作成することは、元の分類器を割り当てずに、その後で分類器をリセットするのと同じ効果を持ちます。エンコーダーのみのビジョンタワー（DeepSeek、Gemma4、MobileNetV5、Qwen3 のエンコーダー）には分類器がなく、これらのメソッドを実装していません。

中間特徴

• forward_intermediates(x, indices=None, norm=False, stop_early=False, output_fmt='NCHW', intermediates_only=False) モデルを実行し、最終的な特徴量と中間特徴量のリストを返します。
  • indices は中間結果を選択します: None ですべて、int の n で最後の n 個、またはインデックスのリスト(負の値は末尾から数えます)。
  • intermediates_only=True を指定すると、中間特徴のみが返されます。
  • stop_early=True を設定すると、最後の選択されたインデックス以降のブロックがスキップされます（MobileNetV3 などの一部のモデルでは、intermediates_only=True が必要です）。
  • norm=True を設定すると、各中間出力に最終的な norm レイヤーが適用されます。
• feature_info は、利用可能な中間特徴を説明します。各インデックスごとに1つのエントリがあり、チャネル数(num_chs)、入力に対するストライド(reduction)、モジュール名(module)が含まれます。
• prune_intermediate_layers(indices=1, prune_norm=False, prune_head=True) 最後に使用されるインデックス以降のブロック（オプションで最終的な norm と head）を削除し、取得する絶対インデックスを返します。モデルが検出やセグメンテーションの head のバックボーンとして、中間特徴の抽出にのみ使用される場合に使用してください。
  • prune_head=True を指定すると、ヘッド全体（head norm、pre-logits 層、attention pooling、classifier）が削除され、残るのは pooling のみ（またはそれ以下）になります。特徴量幅が変更されない場合は、ヘッドを保持するために prune_head=False を渡してください。
  • プルーニングによって特徴の幅が変更される場合（階層型モデルをより前のステージにプルーニングする場合）、最終ステージ用にサイズ設定されたヘッドと最終ノルムも削除されます。その場合、forward_features()は保持された最後の特徴で終了し、num_features / head_hidden_sizeはその幅になります。
  • デフォルト設定では、CoaT（並列ブロック）、CrossViT、HRNet（並列スケール/ブランチの一部のみを使用する場合）を除き、プルーニングされたモデルには未使用のパラメータは存在しません（find_unused_parametersなしでDDPが動作します）。

model = timm.create_model('resnet18').eval()
print([(f['num_chs'], f['reduction']) for f in model.feature_info])
# [(64, 2), (64, 4), (128, 8), (256, 16), (512, 32)]

final, intermediates = model.forward_intermediates(x)  # all 5 feature levels
last_two = model.forward_intermediates(x, indices=2, intermediates_only=True)  # (2, 256, 14, 14), (2, 512, 7, 7)

take_indices = model.prune_intermediate_layers(indices=2, prune_head=True)  # [3, 4], no classifier left

すべての機能はデフォルトでNCHWマップとして返されます。ViTスタイルのモデルも同様で、その空間トークンはプレフィックストークンを除外してグリッドにリシェイプされます。その他のoutput_fmtオプションはファミリーごとに異なります（ViTスタイルのモデルではNLC、一部のモデルではNHWC）。return_prefix_tokens（ViTファミリー）などの追加引数も同様です。features_only=Trueでモデルを作成すると、model(x)から特徴量マップを返すバックボーンとしてラップされます。両方のアプローチの詳細については、特徴量抽出を参照してください。

入力サイズ

モデルは、入力解像度の処理方法によって3つのグループに分類されます。

• 任意の入力サイズ。 ほとんどの畳み込みモデル、および固定サイズの位置埋め込みやウィンドウ分割を備えない畳み込みハイブリッドモデルは、総ストライドより大きい任意の入力サイズで、変更なしで動作します。
• 固定入力サイズ、リサイズ可能。位置埋め込み、アテンションウィンドウの分割、または相対位置テーブルを持つモデルは、作成時のimg_size引数で設定される1つのサイズ用に構築されます(デフォルト: 事前学習済みcfgのinput_size)。これをサポートするファミリー(ViT、DeiT、BEiT、EVA、Swin、MaxViTなど、下表参照)では、set_input_size(img_size=...)を呼び出すことで後から変更でき、位置埋め込みと相対位置テーブルを再サンプリングし、ウィンドウを更新します。いくつかのモデルは、ViTのpatch_sizeやSwinのwindow_size / window_ratioなど、追加の引数も受け付けます。現在のサイズで呼び出すと、モデルは変更されません。その他のモデルは、使用するimg_sizeで作成する必要があります。
• 動的な入力サイズ。dynamic_img_size=True で作成された ViT および EVA ファミリーのモデルは、各 forward pass において位置埋め込みを入力サイズに合わせて再サンプリングします。これには速度面でのコストが伴います。dynamic_img_size=True（または同等の strict_img_size=False）で作成された Swin、SwinV2、SwinV2-CR モデルは、代わりに各 forward pass において入力サイズに対するアテンションマスクを計算します。NaFlex ViT は可変解像度をネイティブで処理します。

model = timm.create_model('vit_tiny_patch16_224')
model.set_input_size(img_size=(384, 384))
model(torch.randn(1, 3, 384, 384))

トレーニングフック

• set_grad_checkpointing(enable=True) は、アクティベーション（勾配）チェックポイント機能を有効にします。これにより、バックワードパスで各ブロックのフォワードアクティベーションを再計算してメモリを節約します（train.py 内の --grad-checkpointing）。ほとんどのモデルがこれに対応していますが、一部の古いアーキテクチャ（VGG、Inception、NASNet など）ではエラーが発生します。
• group_matcher(coarse=False) は、各パラメータをステムまたはブロックグループに割り当てる正規表現を返します。 オプティマイザーファクトリは、レイヤーごとの学習率減衰（layer_decay、オプティマイザーの参考資料を参照）のために、レイヤーごとに学習率をスケーリングするためにこれを使用します。
• 実装されている場合、no_weight_decay() は、ウェイト減衰を適用すべきでないパラメータの名前（位置埋め込み、クラストークンなど）を返します。オプティマイザーファクトリは、これらとすべての1次元パラメータ（バイアス、ノーマルスケール）をウェイト減衰から除外します。

事前学習済み設定

model.pretrained_cfg（およびその旧エイリアスであるmodel.default_cfg）は、ソースのチェックポイントを記述する辞書です。入力サイズ、補間、クロップ、正規化、分類器および最初の conv モジュールの名前、ライセンス、ソースが含まれます。事前学習済み重みが読み込まれる際に分類器と入力 conv を適応させるために使用され、前処理のデフォルト値としても機能します。各フィールドについては、モデルの参照を参照してください。

モデルが作成されたり、チェックポイントと異なるように変更されたりしても、事前学習済みの cfg は変更されません（in_chans、img_size、set_input_size()）。モデルの現在の入力は別途追跡され、timm.models.get_model_input_config(model) はそのチャネル数、サイズ、固定サイズ制約を返します。また、timm.data.resolve_input_data_config(model) は、それに対するトランスフォーム用のデータ設定を解決します。timm.models.get_model_args(model) は、モデルを現在の状態のまま再構築するための引数を返し、save_for_hf はそれらをエクスポートされた設定に書き出すため、リサイズや適応されたモデルを再読み込みできます。モデルの適応とエクスポートを参照してください。

家族からのサポート

以下の表は、各モデルファミリーがインターフェースのどのオプション部分をサポートしているかをリストしています。この表は、hfdocs/generate_model_docs.pyによって生成され、各ファミリーの各モデルクラスの小さなモデルを構築して実行します。サポート状況はファミリー内のアーキテクチャによって異なる場合があります。詳細は各ファミリーのページを参照してください。

✓ 対応、✓ (square) 正方形サイズのみ対応、✗ 非対応、– 不要（モデルはすでに任意の入力サイズを受け入れる）。ファミリー内の各モデルクラスは、そのファミリー内で最小の（テスト用の）アーキテクチャを持つランダム初期化されたモデルに対してすべての機能を実行することで確認されます。同じ結果を持つクラスは1行を共有し、ファミリーページには各クラスに使用されたアーキテクチャがリストされています。

モデルの実装

新しいモデルは、トレーニングスクリプト、特徴量抽出、オプティマイザーファクトリと特別なケースなしで動作するように、インターフェースを実装する必要があります:

• forward_features、forward_head(x, pre_logits=False)、およびそれらの合成であるforwardを、num_classes、num_features、head_hidden_sizeを設定した状態で使用できます。
• get_classifierおよびreset_classifier(num_classes, global_pool=None)。
• forward_intermediates、prune_intermediate_layers、およびfeature_infoリスト。
• 減衰させたくないパラメータには、set_grad_checkpointing、group_matcher、no_weight_decayを使用します。
• モデルが固定の入力サイズ用に構築されている場合は、set_input_sizeを使用します。
• 標準のコンストラクタ引数: num_classes、in_chans、global_pool、drop_rate、drop_path_rate、およびパラメータ作成用のdevice / dtype。

tests/test_models.py は、登録されたモデルのインターフェースの forward、backward、features、intermediates、classifier reset、pretrained cfg の各部分をチェックします（CI の実行時間を短縮するため、最大規模のモデルは一部のテストから除外されています）。