Ultralytics:解读BNContrastiveHead模块

Ultralytics:解读BNContrastiveHead模块

前言

相关介绍

Ultralytics 简介

Ultralytics 基于多年的计算机视觉和人工智能基础研究,创建了最先进的 (SOTA) YOLO 模型。我们的模型不断更新性能和灵活性,快速、准确且易于使用。他们擅长对象检测、跟踪、实例分割、语义分割、图像分类和姿势估计任务。

前提条件

  • 熟悉Python、Pytorch

实验环境

bash 复制代码
Package                  Version
------------------------ ------------
Python                   3.11.8
absl-py                  2.4.0
accelerate               1.13.0
annotated-doc            0.0.4
anyio                    4.13.0
calflops                 0.3.2
certifi                  2026.4.22
charset-normalizer       3.4.7
click                    8.3.3
colorama                 0.4.6
contourpy                1.3.3
cycler                   0.12.1
filelock                 3.29.0
flatbuffers              25.12.19
fonttools                4.62.1
fsspec                   2026.4.0
grpcio                   1.80.0
h11                      0.16.0
hf-xet                   1.5.0
httpcore                 1.0.9
httpx                    0.28.1
huggingface_hub          1.14.0
idna                     3.15
Jinja2                   3.1.6
kiwisolver               1.5.0
Markdown                 3.10.2
markdown-it-py           4.2.0
MarkupSafe               3.0.3
matplotlib               3.10.9
mdurl                    0.1.2
ml_dtypes                0.5.0
mpmath                   1.3.0
networkx                 3.6.1
numpy                    1.26.4
nvidia-cublas-cu12       12.8.3.14
nvidia-cuda-cupti-cu12   12.8.57
nvidia-cuda-nvrtc-cu12   12.8.61
nvidia-cuda-runtime-cu12 12.8.57
nvidia-cudnn-cu12        9.7.1.26
nvidia-cufft-cu12        11.3.3.41
nvidia-cufile-cu12       1.13.0.11
nvidia-curand-cu12       10.3.9.55
nvidia-cusolver-cu12     11.7.2.55
nvidia-cusparse-cu12     12.5.7.53
nvidia-cusparselt-cu12   0.6.3
nvidia-nccl-cu12         2.26.2
nvidia-nvjitlink-cu12    12.8.61
nvidia-nvtx-cu12         12.8.55
onnx                     1.19.0
onnxruntime-gpu          1.26.0
onnxslim                 0.1.94
opencv-python            4.6.0.66
packaging                26.2
pillow                   12.2.0
pip                      24.0
polars                   1.40.1
polars-runtime-32        1.40.1
protobuf                 7.34.1
psutil                   7.2.2
pycocotools              2.0.11
Pygments                 2.20.0
pyparsing                3.3.2
python-dateutil          2.9.0.post0
PyYAML                   6.0.3
regex                    2026.5.9
requests                 2.34.1
rich                     15.0.0
safetensors              0.7.0
scipy                    1.16.0
setuptools               65.5.0
shellingham              1.5.4
six                      1.17.0
sympy                    1.14.0
tabulate                 0.10.0
tensorboard              2.20.0
tensorboard-data-server  0.7.2
tokenizers               0.22.2
torch                    2.7.1+cu128
torchaudio               2.7.1+cu128
torchvision              0.22.1+cu128
tqdm                     4.67.3
transformers             5.8.1
triton                   3.3.1
typer                    0.25.1
typing_extensions        4.15.0
ultralytics              8.4.58
ultralytics-thop         2.0.19
urllib3                  2.7.0
Werkzeug                 3.1.8

BNContrastiveHead(批归一化对比头)

BNContrastiveHead 是一种用于 对比学习 的模块,通常用于视觉-语言多模态任务(如 CLIP 风格)。它将图像特征和文本特征映射到同一度量空间,并计算相似度得分。与常规的 L2 归一化方法不同,该模块对图像特征使用 BatchNorm2d 进行归一化,对文本特征使用 L2 归一化,并通过可学习的温度和偏置调整相似度分布。该设计有助于训练稳定性,并可通过 fuse() 方法在推理时简化模块,提升速度。


代码实现

python 复制代码
import cv2
import math
import torch
import torch.nn as nn
import torch.nn.functional as F
import numpy as np
import matplotlib.pyplot as plt


