YOLOでよくある問題のトラブルシューティング#

このガイドでは、Ultralytics YOLO26の使用時によく発生する問題を、発生箇所ごとに分類して説明します。インストール、モデルのトレーニング、予測、デプロイが対象です。エラーに該当するカテゴリに移動するか、簡単な回答を確認するにはFAQをご覧ください。各項目には問題と、すぐに適用できる具体的な解決策を記載しています。

よくある問題#

インストールエラー#

インストールエラーは、互換性のないバージョン、依存関係の不足、環境設定の誤りなど、さまざまな原因で発生します。まず、次の項目を確認してください。

• 推奨されているPython 3.8以降を使用していることを確認してください。
• 正しいバージョンのPyTorch（1.8以降）がインストールされていることを確認してください。
• 競合を避けるため、仮想環境の使用を検討してください。
• 公式インストールガイドの手順に従ってください。

また、よくあるインストールの問題に対する解決策を以下に示します。

インポートエラーまたは依存関係の問題#

YOLO26のインポート時にエラーが発生したり、依存関係の競合が起きたりした場合は、次の手順を試してください。

• クリーンインストール: クリーンな状態からインストールすると、特にパッケージ構造や機能を変更する更新の後に発生した予期しない問題を解決できる場合があります。
• 定期的な更新: 古いリリースは最近の更新と互換性がない場合があるため、ライブラリの最新バージョンを使用してください。
• 依存関係の確認: 必要な依存関係がすべて正しくインストールされ、互換性のあるバージョンであることを確認してください。
• 変更内容の確認: 古いバージョンをインストールした場合は、公式ドキュメントまたは変更履歴を参照し、構造に関する主な変更点を確認してください。

GPUでYOLO26を実行する#

GPUでYOLO26を実行する際に問題がある場合は、次のトラブルシューティング手順を検討してください。

• CUDAの互換性とインストールを確認: GPUがCUDAに対応しており、CUDAが正しくインストールされていることを確認してください。nvidia-smiコマンドを使用して、NVIDIA GPUとCUDAのバージョンの状態を確認します。
• PyTorchとCUDAの連携を確認: Pythonターミナルでimport torch; print(torch.cuda.is_available())を実行し、PyTorchがCUDAを利用できることを確認してください。'True'が返された場合、PyTorchはCUDAを使用するように設定されています。
• 環境の有効化: 必要なパッケージがすべてインストールされている正しい環境を使用していることを確認してください。
• パッケージの更新: 古いパッケージはGPUと互換性がない場合があります。パッケージを最新の状態に保ってください。
• プログラムの設定: コードでGPUの使用が指定されているか確認してください。トレーニングまたは予測の実行時にdevice引数を設定できます（例: device=0）。

import torch

cap = torch.cuda.get_device_capability(0) if torch.cuda.is_available() else (0, 0)
cudnn = torch.backends.cudnn.version() or 0
ok = "not compatible" if cudnn >= 91100 and (cap[0] < 7 or (cap[0] == 7 and cap[1] < 5)) else "should be ok"
print(f"Compute capability: SM {cap[0]}.{cap[1]}, cuDNN: {cudnn} => {ok}")

モデルのトレーニングに関する問題#

よくあるトレーニングの問題と解決策を以下に示します。

設定の確認#

問題: モデルトレーニング中に.yamlファイルの設定が正しく適用されているか分かりません。

解決策: データセット設定とトレーニング設定は別々の.yamlファイルに記述され、model.train()の異なる引数を通じて渡されます。これらの設定が正しく適用されるよう、次の手順に従ってください。

• .yamlファイルへのパスが正しいことを確認してください。

• データセットの.yaml（パス、クラス名、分割）をdata引数として渡し、カスタムのトレーニング設定.yaml（例: epochsまたはlr0）をcfg引数として渡します。model.train()に直接渡された引数は、両方より優先されます。

  model.train(data="/path/to/your/data.yaml", cfg="/path/to/your/cfg.yaml", batch=4)

複数のGPUを使ったトレーニングの高速化#

問題: 1台のGPUではトレーニングに時間がかかるため、複数のGPUを使って処理を高速化したいと考えています。

