Ultralytics block.py 块模块库深度解析支撑 YOLO26 / YOLO11 骨干的 CSP、注意力与 RepLearner 积木【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics本文围绕 block.py 参考文档 所对应的核心源码 ultralytics/nn/modules/block.py系统讲解 Ultralytics 中全部 50 余个神经网络块block模块的设计意图、参数约定与前向逻辑并结合 tasks.py 的parse_model解析流程与 yolo26.yaml 等真实模型配置说明这些积木如何被组合成 YOLO26、YOLO11、YOLOv9/v10/v12 等完整网络。读完本文你将能够读懂任意 Ultralytics 模型 YAML 中出现的块名理解c1/c2/n/e/shortcut等参数约定的来龙去脉并具备在自定义模型中选用合适 block 的能力。一、block.py 在架构中的位置Ultralytics 的模型构建遵循「YAML 描述结构、源码提供积木」的两层设计积木层ultralytics/nn/modules/block.py约 2000 行集中定义了 CSP 系列、空间金字塔池化、注意力、可重参数化、视觉-语言专用等全部基础块同目录下的 conv.py 提供Conv、DWConv、GhostConv、RepConv、LightConv、autopad等底层卷积原语block 层在其上组装。组装层ultralytics/nn/tasks.py 中的parse_model按行读取 YAML 的[from, repeats, module, args]用globals()[m]把模块名解析为 Python 类实例见 tasks.py 模块解析并按width/depth/max_channels自动缩放通道数与重复次数。配置层ultralytics/cfg/models 目录下按系列26/、11/、12/、v9/、v10/等存放各模型 YAML每行即一次块调用。block.py顶部的__all__block.py#L17-L57声明了 31 个对外导出的核心符号其余类如TorchVision、ResNetLayer、HGStem、HGBlock、Proto26等则供特定模型按需引用。二、通用参数约定读懂一切块的前提几乎所有块都遵循同一套参数命名掌握后即可脱离源码读懂任意 YAML 行参数含义典型默认值c1输入通道数由parse_model根据from自动注入—c2输出通道数按make_divisible(min(c2, max_channels) * width, 8)缩放见 tasks.py#L2070-L2073—n重复次数属于repeat_modules的块会被插入为第 3 个位置参数tasks.py#L2035-L20871e隐层通道扩展比隐层宽度 int(c2 * e)0.5shortcut是否允许残差直连实际生效还需c1 c2True/False视块而定g分组卷积的组数1k卷积核大小Conv内会经autopad自动补齐 padding3例如 yolo26.yaml 中的一行- [-1, 2, C3k2, [512, True]]表示取上一层输出重复 2 次输出通道 512c3kTruec1和重复数n都由解析器自动补全。三、基础瓶颈块Bottleneck 家族3.1 Bottleneck 标准瓶颈Bottleneck 是全部 CSP 块的最内层单元两层卷积Conv(c1→c2*e, k[0])Conv(c2*e→c2, k[1], gg)当shortcut and c1 c2时执行x f(x)残差相加否则直接输出。它本身不做通道拆分纯粹是被上层块堆叠的「砖」。3.2 BottleneckCSPBottleneckCSP 是经典 CSP 思想Cross Stage Partial Networks的实现输入先经cv1送入n个Bottleneck序列再与cv2(x)的旁路分支在通道维拼接经BatchNorm2d SiLU后由cv4压缩为c2通道。它是 v5 时代骨干的主力块。3.3 GhostBottleneckGhostBottleneck 用廉价卷积生成「ghost 特征」GhostConv(1x1)→ 可选DWConv仅s2时降采样→GhostConv(1x1, 无激活)主支与 shortcut 支相加。它是 C3Ghost 的内核用于 v8-ghost 等轻量变体如 yolov8-ghost.yaml。3.4 ResNetBlock / ResNetLayerResNetBlock 是标准的 ResNet 残差块1x1 → 3x3 → 1x1扩比e4通道不匹配或步长不为 1 时自动生成 1x1 投影 shortcut末尾ReLUResNetLayer 则把若干块串成层首个层自动加 7x7 卷积 3x3 最大池化的「stem」。parse_model对ResNetLayer有专门的通道推断分支tasks.py#L2106-L2107它们共同支撑 yolo11-cls-resnet18.yaml 这类分类骨干。四、CSP 系列YOLO 骨干的绝对主力4.1 C1 与 C2C11 卷积 CSP。cv1(x)后经n个 3x3Conv输出self.m(y) y。结构最简多用于小模型。C22 卷积 CSP。cv1把通道扩到2*c后chunk(2)拆成两半一半流经n个Bottleneck隐层e1.0另一半直通拼接后由cv2压回c2。4.2 C2fv8 时代的核心块C2f 是 C2 的「更快实现」也是 YOLOv8/v11 的主力def forward(self, x): y list(self.cv1(x).chunk(2, 1)) # cv1 输出 2*c 通道拆两半 y.extend(m(y[-1]) for m in self.m) # 逐块堆叠每块吃上一块输出 return self.cv2(torch.cat(y, 1)) # 所有分支(2n)份拼接后 1x1 压缩关键差异在于「级联式堆叠 全分支拼接」n个Bottleneck依次接力最终把2n份特征全部拼进cv2梯度路径更多、算力利用更充分。它还提供forward_split用显式split替代chunk供推理后端优化。在parse_model中C2f同属repeat_modulesYAML 第二列的重复数会被注入为ntasks.py#L2035-L2053。4.3 C3 家族v5 主力的各种变体C3 是 3 卷积 CSPcv1/cv2两个 1x1 分支一个流经n个Bottleneck(k((1,1),(3,3)))拼接后cv3输出。其子类仅替换内部self.m子类位置内部 m 替换为特点C3x同上Bottleneck(k((1,3),(3,1)))交叉方向卷积核增强跨行/列感受野C3TR同上TransformerBlock(c_, c_, 4, n)卷积Transformer 混合用于 rtdetr 类模型C3Ghost同上GhostBottleneck序列轻量 ghost 卷积C3f独立类C2f 式级联拼接3 卷积版 C2fcv2输入改为(2n)*c_C3k同上Bottleneck(k(k,k))核大小k可配置默认 34.4 C3k2YOLO26 的主干块C3k2 继承自C2f把内部模块按三个开关替换attnTrue每个单元为Bottleneck PSABlock(attn_ratio0.5, num_headsmax(c//64, 1))的级联引入位置敏感注意力c3kTrue每个单元为C3k(c, c, 2)即内含 2 个 Bottleneck 的 C3 子块否则退化为普通Bottleneck。parse_model对它有一个规模敏感的默认值注入当 scale 为m/l/x且 YAML 未显式给出c3k参数时自动补Truetasks.py#L2088-L2091。yolo26.yaml 的 backbone 完全由C3k2ConvSPPFC2PSA构成例如backbone: - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 - [-1, 2, C3k2, [256, False, 0.25]] ... - [-1, 1, SPPF, [1024, 5, 3, True]] # 9 - [-1, 2, C2PSA, [1024]] # 10可见同一份 YAML 通过scalesdepth/width/max_channels 三元组即可派生 n/s/m/l/x 五个尺寸而块级差异正是由C3k2的参数注入规则实现的。4.5 带注意力的 C2f 变体C2fAttn在 C2f 的拼接列表中额外追加一路MaxSigmoidAttnBlock输出通道数变为(3n)*c前向需要第二个输入guide文本嵌入是 v8-world 等开放词汇检测模型的关键组件parse_model对其nh头数与隐层通道有专门整除校验tasks.py#L2074-L2082。C2fPSA继承C2f将内部Bottleneck全部替换为PSABlock要求c1 c2。五、空间金字塔池化SPP / SPPF / SPPELANSPP经典空间金字塔池化。cv1压缩到c1//2后对k(5,9,13)三组MaxPool2d(stride1, paddingk//2)输出与自身拼接再由cv2还原。SPPFFast 版。用同一个MaxPool2d(k5)串联n3次再拼接等价于SPP(k(5,9,13))源码 Notes 中明确说明但参数与算力大幅减少shortcutTrue且c1c2时输出y x。它是历代 YOLO 骨干倒数第二层的标配yolo26.yaml 中写作- [-1, 1, SPPF, [1024, 5, 3, True]]。SPPELANSPP 的 ELAN 风格实现三个大核最大池化级联后与初始分支拼接4 份用于 v9 系列如 yolov9e.yaml。六、注意力模块族6.1 MaxSigmoidAttnBlock 与 C2fAttn 的内核MaxSigmoidAttnBlock 把guide文本特征经nn.Linear(gc, ec)投影与图像嵌入embed做einsum点积后取max维经缩放、可学习 bias 与sigmoid生成nh组空间权重图再乘到proj_conv(x)上。这是「用文本引导图像特征」的空间注意力。6.2 PSA 家族位置敏感注意力AttentionPSA 原论文的卷积化多头自注意力。1x1qkv卷积同时产出 q/k/v其中key_dim head_dim * attn_ratio默认 0.5K/V 维度压缩降低显存输出加 3x3 深度可分离的位置编码pe。类变量format在coreml时改用F.scaled_dot_product_attention体现对不同推理后端的适配。PSABlockAttention 两层 1x1 FFNc→2c→c 双重残差。PSACSP 包装的 PSA——cv1拆两半一半过attn ffn拼接后cv2输出头数取max(c // 64, 1)。C2PSAPSA 的可堆叠重构内部为n个PSABlockyolo26.yaml 的 backbone 末端即用它替代传统 C3 收束深层特征。6.3 AAttn / ABlock / A2C2fYOLO12 的区域注意力AAttnArea-Attention。与 PSA 的 Attention 相比q/k/v 全维度为all_head_dim无 ratio 压缩7x7 深度可分离位置编码且area1时把特征图按区域切分分别做注意力以降低复杂度__setstate__还兼容了旧检查点缺失all_head_dim属性的情况。ABlockAAttn MLP1x1 卷积两层mlp_ratio默认 1.2 双残差权重用截断正态初始化std0.02。A2C2fC2f 的「级联全拼接」结构注意与 C2f 的 chunk 拆两半不同这里是 1 份初始 n 份级联共(1n)*c_进cv2每个单元默认是 2 个ABlock(c_, c_//32)a2False时退回C3k。residualTrue时引入初始值 0.01 的可学习gamma对输出做通道级缩放残差。parse_model在 scale 为l/x时会自动为其追加参数tasks.py#L2092-L2095。yolo12 全系detect/seg/pose/obb/cls见 12/ 目录的骨干均大量使用它。6.4 视觉-语言桥接ImagePoolingAttnYOLO-World 的图像池化注意力。把多级特征图各自 1x1 投影 AdaptiveMaxPool2d(k,k)池化为 patch 序列作为 Key/Value文本嵌入作为 Query标准多头 softmax 注意力后加残差写回文本特征。SAVPESpatial-Aware Visual Prompt Embedding面向 SAM 类视觉提示的多尺度特征聚合模块输出按 prompt 查询数Q聚合、L2 归一化的嵌入。七、可重参数化RepLearner与 ELAN 家族这组模块的共同思想训练时用多分支结构提升表达能力部署时把分支折叠为单卷积推理零额外开销。模块位置说明RepVGGDW7x7 深度卷积 3x3 深度卷积双支路fuse()方法torch.no_grad把conv1权重零填充到 7x7 后并入conv并删除conv1融合后切换为forward_fuseCIB5 层轻量序列3x3 深度卷积 → 1x1 扩通道 → 深度卷积lkTrue时换RepVGGDW→ 1x1 压回 → 3x3 深度卷积支持残差C2fCIB继承C2f内部换为n个CIBRepBottleneck继承Bottleneckcv1换为RepConvRepC3C3 骨架 n个RepConv串联c_ c2时cv3退化为nn.IdentityRepCSPC3 骨架 RepBottleneck序列RepNCSPELAN4CSP-ELANcv1拆两半后分别过两个RepCSP 3x3 Conv支路拼接后 1x1 输出forward_split同样提供 split 版ELAN1RepNCSPELAN4的 4 卷积轻量版支路直接是 3x3 卷积RepNCSPELAN4/SPPELAN/ADown是 v9 系列v9/ 目录单文件可达 14–21 处引用构建骨干的核心C2fCIB/RepVGGDW则服务于 v10 的轻量分支。八、下采样与特征融合块AConv先 2x2avg_pool2d再 3x3 卷积下采样v10 系列如 yolov10n.yaml用于替代 stride-2 卷积下采样。ADownavg-pool 后把通道拆两半一半走 stride-2 卷积一半走 3x3 最大池化 1x1 卷积双路 concat兼顾平滑与锐利边缘。SCDown1x1 点卷积 大核深度可分离卷积k, s参数化的简洁下采样单元。CBLinear单个nn.Conv2d输出sum(c2s)通道后按c2s列表split成多路一次卷积替代多个 1x1 分支节省推理开销。CBFuse对一组多尺度特征按索引取通道F.interpolate(nearest)统一到最后一级的尺寸后逐元素求和实现轻量 FPN 融合。TorchVision把任意 torchvision 官方模型「拆壳」装进 YAML——优先torchvision.models.get_model(model, weights...)加载unwrapTrue时剥掉末尾truncate默认 2层分类头兼容 EfficientNet/Swin 这类二级nn.Sequential结构splitTrue时逐子模块记录中间特征列表。torchvision采用函数内延迟导入不拖慢import ultralytics。九、HGNetV2 骨干块HGStemPPHGNetV2 的 stem——5 个卷积 MaxPool2d(2, stride1, ceil_modeTrue)F.pad([0,1,0,1])制造错位后双路 concat。HGBlockn个Conv或lightconvTrue时LightConv级联所有中间输出 输入一起 concat 后经两个 1x1 卷积squeeze/excitation压缩可选残差。parse_model为二者设置了专门的通道参数分支c1, cm, c2 ch[f], args[0], args[1]并把n插入HGBlock的第 5 位tasks.py#L2100-L2105。十、开放词汇与分类损失配套模块ContrastiveHeadCLIP 式对比头。图像特征x与文本特征w双 L2 归一化后einsum(bchw,bkc-bkhw)计算区域-文本相似度乘以logit_scale.exp()并加可学习bias初始 -10.0与分类损失初始值对齐。BNContrastiveHead用BatchNorm2d替代图像侧 L2 归一化的变体logit_scale初始化为log(e^-1)更稳定推理阶段可调用fuse()删除 norm/bias/logit_scale 并把前向替换为恒等映射forward_fuse因为该头只参与训练期的文本匹配。Residual把任意带w3属性的模块包成x m(x)并把w3.weight/w3.bias零初始化保证训练初期该分支无扰动注释中给出含 l-scale 模型应改用1e-6常量初始化的建议。SwiGLUFFNLLM 常用的 SwiGLU 前馈层w12投影到e*ec后拆两半silu(x1) * x2门控再经w3压缩供文本编码器等 Transformer 组件使用。十一、分割掩码 Proto 与 YOLO26 的 Proto26Proto实例分割的掩码原型生成器。cv1(3x3)→ConvTranspose2d(2x2 上采样)→cv2(3x3)→cv3(1x1 到 c232)输出 32 个原型掩码由 head 的掩码系数加权组合。Proto26继承Proto面向 YOLO26 分割。新增三块feat_refine把 P4/P5 用 1x1 卷积对齐到 P3 通道、feat_fuse3x3 融合、semseg训练期语义分割辅助头。前向中多级特征经F.interpolate(scale_factor2**(i1), nearest)逐级上采后相加注释说明常量缩放是为动态形状 CoreML 导出保留静态图训练时返回(proto, semantic)元组调用fuse()会置空semseg进入纯推理路径。十二、其他专用模块DFLGeneralized Focal Loss 配套的积分模块。固定权重为[0, 1, ..., c1-1]的 1x1 卷积requires_grad_(False)前向把(b, 4*c1, a)reshape 为(b, 4, c1, a)转置后 softmax 再卷积得到每个边界的期望值。注意 yolo26.yaml 中reg_max: 1即 YOLO26 不再使用多 bin DFL该模块保留给 v8/v11 等传统 head。RealNVPRealNVP 流式生成模型3 层交替 mask 的可逆仿射耦合层scale 网带 Tanh 限幅backward_p同时返回潜变量与雅可比对数行列式log_prob按 2D 标准正态闭式计算并在 fp32 下防 AMP 溢出loc/covbuffer 仅为兼容 8.4.126 之前的检查点而保留源码注释明确说明。它服务于姿态估计等需要可逆先验的场景。HGBlock 的 lightconvlightconvTrue时用LightConv替换Conv是 v2 骨干降算力的开关。十三、parse_model块如何被 YAML 实例化理解「积木」之后最后看「装配线」。tasks.py 中parse_model的核心机制L1997-L2095模块解析nn.前缀走torch.nntorchvision.ops.前缀走 torchvision其余用globals()[m]在nn.tasks命名空间查找——因此block.py的类必须被tasks.py导入文件头部即from .modules.block import ...受限加载模式下还会校验模块是否在白名单内L2062-L2064。基础模块识别base_modules集合含SPPF、C2f、C3k2、A2C2f、ADown、TorchVision等 33 类按c1, c2 ch[f], args[0]规则注入通道并把c2按width缩放、max_channels封顶、8 对齐Classify例外。重复次数注入repeat_modules集合中的块把 YAML 第二列n经max(round(n * depth), 1)深度缩放插入参数第 3 位随后n1——这就是 YAML 里[-1, 2, C2f, ...]的2的归宿。规模特化C3k2在 m/l/x 规模自动补c3kTrueA2C2f在 l/x 规模自动追加参数C2fAttn则做「隐层通道必须被头数整除」的整除性校验不满足直接抛ValueError并提示调整width_multiple、nh或扩展比。十四、全模块速查表下表覆盖 block.py 参考文档 列出的全部模块均可在 block.py 中找到实现模块角色关键参数典型应用DFL积分 DFL 定位解码c116v8/v11 检测头Proto/Proto26掩码原型生成c_256, c232实例分割YOLO26 多尺度语义辅助头HGStem/HGBlockHGNetV2 stem/块cm, k, n, lightconv大规模骨干SPP/SPPF/SPPELAN空间金字塔池化k(5,9,13)/k5,n3骨干深层C1/C2/C2f1/2 卷积 CSPn, e0.5, g全系列骨干C3/C3x/C3f/C3k/C3k23 卷积 CSP 及变体n, k, c3k, attnv5→v26 骨干主线C3TR/C3GhostTransformer / Ghost 版 C3n, ertdetr 系 / ghost 系RepC3/RepBottleneck/RepCSP可重参数化 CSPn, e部署友好骨干RepNCSPELAN4/ELAN1CSP-ELANc3, c4, nv9 系列RepVGGDW/CIB/C2fCIB轻量深度卷积单元lkv10 轻量分支Bottleneck/BottleneckCSP标准瓶颈k(3,3), g, e全部 CSP 的内核GhostBottleneckGhost 瓶颈k, sghost 模型ResNetBlock/ResNetLayerResNet 块/层s, e4, is_first分类 ResNet 骨干MaxSigmoidAttnBlock文本引导空间注意力nh, ec, gcYOLO-WorldC2fAttn带文本引导注意力的 C2fec, nh, gcv8-worldImagePoolingAttn图像池化文本增强ec, ch, nh, kv8-worldContrastiveHead/BNContrastiveHead区域-文本对比头embed_dims开放词汇模型Attention/PSABlock/PSA/C2PSA/C2fPSAPSA 位置敏感注意力attn_ratio, num_headsv12 系 / YOLO26 深层AAttn/ABlock/A2C2fArea-注意力及 C2f 集成area, mlp_ratio, residualyolo12 全系SCDown分离卷积下采样k, s深度骨干下采样AConv/ADownavg-pool 下采样—v10 / v9 系CBLinear/CBFuse分支线性 / 多尺度融合c2s,idx高效 FPNTorchVision官方模型拆壳封装model, weights, truncate, split分类预训练骨干SwiGLUFFN/Residual门控 FFN / 零初始化残差e, gc, ec文本编码器组件SAVPE视觉提示空间聚合ch, c3, embedSAM 提示模块RealNVP可逆流先验—姿态可逆先验十五、上手与验证以上模块均可按标准 PyTorch 用法直接实例化验证参数语义与源码 docstring 一致import torch from ultralytics.nn.modules.block import C2f, C3k2, SPPF x torch.randn(1, 64, 32, 32) print(C2f(64, 128, n2)(x).shape) # torch.Size([1, 128, 32, 32]) print(C3k2(128, 128, n1, c3kTrue)(x).shape) print(SPPF(128, 256, k5, n3)(x).shape) # torch.Size([1, 256, 32, 32])更完整的端到端验证由仓库测试承担tests/test_python.py 会对全量模型 YAML涵盖本文所有系列的块组合执行构建与前向tests/test_engine.py 则覆盖训练/验证引擎对同一批模型的行为。若要查看某个块被哪些模型使用可直接在 ultralytics/cfg/models 下按系列目录检索块名例如grep -r C3k2 ultralytics/cfg/models/。小结ultralytics/nn/modules/block.py 是 Ultralytics 模型体系的「零件车间」Bottleneck及其 CSP 包装C2f/C3/C3k2…构成主干表达力SPP/SPPF 提供多尺度感受野PSA/A2 注意力族与可重参数化族分别服务大规模模型与部署效率ContrastiveHead/C2fAttn/SAVPE等则把网络接入开放词汇与视觉提示场景。掌握第二节的参数约定与第十三节的parse_model装配规则后你就能把任意 YAML 逐行翻译为等价的 PyTorch 结构也能反过来用这些积木设计自己的骨干与 neck。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Ultralytics block.py 块模块库深度解析：支撑 YOLO26 / YOLO11 骨干的 CSP、注意力与 RepLearner 积木
Ultralytics block.py 块模块库深度解析支撑 YOLO26 / YOLO11 骨干的 CSP、注意力与 RepLearner 积木【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics本文围绕 block.py 参考文档 所对应的核心源码 ultralytics/nn/modules/block.py系统讲解 Ultralytics 中全部 50 余个神经网络块block模块的设计意图、参数约定与前向逻辑并结合 tasks.py 的parse_model解析流程与 yolo26.yaml 等真实模型配置说明这些积木如何被组合成 YOLO26、YOLO11、YOLOv9/v10/v12 等完整网络。读完本文你将能够读懂任意 Ultralytics 模型 YAML 中出现的块名理解c1/c2/n/e/shortcut等参数约定的来龙去脉并具备在自定义模型中选用合适 block 的能力。一、block.py 在架构中的位置Ultralytics 的模型构建遵循「YAML 描述结构、源码提供积木」的两层设计积木层ultralytics/nn/modules/block.py约 2000 行集中定义了 CSP 系列、空间金字塔池化、注意力、可重参数化、视觉-语言专用等全部基础块同目录下的 conv.py 提供Conv、DWConv、GhostConv、RepConv、LightConv、autopad等底层卷积原语block 层在其上组装。组装层ultralytics/nn/tasks.py 中的parse_model按行读取 YAML 的[from, repeats, module, args]用globals()[m]把模块名解析为 Python 类实例见 tasks.py 模块解析并按width/depth/max_channels自动缩放通道数与重复次数。配置层ultralytics/cfg/models 目录下按系列26/、11/、12/、v9/、v10/等存放各模型 YAML每行即一次块调用。block.py顶部的__all__block.py#L17-L57声明了 31 个对外导出的核心符号其余类如TorchVision、ResNetLayer、HGStem、HGBlock、Proto26等则供特定模型按需引用。二、通用参数约定读懂一切块的前提几乎所有块都遵循同一套参数命名掌握后即可脱离源码读懂任意 YAML 行参数含义典型默认值c1输入通道数由parse_model根据from自动注入—c2输出通道数按make_divisible(min(c2, max_channels) * width, 8)缩放见 tasks.py#L2070-L2073—n重复次数属于repeat_modules的块会被插入为第 3 个位置参数tasks.py#L2035-L20871e隐层通道扩展比隐层宽度 int(c2 * e)0.5shortcut是否允许残差直连实际生效还需c1 c2True/False视块而定g分组卷积的组数1k卷积核大小Conv内会经autopad自动补齐 padding3例如 yolo26.yaml 中的一行- [-1, 2, C3k2, [512, True]]表示取上一层输出重复 2 次输出通道 512c3kTruec1和重复数n都由解析器自动补全。三、基础瓶颈块Bottleneck 家族3.1 Bottleneck 标准瓶颈Bottleneck 是全部 CSP 块的最内层单元两层卷积Conv(c1→c2*e, k[0])Conv(c2*e→c2, k[1], gg)当shortcut and c1 c2时执行x f(x)残差相加否则直接输出。它本身不做通道拆分纯粹是被上层块堆叠的「砖」。3.2 BottleneckCSPBottleneckCSP 是经典 CSP 思想Cross Stage Partial Networks的实现输入先经cv1送入n个Bottleneck序列再与cv2(x)的旁路分支在通道维拼接经BatchNorm2d SiLU后由cv4压缩为c2通道。它是 v5 时代骨干的主力块。3.3 GhostBottleneckGhostBottleneck 用廉价卷积生成「ghost 特征」GhostConv(1x1)→ 可选DWConv仅s2时降采样→GhostConv(1x1, 无激活)主支与 shortcut 支相加。它是 C3Ghost 的内核用于 v8-ghost 等轻量变体如 yolov8-ghost.yaml。3.4 ResNetBlock / ResNetLayerResNetBlock 是标准的 ResNet 残差块1x1 → 3x3 → 1x1扩比e4通道不匹配或步长不为 1 时自动生成 1x1 投影 shortcut末尾ReLUResNetLayer 则把若干块串成层首个层自动加 7x7 卷积 3x3 最大池化的「stem」。parse_model对ResNetLayer有专门的通道推断分支tasks.py#L2106-L2107它们共同支撑 yolo11-cls-resnet18.yaml 这类分类骨干。四、CSP 系列YOLO 骨干的绝对主力4.1 C1 与 C2C11 卷积 CSP。cv1(x)后经n个 3x3Conv输出self.m(y) y。结构最简多用于小模型。C22 卷积 CSP。cv1把通道扩到2*c后chunk(2)拆成两半一半流经n个Bottleneck隐层e1.0另一半直通拼接后由cv2压回c2。4.2 C2fv8 时代的核心块C2f 是 C2 的「更快实现」也是 YOLOv8/v11 的主力def forward(self, x): y list(self.cv1(x).chunk(2, 1)) # cv1 输出 2*c 通道拆两半 y.extend(m(y[-1]) for m in self.m) # 逐块堆叠每块吃上一块输出 return self.cv2(torch.cat(y, 1)) # 所有分支(2n)份拼接后 1x1 压缩关键差异在于「级联式堆叠 全分支拼接」n个Bottleneck依次接力最终把2n份特征全部拼进cv2梯度路径更多、算力利用更充分。它还提供forward_split用显式split替代chunk供推理后端优化。在parse_model中C2f同属repeat_modulesYAML 第二列的重复数会被注入为ntasks.py#L2035-L2053。4.3 C3 家族v5 主力的各种变体C3 是 3 卷积 CSPcv1/cv2两个 1x1 分支一个流经n个Bottleneck(k((1,1),(3,3)))拼接后cv3输出。其子类仅替换内部self.m子类位置内部 m 替换为特点C3x同上Bottleneck(k((1,3),(3,1)))交叉方向卷积核增强跨行/列感受野C3TR同上TransformerBlock(c_, c_, 4, n)卷积Transformer 混合用于 rtdetr 类模型C3Ghost同上GhostBottleneck序列轻量 ghost 卷积C3f独立类C2f 式级联拼接3 卷积版 C2fcv2输入改为(2n)*c_C3k同上Bottleneck(k(k,k))核大小k可配置默认 34.4 C3k2YOLO26 的主干块C3k2 继承自C2f把内部模块按三个开关替换attnTrue每个单元为Bottleneck PSABlock(attn_ratio0.5, num_headsmax(c//64, 1))的级联引入位置敏感注意力c3kTrue每个单元为C3k(c, c, 2)即内含 2 个 Bottleneck 的 C3 子块否则退化为普通Bottleneck。parse_model对它有一个规模敏感的默认值注入当 scale 为m/l/x且 YAML 未显式给出c3k参数时自动补Truetasks.py#L2088-L2091。yolo26.yaml 的 backbone 完全由C3k2ConvSPPFC2PSA构成例如backbone: - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2 - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4 - [-1, 2, C3k2, [256, False, 0.25]] ... - [-1, 1, SPPF, [1024, 5, 3, True]] # 9 - [-1, 2, C2PSA, [1024]] # 10可见同一份 YAML 通过scalesdepth/width/max_channels 三元组即可派生 n/s/m/l/x 五个尺寸而块级差异正是由C3k2的参数注入规则实现的。4.5 带注意力的 C2f 变体C2fAttn在 C2f 的拼接列表中额外追加一路MaxSigmoidAttnBlock输出通道数变为(3n)*c前向需要第二个输入guide文本嵌入是 v8-world 等开放词汇检测模型的关键组件parse_model对其nh头数与隐层通道有专门整除校验tasks.py#L2074-L2082。C2fPSA继承C2f将内部Bottleneck全部替换为PSABlock要求c1 c2。五、空间金字塔池化SPP / SPPF / SPPELANSPP经典空间金字塔池化。cv1压缩到c1//2后对k(5,9,13)三组MaxPool2d(stride1, paddingk//2)输出与自身拼接再由cv2还原。SPPFFast 版。用同一个MaxPool2d(k5)串联n3次再拼接等价于SPP(k(5,9,13))源码 Notes 中明确说明但参数与算力大幅减少shortcutTrue且c1c2时输出y x。它是历代 YOLO 骨干倒数第二层的标配yolo26.yaml 中写作- [-1, 1, SPPF, [1024, 5, 3, True]]。SPPELANSPP 的 ELAN 风格实现三个大核最大池化级联后与初始分支拼接4 份用于 v9 系列如 yolov9e.yaml。六、注意力模块族6.1 MaxSigmoidAttnBlock 与 C2fAttn 的内核MaxSigmoidAttnBlock 把guide文本特征经nn.Linear(gc, ec)投影与图像嵌入embed做einsum点积后取max维经缩放、可学习 bias 与sigmoid生成nh组空间权重图再乘到proj_conv(x)上。这是「用文本引导图像特征」的空间注意力。6.2 PSA 家族位置敏感注意力AttentionPSA 原论文的卷积化多头自注意力。1x1qkv卷积同时产出 q/k/v其中key_dim head_dim * attn_ratio默认 0.5K/V 维度压缩降低显存输出加 3x3 深度可分离的位置编码pe。类变量format在coreml时改用F.scaled_dot_product_attention体现对不同推理后端的适配。PSABlockAttention 两层 1x1 FFNc→2c→c 双重残差。PSACSP 包装的 PSA——cv1拆两半一半过attn ffn拼接后cv2输出头数取max(c // 64, 1)。C2PSAPSA 的可堆叠重构内部为n个PSABlockyolo26.yaml 的 backbone 末端即用它替代传统 C3 收束深层特征。6.3 AAttn / ABlock / A2C2fYOLO12 的区域注意力AAttnArea-Attention。与 PSA 的 Attention 相比q/k/v 全维度为all_head_dim无 ratio 压缩7x7 深度可分离位置编码且area1时把特征图按区域切分分别做注意力以降低复杂度__setstate__还兼容了旧检查点缺失all_head_dim属性的情况。ABlockAAttn MLP1x1 卷积两层mlp_ratio默认 1.2 双残差权重用截断正态初始化std0.02。A2C2fC2f 的「级联全拼接」结构注意与 C2f 的 chunk 拆两半不同这里是 1 份初始 n 份级联共(1n)*c_进cv2每个单元默认是 2 个ABlock(c_, c_//32)a2False时退回C3k。residualTrue时引入初始值 0.01 的可学习gamma对输出做通道级缩放残差。parse_model在 scale 为l/x时会自动为其追加参数tasks.py#L2092-L2095。yolo12 全系detect/seg/pose/obb/cls见 12/ 目录的骨干均大量使用它。6.4 视觉-语言桥接ImagePoolingAttnYOLO-World 的图像池化注意力。把多级特征图各自 1x1 投影 AdaptiveMaxPool2d(k,k)池化为 patch 序列作为 Key/Value文本嵌入作为 Query标准多头 softmax 注意力后加残差写回文本特征。SAVPESpatial-Aware Visual Prompt Embedding面向 SAM 类视觉提示的多尺度特征聚合模块输出按 prompt 查询数Q聚合、L2 归一化的嵌入。七、可重参数化RepLearner与 ELAN 家族这组模块的共同思想训练时用多分支结构提升表达能力部署时把分支折叠为单卷积推理零额外开销。模块位置说明RepVGGDW7x7 深度卷积 3x3 深度卷积双支路fuse()方法torch.no_grad把conv1权重零填充到 7x7 后并入conv并删除conv1融合后切换为forward_fuseCIB5 层轻量序列3x3 深度卷积 → 1x1 扩通道 → 深度卷积lkTrue时换RepVGGDW→ 1x1 压回 → 3x3 深度卷积支持残差C2fCIB继承C2f内部换为n个CIBRepBottleneck继承Bottleneckcv1换为RepConvRepC3C3 骨架 n个RepConv串联c_ c2时cv3退化为nn.IdentityRepCSPC3 骨架 RepBottleneck序列RepNCSPELAN4CSP-ELANcv1拆两半后分别过两个RepCSP 3x3 Conv支路拼接后 1x1 输出forward_split同样提供 split 版ELAN1RepNCSPELAN4的 4 卷积轻量版支路直接是 3x3 卷积RepNCSPELAN4/SPPELAN/ADown是 v9 系列v9/ 目录单文件可达 14–21 处引用构建骨干的核心C2fCIB/RepVGGDW则服务于 v10 的轻量分支。八、下采样与特征融合块AConv先 2x2avg_pool2d再 3x3 卷积下采样v10 系列如 yolov10n.yaml用于替代 stride-2 卷积下采样。ADownavg-pool 后把通道拆两半一半走 stride-2 卷积一半走 3x3 最大池化 1x1 卷积双路 concat兼顾平滑与锐利边缘。SCDown1x1 点卷积 大核深度可分离卷积k, s参数化的简洁下采样单元。CBLinear单个nn.Conv2d输出sum(c2s)通道后按c2s列表split成多路一次卷积替代多个 1x1 分支节省推理开销。CBFuse对一组多尺度特征按索引取通道F.interpolate(nearest)统一到最后一级的尺寸后逐元素求和实现轻量 FPN 融合。TorchVision把任意 torchvision 官方模型「拆壳」装进 YAML——优先torchvision.models.get_model(model, weights...)加载unwrapTrue时剥掉末尾truncate默认 2层分类头兼容 EfficientNet/Swin 这类二级nn.Sequential结构splitTrue时逐子模块记录中间特征列表。torchvision采用函数内延迟导入不拖慢import ultralytics。九、HGNetV2 骨干块HGStemPPHGNetV2 的 stem——5 个卷积 MaxPool2d(2, stride1, ceil_modeTrue)F.pad([0,1,0,1])制造错位后双路 concat。HGBlockn个Conv或lightconvTrue时LightConv级联所有中间输出 输入一起 concat 后经两个 1x1 卷积squeeze/excitation压缩可选残差。parse_model为二者设置了专门的通道参数分支c1, cm, c2 ch[f], args[0], args[1]并把n插入HGBlock的第 5 位tasks.py#L2100-L2105。十、开放词汇与分类损失配套模块ContrastiveHeadCLIP 式对比头。图像特征x与文本特征w双 L2 归一化后einsum(bchw,bkc-bkhw)计算区域-文本相似度乘以logit_scale.exp()并加可学习bias初始 -10.0与分类损失初始值对齐。BNContrastiveHead用BatchNorm2d替代图像侧 L2 归一化的变体logit_scale初始化为log(e^-1)更稳定推理阶段可调用fuse()删除 norm/bias/logit_scale 并把前向替换为恒等映射forward_fuse因为该头只参与训练期的文本匹配。Residual把任意带w3属性的模块包成x m(x)并把w3.weight/w3.bias零初始化保证训练初期该分支无扰动注释中给出含 l-scale 模型应改用1e-6常量初始化的建议。SwiGLUFFNLLM 常用的 SwiGLU 前馈层w12投影到e*ec后拆两半silu(x1) * x2门控再经w3压缩供文本编码器等 Transformer 组件使用。十一、分割掩码 Proto 与 YOLO26 的 Proto26Proto实例分割的掩码原型生成器。cv1(3x3)→ConvTranspose2d(2x2 上采样)→cv2(3x3)→cv3(1x1 到 c232)输出 32 个原型掩码由 head 的掩码系数加权组合。Proto26继承Proto面向 YOLO26 分割。新增三块feat_refine把 P4/P5 用 1x1 卷积对齐到 P3 通道、feat_fuse3x3 融合、semseg训练期语义分割辅助头。前向中多级特征经F.interpolate(scale_factor2**(i1), nearest)逐级上采后相加注释说明常量缩放是为动态形状 CoreML 导出保留静态图训练时返回(proto, semantic)元组调用fuse()会置空semseg进入纯推理路径。十二、其他专用模块DFLGeneralized Focal Loss 配套的积分模块。固定权重为[0, 1, ..., c1-1]的 1x1 卷积requires_grad_(False)前向把(b, 4*c1, a)reshape 为(b, 4, c1, a)转置后 softmax 再卷积得到每个边界的期望值。注意 yolo26.yaml 中reg_max: 1即 YOLO26 不再使用多 bin DFL该模块保留给 v8/v11 等传统 head。RealNVPRealNVP 流式生成模型3 层交替 mask 的可逆仿射耦合层scale 网带 Tanh 限幅backward_p同时返回潜变量与雅可比对数行列式log_prob按 2D 标准正态闭式计算并在 fp32 下防 AMP 溢出loc/covbuffer 仅为兼容 8.4.126 之前的检查点而保留源码注释明确说明。它服务于姿态估计等需要可逆先验的场景。HGBlock 的 lightconvlightconvTrue时用LightConv替换Conv是 v2 骨干降算力的开关。十三、parse_model块如何被 YAML 实例化理解「积木」之后最后看「装配线」。tasks.py 中parse_model的核心机制L1997-L2095模块解析nn.前缀走torch.nntorchvision.ops.前缀走 torchvision其余用globals()[m]在nn.tasks命名空间查找——因此block.py的类必须被tasks.py导入文件头部即from .modules.block import ...受限加载模式下还会校验模块是否在白名单内L2062-L2064。基础模块识别base_modules集合含SPPF、C2f、C3k2、A2C2f、ADown、TorchVision等 33 类按c1, c2 ch[f], args[0]规则注入通道并把c2按width缩放、max_channels封顶、8 对齐Classify例外。重复次数注入repeat_modules集合中的块把 YAML 第二列n经max(round(n * depth), 1)深度缩放插入参数第 3 位随后n1——这就是 YAML 里[-1, 2, C2f, ...]的2的归宿。规模特化C3k2在 m/l/x 规模自动补c3kTrueA2C2f在 l/x 规模自动追加参数C2fAttn则做「隐层通道必须被头数整除」的整除性校验不满足直接抛ValueError并提示调整width_multiple、nh或扩展比。十四、全模块速查表下表覆盖 block.py 参考文档 列出的全部模块均可在 block.py 中找到实现模块角色关键参数典型应用DFL积分 DFL 定位解码c116v8/v11 检测头Proto/Proto26掩码原型生成c_256, c232实例分割YOLO26 多尺度语义辅助头HGStem/HGBlockHGNetV2 stem/块cm, k, n, lightconv大规模骨干SPP/SPPF/SPPELAN空间金字塔池化k(5,9,13)/k5,n3骨干深层C1/C2/C2f1/2 卷积 CSPn, e0.5, g全系列骨干C3/C3x/C3f/C3k/C3k23 卷积 CSP 及变体n, k, c3k, attnv5→v26 骨干主线C3TR/C3GhostTransformer / Ghost 版 C3n, ertdetr 系 / ghost 系RepC3/RepBottleneck/RepCSP可重参数化 CSPn, e部署友好骨干RepNCSPELAN4/ELAN1CSP-ELANc3, c4, nv9 系列RepVGGDW/CIB/C2fCIB轻量深度卷积单元lkv10 轻量分支Bottleneck/BottleneckCSP标准瓶颈k(3,3), g, e全部 CSP 的内核GhostBottleneckGhost 瓶颈k, sghost 模型ResNetBlock/ResNetLayerResNet 块/层s, e4, is_first分类 ResNet 骨干MaxSigmoidAttnBlock文本引导空间注意力nh, ec, gcYOLO-WorldC2fAttn带文本引导注意力的 C2fec, nh, gcv8-worldImagePoolingAttn图像池化文本增强ec, ch, nh, kv8-worldContrastiveHead/BNContrastiveHead区域-文本对比头embed_dims开放词汇模型Attention/PSABlock/PSA/C2PSA/C2fPSAPSA 位置敏感注意力attn_ratio, num_headsv12 系 / YOLO26 深层AAttn/ABlock/A2C2fArea-注意力及 C2f 集成area, mlp_ratio, residualyolo12 全系SCDown分离卷积下采样k, s深度骨干下采样AConv/ADownavg-pool 下采样—v10 / v9 系CBLinear/CBFuse分支线性 / 多尺度融合c2s,idx高效 FPNTorchVision官方模型拆壳封装model, weights, truncate, split分类预训练骨干SwiGLUFFN/Residual门控 FFN / 零初始化残差e, gc, ec文本编码器组件SAVPE视觉提示空间聚合ch, c3, embedSAM 提示模块RealNVP可逆流先验—姿态可逆先验十五、上手与验证以上模块均可按标准 PyTorch 用法直接实例化验证参数语义与源码 docstring 一致import torch from ultralytics.nn.modules.block import C2f, C3k2, SPPF x torch.randn(1, 64, 32, 32) print(C2f(64, 128, n2)(x).shape) # torch.Size([1, 128, 32, 32]) print(C3k2(128, 128, n1, c3kTrue)(x).shape) print(SPPF(128, 256, k5, n3)(x).shape) # torch.Size([1, 256, 32, 32])更完整的端到端验证由仓库测试承担tests/test_python.py 会对全量模型 YAML涵盖本文所有系列的块组合执行构建与前向tests/test_engine.py 则覆盖训练/验证引擎对同一批模型的行为。若要查看某个块被哪些模型使用可直接在 ultralytics/cfg/models 下按系列目录检索块名例如grep -r C3k2 ultralytics/cfg/models/。小结ultralytics/nn/modules/block.py 是 Ultralytics 模型体系的「零件车间」Bottleneck及其 CSP 包装C2f/C3/C3k2…构成主干表达力SPP/SPPF 提供多尺度感受野PSA/A2 注意力族与可重参数化族分别服务大规模模型与部署效率ContrastiveHead/C2fAttn/SAVPE等则把网络接入开放词汇与视觉提示场景。掌握第二节的参数约定与第十三节的parse_model装配规则后你就能把任意 YAML 逐行翻译为等价的 PyTorch 结构也能反过来用这些积木设计自己的骨干与 neck。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
