timm 모델 API

모든 timm 모델은 forward() 위에 공통 인터페이스를 공유하는 torch.nn.Module입니다. 이 인터페이스는 모델을 특징 추출기와 분류 헤드(클래시파이어 헤드)로 분리하고, 중간 특징을 노출하며, 학습(그라디언트 체크포인트링, 파라미터 그룹핑) 및 입력 해상도 변경을 위한 훅을 제공합니다. 이 인터페이스를 기준으로 작성된 코드는 다양한 아키텍처에서 동일하게 작동하며, timm의 학습 스크립트, 특징 추출 래퍼 및 옵티마이저 팩토리가 모든 모델을 동일한 방식으로 처리하는 방식입니다.

이 페이지는 생성된 모델의 인터페이스를 설명합니다. 모든 모델이 제공하는 부분, 대부분의 모델이 제공하는 부분, 그리고 특정 패밀리에만 해당하는 부분을 다룹니다. 모델이 어떻게 생성되는지(create_model 인자, 사전 학습 태그, 사전 학습 config)는 모델 참조에서 다룹니다.

Feature extractor 및 head

모델의 forward pass는 forward_head(forward_features(x))입니다.

• forward_features(x)는 모델에 최종 norm 레이어가 있는 경우 해당 레이어를 거친 후 마지막 단계의 풀링되지 않은 출력을 반환합니다. 컨볼루션 모델의 경우 NCHW 형식의 feature map, ViT 스타일 모델의 경우 NLC 형식의 토큰(클래스/레지스터 접두사 토큰 포함)입니다.
• forward_head(x, pre_logits=False)는 전역 풀링(또는 토큰 선택), pre-logits 레이어 및 분류기를 적용합니다. pre_logits=True인 경우 분류기 전에 중단하여 풀링된 특징을 반환합니다.

크기에 관여하는 세 가지 속성이 있습니다:

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는 사용 가능한 중간 특징을 설명하며, 각 인덱스마다 채널 수(num_chs), 입력에 대한 스트라이드(reduction) 및 모듈 이름(module) 항목이 하나씩 포함됩니다.
• prune_intermediate_layers(indices=1, prune_norm=False, prune_head=True) 마지막 인덱스 이후의 블록(선택적으로 최종 norm과 head 포함)을 제거하고 가져올 절대 인덱스를 반환합니다. 모델이 탐지나 분할 head의 backbone으로만 사용되어 중간 결과를 추출하는 데만 활용될 때 이 메서드를 사용하세요.
  • prune_head=True는 헤드 전체(head norm, pre-logits 레이어, attention pooling, classifier)를 제거하며, pooling만 최대 한 개까지 남깁니다. feature width가 변하지 않는 경우 헤드를 유지하려면 prune_head=False를 전달하세요.
  • Pruning이 feature width를 변경하는 경우(계층적 모델을 이전 단계로 pruning하는 경우) 마지막 단계에 맞게 설정된 head와 final norm도 함께 제거됩니다. forward_features()는 마지막으로 유지된 feature에서 끝나며, num_features / head_hidden_size는 해당 feature의 width입니다.
  • 기본값을 사용할 경우, CoaT(병렬 블록), CrossViT, HRNet의 경우 일부 병렬 스케일/브랜치만 선택한 경우를 제외하고는 잘라낸 모델에 사용되지 않는 매개변수가 없습니다(DDP는 find_unused_parameters 없이 작동합니다).

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)에서 기능 맵을 반환하는 백본으로 래핑되며, 두 가지 접근 방식에 대한 자세한 내용은 feature extraction을 참고하세요.

입력 크기

모델은 입력 해상도를 처리하는 방식에 따라 세 그룹으로 나뉩니다:

• 임의의 입력 크기. 대부분의 컨볼루션 모델과 고정 크기 위치 임베딩이나 윈도우 분할이 없는 컨볼루션 하이브리드 모델은 총 스트라이드보다 큰 임의의 입력 크기에 대해 변경 없이 작동합니다.
• 고정 입력 크기, 리사이즈 가능. 위치 임베딩, 어텐션 윈도우 파티션 또는 상대 위치 테이블을 사용하는 모델은 생성 시 img_size 인수로 설정된 하나의 크기에 맞춰 빌드됩니다(기본값: 사전 학습된 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))

Training hooks

• set_grad_checkpointing(enable=True)은 활성화(그라디언트) 체크포인트링을 활성화하여, 메모리를 절약하기 위해 backward pass에서 각 블록의 forward activations를 다시 계산합니다(train.py의 --grad-checkpointing). 대부분의 모델이 이를 지원하지만, 일부 오래된 아키텍처(VGG, Inception, NASNet, …)는 오류를 발생시킵니다.
• group_matcher(coarse=False)는 각 매개변수를 stem 또는 block 그룹에 할당하는 정규 표현식을 반환합니다. 옵티마이저 팩토리는 이를 사용하여 레이어별 학습률 감쇠를 위해 레이어마다 학습률을 조정합니다(layer_decay, 옵티마이저 참조를 참조).
• 구현된 경우 no_weight_decay()는 weight decay를 적용하지 않아야 하는 파라미터의 이름(위치 임베딩, 클래스 토큰 등)을 반환합니다. 옵티마이저 팩토리는 이러한 파라미터와 모든 1차원 파라미터(bias, norm scale)를 weight decay에서 제외합니다.

사전 학습된 구성

model.pretrained_cfg(그리고 이전 별칭인 model.default_cfg)는 소스 체크포인트를 설명하는 dict입니다. 입력 크기, 보간, 크롭, 정규화, 분류기 및 첫 번째 conv 모듈 이름, 라이선스 및 출처를 포함합니다. 사전 학습된 가중치가 로드될 때 분류기와 입력 conv를 조정하는 데 사용되며, 전처리 기본값으로도 사용됩니다. 필드에 대한 자세한 내용은 모델 참조를 확인하세요.

모델이 생성되거나 체크포인트와 다르게 수정(in_chans, img_size, set_input_size())되어도 사전 학습된 cfg는 변경되지 않습니다. 모델의 현재 입력은 별도로 추적되며, 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에 의해 생성되며, 각 패밀리의 각 모델 클래스에 대해 작은 모델을 빌드하고 실행합니다. 지원 여부는 패밀리의 아키텍처에 따라 달라질 수 있으므로, 자세한 내용은 패밀리 페이지를 참조하세요.

✓ 지원됨, ✓ (정사각형) 정사각형 크기만 지원됨, ✗ 미지원, – 필요 없음(모델이 이미 모든 입력 크기를 허용함). 각 모델 계열의 모델 클래스는 해당 계열의 가장 작은(테스트용이 아닌) 아키텍처의 무작위 초기화 모델에서 모든 기능을 실행하여 확인됩니다. 동일한 결과를 가진 클래스는 한 행을 공유하며, 계열 페이지에는 각 클래스에 사용된 아키텍처가 나열됩니다.

모델 구현

새로운 모델은 학습 스크립트, feature extraction, optimizer factory와 함께 동작하도록 인터페이스를 구현해야 하며, 특별한 경우를 처리할 필요가 없습니다:

• 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 시간을 줄이기 위해 가장 큰 모델들이 제외됩니다).