API Model timm

Setiap model timm adalah torch.nn.Module yang berbagi antarmuka umum di atas forward(). Antarmuka ini membagi model menjadi ekstraktor fitur dan kepala klasifikasi, mengekspos fitur perantara, serta menyediakan hook untuk pelatihan (checkpointing gradien, pengelompokan parameter) dan untuk mengubah resolusi input. Kode yang ditulis berdasarkan antarmuka ini berfungsi di berbagai arsitektur, yang merupakan cara skrip pelatihan timm, pembungkus ekstraksi fitur, dan pabrik optimizer menangani setiap model dengan cara yang sama.

Halaman ini menjelaskan antarmuka dari model yang telah dibangun: bagian mana yang disediakan oleh setiap model, bagian mana yang disediakan oleh sebagian besar model, dan bagian mana yang spesifik untuk beberapa keluarga. Cara model dibuat (argumen create_model, tag pretrained, dan konfigurasi pretrained) dibahas dalam referensi model.

Ekstraktor fitur dan kepala

Forward pass sebuah model adalah forward_head(forward_features(x)).

• forward_features(x) mengembalikan output yang tidak dipooling dari tahap terakhir, setelah lapisan norm terakhir jika model memilikinya: peta fitur NCHW untuk model konvolusional, token NLC (termasuk token prefix kelas / register apa pun) untuk model gaya ViT.
• forward_head(x, pre_logits=False) menerapkan global pooling (atau pemilihan token), lapisan pre-logits apa pun, dan klasifikator. Dengan pre_logits=True, proses berhenti sebelum klasifikator dan mengembalikan fitur yang telah di-pool.

Tiga atribut menggambarkan ukuran yang terlibat:

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)

Beberapa model menyimpang dari bentuk satu tensor masuk, satu tensor keluar: model multi-cabang (CrossViT, EfficientViM) mengembalikan sebuah list dari forward_features, dan ViT NaFlex / Gemma4 menerima input koordinat patch dan validitas tambahan untuk resolusi variabel.

Klasifikator

• get_classifier() mengembalikan modul klasifikator.
• reset_classifier(num_classes, global_pool=None) mengganti classifier dengan yang baru, diinisialisasi secara acak.
  • num_classes=0 mengganti klasifikator dengan identitas, sehingga model(x) mengembalikan fitur yang telah dipooling ketika pooling masih diaktifkan.
  • global_pool mengubah pooling pada saat yang sama. global_pool='' menonaktifkannya; dikombinasikan dengan num_classes=0, model(x) mengembalikan fitur yang tidak di-pool.
  • global_pool=None mempertahankan pooling saat ini.

Membuat model dengan num_classes / global_pool yang diset memiliki efek yang sama dengan mereset klasifikator setelahnya, tanpa mengalokasikan klasifikator asli. Menara visual hanya-encoder (encoder DeepSeek, Gemma4, MobileNetV5, dan Qwen3) tidak memiliki klasifikator dan tidak mengimplementasikan metode-metode ini.

Fitur perantara

• forward_intermediates(x, indices=None, norm=False, stop_early=False, output_fmt='NCHW', intermediates_only=False) menjalankan model dan mengembalikan fitur akhir beserta daftar fitur perantara.
  • indices memilih intermediates: None untuk semua, int n untuk n terakhir, atau daftar indeks (nilai negatif dihitung dari akhir).
  • intermediates_only=True hanya mengembalikan fitur perantara.
  • stop_early=True melewati blok setelah indeks terpilih terakhir (beberapa model, misalnya MobileNetV3, memerlukan intermediates_only=True).
  • norm=True menerapkan lapisan norm akhir ke setiap intermediate.
