モデルのYAMLコンフィギュレーション

モデルYAML設定ファイルは、Ultralytics ニューラルネットワークのアーキテクチャーの青写真の役割を果たします。レイヤーの接続方法、各モジュールが使用するパラメータ、異なるモデルサイズに対してネットワーク全体がどのようにスケールするかを定義します。

構成構造

モデルのYAMLファイルはアーキテクチャを定義するために連携する3つの主要なセクションに編成されます。

パラメーターセクション

パラメータセクションでは、モデルのグローバルな特性とスケーリング動作を指定する：

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

コネクション・パターン

The 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

モジュールの繰り返し

The repeats パラメータは、より深いネットワークセクションを作成する：

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

実際の繰り返し回数には、モデルサイズの設定から深さのスケーリング係数が掛けられる。

利用可能なモジュール

モジュールは機能ごとに整理され、Ultralytics モジュールディレクトリに定義されています。以下の表は、よく使用されるモジュールをカテゴリ別に示したものです：

基本操作

複合ブロック

専門モジュール

高度な機能

トーチビジョンの統合

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. トーチビジョン事業:で始まる名前 'ops.' → torchvision.ops 名前空間
3. Ultralytics モジュール：他のすべての名前 → imports によるグローバル名前空間

モジュール・インポート・チェーン

標準モジュールは tasks.py:

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

カスタムモジュールの統合

ソースコードの修正

ソースコードを変更することは、カスタムモジュールを統合する最も汎用的な方法ですが、厄介な場合があります。カスタムモジュールを定義して使用するには、以下の手順に従ってください：

1. モジュールを定義する で 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)
   

2. パッケージレベルでモジュールを公開する で ultralytics/nn/modules/__init__.py:

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

3. インポートに追加 で ultralytics/nn/tasks.py:

   from ultralytics.nn.modules import CustomBlock  # noqa
   

4. 特殊引数の処理 (必要に応じて）内側 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:]]
   

5. モデルのYAMLでモジュールを使います：

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

6. 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 コンフィギュレーションをテンプレートとして使用し、ゼロから構築するのではなく、段階的に修正していきます。

段階的にテストする：各変更を段階的に検証する。一度に1つのカスタムモジュールを追加し、次の変更に進む前にそれが動作することを確認します。

モニター・チャンネル:接続されたレイヤー間でチャンネルの寸法が一致していることを確認する。出力チャンネル(c2)は入力チャンネル(c1)の次のレイヤーの

スキップ・コネクションを使う:機能再利用の活用 [[-1, N], 1, Concat, [1]] パターンがある。これらの接続は勾配の流れを助け、モデルが異なるスケールの特徴を組み合わせることを可能にする。

適切な規模:計算上の制約に基づいてモデルスケールを選択します。ナノスケール(n)、エッジ・デバイスは小型(s)でバランスの取れたパフォーマンスを実現し、より大きなスケール(m, l, x)の精度を最大限に高める。

パフォーマンスに関する考察

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

接続をスキップ：トレーニング中の勾配フローを改善し、ネットワーク全体で特徴の再利用を可能にする。勾配の消失（vanishing gradients）を防ぐため、深いアーキテクチャでは特に重要です。

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

マルチスケール機能：同一画像内の異なるサイズの物体を検出するために不可欠。異なるスケールで複数の検出ヘッドを持つ特徴ピラミッドネットワーク（FPN）パターンを使用します。

トラブルシューティング

よくある問題

デバッグのヒント

カスタム・アーキテクチャを開発する場合、体系的なデバッグは問題の早期発見に役立つ：

アイデンティティ・ヘッドをテストに使用する

複雑なヘッドを 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カウントはゼロではないはずです。ゼロであれば、フォワードパスに問題がある可能性が高い。単純なフォワードパスを実行すると、発生したエラーが正確に表示されるはずです。

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)

よくある質問

モデル内のクラス数を変更するには？

を設定する。 nc パラメーターをYAMLファイルの先頭に追加します。

nc: 5 # 5 classes

モデルYAMLでカスタムバックボーンを使うことはできますか？

TorchVisionバックボーンを含むサポートされているモジュール、または独自のカスタムモジュールを定義し、カスタムモジュールの統合で説明されているようにインポートすることができます。

さまざまなサイズ（ナノ、スモール、ミディアムなど）に対応するにはどうすればよいですか？

以下を使用します 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カウントがゼロでないかどうかをチェックします。有効なモデルはFLOPsカウントがゼロでないことを示すはずである。ゼロの場合は デバッグのヒント を使って問題を見つける。

📅 作成日 0日前 ✏️ 更新日 0日前