# RADIO

[RADIO](https://huggingface.co/papers/2312.06709)（Reduce All Domains Into One）是 NVIDIA 推出的一系列视觉基础模型，通过多教师蒸馏（例如 CLIP、DINOv2、SAM）训练到单一的 ViT 骨干网络中。它同时生成图像级别的 `summary` 嵌入和稠密空间 `features`，并通过 Cropped Position Embedding (CPE) 补丁生成器支持可变输入分辨率。

以下示例演示了如何使用 [RadioModel](/docs/transformers/main/zh/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 解码器中的隐藏层数。

num_attention_heads (`int`，*可选*，默认为 `16`)：Transformer 解码器中每个注意力层的注意力头数量。

mlp_ratio (`float`, *可选*, 默认值为 4.0) : MLP 隐藏层大小相对于 `hidden_size` 的比例。

hidden_act (`str`，*可选*，默认为 `gelu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

layer_norm_eps (`float`, *可选*, 默认为 `1e-06`) : 层归一化层使用的 epsilon。

attention_probs_dropout_prob (`float`, *可选*, 默认为 `0.0`) : 注意力概率的 dropout 比率。

hidden_dropout_prob (`float`, *可选*，默认为 `0.0`)：嵌入层、编码器和池化层中所有全连接层的 dropout 概率。

drop_path_rate (`float`, *可选*, 默认为 `0.0`) : 用于 patch fusion 的 drop path 比率。

use_swiglu_ffn (`bool`，*可选*，默认为 `False`)：是否在编码器层中使用 SwiGLU 前馈网络，而不是标准的 MLP。

qkv_bias (`bool`，*可选*，默认为 `True`)：是否向查询、键和值添加偏置。

layerscale_value (`float`, *可选*，默认为 1.0) : LayerScale 参数的初始值。C-RADIO 没有 LayerScale；默认值 `1.0` 使（继承的）LayerScale 成为恒等变换。

num_channels (`int`，*可选*，默认为 `3`)：输入通道数。

patch_size (`int`，*可选*，默认为 `16`)：每个 patch 的大小（分辨率）。

image_size (`int`, *可选*, 默认为 `224`) : 每张图片的尺寸（分辨率）。

max_img_size (`int`，*可选*，默认为 2048)：用于确定 CPE 补丁生成器位置嵌入表大小的最大支持图像尺寸（以像素为单位）。

num_cls_tokens (`int`，*可选*，默认为 3)：添加到 patch 序列前面的可学习类别（摘要）token 数量。

num_registers (`int`，*可选*，默认为 7)：添加到 patch 序列前面的可学习 register token 的数量。

video_temporal_patch_size (`int`, *可选*) : 每个 patch 中沿时间维度堆叠的帧数。设置后，patch 生成器还会为时间打包的视频 patch 构建 `video_patch_projection`；`None` 表示禁用视频路径。

patch_dim (`int`, *可选*) : 单个图像补丁的展平大小。由 `num_channels` 和 `patch_size` 推导得出。

video_patch_dim (`int`, *optional*) : 单个时间打包视频补丁的展平尺寸。由 `video_temporal_patch_size` 和 `patch_dim` 推导得出；对于仅包含图像的模型检查点，值为 `None`。

summary_idxs (`list[int]`，*可选*，默认为 `[0, 1]`)：要收集并展平到 `summary` 输出嵌入中的类别标记的索引。

norm_mean (`tuple[float, float, float]`，*可选*，默认为 `OPENAI_CLIP_MEAN`)：输入调节器用于归一化像素值的每通道均值。

norm_std (`tuple[float, float, float]`，*可选*，默认为 `OPENAI_CLIP_STD`)：输入调节器用于归一化像素值的每通道标准差。

initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

这是用于存储 RadioModel 配置的类。它根据指定的参数实例化 Radio 模型，并定义模型架构。使用默认值实例化配置将生成与 [nvidia/C-RADIOv4-H](https://huggingface.co/nvidia/C-RADIOv4-H) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/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/zh/model_doc/radio#transformers.RadioConfig))：模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

未添加任何特定头部的裸 Radio 模型，直接输出原始隐藏状态。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/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` 的 `(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`，形状为 `(num_images, 2)`，*可选*)：打包的 `pixel_values` 中每张图片的 Patch 网格 `(height, width)`。

**返回：** `RadioModelOutput` 或 `tuple(torch.Tensor)`

`RadioModelOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[RadioConfig](/docs/transformers/main/zh/model_doc/radio#transformers.RadioConfig)）和输入。

[RadioModel](/docs/transformers/main/zh/model_doc/radio#transformers.RadioModel) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **summary**（形状为 `(batch_size, num_summary_idxs * hidden_size)` 的 `torch.Tensor`）-- 展平的摘要嵌入，由 `config.summary_idxs` 选中的 cls token 收集而来。
- **features**（形状为 `(batch_size, num_patches, hidden_size)` 的 `torch.Tensor`）-- 稠密的空间块特征。对于打包输入（提供了 `image_grid_hw`），所有图像的块特征拼接在一起，形状为 `(total_patches, hidden_size)`。
- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 来自最终编码器层的完整 token 序列（前缀 token + 补丁）。对于打包输入，为所有图像序列的拼接结果，形状为 `(total_sequence_length, hidden_size)`。
- **hidden_states** (`tuple[torch.Tensor]`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple[torch.Tensor]`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。