1.7.0へのアップグレード

1.6.0から1.7.0

• 1.7.0で保存したYOLO9、YOLO9-E2E、YOLO9-P2のチェックポイントは新しいテンソル名を使うため、1.6.xでは読み込めません。1.6.xはYOLO9とYOLO9-P2のチェックポイントを欠落キーの警告付きで読み込んでボックスを1つも推論せず、YOLO9-E2Eのチェックポイントにはmodel_familyの不一致エラーを送出します。これらを読み込むすべての環境をアップグレードしてください。以前のリリースが書き出した浮動小数点、量子化済み、学習用のチェックポイントは1.7.0で読み込め、ONNXエクスポートには影響しません。

• YOLO9ファミリーのモデルのmodel.modelに直接アクセスするコードからは、MultimediaTechLab/YOLOのモジュール名がエイリアスなしで見えます。DDetectはYOLO9Head（anchor_convs / class_convs）、RepConvNはRepConv、RepNBottleneckはBottleneck、DFLはAnchor2Vec（anchor2vec）、ncはnum_classesになり、ブロックのサブレイヤーはconv1/conv2/bottleneckになりました。YOLO9-E2Eでは、YOLO9E2EDetectはYOLO9E2EHeadに、one2one_cv2 / one2one_cv3はone_to_one_anchor_convs / one_to_one_class_convsになりました。LibreYOLO9Model.fuse()、RepConvN.fuse_convs()、Conv.forward_without_bn()、Concat、yolo9.utils.decode_boxesは削除されました。すべての名前変更は変更履歴に掲載されています。

• ONNXのノード名は、ヘッド、バックボーン、ネックで新しいモジュール名に従います。たとえば/head/anchor_convs.0/...のようになります。Hailoのエンドノード設定など、ノード名をキーにするツールを更新してください。モデルの入力、出力、出力名は変わりません。

• PGIテンソルを持たない重み（公開済みのLibreYOLO9{t,s,m,c}.ptを含む）からのYOLO9のファインチューニングは、1.5.0と同様に主ヘッドだけを学習します。1.6.0はaux_weight=0.25でランダムに初期化したPGI分岐を付けていました。PGIテンソルを含む重みと、ゼロからの実行は、引き続きPGI付きで学習します。それでも新しい分岐を付けるにはaux_weight=0.25を、強制的に無効にするにはaux_weight=0を渡してください。

• PGIを付けた場合、YOLO9-mとYOLO9-cはMultimediaTechLabの補助分岐を構築します。80クラスでの学習時のみのパラメータは12.8M（m）と25.7M（c）で、以前の7.5Mと10.2Mから増えるため、これらのサイズのPGI学習ではステップあたりのメモリと時間が増えます。1.6.0のm/cの学習チェックポイントは、学習時の分岐のまま再開とファインチューニングができます。推論とYOLO9-t/sは変わりません。

• YOLO9、YOLO9-E2E、YOLO9-P2は勾配のL2ノルムを10でクリップし、学習用アサイナーはアンカーをfp32でスコアリングするため、fp16のAMPで選ばれる正例が変わる場合があります。1.6.0のクリッピングにするにはclip_max_norm=0を渡してください。1.6.0で開始して1.7.0で再開した実行も、この引数を渡さない限りクリップします。fp32の割り当てを切り替える設定はありません。

• 0以外のperspectiveは、共有アフィン変換を使うすべてのファミリー（YOLO9とそのE2E・P2バリアント、YOLOX、YOLOv7、YOLO-NAS、PP-YOLOE、RTMDet、PicoDet、RT-DETR、RT-DETRv2）で、これを設定した1.6.0のチェックポイントから再開した実行も含め、コーナーの変位によって変形します。0.002以上の値は同じ最大変形になり、負の値はValueErrorを送出します。1.6.0の変形を再現する設定はありません。デフォルトのperspective=0は変わりません。

• YOLO9のモザイクパイプラインは、mixupの比率をBeta(32, 32)ではなくBeta(1, 1)から抽出し、以前の値に戻す設定はありません。YOLOv7はデフォルトでmixupを有効にするため、YOLOv7のデフォルトの学習が変わります。YOLO9、YOLO9-E2E、YOLO9-P2、RT-DETR、RT-DETRv2は、mixupを有効にした場合だけ変わります。

