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

相关推荐
雪隐2 分钟前
个人电脑玩AI-15让5060 Ti给你打工——MiniMax H3 本地部署实录:一个自带录音棚的视频模型,和它的 NVFP4 瘦身奇遇
前端·人工智能·后端
数字供应链安全产品选型12 分钟前
中国版 Anthropic Mythos,为何是悬镜安全?
人工智能·安全
甲维斯15 分钟前
Qoder+Qwen3.8Max白嫖测试!这次真牛逼了?和K3比如何?
人工智能
一个数据大开发16 分钟前
Skill、Tool、SOP、MCP 文章合集
大数据·人工智能·知识图谱
紫禁玄科19 分钟前
公共WiFi流量安全全解析
网络·人工智能·web安全·网络安全·系统安全
05664623 分钟前
Python高级——解释器执行原理与虚拟环境工程化实战
开发语言·python
weixin_4357761124 分钟前
2026年长沙托育vi设计从风格定位到元素运用的设计方法
linux·运维·服务器·python
梦想三三27 分钟前
LangChain RAG PDF 智能问答实战:用 Streamlit 构建本地知识库(完整代码)
人工智能·python·langchain·大模型·rag
不加辣椒30 分钟前
第11章:性能优化与成本控制
人工智能
xcLeigh32 分钟前
KingbaseES 的卢智能运维体架构深度拆解
运维·数据库·人工智能·ai·架构·ffmpeg·智能体