Transformers documentation
RADIO
该模型于 2026-06-30 贡献至 Hugging Face Transformers。
RADIO
RADIO（Reduce All Domains Into One）是 NVIDIA 推出的一系列视觉基础模型，通过多教师蒸馏（例如 CLIP、DINOv2、SAM）训练到单一的 ViT 骨干网络中。它同时生成图像级别的 summary 嵌入和稠密空间 features，并通过 Cropped Position Embedding (CPE) 补丁生成器支持可变输入分辨率。
以下示例演示了如何使用 RadioModel 类提取图像特征。
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 featuresRadioConfig
class transformers.RadioConfig
< 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 = Nonehidden_size: int = 1280num_hidden_layers: int = 32num_attention_heads: int = 16mlp_ratio: float = 4.0hidden_act: str = 'gelu'layer_norm_eps: float = 1e-06attention_probs_dropout_prob: float = 0.0hidden_dropout_prob: float = 0.0drop_path_rate: float = 0.0use_swiglu_ffn: bool = Falseqkv_bias: bool = Truelayerscale_value: float = 1.0num_channels: int = 3patch_size: int = 16image_size: int = 224max_img_size: int = 2048num_cls_tokens: int = 3num_registers: int = 7video_temporal_patch_size: int | None = Nonepatch_dim: int | None = Nonevideo_patch_dim: int | None = Nonesummary_idxs: list[int] | None = Nonenorm_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 )
参数
- 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 融合的 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, 可选) — 一个时间打包视频 patch 的展平尺寸。由video_temporal_patch_size和patch_dim推导得出；对于仅包含图像的 checkpoint，值为None。 - summary_idxs (
list[int]，可选，默认为[0, 1]) — 用于收集并展平到summary输出嵌入中的类别 token 的索引。 - 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 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
RadioModel
class transformers.RadioModel
< source >( config: RadioConfig )
参数
- config (RadioConfig) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
未添加任何特定头部的裸 Radio 模型，直接输出原始隐藏状态。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( pixel_values: Tensorimage_grid_hw: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → RadioModelOutput or tuple(torch.Tensor)
参数
- pixel_values（形状为
(batch_size, num_channels, height, width)或(total_patches, num_channels * patch_size**2)的torch.Tensor）— 尺寸统一的图像，或者在使用image_grid_hw时，将不同尺寸图像的展平 patch 拼接在一起。每个 patch 按通道优先排列，即(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）和输入。
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 之后的权重，用于在自注意力头中计算加权平均值。