class BNContrastiveHead(nn.Module):
    """Batch Norm Contrastive Head using batch norm instead of l2-normalization.

    Args:
        embed_dims (int): Embed dimensions of text and image features.
    """

    def __init__(self, embed_dims: int):
        """Initialize BNContrastiveHead.

        Args:
            embed_dims (int): Embedding dimensions for features.
        """
        super().__init__()
        self.norm = nn.BatchNorm2d(embed_dims)
        # NOTE: use -10.0 to keep the init cls loss consistency with other losses
        self.bias = nn.Parameter(torch.tensor([-10.0]))
        # use -1.0 is more stable
        self.logit_scale = nn.Parameter(-1.0 * torch.ones([]))

    def fuse(self):
        """Fuse the batch normalization layer in the BNContrastiveHead module."""
        del self.norm
        del self.bias
        del self.logit_scale
        self.forward = self.forward_fuse

    @staticmethod
    def forward_fuse(x: torch.Tensor, w: torch.Tensor) -> torch.Tensor:
        """Passes image features through unchanged after fusing."""
        return x

    def forward(self, x: torch.Tensor, w: torch.Tensor) -> torch.Tensor:
        """Forward function of contrastive learning with batch normalization.

        Args:
            x (torch.Tensor): Image features.
            w (torch.Tensor): Text features.

        Returns:
            (torch.Tensor): Similarity scores.
        """
        x = self.norm(x)
        w = F.normalize(w, dim=-1, p=2)

        x = torch.einsum("bchw,bkc->bkhw", x, w)
        return x * self.logit_scale.exp() + self.bias

注意 :代码中使用了 F.normalize,需要 import torch.nn.functional as F 才能运行。


功能

  • 特征归一化 :对图像特征 x(形状 [B, C, H, W])应用 BatchNorm2d ,使其在训练时利用批量统计量进行归一化;对文本特征 w(形状 [B, K, C])进行 L2 归一化 (沿特征维度 C),使其模长为 1。
  • 相似度计算 :通过 Einstein 求和(einsum)计算图像特征与文本特征之间的点积相似度,输出形状为 [B, K, H, W],表示每个文本描述与图像每个空间位置的相似度。
  • 可学习温度与偏置 :使用可学习的 logit_scale(温度参数,通过对数尺度控制)和 bias 对相似度进行缩放和平移,以调节分布锐度。
  • 融合模式 :调用 fuse() 可删除 normbiaslogit_scale,并将 forward 重定向到 forward_fuse(直接返回图像特征,忽略文本输入),用于推理时快速处理。

初始化参数

