焦点调制网络

这是FocalNets的官方PyTorch实现：

"焦点调制网络" 由 杨建伟、李春元、戴希阳、卢源 和 高剑锋 共同提出。

新闻

• [2023年11月7日] 研究人员表明，Focal-UNet在多个地球系统分析基准测试中超越了先前的方法。请查看他们的代码、论文和项目！
• [2023年6月30日] :collision: 请从huggingface获取FocalNet-DINO检查点。旧链接已弃用。
• [2023年4月26日] 通过结合FocalNet-Huge主干网络，Focal-Stable-DINO在COCO test-dev上实现了64.8 AP，且无需任何测试时增强！更多详情请参阅我们的技术报告！
• [2023年2月13日] FocalNet已被集成到Keras中，请查看教程！
• [2023年1月18日] 查看一份精选的论文列表，介绍基于现代卷积和调制的超越注意力的网络！
• [2023年1月1日] 研究人员表明，Focal-UNet在多个医学图像分割基准测试中超越了Swin-UNet。请查看他们的代码和论文，祝大家新年快乐！
• [2022年12月16日] :collision: 我们很高兴发布我们在Object365上预训练并在COCO上微调的FocalNet-Large-DINO检查点，该检查点在COCO minival上无需tta即可达到63.5 mAP！快来看看吧！
• [2022年11月14日] 我们创建了一个新的仓库FocalNet-DINO，用于存放使用DINO重现目标检测性能的代码。我们将在那里发布目标检测代码和检查点。敬请关注！
• [2022年11月13日] :collision: 我们发布了在ImageNet-22K上预训练的large、xlarge和huge模型，其中包括我们在COCO目标检测排行榜上取得SoTA时所使用的模型！
• [2022年11月2日] 我们撰写了一篇博客文章，以通俗易懂的方式介绍了FocalNets背后的见解和技术，欢迎阅读！
• [2022年10月31日] :collision: 我们基于强大的OD方法DINO，在COCO minival上取得了新的SoTA，box mAP为64.2；在COCO test-dev上则达到了64.3 64.4 box mAP！我们使用了巨大的模型规模（700M），击败了像SwinV2-G和BEIT-3这样更大的基于注意力的模型。请查看我们的新版本并持续关注！
• [2022年9月20日] 我们的FocalNet已被NeurIPS 2022接受！
• [2022年4月2日] 在huggingface空间中创建了一个gradio演示，用于可视化调制机制。快来体验吧！

简介

我们提出了FocalNets：焦点调制网络，这是一种无注意力架构，在各种视觉基准测试中均表现出优于当前最先进自注意力（SA）方法的性能。如上图所示，SA是一个“先交互、后聚合”（FILA）的过程。而我们的焦点调制则反转了这一过程，采用“先聚合、后交互”（FALI）的方式。这种反转带来了多项优势：

• 平移不变性：它针对每个目标token进行操作，上下文围绕该token展开。
• 显式的输入依赖性：调制器通过聚合来自输入的短程和长程上下文来计算，然后应用于目标token。
• 空间和通道特异性：它首先按空间维度聚合上下文，再按通道维度聚合，最后进行逐元素调制。
• 解耦的特征粒度：查询token保留了最精细级别的个体信息，而其周围的较粗粒度上下文则被提取出来。两者通过调制操作连接在一起，但彼此解耦。
• 易于实现：我们可以以非常简单轻量的方式实现上下文聚合和交互操作。它不需要softmax、多头注意力、特征图滚动或展开等操作。

在开始之前，让我们看看我们的FocalNets学到了如何感知图像以及在哪里进行调制吧！

总之，FocalNets基于卷积层和线性层构建，但通过提出一种简单、通用、有效且高效的新型调制机制，实现了超越。我们在此推荐：

焦点调制或许正是我们进行视觉建模所需要的！

开始使用

