timm Model API'si

Her timm modeli, forward() üzerinde ortak bir arayüz paylaşan bir torch.nn.Module'dür. Bu arayüz, modeli bir özellik çıkarıcı ve bir sınıflandırıcı başlığına ayırır, ara özellikleri açığa çıkarır ve eğitim (gradyan denetleme noktası, parametre gruplandırma) ile giriş çözünürlüğünü değiştirme için kancalar sağlar. Bu arayüze göre yazılan kod, mimariler arasında çalışır; timm'in eğitim betiği, özellik çıkarma sarmalayıcıları ve optimizör fabrikası da tüm modelleri aynı şekilde işler.

Bu sayfa, oluşturulmuş bir modelin arayüzünü açıklar: her modelin sağladığı, çoğunun sağladığı ve bazı ailelere özgü olan kısımlar. Modellerin nasıl oluşturulduğu (create_model argümanları, önceden eğitilmiş etiketler, önceden eğitilmiş yapılandırma) model referansında ele alınır.

Özellik çıkarıcı ve baş

Bir modelin ileri geçişi forward_head(forward_features(x))'dir.

• forward_features(x), modelin bir norm katmanına sahip olması durumunda son norm katmanından sonra, son aşamanın havuzlanmamış çıktısını döndürür: konvolüsyonel modeller için NCHW özellik haritası, ViT tarzı modeller için NLC token (sınıf / kayıt önek token'ları dahil).
• forward_head(x, pre_logits=False) küresel havuzlamayı (veya token seçimini), logit öncesi katmanları ve sınıflandırıcıyı uygular. pre_logits=True ile sınıflandırıcıdan önce durur ve havuzlanmış özellikleri döndürür.

Üç özellik, ilgili boyutları tanımlar:

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)

Birkaç model, tek tensör giriş, tek tensör çıkış biçiminden sapar: çok dallı modeller (CrossViT, EfficientViM) forward_features tarafından bir liste döndürür ve NaFlex / Gemma4 ViT'leri değişken çözünürlük için ek yama koordinatı ve geçerlilik girdilerini kabul eder.

Sınıflandırıcı

• get_classifier() sınıflandırıcı modülünü döndürür.
• reset_classifier(num_classes, global_pool=None) sınıflandırıcıyı yeni, rastgele başlatılmış bir sınıflandırıcıyla değiştirir.
  • num_classes=0 sınıflandırıcıyı bir kimlik dönüşümüyle değiştirir, böylece havuzlama (pooling) etkin kaldığında model(x) havuzlanmış özellikleri döndürür.
  • global_pool aynı anda havuzlamayı değiştirir. global_pool='' bunu devre dışı bırakır; num_classes=0 ile birlikte kullanıldığında model(x) havuzlanmamış özellikleri döndürür.
  • global_pool=None mevcut birleştirmeyi korur.

num_classes / global_pool ayarlı bir model oluşturmak, orijinal sınıflandırıcıyı tahsis etmeden sınıflandırıcıyı sonradan sıfırlamakla aynı etkiye sahiptir. Sadece kodlayıcıya sahip görme kuleleri (DeepSeek, Gemma4, MobileNetV5 ve Qwen3 kodlayıcıları) sınıflandırıcıya sahip değildir ve bu yöntemleri uygulamaz.

Ara özellikler

• forward_intermediates(x, indices=None, norm=False, stop_early=False, output_fmt='NCHW', intermediates_only=False) modeli çalıştırır ve nihai özelliklerin yanı sıra ara özelliklerin bir listesini döndürür.
  • indices ara değerleri seçer: tümü için None, son n için int n veya bir indeks listesi (olumsuz değerler sondan sayılır).
  • intermediates_only=True yalnızca ara özellikleri döndürür.
  • stop_early=True, son seçilen indeksin sonraki blokları atlar (bazı modeller, örneğin MobileNetV3, intermediates_only=True gerektirir).
  • norm=True her ara çıktıya son norm katmanını uygular.
