モデル YAML 設定ガイド#

モデル YAML 設定ファイルは、Ultralytics ニューラルネットワークのアーキテクチャ設計図として機能します。レイヤーの接続方法、各モジュールが使用するパラメーター、さまざまなモデルサイズに応じたネットワーク全体のスケーリング方法を定義します。

設定の構成#

モデル YAML ファイルは、連携してアーキテクチャを定義する3つの主要なセクションで構成されています。

パラメーターセクション#

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) に設定できます。

バックボーンとヘッドのアーキテクチャ#

モデルアーキテクチャは、バックボーン（特徴抽出）とヘッド（タスク固有）のセクションで構成されます。

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()  # 正常に動作していれば、ゼロ以外の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]]パターンを使用して特徴を再利用してください。これらの接続は勾配の流れを助け、モデルが異なるスケールの特徴を組み合わせられるようにします。

適切にスケーリングする: 計算リソースの制約に基づいてモデルのスケールを選択してください。エッジデバイスにはnano（n）、性能のバランスを取るにはsmall（s）、最大限の精度を求める場合はより大きなスケール（m、l、x）を使用してください。

パフォーマンスに関する考慮事項#

深さと幅: 深いネットワークは複数の変換レイヤーを通じて複雑な階層的特徴を捉え、幅の広いネットワークは各レイヤーでより多くの情報を並列処理します。タスクの複雑さに応じてバランスを取ってください。

スキップ接続: 学習中の勾配の流れを改善し、ネットワーク全体で特徴を再利用できるようにします。勾配消失を防ぐため、特に深いアーキテクチャでは重要です。

ボトルネックブロック: モデルの表現力を維持しながら、計算コストを削減します。C2fなどのモジュールは、特徴学習能力を保ちながら、標準的な畳み込みよりも少ないパラメーターを使用します。

マルチスケール特徴: 同じ画像内の異なるサイズの物体を検出するうえで不可欠です。異なるスケールに複数の検出ヘッドを配置するFeature Pyramid Network（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数がゼロ以外になるはずです。ゼロの場合は、フォワードパスに問題がある可能性があります。単純なフォワードパスを実行すると、発生しているエラーを正確に確認できます。

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）でテストしてください

よくある質問#