アーティファクトのバージョンをコレクションにリンクする

アーティファクトのバージョンを組織で利用できるようにするには、Registry のコレクションに リンクします。リンクすると、バージョンは非公開の project レベルのスコープから、共有の組織レベルのスコープに移ります。アーティファクトのバージョンは、W&B Python SDK を使用してプログラムで、または W&B アプリでインタラクティブにリンクできます。アーティファクトをリンクすると、W&B はソースアーティファクトとコレクションのエントリ間に参照を作成します。リンクされたバージョンは、project 内の run にログされたソースアーティファクトのバージョンを指します。コレクション内のリンクされたバージョンと、ログ先の project 内のソースバージョンの両方を確認できます。

アーティファクトをコレクションにリンクする

run 中にアーティファクトを作成するか、run なしで作成するか、既存のアーティファクトのバージョンをリンクするかに応じて、ワークフローを選択します。

開始する前に、次の点を確認してください。

コレクションで許可されているアーティファクトのタイプ。コレクションのタイプについて詳しくは、コレクションを作成するの「コレクションのタイプ」を参照してください。
コレクションが属するRegistryがすでに存在すること。Registryが存在することを確認するには、Registry App にアクセスして、Registry名を検索します。

W&B Python SDK
Registry
アーティファクトブラウザー

wandb.Run.link_artifact() または wandb.Artifact.link() を使用して、プログラムでアーティファクトのバージョンをコレクションにリンクします。次の表は、アーティファクトのバージョンをコレクションにリンクするために使用できるメソッドと、各メソッドを使用したときに W&B が記録する内容をまとめたものです。

ユースケース	メソッド	W&B が記録する内容
run 中にアーティファクトを作成し、コレクションにリンクする	`wandb.Run.link_artifact()`	実行中の run の出力としてアーティファクトをログし、その後リンクします
run を明示的に開始せずにアーティファクトを作成してリンクする	下書きのアーティファクトで `wandb.Artifact.link()` を使用する	まずアーティファクトを保存し、実行中の run がなければ自動的に run を作成します
既存のコミット済みアーティファクトをリンクする	`wandb.Api().artifact()` から取得したアーティファクトで `wandb.Artifact.link()` を使用する	新しい run を作成せずにアーティファクトをリンクします

リンク先のコレクションのパスを target_path パラメーターに渡します。パスは、wandb-registry- 接頭辞、レジストリ名、コレクション名で構成されます。

wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}

wandb.Run.link_artifact() を使用して、実行中の run でアーティファクトのバージョンを作成してリンクします。W&B は、ドラフトのアーティファクトをリンクする前に、run の出力としてログします。アーティファクトのバージョンを作成してリンクするには、次の手順に従います。

wandb.init() で run を初期化します。
Artifact オブジェクトを作成し、1 つ以上のファイルを追加します。
wandb.Run.link_artifact() を呼び出し、リンク先のコレクションを指定します。

山括弧 (<>) で囲まれた値を、ご自身の値に置き換えてください。

import wandb

entity = "<team_entity>"          # ご自身のチーム entity
project = "<project_name>"        # アーティファクトを含む project の名

# run を初期化します
with wandb.init(entity = entity, project = project) as run:

  # アーティファクト オブジェクトを作成します
  # type パラメーターはアーティファクト オブジェクトのタイプと
  # コレクションのタイプの両方を指定します
  artifact = wandb.Artifact(name = "<name>", type = "<type>")

  # アーティファクト オブジェクトにファイルを追加します。 
  # ローカルマシン上のファイルへのパスを指定します。
  artifact.add_file(local_path = "<local_path_to_artifact>")

  # アーティファクトのリンク先のコレクションとレジストリを指定します
  REGISTRY_NAME = "<registry_name>"  
  COLLECTION_NAME = "<collection_name>"
  target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}"

  # アーティファクトをコレクションにリンクします
  run.link_artifact(artifact = artifact, target_path = target_path)

wandb.Artifact.link() を使用すると、run を明示的に初期化せずに、下書きのアーティファクトを作成してリンクできます。W&B は、必要に応じて自動的に run を作成し、リンクする前にアーティファクトを保存します。アーティファクトのバージョンを作成してリンクするには：

Artifact オブジェクトを作成し、1 つ以上のファイルを追加します。
wandb.Artifact.link() を呼び出し、リンク先のコレクションを指定します。

