Hướng dẫn cấu hình YAML cho model#

File cấu hình YAML của model đóng vai trò là bản thiết kế kiến trúc cho các mạng neural của Ultralytics. File này định nghĩa cách các layer kết nối với nhau, từng module sử dụng những tham số nào và toàn bộ mạng được scale ra sao ở các kích thước model khác nhau.

Cấu trúc cấu hình#

File YAML của model được tổ chức thành ba phần chính, phối hợp với nhau để định nghĩa kiến trúc.

Phần Parameters#

Phần parameters chỉ định các đặc tính toàn cục và hành vi scaling của model:

# 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 đặt số lượng class mà model dự đoán.
• scales định nghĩa các hệ số compound scaling để điều chỉnh độ sâu, độ rộng và số channel tối đa của model, tạo ra các biến thể kích thước khác nhau (từ nano đến extra-large).
• kpt_shape áp dụng cho các model pose. Tham số này có thể là [N, 2] cho (x, y) keypoint hoặc [N, 3] cho (x, y, visibility).

Kiến trúc Backbone và Head#

Kiến trúc model gồm các phần backbone (trích xuất đặc trưng) và head (chuyên biệt cho từng tác vụ):

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

Chỉ số layer tiếp tục tăng xuyên suốt backbone và head; các feature map được nối với nhau phải có cùng kích thước không gian.

Định dạng đặc tả Layer#

Mỗi layer tuân theo một cấu trúc thống nhất: [from, repeats, module, args]

Các kiểu kết nối#

Trường from tạo ra các kiểu luồng dữ liệu linh hoạt xuyên suốt mạng của bạn:

- [-1, 1, Conv, [64, 3, 2]]    # Takes input from previous layer

Lặp Module#

Tham số repeats tạo ra các phần mạng sâu hơn:

- [-1, 3, C2f, [128, True]] # Creates 3 consecutive C2f blocks
- [-1, 1, Conv, [64, 3, 2]] # Single convolution layer

Số lần lặp thực tế được nhân với hệ số scaling độ sâu từ cấu hình kích thước model.

Các Module hiện có#

Các module được sắp xếp theo chức năng và định nghĩa trong thư mục module của Ultralytics. Các bảng sau liệt kê những module thường dùng theo danh mục; trong mã nguồn còn có nhiều module khác:

Thao tác cơ bản#

Các khối kết hợp#

Các Module chuyên biệt#

Tính năng nâng cao#

Tích hợp TorchVision#

Module TorchVision cho phép tích hợp liền mạch bất kỳ model TorchVision nào làm backbone:

from ultralytics import YOLO

# Model sử dụng backbone ConvNeXt
model = YOLO("convnext_backbone.yaml")
results = model.train(data="imagenet10", epochs=100)

Module Index để chọn Feature#

Khi sử dụng các model xuất ra nhiều feature map, module Index sẽ chọn các đầu ra cụ thể:

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

Hệ thống phân giải Module#

Hiểu cách Ultralytics xác định vị trí và import module là điều thiết yếu khi tùy chỉnh:

Quy trình tra cứu Module#

Ultralytics sử dụng hệ thống ba tầng trong parse_model:

# Logic phân giải cốt lõi
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]
)  # lấy module

1. Các module PyTorch: Tên bắt đầu bằng 'nn.' → namespace torch.nn
2. Các thao tác TorchVision: Tên bắt đầu bằng 'torchvision.ops.' → namespace torchvision.ops
3. Các module Ultralytics: Tất cả tên khác → global namespace thông qua imports

Chuỗi Import Module#

Các module tiêu chuẩn được cung cấp thông qua imports trong tasks.py:

from ultralytics.nn.modules import (  # noqa: F401
    SPPF,
    C2f,
    Conv,
    Detect,
    # ... còn nhiều module khác
    Index,
    TorchVision,
)

Tích hợp Module tùy chỉnh#

Chỉnh sửa mã nguồn#

Chỉnh sửa mã nguồn là cách linh hoạt nhất để tích hợp các module tùy chỉnh, nhưng có thể khá phức tạp. Để định nghĩa và sử dụng module tùy chỉnh, hãy làm theo các bước sau:

1. Cài đặt Ultralytics ở chế độ development bằng phương pháp Git clone trong hướng dẫn Quickstart.

2. Định nghĩa module trong 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. Đưa module vào cấp package trong ultralytics/nn/modules/__init__.py:

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

4. Thêm vào imports trong ultralytics/nn/tasks.py:

   from ultralytics.nn.modules import CustomBlock  # noqa

5. Thêm module vào base_modules trong parse_model(). Các module trong tập hợp này sẽ tự động nhận số channel đầu vào và đầu ra:

   base_modules = frozenset(
       {
           # Các module hiện có...
           CustomBlock,
       }
   )

