# RADIO

[RADIO](https://huggingface.co/papers/2312.06709)(Reduce All Domains Into One)는 NVIDIA에서 다중 교사 증류(multi-teacher distillation, 예: CLIP, DINOv2, SAM)를 통해 단일 ViT 백본으로 학습한 비전 파운데이션 모델 계열입니다. 이미지 수준의 `summary` 임베딩과 밀집된 공간 `features`를 모두 생성하며, Cropped Position Embedding(CPE) 패치 생성기를 통해 가변 입력 해상도를 지원합니다.

아래 예제는 [RadioModel](/docs/transformers/main/ko/model_doc/radio#transformers.RadioModel) 클래스를 사용하여 이미지 특징을 추출하는 방법을 보여줍니다.

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

from transformers import CLIPImageProcessor, RadioModel

hf_repo = "nvidia/C-RADIOv4-H"

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

model = RadioModel.from_pretrained(hf_repo)
model.eval().to(device)

image_processor = CLIPImageProcessor(
    size={"height": 224, "width": 224}, do_resize=True, do_center_crop=False, do_normalize=False
)

url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
image = Image.open(requests.get(url, stream=True).raw).convert("RGB")
pixel_values = image_processor(images=image, return_tensors="pt").pixel_values
pixel_values = pixel_values.to(device)

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

summary = outputs.summary    # (1, 2560) image-level embedding
features = outputs.features   # (1, 196, 1280) dense spatial features
```

## RadioConfig[[transformers.RadioConfig]]

#### transformers.RadioConfig[[transformers.RadioConfig]]

```python
transformers.RadioConfig(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, hidden_size: int = 1280, num_hidden_layers: int = 32, num_attention_heads: int = 16, mlp_ratio: float = 4.0, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, attention_probs_dropout_prob: float = 0.0, hidden_dropout_prob: float = 0.0, drop_path_rate: float = 0.0, use_swiglu_ffn: bool = False, qkv_bias: bool = True, layerscale_value: float = 1.0, num_channels: int = 3, patch_size: int = 16, image_size: int = 224, max_img_size: int = 2048, num_cls_tokens: int = 3, num_registers: int = 7, video_temporal_patch_size: int | None = None, patch_dim: int | None = None, video_patch_dim: int | None = None, summary_idxs: list[int] | None = None, norm_mean: list[float] | tuple[float, float, float] = (0.48145466, 0.4578275, 0.40821073), norm_std: list[float] | tuple[float, float, float] = (0.26862954, 0.26130258, 0.27577711), initializer_range: float = 0.02)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/radio/configuration_radio.py#L28)

**매개변수:**

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

num_hidden_layers (`int`, *선택 사항*, 기본값 `32`) : Transformer decoder의 숨겨진 레이어 수.

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

mlp_ratio (`float`, *선택 사항*, 기본값 4.0) : `hidden_size`에 대한 MLP의 hidden size 비율입니다.

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

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

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

hidden_dropout_prob (`float`, *선택 사항*, 기본값 `0.0`) : 임베딩, 인코더, 풀러의 모든 완전 연결 계층에 적용되는 드롭아웃 확률입니다.

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

use_swiglu_ffn (`bool`, *선택 사항*, 기본값 `False`) : 표준 MLP 대신 인코더 레이어에서 SwiGLU 피드포워드 네트워크를 사용할지 여부.

qkv_bias (`bool`, *선택 사항*, 기본값 `True`) : 쿼리, 키, 값에 bias를 추가할지 여부.

layerscale_value (`float`, *선택 사항*, 기본값 1.0) : LayerScale 매개변수의 초기 값입니다. C-RADIO에는 LayerScale이 없으며, 기본값 `1.0`은 (상속된) LayerScale을 항등 연산으로 만듭니다.

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

patch_size (`int`, *선택 사항*, 기본값 `16`) : 각 패치의 크기(해상도).

image_size (`int`, *선택 사항*, 기본값 `224`) : 각 이미지의 크기(해상도).

max_img_size (`int`, *선택 사항*, 기본값 2048) : CPE 패치 생성기의 위치 임베딩 테이블 크기를 결정하는 데 사용되는 최대 지원 이미지 크기(픽셀 단위).

num_cls_tokens (`int`, *선택 사항*, 기본값 3) : 패치 시퀀스에 앞에 붙는 학습된 클래스(요약) 토큰의 수.

num_registers (`int`, *선택 사항*, 기본값 7) : 패치 시퀀스에 앞에 붙는 학습된 레지스터 토큰의 개수.

video_temporal_patch_size (`int`, *선택 사항*) : 패치당 시간적으로 스택된 프레임 수. 설정된 경우, 패치 생성기는 시간적으로 패킹된 비디오 패치를 위한 `video_patch_projection`도 생성합니다. `None`은 비디오 경로를 비활성화합니다.

patch_dim (`int`, *선택 사항*) : 이미지 패치 하나의 평탄화 크기. `num_channels`와 `patch_size`에서 유도됩니다.

video_patch_dim (`int`, *선택 사항*) : 시간적으로 패킹된 비디오 패치 하나의 평탄화 크기. `video_temporal_patch_size`와 `patch_dim`에서 파생됩니다. 이미지 전용 체크포인트의 경우 `None`입니다.

summary_idxs (`list[int]`, *선택 사항*, 기본값 `[0, 1]`) : `summary` 출력 임베딩으로 수집하고 평탄화할 클래스 토큰의 인덱스.

norm_mean (`tuple[float, float, float]`, *선택 사항*, 기본값 `OPENAI_CLIP_MEAN`) : 입력 조건부화기(input conditioner)가 픽셀 값을 정규화하는 데 사용하는 채널별 평균입니다.

norm_std (`tuple[float, float, float]`, *선택 사항*, 기본값 `OPENAI_CLIP_STD`) : 입력 조건부화기(input conditioner)가 픽셀 값을 정규화하는 데 사용하는 채널별 표준 편차입니다.

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

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

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

## RadioModel[[transformers.RadioModel]]

#### transformers.RadioModel[[transformers.RadioModel]]

```python
transformers.RadioModel(config: RadioConfig)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/radio/modeling_radio.py#L434)

**매개변수:**

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

특정 헤드가 위에 없는 상태에서 원시 hidden-states를 출력하는 기본 Radio Model입니다.

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

```python
forward(pixel_values: Tensor, image_grid_hw: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/radio/modeling_radio.py#L454)

**매개변수:**

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, height, width)` 또는 `(total_patches, num_channels * patch_size**2)`) : 동일한 크기의 이미지 또는 `image_grid_hw`와 함께 다른 크기의 이미지의 평탄화된 패치가 연결된 형태. 각 패치는 채널 우선 순서로 배치되어 있으며, 즉 `(num_channels, patch_size, patch_size)` 형태입니다.

image_grid_hw (`torch.LongTensor`, shape `(num_images, 2)`, *선택 사항*) : packed `pixel_values`의 각 이미지에 대한 patch grid `(height, width)`.

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

`RadioModelOutput` 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우)로, [RadioConfig](/docs/transformers/main/ko/model_doc/radio#transformers.RadioConfig) 및 입력에 따라 다양한 요소를 포함합니다.

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

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

- **요약** (`torch.Tensor`, shape `(batch_size, num_summary_idxs * hidden_size)`) -- `config.summary_idxs`로 선택된 cls 토큰에서 수집된 평탄화된 요약 임베딩입니다.
- **features** (`torch.Tensor`, shape `(batch_size, num_patches, hidden_size)`) -- Dense spatial patch features. Packed inputs(`image_grid_hw`가 제공된 경우)의 경우, 모든 이미지의 patch features가 연결된 형태로 shape `(total_patches, hidden_size)`를 가집니다.
- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 최종 인코더 레이어에서 나온 전체 토큰 시퀀스(프리픽스 토큰 + 패치). 패킹된 입력의 경우, 모든 이미지의 시퀀스가 연결된 형태로 shape는 `(total_sequence_length, hidden_size)`입니다.
- **hidden_states** (`tuple[torch.Tensor]`, *선택*, `output_hidden_states=True`가 전달되었거나 `config.output_hidden_states=True`인 경우 반환됨) -- `torch.Tensor`의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력용 1개 + 각 레이어의 출력용 1개)로, 모양은 `(batch_size, sequence_length, hidden_size)`입니다.

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

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

