Transformers documentation
FocalNet
该模型于 2022-03-22 在 HF papers 上发布，并于 2023-04-23 贡献至 Hugging Face Transformers。
FocalNet
概述
FocalNet 模型由 Jianwei Yang、Chunyuan Li、Xiyang Dai、Lu Yuan 和 Jianfeng Gao 在 Focal Modulation Networks 中提出。 FocalNet 通过焦点调制机制来建模视觉中的 token 交互，从而完全取代了自注意力机制（该机制用于 ViT 和 Swin 等模型）。 作者声称，在图像分类、目标检测和分割任务上，FocalNet 在计算成本相近的情况下，性能优于基于自注意力的模型。
该论文的摘要如下：
我们提出了焦点调制网络（简称 FocalNets），其中自注意力（SA）被完全替换为焦点调制机制，用于建模视觉中的 token 交互。焦点调制由三个组件组成：(i) 层次化上下文编码，通过堆叠的深度可分离卷积层实现，以编码从短程到长程的视觉上下文；(ii) 门控聚合，根据每个查询 token 的内容选择性地收集上下文；以及 (iii) 逐元素调制或仿射变换，将聚合后的上下文注入查询中。大量实验表明，在图像分类、目标检测和分割任务上，FocalNets 在计算成本相近的情况下，性能优于最先进的 SA 对应模型（例如 Swin 和 Focal Transformers）。具体而言，tiny 和 base 规模的 FocalNets 在 ImageNet-1K 上分别达到了 82.3% 和 83.9% 的 top-1 准确率。在 ImageNet-22K 上以 224 分辨率预训练后，分别在 224 和 384 分辨率下微调时，其 top-1 准确率达到了 86.5% 和 87.3%。当迁移到下游任务时，FocalNets 展现出明显的优势。对于使用 Mask R-CNN 的目标检测，以 1\times 训练的 FocalNet base 比 Swin 对应模型高出 2.1 个点，并且已经超越了以 3\times 调度训练的 Swin（49.0 对 48.5）。对于使用 UPerNet 的语义分割，单尺度下的 FocalNet base 比 Swin 高出 2.4 个点，并超过了多尺度下的 Swin（50.5 对 49.7）。使用大型 FocalNet 和 Mask2former，我们在 ADE20K 语义分割上达到了 58.5 mIoU，在 COCO 全景分割上达到了 57.9 PQ。使用巨型 FocalNet 和 DINO，我们在 COCO minival 和 test-dev 上分别达到了 64.3 和 64.4 mAP，在 Swinv2-G 和 BEIT-3 等更大的基于注意力的模型之上建立了新的 SoTA。
FocalNetConfig
class transformers.FocalNetConfig
< 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 = Noneimage_size: int | list[int] | tuple[int, int] = 224patch_size: int | list[int] | tuple[int, int] = 4num_channels: int = 3embed_dim: int = 96use_conv_embed: bool = Falsehidden_sizes: list[int] | tuple[int, ...] = (192, 384, 768, 768)depths: list[int] | tuple[int, ...] = (2, 2, 6, 2)focal_levels: list[int] | tuple[int, ...] = (2, 2, 2, 2)focal_windows: list[int] | tuple[int, ...] = (3, 3, 3, 3)hidden_act: str = 'gelu'mlp_ratio: float = 4.0hidden_dropout_prob: float | int = 0.0drop_path_rate: float | int = 0.1use_layerscale: bool = Falselayerscale_value: float = 0.0001use_post_layernorm: bool = Falseuse_post_layernorm_in_modulation: bool = Falsenormalize_modulator: bool = Falseinitializer_range: float = 0.02layer_norm_eps: float = 1e-05encoder_stride: int = 32_out_features: list[str] | None = None_out_indices: list[int] | None = None )
参数
- image_size (
Union[int, list[int], tuple[int, int]]，可选，默认为224) — 每张图片的尺寸（分辨率）。 - patch_size (
Union[int, list[int], tuple[int, int]]，可选，默认为4) — 每个 patch 的大小（分辨率）。 - num_channels (
int，可选，默认为3) — 输入通道的数量。 - embed_dim (
int，可选，默认为96) — 嵌入和隐藏状态的维度。 - use_conv_embed (
bool，可选，默认为False) — 是否使用卷积嵌入。作者指出，使用卷积嵌入通常能提升性能，但默认情况下并未启用。 - hidden_sizes (
Union[list[int], tuple[int, ...]]，可选，默认为(192, 384, 768, 768)) — 模型每个阶段的维度（隐藏层大小）。 - depths (
Union[list[int], tuple[int, ...]]，可选，默认为(2, 2, 6, 2)) — Transformer 中每一层的深度。 - focal_levels (
list(int)，可选，默认为[2, 2, 2, 2]) — 编码器中各阶段每一层的焦点层数。 - focal_windows (
list(int)，可选，默认为[3, 3, 3, 3]) — 编码器中各阶段对应层的焦点窗口大小。 - hidden_act (
str，可选，默认为gelu) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、"relu"、"silu"等。 - mlp_ratio (
float，可选，默认为4.0) — MLP 隐藏层维度与嵌入维度的比值。 - hidden_dropout_prob (
float，可选，默认值为 0.0) — 嵌入层和编码器中所有全连接层的 dropout 概率。 - drop_path_rate (
Union[float, int]，可选，默认为0.1) — 用于 patch 融合的 drop path 比率。 - use_layerscale (
bool，可选，默认为False) — 是否在编码器中使用 layer scale。 - layerscale_value (
float，可选，默认值为 0.0001) — 层缩放的初始值。 - use_post_layernorm (
bool，可选，默认为False) — 是否在编码器中使用后置层归一化。 - use_post_layernorm_in_modulation (
bool，可选，默认为False) — 是否在调制层中使用后置层归一化。 - normalize_modulator (
bool，可选，默认为False) — 是否对调制器进行归一化。 - initializer_range (
float，可选，默认为0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 - layer_norm_eps (
float，可选，默认为1e-05) — 层归一化层所使用的 epsilon 值。 - encoder_stride (
int，可选，默认为 32) — 在掩码图像建模的解码器头部中，用于提升空间分辨率的倍数因子。
这是用于存储 FocalNetModel 配置的类。它根据指定的参数实例化 Focalnet 模型，并定义模型架构。使用默认值实例化配置将得到与 microsoft/focalnet-tiny 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
示例：
>>> from transformers import FocalNetConfig, FocalNetModel
>>> # Initializing a FocalNet microsoft/focalnet-tiny style configuration
>>> configuration = FocalNetConfig()
>>> # Initializing a model (with random weights) from the microsoft/focalnet-tiny style configuration
>>> model = FocalNetModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configFocalNetModel
类 transformers.FocalNetModel
< source >( config: FocalNetConfigadd_pooling_layer = Trueuse_mask_token = False )
参数
- config (FocalNetConfig) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
- add_pooling_layer (
bool，可选，默认为True) — 是否添加池化层 - use_mask_token (
bool，可选，默认为False) — 是否使用掩码标记进行掩码图像建模。
未添加任何特定头部的裸 Focalnet 模型，直接输出原始隐藏状态。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = Nonebool_masked_pos: typing.Optional[torch.BoolTensor] = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → FocalNetModelOutput or tuple(torch.Tensor)
参数
- pixel_values (
torch.Tensor，形状为(batch_size, num_channels, image_size, image_size)，可选) — 与输入图像对应的张量。可以使用 BitImageProcessor 获取像素值。有关详细信息，请参阅 BitImageProcessor.call()（processor_class使用 BitImageProcessor 处理图像）。 - bool_masked_pos（形状为
(batch_size, num_patches)的torch.BoolTensor）— 布尔掩码位置。指示哪些 patch 被掩码（1），哪些未被掩码（0）。 - output_hidden_states (
bool，可选) — 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量中的hidden_states。 - return_dict (
bool, 可选) — 是否返回 ModelOutput 而不是普通元组。
返回值
FocalNetModelOutput 或 tuple(torch.Tensor)
FocalNetModelOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（FocalNetConfig）和输入。
FocalNetModel 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor，可选）— 模型最后一层输出的隐藏状态序列。pooler_output（形状为
(batch_size, hidden_size)的torch.Tensor，可选，在传入add_pooling_layer=True时返回） — 最后一层隐藏状态的均值池化。hidden_states (
tuple[torch.Tensor]，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
reshaped_hidden_states (
tuple(torch.Tensor)，可选，在传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（包含嵌入层输出以及每个阶段的输出各一个），形状为(batch_size, hidden_size, height, width)。模型在每一层输出处的隐藏状态，以及重塑为包含空间维度的初始嵌入输出。
FocalNetForMaskedImageModeling
class transformers.FocalNetForMaskedImageModeling
< source >( config: FocalNetConfig )
参数
- config (FocalNetConfig) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
FocalNet 模型，顶部带有解码器，用于掩码图像建模。
这与 SimMIM 中的实现相同。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = Nonebool_masked_pos: typing.Optional[torch.BoolTensor] = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → FocalNetMaskedImageModelingOutput or tuple(torch.Tensor)
参数
- pixel_values (
torch.Tensor，形状为(batch_size, num_channels, image_size, image_size)，可选) — 与输入图像对应的张量。可以使用 BitImageProcessor 获取像素值。有关详细信息，请参阅 BitImageProcessor.call()（processor_class使用 BitImageProcessor 处理图像）。 - bool_masked_pos（形状为
(batch_size, num_patches)的torch.BoolTensor）— 布尔掩码位置。指示哪些 patch 被掩码（1），哪些未被掩码（0）。 - output_hidden_states (
bool，可选) — 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量中的hidden_states。 - return_dict (
bool, 可选) — 是否返回 ModelOutput 而不是普通元组。
返回值
FocalNetMaskedImageModelingOutput 或 tuple(torch.Tensor)
FocalNetMaskedImageModelingOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（FocalNetConfig）和输入。
FocalNetForMaskedImageModeling 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
loss (
torch.Tensor，形状为(1,)，可选，当提供bool_masked_pos时返回) — 掩码图像建模 (MLM) 损失。重建（形状为
(batch_size, num_channels, height, width)的torch.Tensor）— 重建的像素值。hidden_states (
tuple[torch.Tensor]，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
reshaped_hidden_states (
tuple(torch.Tensor)，可选，在传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（包含嵌入层输出以及每个阶段的输出各一个），形状为(batch_size, hidden_size, height, width)。模型在每一层输出处的隐藏状态，以及重塑为包含空间维度的初始嵌入输出。
示例：
>>> from transformers import AutoImageProcessor, FocalNetConfig, FocalNetForMaskedImageModeling
>>> import torch
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
... image = Image.open(BytesIO(response.read()))
>>> image_processor = AutoImageProcessor.from_pretrained("microsoft/focalnet-base-simmim-window6-192")
>>> config = FocalNetConfig()
>>> model = FocalNetForMaskedImageModeling(config)
>>> num_patches = (model.config.image_size // model.config.patch_size) ** 2
>>> pixel_values = image_processor(images=image, return_tensors="pt").pixel_values
>>> # create random boolean mask of shape (batch_size, num_patches)
>>> bool_masked_pos = torch.randint(low=0, high=2, size=(1, num_patches)).bool()
>>> outputs = model(pixel_values, bool_masked_pos=bool_masked_pos)
>>> loss, reconstructed_pixel_values = outputs.loss, outputs.logits
>>> list(reconstructed_pixel_values.shape)
[1, 3, 192, 192]FocalNetForImageClassification
class transformers.FocalNetForImageClassification
< source >( config: FocalNetConfig )
参数
- config (FocalNetConfig) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
FocalNet 模型，顶部带有图像分类头（在池化输出之上添加一个线性层），例如用于 ImageNet。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → FocalNetImageClassifierOutput or tuple(torch.Tensor)
参数
- pixel_values (
torch.Tensor，形状为(batch_size, num_channels, image_size, image_size)，可选) — 与输入图像对应的张量。可以使用 BitImageProcessor 获取像素值。有关详细信息，请参阅 BitImageProcessor.call()（processor_class使用 BitImageProcessor 处理图像）。 - labels（形状为
(batch_size,)的torch.LongTensor，可选）— 用于计算图像分类/回归损失的标签。索引应在[0, ..., config.num_labels - 1]范围内。如果config.num_labels == 1，则计算回归损失（均方损失）；如果config.num_labels > 1，则计算分类损失（交叉熵）。 - output_hidden_states (
bool，可选) — 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量中的hidden_states。 - return_dict (
bool, 可选) — 是否返回 ModelOutput 而不是普通元组。
返回值
FocalNetImageClassifierOutput 或 tuple(torch.Tensor)
FocalNetImageClassifierOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（FocalNetConfig）和输入。
FocalNetForImageClassification 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
loss (
torch.Tensor，形状为(1,)，可选，当提供labels时返回) — 分类损失（如果 config.num_labels==1，则为回归损失）。logits（形状为
(batch_size, config.num_labels)的torch.Tensor）— 分类（或当 config.num_labels==1 时为回归）得分（SoftMax 之前）。hidden_states (
tuple[torch.Tensor]，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
reshaped_hidden_states (
tuple(torch.Tensor)，可选，在传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（包含嵌入层输出以及每个阶段的输出各一个），形状为(batch_size, hidden_size, height, width)。模型在每一层输出处的隐藏状态，以及重塑为包含空间维度的初始嵌入输出。
示例：
>>> from transformers import AutoImageProcessor, FocalNetForImageClassification
>>> import torch
>>> from datasets import load_dataset
>>> dataset = load_dataset("huggingface/cats-image")
>>> image = dataset["test"]["image"][0]
>>> image_processor = AutoImageProcessor.from_pretrained("microsoft/focalnet-tiny")
>>> model = FocalNetForImageClassification.from_pretrained("microsoft/focalnet-tiny")
>>> 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])
...