• feature_info menjelaskan fitur perantara yang tersedia, satu entri per indeks dengan jumlah saluran (num_chs), stride relatif terhadap input (reduction), dan nama modul (module).
• prune_intermediate_layers(indices=1, prune_norm=False, prune_head=True) menghapus blok setelah indeks terakhir yang akan digunakan (dan secara opsional norm akhir serta head) serta mengembalikan indeks absolut yang akan diambil. Gunakan ini ketika model hanya akan digunakan untuk mengekstrak intermediates, sebagai backbone untuk head deteksi atau segmentasi.
  • prune_head=True menghapus seluruh head (head norm, lapisan pre-logits, attention pooling, dan classifier), meninggalkan paling banyak hanya pooling. Berikan prune_head=False untuk mempertahankan head ketika lebar fitur tidak berubah.
  • Ketika pruning mengubah lebar fitur (pruning model hierarkis ke tahap sebelumnya), head dan final norm yang berukuran untuk tahap terakhir juga dihapus. forward_features() kemudian berakhir di fitur terakhir yang dipertahankan, dan num_features / head_hidden_size adalah lebarnya.
  • Dengan nilai bawaan, model yang dipangkas tidak memiliki parameter yang tidak terpakai (DDP bekerja tanpa find_unused_parameters), kecuali CoaT (blok paralel), CrossViT, dan HRNet ketika hanya sebagian dari skala/cabang paralel mereka yang diambil.

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

Semua fitur dikembalikan sebagai peta NCHW secara default, termasuk milik model gaya ViT, di mana token spasialnya dibentuk ulang menjadi grid dengan token prefix dihapus. Opsi output_fmt lainnya bersifat spesifik keluarga (NLC untuk model gaya ViT, NHWC untuk beberapa model), begitu pula argumen tambahan seperti return_prefix_tokens (keluarga ViT). Membuat model dengan features_only=True membungkusnya sebagai backbone yang mengembalikan peta fitur dari model(x), lihat feature extraction untuk detail kedua pendekatan tersebut.

Ukuran input

Model terbagi menjadi tiga kelompok berdasarkan cara mereka menangani resolusi input:

• Ukuran input apa pun. Sebagian besar model konvolusional, serta hibrida konvolusional tanpa embedding posisi berukuran tetap atau partisi jendela, dapat bekerja pada ukuran input apa pun yang lebih besar dari total stride mereka, tanpa perubahan.
• Ukuran input tetap, dapat diubah. Model dengan position embeddings, partisi jendela attention, atau tabel posisi relatif dibangun untuk satu ukuran, yang ditetapkan oleh argumen img_size saat pembuatan (default: input_size dari cfg pretrained). Pada keluarga model yang mengimplementasikannya (ViT, DeiT, BEiT, EVA, Swin, MaxViT, dan lainnya, lihat tabel di bawah), set_input_size(img_size=...) mengubahnya kemudian, dengan melakukan resampling pada position embeddings dan tabel posisi relatif serta memperbarui jendela. Beberapa model menerima argumen tambahan, misalnya patch_size untuk ViT, window_size / window_ratio untuk Swin. Memanggilnya pada ukuran saat ini tidak mengubah model. Model lainnya harus dibuat dengan img_size yang akan digunakan.
• Ukuran input dinamis. Model keluarga ViT dan EVA yang dibuat dengan dynamic_img_size=True melakukan resampling pada position embedding mereka ke ukuran input pada setiap forward pass, dengan sedikit biaya dalam hal kecepatan. Model Swin, SwinV2, dan SwinV2-CR yang dibuat dengan dynamic_img_size=True (atau ekuivalennya strict_img_size=False) menghitung attention mask mereka untuk ukuran input pada setiap forward pass sebagai gantinya. ViT NaFlex menangani resolusi variabel secara native.

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

Hook pelatihan