解決策: バッチサイズを増やすとトレーニングを高速化できますが、GPUメモリ容量を考慮する必要があります。複数のGPUでトレーニングを高速化するには、次の手順に従ってください。

• 複数のGPUが使用可能であることを確認してください。

• device引数にGPUインデックスのリストを設定します（例: device=[0,1,2,3]）。

• メモリ上限を超えずに複数のGPUを最大限に活用できるよう、バッチサイズを適切に増やしてください。

• 複数のGPUを使用するようにトレーニングコマンドを変更してください。

  # トレーニング速度を最適化するため、必要に応じてバッチサイズやその他の設定を調整してください
  model.train(data="/path/to/your/data.yaml", batch=32, device=[0, 1, 2, 3])

継続的に監視するパラメーター#

問題: 損失以外に、トレーニング中に継続的に監視すべきパラメーターを知りたいと考えています。

解決策: 損失は監視すべき重要なメトリクスですが、モデルの性能を最適化するには、ほかのメトリクスも追跡することが重要です。トレーニング中に監視すべき主なメトリクスには、次のものがあります。

• 適合率
• 再現率
• 平均適合率（mAP）

これらのメトリクスは、トレーニングログから確認するか、TensorBoardやWeights & Biasesなどのツールを使って可視化できます。これらのメトリクスに基づいて早期停止を実装すると、より良い結果につながります。

トレーニングの進捗を追跡するツール#

問題: トレーニングの進捗を追跡するツールの推奨事項を探しています。

解決策: トレーニングの進捗を追跡して可視化するには、次のツールの使用を検討できます。

• TensorBoard: TensorBoardは、損失や精度などのトレーニングメトリクスを可視化するための人気の高いツールです。YOLO26のトレーニングプロセスに統合できます。
• Comet: Cometは、実験の追跡や比較に役立つ包括的なツールキットを提供します。メトリクス、ハイパーパラメーター、さらにはモデルの重みも追跡できます。YOLOモデルとの統合も簡単で、実験サイクル全体を把握できます。
• Ultralytics Platform: Ultralytics Platformは、YOLOモデルの追跡に特化した環境を提供し、メトリクス、データセット、チームとの共同作業を一元管理できます。YOLOに特化しているため、よりカスタマイズされた追跡オプションを利用できます。

GPUでトレーニングが行われているか確認する方法#

問題: トレーニングログの「device」の値が「null」で、GPUでトレーニングが行われているか分かりません。

解決策: 通常、「device」の値が「null」の場合、トレーニングプロセスが使用可能なGPUを自動的に選択するよう設定されています。これはデフォルトの動作です。特定のGPUでトレーニングするには、トレーニングの開始時にdevice引数を設定します。deviceはトレーニング引数であるため、データセットの.yamlに設定しても効果はありません。

from ultralytics import YOLO

# モデルを読み込む
model = YOLO("yolo26n.pt")

# GPU 0を使用します。複数のGPUにはdevice=[0, 1]を、CPUにはdevice="cpu"を指定します
model.train(data="path/to/data.yaml", device=0)

トレーニングの進捗を効果的に監視するため、'runs'フォルダーのログとメトリクスを確認してください。

効果的なモデルのトレーニングで考慮すべきポイント#

モデルのトレーニングに関する問題が発生した場合は、次の点に留意してください。

データセットの形式とラベル

• 重要性: どの機械学習モデルも、トレーニングに使用するデータの品質と形式が基盤となります。
• 推奨事項: カスタムデータセットと関連するラベルが、想定される形式に準拠していることを確認してください。アノテーションが正確で高品質であることを検証することが重要です。不正確なアノテーションや品質の低いアノテーションは、モデルの学習プロセスを妨げ、予測不能な結果につながる可能性があります。

モデルの収束

• 重要性: モデルが収束すると、トレーニングデータから十分に学習したことを確認できます。
• 推奨事項: モデルを「スクラッチから」トレーニングする場合は、モデルが十分に収束するようにすることが重要です。既存モデルをファインチューニングする場合よりも長いトレーニング時間と多くのエポックが必要になることがあります。