• name=なしのlibreyolo trainは、EC、D-FINE、SegFormer、LingBot-Visionの実行をruns/train/expではなくruns/train/ec_exp、dfine_exp、segformer_exp、lingbotvision_expに、V-JEPA 2のプローブをruns/train/trainに、YOLO9-P2の実行をruns/train/yolo9_expに書き込みます。以前のパスにするにはname=expを、YOLO9-P2ではname=yolo9_p2_expを渡してください。

• libreyolo trainは、D-FINE、SegFormer、LingBot-Visionをそれぞれ独自のレシピで開始します。D-FINEでは132エポック、lr0=2e-4、weight_decay=1e-4、2エポックのウォームアップで、モザイク、mixup、HSV、アフィンのデータ拡張は使いません。1.6.0が送っていた値を送るには、epochs=300 optimizer=sgd lr0=0.01 weight_decay=5e-4 warmup_epochs=5 mosaic=1.0 mixup=1.0 hsv_prob=1.0 degrees=10 translate=0.1 shear=2.0を渡してください。

• libreyolo.validation.ConfusionMatrixはmatrix[predicted, true]でインデックスし（以前は[actual, predicted]）、conf_thres=0.25で検出を数え（以前は0.15）、names=とtask=をキーワード引数としてのみ受け取り、そのmatrixは再代入できなくなりました。以前の行列をインデックスしていたコードは転置し、以前の件数を得るにはconf_thres=0.15を渡してください。plots=Trueは件数をconfusion_matrix.pngに、正規化したプロットをconfusion_matrix_normalized.pngに書き出します。

• predict(agnostic_nms=True)は警告を出す代わりに、クラスをまたいで重なるボックスを抑制します。ボックスを持たないタスクはValueErrorを、LibreEnsembleとHRNetはNotImplementedErrorを送出し、SAM系のモデルはこのキーワードをTypeErrorで拒否します。これらの呼び出しからは引数を削除してください。

• torchvisionのモードであるLANCZOS、BOX、HAMMING、NEAREST_EXACTを含め、分類器の未知のinterpolationはValueErrorを送出します。bilinear、bicubic、nearest、bilinear_no_antialiasのいずれかを使ってください。

• 複数クラスで学習したモデルでのval(single_cls=True)、ボックスだけの行とポリゴンの行が混在するセグメンテーションデータセット、デフォルトで画像あたり最大max_det=300個のマスクを保持するRTMDet-Insについては、1.6.0の数値と比較する前に検証をやり直してください。MMDetectionの設定にするにはmax_det=100を渡してください。

• libreyolo[rfdetr]がない場合、RF-DETRまたはDINOv2のモデル名を指定したCLI呼び出しは、model_not_foundではなくJSONエラーコードmodel_load_failedで終了し、メッセージにはpip install libreyolo[rfdetr]が示されます。

リリース全体は変更履歴を参照してください。

1.5.0から1.6.0

• ONNX Runtimeを1.18未満に固定した環境では、ONNX追加パッケージをインストールする前にonnxruntime>=1.18.0へ更新してください。

• SAM 3D Bodyは、確認済みのスナップショットアセット一式を受け付けます。libreyolo[hf]をインストールしてアクセス制限付きモデルへの権限を取得し、自動取得を使ってください。または、変更していないスナップショットディレクトリと固定されたMHRアセットを、信頼できるローカルファイルシステム上で指定してください。

• RF-DETRの姿勢推定以外のリサイズと分類器の正規化の修正に伴い、検証をやり直してください。1.5.0の結果と比較する前に、デプロイ済みの信頼度しきい値を再確認してください。従来の前処理を使うフラグはありません。

• D-FINE、DEIM、RT-DETRv4、YOLO-NASの物体検出は、デフォルトでFP16のAMPを有効にします。FP32を維持するにはamp=Falseを渡してください。

• 以前のYOLO9のファインチューニング設定を使うには、aux_weight=0、max_labels=100、warmup_momentum=0.937を設定してください。centerが記録された新しい変換済みモデルで従来の配置を再現する場合は、letterbox_pad="topleft"を設定してください。古い単一ヘッドのチェックポイントは、元のグラフで再開します。新しいYOLO9の実行はより多くのGPUメモリを使うため、1.5.0のバッチサイズでメモリ不足になる場合はbatchを下げてください。