• 请按照get_started_for_image_classification中的说明，开始进行图像分类。
• 请按照get_started_for_object_detection中的说明，开始进行目标检测。
• 请按照get_started_for_semantic_segmentation中的说明，开始进行语义分割。

基准测试

ImageNet-1K 上的图像分类

• 与多尺度 Swin 和 Focal Transformer 的严格对比：

模型	深度	尺寸	核大小	参数量 (M)	FLOPs (G)	吞吐量 (imgs/s)	Top-1	下载
FocalNet-T	[2,2,6,2]	96	[3,5]	28.4	4.4	743	82.1	ckpt/配置文件/日志
FocalNet-T	[2,2,6,2]	96	[3,5,7]	28.6	4.5	696	82.3	ckpt/配置文件/日志
FocalNet-S	[2,2,18,2]	96	[3,5]	49.9	8.6	434	83.4	ckpt/配置文件/日志
FocalNet-S	[2,2,18,2]	96	[3,5,7]	50.3	8.7	406	83.5	ckpt/配置文件/日志
FocalNet-B	[2,2,18,2]	128	[3,5]	88.1	15.3	280	83.7	ckpt/配置文件/日志
FocalNet-B	[2,2,18,2]	128	[3,5,7]	88.7	15.4	269	83.9	ckpt/配置文件/日志

• 与各向同性 ViT 模型的严格对比：

模型	深度	尺寸	核大小	参数量 (M)	FLOPs (G)	吞吐量 (imgs/s)	Top-1	下载
FocalNet-T	12	192	[3,5,7]	5.9	1.1	2334	74.1	ckpt/配置文件/日志
FocalNet-S	12	384	[3,5,7]	22.4	4.3	920	80.9	ckpt/配置文件/日志
FocalNet-B	12	768	[3,5,7]	87.2	16.9	300	82.4	ckpt/配置文件/日志

ImageNet-22K 预训练

模型	深度	尺寸	核大小	参数量 (M)	下载
FocalNet-L	[2,2,18,2]	192	[5,7,9]	207	ckpt/配置文件
FocalNet-L	[2,2,18,2]	192	[3,5,7,9]	207	ckpt/配置文件
FocalNet-XL	[2,2,18,2]	256	[5,7,9]	366	ckpt/配置文件
FocalNet-XL	[2,2,18,2]	256	[3,5,7,9]	366	ckpt/配置文件
FocalNet-H	[2,2,18,2]	352	[3,5,7]	687	ckpt/配置文件
FocalNet-H	[2,2,18,2]	352	[3,5,7,9]	689	ckpt/配置文件

注: 我们对 ImageNet-22K 中的类别名称进行了重新排序，以便可以直接使用前 1000 个 logits 来在 ImageNet-1K 上进行评估。请注意，ImageNet-1K 中的第 851 类（标签=850）在 ImageNet-22K 中缺失。请参考此 labelmap。更多讨论请参见此 issue。

COCO 数据集上的目标检测

• Mask R-CNN

