保存したArtifactを調べ、Local Registryを管理する

保存したArtifactを調べ、Local Registryを管理する#

Artifactは、InstanceやSolutionなどをまとめて保存・受け渡しするためのデータです。 ここではommxコマンドで内容を調べ、OMMXのローカル保存領域（Local Registry）を整理します。 求解やAdapter比較のために、この操作を覚える必要はありません。

まずCLIの導入手順を確認してください。以降はSDKに付属するCLIを SDKを導入した作業ディレクトリからuv run --no-sync ommxで呼び出します。 単体CLIを導入した場合はuv run --no-sync ommxをommxに置き換えます。 利用できるコマンドやオプションはuv run --no-sync ommx --helpと各サブコマンドの--helpで確認できます。

ファイルや保存済みの名前を調べる#

受け取った.ommxファイルのManifest（収録データを示す一覧）を見るには次を実行します。 これはInstanceやSolutionを評価する操作ではありません。内容の取り出し方は ArtifactのAPI Referenceを参照してください。

uv run --no-sync ommx inspect shared.ommx
uv run --no-sync ommx list

listは現在のLocal Registry内の名前を一覧します。名前が分かれば、その参照先や 論理サイズを調べられます。以下の名前は自分が保存した名前に置き換えてください。

uv run --no-sync ommx inspect example.com/team/result:trial-1
uv run --no-sync ommx size example.com/team/result:trial-1

末尾のtrial-1はタグです。名前やタグは別の内容を指すように更新できますが、 Manifestのdigestは内容の一覧から計算される識別子です。複数の名前が同じデータを参照する こともあります。sizeはManifest自身、config、重複を除いたlayerの論理サイズを示し、 親Artifactへのsubjectは含めません。別々の名前の共有データはそれぞれ数えられるため、 sizeの値を足しても実ディスク使用量にはなりません。 詳しくはArtifactの保存と識別を参照してください。

Pythonから記録を探す#

list_artifacts()は汎用ArtifactとExperimentを一覧します。 Experiment専用の記録や、プロジェクトのannotationを使った絞り込みの完全な例は list_experiments()を参照してください。 Experiment全体の検索用メタデータと、試行ごとに記録する条件の使い分けも説明します。 いずれもソルバーは必要ありません。

中断した編集を探して復帰する場合はlist_experiment_checkpoints()と restore_from_checkpoint()を使います。 調べた内容を正確に特定するにはmanifest digestも残します。一覧にある名前は後から 別の内容を指すことがあるためです。

保存した記録を削除・復元し、保存領域を整理する#

Local Registry はOMMXのローカル保存領域です。ArtifactやExperimentには、 example.com/team/experiment:obsoleteのような名前（ref）を付けられます。 名前を削除する操作と、データ本体を回収して容量を空ける操作は別です。

以下の./local-registryは、実際に使っている保存領域のパスに置き換えてください。 各コマンドの--rootで対象を明示します。省略するとOMMX_LOCAL_REGISTRY_ROOT、 それも未設定ならOS既定の保存先を使います。

まず対象を確認する#

uv run --no-sync ommx prune-anonymous --root ./local-registry --experiments --older-than 7d
uv run --no-sync ommx gc --root ./local-registry

どちらも既定では報告のみで、名前やデータを削除しません。 prune-anonymousは名前を自動生成した匿名Artifactを対象にし、--experimentsで 匿名Experimentも含めます。--older-than 7dは7日以上経過した名前に絞る指定です。 gc（ガベージコレクション）は、どの名前からも参照されなくなったデータ本体の 回収候補を表示します。

一つの名前を削除・復元する#

名前を確認し、例示名を実際の削除対象に置き換えてから実行します。 rmは直ちに名前を削除します。 データ本体はこの操作では削除しません。

uv run --no-sync ommx rm example.com/team/experiment:obsolete --root ./local-registry

出力のRollback行には、削除した名前と、その内容を識別するManifest digestを含む ommx restore-ref ...コマンドが表示されます。復元するときは、そのコマンドを 実行してください。Pythonに付属するCLIを使う場合は先頭にuv run --no-syncを付けます。 --rootも出力に含まれるため、同じ保存先へ復元できます。 同じ名前が既に別の内容を指している場合は、上書きせずエラーになります。

復元には、削除時のデータ本体が残っている必要があります。 必要な復元は、次のデータ回収より先に行ってください。

確認した対象を整理する#

匿名の名前を一括削除する場合は、先ほどの報告を確認してから--deleteを付けます。 削除した名前ごとに復元用コマンドが表示されます。

uv run --no-sync ommx prune-anonymous --root ./local-registry --experiments --older-than 7d --delete

データ本体の回収は、別途gc --deleteで行います。

uv run --no-sync ommx gc --root ./local-registry --delete

残る名前やExperimentのcheckpoint、残した子から参照される親Artifactのデータは回収しません。 名前を公開する前に中断した書き込みのデータは、参照されていない場合があります。 参照されていないデータのうち、データ本体の最終更新から既定で24時間の 猶予期間（grace period）が経過したものを回収します。名前を削除してから24時間の 復元を保証するものではなく、古いデータは削除直後のGCでも回収される可能性があります。 回収後は復元できない場合があります。 書き込み中のデータを保護するため、 通常は猶予期間を短くせず、ommx gc --helpで条件を確認してください。

Pythonから同じ操作を行う場合は、remove_image()、 restore_image()、prune_anonymous()、 gc()を使えます。引数や戻り値の詳細はAPI Referenceを参照してください。

調査のために猶予期間を指定する場合、--grace-periodはs・m・h・dを受け付けます。 0sはその保存先に書き込むOMMXプロセスがない場合に限ります。通常の報告は件数と容量を示し、 --show-digestsを付けると欠損・不正・回収候補・猶予中のデータの識別子を確認できます。

uv run --no-sync ommx gc --root ./local-registry --grace-period 2h --show-digests

CAS・index・cacheの実装はRust Local Registryの資料に分けています。