모델 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

# ConvNeXt 백본을 사용하는 모델
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단계 시스템을 사용합니다.

# 핵심 확인 로직
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]
)  # 모듈 가져오기

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,
    # ... 그 외 다양한 모듈
    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(
       {
           # 기존 모듈...
           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()  # 작동하면 0이 아닌 FLOPs가 출력되어야 합니다.

예제 구성#

기본 탐지 모델#

# 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]] 패턴을 사용해 특징을 재사용합니다. 이러한 연결은 그래디언트 흐름을 개선하고 모델이 서로 다른 스케일의 특징을 결합하도록 합니다.

적절하게 스케일 조정하기: 컴퓨팅 제약 조건에 따라 모델 스케일을 선택합니다. 엣지 디바이스에는 나노(n), 균형 잡힌 성능에는 스몰(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)로 테스트합니다

자주 묻는 질문#