主干网络	卷积核设置	学习率调度	参数量 (M)	浮点运算次数 (G)	box mAP	mask mAP	下载
FocalNet-T	[9,11]	1x	48.6	267	45.9	41.3	检查点/配置文件/日志
FocalNet-T	[9,11]	3x	48.6	267	47.6	42.6	检查点/配置文件/日志
FocalNet-T	[9,11,13]	1x	48.8	268	46.1	41.5	检查点/配置文件/日志
FocalNet-T	[9,11,13]	3x	48.8	268	48.0	42.9	检查点/配置文件/日志
FocalNet-S	[9,11]	1x	70.8	356	48.0	42.7	检查点/配置文件/日志
FocalNet-S	[9,11]	3x	70.8	356	48.9	43.6	检查点/配置文件/日志
FocalNet-S	[9,11,13]	1x	72.3	365	48.3	43.1	检查点/配置文件/日志
FocalNet-S	[9,11,13]	3x	72.3	365	49.3	43.8	检查点/配置文件/日志
FocalNet-B	[9,11]	1x	109.4	496	48.8	43.3	检查点/配置文件/日志
FocalNet-B	[9,11]	3x	109.4	496	49.6	44.1	检查点/配置文件/日志
FocalNet-B	[9,11,13]	1x	111.4	507	49.0	43.5	检查点/配置文件/日志
FocalNet-B	[9,11,13]	3x	111.4	507	49.8	44.1	检查点/配置文件/[日志](https://projects4jw.blob core.windows.net/focalnet/release/detection/log_focalnet_base_lrf_maskrcnn_3x.json)

• 其他检测方法

主干网络	卷积核设置	方法	学习率调度	参数量 (M)	浮点运算次数 (G)	box mAP	下载
FocalNet-T	[11,9,9,7]	Cascade Mask R-CNN	3x	87.1	751	51.5	检查点/配置文件/日志
FocalNet-T	[11,9,9,7]	ATSS	3x	37.2	220	49.6	检查点/配置文件/[日志](https://projects4jw.blob core.windows.net/focalnet/release/detection/log_focalnet_tiny_lrf_atss_3x.json)
FocalNet-T	[11,9,9,7]	Sparse R-CNN	3x	111.2	178	49.9	[检查点](https://projects4jw.blob core.windows.net/focalnet/release/detection/focalnet_tiny_lrf_sparsercnn_3x.pth)/配置文件/[日志](https://projects4jw.blob core.windows.net/focalnet/release/detection/log_focalnet_tiny_lrf_sparsercnn_3x.json)

ADE20K 数据集上的语义分割

• 分辨率 512x512，迭代次数 16万次

主干网络	核心数	方法	参数量 (M)	FLOPs (G)	mIoU	mIoU (多尺度)	下载
FocalNet-T	[9,11]	UPerNet	61	944	46.5	47.2	检查点/配置文件/日志
FocalNet-T	[9,11,13]	UPerNet	61	949	46.8	47.8	检查点/配置文件/日志
FocalNet-S	[9,11]	UPerNet	83	1035	49.3	50.1	检查点/配置文件/日志
FocalNet-S	[9,11,13]	UPerNet	84	1044	49.1	50.1	检查点/配置文件/日志
FocalNet-B	[9,11]	UPerNet	124	1180	50.2	51.1	检查点/配置文件/日志
FocalNet-B	[9,11,13]	UPerNet	126	1192	50.5	51.4	检查点/配置文件/日志

可视化

我们的 FocalNets 包含三个步骤：

1. 使用深度可分离卷积进行上下文建模；
2. 通过门控机制进行多尺度聚合；
3. 基于上下文聚合与投影生成调制器。

我们逐一展示这些步骤的可视化效果。

• FocalNets 中学习到的深度可分离卷积核：

黄色表示较高的值。显然，FocalNets 在早期阶段学习聚集更多的局部上下文，而在后期阶段则更多地关注全局上下文。

• FocalNets 最后一层针对不同输入图像的门控图：

从左至右依次为输入图像、第1、2、3层焦点级别的门控图以及全局上下文图。很明显，我们的模型已经学会根据不同位置的视觉内容来决定在哪里聚集上下文信息。

• FocalNets 中针对不同输入图像学习到的调制器：

由我们的模型生成的调制器能够自动聚焦于前景区域。

如需自行进行可视化，请参阅 可视化笔记本。

引用

如果您觉得本仓库对您的项目有所帮助，请考虑使用以下 BibTeX 格式引用：

@misc{yang2022focal,
      title={Focal Modulation Networks}, 
      author={Jianwei Yang and Chunyuan Li and Xiyang Dai and Jianfeng Gao},
      journal={Advances in Neural Information Processing Systems (NeurIPS)},
      year={2022}
}

致谢

我们的代码库基于 Swin Transformer 和 Focal Transformer 构建。为了达到当前最优的目标检测性能，我们高度依赖最先进的方法 DINO 以及作者们的宝贵建议。感谢作者们精心组织的代码！

贡献

本项目欢迎各类贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），以声明您有权并确实授予我们使用您贡献的权利。详情请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并相应地标记 PR（例如状态检查、评论）。只需按照机器人提供的指示操作即可。对于所有使用我们 CLA 的仓库，您只需完成一次此流程。

本项目已采用 微软开源行为准则。更多信息请参阅 行为准则常见问题解答 或发送邮件至 opencode@microsoft.com 提出任何其他问题或意见。

商标

本项目可能包含项目、产品或服务相关的商标或标志。未经授权使用微软商标或标志须遵守并遵循 微软商标与品牌指南。在本项目的修改版本中使用微软商标或标志不得造成混淆或暗示微软的赞助。任何第三方商标或标志的使用均受其各自政策的约束。

FocalNet 快速上手指南

FocalNet (Focal Modulation Networks) 是一种无需注意力机制（Attention-free）的视觉架构，通过“先聚合后交互”的焦点调制机制，在图像分类、目标检测和语义分割等任务中实现了超越主流自注意力模型的性能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 18.04+) 或 Windows (WSL2)
• Python: 3.7 或更高版本
• GPU: 支持 CUDA 的 NVIDIA GPU (推荐显存 16GB+ 以运行大型模型)
• 核心依赖:
  • PyTorch >= 1.8
  • torchvision
  • timm
  • mmcv / mmdetection (若用于目标检测)
  • mmsegmentation (若用于语义分割)

国内加速建议：建议使用清华源或阿里源安装 Python 依赖，以提升下载速度。

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple torch torchvision timm

安装步骤

1. 克隆代码库

从 GitHub 获取官方源代码：

git clone https://github.com/microsoft/FocalNet.git
cd FocalNet

2. 安装依赖

项目根目录下通常包含 requirements.txt，请使用以下命令安装所需包（推荐使用国内镜像）：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

如果需要进行目标检测或语义分割任务，请分别参考 detection/ 和 segmentation/ 目录下的具体环境配置说明（通常涉及安装 MMDetection 或 MMSegmentation）。

基本使用

以下以最常用的 ImageNet-1K 图像分类 为例，展示如何加载预训练模型并进行推理。

1. 下载预训练模型

从 Release 页面下载 Tiny 版本的预训练权重（示例）：

wget https://github.com/microsoft/FocalNet/releases/download/v1.0.0/focalnet_tiny_srf.pth

2. Python 推理示例

创建一个 infer.py 文件，编写以下代码加载模型并预测图片：

import torch
from PIL import Image
from torchvision import transforms
from models import focalnet

# 1. 配置设备
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

# 2. 构建模型 (以 FocalNet-Tiny SRF 为例)
# depth=[2,2,6,2], dim=96, kernels=[3,5]
model = focalnet.FocalNet(depths=[2, 2, 6, 2], embed_dim=96, sr_ratio=[3, 5])

# 3. 加载预训练权重
checkpoint = torch.load('focalnet_tiny_srf.pth', map_location=device)
model.load_state_dict(checkpoint['model'], strict=True)
model.to(device)
model.eval()

# 4. 图像预处理
transform = transforms.Compose([
    transforms.Resize(256),
    transforms.CenterCrop(224),
    transforms.ToTensor(),
    transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
])

# 5. 推理
image = Image.open("your_image.jpg").convert('RGB')
input_tensor = transform(image).unsqueeze(0).to(device)

with torch.no_grad():
    output = model(input_tensor)
    prediction = torch.argmax(output, dim=1)

print(f"Predicted class index: {prediction.item()}")

3. 其他任务入口

• 目标检测: 请参考 detection/ 目录，基于 MMDetection 框架运行训练和测试脚本。
• 语义分割: 请参考 segmentation/ 目录，基于 MMSegmentation 框架运行相关脚本。
• 可视化演示: 可访问 HuggingFace Space 查看焦点调制机制的可视化效果。