山括弧 (<>) 内の値を独自の値に置き換えてください：

import wandb

# アーティファクト オブジェクトを作成します
# type パラメーターは、アーティファクト オブジェクトのタイプとコレクションのタイプの両方を指定します
artifact = wandb.Artifact(name = "<name>", type = "<type>")

# アーティファクト オブジェクトにファイルを追加します。 
# ローカルマシン上のファイルへのパスを指定します。
artifact.add_file(local_path = "<local_path_to_artifact>")

# アーティファクトのリンク先のコレクションとレジストリを指定します
REGISTRY_NAME = "<registry_name>"  
COLLECTION_NAME = "<collection_name>"
target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}"

# アーティファクトをコレクションにリンクします
artifact.link(target_path = target_path)

wandb.Api().artifact() で取得したアーティファクトに対して wandb.Artifact.link() を使用すると、新しい run を作成せずに、コミット済みの既存のアーティファクトのバージョンをリンクできます。

wandb.Api() で Public API クライアントを作成します。
wandb.Api.artifact() でアーティファクトのバージョンを取得します。
wandb.Artifact.link() を呼び出し、リンク先のコレクションを指定します。

import wandb

api = wandb.Api()

artifact = api.artifact(
    "<entity>/<project>/<artifact-name>:<alias-or-version>"
)

artifact.link(
    target_path="wandb-registry-<registry-name>/<collection-name>",
    aliases=["latest"],
)

W&B App で project のアーティファクトブラウザーにアクセスします: https://wandb.ai/<entity>/<project>/artifacts
プロジェクトのサイドバーで Artifacts アイコンを選択します。
レジストリにリンクするアーティファクトのバージョンをクリックします。
Version overview セクションで、Link to registry ボタンをクリックします。
画面右側に表示されるモーダルで、Select a registered model ドロップダウンメニューからアーティファクトを選択します。
Next step をクリックします。
(オプション) Aliases ドロップダウンからエイリアスを選択します。
Link to registry をクリックします。

Registry App では、リンクされたアーティファクトのメタデータ、バージョンデータ、使用状況、リネージ情報などを確認できます。

コレクションからアーティファクトのバージョンのリンクを解除する

W&B Python SDK または Registry を使用して、コレクションからアーティファクトのバージョンのリンクを解除します。リンクを解除すると、コレクションからアーティファクトのバージョンが削除されますが、ソースアーティファクトのバージョンやそのファイルは削除されません。

アーティファクトのバージョンを Registry のコレクションにリンクすると、有効期間 (TTL) ポリシーが無効化され、TTL が None に設定されます。後でそのバージョンのリンクを解除しても、W&B は以前の TTL を復元せず、元の期間も保持しません。そのバージョンに引き続き TTL が必要な場合は、リンク解除後に TTL を再設定してください。TTL ポリシーの詳細については、アーティファクトのデータ保持を管理するを参照してください。

W&B Python SDK
Registry

W&B Python SDK でアーティファクトのバージョンのリンクを解除するには、次の手順を実行します。

wandb.Api() で Public API クライアントを作成します。
wandb.Api.artifact() でリンクされたアーティファクトのバージョンを取得します。
wandb.Artifact.unlink() を呼び出して、コレクションからアーティファクトのバージョンのリンクを解除します。

wandb-registry-<registry_name>/<collection_name>:<version_or_alias>

プレースホルダーの値を実際の値に置き換えます。

import wandb

registry_name = "your-registry-name"  # Registry 名に置き換えます
collection_name = "your-collection-name"  # コレクション名に置き換えます
version = "version-or-alias"  # リンクを解除するアーティファクトのバージョンに置き換えます

target_path=f"wandb-registry-{registry_name}/{collection_name}:{version}"

api = wandb.Api()
linked_artifact = api.artifact(name=target_path)

# コレクションからアーティファクトのバージョンのリンクを解除します
linked_artifact.unlink()

Registry内のリンクされたアーティファクトを表示する

Registry で、リンクされたアーティファクトのメタデータ、リネージ、使用量情報などを表示します。

