Transformers documentation
UPerNet
이 모델은 2018-07-26에 HF papers에 게시되었으며, 2023-01-16에 Hugging Face Transformers에 기여되었습니다.
UPerNet
개요
UPerNet 모델은 Tete Xiao, Yingcheng Liu, Bolei Zhou, Yuning Jiang, Jian Sun이 Unified Perceptual Parsing for Scene Understanding에서 제안했습니다. UPerNet은 ConvNeXt 또는 Swin과 같은 다양한 비전 백본을 활용하여 이미지에서 폭넓은 개념을 효과적으로 분할하는 범용 프레임워크입니다.
해당 논문의 초록은 다음과 같습니다:
인간은 여러 수준에서 시각적 세계를 인식합니다. 우리는 장면을 자연스럽게 분류하고 그 안의 객체를 감지하는 동시에, 객체의 질감과 표면 및 다양한 구성 요소를 식별합니다. 이 논문에서는 주어진 이미지에서 가능한 한 많은 시각 개념을 인식해야 하는 새로운 작업인 Unified Perceptual Parsing을 연구합니다. 이질적인 이미지 주석에서 학습하기 위해 다중 작업 프레임워크인 UPerNet과 학습 전략을 개발했습니다. 제안한 프레임워크를 Unified Perceptual Parsing에 대해 벤치마크하여, 이미지에서 다양한 개념을 효과적으로 분할할 수 있음을 보여줍니다. 학습된 네트워크는 자연 장면에서 시각적 지식을 발견하는 데 추가로 적용됩니다.
UPerNet framework. Taken from the original paper. 이 모델은 nielsr에 의해 기여되었습니다. 원본 코드는 OpenMMLab의 mmsegmentation 여기에 기반합니다.
사용 예시
UPerNet은 의미론적 분할을 위한 범용 프레임워크입니다. 다음과 같이 어떤 비전 백본과도 함께 사용할 수 있습니다:
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와 같은 적절한 백본으로 모델을 인스턴스화하면 됩니다:
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 데모 노트북은 여기에서 찾을 수 있습니다.
- 이 노트북은 UperNetForSemanticSegmentation을 지원합니다.
- 참고: 의미론적 분할 작업 가이드
여기에 포함할 리소스를 제출하고 싶으시면 Pull Request를 열어 주시면 검토하겠습니다! 기존 리소스와 중복되지 않고 새로운 것을 보여주는 것이 이상적입니다.
UperNetConfig
class transformers.UperNetConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonebackbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonehidden_size: int = 512initializer_range: float = 0.02pool_scales: list[int] | tuple[int, ...] = (1, 2, 3, 6)use_auxiliary_head: bool = Trueauxiliary_loss_weight: float = 0.4auxiliary_in_channels: int | None = Noneauxiliary_channels: int = 256auxiliary_num_convs: int = 1auxiliary_concat_input: bool = Falseloss_ignore_index: int = 255 )
매개변수
- backbone_config (
Union[dict, ~configuration_utils.PreTrainedConfig], 선택) — backbone 모델의 설정입니다. - 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)의 출력을 분류 계층(classification layer) 전에 입력과 연결(concatenate)할지 여부. - loss_ignore_index (
int, 선택 사항, 기본값 255) — 손실 함수에서 무시되는 인덱스입니다.
이것은 UpernetModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Upernet 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 openmmlab/upernet-convnext-tiny와 유사한 구성이 생성됩니다.
Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.
예:
>>> 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.configUperNetForSemanticSegmentation
class transformers.UperNetForSemanticSegmentation
< source >( config: UperNetConfig )
매개변수
- config (UperNetConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
ADE20k, CityScapes 등에 사용할 수 있는 임의의 비전 백본을 활용하는 UperNet 프레임워크.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = Noneoutput_attentions: bool | None = Noneoutput_hidden_states: bool | None = Nonelabels: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = None**kwargs ) → SemanticSegmenterOutput or tuple(torch.Tensor)
매개변수
- pixel_values (
torch.Tensor, shape(batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 SegformerImageProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 SegformerImageProcessor.call()를 참조하세요 (processor_class는 이미지 처리에 SegformerImageProcessor를 사용합니다). - output_attentions (
bool, 선택 사항) — 모든 attention 레이어의 attentions 텐서를 반환할지 여부. 자세한 내용은 반환 텐서 섹션의attentions항목을 참조하세요. - output_hidden_states (
bool, 선택 사항) — 모든 레이어의 hidden states를 반환할지 여부입니다. 자세한 내용은 반환되는 텐서 중hidden_states항목을 참고하세요. - labels (
torch.LongTensor, shape(batch_size, height, width), 선택 사항) — 손실 계산에 사용되는 ground truth semantic segmentation map입니다. 인덱스는[0, ..., config.num_labels - 1]범위에 있어야 합니다.config.num_labels > 1인 경우, 분류 손실(Cross-Entropy)이 계산됩니다. - return_dict (
bool, 선택) — 일반 튜플 대신 ModelOutput를 반환할지 여부.
반환값
SemanticSegmenterOutput 또는 tuple(torch.Tensor)
torch.Tensor의 튜플 또는 SemanticSegmenterOutput입니다. return_dict=False가 전달되거나 config.return_dict=False인 경우, UperNetConfig와 입력에 따라 다양한 요소로 구성됩니다.
UperNetForSemanticSegmentation의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
loss (
torch.Tensor, shape(1,), 선택 사항,labels이 제공될 때 반환됨) — 분류 (또는 config.num_labels==1인 경우 회귀) 손실.logits (
torch.Tensor, shape(batch_size, config.num_labels, logits_height, logits_width)) — 각 픽셀에 대한 분류 점수.pixel_values로 전달된 입력과 반환되는 logits의 크기가 항상 동일하지는 않습니다. 이는 사용자가 후처리 단계에서 logits를 원본 이미지 크기로 리사이즈할 때 두 번의 보간을 수행하여 품질이 저하되는 것을 방지하기 위한 것입니다. 따라서 logits의 shape을 항상 확인하고 필요에 따라 리사이즈해야 합니다.hidden_states (
tuple(torch.Tensor), 선택 사항,output_hidden_states=True가 전달되거나config.output_hidden_states=True인 경우 반환됨) —torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은(batch_size, patch_size, hidden_size)입니다.각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
attentions (
tuple(torch.Tensor), 선택 사항,output_attentions=True가 전달되었거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, patch_size, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.
예:
>>> 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]