모델 YAML 구성

Q: How do I change the number of classes in my model?

데이터 집합의 클래스 수와 일치하도록 YAML 파일 상단의 nc 매개변수를 설정하세요.

Q: How do I scale my model for different sizes (nano, small, medium, etc.)?

YAML의 스케일 섹션을 사용하여 깊이, 너비 및 최대 채널에 대한 스케일 인자를 정의합니다. 파일 이름에 스케일이 추가된 기본 YAML 파일(예: yolo11n.yaml)을 로드하면 모델에서 자동으로 적용됩니다.

Q: How do I troubleshoot channel mismatch errors?

한 레이어의 출력 채널이 다음 레이어의 예상 입력 채널과 일치하는지 확인합니다. print(model.model.model)를 사용하여 모델의 아키텍처를 검사합니다.

Q: Where can I find a list of available modules and their arguments?

사용 가능한 모든 모듈과 해당 인수는 ultralytics 디렉터리에서 소스 코드를 확인하세요.

Q: Can I use pretrained weights with a custom YAML?

예, model.load("path/to/weights")를 사용하여 미리 학습된 체크포인트에서 가중치를 로드할 수 있습니다. 그러나 일치하는 레이어의 가중치만 성공적으로 로드됩니다.

Q: How do I validate my model configuration?

model.info()를 사용하여 FLOPs 수가 0이 아닌지 확인합니다. 유효한 모델에는 0이 아닌 FLOPs 수가 표시되어야 합니다. 0인 경우 디버깅 팁의 제안에 따라 문제를 찾아보세요.

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