https://forge.coreweave.com/registry/ の Registry にアクセスします。
アーティファクトをリンクしたRegistryの名を選択します。
コレクションの名を選択します。
コレクションのアーティファクトがメトリクスをログする場合は、Show metrics をクリックしてバージョン間のメトリクスを比較します。
アーティファクトのバージョンの一覧から、アクセスするバージョンを選択します。バージョン番号は、リンクされた各アーティファクトのバージョンに v0 から段階的に割り当てられます。
アーティファクトのバージョンの詳細を表示するには、そのバージョンをクリックします。このページのタブから、そのバージョンのメタデータ (ログされたメトリクスを含む) 、リネージ、使用量情報を表示できます。

Version タブ内の Full Name フィールドを確認してください。リンクされたアーティファクトの完全名は、Registry、コレクション名、アーティファクトのバージョンのエイリアスまたはインデックスで構成されます。

Full name of a linked artifact

wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}:v{INTEGER}

アーティファクトのバージョンにプログラムからアクセスするには、リンクされたアーティファクトの完全名が必要です。

トラブルシューティング

アーティファクトをリンクできない場合に確認すべき一般的な事項を以下に示します。

個人アカウントからのアーティファクトのログ

personal entity で W&B にログされたアーティファクトは、Registry にリンクできません。組織内のチーム entity を使用してアーティファクトをログするようにしてください。組織のチーム内でログされたアーティファクトのみが、組織の Registry にリンクできます。

Registry にアーティファクトをリンクしたい場合は、チーム entity でアーティファクトをログするようにしてください。

チーム entity を検索する

W&B はチーム名をチームの entity として使用します。たとえば、チーム名が team-awesome の場合、チーム entity は team-awesome です。チーム名は次の手順で確認できます。

チームの W&B プロフィールページにアクセスします。
サイトの URL をコピーします。URL は https://wandb.ai/<team> の形式です。ここで、<team> はチーム名であり、チームの entity でもあります。

チーム entity からログする

wandb.init() で run を初期化するときに、チームを entity として指定します。run の初期化時に entity を指定しない場合、run はデフォルトの entity を使用します。これはチーム entity であるとは限りません。
import wandb with wandb.init(entity='<team_entity>', project='<project_name>') as run: # ここでアーティファクトをログします
wandb.Run.log_artifact() を使用するか、次のコードでアーティファクトオブジェクトを作成してからファイルを追加し、アーティファクトを run にログします。
artifact = wandb.Artifact(name="<artifact_name>", type="<type>")
アーティファクトをログする方法については、アーティファクトの構築を参照してください。
アーティファクトが個人の entity にログされている場合は、組織内の entity に再度ログする必要があります。

W&B アプリの UI で registry のパスを確認する

空のコレクションを作成して、W&B アプリの UI で registry のパスを確認します。以下のステップに従ってください。

https://forge.coreweave.com/registry/ の Registry にアクセスします。
アーティファクトをリンクする registry をクリックします。
空のコレクションをクリックします。空のコレクションがない場合は、新しいコレクションを作成します。
表示されるコードスニペットで、.link_artifact() 内の target_path= フィールドを確認します。
(オプション) コレクションを削除します。

たとえば、上記のステップを完了すると、target_path パラメーターを含むコードブロックを検索できます。

target_path = 
      "wandb-registry-Zoo-Classifier-Registry/Temp Collection"

これを構成要素に分解すると、アーティファクトをプログラムでリンクするためのパスを作成する際に、何を使用する必要があるかがわかります。

ORG_ENTITY_NAME = "wandb"
REGISTRY_NAME = "Zoo-Classifier-Registry"
COLLECTION_NAME = "Temp Collection"

一時的なコレクションのコレクション名を、アーティファクトのリンク先となるコレクションのコレクション名に必ず置き換えてください。

​アーティファクトをコレクションにリンクする

​コレクションからアーティファクトのバージョンのリンクを解除する

​Registry内のリンクされたアーティファクトを表示する

​トラブルシューティング

​個人アカウントからのアーティファクトのログ

​チーム entity を検索する

​チーム entity からログする

​W&B アプリの UI で registry のパスを確認する

アーティファクトをコレクションにリンクする

コレクションからアーティファクトのバージョンのリンクを解除する

Registry内のリンクされたアーティファクトを表示する

トラブルシューティング

個人アカウントからのアーティファクトのログ

チーム entity を検索する

チーム entity からログする

W&B アプリの UI で registry のパスを確認する