• RF-DETRとDINOv2は、ファミリー名を含む連番付きの実行ディレクトリを作成します。ファイルパスを使う処理を更新するか、output_dir="runs/train", exist_ok=Trueを設定して、従来の保存場所と再利用の動作を維持してください。

• 分類ではmixup + cutmix <= 1を守ってください。不正な組み合わせは、設定時に例外を送出するようになりました。

• QATはEMA、SyncBatchNorm、チェックポイントの平均化を無効にします。これらの状態に依存せず、QATのbestまたはlastチェックポイントを使ってください。

• データセットを変更するフックを持つ独自ローダーでは、persistent_workers=Falseを使うか、変更後にワーカーを再構築してください。互換性のない永続的な複数ワーカーのコピーは、例外を送出するようになりました。

• NumPyの画像配列は、OpenCVの順序であるBGRとして読み取られます。np.asarray(pil_image)のようなRGB配列を渡す箇所ではcolor_format="rgb"を渡してください。cv2.imread()の出力と動画フレームは変更不要です。

• 4DのNumPy配列またはテンソルはバッチとして扱われます。predict()は最初の画像だけを使うのではなく、画像ごとに1つのResultsを含むリストを返します。

• train(resume=True)とtrain(resume="path/to/last.pt")は、その実行で保存された学習引数を復元し、その実行ディレクトリに引き続き書き込みます。明示的に渡した引数が優先されます。公開済みの重みや、すでにepochsに達した実行を再開するとValueErrorを送出します。

• 検証が有効な場合は最終エポックで必ず検証するため、eval_intervalより短い実行でも指標を報告し、best.ptを書き出すようになりました。val=Falseは最終エポックも含めて検証を無効にします。学習中の検証はruns/val/ではなく<run>/valに書き込みます。

• CLIのtrainの失敗はエラーの種類を報告するため、設定エラーはio_error付きのコード1ではなく、コード2で終了します。

リリース全体は変更履歴、チェックポイントの変換は重みのインポートを参照してください。

1.4.0から1.5.0

このページではLibreYOLO自体のアップグレードについて説明します。アップストリームプロジェクトのチェックポイントを読み込む方法を探している場合は、別のトピックである既存の重みのインポートを参照してください。

このリリースの完全な記録は変更履歴にあります。以下では、利用者側の対応が必要な部分だけを説明します。

必須のコード変更

allow_experimental=Trueは廃止されました

確認用ゲートと、その背後にあったddp_aware(experimental_key=...)の仕組みが廃止されました。以前はEC、RTMDet、PicoDet、FOMOの学習とエクスポートでこの引数が必要だったため、これらのファミリーを学習するスクリプトが影響を受けます。

# 1.4.0model.train(data="data.yaml", epochs=100, allow_experimental=True) # 1.5.0: この引数を削除model.train(data="data.yaml", epochs=100)

非推奨互換レイヤーはありません。引数を渡し続ける呼び出しではUnknown training config keys (ignored)という警告が出て、その引数は効果を持ちません。BaseModel.EXPERIMENTAL_WEIGHT_FILENAMESもあわせて削除されました。get_download_notice()フックは残っており、MiDaS、SegFormer、YOLO9-P2で引き続きオーバーライドされています。

サポートレベルは今も公開されていますが、引数ではなくなりました。安定性レベルを参照してください。

エクスポートレベル"experimental"は廃止されました

from libreyolo.export.support import Tier # 1.4.0: Literal["validated", "experimental", "blocked"]# 1.5.0: Literal["validated", "available", "blocked"]

レベル文字列で分岐するコードは、"experimental"を読んでいた箇所で"available"を読むように変更してください。BaseExporterはこれらの形式に対してRuntimeWarningを発行しなくなりました。形式ごとの状態はエクスポートマトリックスに掲載されています。

pretrained=Falseとresumeの併用は拒否されます

以前は矛盾した状態のまま処理が進んでいました。現在は次のエラーが発生します。

ValueError: pretrained=False cannot be combined with resume.

どちらか一方を選んでください。pretrained=Falseは新しいシード済み初期値から開始します。1.5.0では3つだけでなく、学習可能なすべてのファミリーで動作します。resumeは中断した実行をチェックポイントから再開します。どちらも学習に記載されています。

CLIの--imgszは整数ではなく文字列です

影響範囲は見た目より限定的です。次の2つは影響を受けません。

