アップストリームのチェックポイント

読み込み時の処理

LibreYOLO()が完全なv1.0チェックポイントではない.ptファイルを受け取ると、自動変換処理を呼び出し、次の処理を行います。

1. 一般的なアップストリームのレイアウトからテンソル辞書を展開します。
2. 登録済みの全ファミリーにレイアウトを認識できるか確認し、アップストリームの命名がネイティブ移植版と異なる場合はキーを再マッピングします。
3. 一致したファミリーを厳密なv1.0メタデータ付きチェックポイントでラップします。サイズ、タスク、クラス数はテンソル自体から読み取るため、ファインチューニング済みのチェックポイントも正しく変換できます。
4. ソースの隣に<source>-<Prefix><size>[-task].ptとして書き込み、そのパスを返します。これにより、ファクトリーは通常どおり読み込めます。

呼び出し側で追加の操作は必要ありません。どのファミリーにも該当しないファイルでは何も返されず、ファクトリーは読み込めなかったことを報告します。

from libreyolo import LibreYOLO # 認識されたアップストリームファイルは読み込み時に変換され、変換済みの# チェックポイントがその隣に書き込まれます。# model = LibreYOLO("yolov9-t-converted.pt") # LibreYOLOのチェックポイントは変更されずに読み込まれます。model = LibreYOLO("LibreYOLO9t.pt")print(model.family, model.size, model.task, model.nb_classes)

展開するレイアウト

テンソル辞書は、EMAを優先して次の順序で検索されます。各候補は実際にテンソルを保持しているか確認されます。このため、空またはメタデータのみのEMAブロックが、その下にある有効な重みを隠すことはありません。

次に各候補をテンソル値のエントリーだけに絞り込み、正規化します。先頭のmodule.または_orig_mod.プレフィックスを除去し、すべてのキーがmodel.model.で始まる辞書では、そのプレフィックスも除去します。

各ファミリーが認識する形式

認識処理はファミリーごとのクラスメソッドです。デフォルト実装は、キーがネイティブ移植版とすでに一致しているレイアウトを受け付けます。アップストリームのキー命名が異なるファミリーは再マッピングをオーバーライドし、認識できないレイアウトでは何も返しません。

再マッピング認識処理を備えるファミリーは、centernet、deeplabv3、deformable_detr、dexined、moge2、picodet、rtdetr、rtdetrv2、rtdetrv4、rtmdet、segformer、swin、teed、yolo7、yolo9、yolo9_e2e、yolo9_p2です。

自動変換を明示的に拒否するファミリーもあります。efficientdet、eomt、pidnetは認識処理から何も返さないため、アップストリームファイルには代わりに変換スクリプトを使用します。l2csは推論専用で、重みに再配布制限があるため、汎用認識処理から除外されています。

RF-DETRには独自の認識処理があります。サイズの検出とCOCOクラスの再マッピングにテンソル辞書だけでなくチェックポイント全体が必要なためです。オプション依存関係がインストールされている場合にのみ登録されます。

その他の登録済みファミリーはすべてデフォルトを使用します。各ファミリー自身のローダーがキーをすでに認識できる場合に、ファイルを受け付けます。

選ばれるファミリー

同じファイルを複数のファミリーが受け付ける場合があるため、解決方法はファクトリーのディスパッチルールに従います。

サブクラスの一致は基底クラスより優先されます。登録順はクラスの作成順に従うため、派生ファミリーは改良対象の基底クラスより後に登録されます。その明確な識別子が、基底クラスのより広いパススルーに負けることはありません。

次にレジストリー順で決定します。この順序が具体性を表しており、最初の一致が最も具体的な一致です。

レジストリー順で解決できない唯一の競合は、アーキテクチャキーが同一のDEIMとD-FINEです。この場合に限りファイル名を判定材料とし、名前に手掛かりがないファイルは推測せず拒否します。それ以外では意図的にファイル名を参照しないため、ファイル名だけを理由に広すぎる誤検出が、より具体的な一致より優先されることはありません。

安全な読み込み

アップストリームファイルはweights-onlyアンピクラーで読み込まれます。一部のアップストリーム学習チェックポイントには、アンピクラーが拒否するライブラリオブジェクトが埋め込まれています。これらは重みではなく学習メタデータであるため、ブロックされた各グローバルについて、コードを実行せずにアンピクラーの要件を満たす不活性な代替クラスで再試行します。取得した名前は文字列ラベルとしてだけ使用され、インポート、評価、呼び出しは行われません。

