はじめる

Ultralytics YOLOモデルのST Edge AIエクスポート

Ultralytics YOLOモデルをformat="stedgeai"でエクスポートすると、STM32マイクロコントローラー(Neural-ARTアクセラレーターを搭載したSTM32N6を含む)向けにニューラルネットワークをコンパイルするSTMicroelectronicsのツールチェーン、ST Edge AI Coreに適した形状のONNXモデルが生成されます。エクスポートでは、デフォルトでFloatモデルと、quantize=8を使用した完全量子化INT8モデルが書き出されます。Ultralyticsはyolo predictとyolo valを使って、どちらのファイルもコンピューター上で実行できるため、デバイス向けにコンパイルする前に精度を測定できます。

ホスト上で検証済み

Ultralyticsはコンピューター上でONNX Runtimeを使ってこれらのモデルを検証しており、STMicroelectronicsはST Edge AI Coreを使って、7つすべてのタスクのINT8エクスポートをSTM32N6向けにコンパイルしました。STM32ボード上で精度、レイテンシ、メモリを測定する作業は、STツールを使って行います。STM32へのデプロイを参照してください。

専用のST Edge AI形式を使用する理由#

マイクロコントローラーではINT8モデルが実行されますが、標準のONNXエクスポートはエンドツーエンドで適切に量子化できません。

  • 1つの出力内に混在する値の範囲。 YOLOの検出ヘッドは、ピクセル単位のボックス座標(約0~640)とクラススコア(0~1)を1つのテンソルにまとめます。INT8量子化では、このテンソルに1つのスケールが適用されるため、スコアの解像度がほぼ失われます。ST Edge AIエクスポートでは、ボックスとキーポイントの座標を入力サイズで割った[0, 1]に正規化します。これはUltralyticsがEdge TPU向けに使用する正規化と同じで、グラフ全体を量子化できます。
  • 大きく高密度な出力。 セマンティックセグメンテーションモデルと深度モデルは通常、グラフ内で入力解像度までアップサンプリングします。ST Edge AIエクスポートはアップサンプリングの前に処理を止めるため、セマンティックセグメンテーションの出力バッファーは64分の1、深度の出力バッファーは16分の1になります。また、深度はINT8の各レベルが均等に分布する対数領域で保持されます。
  • グラフ内の後処理。 組み込みNMSとYOLO26のNMSフリーヘッドは、ヘッドの後にTopKおよびgatherオペレーターを追加します。エクスポートではこれらを含めず、常に生の予測値を返すため、NMSはアプリケーションで実行します。

代わりに標準的なレイアウト(ピクセル座標、フル解像度マップ、オプションの組み込みNMS)が必要な場合は、ONNXエクスポートを使用してください。

対応タスク#

すべてのUltralytics YOLOタスクはエクスポートしてホスト上で実行できます。出力形状はimgsz=640向けです。

タスク出力
物体検出[1, 4 + nc, 8400]:[0, 1]に正規化されたボックス、クラススコア
インスタンスセグメンテーション[1, 4 + nc + 32, 8400](ボックスは[0, 1]に正規化)、およびマスクプロトタイプ[1, 32, 160, 160]
セマンティックセグメンテーション1/8解像度のクラスロジット[1, nc, 80, 80]。アップサンプリング後、ピクセルごとのargmaxを取得します
深度推定1/4解像度の対数深度[1, 1, 160, 160]。メートル単位の深度を得るためにexp(x)を適用し、その後アップサンプリングします
分類クラス確率[1, nc]
姿勢推定[1, 4 + nc + nk, 8400]:ボックスとキーポイントは[0, 1]に正規化されています
方向付き物体検出[1, 4 + nc + 1, 8400]:ボックスは[0, 1]に正規化され、角度はラジアン単位です。正方形のimgszが必要です

RT-DETRおよびYOLO-NASモデルはサポートされていません。

使用方法#

エクスポート
from ultralytics import YOLO

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

# Floatモデルをエクスポート
model.export(format="stedgeai")  # 「yolo26n_stedgeai.onnx」を作成します

