YOLOの一般的な問題のトラブルシューティング#

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

よくある問題#

インストールエラー#

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

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

さらに、一般的なインストール問題の解決策を以下に示します。

Importエラーまたは依存関係の問題#

YOLO26のimport時にエラーが発生する場合や、依存関係の競合が発生した場合は、次の手順を試してください。

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

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設定ファイルへのパスが正しいことを確認してください。

• 以下に示すように、model.train()を呼び出す際、.yamlファイルへのパスをdata引数として渡してください。

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

複数のGPUによるトレーニングの高速化#

問題：1つのGPUではトレーニングが遅いため、複数のGPUを使用して処理を高速化したいと考えています。

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

• 複数のGPUを利用できることを確認してください。

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

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

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

  # Adjust the batch size and other settings as needed to optimize training speed
  model.train(data="/path/to/your/data.yaml", batch=32, device=[0, 1, 2, 3])

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

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

解決策：損失は監視すべき重要な指標ですが、モデルのパフォーマンスを最適化するには、他の指標も追跡することが重要です。トレーニング中に監視すべき主な指標には、次のようなものがあります。

• Precision
• Recall
• 平均適合率 (mAP)

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

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

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

解決策：トレーニングの進捗を追跡および可視化するには、次のツールの使用を検討してください。

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

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

問題：トレーニングログの「device」の値が「null」になっており、トレーニングがGPU上で実行されているか不明です。

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

from ultralytics import YOLO

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

# Use GPU 0; device=[0, 1] for multiple GPUs, device="cpu" for CPU
model.train(data="path/to/data.yaml", device=0)

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

効果的なモデルのトレーニングに関する主な考慮事項#

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

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

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

モデルの収束

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

学習率とバッチサイズ

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

クラス分布

• 重要性：データセット内のクラス分布は、モデルの予測傾向に影響を与える可能性があります。
• 推奨事項：データセット内のクラス分布を定期的に評価してください。クラスの不均衡がある場合、モデルが出現数の多いクラスに偏るリスクがあります。この偏りは混同行列に現れることがあり、モデルが大多数のクラスを主に予測する可能性があります。

事前学習済みの重みとのクロスチェック

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

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

モデルの予測中に発生しやすい問題とその解決策を以下に示します。

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

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

解決策：

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

  # Convert absolute coordinates to relative coordinates
  x1 = x1 / 640  # Divide x-coordinates by image width
  x2 = x2 / 640
  y1 = y1 / 640  # Divide y-coordinates by image height
  y2 = y2 / 640

• ファイル名：予測対象画像のファイル名を取得するには、予測ループ内のresultオブジェクトから画像ファイルパスに直接アクセスしてください。

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（積集合と和集合の比率）を指標として、予測されたバウンディングボックスと実際のグラウンドトゥルースボックスの一致度を測定します。マスク精度は、ピクセル単位のオブジェクト分類において、予測されたセグメンテーションマスクとグラウンドトゥルースマスクの一致度を評価します。一方、混同行列の精度は、すべてのクラスにわたる全体的な分類精度に焦点を当て、予測の幾何学的な精度は考慮しません。バウンディングボックスは、クラス予測が誤っていても幾何学的には正確（真陽性）である場合があり、その結果、ボックス精度と混同行列の精度に差が生じます。これらの指標はモデルのパフォーマンスの異なる側面を評価するものであり、タスクごとに異なる評価指標が必要であることを示しています。

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使用率とメモリ使用量を監視し、異常をリアルタイムで特定してください。また、フレームワークまたはライブラリの最新バージョンを使用していることを確認してください。

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

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

解決策： Exportモードのドキュメントで対応形式と形式ごとのオプションを確認し、次の項目を順に確認してください。

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

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

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

サポートを受けるためのフォーラムとチャンネル#

GitHub Issues: Ultralytics の GitHub リポジトリには、質問、バグ報告、新機能の提案を行えるIssues タブがあります。コミュニティとメンテナーがここで活発に活動しており、特定の問題に対するヘルプを得るのに最適な場所です。

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

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

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

まとめ#

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

FAQ#