libreyolo predict --model yolo9-t --source img.jpg --imgsz 640   # 引き続き有効

model.predict("img.jpg", imgsz=640)   # 引き続き有効

PythonからCLIのコマンド関数を直接呼び出すコードだけを変更する必要があります。長方形サイズを受け付けられるよう、predict、train、valの--imgszがintからstrへ拡張されたためです。

from libreyolo.cli.commands.predict import predict_cmd predict_cmd(..., imgsz=640)      # 1.4.0predict_cmd(..., imgsz="640")    # 1.5.0では"480x640"も使用可能

trainのデフォルトは文字列"640"になりました。export --imgszは以前から文字列で、profileに変更はありません。

変化する数値

デフォルト設定の指標値が変わる変更は3つあります。バージョンをまたいで結果を追跡する場合は、1.5.0の実行結果と1.4.0を比較する前に確認してください。

faster-coco-evalがデフォルトのCOCO指標バックエンドになりました

val()と各エポックの学習検証は、pycocotoolsではなくfaster-coco-evalのC++バックエンドでCOCO指標を計算するようになりました。

この切り替えは、RF100-VLの100個すべてのテスト分割で測定した同等性に基づいて決定されました。1400個の指標値のうち1381個がビット単位で同一、最大差は2.22e-16、主要指標の差は正確に0でした。全体では15.6倍、検出密度の高いデータセットでは56倍高速です。数値は変わらないはずですが、異なる実装で生成されるため、この一覧に含めています。

faster-coco-evalがインストールされていない場合、pycocotoolsが自動フォールバックとして残ります。強制的に使用するには次のようにします。

libreyolo val --model yolo9-t --data coco.yaml --no-faster-coco-eval

model.val(data="coco.yaml", faster_coco_eval=False)

LIBREYOLO_FASTER_COCO_EVAL=0でもグローバルに同じ設定を行えます。実際に使用されたバックエンドはINFOレベルでログに記録され、val()の後にmodel.last_eval_backendで参照できます。CLIのJSONペイロードにもeval_backendとして含まれます。高速経路はpip install libreyolo[fast-eval]でインストールできます。

1.5.0より前に学習したYOLOXチェックポイントにはepsのオーバーライドが必要です

これは今回のリリースで注意が必要な点です。YOLOXをファインチューニングしている場合は確認してください。

YOLOXはBatchNormのeps=1e-3とmomentum=0.03を指定します。1.5.0より前は、これらの値が後処理の修正として適用されており、データセットのncがチェックポイントと異なるときにtrain()が行うクラス数の再構築では維持されませんでした。そのようなファインチューニングでは、PyTorchのデフォルトeps=1e-5で学習され、学習中の検証も行われた後、推論時には1e-3で再読み込みされていました。同じテンソルに異なる正規化が適用されていたことになります。

通常の畳み込みを使うサイズでは変化はごくわずかです。Depthwiseのnでは、チャンネルごとのrunning_varが小さくepsの影響が支配的になるため、大きく変化します。RF100-VLのballでは、同じnanoチェックポイントを学習時のepsで評価するとmAP50-95は0.566ですが、通常どおり再読み込みすると0.151になります。

1.5.0より前に学習したチェックポイントはeps=1e-5の意味を持ちます。正しい数値を報告するには、BNのepsを1e-5へオーバーライドして評価します。

import torchfrom libreyolo import LibreYOLO model = LibreYOLO("my-yolox-finetune.pt")for module in model.model.modules():    if isinstance(module, torch.nn.BatchNorm2d):        module.eps = 1e-5 model.val(data="data.yaml")

または、sqrt((var + 1e-3) / (var + 1e-5))をBNの重みに一度組み込んで結果を保存してください。1.5.0以降で学習したチェックポイントでは、どちらも不要です。

D-FINEのマルチスケール学習はアップストリームのサイズ別レシピを使用します

以前はすべてのサイズでbase_size_repeatが3に固定されていました。現在はアップストリームの指定に従い、サイズごとに解決されます。nは固定サイズでマルチスケール無効、sは20、mは6、lは4、xは3です。以前と一致するのはxだけなので、n、s、m、lではスケール分布が変わり、収束する指標値も変わります。

以前の動作へ戻すには明示的に設定します。

from libreyolo.training.config import DFINEConfig config = DFINEConfig(base_size_repeat=3)

