Model

Halaman ini berisi dokumentasi referensi API untuk membuat dan menemukan model timm, konfigurasi pretrained mereka, serta helper checkpoint / Hub, dan ringkasan antarmuka yang dibagikan oleh model timm. Arsitektur individual dibahas dalam ringkasan model dan halaman per model.

Penggunaan

Model dibuat berdasarkan nama dengan create_model. Nama tersebut memilih arsitektur yang terdaftar di timm, secara opsional dengan tag pretrained setelah . (resnet50.a1_in1k), atau model di Hugging Face Hub atau di folder lokal melalui prefiks sumber. Argumen kata kunci yang tidak digunakan sendiri oleh create_model diteruskan ke fungsi entrypoint model menuju konstruktor kelas model, sehingga argumen spesifik model apa pun dapat diatur.

import torch
import timm

# Random init (pretrained=False is the default). The tag selects the pretrained cfg, and the weights loaded with
# pretrained=True. Without a tag the architecture's default tag is used.
model = timm.create_model('vit_tiny_patch16_224.augreg_in21k_ft_in1k')
print(model.pretrained_cfg['mean'], model.pretrained_cfg['crop_pct'])  # (0.5, 0.5, 0.5) 0.9

# Model arguments pass through to the model class, a 10 class head, single channel input and regularization.
model = timm.create_model('resnet50', num_classes=10, in_chans=1, drop_rate=0.2, drop_path_rate=0.05)

# Discover models, filters are fnmatch wildcards.
timm.list_models('convnext*')  # architecture names
timm.list_pretrained('resnet50.*')  # architecture.tag names w/ pretrained weights
timm.list_models(module='vision_transformer', pretrained=True)

# Image preprocessing to match the model's pretrained cfg (input size, interpolation, crop, mean / std).
model = timm.create_model('vit_tiny_patch16_224.augreg_in21k_ft_in1k')
data_config = timm.data.resolve_model_data_config(model)
transform = timm.data.create_transform(**data_config, is_training=False)

x = torch.randn(2, 3, 224, 224)
features = model.forward_features(x)  # unpooled features, (2, 197, 192)
pre_logits = model.forward_head(features, pre_logits=True)  # pooled features, (2, 192)
logits = model.forward_head(features)  # same as model(x), (2, 1000)

model.reset_classifier(5)  # replace the classifier w/ a new 5 class one
model.set_input_size(img_size=(384, 384))  # resample the position embedding for a new resolution
logits = model(torch.randn(2, 3, 384, 384))  # (2, 5)

Skrip pelatihan (train.py) mengekspos argumen umum melalui flag berikut:

• --model memilih model.
• --pretrained memuat bobot terlatih sebelumnya.
• --num-classes mengatur ukuran klasifikator (num_classes).
• --in-chans mengatur saluran input (in_chans).
• --gp mengatur jenis pooling global (global_pool).
• --drop mengatur dropout klasifikator (drop_rate).
• --drop-path mengatur stochastic depth (drop_path_rate).
• --pretrained-path memuat bobot terlatih dari file lokal dengan adaptasi klasifikator / konvolusi input (pretrained_cfg_overlay=dict(file=...)).
• --initial-checkpoint memuat checkpoint setelah model dibuat, tanpa adaptasi (checkpoint_path).
• --model-kwargs key=value ... meneruskan argumen model lainnya.

Lihat quickstart untuk pengantar.

Nama model

Hub dan sumber lokal membaca konfigurasi bahkan dengan pretrained=False, bobot hanya dimuat dengan pretrained=True. Nama tanpa prefiks sumber yang mengandung /, \ atau : akan memicu ValueError alih-alih kembali ke model registry dengan nama yang sama. hf_hub: adalah alias yang tidak didukung lagi dari hf-hub:.

Argumen umum

