Руководство по YAML-конфигурации модели

Файл конфигурации модели YAML служит архитектурным планом для нейронных сетей Ultralytics. Он определяет, как соединяются слои, какие параметры использует каждый модуль и как вся сеть масштабируется в зависимости от размера модели.

Структура конфигурации

YAML-файлы моделей организованы в три основных раздела, которые совместно определяют архитектуру.

Раздел параметров

В разделе параметры указаны глобальные характеристики модели и поведение при масштабировании:

# 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 определите составные коэффициенты масштабирования, которые регулируют глубину, ширину и максимальные каналы модели для создания различных вариантов размера (от нано до очень большого).
• kpt_shape применяется к моделям позы. Это может быть [N, 2] для (x, y) ключевые точки или [N, 3] для (x, y, visibility).

Архитектура Backbone и Head

Архитектура модели состоит из разделов backbone (извлечение признаков) и head (для конкретных задач):

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 field создает гибкие схемы потоков данных по всей вашей сети:

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

- [[-1, 6], 1, Concat, [1]]    # Combines current layer with layer 6

- [[4, 6, 8], 1, Detect, [nc]] # Detection head using 3 feature scales

Повторение модуля

Параметр repeats параметр создает более глубокие разделы сети:

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

Фактическое количество повторений умножается на коэффициент масштабирования глубины из конфигурации размера вашей модели.

Доступные модули

Модули организованы по функциональности и определены в директории модулей Ultralytics. В следующих таблицах показаны часто используемые модули по категориям, при этом в исходном коде доступно гораздо больше:

Основные операции

Композитные блоки

Специализированные модули

Расширенные возможности

Интеграция TorchVision

Модуль TorchVision обеспечивает простую интеграцию любой модели TorchVision в качестве backbone:

from ultralytics import YOLO

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

backbone:
  - [-1, 1, TorchVision, [768, convnext_tiny, DEFAULT, True, 2, False]]
head:
  - [-1, 1, Classify, [nc]]

Индексный модуль для выбора признаков

При использовании моделей, которые выводят несколько карт признаков, модуль 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. Установите Ultralytics в режиме разработки, используя метод клонирования Git из руководства по быстрому старту.

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. Добавить в импорты в ultralytics/nn/tasks.py:

   from ultralytics.nn.modules import CustomBlock  # noqa
   

5. Обработка специальных аргументов (при необходимости) внутри parse_model() в 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
   

Примеры конфигураций

Базовая модель detect

# 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) следующего слоя в последовательности.

Используйте Skip Connections: Используйте повторное использование функций с [[-1, N], 1, Concat, [1]] паттерны. Эти соединения помогают с распространением градиента и позволяют модели объединять признаки из разных масштабов.

Масштабируйте Соответствующим Образом: Выбирайте масштабы модели в зависимости от ваших вычислительных ограничений. Используйте nano (n) для периферийных устройств, small (s) для сбалансированной производительности и более крупные масштабы (m, l, x) для максимальной точности.

Рекомендации по производительности

Глубина против ширины: Глубокие сети захватывают сложные иерархические признаки посредством множественных слоев преобразования, в то время как широкие сети обрабатывают больше информации параллельно на каждом слое. Сбалансируйте их в зависимости от сложности вашей задачи.

Skip Connections: Улучшают прохождение градиента во время обучения и обеспечивают повторное использование признаков во всей сети. Они особенно важны в более глубоких архитектурах для предотвращения исчезновения градиентов.

Блоки узких мест: Снижение вычислительных затрат при сохранении выразительности модели. Такие модули, как C2f используйте меньше параметров, чем стандартные свертки, сохраняя при этом способность к изучению признаков.

Multi-Scale Features: Необходимы для detect объектов разных размеров на одном изображении. Используйте шаблоны Feature Pyramid Network (FPN) с несколькими головками detect на разных масштабах.

Устранение неполадок

Распространенные проблемы

Советы по отладке

При разработке пользовательских архитектур систематическая отладка помогает выявить проблемы на ранней стадии:

Используйте Identity Head для тестирования

Замените сложные заголовки на nn.Identity чтобы изолировать проблемы с магистральной сетью:

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

Это позволяет напрямую проверять выходные данные backbone:

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)

Часто задаваемые вопросы

Как изменить количество классов в моей модели?

Установите nc параметр в верхней части вашего YAML-файла, чтобы он соответствовал количеству классов в вашем наборе данных.

nc: 5 # 5 classes

Могу ли я использовать пользовательский backbone в моем YAML-файле модели?

Да. Вы можете использовать любой поддерживаемый модуль, включая бэкбоны TorchVision, или определить свой собственный модуль и импортировать его, как описано в Custom Module Integration.

Как масштабировать мою модель для различных размеров (nano, small, medium и т. д.)?

Используйте scales разделе в вашем YAML-файле, чтобы определить коэффициенты масштабирования для глубины, ширины и максимальных каналов. Модель автоматически применит их, когда вы загрузите базовый YAML-файл с добавленным к имени файла масштабом (например, yolo11n.yaml).

Что такое [from, repeats, module, args] формат среднего?

Этот формат определяет способ построения каждого слоя:

• from: входной(-ые) источник(-и)
• repeats: количество повторений модуля
• module: тип слоя
• args: аргументы для модуля

Как устранить ошибки несоответствия каналов?

Убедитесь, что выходные каналы одного слоя соответствуют ожидаемым входным каналам следующего. Используйте print(model.model.model) чтобы проверить архитектуру вашей модели.

Где я могу найти список доступных модулей и их аргументов?

Проверьте исходный код в ultralytics/nn/modules directory для всех доступных модулей и их аргументов.

Как добавить пользовательский модуль в мою YAML-конфигурацию?

Определите свой модуль в исходном коде, импортируйте его, как показано в разделе Изменение исходного кода, и укажите его имя в вашем YAML-файле.

Могу ли я использовать предварительно обученные веса с пользовательским YAML-файлом?

Да, вы можете использовать model.load("path/to/weights") чтобы загрузить веса из предварительно обученной контрольной точки. Однако успешно загрузятся только веса для совпадающих слоев.

Как проверить конфигурацию моей модели?

Используйте model.info() чтобы проверить, является ли количество FLOP ненулевым. Действительная модель должна показывать ненулевое количество FLOP. Если оно равно нулю, следуйте предложениям в Советы по отладке чтобы найти проблему.

📅 Создано 2 месяца назад ✏️ Обновлено 1 месяц назад

Комментарии