RT-DETR

インストール

RT-DETRにオプションの追加パッケージは不要です。インポートするものはすべて基本インストールに含まれ、rtdetr追加パッケージは何も追加しない安定した名前として用意されています。

pip install libreyolo

lora=Trueによるアダプターのファインチューニングは例外で、lora追加パッケージが必要です。

pip install "libreyolo[lora]"

推論

重みは初回使用時にHugging Faceからダウンロードされ、ローカルにキャッシュされます。

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreRTDETRr18.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(box.cls, box.conf, box.xyxy)

libreyolo predict model=LibreRTDETRr18.pt save=True \  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg

from libreyolo import LibreYOLO # バージョンはファイル名の一部でファクトリーはチェックポイントに基づき# 振り分けるため3つすべて同じ方法で読み込むmodel = LibreYOLO("LibreRTDETRv4s.pt") # ライブラリが受け付ける任意のソース: ファイル フォルダー URL Webカメラ番号# RTSP ストリーム または .streams リストfor result in model.predict("clip.mp4", stream=True, save=True):    print(len(result.boxes))

from libreyolo import LibreYOLO # バージョン2のみ -obb サフィックスでタスクを選択しチェックポイント自体の# テンソルから回転ありと認識するため task 引数は不要# この重みは DOTA v1.0 の15航空クラス向けで 1024 pxmodel = LibreYOLO("LibreRTDETRv2n-obb.pt")result = model("aerial.png", save=True) obb = result.obbprint(obb.xywhr)     # (N, 5): cx cy w h ラジアンprint(obb.xyxyxyxy)  # 同じ行を4つのコーナーポイントとして表示print(result.boxes.xyxy)  # 外接する軸平行ボックス

libreyolo predict model=LibreRTDETRv2n-obb.pt source=aerial.png save=True

返されるResultsオブジェクトはすべてのファミリーに共通するため、別の検出器への切り替えは1行の変更で済みます。confとmax_detはクエリとクラスに対する上位k件のデコードをフィルタリングします。調整するNMSステップはなく、iouは受け付けられますが使用されません。回転ありのチェックポイントはresult.obbを直接埋め、外接する軸平行長方形でresult.boxesも埋めます。ソース、ストリーミング、結果の処理については推論を参照してください。

バリアント

3つのバージョンに2つのタスクがあり、サイズコードは単一の系列ではありません。バージョン1はResNetまたはHGNetv2というバックボーン名に基づいてサイズを命名します。バージョン2はResNetの名前だけを再利用します。バージョン1がすでに2つのHGNetv2サイズを提供し、そこでのバージョン2の結果は非常に近いため、LibreYOLOは重複する重みを公開していません。バージョン4は単純な文字系列を使用し、バージョン1のHGNetv2名と衝突します。そのため、サイズコードだけではモデルを特定できません。バージョンはチェックポイントのファイル名に記載されます。

バージョン2はバージョン1のアーキテクチャとstate dictの構成を維持し、変形可能アテンションのサンプリング方法を変更します。そのため、2つは形状ではなくチェックポイント内のメタデータで区別されます。バージョン4は異なる系統です。D-FINEのアーキテクチャとトレーナーを再利用し、DINOv3の視覚基盤モデルの教師からHGNetv2の生徒へ蒸留した重みを使います。LibreYOLOでは、LibreRTDETRv4はマスクヘッドを無効に固定したLibreDFINEのサブクラスなので、検出専用のままです。

バージョン2の回転バウンディングボックス

バージョン2は2つ目のタスクを持つ唯一のバージョンです。サポートするタスクはdetectとobbで、2つはグラフもサイズ系列も共有しません。検出は640 pxのResNetサイズを使い、回転あり検出は1024 pxでHGNetv2のn、s、m、l、x系列を使います。入力サイズはファミリー単位ではなくタスク単位で解決されます。チェックポイントは、5座標のボックスヘッドとバージョン2のサンプリングパラメータという自身のテンソルから回転ありと認識されます。そのため、-obbの重みはtask引数なしで回転ありのグラフに読み込まれ、2つが一致しない場合は暗黙に再解釈されず、明確なエラーになります。