• pretrained memuat bobot dari cfg pretrained, dari state_dict atau file jika diset, jika tidak dari Hub (hf_hub_id) ketika huggingface_hub terpasang, atau dari url. Adaptasi classifier / input conv di bawah memungkinkan model pretrained dibuat untuk fine-tuning dalam satu panggilan.
• num_classes mengatur ukuran klasifikator, 0 menghapus klasifikator. Nilai default berasal dari cfg pretrained. Saat memuat bobot pretrained, jumlah kelas yang berbeda akan membuang bobot klasifikator (dibiarkan pada inisialisasi acak).
• global_pool mengatur jenis pooling, opsinya spesifik untuk model (misalnya avg, max, avgmax, catavgmax untuk sebagian besar convnet, token, avg, map untuk ViT), '' menonaktifkan pooling.
• in_chans mengatur jumlah channel input. Nilai default berasal dari cfg pretrained. Saat memuat bobot pretrained, bobot conv pertama akan disesuaikan (jika didukung) jika nilai ini berbeda dari jumlah channel pada checkpoint sumber (input_size[0] dalam cfg pretrained).
• drop_rate mengatur dropout pada klasifikator, didukung oleh sebagian besar model.
• drop_path_rate mengatur stochastic depth, yang didukung oleh sebagian besar model.
• img_size adalah argumen dari model gaya ViT dan model lain dengan ukuran input tetap; model-model ini dibangun untuk cfg pra-terlatih input_size kecuali jika disetel.
• dynamic_img_size=True pada keluarga ViT dan EVA melakukan resampling posisi embedding ke ukuran input pada setiap forward pass.
• features_only (dengan out_indices, output_stride, feature_cls) membungkus model sebagai feature backbone yang mengembalikan feature maps, lihat feature extraction.
• pretrained_cfg menggantikan cfg pretrained (sebuah tag, dict, atau PretrainedCfg).
• pretrained_cfg_overlay menimpa beberapa field-nya, misalnya pretrained_cfg_overlay=dict(file='weights.pth') memuat bobot pretrained=True dari file lokal, dengan adaptasi klasifikator / konvolusi input di atas (seperti yang dilakukan --pretrained-path di train.py).
• checkpoint_path memuat checkpoint dengan load_checkpoint setelah model dibuat. Ini adalah pemuatan ketat tanpa adaptasi, dan bobot EMA digunakan jika checkpoint memilikinya.
• cache_dir menimpa cache unduhan untuk bobot pretrained dan konfigurasi Hub.
• device diteruskan ke kelas model, parameter dibuat langsung pada perangkat tersebut. device='meta' membuat model tanpa mengalokasikan memori untuk bobotnya.
• dtype diteruskan ke kelas model, dan parameter dibuat langsung dalam dtype tersebut.
• scriptable mengatur bendera konfigurasi lapisan untuk scripting TorchScript.
• exportable mengatur bendera konfigurasi lapisan untuk ekspor / pelacakan.
• no_jit mengatur flag konfigurasi layer untuk menonaktifkan layer yang di-jit script.

Argumen yang diset ke None akan dibuang sebelum mencapai model, sehingga nilai bawaan model yang berlaku. Argumen yang tidak diterima oleh kelas model akan memicu TypeError pada sebagian besar model, sementara beberapa model mengabaikan argumen yang tidak dikenal.

Konfigurasi pralatih

Arsitektur memiliki satu atau lebih cfg pretrained, satu per tag, yang terdaftar dengan model. Sebuah cfg menjelaskan bobot (lokasi, lisensi, asal) dan bagaimana model dilatih serta harus dievaluasi dengan bobot tersebut. Model yang dibuat oleh create_model memiliki cfg-nya sebagai dict di model.pretrained_cfg (model.default_cfg adalah alias), sedangkan versi registry dikembalikan sebagai instance PretrainedCfg oleh get_pretrained_cfg.

