# HGNet-V2

[HGNetV2](https://github.com/PaddlePaddle/PaddleClas/blob/v2.6.0/docs/zh_CN/models/ImageNet1k/PP-HGNetV2.md)는 NVIDIA GPU에서 최적의 정확도-지연 시간 트레이드오프를 위해 설계된 차세대 합성곱 신경망(CNN) 백본입니다. 기존 [HGNet](https://github.com/PaddlePaddle/PaddleClas/blob/v2.6.0/docs/en/models/PP-HGNet_en.md)을 기반으로 한 HGNetV2는 빠른 추론 속도로 높은 정확도를 제공하며, 이미지 분류, 객체 감지, 분할과 같은 작업에서 뛰어난 성능을 발휘하여 GPU 기반 컴퓨터 비전 애플리케이션에 실용적인 선택지가 됩니다.

모든 원본 HGNet V2 모델은 [USTC](https://huggingface.co/ustc-community/models?search=hgnet) 조직에서 찾을 수 있습니다.

> [!TIP]
> 이 모델은 [VladOS95-cyber](https://github.com/VladOS95-cyber)에 의해 기여되었습니다. HGNet V2를 다양한 컴퓨터 비전 작업에 적용하는 방법에 대한 추가 예제는 오른쪽 사이드바의 HGNet V2 모델들을 클릭하여 확인하세요.

아래 예제는 [Pipeline](/docs/transformers/main/ko/main_classes/pipelines#transformers.Pipeline) 또는 [AutoModel](/docs/transformers/main/ko/model_doc/auto#transformers.AutoModel) 클래스를 사용하여 이미지를 분류하는 방법을 보여줍니다.

```python
from transformers import pipeline

pipeline = pipeline(
    task="image-classification",
    model="ustc-community/hgnet-v2",
    device=0
)
pipeline("http://images.cocodataset.org/val2017/000000039769.jpg")
```

```python
import requests
import torch
from PIL import Image

from transformers import AutoImageProcessor, HGNetV2ForImageClassification

url = "http://images.cocodataset.org/val2017/000000039769.jpg"
image = Image.open(requests.get(url, stream=True).raw)

model = HGNetV2ForImageClassification.from_pretrained("ustc-community/hgnet-v2", device_map="auto")
processor = AutoImageProcessor.from_pretrained("ustc-community/hgnet-v2")

inputs = processor(images=image, return_tensors="pt").to(model.device)
with torch.no_grad():
    logits = model(**inputs).logits
predicted_class_id = logits.argmax(dim=-1).item()

class_labels = model.config.id2label
predicted_class_label = class_labels[predicted_class_id]
print(f"The predicted class label is: {predicted_class_label}")
```

## HGNetV2Config[[transformers.HGNetV2Config]]

#### transformers.HGNetV2Config[[transformers.HGNetV2Config]]

```python
transformers.HGNetV2Config(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, is_encoder_decoder: bool = False, 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, num_channels: int = 3, embedding_size: int = 64, depths: list[int] | tuple[int, ...] = (3, 4, 6, 3), hidden_sizes: list[int] | tuple[int, ...] = (256, 512, 1024, 2048), hidden_act: str = 'relu', _out_features: list[str] | None = None, _out_indices: list[int] | None = None, stem_channels: list[int] | tuple[int, ...] = (3, 32, 48), stem_strides: Sequence = (2, 1, 1, 2, 1), stage_in_channels: list[int] | tuple[int, ...] = (48, 128, 512, 1024), stage_mid_channels: list[int] | tuple[int, ...] = (48, 96, 192, 384), stage_out_channels: list[int] | tuple[int, ...] = (128, 512, 1024, 2048), stage_num_blocks: list[int] | tuple[int, ...] = (1, 1, 3, 1), stage_downsample: list[bool] | tuple[bool, ...] = (False, True, True, True), stage_downsample_strides: Sequence = (2, 2, 2, 2), stage_light_block: list[bool] | tuple[bool, ...] = (False, False, True, True), stage_kernel_size: list[int] | tuple[int, ...] = (3, 3, 5, 5), stage_numb_of_layers: list[int] | tuple[int, ...] = (6, 6, 6, 6), use_learnable_affine_block: bool = False, initializer_range: float = 0.02)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hgnet_v2/configuration_hgnet_v2.py#L35)

**매개변수:**

num_channels (`int`, *선택 사항*, 기본값 `3`) : 입력 채널의 수입니다.

embedding_size (`int`, *선택 사항*, 기본값 `64`) : 임베딩 및 숨겨진 상태의 차원.

depths (`Union[list[int], tuple[int, ...]]`, *선택 사항*, 기본값 `(3, 4, 6, 3)`) : Transformer의 각 레이어 깊이.

hidden_sizes (`Union[list[int], tuple[int, ...]]`, *선택 사항*, 기본값 `(256, 512, 1024, 2048)`) : 모델의 각 단계별 차원(숨겨진 크기).

hidden_act (`str`, *선택 사항*, 기본값 `relu`) : 디코더의 비선형 활성화 함수(함수 또는 문자열). 예를 들어, `"gelu"`, `"relu"`, `"silu"` 등.

stem_channels (`list[int]`, *선택 사항*, 기본값 `[3, 32, 48]`) : stem 레이어의 채널 차원입니다: - 첫 번째 숫자(3)는 입력 이미지 채널 - 두 번째 숫자(32)는 중간 stem 채널 - 세 번째 숫자(48)는 출력 stem 채널

stem_strides (`Sequence[int | list[int] | tuple[int, ...]]`, *선택 사항*, 기본값은 `(2, 1, 1, 2, 1)`) : stem 레이어의 스트라이드 패턴입니다.

stage_in_channels (`list[int]`, *선택 사항*, 기본값 `[48, 128, 512, 1024]`) : 백본의 각 단계에 대한 입력 채널 차원입니다. 이는 각 단계의 입력이 가질 채널 수를 정의합니다.

stage_mid_channels (`list[int]`, *선택 사항*, 기본값 `[48, 96, 192, 384]`) : 백본의 각 단계별 중간 채널 차원입니다. 이는 각 단계의 중간 레이어에서 사용되는 채널 수를 정의합니다.

stage_out_channels (`list[int]`, *선택 사항*, 기본값 `[128, 512, 1024, 2048]`) : 백본의 각 단계에 대한 출력 채널 차원입니다. 이는 각 단계의 출력이 가질 채널 수를 정의합니다.

stage_num_blocks (`list[int]`, *선택 사항*, 기본값 `[1, 1, 3, 1]`) : 백본의 각 단계에 사용할 블록 수입니다. 이는 컨볼루션 블록을 얼마나 쌓을지 지정하여 각 단계의 깊이를 제어합니다.

stage_downsample (`list[bool]`, *선택 사항*, 기본값 `[False, True, True, True]`) : 각 단계에서 feature map을 다운샘플링할지 여부를 나타냅니다. `True`인 경우 feature map의 공간 차원이 축소됩니다.

stage_downsample_strides (`Sequence[int | list[int] | tuple[int, ...]]`, *선택 사항*, 기본값 `(2, 2, 2, 2)`) : 각 stage layer의 stride 패턴입니다.

stage_light_block (`list[bool]`, *선택 사항*, 기본값 `[False, False, True, True]`) : 각 단계에서 light block을 사용할지 여부를 나타냅니다. Light block은 매개변수가 더 적을 수 있는 컨볼루션 블록의 변형입니다.

stage_kernel_size (`list[int]`, *선택 사항*, 기본값 `[3, 3, 5, 5]`) : 각 단계의 합성곱 계층에 사용되는 커널 크기입니다.

stage_numb_of_layers (`list[int]`, *선택 사항*, 기본값 `[6, 6, 6, 6]`) : 각 스테이지의 블록에 사용할 레이어 수입니다.

use_learnable_affine_block (`bool`, *선택 사항*, 기본값 `False`) : 네트워크에서 Learnable Affine Blocks(LAB)를 사용할지 여부입니다. LAB은 특정 연산 이후에 학습 가능한 scale 및 bias 매개변수를 추가합니다.

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

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

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

## HGNetV2Backbone[[transformers.HGNetV2Backbone]]

#### transformers.HGNetV2Backbone[[transformers.HGNetV2Backbone]]

```python
transformers.HGNetV2Backbone(config: HGNetV2Config)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hgnet_v2/modeling_hgnet_v2.py#L343)

#### forward[[transformers.HGNetV2Backbone.forward]]

```python
forward(pixel_values: Tensor, output_hidden_states: bool | None = None, return_dict: bool | None = None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hgnet_v2/modeling_hgnet_v2.py#L356)

**매개변수:**

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`를 사용합니다).

output_hidden_states (`bool`, *선택 사항*) : 모든 레이어의 hidden states를 반환할지 여부. 자세한 내용은 반환되는 텐서 중 `hidden_states` 항목을 참조하세요.

return_dict (`bool`, *선택 사항*) : 일반 튜플 대신 [ModelOutput](/docs/transformers/main/ko/main_classes/output#transformers.utils.ModelOutput)를 반환할지 여부.

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

구성([HGNetV2Config](/docs/transformers/main/ko/model_doc/hgnet_v2#transformers.HGNetV2Config))과 입력에 따라 다양한 요소를 포함하는 `BackboneOutput` 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우).

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

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

- **feature_maps** (`tuple(torch.Tensor)`, shape `(batch_size, num_channels, height, width)`) -- 각 단계의 feature maps.
- **hidden_states** (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`인 경우 반환) -- 백본에 따라 shape가 `(batch_size, sequence_length, hidden_size)` 또는 `(batch_size, num_channels, height, width)`인 `torch.Tensor` 튜플 (임베딩 출력 1개 + 각 레이어 출력 1개)

  각 단계의 출력에서 모델의 Hidden-states와 초기 임베딩 출력을 포함합니다.
- **attentions** (`tuple(torch.Tensor)`, *선택*, `output_attentions=True`가 전달되거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어당 하나씩, shape가 `(batch_size, num_heads, sequence_length, sequence_length)`인 `torch.Tensor`의 튜플. backbone이 attention을 사용하는 경우에만 적용됩니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.

예:

```python
>>> from transformers import HGNetV2Config, HGNetV2Backbone
>>> import torch

>>> config = HGNetV2Config()
>>> model = HGNetV2Backbone(config)

>>> pixel_values = torch.randn(1, 3, 224, 224)

>>> with torch.no_grad():
...     outputs = model(pixel_values)

>>> feature_maps = outputs.feature_maps
>>> list(feature_maps[-1].shape)
[1, 2048, 7, 7]
```

## HGNetV2ForImageClassification[[transformers.HGNetV2ForImageClassification]]

#### transformers.HGNetV2ForImageClassification[[transformers.HGNetV2ForImageClassification]]

```python
transformers.HGNetV2ForImageClassification(config: HGNetV2Config)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hgnet_v2/modeling_hgnet_v2.py#L420)

**매개변수:**

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

이미지 분류 헤드가 위에 있는 HGNetV2 모델(풀링된 특징 위에 선형 레이어가 있는 형태)로, 예: ImageNet

이 모델은 [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.HGNetV2ForImageClassification.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/hgnet_v2/modeling_hgnet_v2.py#L436)

**매개변수:**

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`를 사용합니다).

labels (`torch.LongTensor`, shape `(batch_size,)`, *선택 사항*) : 이미지 분류/회귀 손실을 계산하는 데 사용되는 라벨. 인덱스는 `[0, ..., config.num_labels - 1]` 범위에 있어야 합니다. `config.num_labels == 1`인 경우 회귀 손실(평균 제곱 손실)이 계산되고, `config.num_labels > 1`인 경우 분류 손실(크로스 엔트로피)이 계산됩니다.

output_hidden_states (`bool`, *선택 사항*) : 모든 레이어의 hidden states를 반환할지 여부. 자세한 내용은 반환되는 텐서 중 `hidden_states` 항목을 참조하세요.

return_dict (`bool`, *선택 사항*) : 일반 튜플 대신 [ModelOutput](/docs/transformers/main/ko/main_classes/output#transformers.utils.ModelOutput)를 반환할지 여부.

**반환값:** [ImageClassifierOutputWithNoAttention](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.ImageClassifierOutputWithNoAttention) 또는 `tuple(torch.Tensor)`

[ImageClassifierOutputWithNoAttention](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.ImageClassifierOutputWithNoAttention) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되었거나 `config.return_dict=False`인 경우)로, 구성([HGNetV2Config](/docs/transformers/main/ko/model_doc/hgnet_v2#transformers.HGNetV2Config))과 입력에 따라 다양한 요소를 포함합니다.

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

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

- **loss** (`torch.Tensor`, shape `(1,)`, *선택*, `labels`이 제공될 때 반환됨) -- 분류(또는 config.num_labels==1인 경우 회귀) 손실.
- **logits** (`torch.Tensor`, shape `(batch_size, config.num_labels)`) -- SoftMax 적용 전 분류(또는 config.num_labels==1인 경우 회귀) 점수.
- **hidden_states** (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`인 경우 반환) -- `torch.Tensor`의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력용 1개 + 각 단계 출력용 1개)로, shape은 `(batch_size, num_channels, height, width)`입니다. 각 단계 출력 시점의 모델 hidden-states(또는 feature maps)입니다.

예:
```python
>>> import torch
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import HGNetV2ForImageClassification, AutoImageProcessor
>>> from PIL import Image

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

>>> model = HGNetV2ForImageClassification.from_pretrained("ustc-community/hgnet-v2")
>>> processor = AutoImageProcessor.from_pretrained("ustc-community/hgnet-v2")

>>> inputs = processor(images=image, return_tensors="pt")
>>> with torch.no_grad():
...     outputs = model(**inputs)
>>> outputs.logits.shape
torch.Size([1, 2])
```