公開済みファイルはLibreRTDETRv2n-obb.ptからLibreRTDETRv2x-obb.ptまでです。公式のDOTA v1.0シングルスケールチェックポイントをLibreYOLO形式に変換したもので、planeやshipからharbor、helicopterまで15の航空クラスを扱い、クラス名はチェックポイントに記録されています。検出側と異なり、回転ありのタスクは推論専用です。推論、検証、エクスポートは動作しますが、回転ありのモデルでtrain()を呼び出すと例外が発生します。トラッキングとテスト時拡張も回転バウンディングボックスをサポートしません。タスク、ラベル形式、メトリクスについては回転物体検出で説明します。

学習

学習は公開済みチェックポイントから開始します。3つすべてのバージョンでpretrainedは受け付けられた後に破棄されるため、pretrained=Falseを指定してもランダムに初期化されたモデルにはなりません。このセクションの内容はすべて検出に関するものです。バージョン2の回転ありタスクは推論専用で、2つは異なるバックボーンを使うため、検出重みからの転移経路はありません。

from libreyolo import LibreYOLO model = LibreYOLO("LibreRTDETRr18.pt") # coco128.yaml は初回使用時に128枚のサンプルをダウンロード# 実際の実行では data に独自データセットのYAMLを指定model.train(data="coco128.yaml", epochs=50, batch=4, lr0=1e-4)

libreyolo train model=LibreRTDETRr18.pt data=coco128.yaml \  epochs=50 batch=4 lr0=1e-4

# lora 追加パッケージが必要: pip install "libreyolo[lora]"from libreyolo import LibreYOLO model = LibreYOLO("LibreRTDETRr18.pt")model.train(data="coco128.yaml", epochs=50, lora=True)

libreyolo train model=LibreRTDETRr18.pt data=coco128.yaml \  epochs=50 device=0,1

正しく設定すべき引数は学習率で、各バージョンがライブラリ全体の値ではなく固有のデフォルトを持ちます。Pythonのtrain()シグネチャはそのバージョンの学習設定から値を読み取り、lr0を渡さない場合はCLIも同じ値を解決します。バージョン1と2はlr_backboneも受け取り、元のレシピに従ってデフォルトをlr0の20分の1に設定します。バージョン4はD-FINEトレーナーで実行され、代わりにbackbone_lr_multでバックボーンのパラメータグループをスケーリングします。

変更する理由がない限り、imgszはチェックポイントのネイティブサイズのままにしてください。別のサイズでの検証と推論も動作しますが、1つ問題が残ります。トークン数がネイティブサイズと一致する長方形サイズでは、誤ったアスペクト比用に構築された埋め込みベクトルが再利用されます。

データセット、データ拡張、マルチGPU、ロガーについては学習を参照してください。

検証

val()は、学習に使用した形式の任意のデータセットで測定した適合率、再現率、mAP 50、mAP 50-95を含むmetrics/キーの辞書を返します。

from libreyolo import LibreYOLO model = LibreYOLO("LibreRTDETRr18.pt") # val() はオブジェクトではなく通常の辞書を返すmetrics = model.val(data="coco128.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"])print(metrics["metrics/precision"], metrics["metrics/recall"])

libreyolo val model=LibreRTDETRr18.pt data=coco128.yaml

# coco-val-only.yaml は5000枚の val2017 画像を取得し# 学習セットをスキップする ダウンロードスクリプトを内包するため# データセットがローカルにない場合は明示的な許可が必要libreyolo val model=LibreRTDETRr18.pt data=coco-val-only.yaml \  allow_download_scripts=True

from libreyolo import LibreYOLO # 回転ありの検証は回転 IoU で照合するため位置が正しくても# 角度が誤った予測は不一致として扱うmodel = LibreYOLO("LibreRTDETRv2n-obb.pt")metrics = model.val(data="my-obb-dataset.yaml") print(metrics["metrics/mAP50-95(OBB)"])print(metrics["metrics/mAP50(OBB)"])

