모델 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)
.
다음 파라미터를 사용하여 중복성을 줄입니다. scales
에 지정되어 있습니다. scales
파라미터를 사용하면 단일 기본 YAML에서 여러 모델 크기를 생성할 수 있습니다. 예를 들어, 다음을 로드할 때 yolo11n.yaml
, Ultralytics는 기본 yolo11.yaml
을 읽고 n
스케일링 요소(depth=0.50
, width=0.25
)를 적용하여 나노 변형을 빌드합니다.
nc
및 kpt_shape
은 데이터 세트에 따라 달라집니다.
데이터 세트가 다른 nc
또는 kpt_shape
을 지정하는 경우 Ultralytics는 런타임 시 데이터 세트 YAML과 일치하도록 모델 구성을 자동으로 재정의합니다.
백본 및 헤드 아키텍처
모델 아키텍처는 백본(특징 추출) 및 헤드(작업별) 섹션으로 구성됩니다.
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]
구성 요소 | 목적 | 예제 |
---|---|---|
다음에서 | 입력 연결 | -1 (이전 레이어), 6 (레이어 6), [4, 6, 8] (다중 입력) |
반복 횟수 | 반복 횟수 | 1 (단일), 3 (3회 반복) |
모듈 | 모듈 유형 | Conv , C2f , TorchVision , Detect |
args | 모듈 인수 | [64, 3, 2] (채널, 커널, 스트라이드) |
연결 패턴
에 지정되어 있습니다. 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
레이어 인덱싱
레이어는 0부터 인덱싱됩니다. 음수 인덱스는 이전 레이어를 참조하고(-1
= 이전 레이어), 양수 인덱스는 특정 레이어를 위치별로 참조합니다.
모듈 반복
에 지정되어 있습니다. repeats
파라미터는 더 깊은 네트워크 섹션을 생성합니다.
- [-1, 3, C2f, [128, True]] # Creates 3 consecutive C2f blocks
- [-1, 1, Conv, [64, 3, 2]] # Single convolution layer
실제 반복 횟수는 모델 크기 구성의 깊이 스케일링 요소에 의해 곱해집니다.
사용 가능한 모듈
모듈은 기능별로 구성되어 있으며 Ultralytics 모듈 디렉토리에 정의되어 있습니다. 다음 표는 범주별로 일반적으로 사용되는 모듈을 보여주며, 소스 코드에서 더 많은 모듈을 사용할 수 있습니다.
기본 작업
모듈 | 목적 | 소스 | 인수 |
---|---|---|---|
Conv |
Convolution + BatchNorm + Activation | conv.py | [out_ch, kernel, stride, pad, groups] |
nn.Upsample |
공간 업샘플링 | PyTorch | [size, scale_factor, mode] |
nn.Identity |
Pass-through 연산 | PyTorch | [] |
복합 블록
모듈 | 목적 | 소스 | 인수 |
---|---|---|---|
C2f |
2개의 Convolution이 있는 CSP 병목 | block.py | [out_ch, shortcut, expansion] |
SPPF |
Spatial Pyramid Pooling (고속) | block.py | [out_ch, kernel_size] |
Concat |
채널별 연결 | conv.py | [dimension] |
특수 모듈
모듈 | 목적 | 소스 | 인수 |
---|---|---|---|
TorchVision |
torchvision 모델 로드 | block.py | [out_ch, model_name, weights, unwrap, truncate, split] |
Index |
목록에서 특정 텐서 추출 | block.py | [out_ch, index] |
Detect |
YOLO 감지 헤드 | head.py | [nc, anchors, ch] |
전체 모듈 목록
이것은 사용 가능한 모듈의 하위 집합을 나타냅니다. 전체 모듈 목록 및 해당 파라미터는 modules 디렉토리를 탐색하십시오.
고급 기능
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]]
파라미터 분석:
768
: 예상 출력 채널convnext_tiny
: 모델 아키텍처 (사용 가능한 모델)DEFAULT
: 사전 훈련된 가중치 사용True
: 분류 헤드 제거2
: 마지막 2개 레이어 잘라내기False
: 단일 텐서 반환 (목록 아님)
다중 스케일 특징
마지막 파라미터를 다음으로 설정하십시오. True
다중 스케일 감지를 위한 중간 특징 맵을 얻으려면
특징 선택을 위한 인덱스 모듈
여러 특징 맵을 출력하는 모델을 사용하는 경우 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]
- PyTorch 모듈: 다음으로 시작하는 이름
'nn.'
→torch.nn
네임스페이스 - TorchVision 연산: 다음으로 시작하는 이름
'ops.'
→torchvision.ops
네임스페이스 - Ultralytics 모듈: 다른 모든 이름 → import를 통해 전역 네임스페이스로
모듈 임포트 체인
표준 모듈은 다음 위치에서 import를 통해 사용할 수 있습니다. tasks.py
:
from ultralytics.nn.modules import ( # noqa: F401, E501
SPPF,
C2f,
Conv,
Detect,
# ... many more modules
Index,
TorchVision,
)
사용자 정의 모듈 통합
소스 코드 수정
소스 코드를 수정하는 것은 사용자 정의 모듈을 통합하는 가장 다재다능한 방법이지만 까다로울 수 있습니다. 사용자 정의 모듈을 정의하고 사용하려면 다음 단계를 따르세요.
-
빠른 시작 가이드의 Git clone 방법을 사용하여 개발 모드에서 Ultralytics를 설치하십시오.
-
모듈 정의 에서
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)
-
패키지 수준에서 모듈 노출 에서
ultralytics/nn/modules/__init__.py
:from .block import CustomBlock # noqa makes CustomBlock available as ultralytics.nn.modules.CustomBlock
-
import에 추가 에서
ultralytics/nn/tasks.py
:from ultralytics.nn.modules import CustomBlock # noqa
-
특수 인수 처리 (필요한 경우)
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:]]
-
모델 YAML에서 모듈 사용:
# custom_model.yaml nc: 1 backbone: - [-1, 1, CustomBlock, [64]] head: - [-1, 1, Classify, [nc]]
-
정방향 패스가 작동하는지 확인하려면 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) 패턴을 사용하십시오.
문제 해결
일반적인 문제
문제 | 원인 | 솔루션 |
---|---|---|
KeyError: 'ModuleName' |
모듈이 임포트되지 않음 | 다음에 추가 tasks.py imports |
채널 차원 불일치 | 잘못된 args 사양 |
입력/출력 채널 호환성 확인 |
AttributeError: 'int' object has no attribute |
잘못된 인수 유형 | 올바른 인수 유형에 대한 모듈 설명서 확인 |
모델 빌드 실패 | 유효하지 않은 from 참조 |
참조된 레이어가 존재하는지 확인 |
디버깅 팁
사용자 정의 아키텍처를 개발할 때 체계적인 디버깅은 문제를 조기에 식별하는 데 도움이 됩니다.
테스트를 위해 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}")
단계별 검증
- 최소한으로 시작: 가장 간단한 아키텍처로 먼저 테스트합니다.
- 점진적으로 추가: 레이어별로 복잡성을 구축합니다.
- 차원 확인: 채널 및 공간 크기 호환성을 확인합니다.
- 스케일링 검증: 다양한 모델 스케일로 테스트 (
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인 경우 다음 제안 사항을 따르십시오. 디버깅 팁 문제를 찾으십시오.