Bidang input adalah apa yang resolve_data_config / resolve_model_data_config selesaikan menjadi konfigurasi data untuk dataset, transformasi, dan loader. cfg menggambarkan checkpoint sumber dan tidak diperbarui ketika model dibuat atau dimodifikasi secara berbeda (num_classes, in_chans, img_size, set_input_size()). Saluran input, ukuran, dan batasan ukuran tetap saat ini dari model dilacak secara terpisah: get_model_input_config mengembalikannya, dan resolve_input_data_config menyelesaikan konfigurasi data terhadapnya (seperti yang dilakukan oleh skrip pelatihan, validasi, dan inferensi). get_model_args mengembalikan argumen untuk membangun ulang model seperti sekarang, yang save_for_hf tulis ke konfigurasi yang diekspor. Lihat adaptasi dan ekspor model untuk detailnya.

Antarmuka model

Model timm berbagi antarmuka umum di luar forward(): pemisahan forward_features() / forward_head(), reset klasifikator, fitur perantara, penyesuaian ukuran input, dan hook pelatihan seperti gradient checkpointing dan pengelompokan parameter. Hal ini dijelaskan dalam Model API timm, termasuk keluarga model mana yang mendukung bagian mana.

Checkpoint dan Hub

• load_checkpoint memuat file checkpoint (PyTorch atau .safetensors) ke dalam model.
• load_state_dict membaca file checkpoint dan mengembalikan state dict-nya.
• resume_checkpoint memulihkan status model, optimizer, dan loss scaler dari checkpoint train.py dan mengembalikan epoch untuk dilanjutkan.

load_checkpoint dan load_state_dict secara default memilih bobot EMA dari checkpoint train.py (use_ema) dan menghapus prefiks kunci module. (DDP) dan _orig_mod. (torch.compile).

• save_for_hf menulis bobot dan config.json (arsitektur, cfg pretrained, model_args, label_names) ke sebuah folder.
• push_to_hf_hub mengunggah bobot dan konfigurasi ke repositori Hub dengan kartu model yang dihasilkan jika repositori tersebut tidak memilikinya.

Model kemudian dibuat dengan hf-hub: atau local-dir:, lihat berbagi dan memuat model.

import timm
from timm.models import save_for_hf

model = timm.create_model('resnet18', num_classes=4)
# ... fine-tune
save_for_hf(model, 'my_resnet18', model_config=dict(label_names=['a', 'b', 'c', 'd']), safe_serialization=True)
model = timm.create_model('local-dir:my_resnet18', pretrained=True)  # 4 classes, weights and labels restored
print(model.pretrained_cfg['label_names'])

Model kustom

Fungsi entrypoint model yang dihias dengan register_model ditambahkan ke registry, sehingga dapat dibuat dengan create_model dan ditemukan dengan list_models. Entrypoint di timm membangun modelnya dengan build_model_with_cfg, yang menangani cfg pretrained, pemuatan bobot pretrained, dan features_only.

API

Pembuatan model

>>> from timm import create_model

>>> # Create a MobileNetV3-Large model with no pretrained weights.
>>> model = create_model('mobilenetv3_large_100')

>>> # Create a MobileNetV3-Large model with pretrained weights.
>>> model = create_model('mobilenetv3_large_100', pretrained=True)
>>> model.num_classes
1000

>>> # Create a MobileNetV3-Large model with pretrained weights and a new head with 10 classes.
>>> model = create_model('mobilenetv3_large_100', pretrained=True, num_classes=10)
>>> model.num_classes
10

>>> # Create a Dinov2 small model with pretrained weights and save weights in a custom directory.
>>> model = create_model('vit_small_patch14_dinov2.lvd142m', pretrained=True, cache_dir="/data/my-models")
>>> # Data will be stored at */data/my-models/models--timm--vit_small_patch14_dinov2.lvd142m/*

Penemuan model

Konfigurasi pralatih

Input dan ekspor model saat ini

Checkpoint dan Hub

Model kustom