# UPerNet

## 개요

UPerNet 모델은 Tete Xiao, Yingcheng Liu, Bolei Zhou, Yuning Jiang, Jian Sun이 [Unified Perceptual Parsing for Scene Understanding](https://huggingface.co/papers/1807.10221)에서 제안했습니다. UPerNet은 [ConvNeXt](convnext) 또는 [Swin](swin)과 같은 다양한 비전 백본을 활용하여 이미지에서 폭넓은 개념을 효과적으로 분할하기 위한 범용 프레임워크입니다.

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

*인간은 여러 수준에서 시각적 세계를 인식합니다. 우리는 장면을 자연스럽게 분류하고 그 안의 객체를 감지하는 동시에, 객체의 질감과 표면 및 다양한 구성 요소를 식별합니다. 이 논문에서는 주어진 이미지에서 가능한 한 많은 시각 개념을 인식해야 하는 새로운 작업인 Unified Perceptual Parsing을 연구합니다. 이질적인 이미지 주석에서 학습하기 위해 다중 작업 프레임워크인 UPerNet과 학습 전략을 개발했습니다. 제안한 프레임워크를 Unified Perceptual Parsing에 대해 벤치마크하여, 이미지에서 다양한 개념을 효과적으로 분할할 수 있음을 보여줍니다. 학습된 네트워크는 자연 장면에서 시각적 지식을 발견하는 데 추가로 적용됩니다.*

<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/upernet_architecture.jpg"
alt="drawing" width="600"/>

 UPerNet 프레임워크. 원 논문에서 가져왔습니다.

이 모델은 [nielsr](https://huggingface.co/nielsr)에 의해 기여되었습니다. 원래 코드는 OpenMMLab의 mmsegmentation [여기](https://github.com/open-mmlab/mmsegmentation/blob/master/mmseg/models/decode_heads/uper_head.py)에 기반합니다.

## 사용 예시

UPerNet은 의미론적 분할을 위한 범용 프레임워크입니다. 다음과 같이 어떤 비전 백본과도 함께 사용할 수 있습니다:

```python
from transformers import SwinConfig, UperNetConfig, UperNetForSemanticSegmentation

backbone_config = SwinConfig(out_features=["stage1", "stage2", "stage3", "stage4"])

config = UperNetConfig(backbone_config=backbone_config)
model = UperNetForSemanticSegmentation(config)
```

ConvNeXt와 같은 다른 비전 백본을 사용하려면, [ConvNeXt](convnext)와 같은 적절한 백본으로 모델을 인스턴스화하면 됩니다:

```python
from transformers import ConvNextConfig, UperNetConfig, UperNetForSemanticSegmentation

backbone_config = ConvNextConfig(out_features=["stage1", "stage2", "stage3", "stage4"])

config = UperNetConfig(backbone_config=backbone_config)
model = UperNetForSemanticSegmentation(config)
```

이 과정은 모델의 모든 가중치를 무작위로 초기화합니다.

## 리소스

🌎 표시로 커뮤니티 리소스를 구분하여, UPerNet 시작을 돕는 Hugging Face 공식 및 커뮤니티 리소스 목록입니다.

- UPerNet 데모 노트북은 [여기](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/UPerNet)에서 찾을 수 있습니다.
- 이 [노트북](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/semantic_segmentation.ipynb)은 [UperNetForSemanticSegmentation](/docs/transformers/v5.23.0/ko/model_doc/upernet#transformers.UperNetForSemanticSegmentation)을 지원합니다.
- 참고: [의미론적 분할 작업 가이드](../tasks/semantic_segmentation)

여기에 포함할 리소스를 제출하고 싶으시면 Pull Request를 열어 주시면 검토하겠습니다! 기존 리소스와 중복되지 않고 새로운 것을 보여주는 것이 이상적입니다.

## UperNetConfig[[transformers.UperNetConfig]]

#### transformers.UperNetConfig[[transformers.UperNetConfig]]

```python
transformers.UperNetConfig(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, backbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, hidden_size: int = 512, initializer_range: float = 0.02, pool_scales: list[int] | tuple[int, ...] = (1, 2, 3, 6), use_auxiliary_head: bool = True, auxiliary_loss_weight: float = 0.4, auxiliary_in_channels: int | None = None, auxiliary_channels: int = 256, auxiliary_num_convs: int = 1, auxiliary_concat_input: bool = False, loss_ignore_index: int = 255)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/upernet/configuration_upernet.py#L25)

**매개변수:**

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

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

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

pool_scales (`tuple[int]`, *선택 사항*, 기본값 `[1, 2, 3, 6]`) : 마지막 feature map에 적용되는 Pooling Pyramid Module에서 사용되는 pooling scale입니다.

use_auxiliary_head (`bool`, *선택 사항*, 기본값 `True`) : 학습 중에 보조 헤드를 사용할지 여부.

auxiliary_loss_weight (`float`, *선택 사항*, 기본값 0.4) : 보조 헤드의 교차 엔트로피 손실 가중치.

auxiliary_in_channels (`int`, *선택 사항*, 기본값 256) : 보조 헤드(auxiliary head)의 입력 채널 수.

auxiliary_channels (`int`, *선택 사항*, 기본값 256) : 보조 헤드에 사용할 채널 수.

auxiliary_num_convs (`int`, *선택 사항*, 기본값 1) : 보조 헤드에 사용할 컨볼루션 레이어의 수.

auxiliary_concat_input (`bool`, *선택 사항*, 기본값 `False`) : 분류 레이어 전에 보조 헤드(auxiliary head)의 출력을 입력과 연결(concatenate)할지 여부.

loss_ignore_index (`int`, *선택 사항*, 기본값 255) : 손실 함수가 무시하는 인덱스입니다.

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

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

예:

```python
>>> from transformers import UperNetConfig, UperNetForSemanticSegmentation

>>> # Initializing a configuration
>>> configuration = UperNetConfig()

>>> # Initializing a model (with random weights) from the configuration
>>> model = UperNetForSemanticSegmentation(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## UperNetForSemanticSegmentation[[transformers.UperNetForSemanticSegmentation]]

#### transformers.UperNetForSemanticSegmentation[[transformers.UperNetForSemanticSegmentation]]

```python
transformers.UperNetForSemanticSegmentation(config: UperNetConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/upernet/modeling_upernet.py#L278)

**매개변수:**

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

ADE20k, CityScapes 등에 사용할 수 있는 임의의 비전 백본을 활용하는 UperNet 프레임워크.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/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.UperNetForSemanticSegmentation.forward]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/upernet/modeling_upernet.py#L293)

**매개변수:**

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [SegformerImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/segformer#transformers.SegformerImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [SegformerImageProcessor.__call__()](/docs/transformers/v5.23.0/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하세요 (`processor_class`는 이미지 처리에 [SegformerImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/segformer#transformers.SegformerImageProcessor)를 사용합니다).

output_attentions (`bool`, *선택 사항*) : 모든 어텐션 레이어의 어텐션 텐서를 반환할지 여부. 자세한 내용은 반환 텐서 섹션의 `attentions`를 참조하세요.

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

labels (`torch.LongTensor`, shape `(batch_size, height, width)`, *선택 사항*) : 손실을 계산하기 위한 ground truth semantic segmentation 맵입니다. 인덱스는 `[0, ..., config.num_labels - 1]` 범위에 있어야 합니다. `config.num_labels > 1`인 경우, 분류 손실(Cross-Entropy)이 계산됩니다.

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

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

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

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

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

- **loss** (`torch.Tensor`, shape `(1,)`, *선택*, `labels`이 제공될 때 반환됨) -- 분류(또는 config.num_labels==1인 경우 회귀) 손실.
- **logits** (shape `(batch_size, config.num_labels, logits_height, logits_width)`의 `torch.Tensor`) -- 각 픽셀에 대한 분류 점수입니다.

  

  반환되는 logits는 입력으로 전달된 `pixel_values`와 반드시 동일한 크기를 갖지 않습니다. 이는 사용자가 후처리 단계에서 logits를 원본 이미지 크기로 리사이즈할 때 두 번의 보간을 수행하여 품질이 저하되는 것을 방지하기 위한 것입니다. 항상 logits의 shape을 확인하고 필요에 따라 리사이즈해야 합니다.

  
- **hidden_states** (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`일 때 반환) -- shape가 `(batch_size, patch_size, hidden_size)`인 `torch.Tensor`의 튜플 (모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개).

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

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

예:
```python
>>> from transformers import AutoImageProcessor, UperNetForSemanticSegmentation
>>> from PIL import Image
>>> from huggingface_hub import hf_hub_download

>>> image_processor = AutoImageProcessor.from_pretrained("openmmlab/upernet-convnext-tiny")
>>> model = UperNetForSemanticSegmentation.from_pretrained("openmmlab/upernet-convnext-tiny")

>>> filepath = hf_hub_download(
...     repo_id="hf-internal-testing/fixtures_ade20k", filename="ADE_val_00000001.jpg", repo_type="dataset"
... )
>>> image = Image.open(filepath).convert("RGB")

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

>>> outputs = model(**inputs)

>>> logits = outputs.logits  # shape (batch_size, num_labels, height, width)
>>> list(logits.shape)
[1, 150, 512, 512]
```