学習率とバッチサイズ

• 重要性: これらのハイパーパラメーターは、トレーニング中にモデルの重みをどのように更新するかを決めるうえで重要な役割を果たします。
• 推奨事項: 選択した学習率とバッチサイズが、対象のデータセットに適しているか定期的に評価してください。データセットの特性に合わないパラメーターは、モデルの性能を妨げる可能性があります。

クラス分布

• 重要性: データセット内のクラス分布は、モデルの予測傾向に影響する可能性があります。
• 推奨事項: データセット内のクラス分布を定期的に評価してください。クラスに偏りがある場合、モデルが出現頻度の高いクラスに偏るおそれがあります。この偏りは混同行列にも表れ、モデルが多数派クラスばかりを予測することがあります。

事前学習済み重みとの相互確認

• 重要性: 事前学習済みの重みを活用すると、特にデータが限られている場合に、モデルのトレーニングを確かな出発点から始められます。
• 推奨事項: 診断の一環として、同じデータを使用しながら、事前学習済みの重みで初期化してモデルをトレーニングすることを検討してください。この方法で適切な混同行列が得られれば、「スクラッチから」トレーニングしたモデルには、追加のトレーニングや調整が必要である可能性があります。

モデルの予測に関する問題#

ここでは、モデルの予測時によく発生する問題とその解決策を紹介します。

カスタムYOLO26モデルでバウンディングボックスの予測結果を取得する#

問題: カスタムYOLO26モデルで予測を実行すると、バウンディングボックスの座標の形式や可視化に関する問題が発生します。

解決策:

• 座標の形式: YOLO26はバウンディングボックスの座標を絶対ピクセル値で出力します。これらを相対座標（0～1の範囲）に変換するには、画像の寸法で割る必要があります。たとえば、画像サイズが640x640の場合、次のようにします。

  # 絶対座標を相対座標に変換します
  x1 = x1 / 640  # x座標を画像の幅で割ります
  x2 = x2 / 640
  y1 = y1 / 640  # y座標を画像の高さで割ります
  y2 = y2 / 640

• ファイル名: 予測対象の画像のファイル名を取得するには、予測ループ内で各結果オブジェクトのpath属性から画像ファイルのパスを読み取ります（例: result.path）。

YOLO26の予測結果でオブジェクトをフィルタリングする#

問題: UltralyticsライブラリでYOLO26を実行する際、予測結果から特定のオブジェクトだけをフィルタリングして表示する方法に問題が生じます。

解決策: 特定のクラスを検出するには、classes引数を使って出力に含めるクラスを指定します。たとえば、車のみを検出する場合（「cars」のクラスインデックスが2であると仮定）：

yolo segment predict model=yolo26n-seg.pt source='path/to/car.mp4' show=True classes=2

YOLO26の適合率指標について#

問題: YOLO26におけるボックス適合率、マスク適合率、混同行列の適合率の違いが分かりにくい。

解決策: ボックス適合率は、IoU（Intersection over Union）を指標として、予測されたバウンディングボックスと実際の正解ボックスとの一致度を測定します。マスク適合率は、ピクセル単位のオブジェクト分類において、予測されたセグメンテーションマスクと正解マスクの一致度を評価します。一方、混同行列の適合率は、すべてのクラスを対象とした全体的な分類精度に焦点を当てており、予測の幾何学的な精度は考慮しません。クラス予測が誤っていても、バウンディングボックスが幾何学的に正確（真陽性）である場合があり、その結果、ボックス適合率と混同行列の適合率に違いが生じる点に注意してください。これらの指標はモデルの性能の異なる側面を評価しており、タスクに応じて異なる評価指標が必要であることを示しています。

YOLO26でオブジェクトの寸法を抽出する#

問題: YOLO26で検出されたオブジェクトの長さと高さを取得するのが難しく、特に画像内に複数のオブジェクトが検出される場合に問題となります。

解決策: バウンディングボックスの寸法を取得するには、まずUltralytics YOLO26モデルを使用して画像内のオブジェクトを予測します。次に、予測結果からバウンディングボックスの幅と高さの情報を抽出します。