DEIMは引き続き3に固定されています。ファミリーの詳細はD-FINEにあります。

知っておくべき変更（対応不要）

• 長方形のimgszで結果が変わるのは、以前の結果が誤っていたためです。 ボックス座標、RTMDetのマスクサイズ変更、YOLO-NASの再スケーリング、バリデーターの正解データスケーリングで、単一のスカラーではなく高さと幅を軸ごとに使用するようになりました。正方形のimgszはビット単位で変わりません。1.4.0での長方形の推論または検証は誤ってスケーリングされていました。YOLO-NASは誤った出力を通知なく生成せず、長方形のimgszを明示的に拒否するようになりました。
• 指標辞書にキーが追加されました。 COCO評価器からmax_det、ar_max_det、AR_max_detが、FOMOからmetrics/lossとmetrics/loss/ceが追加されました。デフォルトでの値は変わりませんが、カスタムロガーやCSVヘッダーなど、指標キーを反復処理するものには新しい列が表示されます。
• ヘッド再構築が発生するシード付きYOLO9実行では、再構築後ではなく再構築前にシードを適用するようになったため、異なる初期値から始まります。異なるクラス数へファインチューニングしたシード付き1.4.0実行を、1.5.0でビット単位に再現することはできません。
• CUDA上のlibreyolo[hub-kernels]で、ネイティブのMS-deform-attnカーネルが実際に使われるようになりました。 1.4.0ではRF-DETRが通らない条件の背後に置かれていたため、カーネルが実行されませんでした。RF-DETRやほかの変形可能アテンションファミリーでは、浮動小数点の許容範囲内で予測が変わる可能性があります。標準インストールには影響せず、LIBREYOLO_HUB_KERNELS=0で無効にできます。
• libreyolo predictは未対応のオプションで例外を発生させず、破棄します。 CLIはモデルの__call__シグネチャに照らしてキーワード引数をフィルタリングするため、ファミリーが受け付けないオプションはTypeErrorを発生させず無視されます。未知のフラグ名は引き続きNo such optionで拒否されます。
• ライブソースではJSON出力の形が変わります。 Webカメラ、RTSPストリーム、画面キャプチャは暗黙的にストリーミングを有効にし、呼び出し全体で1レコードではなくフレームごとに1レコードを出力します。これらの入力ソースは1.5.0で追加されたため、1.4.0のスクリプトには影響しません。
• rfdetr-poseまたはyolonas-poseをONNXへ再エクスポートすると、出力名が変わります。 1.4.0では出力数に基づく判定により、複数テンソルの姿勢推定ヘッドをセグメンテーションと誤認していました。ディスク上の既存.onnxファイルは変更されません。
• PyTorchなしのインストールでは、結果がtorch.TensorではなくNumPy配列を保持するため、.boxes.dataが返す型が変わり、NMSの同点処理がtorchvisionと異なる場合があります。PyTorchがインストールされていれば、動作はバイト単位で変わりません。軽量インストールを参照してください。
• 構成オブジェクトは構築時により多くの検証を行います。 TrainConfigには以前存在しなかった__post_init__が追加されたため、すでに無効だった構成は実行の途中ではなく即座に例外を発生させます。ValidationConfigのシリアライズにはedge_thresholdsキーが追加され、1.4.0のダンプに対する厳密なValidationConfig(**dump)往復変換は機能しません。
• タスクサフィックス付きファミリーの重みファイル名は異なる方法で解決されます。 segformer-b0はLibreSegformerb0-sem.ptへ解決されるようになりました。これにより自動ダウンロードの404が修正されますが、以前のサフィックスなしファイル名をハードコードしたスクリプトは動作しなくなります。
• pytestマーカーexperimental_backendはextended_backendになりました。 -mを指定してテストスイートを実行する場合だけ関係します。

チェックポイントとデータセット

1.4.0で書き込まれたチェックポイントは変更なしで読み込めます。スキーマには長方形モデル向けのimgsz_hとimgsz_wが追加され、古いリーダー向けにスカラーのimgsz = max(h, w)も引き続き書き込まれます。ExecuTorchとMNNのエクスポートでは、それぞれ<program>.pte.jsonと<model>.mnn.jsonというサイドカーが必要になりました。HRNetのエクスポートにはpose_input: "person_crop"が含まれます。データセット形式に変更はありません。