huggingface/pytorch-image-models

• 새로운 소식 (What's New)

• 소개 (Introduction)

• 모델 (Models)

• 기능 (Features)

• 결과 (Results)

• 시작하기 (문서) (Getting Started (Documentation))

• 학습, 검증, 추론 스크립트 (Train, Validation, Inference Scripts)

• 멋진 PyTorch 리소스 (Awesome PyTorch Resources)

• 라이선스 (Licenses)

• 인용 (Citing)

• Release 1.0.27

• NaFlex 파이프라인 지원(이미지당 가변 종횡비/크기)을 포함한 Gemma4 ViT 인코더 추가. Yonghye Kwon님께 감사드립니다.

• NaFlexVit에서 DINOv3 가중치 지원.

• Muon 폴백 (AdamW/NadamW) 학습률 (lr) 동작 개선

• pickle 체크포인트 처리 보안 개선. 모든 로딩의 기본값을 weights_only=True로 설정.

, ArgParse를 위한 safe_global 추가. - 핵심 ViT/EVA 모델 및 레이어의 어텐션 마스크 (attention mask) 처리 개선. 불리언 (bool) 마스크를 해결하고, SSL 작업을 위해 is_causal을 전달.

• ViT에서 위치 임베딩 (pos embed)이 비활성화된 경우의 클래스 및 레지스터 토큰 (register token) 사용 수정.

• ViT의 풀링 (pooling) 옵션으로 패치 표현 정제 (Patch Representation Refinement, PRR) 추가. Sina (https://github.com/sinahmr)님께 감사드립니다.

• 어텐션 풀링 (attention pooling) 레이어의 출력 투영 (output projection) / MLP 차원 일관성 개선.

• Flash Attention 커널 사용을 위한 Hiera 모델 F.SDPA 최적화.

• SGDP 옵티마이저 (optimizer)에 주의 사항 추가.

• Release 1.0.26. Hugging Face를 떠난 이후 첫 유지보수 릴리스.

• 증류 (distillation) 작업 래퍼 (wrappers)에 토큰 증류 (token distillation) 학습 지원 추가

• 공식적인 지원 중단 (deprecation)에 대비하여 일부 torch.jit 사용 제거

• AdamP 옵티마이저에 주의 사항 추가

• 버퍼가 init_empty_weights와 같은 해킹 방식으로 초기화될 수 있도록 meta-device 초기화 시에도 reset_parameters() 호출

• DTensor/FSDP2와 작동하도록 Muon 옵티마이저 조정 (clamp_min_ 대신 clamp_ 사용, DTensor를 위한 대체 NS 브랜치)

• Release 1.0.25

호환성 중단 (Compat Break): ParallelScalingBlock (& DiffParallelScalingBlock)에서 QKV 대 MLP 편향 (bias) 관련 간과된 사항 수정

• 이미 학습된 timm 모델에는 영향을 미치지 않으나, 다운스트림 (downstream) 사용에는 영향을 미칠 수 있음.

• 이미 학습된 모델에는 영향을 미치지 않음

• Release 1.0.24

• PyTorch 2.9.1 기반의 RTX Pro 6000, 5090, 4090 카드에서 모든 모델에 대한 추론 시간 (inference timing) 측정을 위한 새로운 벤치마크 결과 csv 파일 추가

• 레거시 임포트 (legacy imports)에 영향을 미치는, 지원 중단된 (deprecated) timm.models.layers 임포트 경로의 모듈 이동 오류 수정

• Release 1.0.23

• 이전 실행 결과보다 약간 향상된 dpwee, dwee, dlittle (differential) ViT 모델을 위한 더 나은 NAdaMuon 학습 적용

• 512x512 및 640x640 해상도의 약 21M 파라미터 규모 timm 변형 CSATv2 모델 추가 - https://huggingface.co/timm/csatv2_21m.sw_r640_in1k (83.13% top-1)

• https://huggingface.co/timm/csatv2_21m.sw_r512_in1k (82.58% top-1)

• 비지속적 파라미터 (non-persistent param) 초기화를 __init__에서 분리하여, 메타 디바이스 (meta-device) 초기화 후 init_non_persistent_buffers()를 통해 외부에서 호출할 수 있는 공통 메서드로 변경

• CSATV2 모델 추가 (감사합니다 https://github.com/gusdlf93) -- DCT stem 및 공간 주의 집중 (spatial attention)을 갖춘 가볍지만 고해상도인 모델. https://huggingface.co/Hyunil/CSATV2

• 기존 timm Muon 구현에 AdaMuon 및 NAdaMuon 옵티마이저 (optimizer) 지원 추가. 이미지 작업에 익숙한 하이퍼파라미터 (hparams)를 사용했을 때 AdamW 대비 더 경쟁력 있는 모습을 보임.

• 연말 PR 정리, 오랫동안 열려 있던 여러 PR의 측면들을 병합

• 차분 주의 집중 (differential attention, DiffAttention) 병합, 이에 대응하는 DiffParallelScalingBlock (ViT용) 추가, 일부 작은 ViT 모델 학습

• 몇 가지 풀링 (pooling) 모듈인 LsePlus 및 SimPool 추가

• DropBlock2d 정리 및 최적화 (ByobNet 기반 모델에 대한 지원도 추가)

• 차분 주의 집중 (differential attention) 병합

• 유닛 테스트 (unit test) 범위를 상한 PyTorch 2.9.1 + Python 3.13까지 상향, 하한은 여전히 PyTorch 1.13 + Python 3.10 유지

• 가벼운 태스크 추상화 (task abstraction) 추가, 새로운 태스크를 통해 학습 스크립트에 로짓 (logits) 및 특징 증류 (feature distillation) 지원 추가

• 오래된 APEX AMP 지원 제거

• 1.0.21 버전에서 도입된 LayerScale / LayerScale2d 초기화 버그 (초기화 값이 무시됨) 수정. 감사합니다 https://github.com/Ilya-Fradlin

• Release 1.0.22

• 몇몇 새로운 모델을 포함하도록 ImageNet 및 OOD 변형 결과 CSV 파일을 업데이트하고, 여러 torch 및 timm 버전에서 정확성을 검증함

• AdamW 대 Muon의 하이퍼파라미터 (hparam) 탐색의 일환으로 EfficientNet-X 및 EfficientNet-H B5 모델 가중치 추가 (Muon 실행에 대해 여전히 반복 작업 중)

• 커스텀 기능이 포함된 Muon 옵티마이저 (optimizer) 구현 추가 (https://github.com/KellerJordan/Muon 기반)

  • 컨볼루션 (conv) 가중치에 대한 추가적인 유연성 및 개선된 처리, 그리고 직교화 (orthogonalization)에 적합하지 않은 가중치 형상 (weight shapes)에 대한 폴백 (fallback) 기능 제공
  • 할당 (allocs)을 줄이고 융합된 (fused) (b)add(b)mm 연산을 사용하여 NS 반복 (iterations) 속도 소폭 향상
  • Muon이 파라미터 형상에 적합하지 않거나 (또는 파라미터 그룹 플래그를 통해 제외된 경우) 기본적으로 AdamW (nesterov=True인 경우 NAdamW) 업데이트를 사용 - torch 구현과 유사하게 adjust_lr_fn을 통해 여러 LR 스케일 조정 함수 중에서 선택 가능
  • 여러 NS 계수 프리셋 중에서 선택하거나 ns_coefficients를 통해 직접 지정 가능

• 'meta' 디바이스 모델 초기화의 처음 2단계 지원

• 'meta' 디바이스 컨텍스트에서 생성을 방해하던 여러 연산 (ops) 수정

• timm 내의 모든 모델 및 모듈 (nn.Module을 상속받는 모든 것)에 device 및 dtype factory kwarg 지원 추가

• 코드 내 사전 학습된 설정 (pretrained cfgs)에 라이선스 필드 추가

• Release 1.0.21

• DINOv3 ViT 가중치 태그를 lvd_1689m -> lvd1689m으로 재매핑 ( sat_493m -> sat493m 도 동일) - Release 1.0.20

• DINOv3 (https://arxiv.org/abs/2508.10104) ConvNeXt 및 ViT 모델 추가. ConvNeXt 모델은 기존 timm 모델로 매핑됨. ViT 지원은 DINOv3 특유의 RoPE 구현과 일치하도록 새로운 RotaryEmbeddingDinoV3를 사용하는 EVA base 모델을 통해 완료됨 - MobileCLIP-2 (https://arxiv.org/abs/2508.20691) 비전 인코더. 새로운 MCI3/MCI4 FastViT 변형이 추가되었으며 가중치는 기존 FastViT 및 B, L/14 ViT에 매핑됨.

• MetaCLIP-2 Worldwide (https://arxiv.org/abs/2507.22062) ViT 인코더 가중치 추가.

• SigLIP-2 (https://arxiv.org/abs/2502.14786) NaFlex ViT 인코더 가중치를 timm NaFlexViT 모델을 통해 추가.

• 기타 수정 및 기여 사항

• set_input_size() 추가

OpenCLIP 3.0.0에서 사용하는 EVA 모델에 적용된 방식으로, timm 기반 인코더 모델의 리사이징 (resizing)을 허용함. - Release 1.0.18, OpenCLIP 3.0.0의 PE-Core S & T 모델에 필요함

• Python 3.9 호환성을 깨뜨리던 작은 타이핑 (typing) 이슈 수정. 1.0.19 패치 릴리스.

• NaFlexViT에 ROPE 지원 추가. EVA, EVA02, Meta PE ViT, timm SBB ViT (ROPE 포함), 그리고 Naver ROPE-ViT를 포함하여 EVA 베이스 (eva.py)가 적용되는 모든 모델은 모델 생성 시 use_naflex=True를 전달하면 이제 NaFlexViT로 로드할 수 있음. - small/tiny 변형, tiling이 포함된 lang 변형, 그리고 더 많은 공간 (spatial) 변형을 포함하여 더 많은 Meta PE ViT 인코더 추가.

• NaFlexViT 및 EVA 모델에서 PatchDropout 수정 (Naver ROPE-ViT 추가 이후 발생한 회귀 (regression) 문제).

• grid_indexing='xy' 사용 시 XY 순서 수정, 'xy' 모드에서 정방형이 아닌 이미지 사용에 영향을 미침 ('xy' 모드는 ROPE-ViT와 PE만 영향을 받음).

• 개선된 Google Gemma 3n 동작을 위한 MobileNet-v5 백본 (backbone) 미세 조정 (업데이트된 공식 가중치와 쌍을 맞추기 위함)

• stem bias 추가 (업데이트된 가중치에서는 0으로 설정됨, 이전 가중치와 호환성 깨짐)

• GELU -> GELU (tanh 근사). JAX에 더 가깝게 만들기 위한 사소한 변경

• 레이어 감쇠 (layer-decay) 지원을 위한 두 가지 인자(argument) 추가: 최소 스케일 클램프 (min scale clamp) 및 '최적화 없음 (no optimization)' 스케일 임계값

• 정규화 (norm) 계산을 float32로 강제하기 위해 활성화할 수 있는 'Fp32' LayerNorm, RMSNorm, SimpleNorm 변형 추가

• 위에서 언급한 norm, norm+act 레이어에 대한 일부 타이핑 및 인자 정리 수행

• eva.py에서 Naver ROPE-ViT (https://github.com/naver-ai/rope-vit) 지원, 혼합 모드를 위한 RotaryEmbeddingMixed 모듈 추가, HuggingFace Hub에 가중치 업로드

모델	이미지 크기	top1	top5	파라미터 수
vit_large_patch16_rope_mixed_ape_224.naver_in1k	224	84.84	97.122	304.4
...

• ROPE 모듈, 헬퍼 (helpers), 그리고 FX 트레이싱 리프 등록 (FX tracing leaf registration) 정리

• 버전 1.0.17 릴리스 준비

• Gemma 3n 이미지 인코더를 위한 MobileNetV5 백본 (인코더 전용 변형 포함)

• 버전 1.0.16 릴리스

• NaFlexViT에 F.grid_sample 기반 2D 및 factorized pos embed 리사이즈 추가. 다양한 크기를 사용할 때 더 빠름 (https://github.com/stas-sl 의 예시 기반).

• vmap을 matmul로 교체하여 patch embed 리샘플링 속도 추가 개선 (https://github.com/stas-sl 의 스니펫 기반).

• 테스트 중에 생성된 3개의 초기 네이티브 (native) NaFlexViT 체크포인트 추가: ImageNet-1k 및 동일한 하이퍼파라미터(hparams)를 가진 3가지 서로 다른 pos embed 설정.

모델	Top-1 Acc	Top-5 Acc	Params (M)	Eval Seq Len
naflexvit_base_patch16_par_gap.e300_s576_in1k	83.67	96.45	86.63	576
...

• forward_intermediates를 위한 그래디언트 체크포인팅 (gradient checkpointing) 지원 및 일부 체크포인팅 버그 수정. 감사합니다 https://github.com/brianhou0208

• AdamW (legacy), Adopt, Kron, Adafactor (BV), Lamb, LaProp, Lion, NadamW, RmsPropTF, SGDW 옵티마이저 (optimizers)에 '수정된 가중치 감쇠 (corrected weight decay)' (https://arxiv.org/abs/2506.02285) 옵션 추가

• PE (perception encoder) ViT 모델이 실시간 리매핑 대신 네이티브 timm 가중치를 사용하도록 전환

• prefetch loader의 cuda stream 버그 수정

• 초기 NaFlexVit 모델 코드. NaFlexVit은 다음과 같은 Vision Transformer입니다:

• 임베딩 (embedding)과 위치 인코딩 (position encoding)을 단일 모듈로 캡슐화

• 패치화 전 (dictionary) 입력에 대한 nn.Linear 패치 임베딩 (patch embedding) 지원

• NaFlex 가변 종횡비, 가변 해상도 지원 (SigLip-2: https://arxiv.org/abs/2502.14786)

• FlexiViT 가변 패치 크기 지원 (https://arxiv.org/abs/2212.08013)

• NaViT 분수/인수 분해된 위치 임베딩 (fractional/factorized position embedding) 지원 (https://arxiv.org/abs/2307.06304)

• vision_transformer.py에 있는 기존 vit 모델들은 create_model에 use_naflex=True 플래그를 추가함으로써 NaFlexVit 모델로 로드할 수 있습니다.

• 일부 네이티브 가중치는 곧 추가될 예정입니다.

• 가변 종횡비 / 크기 이미지를 사용하여 학습 / 미세 조정 (fine-tuning) / 평가를 할 수 있는 전체 NaFlex 데이터 파이프라인을 사용할 수 있습니다.

• train.py 및 validate.py에서 이를 활성화하려면 --naflex-loader 인자를 추가해야 하며, 반드시 NaFlexVit과 함께 사용해야 합니다.

• 활성화하려면

• NaFlex 데이터 파이프 (data pipe)와 함께 NaFlexVit 모델에 로드된 기존 (classic) ViT를 평가하려면:
  python validate.py /imagenet --amp -j 8 --model vit_base_patch16_224 --model-kwargs use_naflex=True --naflex-loader --naflex-max-seq-len 256

• 학습 (training)에는 주목할 만한 몇 가지 추가 인자 (args) 기능이 있습니다.

• --naflex-train-seq-lens 인자는 학습 중 배치 (batch)당 무작위로 선택할 시퀀스 길이 (sequence lengths)를 지정합니다. --naflex-max-seq-len 인자는 검증 (validation)을 위한 목표 시퀀스 길이를 설정합니다. --model-kwargs enable_patch_interpolator=True --naflex-patch-sizes 12 16 24를 추가하면 보간 (interpolation)을 통한 배치당 무작위 패치 크기 (patch size) 선택이 활성화됩니다. --naflex-loss-scale 인자는 배치 크기에 따라 배치당 손실 스케일링 (loss scaling) 모드를 변경합니다. timm NaFlex 로딩은 각 시퀀스 길이 (seq len)에 대해 배치 크기를 변경합니다.

• https://github.com/brianhou0208 덕분에 작고 빠른 모델들을 다수 추가했습니다.

• SwiftFormer - (ICCV2023) SwiftFormer: Efficient Additive Attention for Transformer-based Real-time Mobile Vision Applications

• FasterNet - (CVPR2023) Run, Don’t Walk: Chasing Higher FLOPS for Faster Neural Networks

• SHViT - (CVPR2024) SHViT: Single-Head Vision Transformer with Memory Efficient

• StarNet - (CVPR2024) Rewrite the Stars

• GhostNet-V3 - GhostNetV3: Exploring the Training Strategies for Compact Models

• Meta의 Perception Encoder 모델(https://arxiv.org/abs/2504.13181)을 지원하도록 EVA ViT (가장 유사한 모델)를 업데이트하고 Hub 가중치 (weights)를 로드했습니다. 다만 전용 timm 가중치는 아직 푸시(push)해야 합니다.

• RoPE 구현에 유연성을 추가했습니다.

• https://github.com/brianhou0208 덕분에 forward_intermediates()를 지원하는 모델 수가 크게 증가했으며 몇 가지 추가 수정 사항이 적용되었습니다.

• DaViT, EdgeNeXt, EfficientFormerV2, EfficientViT(MIT), EfficientViT(MSRA), FocalNet, GCViT, HGNet /V2, InceptionNeXt, Inception-V4, MambaOut, MetaFormer, NesT, Next-ViT, PiT, PVT V2, RepGhostNet, RepViT, ResNetV2, ReXNet, TinyViT, TResNet, VoV

• 새로운 가중치(weights)를 포함하여 TNT 모델 업데이트
  forward_intermediates()

https://github.com/brianhou0208 님 덕분에 local-dir: 추가

사전 학습된 스키마(pretrained schema)를 위해 local-dir:/path/to/model/folder를 사용할 수 있습니다.

모델 이름 대신 로컬 폴더로부터 Hugging Face Hub 모델(config.json + 가중치 파일)의 소스 모델 / 사전 학습된 설정(pretrained cfg) 및 가중치를 가져옵니다. - ONNX 내보내기(export)를 위한 수정 및 개선 사항

• SigLIP 2 ViT 이미지 인코더 추가 (https://huggingface.co/collections/timm/siglip-2-67b8e72ba08b09dd97aecaf9)

• 가변 해상도(Variable resolution) / 종횡비 NaFlex 버전은 작업 진행 중(WIP)

• SBB 레시피로 학습된 'SO150M2' ViT 가중치 추가. 훌륭한 결과가 나왔으며, 이전 시도보다 적은 학습량으로 ImageNet에서 더 나은 성능을 보임.
  vit_so150m2_patch16_reg1_gap_448.sbb_e200_in12k_ft_in1k

• 88.1% top-1 vit_so150m2_patch16_reg1_gap_384.sbb_e200_in12k_ft_in1k

• 87.9% top-1 vit_so150m2_patch16_reg1_gap_256.sbb_e200_in12k_ft_in1k

• 87.3% top-1 vit_so150m2_patch16_reg4_gap_256.sbb_e200_in12k

• InternViT-300M '2.5' 가중치 업데이트

• 1.0.15 버전 출시

• 참고: PyTorch 2.6 및 Python 3.13은 현재 timm의 메인 브랜치 및 출시된 버전에서 테스트를 마쳤으며 정상 작동합니다.