from ultralytics import YOLO

# Load a pretrained YOLO26 model
model = YOLO("yolo26n.pt")

# Specify the source image
source = "https://ultralytics.com/images/bus.jpg"

# Make predictions
results = model.predict(source, save=True, imgsz=320, conf=0.25)

# Extract bounding box dimensions
boxes = results[0].boxes.xywh.cpu()
for box in boxes:
    x, y, w, h = box
    print(f"Width of Box: {w}, Height of Box: {h}")

デプロイ時の課題#

GPUデプロイの問題#

問題: マルチGPU環境でモデルをデプロイすると、予期しないメモリ使用量やGPU間での結果の不一致など、予想外の動作が発生することがあります。

解決策: デフォルトのGPU初期化を確認してください。PyTorchなどの一部のフレームワークでは、指定されたGPUに切り替える前に、デフォルトGPUでCUDA操作を初期化することがあります。予期しないデフォルト初期化を回避するには、デプロイ時と予測時にGPUを直接指定します。その後、ツールを使ってGPU使用率とメモリ使用量を監視し、異常をリアルタイムで特定します。また、フレームワークまたはライブラリの最新バージョンを使用していることを確認してください。

モデルの変換・エクスポートに関する問題#

問題: 機械学習モデルを異なる形式やプラットフォームに変換またはエクスポートする過程で、エラーや予期しない動作が発生することがあります。

解決策: エクスポートモードのドキュメントで、サポートされている形式と形式ごとのオプションを確認してから、次の項目を確認してください。

• 互換性の確認: 相互に互換性のあるバージョンのライブラリとフレームワークを使用していることを確認してください。バージョンが一致していないと、変換中に予期しないエラーが発生することがあります。
• 環境のリセット: JupyterやColabなどのインタラクティブ環境を使用している場合、大幅な変更やインストールを行った後に環境を再起動することを検討してください。環境を再起動すると、根本的な問題が解決する場合があります。
• 公式ドキュメント: 変換に使用するツールまたはライブラリの公式ドキュメントを必ず参照してください。モデルのエクスポートに関する具体的なガイドラインやベストプラクティスが記載されていることがよくあります。
• コミュニティのサポート: 他のユーザーが同様の問題を報告していないか、ライブラリまたはフレームワークの公式リポジトリを確認してください。メンテナーやコミュニティが、ディスカッションスレッドで解決策や回避策を提示している場合があります。
• 定期的な更新: ツールまたはライブラリの最新バージョンを使用していることを確認してください。開発者は既知のバグを修正したり、機能を改善したりする更新を頻繁にリリースしています。
• 段階的なテスト: 変換をすべて実行する前に、小規模なモデルまたはデータセットでプロセスをテストし、潜在的な問題を早期に特定してください。

コミュニティとサポート#

以下のチャンネルやリソースを通じて、サポートを受けたり解決策を共有したりできます。

サポートを受けられるフォーラムとチャンネル#

GitHub Issues: GitHub上のUltralyticsリポジトリにはIssuesタブがあり、質問、バグ報告、新機能の提案ができます。コミュニティとメンテナーが活発に活動しており、具体的な問題についてサポートを得るのに最適な場所です。

Ultralytics Discordサーバー: UltralyticsにはDiscordサーバーがあり、ほかのユーザーや開発者と交流できます。

公式ドキュメントとリソース#

Ultralytics YOLO26 Docs: 公式ドキュメントでは、YOLO26の概要に加えて、インストール、使用方法、トラブルシューティングに関するガイドを提供しています。

結論#

YOLO26の問題の多くは、バージョンの不一致、データセットの形式、GPUの設定という、いくつかの原因に起因します。ここで取り上げていないエラーが発生した場合は、GitHub Issuesタブを検索するか、Discord serverで質問してください。すでに誰かが解決している可能性があります。より詳細なトレーニングの問題については、モデルのトレーニングに関するヒントガイドを参照し、コンピュータービジョンプロジェクトでより良い結果を得るための実践的なアドバイスをご確認ください。

よくある質問#