上記のベンチマーク表の行はLibreYOLOのベンチマークハーネスから取得されています。表の下の注記には、使用したデータセットと実行記録へのリンクが記載されています。

回転ありの検証は同じ呼び出しで実行され、同じキーに加えて、(OBB)サフィックス付きで4つのキーを繰り返し報告します。照合には外接長方形のIoUではなく回転IoUを使うため、角度の誤りは不一致になります。このタスクではaugment=Trueが拒否されます。

エクスポート

このマトリクスは各系統を1ページで扱います。3つのバージョンで形式に対する対応状況が異なる場合、そのセルには最も弱いものが表示されるため、どのバージョンを読み込んでも実際以上の対応を示すことはありません。回転ありの行はバージョン2だけに該当します。ONNXとTorchScriptはFP32、バッチ1、固定の1024 x 1024キャンバスで検証済みです。OpenVINO、TensorRT、ExecuTorchは変換と再読み込みができますが、クエリ集合全体で未加工出力の一致基準を満たしていません。上位のボックスは1 px未満の差で一致する一方、末尾ではずれが生じます。

エクスポートした成果物は、ファイルサフィックスに基づいてLibreYOLO()から再度読み込めます。そのため、.onnxまたは.engineファイルはチェックポイントと同様に動作し、同じResultsを返します。

# onnx 追加パッケージが必要: pip install "libreyolo[onnx]"from libreyolo import LibreYOLO model = LibreYOLO("LibreRTDETRr18.pt")path = model.export(format="onnx")print(path)

libreyolo export model=LibreRTDETRr18.pt format=onnx

# ONNX と TorchScript は回転タスクで検証済みのターゲット# FP32 バッチ1 固定の 1024 x 1024 キャンバスを使用libreyolo export model=LibreRTDETRv2n-obb.pt format=onnx imgsz=1024libreyolo export model=LibreRTDETRv2n-obb.pt format=torchscript imgsz=1024

from libreyolo import LibreYOLO, SAMPLE_IMAGE # ファクトリーはファイルサフィックスで振り分けるためエクスポート成果物も# 任意のチェックポイントと同様に読み込まれ同じ Results オブジェクトを返すmodel = LibreYOLO("LibreRTDETRr18.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)

チェックポイント

このファミリーで公開されているすべての重みファイルです。

ファイル名にはバージョン、サイズ、タスクの順に含まれます。検出重みはLibreRTDETR<size>.pt、LibreRTDETRv2<size>.pt、LibreRTDETRv4<size>.ptで、すべて640 pxです。回転ありの重みはバージョン2だけに存在し、タスクサフィックスが追加されます。LibreRTDETRv2n-obb.ptからLibreRTDETRv2x-obb.ptまでで、すべて1024 px、COCOではなくDOTA v1.0で学習されています。

ライセンス

引用

@misc{lv2023detrs,
      title={DETRs Beat YOLOs on Real-time Object Detection},
      author={Yian Zhao and Wenyu Lv and Shangliang Xu and Jinman Wei and Guanzhong Wang and Qingqing Dang and Yi Liu and Jie Chen},
      year={2023},
      eprint={2304.08069},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
}

@misc{lv2024rtdetrv2improvedbaselinebagoffreebies,
      title={RT-DETRv2: Improved Baseline with Bag-of-Freebies for Real-Time Detection Transformer}, 
      author={Wenyu Lv and Yian Zhao and Qinyao Chang and Kui Huang and Guanzhong Wang and Yi Liu},
      year={2024},
      eprint={2407.17140},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2407.17140}, 
}

上のブロックは、著者がバージョン1と2の検出向けに公開しているものです。バージョン2の回転あり重みには、3つ目のアップストリームがあります。DOTAチェックポイントの取得元であるApache-2.0のRiO-DETRリポジトリgithub.com/RicePasteM/RiO-DETRです。これらのいずれかを使用した場合は、そのプロジェクトを引用してください。バージョン4は別のグループによる別の論文で、github.com/RT-DETRs/RT-DETRv4に専用の引用ブロックがあります。バージョン4のチェックポイントを使用した場合は、そちらを引用してください。