• feature_info, her indeks için bir giriş olacak şekilde kullanılabilir ara özellikleri açıklar: kanal sayısı (num_chs), girdiye göre stride (reduction) ve modül adı (module).
• prune_intermediate_layers(indices=1, prune_norm=False, prune_head=True) kullanılacak son index'ten sonraki blokları (ve isteğe bağlı olarak son normu ve başlığı) kaldırır ve alınacak mutlak index'leri döndürür. Model yalnızca bir algılama veya segmentasyon başlığı için omurga olarak ara çıktılarını çıkarmak için kullanılacaksa bunu kullanın.
  • prune_head=True tüm başlığı (baş normu, logit öncesi katmanlar, dikkat birleştirme ve sınıflandırıcı) kaldırır, en fazla birleştirme katmanını bırakır. Özellik genişliği değişmediğinde başlığı korumak için prune_head=False geçin.
  • Budama, özellik genişliğini değiştirdiğinde (hiyerarşik bir modeli önceki bir aşamaya budamak), son aşama için boyutlandırılmış başlık ve son norm da kaldırılır. forward_features() o zaman son tutulan özellikte sona erer ve num_features / head_hidden_size onun genişliğidir.
  • Varsayılan ayarlarla, budanmış modelde kullanılmayan parametre yoktur (DDP, find_unused_parameters olmadan çalışır); ancak CoaT (paralel bloklar), CrossViT ve HRNet modellerinde yalnızca paralel ölçeklerin / dalların bir kısmı kullanıldığında bu durum geçerli değildir.

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

Tüm özellikler, ViT tarzı modellerin özellikleri dahil olmak üzere, varsayılan olarak NCHW haritaları olarak döndürülür; bu modellerde uzamsal jetonlar, önek jetonları atılarak bir ızgaraya yeniden şekillendirilir. Diğer output_fmt seçenekleri aileye özgüdür (ViT tarzı modeller için NLC, bazıları için NHWC); return_prefix_tokens (ViT ailesi) gibi ek argümanlar da aynı şekilde aileye özgüdür. features_only=True ile oluşturulan bir model, model(x) tarafından döndürülen özellik haritalarını döndüren bir omurga olarak sarılır; her iki yaklaşımın ayrıntıları için özellik çıkarımı bölümüne bakın.

Girdi boyutu

Modeller, girdi çözünürlüğünü nasıl ele aldıklarına göre üç gruba ayrılır:

• Herhangi bir giriş boyutu. Çoğu konvolüsyonel model ve sabit boyutlu konum gömme veya pencere bölümleri içermeyen konvolüsyonel hibritler, toplam kaydırma değerlerinden büyük herhangi bir giriş boyutunda, değişiklik yapılmadan çalışır.
• Sabit giriş boyutu, yeniden boyutlandırılabilir. Pozisyon gömme, dikkat pencere bölümleri veya göreli pozisyon tabloları içeren modeller, oluşturulurken img_size argümanıyla belirlenen (varsayılan: önceden eğitilmiş cfg input_size) tek bir boyut için oluşturulur. Bunu uygulayan ailelerde (ViT, DeiT, BEiT, EVA, Swin, MaxViT ve diğerleri, aşağıdaki tabloya bakın), set_input_size(img_size=...) bunu daha sonra değiştirir; pozisyon gömme ve göreli pozisyon tablolarını yeniden örnekler ve pencereleri günceller. Birkaçı ek argümanlar kabul eder, örneğin ViT için patch_size, Swin için window_size / window_ratio. Mevcut boyutta çağrılması modeli değiştirmez. Diğerleri kullanılacakları img_size ile oluşturulmalıdır.
• Değişken giriş boyutu. dynamic_img_size=True ile oluşturulan ViT ve EVA ailesi modelleri, her ileri geçişte konum gömme (position embedding) değerlerini giriş boyutuna yeniden örnekler; bu işlem hızda bazı kayıplara yol açar. dynamic_img_size=True (veya eşdeğeri strict_img_size=False) ile oluşturulan Swin, SwinV2 ve SwinV2-CR modelleri ise dikkat maskelerini (attention mask) her ileri geçişte giriş boyutuna göre hesaplar. NaFlex ViT'ler değişken çözünürlüğü yerel olarak (native) destekler.

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

Eğitim kancaları