# COCO8でキャリブレーションしたINT8モデルをエクスポート
model.export(format="stedgeai", quantize=8, data="coco8.yaml")  # 「yolo26n_int8_stedgeai.onnx」を作成します
ホスト上で予測と検証を行う
from ultralytics import YOLO

# エクスポートしたST Edge AIモデルを読み込みます
model = YOLO("yolo26n_int8_stedgeai.onnx")

# 推論を実行
results = model("https://ultralytics.com/images/bus.jpg")

# COCO8データセットでINT8の精度を測定します
metrics = model.val(data="coco8.yaml")

各エクスポートで1つのファイルが書き出されます。Ultralyticsは_stedgeai.onnxという末尾でST Edge AIモデルを識別し、座標をピクセル単位に戻し、セマンティックマップと深度マップをアップサンプリングして、対数深度をメートル単位の深度に変換します。ファイル名を変更するときも、この末尾を維持してください。通常の.onnxという名前では標準のONNXモデルとして読み込まれ、ボックスは[0, 1]で返されます。

エクスポート引数#

引数種類デフォルト説明
formatstr'stedgeai'エクスポートするモデルのターゲット形式です。
imgszintまたはtuple640モデルの入力サイズです。正方形画像の場合は整数、または(height, width)タプルを指定します。モデルのバッチサイズは1に固定され、形状は静的です。OBBモデルには正方形のimgszが必要です。
quantizeintまたはstrNone精度です。未設定または32の場合はFloatモデルを書き出し、8の場合はINT8モデルを書き出します。
datastrNoneINT8キャリブレーションに使用するデータセットです。データセットYAML、データセットディレクトリ、または分類用の組み込みデータセット名を指定します。指定しない場合、quantize=8はタスクのデフォルトデータセットを使用します。たとえば、検出ではcoco8.yamlを使用します。
fractionfloat1.0使用するキャリブレーションデータセットの割合です。
opsetintNoneONNX opsetです。PyTorchのバージョンで安定してエクスポートできる最新のopsetがデフォルトで使用されます。
simplifyboolTrueonnxslimを使用してONNXグラフを簡略化します。
devicestrNoneエクスポートに使用するデバイスです。GPU(device=0)またはCPU(device=cpu)を指定します。

batchとdynamic=Trueは拒否され、nms=Trueは警告を出して生の出力にフォールバックします。

INT8量子化#

quantize=8を指定すると、UltralyticsはONNX Runtimeの静的量子化を使ってモデルを量子化します。これは、ST Edge AI Coreが推奨し、STM32 AI Model Zoo Servicesが適用する方式です。

  • Float形式のモデル入力と出力を使用するQDQ(QuantizeLinear/DequantizeLinear)形式です。
  • 符号付き対称per-channel INT8重みと、符号付き非対称INT8アクティベーションです。
  • data枚の画像を対象にしたMinMaxキャリブレーションです。画像はUltralyticsの検証時とまったく同じ方法で前処理されます。

ヘッドをFloatのままにする標準のONNX quantize=8エクスポートとは異なり、すべてのオペレーターが量子化されます。代わりにSTツールで量子化する場合は、Floatモデルをエクスポートし、STM32 AI Model Zoo Servicesに渡してください。

独自のデータでキャリブレーションする

INT8の精度は、キャリブレーション画像がデプロイ先のシーンにどれだけ合致しているかによって変わります。data=に代表的な画像を少なくとも300枚含むデータセットを渡してください。デフォルトのキャリブレーションデータセットに含まれる公開サンプルは数枚のみです。

以下の表では、各モデルのデフォルトのimgsz(640、セマンティックセグメンテーションは1024、深度は768)でのYOLO26nを、小規模なデフォルト検証データセット上で比較しています。キャリブレーションには同じ画像を使用しました。各データセットの画像は4~8枚のため、数値はINT8の影響を受けやすいタスクを示す目安として捉え、yolo valを使って独自のモデルを測定してください。

