モデル 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).
冗長性を削減するには、 scales
The 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]
| コンポーネント | 目的 | 例 | 
|---|---|---|
| from | 入力接続 | -1(前へ)、6(レイヤー 6)、[4, 6, 8](複数入力) | 
| 繰り返し | 繰り返しの回数 | 1(単一)3(3回繰り返し) | 
| モジュール | モジュールタイプ | Conv,C2f,TorchVision,Detect | 
| args | モジュールの引数 | [64, 3, 2](チャネル数、カーネルサイズ、ストライド) | 
接続パターン
The from fieldは、ネットワーク全体で柔軟なデータフローパターンを生成します。
- [-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 = 前のレイヤー)、正のインデックスは特定の位置にあるレイヤーを参照します。
モジュールの繰り返し
The 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 | パススルーオペレーション | 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 | リストから特定のtensorを抽出 | 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:単一のtensorを返す(リストではない)
マルチスケール特徴
最後のパラメータを以下に設定 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名前空間
- <strong>Ultralyticsモジュール:その他すべての名前 → インポートを介してグローバル名前空間へ
モジュールインポートチェーン
標準モジュールは、インポートによって利用可能になります。 tasks.py:
from ultralytics.nn.modules import (  # noqa: F401, E501
    SPPF,
    C2f,
    Conv,
    Detect,
    # ... many more modules
    Index,
    TorchVision,
)
カスタムモジュールの統合
ソースコードの修正
ソースコードを修正することは、カスタムモジュールを統合する上で最も汎用性の高い方法ですが、トリッキーな場合があります。カスタムモジュールを定義して使用するには、次の手順に従ってください。
- 
Ultralytics を開発モードでインストールするには、クイックスタートガイドにあるように、Git clone メソッドを使用します。 
- 
モジュールを定義する で 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
- 
インポートに追加する で 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で<strong>モジュールを使用する: # custom_model.yaml nc: 1 backbone: - [-1, 1, CustomBlock, [64]] head: - [-1, 1, Classify, [nc]]
- 
フォワードパスが機能することを確認するために、<strong>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]]
ベストプラクティス
アーキテクチャ設計のヒント
<strong>シンプルに始める:カスタマイズする前に、実績のあるアーキテクチャから始めてください。既存のYOLO構成をテンプレートとして使用し、ゼロから構築するのではなく、段階的に変更してください。
<strong>段階的にテストする:各変更を段階的に検証します。一度に1つのカスタムモジュールを追加し、次の変更に進む前に、それが機能することを確認します。
チャネルを監視する:接続されたレイヤー間でチャネルの次元が一致していることを確認します。あるレイヤーの出力チャネル(c2)は、シーケンス内の次のレイヤーの入力チャネル(c1)と一致する必要があります。
スキップ接続を使用する:以下で特徴の再利用を活用します [[-1, N], 1, Concat, [1]] パターン。これらの接続は、勾配の流れを助け、モデルが異なるスケールの特徴を組み合わせることを可能にします。
適切にスケールする:計算上の制約に基づいてモデルのスケールを選択します。エッジデバイスにはnano(n)を、バランスの取れたパフォーマンスにはsmall(s)を、より大きなスケールにはm, l, x)で、精度を最大限に高めます。
パフォーマンスに関する考慮事項
Depth vs Width:深層ネットワークは、複数の変換層を介して複雑な階層的特徴を捉え、広層ネットワークは、各層でより多くの情報を並行して処理します。タスクの複雑さに応じて、これらをバランスさせます。
Skip Connections:トレーニング中の勾配の流れを改善し、ネットワーク全体で特徴の再利用を可能にします。これらは、勾配消失を防ぐために、より深いアーキテクチャで特に重要です。
ボトルネックブロック:モデルの表現力を維持しながら、計算コストを削減します。次のようなモジュール C2f は、特徴学習能力を維持しながら、標準的な畳み込みよりも少ないパラメータを使用します。
Multi-Scale Features:同一画像内の異なるサイズのオブジェクトを検出するために不可欠です。異なるスケールで複数の検出ヘッドを持つ Feature Pyramid Network(FPN)パターンを使用します。
トラブルシューティング
よくある問題
| 問題 | 原因 | ソリューション | 
|---|---|---|
| KeyError: 'ModuleName' | モジュールがインポートされていません | に追加 tasks.pyインポート | 
| チャネル次元の不一致 | 不正な 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のカウントは、有効なモデルではゼロ以外である必要があります。ゼロの場合は、フォワードパスに問題がある可能性があります。単純なフォワードパスを実行すると、発生している正確なエラーが表示されます。
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)
よくある質問
モデルのクラス数を変更するにはどうすればよいですか?
YAMLファイルの先頭にある nc パラメータを、データセットのクラス数と一致するように設定します。
nc: 5 # 5 classes
モデルのYAMLでカスタムバックボーンを使用できますか?
はい。TorchVisionバックボーンを含む、サポートされている任意のモジュールを使用したり、カスタムモジュール統合で説明されているように、独自のカスタムモジュールを定義してインポートしたりできます。
モデルをさまざまなサイズ(nano、small、mediumなど)にスケールするにはどうすればよいですか?
以下を使用します scales セクション YAMLファイルで、depth(深度)、width(幅)、およびmax channels(最大チャネル数)のスケーリングファクターを定義します。モデルは、ファイル名にスケールが付加されたベース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カウントを示す必要があります。ゼロの場合は、次の提案に従って デバッグのヒント 問題を特定してください。