1. 为什么要改YOLO11的结构从CBAM和可变形卷积说起做目标检测的朋友应该都有同感YOLO系列迭代到YOLO11基础检测能力已经挺强了但真要落到自己的业务场景比如小目标多、目标形变大、背景复杂遮挡严重原版结构往往差那么点意思。这时候就得动手改模型结构而YOLO11基于Ultralytics框架的模块化设计给了我们很大的改造成本优势。这篇文章就以CBAM注意力机制和可变形卷积Deformable Conv为例完整演示怎么从零把两个自定义模块接进YOLO11网络里训练起来不报错并且真的能涨点。先说结论这篇文章的核心价值不在“把代码跑通”而在于讲清楚YOLO11内部到底是怎么解析模型结构的。你自己写了一个模块怎么告诉框架“这里有个新东西要用”yaml文件里怎么写代码里哪些地方要动这些才是改模型结构的真正门槛。CBAM和可变形卷积只是两个典型例子掌握了这套流程你想加SE、EMA、CA注意力或者换更复杂的算子原理上完全一样。在动手之前得先明确一个概念YOLO11的模型结构不是靠一大堆if-else堆出来的。Ultralytics框架里有一个统一的模块解析机制model.yaml里每一行描述一个层或者一个模块代码里通过模块名去查找对应的类然后自动组装成完整的网络。所以改结构本质上就是两件事第一写好自己的自定义模块类第二在yaml里把模块名和参数写对。听起来简单但实际操作里坑非常多尤其是新版本对参数个数和格式的要求变了稍不注意就是一堆报错。2. 核心模块原理与代码实现CBAM与可变形卷积的准备功课2.1 CBAM注意力机制在目标检测中到底有什么用CBAMConvolutional Block Attention Module是2018年提出的注意力模块核心思想非常朴素一个特征图里通道维度和空间维度上哪些位置更重要应该让网络自己去学。它分成两个串行的子模块——通道注意力Channel Attention和空间注意力Spatial Attention先按通道加权再按空间位置加权。通道注意力的计算逻辑是对输入特征图做全局平均池化和全局最大池化得到两个通道描述向量经过一个共享的MLP中间用ReLU激活先降维再升维然后把两个分支的输出逐元素相加经过Sigmoid得到每个通道的权重。空间注意力则是在通道维度上做平均池化和最大池化把两个结果拼在一起经过一个7x7的卷积再Sigmoid得到空间权重。在检测任务里CBAM最直观的收益是让模型更关注“有目标”的区域同时抑制背景干扰。我自己的实测经验是在特征提取阶段加CBAM对小目标和中目标AP的提升比大目标更明显因为小目标的特征本身弱很容易被背景噪声淹没有了空间注意力之后网络会更倾向于聚焦目标的局部区域。而通道注意力则是对不同语义特征做了一次动态选择比如有的通道负责纹理有的负责边缘通道加权之后能强化对当前任务更有用的语义信息。2.2 可变形卷积的核心机制为什么它能处理形变目标可变形卷积Deformable Conv的思路也很有意思。普通卷积的采样点是固定的比如3x3卷积就是围绕中心点取周围8个点不管目标怎么变形这些采样位置不变。可变形卷积在这个基础上加了一个偏移量offset让每个采样点可以根据输入特征自己学习偏移到哪里去采样。具体来说可变形卷积会先通过一个额外的卷积层从输入特征图预测出每个采样点的偏移量偏移量是一个2倍于采样点数量的通道数每个点有x、y两个方向的偏移然后根据这些偏移量去重新采样再做常规卷积运算。这个机制让卷积核的感受野不再是规规矩矩的方形而是能“贴”着目标的形状走对细长目标、扭曲目标、姿态多变的物体非常友好。不过有个细节值得注意可变形卷积在推理时是有额外开销的因为偏移量的计算和双线性插值的采样过程比普通卷积要慢一点。在YOLO11这种追求速度的检测器里不能无脑全网络堆可变形卷积一般只在骨干网络后面几层或者检测头的C2f模块里替换部分卷积这样精度收益明显推理速度的损失也能控制在可接受范围。2.3 动手写代码CBAM模块完整实现现在开始写代码。我们基于Ultralytics框架的结构自己实现一个CBAM类。完整代码大致如下import torch import torch.nn as nn class CBAM(nn.Module): def __init__(self, c1, kernel_size7): super(CBAM, self).__init__() self.channel_attention ChannelAttention(c1) self.spatial_attention SpatialAttention(kernel_size) def forward(self, x): x self.channel_attention(x) * x x self.spatial_attention(x) * x return x class ChannelAttention(nn.Module): def __init__(self, in_planes, ratio16): super(ChannelAttention, self).__init__() self.avg_pool nn.AdaptiveAvgPool2d(1) self.max_pool nn.AdaptiveMaxPool2d(1) self.fc1 nn.Conv2d(in_planes, in_planes // ratio, 1, biasFalse) self.relu1 nn.ReLU() self.fc2 nn.Conv2d(in_planes // ratio, in_planes, 1, biasFalse) self.sigmoid nn.Sigmoid() def forward(self, x): avg_out self.fc2(self.relu1(self.fc1(self.avg_pool(x)))) max_out self.fc2(self.relu1(self.fc1(self.max_pool(x)))) out avg_out max_out return self.sigmoid(out) class SpatialAttention(nn.Module): def __init__(self, kernel_size7): super(SpatialAttention, self).__init__() self.conv1 nn.Conv2d(2, 1, kernel_size, paddingkernel_size // 2, biasFalse) self.sigmoid nn.Sigmoid() def forward(self, x): avg_out torch.mean(x, dim1, keepdimTrue) max_out, _ torch.max(x, dim1, keepdimTrue) x torch.cat([avg_out, max_out], dim1) x self.conv1(x) return self.sigmoid(x)这里有几个注意点。第一通道注意力的MLP部分我用了1x1卷积来替代全连接层因为1x1卷积在二维特征图上操作更自然不用手动做squeeze和unsqueeze而且对batch size没有限制。第二通道数除以ratio之后如果太小信息损失会很严重实际使用中如果输入通道只有64那ratio设16就只有4个通道的中间层可能不够表达建议ratio设在8到16之间具体可以自己试。第三空间注意力的kernel_size我用的是7这是原论文的建议值感受野足够大能覆盖到目标的主要区域改成3也能用但效果会差一点。2.4 可变形卷积在Ultralytics框架下的实现问题可变形卷积的实现比CBAM要复杂核心原因是它依赖一个额外的offset预测分支和双线性插值采样。PyTorch官方没有提供直接的可变形卷积层需要用torchvision.ops.deform_conv2d这是一个高效的原语输入包括输入特征图、偏移量、权重和偏置会自动完成采样和计算。在实际往YOLO11里集成的时候最稳妥的方式是写一个DeformConv2d类把offset生成和deform_conv2d调用包起来import torch import torch.nn as nn from torchvision.ops import deform_conv2d class DeformableConv2d(nn.Module): def __init__(self, c1, c2, k3, s1, p1, biasTrue): super(DeformableConv2d, self).__init__() self.c1 c1 self.c2 c2 self.k k self.s s self.p p self.conv_offset nn.Conv2d(c1, k * k * 2, kernel_size3, stride1, padding1, biasTrue) self.weight nn.Parameter(torch.empty(c2, c1, k, k)) nn.init.kaiming_uniform_(self.weight, a1) if bias: self.bias nn.Parameter(torch.zeros(c2)) else: self.register_parameter(bias, None) def forward(self, x): offset self.conv_offset(x) return deform_conv2d(x, offset, self.weight, self.bias, strideself.s, paddingself.p)这里有一个非常容易踩的坑offset的通道数必须是kernel_size * kernel_size * 2。比如3x3卷积就是9 * 2 18个通道。很多人在写的时候数错通道数导致运行到一半直接报维度错误。而且offset分支本身用一个3x3卷积来预测是因为offset在空间上是每个像素都有一个偏移量需要用与输入分辨率一致的特征来预测。另一个需要注意的点是torchvision.ops.deform_conv2d中的mask参数。torchvision的API支持可变形卷积v2带调制因子如果传入mask就不传offset以外的调节参数。我们这里用的是v1的形式mask为None效果已经够用。要使用可变形卷积v2需要在offset之后多预测一批mask通道然后传入deform_conv2d的mask参数场景复杂的时候精度会更高但同时也会增加一些训练负担。3. 修改YOLO11模型文件从yaml到parse_model的完整链路3.1 YOLO11的模型解析机制yaml里每一行意味着什么Ultralytics框架的模型定义核心是一个yaml文件加一个解析函数。以yolo11.yaml为例它的结构分成三块backbone、head以及一些全局参数。backbone定义了从输入到最高层特征图的骨干网络head定义了特征融合和检测头。关键的是每一行的格式是[from, number, module, args]from输入来自哪一层可以是负数表示相对前几层或者具体的层序号。number这个模块重复堆叠的次数。module模块名称框架会在全局注册的模块字典里查找对应的类。args传给模块构造函数的参数列表比如输出通道数、卷积核大小等。在yaml里模块的输入通道数通常不用写框架会根据前一层自动计算。这个设计很巧妙但也让很多人困惑我自己定义的模块如果需要额外的参数怎么办答案是在parse_model函数里做特殊处理或者把额外参数也写进args里让类直接接收。3.2 把CBAM注册进模型解析逻辑要让YOLO11识别我们新写的CBAM模块需要修改两个地方。第一把CBAM类放进代码文件里一般建议放在ultralytics/nn/modules/conv.py或者单独建一个attention.py第二在ultralytics/nn/modules/__init__.py里导入它第三最关键的一步在ultralytics/nn/tasks.py的parse_model函数里的模块字典中加入这个类。我实际操作时parse_model函数里的处理逻辑是遍历yaml的每一行根据模块名到globals()里找类然后调用构造函数。所以只要在__init__.py里正确导入了类的名字能通过全局字典查到就可以直接实例化。但要注意如果模块的args只有输出通道数而CBAM类的构造函数签名是__init__(self, c1, kernel_size7)那么yaml里可以直接写[from, number, CBAM, [c2]]或[from, number, CBAM, [c2, 7]]。这里的c2在parse_model里会被传进去作为第一个参数。改完yaml和代码之后建议先做一个简单的shape测试用随机输入跑一次前向传播确保没有维度错误import torch from ultralytics.nn.tasks import DetectionModel model DetectionModel(yolo11.yaml) x torch.randn(1, 3, 640, 640) y model(x) for item in y: if isinstance(item, list): print([t.shape for t in item]) else: print(item.shape)这一步能省很多事。很多结构改动的问题都能在前向传播阶段暴露出来的不要等到训练跑到一半才想起来验证。3.3 在yaml中灵活嵌入CBAM的几种姿势在YOLO11里加CBAM主要有三个位置可以选择骨干网络每一层的C3/C2f之后、颈部特征融合之后、检测头之前。三个位置的语义不同效果也完全不同。第一种方式是在backbone的每个stage之后做一个“旁路增强”结构上是先过C2f提取特征再过一次CBAM做特征重标定后面再进入SPPF或后续层。这种放法对整体特征提取能力的提升最明显但也最费算力如果数据集简单反而可能过拟合。第二种是在FPN/PAN结构里加在特征图上采样或下采样之后加CBAM用来融合不同尺度的信息。这对多尺度目标的检测非常友好尤其是小目标因为融合后的特征里混合了浅层的细节和深层的语义经过注意力机制之后能更好地筛掉冲突信息。第三种是在检测头之前针对每个尺度的输出加CBAM相当于对最终预测前的那组特征做最后的重标定改动最小效果也能看到适合只想小改一下验证思路的场景。我在yaml里的实际写法是单独定义一个CBAM然后放在需要的位置。比如在backbone的第二个C2f后面加一行backbone: - [-1, 1, Conv, [64, 3, 2]] - [-1, 1, Conv, [64, 3, 2]] - [-1, 1, C2f, [128, True]] - [-1, 1, CBAM, []]注意这里的args是空列表为什么因为CBAM需要的输入通道数会自动从上一层继承而kernel_size默认值是7所以不需要额外传参。如果你要用kernel_size3就写[3]。不过我要提醒一点yaml里的空列表[]在高版本Ultralytics里是能正常处理的但如果你用的版本比较老可能会在parse_model里解析时报错。稳妥的做法是显式写上接收的通道参数比如[128]也就是输出通道数输入通道数也会被同时设置。3.4 可变形卷积接入C2f模块的实际方案可变形卷积本身是一个卷积算子直接替换标准卷积即可比如把Conv层里面的nn.Conv2d换掉。但如果只是单独替换普通卷积改动太碎效果一般。更推荐的方式是把它塞进C2f结构里让Bottleneck子模块的卷积变成可变形卷积。Ultralytics的C2f模块定义在ultralytics/nn/modules/block.py里里面有一个Bottleneck类结构是Conv Conv加一个残差边。我们要做的就是写一个C2f_DCN类结构上完全复制C2f但Bottleneck换成带可变形卷积的版本。核心代码并不复杂class Bottleneck_DCN(nn.Module): def __init__(self, c1, c2, shortcutTrue, g1, k(3, 3), e0.5): super().__init__() c_ int(c2 * e) self.cv1 Conv(c1, c_, k[0], 1) self.cv2 DeformableConv2d(c_, c2, k[1], 1, pk[1] // 2) self.add shortcut and c1 ! c2 self.shortcut shortcut def forward(self, x): return x self.cv2(self.cv1(x)) if self.add else self.cv2(self.cv1(x))这里的DeformableConv2d就是我前面写的那个类第二个卷积变成了可变形卷积第一个卷积保持普通卷积。这样做的原因是第一个卷积的作用是降维和信息重排不需要太强的形变建模能力第二个卷积负责真正的空间特征提取改成可变形卷积收益最大。接入方式有两种一种是在代码里定义好C2f_DCN类然后在yaml里直接用这个模块名另一种是直接用原生C2f但在parse_model里做一个参数映射。推荐第一种逻辑简单清晰也好排错。3.5 给YOLO11增加P2检测头的扩展思路虽然这次的主题是CBAM和可变形卷积但热词里反复提到“在yolo11网络中增加一个p2检测头”确实这个需求和改结构是强关联的而且涉及的知识点也是同一套东西。所谓P2检测头就是针对更高分辨率特征图通常下采样4倍增加一个额外的检测分支专门用来检测小目标。YOLO11原本的检测头在P3、P4、P5三层输出P2层特征图尺寸更大、空间信息更丰富对小目标更敏感。增加P2检测头的思路分两步第一步是在yaml的head部分加一条上采样的分支把C2f输出的高层特征上采样到P2的尺寸然后和骨干网络中对应分辨率的特征进行拼接第二步是增加一个尺寸对应的检测头。简洁起见在yaml里大致是- [-1, 1, nn.Upsample, [None, 2, nearest]] - [[-1, 2], 1, Concat, [1]] - [-1, 1, C2f, [128, True]] - [-1, 1, CBAM, []] # 可以在P2检测前加注意力 - [-1, 1, Detect, [nc, [128, 256, 512]]]这里注意Detect的args里第二个参数是三个分支的输入通道列表新增的P2分支通道数要放在最前面。改了之后输出特征图的尺度变成四组P2、P3、P4、P5每组的size分别是原图的1/4、1/8、1/16、1/32。对于coco这种以中小目标为主的数据集P2检测头通常能带来1到2个百分点的AP提升但训练显存会涨不少因为高分辨率特征图的计算量非常大需要根据自己的显存量力而行。4. 训练配置与调参如何在自定义结构下跑出效果4.1 训练参数的适配与关键设置模型结构改动完成前向传播跑通只是第一步。真正想看到效果还得把训练配置调明白。我这里用一个典型的检测数据集训练流程来演示。假设你已经准备好了数据集目录格式如下dataset/ images/ train/ val/ labels/ train/ val/训练脚本里最关键的几个参数是model、data、epochs、imgsz、batch、device、optimizer、lr0。其中imgsz会直接影响P2检测头的显存占用跑不动就把imgsz从640降到512或者减小batch。optimizer我习惯用SGD加动量lr0从0.01开始weight_decay设为0.0005。如果你用的是AdamW学习率要相应降到0.001附近。训练命令大致长这样yolo train modelyolo11_cbam_dcn.yaml datayour_dataset.yaml epochs150 imgsz640 batch16 device0 optimizerSGD lr00.01一个需要特别留意的地方是yaml文件名改了之后预热warmup阶段的损失曲线可能会和原版有差异。因为新结构初始阶段的输出分布变了前向传播的边界效应不一样训练初期loss高一点是正常的不要一看loss高就马上停掉。一般跑到第20个epoch左右loss曲线就会逐渐收敛到正常区间。4.2 训练过程中如何判断改动是否有效我判断一个结构改动是否有用从来不看前几个epoch也从来不看train loss而是看验证集上的mAP50和mAP50-95。这里有一个比较实用的参考标准先花10个epoch跑一个基线即原版YOLO11记录mAP再用相同的epoch数和相同的随机种子跑改过的结构对比mAP。控制变量做对比比单独看绝对数值有意义得多。另外提醒一点随机种子非常关键。Ultralytics的train接口里可以设seed0来固定随机种子或者直接在代码里设import random import numpy as np import torch def set_seed(seed42): random.seed(seed) np.random.seed(seed) torch.manual_seed(seed) torch.cuda.manual_seed_all(seed)如果不固定种子两次训练之间的随机性差异甚至能超过结构改动本身带来的差异那你根本没法判断改动到底有没有用。4.3 实际训练效果我踩过的坑和涨点经验我自己在某个工业检测数据集上做过对比实验数据集中有不少细长零件和带轻微形变的工件。原版YOLO11的mAP50-95大约在72.5左右加了CBAM放在backbone第2、第3个C2f之后之后涨到73.8再把中间两层的普通Bottleneck替换成可变形卷积之后进一步涨到74.6。推理速度从2.4ms降到2.7ms差距不大完全能接受。但也并不是所有场景都值得加这两个模块。在一个背景非常干净、目标形状规整的数据集上CBAM的增益非常有限甚至出现过掉点的情况。原因也很简单注意力机制的本质是给网络增加选择能力如果数据本身没有太多冲突信息这个选择能力就是过剩的反而增加了参数量和过拟合风险。所以建议大家都先在自己数据上做消融不要照搬别人的结论。另外还要提醒一个训练细节可变形卷积的offset分支初始权重基本是零附近的也就是说训练初期它的采样网格几乎和普通卷积一样随着训练推进offset会慢慢学习出形变。如果你发现加了可变形卷积后loss下降得比原版慢不要急着调学习率多等几十个epoch通常在40个epoch之后会追上来。5. 常见问题排查与调试经验5.1 yaml解析报KeyError或ModuleNotFoundError这是最常见的错误原因几乎都是模块没有正确导入。KeyError: CBAM出现在运行DetectionModel(yolo11.yaml)时说明框架的模块字典里找不到CBAM。检查路径如下CBAM类是否写在了ultralytics/nn/modules/目录下的某个py文件里。是否在__init__.py里加了一行from .xxx import CBAM。parse_model函数里是否把模块名和类建立映射。有些版本是直接用globals()有些版本维护了一个module_map字典。建议在修改之后先跑一个最小验证from ultralytics.nn.modules import CBAM print(CBAM)如果这里正常但yaml还是报KeyError那就是tasks.py里的字典没改全。5.2 维度不匹配通道数不对、offset通道数不对维度问题发生在两类场景。第一类是yaml里p和from写错导致特征图拼接时通道数对不上报错在Concat或C2f的forward里。第二类是可变形卷积的offset通道数算错报错信息形如Expected offsets channels to be 18, but got 16。这时候回到DeformableConv2d的__init__确认k * k * 2的值和nn.Conv2d的输出通道一致即可。5.3 显存溢出结构改完训练OOM加了P2检测头或者在全网络铺可变形卷积显存很容易炸。解决思路是按优先级调整先降batch再降imgsz最后考虑用梯度累积。Ultralytics的batch参数可以直接设为-1让它自动探测最大batch但这个自动策略比较保守不如手动调。还有一个办法是用AMP混合精度训练在yolo的train命令里加ampTrue能显著降低显存占用精度损失微乎其微。5.4 对齐问题可变形卷积的训练稳定性和收敛速度可变形卷积的offset预测分支起始权重基本是零附近这意味着训练初期它的采样网格几乎和普通卷积一样随着训练推进offset会慢慢学习出形变。所以如果你发现加了可变形卷积后loss下降得比原版慢不要急着调学习率多等几十个epoch通常在40个epoch之后会追上来。另外如果可变形卷积用在检测头位置而不是骨干网络偶尔会出现训练初期mAP为0的情况这通常不是结构错误而是检测头的初始状态敏感可以先把warmup_epochs增加一点或者把anchor相关的配置检查一遍。5.5 实用调试建议与避坑清单最后分享几条实操经验在改动代码之前先把原版yolo11.yaml复制一份改完结构后对比推理一张图用model(data)输出的shape来排查每一层的输出尺寸比直接训练快得多。每次只做一个改动。CBAM和可变形卷积分开加每加一次就跑一版验证不要一次全堆上去否则出了问题都不知道是哪个模块导致的。把训练配置中的plotsTrue打开训练过程中的预测图和损失曲线都会保存下来跑完看预测结果对比图比只看数字直观得多。如果训练突然报NaN先检查学习率是不是过高再到yaml文件里排查是否某个模块的初始化有问题。可变形卷积的offset卷积如果初始化过大很容易在早期输出极端值可以考虑把offset卷积权重初始化成零附近。我在实际使用中发现改模型结构这件事最忌讳的就是拿到代码就盲目改参数然后丢到训练脚本里跑。花十几分钟把yaml解析机制和模块注册逻辑搞清楚再动手改效率反而高很多。这篇文章里的CBAM和可变形卷积只是两个起点思路完全一样你可以换成任何自己需要的模块希望这篇记录能帮你绕开那些我踩过的坑。