# 컨볼루션 비전 트랜스포머(CvT)

[Convolutional Vision Transformer (CvT)](https://huggingface.co/papers/2103.15808)은 컴퓨터 비전 작업을 위해 합성곱 신경망(CNN)과 Vision Transformer의 장점을 결합한 모델입니다. Vision Transformer 아키텍처에 합성곱 계층을 도입하여, self-attention 메커니즘이 제공하는 전역적 맥락을 유지하면서 이미지 내의 로컬 패턴을 포착할 수 있게 합니다.

CvT 체크포인트는 모두 [Microsoft](https://huggingface.co/microsoft?search_models=cvt) 조직에서 찾을 수 있습니다.

> [!TIP]
> 이 모델은 [anujunj](https://huggingface.co/anugunj)에 의해 기여되었습니다.
>
> CvT 모델에 대한 다양한 컴퓨터 비전 작업 적용 예시를 보려면 오른쪽 사이드바의 CvT 모델을 클릭하세요.

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

```python
from transformers import pipeline

pipeline = pipeline(
    task="image-classification",
    model="microsoft/cvt-13",
    device=0
)
pipeline("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg")
```

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

from transformers import AutoImageProcessor, AutoModelForImageClassification

image_processor = AutoImageProcessor.from_pretrained("microsoft/cvt-13")
model = AutoModelForImageClassification.from_pretrained(
    "microsoft/cvt-13",
    device_map="auto"
)

url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
image = Image.open(requests.get(url, stream=True).raw)
inputs = image_processor(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}")
```

## 리소스

커스텀 데이터셋에서 추론 및 미세 조정 예시를 확인하려면 이 ViT [노트북](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/VisionTransformer) 모음을 참조하세요. 해당 노트북에서 `ViTFeatureExtractor`와 [ViTForImageClassification](/docs/transformers/v5.23.0/ko/model_doc/vit#transformers.ViTForImageClassification)를 각각 [AutoImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoImageProcessor)와 [CvtForImageClassification](/docs/transformers/v5.23.0/ko/model_doc/cvt#transformers.CvtForImageClassification)로 교체하세요.

## CvtConfig[[transformers.CvtConfig]]

#### transformers.CvtConfig[[transformers.CvtConfig]]

```python
transformers.CvtConfig(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, patch_sizes: list[int] | tuple[int, ...] = (7, 3, 3), patch_stride: list[int] | tuple[int, ...] = (4, 2, 2), patch_padding: list[int] | tuple[int, ...] = (2, 1, 1), embed_dim: list[int] | tuple[int, ...] = (64, 192, 384), num_heads: list[int] | tuple[int, ...] = (1, 3, 6), depth: list[int] | tuple[int, ...] = (1, 2, 10), mlp_ratio: list[float] | tuple[float, ...] = (4.0, 4.0, 4.0), attention_drop_rate: list[float] | tuple[float, ...] = (0.0, 0.0, 0.0), drop_rate: list[float] | tuple[float, ...] = (0.0, 0.0, 0.0), drop_path_rate: list[float] | tuple[float, ...] = (0.0, 0.0, 0.1), qkv_bias: list[bool] | tuple[bool, ...] = (True, True, True), cls_token: list[bool] | tuple[bool, ...] = (False, False, True), qkv_projection_method: list[str] | tuple[str, ...] = ('dw_bn', 'dw_bn', 'dw_bn'), kernel_qkv: list[int] | tuple[int, ...] = (3, 3, 3), padding_kv: list[int] | tuple[int, ...] = (1, 1, 1), stride_kv: list[int] | tuple[int, ...] = (2, 2, 2), padding_q: list[int] | tuple[int, ...] = (1, 1, 1), stride_q: list[int] | tuple[int, ...] = (1, 1, 1), initializer_range: float = 0.02, layer_norm_eps: float = 1e-12)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cvt/configuration_cvt.py#L24)

**매개변수:**

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

patch_sizes (`Union[list[int], tuple[int, ...]]`, *선택 사항*, 기본값 `(7, 3, 3)`) : 모델의 각 단계별 패치 크기.

patch_stride (`list[int]`, *선택 사항*, 기본값 `[4, 2, 2]`) : 각 인코더의 패치 임베딩 스트라이드 크기입니다.

patch_padding (`list[int]`, *선택 사항*, 기본값 `[2, 1, 1]`) : 각 인코더의 패치 임베딩 패딩 크기입니다.

embed_dim (`Union[list[int], tuple[int, ...]]`, *선택 사항*, 기본값 `(64, 192, 384)`) : 임베딩 및 숨겨진 상태의 차원.

num_heads (`Union[list[int], tuple[int, ...]]`, *선택 사항*, 기본값 `(1, 3, 6)`) : Transformer 디코더의 각 attention layer에 사용할 attention head의 수입니다.

depth (`list[int]`, *선택 사항*, 기본값 `[1, 2, 10]`) : 각 인코더 블록의 레이어 수입니다.

mlp_ratio (`Union[list[float], tuple[float, ...]]`, *선택 사항*, 기본값 `(4.0, 4.0, 4.0)`) : MLP 숨겨진 차원과 임베딩 차원의 비율입니다.

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

drop_rate (`list[float]`, *선택 사항*, 기본값 `[0.0, 0.0, 0.0]`) : 패치 임베딩 확률에 대한 드롭아웃 비율입니다.

drop_path_rate (`Union[list[float], tuple[float, ...]]`, *선택 사항*, 기본값 `(0.0, 0.0, 0.1)`) : 패치 퓨전용 드롭 패스 비율입니다.

qkv_bias (`Union[list[bool], tuple[bool, ...]]`, *선택 사항*, 기본값 `(True, True, True)`) : 쿼리, 키, 값에 바이어스를 추가할지 여부.

cls_token (`list[bool]`, *선택 사항*, 기본값 `[False, False, True]`) : 마지막 3단계의 출력에 분류 토큰을 추가할지 여부.

qkv_projection_method (`list[string]`, *선택 사항*, 기본값은 ["dw_bn", "dw_bn", "dw_bn"]`) : query, key, value에 대한 투사 방법입니다. 기본값은 batch norm이 적용된 depth-wise convolution입니다. Linear 투사를 사용하려면 "avg"를 사용합니다.

kernel_qkv (`list[int]`, *선택 사항*, 기본값 `[3, 3, 3]`) : attention 레이어에서 query, key, value의 커널 크기

padding_kv (`list[int]`, *선택 사항*, 기본값 `[1, 1, 1]`) : attention 레이어에서 key와 value의 padding 크기

stride_kv (`list[int]`, *선택 사항*, 기본값 `[2, 2, 2]`) : attention 레이어에서 key와 value의 stride 크기

padding_q (`list[int]`, *선택 사항*, 기본값 `[1, 1, 1]`) : attention 레이어에서 query에 대한 padding 크기

stride_q (`list[int]`, *선택 사항*, 기본값 `[1, 1, 1]`) : attention 레이어에서 query의 stride 크기

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

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

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

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 CvtConfig, CvtModel

>>> # Initializing a Cvt msft/cvt style configuration
>>> configuration = CvtConfig()

>>> # Initializing a model (with random weights) from the msft/cvt style configuration
>>> model = CvtModel(configuration)

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

## CvtModel[[transformers.CvtModel]]

#### transformers.CvtModel[[transformers.CvtModel]]

```python
transformers.CvtModel(config: CvtConfig, add_pooling_layer = True)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cvt/modeling_cvt.py#L499)

**매개변수:**

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

add_pooling_layer (`bool`, *선택 사항*, 기본값 `True`) : 풀링 레이어를 추가할지 여부

head가 없는 순수한 Cvt Model로, 특정 head 없이 원시 hidden-states를 출력합니다.

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cvt/modeling_cvt.py#L510)

**매개변수:**

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

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

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

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

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

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

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

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.
- **cls_token_value** (`torch.Tensor`, shape `(batch_size, 1, hidden_size)`) -- 모델의 마지막 레이어 출력의 분류 토큰.
- **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와 선택적 초기 임베딩 출력을 포함합니다.

## CvtForImageClassification[[transformers.CvtForImageClassification]]

#### transformers.CvtForImageClassification[[transformers.CvtForImageClassification]]

```python
transformers.CvtForImageClassification(config: CvtConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cvt/modeling_cvt.py#L549)

**매개변수:**

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

Cvt 모델은 최종 은닉 상태의 [CLS] 토큰 위에 선형 레이어를 올린 이미지 분류 헤드를 포함합니다. 예를 들어 ImageNet에 사용됩니다.

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

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/cvt/modeling_cvt.py#L564)

**매개변수:**

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

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/v5.23.0/ko/main_classes/output#transformers.utils.ModelOutput)를 반환할지 여부.

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

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

[CvtForImageClassification](/docs/transformers/v5.23.0/ko/model_doc/cvt#transformers.CvtForImageClassification)의 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
>>> from transformers import AutoImageProcessor, CvtForImageClassification
>>> import torch
>>> from datasets import load_dataset

>>> dataset = load_dataset("huggingface/cats-image")
>>> image = dataset["test"]["image"][0]

>>> image_processor = AutoImageProcessor.from_pretrained("microsoft/cvt-13")
>>> model = CvtForImageClassification.from_pretrained("microsoft/cvt-13")

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

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> # model predicts one of the 1000 ImageNet classes
>>> predicted_label = logits.argmax(-1).item()
>>> print(model.config.id2label[predicted_label])
...
```

