模型 YAML 配置指南

模型 YAML 配置文件是 Ultralytics 神经网络的架构蓝图。它定义了层与层之间的连接方式、每个模块使用的参数，以及整个网络如何在不同模型尺寸下进行缩放。

配置结构

模型 YAML 文件分为三个主要部分，共同协作以定义架构。

参数部分

参数 (parameters) 部分指定了模型的全局特性和缩放行为：

# Parameters
nc: 80 # number of classes
scales: # compound scaling constants [depth, width, max_channels]
    n: [0.50, 0.25, 1024] # nano: shallow layers, narrow channels
    s: [0.50, 0.50, 1024] # small: shallow depth, standard width
    m: [0.50, 1.00, 512] # medium: moderate depth, full width
    l: [1.00, 1.00, 512] # large: full depth and width
    x: [1.00, 1.50, 512] # extra-large: maximum performance
kpt_shape: [17, 3] # pose models only

• nc 用于设置模型预测的类别数量。
• scales 定义了复合缩放因子，用于调整模型深度、宽度和最大通道数，以生成不同尺寸的变体（从 nano 到 extra-large）。
• kpt_shape 适用于姿态模型。它可以是 [N, 2]（表示 (x, y) 关键点）或 [N, 3]（表示 (x, y, visibility)）。

骨干网络与检测头架构

模型架构由骨干网络（特征提取）和检测头（特定任务）部分组成：

backbone:
    # [from, repeats, module, args]
    - [-1, 1, Conv, [64, 3, 2]] # 0: Initial convolution
    - [-1, 1, Conv, [128, 3, 2]] # 1: Downsample
    - [-1, 3, C2f, [128, True]] # 2: Feature processing

head:
    - [-1, 1, nn.Upsample, [None, 2, nearest]] # 6: Upsample
    - [[-1, 2], 1, Concat, [1]] # 7: Skip connection
    - [-1, 3, C2f, [256]] # 8: Process features
    - [[8], 1, Detect, [nc]] # 9: Detection layer

层规范格式

每一层都遵循一致的模式：[from, repeats, module, args]

连接模式

from 字段可在整个网络中创建灵活的数据流模式：

- [-1, 1, Conv, [64, 3, 2]]    # Takes input from previous layer

模块重复

repeats 参数用于创建更深的网络部分：

- [-1, 3, C2f, [128, True]] # Creates 3 consecutive C2f blocks
- [-1, 1, Conv, [64, 3, 2]] # Single convolution layer

实际重复次数会乘以模型尺寸配置中的深度缩放因子。

可用模块

模块按功能组织，并在 Ultralytics 模块目录 中定义。下表展示了按类别划分的常用模块，源代码中还有更多可用模块：

基础操作

组合模块

专用模块

高级功能

TorchVision 集成

TorchVision 模块可以无缝集成任何 TorchVision 模型 作为骨干网络：

from ultralytics import YOLO

# Model with ConvNeXt backbone
model = YOLO("convnext_backbone.yaml")
results = model.train(data="coco8.yaml", epochs=100)

用于特征选择的 Index 模块

当使用输出多个特征图的模型时，Index 模块会选择特定的输出：

backbone:
    - [-1, 1, TorchVision, [768, convnext_tiny, DEFAULT, True, 2, True]] # Multi-output
head:
    - [0, 1, Index, [192, 4]] # Select 4th feature map (192 channels)
    - [0, 1, Index, [384, 6]] # Select 6th feature map (384 channels)
    - [0, 1, Index, [768, 8]] # Select 8th feature map (768 channels)
    - [[1, 2, 3], 1, Detect, [nc]] # Multi-scale detection

模块解析系统

了解 Ultralytics 如何定位和导入模块对于自定义配置至关重要：

模块查找流程

Ultralytics 在 parse_model 中使用三层系统：

# Core resolution logic
m = getattr(torch.nn, m[3:]) if "nn." in m else getattr(torchvision.ops, m[4:]) if "ops." in m else globals()[m]

1. PyTorch 模块：名称以 'nn.' 开头 → torch.nn 命名空间
2. TorchVision 操作：名称以 'ops.' 开头 → torchvision.ops 命名空间
3. Ultralytics 模块：所有其他名称 → 通过导入进入全局命名空间