タスク指標ONNX FloatST Edge AI FloatST Edge AI INT8
DetectmAP50-950.6860.6860.639
Segmentボックス/マスク mAP50-950.638 / 0.5400.638 / 0.5400.356 / 0.401
セマンティックmIoU0.6100.6100.609
深度delta10.8520.8520.840
姿勢推定ボックス/ポーズ mAP50-950.697 / 0.4590.697 / 0.4590.650 / 0.267
OBBmAP50-950.8940.8940.806

Floatエクスポートは、すべてのタスクで標準のONNXエクスポートと一致します。インスタンスセグメンテーションとポーズは、グラフ全体をINT8量子化した場合に精度が最も低下します。これは、マスク係数とキーポイントがボックスと1つの出力スケールを共有するためです。デプロイ前に、これら2つのタスクを独自のデータで慎重に検証してください。

STM32へのデプロイ#

  1. デバイス上で実行するimgszを指定して、format="stedgeai"でモデルをエクスポートします。

  2. yolo valを使い、データセット上でFloatモデルとINT8モデルを検証します。

  3. ST Edge AI Coreでモデルをコンパイルします。以下のコマンドは、ST Edge AI CoreのコマンドラインドキュメントとNeural-ART入門ガイドに沿っています。メモリプロファイルと入力オプションについては、各ドキュメントを参照してください。

    # Report the model's memory and operator usage for an STM32 target
    stedgeai analyze -m yolo26n_int8_stedgeai.onnx --target stm32
    
    # Generate the C model for an STM32N6 with the Neural-ART accelerator
    stedgeai generate -m yolo26n_int8_stedgeai.onnx --target stm32n6 --st-neural-art
  4. 生成されたモデルをSTM32アプリケーションにデプロイします。STM32 AI Model Zoo Servicesでは、STM32N6上でUltralytics YOLOモデルを使用するためのアプリケーションコードとチュートリアルを提供しています。

出力には後処理が必要です

デバイス上のCによる後処理など、Ultralytics以外でエクスポート済みモデルを読み込むコードでは、ボックスとキーポイントのxおよびwの値に入力幅を掛け、yおよびhの値に入力高さを掛ける必要があります。また、NMSを実行し、argmaxの前にセマンティックロジットをアップサンプリングして、深度出力にexpを適用してからアップサンプリングしてください。トレーニング、エクスポート、デプロイの間でimgszを同一に保ってください。

よくある質問#

  • yolo export model=yolo26n.pt format=stedgeai quantize=8 data=coco8.yamlを実行してINT8モデルyolo26n_int8_stedgeai.onnxを書き出すか、quantize=8を省略してFloatモデルyolo26n_stedgeai.onnxを書き出します。その後、STM32へのデプロイに示すように、ST Edge AI Coreでファイルをコンパイルしてください。

  • ST Edge AIエクスポートでは、ボックスとキーポイントの座標を入力サイズで割って正規化します。これにより、クラススコアと同じ[0, 1]の範囲になり、グラフ全体をINT8に量子化できます。ピクセル座標に戻すには、xとwに入力幅を掛け、yとhに入力高さを掛けます。Ultralyticsは_stedgeai.onnxモデルを読み込むときに、この処理を自動で行います。

  • いいえ。エクスポートは常に生の予測値を返すため、アプリケーションでNMSを実行するか、STM32 AI Model Zoo Servicesの後処理を使用してください。

  • 標準のONNXエクスポートは、ピクセル座標とフル解像度のセマンティックマップおよび深度マップを返し、NMSを埋め込むことができます。また、quantize=8を指定すると、畳み込み層と行列乗算層のみを量子化します。ST Edge AIエクスポートは、正規化された座標、低解像度のセマンティックロジットと対数深度を返し、バッチサイズは1に固定され、NMSは埋め込みません。また、quantize=8を指定すると、グラフ全体を量子化します。

  • はい。yolo val model=yolo26n_int8_stedgeai.onnx data=coco8.yamlはコンピューター上でONNX Runtimeを使って量子化モデルを実行し、他のUltralyticsモデルと同じ指標を報告します。デバイス上の精度はわずかに異なる場合があるため、コンパイル後にSTツールで確認してください。

コントリビューター

コメント

質問したり、結果を共有したり、ほかの人をサポートしたりできます。