모델 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 포즈 모델에 적용됩니다. 값은 다음과 같습니다. [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

- [[-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 모델을 백본으로 원활하게 통합할 수 있습니다.

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는 3단계 시스템을 사용합니다. 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 모듈: 다른 모든 이름 → import를 통해 전역 네임스페이스로

모듈 임포트 체인

표준 모듈은 다음 위치에서 import를 통해 사용할 수 있습니다. tasks.py:

from ultralytics.nn.modules import (  # noqa: F401, E501
    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. import에 추가 에서 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
   

구성 예시

기본 감지 모델

# 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 연결 사용: 다음을 통해 기능 재사용 활용 [[-1, N], 1, Concat, [1]] 패턴. 이러한 연결은 기울기 흐름을 돕고 모델이 다양한 스케일의 기능을 결합할 수 있도록 합니다.

적절하게 스케일링: 계산 제약 조건에 따라 모델 스케일을 선택하세요. 나노 사용(n) 등의 에지 장치용 소형 모델(s)은 균형 잡힌 성능을, 더 큰 스케일(m, l, x)은 최대 정확도를 제공합니다.

성능 고려 사항

깊이 대 폭: 심층 네트워크는 여러 변환 계층을 통해 복잡한 계층적 특징을 캡처하는 반면, 광폭 네트워크는 각 계층에서 더 많은 정보를 병렬로 처리합니다. 작업 복잡성에 따라 이 균형을 조정하십시오.

Skip Connections: 학습 중 기울기 흐름을 개선하고 네트워크 전체에서 특징 재사용을 활성화합니다. 이는 기울기 소실을 방지하기 위해 더 심층적인 아키텍처에서 특히 중요합니다.

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

Multi-Scale Features: 동일한 이미지에서 다양한 크기의 객체를 감지하는 데 필수적입니다. 다양한 스케일에서 여러 감지 헤드가 있는 FPN(Feature Pyramid Network) 패턴을 사용하십시오.

문제 해결

일반적인 문제

디버깅 팁

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

테스트를 위해 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")
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", 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 등)에 맞게 모델을 어떻게 조정합니까?

다음을 사용하여 scales 섹션 YAML에서 깊이, 너비 및 최대 채널에 대한 스케일링 요소를 정의합니다. 모델은 파일 이름에 스케일이 추가된 기본 YAML 파일을 로드할 때 자동으로 이를 적용합니다(예: yolo11n.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 계산이 0이 아닌지 확인합니다. 유효한 모델은 0이 아닌 FLOPs 계산을 표시해야 합니다. 0인 경우 다음 제안 사항을 따르십시오. 디버깅 팁 문제를 찾으십시오.

📅 1개월 전에 생성됨 ✏️ 14일 전에 업데이트됨

댓글