模块导入链

标准模块可以通过 tasks.py 中的导入来使用：

from ultralytics.nn.modules import (  # noqa: F401
    SPPF,
    C2f,
    Conv,
    Detect,
    # ... many more modules
    Index,
    TorchVision,
)

自定义模块集成

修改源代码

修改源代码是集成自定义模块最灵活的方法，但可能比较复杂。要定义并使用自定义模块，请按照以下步骤操作：

1. 使用 快速入门指南 中的 Git 克隆方法以开发模式安装 Ultralytics。

2. 在 ultralytics/nn/modules/block.py 中定义你的模块：

   class CustomBlock(nn.Module):
       """Custom block with Conv-BatchNorm-ReLU sequence."""
   
       def __init__(self, c1, c2):
           """Initialize CustomBlock with input and output channels."""
           super().__init__()
           self.layers = nn.Sequential(nn.Conv2d(c1, c2, 3, 1, 1), nn.BatchNorm2d(c2), nn.ReLU())
   
       def forward(self, x):
           """Forward pass through the block."""
           return self.layers(x)

3. 在 ultralytics/nn/modules/__init__.py 中在包级别暴露你的模块：

   from .block import CustomBlock  # noqa makes CustomBlock available as ultralytics.nn.modules.CustomBlock

4. Add to imports in ultralytics/nn/tasks.py:

   from ultralytics.nn.modules import CustomBlock  # noqa

5. Handle special arguments (if needed) inside parse_model() in ultralytics/nn/tasks.py:

   # Add this condition in the parse_model() function
   if m is CustomBlock:
       c1, c2 = ch[f], args[0]  # input channels, output channels
       args = [c1, c2, *args[1:]]

6. 在你的模型 YAML 中使用该模块：

   # custom_model.yaml
   nc: 1
   backbone:
       - [-1, 1, CustomBlock, [64]]
   head:
       - [-1, 1, Classify, [nc]]

7. 检查 FLOPs 以确保前向传播正常工作：

   from ultralytics import YOLO
   
   model = YOLO("custom_model.yaml", task="classify")
   model.info()  # should print non-zero FLOPs if working

示例配置

基础检测模型

# Simple YOLO detection model
nc: 80
scales:
    n: [0.33, 0.25, 1024]

backbone:
    - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2
    - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4
    - [-1, 3, C2f, [128, True]] # 2
    - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8
    - [-1, 6, C2f, [256, True]] # 4
    - [-1, 1, SPPF, [256, 5]] # 5

head:
    - [-1, 1, Conv, [256, 3, 1]] # 6
    - [[6], 1, Detect, [nc]] # 7

TorchVision 主干网络模型

# ConvNeXt backbone with YOLO head
nc: 80

backbone:
    - [-1, 1, TorchVision, [768, convnext_tiny, DEFAULT, True, 2, True]]

head:
    - [0, 1, Index, [192, 4]] # P3 features
    - [0, 1, Index, [384, 6]] # P4 features
    - [0, 1, Index, [768, 8]] # P5 features
    - [[1, 2, 3], 1, Detect, [nc]] # Multi-scale detection

分类模型

# Simple classification model
nc: 1000

backbone:
    - [-1, 1, Conv, [64, 7, 2, 3]]
    - [-1, 1, nn.MaxPool2d, [3, 2, 1]]
    - [-1, 4, C2f, [64, True]]
    - [-1, 1, Conv, [128, 3, 2]]
    - [-1, 8, C2f, [128, True]]
    - [-1, 1, nn.AdaptiveAvgPool2d, [1]]

head:
    - [-1, 1, Classify, [nc]]

最佳实践

架构设计技巧

保持简单：在自定义之前，先从经过验证的架构开始。使用现有的 YOLO 配置作为模板，逐步进行修改，而不是从零开始构建。

增量测试：一步步验证每次修改。每次添加一个自定义模块，并确认其工作正常，然后再进行下一次更改。

监控通道：确保连接层之间的通道维度匹配。一层的输出通道 (c2) 必须与序列中下一层的输入通道 (c1) 相匹配。

使用跳跃连接：利用 [[-1, N], 1, Concat, [1]] 模式进行特征复用。这些连接有助于梯度流动，并允许模型组合来自不同尺度的特征。