다음을 통해 중복성을 줄이세요. 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`	컨볼루션 + 배치노름 + 활성화	conv.py	`[out_ch, kernel, stride, pad, groups]`
`nn.Upsample`	공간 업샘플링	PyTorch	`[size, scale_factor, mode]`
`nn.Identity`	패스스루 작업	PyTorch	`[]`

복합 블록

모듈	목적	소스	인수
`C2f`	2개의 컨볼루션을 사용하는 CSP 병목 현상	block.py	`[out_ch, shortcut, expansion]`
`SPPF`	공간 피라미드 풀링(빠른)	block.py	`[out_ch, kernel_size]`
`Concat`	채널별 연결	conv.py	`[dimension]`

전문 모듈

모듈	목적	소스	인수
`TorchVision`	토치비전 모델 로드	block.py	`[out_ch, model_name, weights, unwrap, truncate, split]`
`Index`	목록에서 특정 tensor 추출	block.py	`[out_ch, index]`
`Detect`	YOLO 감지 헤드	head.py	`[nc, anchors, ch]`

전체 모듈 목록

이는 사용 가능한 모듈의 하위 집합을 나타냅니다. 모듈 및 해당 매개변수의 전체 목록을 보려면 모듈 디렉터리를 살펴보세요.

고급 기능

TorchVision 통합

토치비전 모듈을 사용하면 모든 토치비전 모델을 백본으로 원활하게 통합할 수 있습니다:

PythonYAML 구성

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: 단일 tensor 반환(리스트가 아님)

멀티스케일 기능

마지막 매개 변수를 다음과 같이 설정합니다. True 를 사용하여 다중 규모 감지를 위한 중간 피처 맵을 얻을 수 있습니다.

기능 선택을 위한 인덱스 모듈

여러 피처 맵을 출력하는 모델을 사용하는 경우 인덱스 모듈은 특정 출력을 선택합니다:

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 네임스페이스
토치비전 운영: 로 시작하는 이름 'ops.' → torchvision.ops 네임스페이스
Ultralytics 모듈: 다른 모든 이름 → 가져오기를 통한 글로벌 네임스페이스

모듈 가져오기 체인

표준 모듈은 다음에서 가져오기를 통해 사용할 수 있습니다. tasks.py:

from ultralytics.nn.modules import (  # noqa: F401, E501
    SPPF,
    C2f,
    Conv,
    Detect,
    # ... many more modules
    Index,
    TorchVision,
)

사용자 지정 모듈 통합

소스 코드 수정

소스 코드를 수정하는 것은 사용자 정의 모듈을 통합하는 가장 다양한 방법이지만 까다로울 수 있습니다. 사용자 지정 모듈을 정의하고 사용하려면 다음 단계를 따르세요:

모듈 정의 에서 ultralytics/nn/modules/block.py:

class CustomBlock(nn.Module):
    def __init__(self, c1, c2):
        super().__init__()
        self.layers = nn.Sequential(nn.Conv2d(c1, c2, 3, 1, 1), nn.BatchNorm2d(c2), nn.ReLU())

    def forward(self, x):
        return self.layers(x)

패키지 수준에서 모듈 노출 에서 ultralytics/nn/modules/__init__.py:

from .block import CustomBlock  # noqa makes CustomBlock available as ultralytics.nn.modules.CustomBlock

가져오기에 추가 에서 ultralytics/nn/tasks.py:

from ultralytics.nn.modules import CustomBlock  # noqa

특수 인수 처리 (필요한 경우) 내부 parse_model() 에서 ultralytics/nn/tasks.py:

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

FLOP을 확인하여 포워드 패스가 작동하는지 확인합니다:

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

토치비전 백본 모델

# 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)를 시퀀스의 다음 레이어에 추가합니다.

연결 건너뛰기 사용: 다음을 통해 기능 재사용 활용 [[-1, N], 1, Concat, [1]] 패턴을 연결합니다. 이러한 연결은 그라데이션 흐름에 도움이 되며 모델에서 다양한 스케일의 기능을 결합할 수 있습니다.

적절한 규모 조정: 계산 제약 조건에 따라 모델 배율을 선택합니다. 나노 사용(n), 엣지 디바이스의 경우 소형(s), 균형 잡힌 성능을 위해 더 큰 규모(m, l, x)를 사용하여 정확도를 극대화합니다.

성능 고려 사항

깊이와 폭: 딥 네트워크는 여러 변환 계층을 통해 복잡한 계층적 특징을 포착하는 반면, 와이드 네트워크는 각 계층에서 더 많은 정보를 병렬로 처리합니다. 작업의 복잡성에 따라 이 둘의 균형을 맞출 수 있습니다.

연결 건너뛰기: 학습 중 그라데이션 흐름을 개선하고 네트워크 전체에서 피처 재사용을 가능하게 합니다. 특히 더 깊은 아키텍처에서 그라데이션이 사라지는 것을 방지하기 위해 중요합니다.

병목 블록: 모델 표현력을 유지하면서 계산 비용을 절감합니다. 다음과 같은 모듈 C2f 기능 학습 용량을 유지하면서 표준 컨볼루션보다 더 적은 수의 매개 변수를 사용합니다.

멀티 스케일 기능: 동일한 이미지에서 다양한 크기의 물체를 감지하는 데 필수적입니다. 다양한 스케일의 여러 감지 헤드가 있는 FPN(피처 피라미드 네트워크) 패턴을 사용합니다.

문제 해결

일반적인 문제

문제	원인	솔루션
`KeyError: 'ModuleName'`	모듈을 가져올 수 없습니다.	다음에 추가 `tasks.py` 수입
채널 치수 불일치	잘못됨 `args` 사양	입력/출력 채널 호환성 확인
`AttributeError: 'int' object has no attribute`	잘못된 인수 유형	모듈 설명서에서 올바른 인수 유형을 확인하세요.
모델을 빌드하지 못함	유효하지 않음 `from` 참조	참조된 레이어가 있는지 확인

디버깅 팁

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

테스트에 아이덴티티 헤드 사용

복잡한 헤드를 다음과 같이 교체하십시오. 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

내 모델의 클래스 수를 변경하려면 어떻게 해야 하나요?

설정 nc 매개 변수를 데이터 집합의 클래스 수와 일치하도록 YAML 파일 상단에 추가합니다.

nc: 5 # 5 classes

내 모델 YAML에 사용자 지정 백본을 사용할 수 있나요?

예. TorchVision 백본을 포함하여 지원되는 모든 모듈을 사용하거나 사용자 지정 모듈 통합에 설명된 대로 자체 사용자 지정 모듈을 정의하고 가져올 수 있습니다.

다양한 크기(나노, 소형, 중형 등)에 맞게 모델을 확장하려면 어떻게 해야 하나요?

다음을 사용하여 scales 섹션 를 사용하여 깊이, 너비 및 최대 채널에 대한 배율을 정의할 수 있습니다. 파일 이름에 스케일이 추가된 기본 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인 경우 다음 제안 사항을 따르세요. 디버깅 팁 를 클릭하여 문제를 찾아보세요.

📅 생성일: 0일 전 ✏️ 업데이트: 0일 전