# DEIMv2

## 개요

DEIMv2 (DETR with Improved Matching v2)은 Shihua Huang, Yongjie Hou, Longfei Liu, Xuanlong Yu, Xi Shen이 [DEIMv2: Real-Time Object Detection Meets DINOv3](https://huggingface.co/papers/2509.20787)에서 제안했습니다.

해당 논문의 초록은 다음과 같습니다:

*간결하고 효과적인 Dense O2O를 기반으로 DEIM은 더 빠른 수렴과 향상된 성능을 입증했습니다. 본 연구에서는 DINOv3 특징을 확장하여 DEIMv2를 제안했습니다. DEIMv2는 X부터 Atto까지 8가지 모델 크기를 제공하며 GPU, 엣지, 모바일 배포를 지원합니다. X, L, M, S 변형의 경우 DINOv3 사전 학습/증류된 백본을 채택하고, DINOv3의 단일 스케일 출력을 다중 스케일 특징으로 효율적으로 변환하여 강력한 의미론적 정보와 세밀한 세부 정보를 보완함으로써 감지를 향상시키는 Spatial Tuning Adapter(STA)를 도입했습니다. 초경량 모델(Nano, Pico, Femto, Atto)의 경우 엄격한 자원 예산을 충족하기 위해 깊이 및 폭 가지치기를 적용한 HGNetv2를 사용합니다. 단순화된 디코더와 업그레이드된 Dense O2O와 함께, 이러한 통합 설계는 DEIMv2가 다양한 시나리오에서 우수한 성능-비용 트레이드오프를 달성할 수 있게 하여 새로운 최첨단 결과를 수립했습니다. 특히, 가장 큰 모델인 DEIMv2-X는 50.3M의 매개변수만으로 57.8 AP를 달성하여, 56.5 AP에 불과한 기존 X 스케일 모델(60M 이상 매개변수 필요)을 능가합니다. 컴팩트한 측면에서 DEIMv2-S는 COCO에서 50 AP 마일스톤을 초과한 최초의 10M 미만 모델(9.71M)로, 50.9 AP에 도달했습니다. 매개변수가 단 1.5M인 초경량 DEIMv2-Pico조차 38.5 AP를 제공하여, 매개변수가 약 50% 적은 YOLOv10-Nano(2.3M)와 동일한 성능을 달성합니다.*

이 모델은 [Harshal Janjani](https://huggingface.co/harshaljanjani)님이 기여했습니다. 원본 코드는 [여기](https://github.com/Intellindust-AI-Lab/DEIMv2)에서 찾을 수 있습니다.

## 사용

```python
from transformers import AutoImageProcessor, AutoModelForObjectDetection
from transformers.image_utils import load_image

url = "http://images.cocodataset.org/val2017/000000039769.jpg"
image = load_image(url)

image_processor = AutoImageProcessor.from_pretrained("harshaljanjani/DEIMv2_HGNetv2_N_COCO_Transformers")
model = AutoModelForObjectDetection.from_pretrained("harshaljanjani/DEIMv2_HGNetv2_N_COCO_Transformers", device_map="auto")

inputs = image_processor(images=image, return_tensors="pt").to(model.device)
outputs = model(**inputs)

results = image_processor.post_process_object_detection(
    outputs, threshold=0.5, target_sizes=[image.size[::-1]]
)

for result in results:
    for score, label, box in zip(result["scores"], result["labels"], result["boxes"]):
        box = [round(i, 2) for i in box.tolist()]
        print(f"Detected {model.config.id2label[label.item()]} with confidence {round(score.item(), 3)} at location {box}")
```

## Deimv2Config[[transformers.Deimv2Config]]

#### transformers.Deimv2Config[[transformers.Deimv2Config]]

```python
transformers.Deimv2Config(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, is_encoder_decoder: bool = True, initializer_range: float = 0.01, initializer_bias_prior_prob: float | None = None, layer_norm_eps: float = 1e-05, batch_norm_eps: float = 1e-05, backbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, freeze_backbone_batch_norms: bool = True, encoder_hidden_dim: int = 256, encoder_in_channels: list[int] | tuple[int, ...] = (512, 1024, 2048), feat_strides: list[int] | tuple[int, ...] = (8, 16, 32), encoder_layers: int = 1, encoder_ffn_dim: int = 1024, encoder_attention_heads: int = 8, dropout: float | int = 0.0, activation_dropout: float | int = 0.0, encode_proj_layers: list[int] | tuple[int, ...] = (2,), positional_encoding_temperature: int = 10000, encoder_activation_function: str = 'gelu', activation_function: str = 'silu', eval_size: list[int] | tuple[int, int] | None = None, normalize_before: bool = False, hidden_expansion: float = 1.0, d_model: int = 256, num_queries: int = 300, decoder_in_channels: list[int] | tuple[int, ...] = (256, 256, 256), decoder_ffn_dim: int = 1024, num_feature_levels: int = 3, decoder_n_points: int | list[int] = 4, decoder_layers: int = 6, decoder_attention_heads: int = 8, decoder_activation_function: str = 'relu', attention_dropout: float | int = 0.0, num_denoising: int = 100, label_noise_ratio: float = 0.5, box_noise_scale: float = 1.0, learn_initial_query: bool = False, anchor_image_size: int | list[int] | None = None, with_box_refine: bool = True, matcher_alpha: float = 0.25, matcher_gamma: float = 2.0, matcher_class_cost: float = 2.0, matcher_bbox_cost: float = 5.0, matcher_giou_cost: float = 2.0, use_focal_loss: bool = True, auxiliary_loss: bool = True, focal_loss_alpha: float = 0.75, focal_loss_gamma: float = 2.0, weight_loss_vfl: float = 1.0, weight_loss_bbox: float = 5.0, weight_loss_giou: float = 2.0, weight_loss_fgl: float = 0.15, weight_loss_ddf: float = 1.5, eos_coefficient: float = 0.0001, eval_idx: int = -1, layer_scale: int | float = 1.0, max_num_bins: int = 32, reg_scale: float = 4.0, depth_mult: float = 1.0, top_prob_values: int = 4, lqe_hidden_dim: int = 64, lqe_layers: int = 2, decoder_offset_scale: float = 0.5, decoder_method: str = 'default', up: float = 0.5, tie_word_embeddings: bool = True, weight_loss_mal: float = 1.0, use_dense_one_to_one: bool = True, mal_alpha: float | None = None, encoder_fuse_op: str = 'sum', spatial_tuning_adapter_inplanes: int = 16, encoder_type: str = 'hybrid', use_gateway: bool = True, share_bbox_head: bool = False, encoder_has_trailing_conv: bool = True)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/deimv2/configuration_deimv2.py#L32)

**매개변수:**

is_encoder_decoder (`bool`, *선택 사항*, 기본값 `True`) : 모델이 인코더/디코더로 사용되는지 여부.

initializer_range (`float`, *선택 사항*, 기본값 `0.01`) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.

initializer_bias_prior_prob (`float`, *선택 사항*) : `enc_score_head`와 `class_embed`의 bias를 초기화하는 데 사용되는 bias initializer의 사전 확률입니다. `None`인 경우, 모델 가중치를 초기화할 때 `prior_prob`가 `prior_prob = 1 / (num_labels + 1)`로 계산됩니다.

layer_norm_eps (`float`, *선택 사항*, 기본값 `1e-05`) : layer normalization 레이어에서 사용되는 epsilon 값입니다.

batch_norm_eps (`float`, *선택 사항*, 기본값 `1e-05`) : 배치 정규화 레이어에서 사용되는 epsilon 값입니다.

backbone_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *선택*) : 백본 모델의 구성입니다.

freeze_backbone_batch_norms (`bool`, *선택 사항*, 기본값 `True`) : 백본의 배치 정규화 레이어를 고정할지 여부.

encoder_hidden_dim (`int`, *선택 사항*, 기본값 `256`) : 숨겨진 표현의 차원.

encoder_in_channels (`list`, *선택 사항*, 기본값 `[512, 1024, 2048]`) : 인코더에 입력되는 다단계 특징.

feat_strides (`list[int]`, *선택 사항*, 기본값 `[8, 16, 32]`) : 각 feature map에서 사용되는 strides입니다.

encoder_layers (`int`, *선택 사항*, 기본값 `1`) : Transformer 인코더의 숨겨진 레이어 수. 설정되지 않으면 `num_layers`와 동일한 값을 사용합니다.

encoder_ffn_dim (`int`, *선택 사항*, 기본값 `1024`) : 인코더의 "중간"(일반적으로 feed-forward라고도 함) 레이어의 차원.

encoder_attention_heads (`int`, *선택 사항*, 기본값 `8`) : Transformer 인코더의 각 어텐션 레이어에 사용할 어텐션 헤드 수입니다.

dropout (`Union[float, int]`, *선택 사항*, 기본값 `0.0`) : 모든 dropout 레이어에 적용되는 비율입니다.

activation_dropout (`Union[float, int]`, *선택 사항*, 기본값 `0.0`) : 완전 연결 계층 내부 활성화에 적용되는 dropout 비율입니다.

encode_proj_layers (`list[int]`, *선택 사항*, 기본값 `[2]`) : 인코더에서 사용할 투영된 레이어의 인덱스입니다.

positional_encoding_temperature (`int`, *선택 사항*, 기본값 10000) : 위치 인코딩을 생성하는 데 사용되는 temperature 파라미터입니다.

encoder_activation_function (`str`, *선택 사항*, 기본값 `"gelu"`) : 인코더와 풀러에서 사용되는 비선형 활성화 함수(함수 또는 문자열).

activation_function (`str`, *선택 사항*, 기본값 `silu`) : 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열). 예를 들어, `"gelu"`, `"relu"`, `"silu"` 등이 있습니다.

eval_size (`list[int]` 또는 `tuple[int, int]`, *선택 사항*) : 스트라이드를 고려한 후 위치 임베딩의 유효 높이를 계산하는 데 사용되는 높이와 너비.

normalize_before (`bool`, *선택 사항*, 기본값 `False`) : transformer 인코더 레이어에서 self-attention 및 feed-forward 모듈 적용 전에 layer normalization을 적용할지 여부를 결정합니다.

hidden_expansion (`float`, *선택 사항*, 기본값 1.0) : RepVGGBlock과 CSPRepLayer의 차원 크기를 확장하는 확장 비율입니다.

d_model (`int`, *선택 사항*, 기본값 `256`) : 인코더 레이어와 풀러 레이어의 크기.

num_queries (`int`, *선택 사항*, 기본값 300) : 객체 쿼리의 수.

decoder_in_channels (`list`, *선택 사항*, 기본값 `[256, 256, 256]`) : 디코더의 다단계 특징 차원입니다.

decoder_ffn_dim (`int`, *선택 사항*, 기본값 `1024`) : 디코더의 "중간"(일반적으로 feed-forward라고도 함) 레이어의 차원.

num_feature_levels (`int`, *선택 사항*, 기본값 3) : 입력 특징 레벨의 수입니다.

decoder_n_points (`int`, *선택 사항*, 기본값 4) : 디코더의 각 어텐션 헤드에서 각 특징 레벨당 샘플링된 키의 수입니다.

decoder_layers (`int`, *선택 사항*, 기본값 `6`) : Transformer decoder의 숨겨진 레이어 수입니다. 설정하지 않으면 `num_layers`와 동일한 값을 사용합니다.

decoder_attention_heads (`int`, *선택 사항*, 기본값 `8`) : Transformer decoder의 각 attention layer에 사용할 attention head의 수입니다.

decoder_activation_function (`str`, *선택 사항*, 기본값 `"relu"`) : 디코더의 비선형 활성화 함수(함수 또는 문자열).

attention_dropout (`Union[float, int]`, *선택 사항*, 기본값 `0.0`) : attention 확률에 적용할 dropout 비율입니다.

num_denoising (`int`, *선택 사항*, 기본값 100) : 대조적 노이즈 제거에 사용할 노이즈 제거 작업 또는 쿼리의 총 개수입니다.

label_noise_ratio (`float`, *선택 사항*, 기본값 0.5) : 랜덤 노이즈를 추가할 디노이징 레이블의 비율입니다.

box_noise_scale (`float`, *선택 사항*, 기본값 1.0) : 바운딩 박스에 추가할 노이즈의 스케일 또는 크기.

learn_initial_query (`bool`, *선택 사항*, 기본값 `False`) : 학습 중에 디코더의 초기 쿼리 임베딩을 학습할지 여부를 나타냅니다.

anchor_image_size (`tuple[int, int]`, *선택 사항*) : 평가 중에 바운딩 박스 앵커를 생성하는 데 사용되는 입력 이미지의 높이와 너비.

with_box_refine (`bool`, *선택 사항*, 기본값 `True`) : 반복적 바운딩 박스 정제를 적용할지 여부.

matcher_alpha (`float`, *선택 사항*, 기본값 0.25) : Hungarian Matcher에서 사용되는 alpha 매개변수입니다.

matcher_gamma (`float`, *선택 사항*, 기본값 2.0) : Hungarian Matcher에서 사용되는 gamma 매개변수입니다.

matcher_class_cost (`float`, *선택 사항*, 기본값 2.0) : Hungarian Matcher가 사용하는 클래스 손상의 상대적 가중치입니다.

matcher_bbox_cost (`float`, *선택 사항*, 기본값 5.0) : Hungarian Matcher가 사용하는 바운딩 박스 손실의 상대 가중치입니다.

matcher_giou_cost (`float`, *선택 사항*, 기본값 2.0) : Hungarian Matcher가 사용하는 giou loss의 상대적 가중치입니다.

use_focal_loss (`bool`, *선택 사항*, 기본값 `True`) : focal loss를 사용할지 여부를 나타내는 매개변수입니다.

auxiliary_loss (`bool`, *선택 사항*, 기본값 `True`) : 보조 디코딩 손실(각 디코더 레이어의 손실)을 사용할지 여부.

focal_loss_alpha (`float`, *선택 사항*, 기본값 0.75) : focal loss를 계산하는 데 사용되는 alpha 매개변수.

focal_loss_gamma (`float`, *선택 사항*, 기본값 2.0) : focal loss를 계산하는 데 사용되는 gamma 매개변수.

weight_loss_vfl (`float`, *선택 사항*, 기본값 1.0) : 객체 감지 손실에서 varifocal loss의 상대적 가중치.

weight_loss_bbox (`float`, *선택 사항*, 기본값 5.0) : 객체 감지 손실에서 L1 바운딩 박스 손실의 상대적 가중치.

weight_loss_giou (`float`, *선택 사항*, 기본값 2.0) : 객체 감지 손실에서 일반화 IoU 손실의 상대적 가중치.

weight_loss_fgl (`float`, *선택 사항*, 기본값 0.15) : 객체 감지 손실에서 세분화된 위치 지정 손실의 상대적 가중치.

weight_loss_ddf (`float`, *선택 사항*, 기본값 1.5) : 객체 감지 손실에서 분리된 증류 초점 손실의 상대 가중치.

eos_coefficient (`float`, *선택 사항*, 기본값 `0.0001`) : 객체 감지 손실에서 'no-object' 클래스의 상대 분류 가중치입니다.

eval_idx (`int`, *선택 사항*, 기본값 -1) : 평가에 사용할 decoder 레이어의 인덱스.

layer_scale (`float`, *선택 사항*, 기본값 `1.0`) : 후속 decoder 레이어의 hidden dimension에 적용되는 스케일링 계수입니다.

max_num_bins (`int`, *선택 사항*, 기본값 32) : 분포 기반 바운딩 박스 정제에 사용할 최대 빈(bin) 수입니다.

reg_scale (`float`, *선택 사항*, 기본값 4.0) : 회귀 분포의 스케일 팩터입니다.

depth_mult (`float`, *선택 사항*, 기본값 1.0) : RepNCSPELAN5 레이어의 블록 수에 곱해지는 배율입니다.

top_prob_values (`int`, *선택 사항*, 기본값 4) : 각 코너의 분포에서 고려할 상위 확률 값의 개수.

lqe_hidden_dim (`int`, *선택 사항*, 기본값 64) : Location Quality Estimator (LQE) 네트워크의 숨겨진 차원 크기.

lqe_layers (`int`, *선택 사항*, 기본값 2) : Location Quality Estimator MLP의 레이어 수.

decoder_offset_scale (`float`, *선택 사항*, 기본값 0.5) : deformable attention에서 사용되는 offset scale입니다.

decoder_method (`str`, *선택 사항*, 기본값 `"default"`) : 디코더에 사용할 방법: `"default"` 또는 `"discrete"`.

up (`float`, *선택 사항*, 기본값 0.5) : 가중치 함수의 상한을 제어합니다.

tie_word_embeddings (`bool`, *선택 사항*, 기본값 `True`) : 모델의 `tied_weights_keys` 매핑에 따라 가중치 임베딩을 묶을지 여부.

weight_loss_mal (`float`, *선택 사항*, 기본값 1.0) : 객체 감지 손실에서 매칭된 보조 손실의 상대적 가중치.

use_dense_one_to_one (`bool`, *선택 사항*, 기본값 `True`) : 디코더 레이어 전체에 대해 dense one-to-one 매칭을 사용할지 여부.

mal_alpha (`float`, *선택 사항*) : Matching Auxiliary Loss(MAL)의 Alpha 매개변수입니다. `None`인 경우 `focal_loss_alpha`를 사용합니다.

encoder_fuse_op (`str`, *선택 사항*, 기본값 `"sum"`) : 인코더 FPN에서 사용되는 융합 연산입니다. DEIMv2는 D-FINE의 `"cat"` 대신 `"sum"`을 사용합니다.

spatial_tuning_adapter_inplanes (`int`, *선택 사항*, 기본값 16) : STA 컨볼루션 스템의 입력 평면 수.

encoder_type (`str`, *선택 사항*, 기본값 `"hybrid"`) : 사용할 인코더의 유형입니다. `"hybrid"`은 AIFI, FPN, PAN을 갖춘 전체 HybridEncoder를 사용합니다. `"lite"`는 더 작은 변형(Atto, Femto, Pico)을 위해 GAP 융합을 갖춘 경량 LiteEncoder를 사용합니다.

use_gateway (`bool`, *선택 사항*, 기본값 `True`) : 디코더 레이어에서 게이트 메커니즘(크로스 어텐션 게이팅)을 사용할지 여부입니다. `False`인 경우, 인코더 어텐션 출력에 대신 RMSNorm을 사용합니다.

share_bbox_head (`bool`, *선택 사항*, 기본값 `False`) : 모든 decoder 레이어에 걸쳐 bounding box 예측 헤드를 공유할지 여부.

encoder_has_trailing_conv (`bool`, *선택 사항*, 기본값 `True`) : 인코더의 CSP 블록이 bottleneck 경로 뒤에 3x3 컨볼루션을 포함하는지 여부. RepNCSPELAN4(HGNetV2 N 및 LiteEncoder 변형에서 사용)의 경우 `True`입니다. RepNCSPELAN5(DINOv3 변형에서 사용)의 경우 `False`입니다.

이것은 Deimv2Model의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Deimv2 모델을 인스턴스화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [Intellindust/DEIMv2_HGNetv2_N_COCO](https://huggingface.co/Intellindust/DEIMv2_HGNetv2_N_COCO)와 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

## Deimv2Model[[transformers.Deimv2Model]]

#### transformers.Deimv2Model[[transformers.Deimv2Model]]

```python
transformers.Deimv2Model(config: Deimv2Config)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/deimv2/modeling_deimv2.py#L1695)

**매개변수:**

config ([Deimv2Config](/docs/transformers/main/ko/model_doc/deimv2#transformers.Deimv2Config)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

head가 없는 backbone과 encoder-decoder로 구성된 RT-DETR Model이 raw hidden states를 출력합니다.

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### forward[[transformers.Deimv2Model.forward]]

```python
forward(pixel_values: Tensor, pixel_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: list[dict] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/deimv2/modeling_deimv2.py#L1789)

**매개변수:**

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 `image_processor_class`를 사용하여 얻을 수 있습니다. 자세한 내용은 `image_processor_class.__call__`를 참조하세요 (`processor_class`는 이미지 처리에 `image_processor_class`를 사용합니다).

pixel_mask (`torch.LongTensor`, shape `(batch_size, height, width)`, *선택 사항*) : 패딩 픽셀 값에 대한 attention을 수행하지 않도록 하는 마스크. `[0, 1]`에서 선택된 마스크 값: - 실제 픽셀(즉, **마스크되지 않은** 픽셀)은 1, - 패딩 픽셀(즉, **마스크된** 픽셀)은 0. [attention 마스크란?](../glossary#attention-mask)

encoder_outputs (`torch.Tensor`, *선택 사항*) : (`last_hidden_state`, *선택 사항*: `hidden_states`, *선택 사항*: `attentions`) `last_hidden_state`의 shape은 `(batch_size, sequence_length, hidden_size)`, *선택 사항*)이며, 인코더의 마지막 레이어 출력에서 생성된 hidden-states의 시퀀스입니다. 디코더의 cross-attention에 사용됩니다.

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : backbone + projection layer의 출력인 flattened feature map을 전달하는 대신, 이미지의 flattened representation을 직접 전달할 수 있습니다.

labels (`list[Dict]` of len `(batch_size,)`, *optional*) : 이분 매칭 손실을 계산하기 위한 라벨. 딕셔너리의 목록으로, 각 딕셔너리는 최소한 다음 2개의 키를 포함해야 합니다: 'class_labels'와 'boxes' (배치 내 이미지의 클래스 라벨과 바운딩 박스). 클래스 라벨 자체는 len이 `(number of bounding boxes in the image,)`인 `torch.LongTensor`여야 하고, boxes는 shape이 `(number of bounding boxes in the image, 4)`인 `torch.Tensor`여야 합니다.

**반환값:** `Deimv2ModelOutput` 또는 `tuple(torch.Tensor)`

`Deimv2ModelOutput` 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우)로, 구성(`None`) 및 입력에 따라 다양한 요소를 포함합니다.

[Deimv2Model](/docs/transformers/main/ko/model_doc/deimv2#transformers.Deimv2Model)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, num_queries, hidden_size)`) -- 모델의 decoder 마지막 레이어 출력의 hidden-state 시퀀스.
- **intermediate_hidden_states** (`torch.Tensor`, shape `(batch_size, config.decoder_layers, num_queries, hidden_size)`) -- 중간 hidden states의 스택 (decoder의 각 레이어 출력).
- **intermediate_logits** (`torch.Tensor`, shape `(batch_size, config.decoder_layers, sequence_length, config.num_labels)`) -- 스택된 중간 logits (decoder의 각 레이어의 logits).
- **intermediate_reference_points** (`torch.Tensor`, shape `(batch_size, config.decoder_layers, num_queries, 4)`) -- decoder의 각 레이어의 reference point를 스택한 중간 reference point
- **intermediate_predicted_corners** (`torch.Tensor`, shape `(batch_size, config.decoder_layers, num_queries, 4)`) -- 디코더의 각 레이어에서 예측된 코너를 스택한 중간 예측 코너.
- **initial_reference_points** (`torch.Tensor`, shape `(batch_size, num_queries, 4)`) -- 첫 번째 decoder layer에서 사용되는 초기 reference points.
- **decoder_hidden_states** (`tuple[torch.Tensor]`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`인 경우 반환) -- shape가 `(batch_size, sequence_length, hidden_size)`인 `torch.Tensor`의 튜플 (모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개).

  각 레이어의 출력에서 디코더의 Hidden-states와 초기 임베딩 출력을 더한 값.
- **decoder_attentions** (`tuple[torch.Tensor]`, *선택 사항*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어에 하나씩, shape가 `(batch_size, num_heads, sequence_length, sequence_length)`인 `torch.Tensor` 튜플.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는, attention softmax 이후의 decoder의 attention 가중치입니다.
- **cross_attentions** (`tuple[torch.Tensor]`, *선택*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`일 때 반환) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  decoder의 cross-attention 레이어에서 attention softmax를 적용한 후, cross-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention 가중치입니다.
- **encoder_last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) -- 모델 인코더의 마지막 레이어 출력의 hidden-state 시퀀스입니다.
- **encoder_hidden_states** (`tuple[torch.Tensor]`, *선택 사항*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`일 때 반환됩니다) -- `torch.Tensor`의 튜플 (임베딩 레이어가 있는 경우 임베딩 출력용 1개 + 각 레이어의 출력용 1개)로, shape가 `(batch_size, sequence_length, hidden_size)`입니다.

  각 레이어의 출력에서 인코더의 Hidden-states와 초기 임베딩 출력을 더한 값.
- **encoder_attentions** (`tuple[torch.Tensor]`, *선택*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어에 하나씩 포함된 `torch.Tensor` 튜플이며, shape은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  인코더의 어텐션 가중치입니다. 어텐션 softmax 이후에 self-attention 헤드에서 가중 평균을 계산하는 데 사용됩니다.
- **init_reference_points** (shape가 `(batch_size, num_queries, 4)`인 `torch.Tensor`) -- Transformer decoder를 통해 전달되는 초기 참조점.
- **enc_topk_logits** (`torch.Tensor`, shape `(batch_size, sequence_length, config.num_labels)`) -- 인코더 단계에서 상위 `config.two_stage_num_proposals` 점수를 가진 바운딩 박스가 리전 제안으로 선택되는 예측된 바운딩 박스 점수입니다. 바운딩 박스 이진 분류(즉, 포그라운드와 배경)의 출력입니다.
- **enc_topk_bboxes** (`torch.Tensor`, shape `(batch_size, sequence_length, 4)`) -- 인코더 단계에서 예측된 바운딩 박스 좌표의 로짓.
- **enc_outputs_class** (`torch.Tensor`, shape `(batch_size, sequence_length, config.num_labels)`, *선택*, `config.with_box_refine=True`이고 `config.two_stage=True`일 때 반환됨) -- 첫 번째 단계에서 상위 `config.two_stage_num_proposals`개 점수의 바운딩 박스가 영역 제안으로 선택되는 예측된 바운딩 박스 점수입니다. 바운딩 박스 이진 분류(즉, 전경과 배경)의 출력입니다.
- **enc_outputs_coord_logits** (`torch.Tensor`, shape `(batch_size, sequence_length, 4)`, *선택*, `config.with_box_refine=True`이고 `config.two_stage=True`일 때 반환) -- 첫 번째 단계에서 예측된 바운딩 박스 좌표의 logits.
- **denoising_meta_values** (`dict`, *선택 사항*) -- 노이즈 제거 관련 값에 대한 추가 사전입니다.

예:

```python
>>> from transformers import AutoImageProcessor, Deimv2Model
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))

>>> image_processor = AutoImageProcessor.from_pretrained("PekingU/Deimv2_r50vd")
>>> model = Deimv2Model.from_pretrained("PekingU/Deimv2_r50vd")

>>> inputs = image_processor(images=image, return_tensors="pt")

>>> outputs = model(**inputs)

>>> last_hidden_states = outputs.last_hidden_state
>>> list(last_hidden_states.shape)
[1, 300, 256]
```

## Deimv2ForObjectDetection[[transformers.Deimv2ForObjectDetection]]

#### transformers.Deimv2ForObjectDetection[[transformers.Deimv2ForObjectDetection]]

```python
transformers.Deimv2ForObjectDetection(config: Deimv2Config)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/deimv2/modeling_deimv2.py#L2068)

**매개변수:**

config ([Deimv2Config](/docs/transformers/main/ko/model_doc/deimv2#transformers.Deimv2Config)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

RT-DETR 모델(백본과 인코더-디코더로 구성)은 바운딩 박스와 로짓을 출력하며, 이는 점수와 클래스로 추가 디코딩됩니다.

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### forward[[transformers.Deimv2ForObjectDetection.forward]]

```python
forward(pixel_values: Tensor, pixel_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: list[dict] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/deimv2/modeling_deimv2.py#L2107)

**매개변수:**

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 `image_processor_class`를 사용하여 얻을 수 있습니다. 자세한 내용은 `image_processor_class.__call__`를 참조하세요 (`processor_class`는 이미지 처리에 `image_processor_class`를 사용합니다).

pixel_mask (`torch.LongTensor`, shape `(batch_size, height, width)`, *선택 사항*) : 패딩 픽셀 값에 대한 attention을 수행하지 않도록 하는 마스크. `[0, 1]`에서 선택된 마스크 값: - 실제 픽셀(즉, **마스크되지 않은** 픽셀)은 1, - 패딩 픽셀(즉, **마스크된** 픽셀)은 0. [attention 마스크란?](../glossary#attention-mask)

encoder_outputs (`torch.Tensor`, *선택 사항*) : (`last_hidden_state`, *선택 사항*: `hidden_states`, *선택 사항*: `attentions`) `last_hidden_state`의 shape은 `(batch_size, sequence_length, hidden_size)`, *선택 사항*)이며, 인코더의 마지막 레이어 출력에서 생성된 hidden-states의 시퀀스입니다. 디코더의 cross-attention에 사용됩니다.

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

labels (`list[Dict]` of len `(batch_size,)`, *optional*) : 이분 매칭 손실을 계산하기 위한 라벨. 딕셔너리의 목록으로, 각 딕셔너리는 최소한 다음 2개의 키를 포함해야 합니다: 'class_labels'와 'boxes' (배치 내 이미지의 클래스 라벨과 바운딩 박스). 클래스 라벨 자체는 len이 `(number of bounding boxes in the image,)`인 `torch.LongTensor`여야 하고, boxes는 shape이 `(number of bounding boxes in the image, 4)`인 `torch.Tensor`여야 합니다.

**반환값:** `Deimv2ObjectDetectionOutput` 또는 `tuple(torch.Tensor)`

`Deimv2ObjectDetectionOutput` 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되었거나 `config.return_dict=False`인 경우)로, 구성(`None`) 및 입력에 따라 다양한 요소를 포함합니다.

[Deimv2ForObjectDetection](/docs/transformers/main/ko/model_doc/deimv2#transformers.Deimv2ForObjectDetection)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **loss** (`torch.Tensor`, 형상 `(1,)`, *선택 사항*, `labels`가 제공될 때 반환)) -- 클래스 예측에 대한 음의 로그 가능도(교차 엔트로피)와 바운딩 박스 손실의 선형 결합으로 계산된 총 손실입니다. 후자는 L1 손실과 일반화된 스케일 불변 IoU 손실의 선형 결합으로 정의됩니다.
- **loss_dict** (`Dict`, *선택 사항*) -- 개별 손실 값을 포함하는 사전입니다. 로깅에 유용합니다.
- **logits** (`torch.Tensor`, shape `(batch_size, num_queries, num_classes + 1)`) -- 모든 query에 대한 분류 logits(no-object 포함).
- **pred_boxes** (`torch.Tensor`, shape `(batch_size, num_queries, 4)`) -- 모든 쿼리에 대한 정규화된 박스 좌표로, (center_x, center_y, width, height) 형식으로 표현됩니다. 이 값들은 배치 내 각 개별 이미지의 크기에 대해 [0, 1] 범위로 정규화되며, 가능한 패딩은 무시됩니다. 정규화되지 않은(절대) 바운딩 박스를 가져오려면 `~Deimv2ImageProcessor.post_process_object_detection`을 사용할 수 있습니다.
- **auxiliary_outputs** (`list[Dict]`, *선택*) -- 선택 사항이며, 보조 손실이 활성화된 경우(즉, `config.auxiliary_loss`가 `True`로 설정된 경우)와 라벨이 제공된 경우에만 반환됩니다. 각 디코더 레이어에 대해 위의 두 키(`logits`와 `pred_boxes`)를 포함하는 사전의 목록입니다.
- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, num_queries, hidden_size)`) -- 모델의 decoder 마지막 레이어 출력의 hidden-state 시퀀스.
- **intermediate_hidden_states** (`torch.Tensor`, shape `(batch_size, config.decoder_layers, num_queries, hidden_size)`) -- 중간 hidden states의 스택 (decoder의 각 레이어 출력).
- **intermediate_logits** (`torch.Tensor`, shape `(batch_size, config.decoder_layers, num_queries, config.num_labels)`) -- 스택된 중간 logits (decoder의 각 레이어의 logits).
- **intermediate_reference_points** (`torch.Tensor`, shape `(batch_size, config.decoder_layers, num_queries, 4)`) -- decoder의 각 레이어의 reference point를 스택한 중간 reference point
- **intermediate_predicted_corners** (`torch.Tensor`, shape `(batch_size, config.decoder_layers, num_queries, 4)`) -- 디코더의 각 레이어에서 예측된 코너를 스택한 중간 예측 코너.
- **initial_reference_points** (`torch.Tensor`, shape `(batch_size, config.decoder_layers, num_queries, 4)`) -- 스택된 초기 참조 점(decoder의 각 레이어의 초기 참조 점).
- **decoder_hidden_states** (`tuple[torch.Tensor]`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`인 경우 반환) -- shape가 `(batch_size, sequence_length, hidden_size)`인 `torch.Tensor`의 튜플 (모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개).

  각 레이어의 출력에서 디코더의 Hidden-states와 초기 임베딩 출력을 더한 값.
- **decoder_attentions** (`tuple[torch.Tensor]`, *선택 사항*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어에 하나씩, shape가 `(batch_size, num_heads, sequence_length, sequence_length)`인 `torch.Tensor` 튜플.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는, attention softmax 이후의 decoder의 attention 가중치입니다.
- **cross_attentions** (`tuple[torch.Tensor]`, *선택*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`일 때 반환) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, shape는 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  decoder의 cross-attention 레이어에서 attention softmax를 적용한 후, cross-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention 가중치입니다.
- **encoder_last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) -- 모델 인코더의 마지막 레이어 출력의 hidden-state 시퀀스입니다.
- **encoder_hidden_states** (`tuple[torch.Tensor]`, *선택 사항*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`일 때 반환됩니다) -- `torch.Tensor`의 튜플 (임베딩 레이어가 있는 경우 임베딩 출력용 1개 + 각 레이어의 출력용 1개)로, shape가 `(batch_size, sequence_length, hidden_size)`입니다.

  각 레이어의 출력에서 인코더의 Hidden-states와 초기 임베딩 출력을 더한 값.
- **encoder_attentions** (`tuple[torch.Tensor]`, *선택*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어에 하나씩 포함된 `torch.Tensor` 튜플이며, shape은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  인코더의 어텐션 가중치입니다. 어텐션 softmax 이후에 self-attention 헤드에서 가중 평균을 계산하는 데 사용됩니다.
- **init_reference_points** (`torch.Tensor`, shape `(batch_size, num_queries, 4)`) -- Transformer decoder를 통해 전달되는 초기 reference points.
- **enc_topk_logits** (`torch.Tensor`, shape `(batch_size, sequence_length, config.num_labels)`, *선택 사항*, `config.with_box_refine=True`이고 `config.two_stage=True`일 때 반환됨) -- 인코더에서 예측된 바운딩 박스 좌표의 로짓입니다.
- **enc_topk_bboxes** (`torch.Tensor`, shape `(batch_size, sequence_length, 4)`, *선택 사항*, `config.with_box_refine=True`이고 `config.two_stage=True`일 때 반환됨) -- 인코더에서 예측된 바운딩 박스 좌표의 로짓.
- **enc_outputs_class** (`torch.Tensor`, shape `(batch_size, sequence_length, config.num_labels)`, *선택*, `config.with_box_refine=True`이고 `config.two_stage=True`일 때 반환됨) -- 첫 번째 단계에서 상위 `config.two_stage_num_proposals`개 점수의 바운딩 박스가 영역 제안으로 선택되는 예측된 바운딩 박스 점수입니다. 바운딩 박스 이진 분류(즉, 전경과 배경)의 출력입니다.
- **enc_outputs_coord_logits** (`torch.Tensor`, shape `(batch_size, sequence_length, 4)`, *선택*, `config.with_box_refine=True`이고 `config.two_stage=True`일 때 반환) -- 첫 번째 단계에서 예측된 바운딩 박스 좌표의 logits.
- **denoising_meta_values** (`dict`, *선택 사항*) -- 디노이징 관련 값에 대한 추가 사전

예:

```python
>>> import torch
>>> from transformers.image_utils import load_image
>>> from transformers import AutoImageProcessor, Deimv2ForObjectDetection

>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> image = load_image(url)

>>> image_processor = AutoImageProcessor.from_pretrained("harshaljanjani/DEIMv2_HGNetv2_N_COCO_Transformers")
>>> model = Deimv2ForObjectDetection.from_pretrained("harshaljanjani/DEIMv2_HGNetv2_N_COCO_Transformers")

>>> # prepare image for the model
>>> inputs = image_processor(images=image, return_tensors="pt")

>>> # forward pass
>>> outputs = model(**inputs)

>>> logits = outputs.logits
>>> list(logits.shape)
[1, 300, 80]

>>> boxes = outputs.pred_boxes
>>> list(boxes.shape)
[1, 300, 4]

>>> # convert outputs (bounding boxes and class logits) to Pascal VOC format (xmin, ymin, xmax, ymax)
>>> target_sizes = torch.tensor([image.size[::-1]])
>>> results = image_processor.post_process_object_detection(outputs, threshold=0.9, target_sizes=target_sizes)
>>> result = results[0]  # first image in batch

>>> for score, label, box in zip(result["scores"], result["labels"], result["boxes"]):
...     box = [round(i, 2) for i in box.tolist()]
...     print(
...         f"Detected {model.config.id2label[label.item()]} with confidence "
...         f"{round(score.item(), 3)} at location {box}"
...     )
```