6. Sử dụng module trong YAML của model:

   # custom_model.yaml
   nc: 1
   backbone:
       - [-1, 1, CustomBlock, [64]]
   head:
       - [-1, 1, Classify, [nc]]

7. Kiểm tra FLOPs để đảm bảo forward pass hoạt động:

   from ultralytics import YOLO
   
   model = YOLO("custom_model.yaml", task="classify")
   model.info()  # nên in ra FLOPs khác 0 nếu hoạt động

Ví dụ cấu hình#

Model phát hiện cơ bản#

# 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

Model backbone 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

Model phân loại#

# 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 đã thực hiện pooling trung bình thích ứng nội bộ.

Các phương pháp hay nhất#

Mẹo thiết kế kiến trúc#

Bắt đầu đơn giản: Bắt đầu với các kiến trúc đã được kiểm chứng trước khi tùy chỉnh. Dùng cấu hình YOLO hiện có làm mẫu và sửa đổi từng bước thay vì xây dựng từ đầu.

Kiểm thử từng bước: Xác thực từng bước sửa đổi. Thêm từng module tùy chỉnh một và xác minh module hoạt động trước khi tiếp tục thay đổi tiếp theo.

Theo dõi số kênh: Đảm bảo số chiều kênh khớp nhau giữa các layer được kết nối. Số kênh đầu ra (c2) của một layer phải khớp với số kênh đầu vào (c1) của layer tiếp theo trong chuỗi.

Sử dụng kết nối skip: Tận dụng khả năng tái sử dụng đặc trưng với các mẫu [[-1, N], 1, Concat, [1]]. Những kết nối này hỗ trợ luồng gradient và cho phép model kết hợp đặc trưng từ các scale khác nhau.

Chọn scale phù hợp: Chọn scale model dựa trên giới hạn tính toán của bạn. Dùng nano (n) cho thiết bị edge, small (s) để cân bằng hiệu năng và các scale lớn hơn (m, l, x) để đạt độ chính xác tối đa.

Các yếu tố cần cân nhắc về hiệu năng#

Độ sâu và độ rộng: Mạng sâu trích xuất các đặc trưng phân cấp phức tạp thông qua nhiều layer biến đổi, trong khi mạng rộng xử lý song song nhiều thông tin hơn ở mỗi layer. Hãy cân bằng hai yếu tố này dựa trên độ phức tạp của tác vụ.

Kết nối skip: Cải thiện luồng gradient trong quá trình huấn luyện và cho phép tái sử dụng đặc trưng xuyên suốt mạng. Chúng đặc biệt quan trọng trong các kiến trúc sâu hơn để ngăn gradient biến mất.

Các block bottleneck: Giảm chi phí tính toán trong khi vẫn duy trì khả năng biểu diễn của model. Các module như C2f sử dụng ít tham số hơn so với convolution tiêu chuẩn nhưng vẫn bảo toàn năng lực học đặc trưng.

Đặc trưng đa scale: Thiết yếu để phát hiện các đối tượng có kích thước khác nhau trong cùng một ảnh. Sử dụng các mẫu Mạng Kim tự tháp Đặc trưng (FPN) với nhiều head phát hiện ở các scale khác nhau.

Khắc phục sự cố#

Các sự cố thường gặp#

Mẹo gỡ lỗi#

Khi phát triển kiến trúc tùy chỉnh, việc gỡ lỗi có hệ thống giúp sớm xác định vấn đề:

Dùng head identity để kiểm thử

Thay các head phức tạp bằng nn.Identity để cô lập vấn đề ở backbone:

nc: 1
backbone:
    - [-1, 1, CustomBlock, [64]]
head:
    - [-1, 1, nn.Identity, []] # Pass-through for debugging

Cách này cho phép kiểm tra trực tiếp đầu ra của backbone:

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

Kiểm tra kiến trúc model

Kiểm tra số FLOPs và in từng layer cũng có thể giúp gỡ lỗi cấu hình model tùy chỉnh. Số FLOPs phải khác không thì model mới hợp lệ. Nếu bằng không, có thể forward pass đang gặp vấn đề. Chạy một forward pass đơn giản sẽ cho biết chính xác lỗi đang gặp phải.

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}")

Xác thực từng bước

1. Bắt đầu tối giản: Trước tiên, kiểm thử với kiến trúc đơn giản nhất có thể
2. Bổ sung từng bước: Tăng dần độ phức tạp theo từng layer
3. Kiểm tra kích thước: Xác minh tính tương thích của số kênh và kích thước không gian
4. Xác thực việc scaling: Kiểm thử với các scale model khác nhau (n, s, m)

Câu hỏi thường gặp#