すべての記事

RT-DETRをUltralyticsなしで使う方法：v1・v2・v4、Apache-2.0対応

Xuban

RT-DETRはBaiduが開発したリアルタイム物体検出トランスフォーマーです。密なグリッドではなく固定数のクエリをデコードするため、調整が必要なNMS処理がありません。検索すると、最初に見つかる実装の1つはPythonパッケージultralyticsに含まれるものです。ここで、モデル自体にはなかったライセンスの疑問が生じます。

RT-DETRのライセンスはリポジトリによって異なります

ライセンスが適用されるのはモデルではなく、リポジトリです。RT-DETRには複数のリポジトリがあり、ライセンスはそれぞれ異なります。

リポジトリ対象ライセンス
lyuwenyu/RT-DETRRT-DETRとRT-DETRv2、PyTorchとPaddleApache-2.0
RT-DETRs/RT-DETRv4RT-DETRv4Apache-2.0
ultralytics/ultralyticsultralyticsパッケージ内のRT-DETRAGPL-3.0またはEnterprise License
LibreYOLORT-DETR、RT-DETRv2、RT-DETRv4MITライセンスのコード、Apache-2.0の重み

Ultralyticsの実装は優れています。RT-DETRのページには、学習、検証、推論、エクスポートに対応する学習済みのrtdetr-l.ptとrtdetr-x.ptが掲載されています。AGPL-3.0ライセンスのパッケージに含まれており、プロジェクト全体をオープンソースにしたくないチーム向けに、UltralyticsはEnterprise Licenseを販売しています。どちらも適さない場合は、アーキテクチャの作者が公開しているApache-2.0版を利用できます。YOLOのライセンス解説ではYOLOファミリー全体の同じパターンを説明し、商用ライセンスガイドではクローズドソース製品にとってAGPL-3.0が何を意味するかを説明しています。

LibreYOLOでRT-DETRを実行する

pip install libreyolo

from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreRTDETRr18.pt")  # downloads from Hugging Face on first use
result = model(SAMPLE_IMAGE, save=True)

for box in result.boxes:
    print(box.cls, box.conf, box.xyxy)

コマンドラインでも同じ呼び出し方ができます。

libreyolo predict model=LibreRTDETRr18.pt source=image.jpg save=True

confとmax_detは、クエリとクラスに対するtop-kデコードの結果をフィルタリングします。NMSがないため、iouは受け付けますが使用されません。返されるResultsオブジェクトはすべてのLibreYOLOモデルで共通なので、検出器は1行の変更で切り替えられます。

RT-DETR、RT-DETRv2、RT-DETRv4を1つのローダーで使う

バージョンはファイル名に含まれ、LibreYOLO()はチェックポイントに応じて処理を振り分けるため、3つのバージョンを同じ方法で読み込めます。

  • RT-DETR： LibreRTDETRはr18、r34、r50、r50m、r101（ResNetバックボーン）、l、x（HGNetv2）に対応します。
  • RT-DETRv2： LibreRTDETRv2はr18、r34、r50、r50m、r101に対応します。バージョン1のアーキテクチャを維持し、変形可能アテンションのサンプリング方法を変更しています。
  • RT-DETRv4： LibreRTDETRv4はs、m、l、xに対応します。D-FINEのアーキテクチャを再利用し、DINOv3の教師モデルからHGNetv2の生徒モデルへ知識蒸留した重みを使います。

すべての検出用重みはCOCOで学習され、640 pxで動作します。参考値として、上流のREADMEではCOCOでRT-DETR-R18が46.5 AP、RT-DETR-Lが53.0 AP、RT-DETRv4-Sが49.8 AP、RT-DETRv4-Xが最大57.0 APと報告されています。RT-DETRのドキュメントページには、すべてのチェックポイントについてLibreYOLO独自のベンチマーク表があります。

RT-DETRv2は回転ボックスにも対応します。LibreRTDETRv2n-obb.ptからLibreRTDETRv2x-obb.ptまでのモデルは、公式のDOTA v1.0チェックポイントをLibreYOLO形式に変換したもので、1024 pxで15種類の航空画像クラスを扱います。

from libreyolo import LibreYOLO

model = LibreYOLO("LibreRTDETRv2n-obb.pt")
result = model("aerial.png", save=True)
print(result.obb.xywhr)  # (N, 5): cx, cy, w, h, radians

回転物体検出では、ラベル形式と評価指標を説明しています。

独自データでRT-DETRをファインチューニングする

学習は公開済みチェックポイントから始めます。

from libreyolo import LibreYOLO

model = LibreYOLO("LibreRTDETRr18.pt")
model.train(data="coco128.yaml", epochs=50, batch=4, lr0=1e-4)

実際に学習する場合は、dataに独自データセットのYAMLファイルを指定します。各バージョンにはそれぞれの学習率のデフォルト値があり、バージョン1と2では元のレシピに従い、バックボーンの学習率をlr0の20分の1に設定します。CLIでのマルチGPU実行にはdevice=0,1を指定します。また、lora追加パッケージをインストールしてlora=Trueにすると、LoRAアダプターでファインチューニングできます。RT-DETRv2の回転ボックスモデルは推論専用です。データセット、拡張、ロガーについては学習を参照してください。

検証とエクスポート

metrics = model.val(data="coco128.yaml")
print(metrics["metrics/mAP50-95"])

path = model.export(format="onnx")  # needs: pip install "libreyolo[onnx]"

val()は通常の辞書を返します。エクスポート先にはONNX、TorchScript、ExecuTorch、TensorRT、OpenVINOがあります。モデルページのエクスポート対応表では、タスクごとに検証済みの形式を確認できます。エクスポートした.onnxまたは.engineファイルをLibreYOLO()で再読み込みすると、同じResultsが返されます。形式ごとのガイドはエクスポートを参照してください。

元のリポジトリを使うのが適切な場合

論文の結果を作者の設定そのままで再現したい場合、Paddle版が必要な場合、またはRT-DETRv4のDINOv3教師モデルによる蒸留を自分で実行したい場合は、上流のリポジトリを使ってください。LibreYOLOでファインチューニングできるのは公開済みのv4生徒モデルであり、教師モデルは実行しません。また、すでにプロジェクトがAGPL-3.0の対象である場合や、Ultralytics Enterprise Licenseの適用を受けている場合、ライセンス上の理由で移行する必要はありません。

ライセンスについて

LibreYOLOのコードはMITです。すべてのRT-DETR重みファイルはApache-2.0で、各Hugging Face重みリポジトリには、重みを再配布するときに保持するようApache-2.0が求める上流のLICENSEとNOTICEが含まれています。独自データで学習した重みは利用者のものです。RT-DETRv4は学習時の教師モデルとしてのみDINOv3を使い、公開された生徒モデルにDINOv3のパラメーターは含まれません。これは一般的な情報であり、法的助言ではありません。公開前に最新のLICENSEファイルを確認してください。

試してみる

pip install libreyolo

from libreyolo import LibreYOLO

model = LibreYOLO("LibreRTDETRv4s.pt")
result = model("image.jpg", save=True)
print(result.boxes.xyxy)

LibreYOLOはMITライセンスで、Linux、Mac、Windows上で動作します。GPU、Apple Silicon、通常のCPUのいずれでもコードを変更せずに使えます。

GitHub | RT-DETRのドキュメント