모델 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은 모델의 깊이, 너비 및 최대 채널 수를 조정하여 다양한 크기 변형(나노부터 엑스트라 라지까지)을 생성하는 복합 스케일링 계수를 정의합니다.
• kpt_shape은 포즈 모델에 적용됩니다. (x, y) 키포인트에는 [N, 2]을, (x, y, visibility)에는 [N, 3]을 사용할 수 있습니다.

백본 및 헤드 아키텍처#

모델 아키텍처는 백본(특징 추출)과 헤드(작업별) 섹션으로 구성됩니다:

nc: 80

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]] # 3: Upsample
    - [[-1, 0], 1, Concat, [1]] # 4: Spatially compatible skip connection
    - [-1, 3, C2f, [256]] # 5: Process features
    - [[5], 1, Detect, [nc]] # 6: 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="imagenet10", epochs=100)

특징 선택을 위한 Index 모듈#

여러 특징 맵을 출력하는 모델을 사용할 때 Index 모듈은 특정 출력을 선택합니다:

nc: 80

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에서 3단계 시스템을 사용합니다:

# Core resolution logic
m = (
    getattr(torch.nn, m[3:])
    if m.startswith("nn.")
    else getattr(__import__("torchvision").ops, m[16:])
    if m.startswith("torchvision.ops.")
    else globals()[m]
)  # get module

1. PyTorch 모듈: 'nn.'으로 시작하는 이름 → torch.nn 네임스페이스
2. TorchVision 연산: '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 clone 방법을 사용하여 개발 모드로 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. ultralytics/nn/tasks.py에서 가져오기에 추가:

   from ultralytics.nn.modules import CustomBlock  # noqa

5. parse_model() 내부의 base_modules에 모듈 추가. 이 집합의 모듈은 입력 및 출력 채널을 자동으로 전달받습니다:

   base_modules = frozenset(
       {
           # Existing modules...
           CustomBlock,
       }
   )

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]]

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

Classify은 이미 내부적으로 적응형 평균 풀링을 수행합니다.

모범 사례#

아키텍처 설계 팁#

간단하게 시작하기: 사용자 지정 전에 검증된 아키텍처부터 시작합니다. 처음부터 구축하기보다는 기존 YOLO 구성을 템플릿으로 사용하고 점진적으로 수정합니다.

점진적으로 테스트하기: 각 수정 사항을 단계별로 검증합니다. 한 번에 하나의 사용자 지정 모듈만 추가하고 다음 변경으로 넘어가기 전에 정상적으로 작동하는지 확인합니다.

채널 모니터링하기: 연결된 레이어 간 채널 차원이 일치하는지 확인합니다. 한 레이어의 출력 채널(c2)은 시퀀스에서 다음 레이어의 입력 채널(c1)과 일치해야 합니다.

스킵 연결 사용하기: [[-1, N], 1, Concat, [1]] 패턴을 사용하여 특징을 재사용합니다. 이러한 연결은 그래디언트 흐름을 개선하고 모델이 서로 다른 스케일의 특징을 결합할 수 있도록 합니다.

적절하게 스케일링하기: 컴퓨팅 제약 조건에 따라 모델 스케일을 선택합니다. 엣지 디바이스에는 nano(n), 균형 잡힌 성능에는 small(s), 최고 정확도에는 더 큰 스케일(m, l, x)을 사용합니다.

성능 고려 사항#

깊이와 너비: 깊은 네트워크는 여러 변환 레이어를 통해 복잡한 계층적 특징을 추출하는 반면, 넓은 네트워크는 각 레이어에서 더 많은 정보를 병렬로 처리합니다. 작업의 복잡도에 따라 이 둘의 균형을 맞춥니다.

스킵 연결: 학습 중 그래디언트 흐름을 개선하고 네트워크 전체에서 특징을 재사용할 수 있도록 합니다. 그래디언트 소실을 방지하려면 더 깊은 아키텍처에서 특히 중요합니다.

병목 블록: 모델의 표현력을 유지하면서 컴퓨팅 비용을 줄입니다. C2f과 같은 모듈은 특징 학습 능력을 유지하면서 표준 컨볼루션보다 적은 파라미터를 사용합니다.

다중 스케일 특징: 동일한 이미지에서 다양한 크기의 객체를 탐지하는 데 필수적입니다. 여러 스케일에서 다중 탐지 헤드와 함께 특징 피라미드 네트워크(FPN) 패턴을 사용합니다.

문제 해결#

일반적인 문제#

디버깅 팁#

사용자 지정 아키텍처를 개발할 때 체계적인 디버깅을 수행하면 문제를 조기에 식별하는 데 도움이 됩니다:

테스트에 Identity Head 사용하기

복잡한 헤드를 nn.Identity으로 교체하여 백본 문제를 분리합니다:

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", task="detect")
output = model.model(torch.randn(1, 3, 640, 640))
print(f"Output shape: {output.shape}")  # Should match expected dimensions

모델 아키텍처 검사

FLOPs 수를 확인하고 각 레이어를 출력하는 것도 사용자 지정 모델 구성의 문제를 디버깅하는 데 도움이 될 수 있습니다. 유효한 모델의 FLOPs 수는 0이 아니어야 합니다. 0이라면 순전파에 문제가 있을 가능성이 높습니다. 간단한 순전파를 실행하면 발생한 정확한 오류를 확인할 수 있습니다.

from ultralytics import YOLO

# Build model with verbose output to see layer details
model = YOLO("debug_model.yaml", task="detect", 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#