• set_grad_checkpointing(enable=True) mengaktifkan checkpointing aktivasi (gradien), yang menghitung ulang aktivasi maju dari setiap blok pada langkah mundur untuk menghemat memori (--grad-checkpointing di train.py). Sebagian besar model mendukungnya, tetapi beberapa arsitektur lama (VGG, Inception, NASNet, …) akan memicu error.
• group_matcher(coarse=False) mengembalikan ekspresi reguler yang menetapkan setiap parameter ke grup stem atau blok. Pabrik optimizer menggunakannya untuk menskalakan learning rate per layer untuk layer-wise learning rate decay (layer_decay, lihat referensi optimizers).
• no_weight_decay(), jika diimplementasikan, mengembalikan nama parameter yang tidak boleh didekay dengan weight decay (position embeddings, class tokens, …). Pabrik optimizer mengecualikan parameter-parameter ini dan semua parameter 1D (biases, norm scales) dari weight decay.

Konfigurasi pralatih

model.pretrained_cfg (dan alias lamanya model.default_cfg) adalah dict yang menjelaskan checkpoint sumber: ukuran input, interpolasi, crop, normalisasi, nama modul classifier dan conv pertama, lisensi, serta sumber. Ini digunakan untuk menyesuaikan classifier dan input conv saat bobot pretrained dimuat, serta sebagai nilai default pra-pemrosesan. Lihat referensi model untuk detail field-nya.

Pretrained cfg tidak berubah saat model dibuat atau dimodifikasi agar berbeda dari checkpoint-nya (in_chans, img_size, set_input_size()). Input saat ini dari model dilacak secara terpisah, timm.models.get_model_input_config(model) mengembalikan channel, ukuran, dan constraint ukuran tetapnya, dan timm.data.resolve_input_data_config(model) menyelesaikan data config untuk transformasi terhadapnya. timm.models.get_model_args(model) mengembalikan argumen untuk membangun ulang model seperti saat ini, dan save_for_hf menuliskannya ke config yang diekspor, sehingga model yang di-resize atau diadaptasi dapat dimuat ulang. Lihat adapt and export models.

Dukungan dari keluarga

Tabel di bawah ini merangkum bagian opsional dari antarmuka yang didukung oleh masing-masing keluarga model. Tabel ini dihasilkan oleh hfdocs/generate_model_docs.py, yang membangun dan menjalankan model kecil dari setiap kelas model dalam setiap keluarga. Dukungan dapat bervariasi antar arsitektur dalam satu keluarga, lihat halaman keluarga untuk detailnya.

✓ didukung, ✓ (persegi) hanya berfungsi untuk ukuran persegi, ✗ tidak didukung, – tidak diperlukan (model sudah menerima ukuran input apa pun). Setiap kelas model dalam sebuah keluarga diperiksa dengan menjalankan setiap fitur pada model yang diinisialisasi secara acak dari arsitektur terkecil (non-test) dalam keluarga tersebut. Kelas dengan hasil yang sama berbagi satu baris, dan halaman keluarga mencantumkan arsitektur yang digunakan untuk masing-masing.

Menerapkan model

Model baru harus mengimplementasikan antarmuka agar dapat bekerja dengan skrip pelatihan, ekstraksi fitur, dan pabrik optimizer tanpa kasus khusus:

• forward_features, forward_head(x, pre_logits=False) dan forward sebagai komposisinya, dengan num_classes, num_features dan head_hidden_size diatur.
• get_classifier dan reset_classifier(num_classes, global_pool=None).
• forward_intermediates, prune_intermediate_layers dan daftar feature_info.
• set_grad_checkpointing, group_matcher, dan no_weight_decay untuk parameter mana pun yang tidak boleh didekay.
• set_input_size jika model dibangun untuk ukuran input tetap.
• Argumen konstruktor standar: num_classes, in_chans, global_pool, drop_rate, drop_path_rate, dan device / dtype untuk pembuatan parameter.

tests/test_models.py memeriksa bagian antarmuka forward, backward, features, intermediates, classifier reset, dan pretrained cfg untuk model-model yang terdaftar (model terbesar dikecualikan dari beberapa tes untuk menjaga waktu CI tetap rendah).