参数 类型 说明
embed_dims int 图像和文本特征的嵌入维度(C
  • self.normBatchNorm2d,对图像特征进行批量归一化。
  • self.bias:可学习偏置,初始化为 -10.0。
  • self.logit_scale:可学习对数尺度参数,初始化为 -1.0(即原始尺度约为 0.3679)。

前向方法

  • forward(x, w)
    • x:图像特征,形状 [B, C, H, W]
    • w:文本特征,形状 [B, K, C],其中 K 为文本描述数量。
    • 返回相似度张量,形状 [B, K, H, W]

计算流程

  1. x = self.norm(x) → 归一化图像特征。
  2. w = F.normalize(w, dim=-1, p=2) → L2 归一化文本特征。
  3. torch.einsum("bchw,bkc->bkhw", x, w) → 计算点积相似度,输出 [B, K, H, W]
  4. x * self.logit_scale.exp() + self.bias → 缩放并平移。
  • forward_fuse(x, w):仅返回 x,忽略 w,用于轻量推理。

使用示例

python 复制代码
if __name__ == "__main__":
    # 模拟输入
    B, C, H, W = 2, 256, 16, 16   # 图像特征
    K = 10                          # 文本描述数量

    x = torch.randn(B, C, H, W)    # 图像特征
    w = torch.randn(B, K, C)       # 文本特征

    # 创建模块
    head = BNContrastiveHead(embed_dims=C)

    # 前向传播
    with torch.no_grad():
        sim = head(x, w)
    print("相似度形状:", sim.shape)  # [2, 10, 16, 16]

    # 融合后推理(忽略文本,仅返回图像特征)
    head.fuse()
    with torch.no_grad():
        fused_out = head(x, w)      # 现在返回 x,与输入相同
    print("融合后输出形状:", fused_out.shape)  # [2, 256, 16, 16]

输出示例

复制代码
相似度形状: torch.Size([2, 10, 16, 16])
融合后输出形状: torch.Size([2, 256, 16, 16])

流程示意图

#mermaid-svg-z3fKwcXILOKlRJOx{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-z3fKwcXILOKlRJOx .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-z3fKwcXILOKlRJOx .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-z3fKwcXILOKlRJOx .error-icon{fill:#552222;}#mermaid-svg-z3fKwcXILOKlRJOx .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-z3fKwcXILOKlRJOx .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-z3fKwcXILOKlRJOx .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-z3fKwcXILOKlRJOx .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-z3fKwcXILOKlRJOx .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-z3fKwcXILOKlRJOx .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-z3fKwcXILOKlRJOx .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-z3fKwcXILOKlRJOx .marker{fill:#333333;stroke:#333333;}#mermaid-svg-z3fKwcXILOKlRJOx .marker.cross{stroke:#333333;}#mermaid-svg-z3fKwcXILOKlRJOx svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-z3fKwcXILOKlRJOx p{margin:0;}#mermaid-svg-z3fKwcXILOKlRJOx .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-z3fKwcXILOKlRJOx .cluster-label text{fill:#333;}#mermaid-svg-z3fKwcXILOKlRJOx .cluster-label span{color:#333;}#mermaid-svg-z3fKwcXILOKlRJOx .cluster-label span p{background-color:transparent;}#mermaid-svg-z3fKwcXILOKlRJOx .label text,#mermaid-svg-z3fKwcXILOKlRJOx span{fill:#333;color:#333;}#mermaid-svg-z3fKwcXILOKlRJOx .node rect,#mermaid-svg-z3fKwcXILOKlRJOx .node circle,#mermaid-svg-z3fKwcXILOKlRJOx .node ellipse,#mermaid-svg-z3fKwcXILOKlRJOx .node polygon,#mermaid-svg-z3fKwcXILOKlRJOx .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-z3fKwcXILOKlRJOx .rough-node .label text,#mermaid-svg-z3fKwcXILOKlRJOx .node .label text,#mermaid-svg-z3fKwcXILOKlRJOx .image-shape .label,#mermaid-svg-z3fKwcXILOKlRJOx .icon-shape .label{text-anchor:middle;}#mermaid-svg-z3fKwcXILOKlRJOx .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-z3fKwcXILOKlRJOx .rough-node .label,#mermaid-svg-z3fKwcXILOKlRJOx .node .label,#mermaid-svg-z3fKwcXILOKlRJOx .image-shape .label,#mermaid-svg-z3fKwcXILOKlRJOx .icon-shape .label{text-align:center;}#mermaid-svg-z3fKwcXILOKlRJOx .node.clickable{cursor:pointer;}#mermaid-svg-z3fKwcXILOKlRJOx .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-z3fKwcXILOKlRJOx .arrowheadPath{fill:#333333;}#mermaid-svg-z3fKwcXILOKlRJOx .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-z3fKwcXILOKlRJOx .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-z3fKwcXILOKlRJOx .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-z3fKwcXILOKlRJOx .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-z3fKwcXILOKlRJOx .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-z3fKwcXILOKlRJOx .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-z3fKwcXILOKlRJOx .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-z3fKwcXILOKlRJOx .cluster text{fill:#333;}#mermaid-svg-z3fKwcXILOKlRJOx .cluster span{color:#333;}#mermaid-svg-z3fKwcXILOKlRJOx div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-z3fKwcXILOKlRJOx .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-z3fKwcXILOKlRJOx rect.text{fill:none;stroke-width:0;}#mermaid-svg-z3fKwcXILOKlRJOx .icon-shape,#mermaid-svg-z3fKwcXILOKlRJOx .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-z3fKwcXILOKlRJOx .icon-shape p,#mermaid-svg-z3fKwcXILOKlRJOx .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-z3fKwcXILOKlRJOx .icon-shape .label rect,#mermaid-svg-z3fKwcXILOKlRJOx .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-z3fKwcXILOKlRJOx .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-z3fKwcXILOKlRJOx .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-z3fKwcXILOKlRJOx :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 融合模式
输入 x, w
直接返回 x (忽略 w)
图像特征 x (B, C, H, W)
BatchNorm2d
归一化后 x (B, C, H, W)
文本特征 w (B, K, C)
L2 归一化 (dim=-1)
归一化后 w (B, K, C)
einsum: bchw,bkc->bkhw

计算相似度 (B, K, H, W)
缩放: * exp(logit_scale) + bias
输出相似度 (B, K, H, W)


代码解读

  • __init__
    • norm:BatchNorm2d 用于对图像特征进行归一化,在训练时使用批量统计量,推理时使用运行统计量。
    • biaslogit_scale 均为可学习参数,初始值分别设为 -10.0 和 -1.0,以保持初始损失与其他损失函数一致。
  • forward
    • 先对 x 进行 BatchNorm,再对 w 进行 L2 归一化(沿最后一个维度),使每个文本向量模长为 1。
    • 使用 einsum 高效计算点积,并将图像特征的空间维度(H, W)保留,使得每个空间位置的像素都能与所有文本特征计算相似度。
    • 最后通过指数缩放和偏置调整输出范围。
  • fuse
    • 删除 norm, bias, logit_scale 属性,并将 forward 替换为 forward_fuse
    • forward_fuse 直接返回图像特征,忽略文本特征,适用于仅需要图像特征的场景(如分类或检索)。
  • 依赖 :需要导入 torch.nn.functional as F 以使用 F.normalize

注意事项

  1. BatchNorm2d 模式 :训练时应保持 self.norm 处于 train() 模式,以便累积运行统计量;推理时需切换至 eval() 模式,或调用 fuse() 彻底移除 BN。
  2. 输入形状w 的最后一维必须等于 embed_dims,否则无法与 x 计算点积。
  3. fuse() 后使用 :融合后 forward 仅返回 x,不再返回相似度,因此需确保后续网络正确处理。
  4. 温度初始化logit_scale 初始为 -1.0,实际温度约为 0.3679,可能偏小,可根据任务调整。
  5. 内存开销:由于输出包含空间维度 H×W,当分辨率较大时,相似度张量占用显存较多。

优缺点

优点
  1. 训练稳定:BatchNorm 能减少内部协变量偏移,加速收敛。
  2. 保留空间信息:输出保持空间维度,适用于密集预测或像素级对比学习。
  3. 融合便捷 :提供 fuse() 方法,便于推理时裁剪冗余参数,提升速度。
  4. 灵活的温度缩放:可学习参数使模型能自适应调整相似度分布。
缺点
  1. 依赖批量统计量:BatchNorm 在小 batch 下可能不稳定,且推理时需使用运行统计量。
  2. 融合后功能单一fuse() 后无法再进行相似度计算,限制了灵活性。
  3. 额外参数:相比简单的 L2 归一化,增加了 BatchNorm 的可学习参数(gamma, beta)以及温度、偏置参数。
  4. 输入约束 :要求 w 的通道维与 embed_dims 严格匹配。

在对比学习或视觉-语言多模态任务中,BNContrastiveHead 可作为图像与文本特征对齐的头部模块。使用时应合理设置 embed_dims,并根据训练和推理场景选择是否调用 fuse()。若任务需要相似度输出,则保持完整模块;若仅需图像特征,则可融合以加速。

参考文献

1 https://docs.ultralytics.com/

2 https://github.com/ultralytics/ultralytics.git

相关推荐
tkevinjd1 小时前
416分割等和子集
java·python·算法·leetcode·职场和发展
模型时代1 小时前
景嘉微的AI芯片账:64TOPS边端SoC在导入,商业航天暂未形成订单
人工智能·ai芯片·景嘉微
小呀小叮当~1 小时前
Telegram 有哪些实用功能?一文了解
前端·人工智能·后端·其它
CAIE研习社2 小时前
大学生数据分析作品集,应该包含哪些内容?
人工智能·数据分析
namelijink2 小时前
yolo26 目标检测原理
人工智能·目标检测·计算机视觉
ltqvibe2 小时前
TokUI怎么让AI输出从文字墙变成可交互UI
人工智能·ui·交互
薛定猫AI2 小时前
【技术干货】多模型协同编程实战:基于角色路由与工作树构建AI开发流水线
人工智能
国服第二切图仔2 小时前
LabGuide(Pip)基础医学实验AI眼镜智能助手项目介绍
人工智能·ai眼镜·智能体开发大赛
对不起初见i2 小时前
TokenFaucet 大模型 API中转站
人工智能·ai·chatgpt