• set_grad_checkpointing(enable=True), aktivasyon (gradyan) checkpointing’i etkinleştirir; bellek tasarrufu sağlamak için geriye yayılım sırasında her bloğun ileri aktivasyonlarını yeniden hesaplar (train.py içinde --grad-checkpointing). Çoğu model bunu destekler; bazı eski mimariler (VGG, Inception, NASNet, …) hata verir.
• group_matcher(coarse=False), her parametreyi bir kök veya blok grubuna atayan düzenli ifadeleri döndürür. Optimizatör fabrikası, katman bazlı öğrenme oranı azalması için (layer_decay, bkz. optimizers referansı) katman başına öğrenme oranlarını ölçeklendirmek için bunu kullanır.
• no_weight_decay(), uygulandığı yerlerde, ağırlık çürümesi uygulanmaması gereken parametrelerin adlarını döndürür (pozisyon gömme, sınıf belirteçleri, …). Optimizör fabrikası, bunları ve tüm 1B parametreleri (yapılar, norm ölçekleri) ağırlık çürümesinden hariç tutar.

Önceden eğitilmiş yapılandırma

model.pretrained_cfg (ve eski takma adı model.default_cfg) kaynak checkpoint'i tanımlayan bir sözlüktür: giriş boyutu, interpolasyon, kırpma, normalizasyon, sınıflandırıcı ve ilk conv modülü adları, lisans ve kaynak. Ön eğitilmiş ağırlıklar yüklendiğinde sınıflandırıcıyı ve giriş conv'ini uyarlamak için ve ön işleme varsayılanları olarak kullanılır. Alanlar için model referansına bakın.

Model oluşturulduğunda veya checkpoint’inden farklı olacak şekilde değiştirildiğinde (in_chans, img_size, set_input_size()) ön eğitilmiş cfg değiştirilmez. Modelin mevcut girdisi ayrı olarak izlenir, timm.models.get_model_input_config(model) kanal, boyut ve sabit boyut kısıtlamasını döndürür ve timm.data.resolve_input_data_config(model) dönüşümler için bir veri yapılandırmasını buna göre çözümler. timm.models.get_model_args(model) modelin şu anki haliyle yeniden oluşturulması için gerekli argümanları döndürür ve save_for_hf bunları dışa aktarılan yapılandırmaya yazar, böylece yeniden boyutlandırılmış veya uyarlanmış bir model yeniden yüklenebilir. modelleri uyarla ve dışa aktar bölümüne bakın.

Aile desteği

Aşağıdaki tablo, her model ailesinin arayüzün hangi isteğe bağlı bölümlerini desteklediğini listeler. Bu tablo, her ailedeki her model sınıfının küçük bir modelini oluşturup çalıştıran hfdocs/generate_model_docs.py betiği tarafından oluşturulur. Destek, bir aile içindeki mimariler arasında farklılık gösterebilir; ayrıntılar için aile sayfalarına bakın.

✓ destekleniyor, ✓ (kare) yalnızca kare boyutlarda çalışır, ✗ desteklenmiyor, – gerekli değil (model zaten herhangi bir giriş boyutunu kabul eder). Bir ailenin her model sınıfı, ailenin en küçük (test dışı) mimarisine sahip rastgele başlatılmış bir model üzerinde her özelliğin çalıştırılmasıyla kontrol edilir. Aynı sonuçlara sahip sınıflar bir satırı paylaşır; aile sayfasında her biri için kullanılan mimari listelenir.

Bir modelin uygulanması

Yeni bir model, eğitim betiği, özellik çıkarımı ve optimizator fabrikasıyla özel durumlar gerektirmeden çalışabilmesi için arayüzü uygulamalıdır:

• forward_features, forward_head(x, pre_logits=False) ve bunların bileşimi olan forward, num_classes, num_features ve head_hidden_size ayarlanmış olarak.
• get_classifier ve reset_classifier(num_classes, global_pool=None).
• forward_intermediates, prune_intermediate_layers ve bir feature_info listesi.
• Herhangi bir parametrenin azaltılmaması gerekiyorsa set_grad_checkpointing, group_matcher ve no_weight_decay kullanın.
• Model sabit bir giriş boyutu için oluşturulduysa set_input_size.
• Standart yapıcı argümanları: num_classes, in_chans, global_pool, drop_rate, drop_path_rate ve parametre oluşturma için device / dtype.

tests/test_models.py, kayıtlı modellerin arayüzünün forward, backward, features, intermediates, classifier reset ve pretrained cfg kısımlarını kontrol eder (CI süresini kısaltmak için en büyük modeller bazı testlerden hariç tutulur).