适当缩放：根据你的计算约束选择模型规模。对于边缘设备使用 nano (n)，对于平衡性能使用 small (s)，对于最大准确度使用较大规模 (m, l, x)。

性能考量

深度与宽度：深度网络通过多个转换层捕捉复杂的层级特征，而宽度网络在每一层并行处理更多信息。根据任务复杂度平衡这两者。

跳跃连接：改善训练期间的梯度流动，并实现全网络的特征复用。在更深的架构中，它们对于防止梯度消失尤为重要。

瓶颈块 (Bottleneck Blocks)：在保持模型表达能力的同时降低计算成本。像 C2f 这样的模块使用的参数比标准卷积少，同时保持了特征学习能力。

多尺度特征：对于检测同一图像中不同大小的对象至关重要。使用具有不同尺度检测头的特征金字塔网络 (FPN) 模式。

故障排除

常见问题

调试技巧

在开发自定义架构时，系统化的调试有助于及早识别问题：

使用 Identity Head 进行测试

用 nn.Identity 替换复杂的 Head 以隔离主干网络问题：

nc: 1
backbone:
    - [-1, 1, CustomBlock, [64]]
head:
    - [-1, 1, nn.Identity, []] # Pass-through for debugging

这可以直接检查主干网络的输出：

import torch

from ultralytics import YOLO

model = YOLO("debug_model.yaml")
output = model.model(torch.randn(1, 3, 640, 640))
print(f"Output shape: {output.shape}")  # Should match expected dimensions

模型架构检查

检查 FLOPs 计数并打印出每一层也有助于调试自定义模型配置的问题。有效模型的 FLOPs 计数应为非零。如果为零，则前向传播很可能存在问题。运行一个简单的前向传播应该能显示遇到的确切错误。

from ultralytics import YOLO

# Build model with verbose output to see layer details
model = YOLO("debug_model.yaml", verbose=True)

# Check model FLOPs. Failed forward pass causes 0 FLOPs.
model.info()

# Inspect individual layers
for i, layer in enumerate(model.model.model):
    print(f"Layer {i}: {layer}")

逐步验证

1. 从最简开始：首先测试尽可能简单的架构
2. 增量添加：一层一层地增加复杂度
3. 检查维度：验证通道和空间大小的兼容性
4. 验证缩放：使用不同的模型规模 (n, s, m) 进行测试

常见问题 (FAQ)

如何更改模型中的类别数量？

在 YAML 文件顶部设置 nc 参数，以匹配你数据集的类别数量。

nc: 5 # 5 classes

我可以在模型 YAML 中使用自定义主干网络吗？

是的。你可以使用任何受支持的模块，包括 TorchVision 主干网络，或者定义你自己的自定义模块并按照 自定义模块集成 所述进行导入。

如何针对不同大小（nano, small, medium 等）缩放我的模型？

使用 YAML 中的 scales 部分 来定义深度、宽度和最大通道的缩放因子。当你加载文件名后附加了缩放比例的基础 YAML 文件时（例如 yolo26n.yaml），模型将自动应用这些缩放。

[from, repeats, module, args] 格式是什么意思？

此格式指定了每一层的构建方式：

• from：输入来源
• repeats：重复模块的次数
• module：层类型
• args：模块参数

如何排查通道不匹配错误？

检查一层的输出通道是否与下一层的预期输入通道匹配。使用 print(model.model.model) 来检查你的模型架构。

在哪里可以找到可用模块及其参数的列表？

查看 ultralytics/nn/modules 目录 中的源代码，获取所有可用模块及其参数。

如何将自定义模块添加到我的 YAML 配置中？

在源代码中定义你的模块，按照 修改源代码 中所示进行导入，并在你的 YAML 文件中按名称引用它。

我可以在自定义 YAML 中使用预训练权重吗？

是的，你可以使用 model.load("path/to/weights") 从预训练检查点加载权重。但是，只有匹配的层权重才会成功加载。

如何验证我的模型配置？

使用 model.info() 来检查 FLOPs 计数是否为非零。一个有效的模型应该显示非零的 FLOPs 计数。如果为零，请遵循 调试技巧 中的建议来查找问题。