1.5.0へのアップグレード

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

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

必須のコード変更

allow_experimental=Trueは廃止されました

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

# 1.4.0
model.train(data="data.yaml", epochs=100, allow_experimental=True)

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

非推奨互換レイヤーはありません。引数を渡し続ける呼び出しではTypeErrorが発生します。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.0
predict_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 torch
from libreyolo import LibreYOLOX

model = LibreYOLOX("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を発生させず無視されます。フラグ名のタイプミスも通知なく無視されるようになりました。
• ライブソースでは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"が含まれます。データセット形式に変更はありません。