機密性の高いモジュール名は明示的に拒否され、スタブ化されません。対象はbuiltins、os、sys、posix、nt、subprocessです。再試行ループは32回を上限とするため、異なるグローバルを無制限に提示するよう細工されたファイルはループし続けず、安全側に倒して失敗します。変換済みチェックポイントにはテンソルだけが残ります。

変換済みファイルの保存先

出力はソースの隣に<source>-<Prefix><size>[-task].ptという名前で書き込まれます。再利用せず常に書き直すため、同じソースを繰り返し読み込んでも変換結果を最新に保てます。また、公式の重みや、同じディレクトリにある同一ファミリー、サイズ、タスクの別のファインチューニング結果との衝突を避けられます。

ソースディレクトリが読み取り専用の場合、変換は呼び出しごとに作成される新しい専用一時ディレクトリへフォールバックし、ログ行に使用したパスを表示します。それにも失敗した場合に限り、警告を出して変換を中止します。

既存のLibreYOLOチェックポイント

LibreYOLO固有のマーカーであるlibreyolo_versionまたはmodel_familyを持つファイルは通常の読み込み経路に属し、再変換されません。このスキップは、キーセットが変更されていないパススルーの一致だけに適用されます。変換によってキーセットが変わった一致は、外部のアップストリームレイアウトである証拠になるため、マーカー付きファイルでも受け付けます。

schema_versionは意図的にマーカーとして扱いません。ほかの学習ツールやエクスポートツールもこの汎用名を使うためです。同様に、names、nc、size、task、imgszもマーカーではありません。アップストリームでファインチューニングされたファイルにも含まれる場合があるためです。したがって、汎用的なnamesキーを持つだけの外部ファインチューニング結果はマーク済みとは見なされません。ネイティブ形式のキーによる一致は通常どおり変換され、80クラスとして誤って読み込まれるのではなく、テンソルヘッドからクラス数を取得します。

変換処理が読み取るメタデータ

クラス名はトップレベルのnamesキー、またはargsかhyper_parametersブロック内のclass_namesから取得されます。クラスインデックスではなくラベルをキーとするnamesマップは使用できないため、生成されたデフォルト値に置き換えられます。検出したクラス数より長いnamesリストは切り詰められます。範囲外インデックスがあると厳密なバリデーターに失敗し、変換が通知なく中止されるためです。

アップストリームのargsは通常のメタデータとして引き継がれます。文字列、数値、真偽値、リスト、辞書ではない値はすべて除外されるため、安全でないものが保存ファイルに渡ることはありません。

RF-DETRのCOCO正規化

アップストリームのRF-DETRチェックポイントは、COCOの90クラスと背景からなる91出力の分類ヘッドを公開します。自動変換は、後処理で再マッピングを適用し、COCOのRF-DETRをCOCO-80の規則に正規化します。

チェックポイントに名前がちょうど80個ある場合、クラス数が80と宣言されている場合、cocoデータセットのヒントがある場合、またはクラスやデータセットのメタデータがまったくない場合はCOCOとして扱います。最後の条件は重要です。通常のアップストリームstate dictは標準的なCOCO事前学習済みチェックポイントであり、配布されている91出力RF-DETRのうち、メタデータを持たない唯一の形式です。

実際のカスタム90クラスRF-DETRは、90クラスのまま保持されます。namesリスト、80以外の明示的なクラス数、またはCOCO以外のデータセットヒントによって識別されるため、通常のチェックポイント用フォールバックは適用されません。データセットヒントの有無を判断するときは、空のプレースホルダーを無視します。

制限

自動変換は、公開されたアップストリームのレイアウトを認識します。アーキテクチャを書き換えたり、未移植モデルを読み込めるようにしたりするものではありません。どのファミリーにも該当しないファイルでは、ファクトリーの引数ではなく変換スクリプトを使います。リポジトリには、変換が必要なファミリー向けのweights/convert_*.pyが用意されており、EoMT、PIDNet、EfficientDetも含まれます。

また、変換処理は読み取れないメタデータを作り出しません。サイズ、タスク、クラス数はテンソルから取得します。名前はファイルに存在する場合はそこから取得し、ない場合はclass_iとして生成します。