webhook オートメーションを作成する - Weights & Biases Documentation

このページでは、W&B で特定のイベントが発生したときに外部サービスへ HTTP リクエストを送信する webhook オートメーションを作成する方法を説明します。webhook オートメーションを使用すると、W&B を CI/CD パイプライン、通知サービス、カスタムツールなどの外部システムと統合できます。Slack オートメーションを作成する場合は、代わりにSlack オートメーションを作成するを参照してください。 webhook オートメーションの作成手順は、大まかに次のとおりです。

必要に応じて、オートメーションで必要となるアクセストークン、パスワード、SSH キーなどの機密文字列ごとに、W&B secret を作成します。Secrets は Team Settings で定義します。
webhook を作成して、エンドポイントと認可の詳細を定義し、インテグレーションに必要な secret への access を付与します。
オートメーションを作成して、監視するイベントと、W&B が送信するペイロードを定義します。ペイロードに必要な secret への access をオートメーションに付与します。

Webhook を作成する

チーム管理者は、チームに Webhook を追加できます。Webhook では、W&B がリクエストを送信するエンドポイントと、そこでの認証に必要な認証情報を定義します。

Webhook で Bearer トークンが必要な場合、またはペイロードで機密性の高い文字列が必要な場合は、Webhook を作成する前に、それを含むsecretを作成してください。1 つの Webhook には、最大で 1 つのアクセストークンと、もう 1 つの secret を設定できます。Webhook の認証および認可の要件は、Webhook サービスによって決まります。

W&B にログインし、Team Settings ページに移動します。
Webhooks セクションで、New webhook をクリックします。
Webhook の名を入力します。
Webhook のエンドポイント URL を入力します。
Webhook で Bearer トークンが必要な場合は、Access token に、それを含む secret を設定します。webhook オートメーションを使用すると、W&B は Authorization: Bearer HTTP ヘッダーにアクセストークンを設定し、${ACCESS_TOKEN} のペイロード変数でそのトークンにアクセスできます。W&B が Webhook サービスに送信する POST リクエストの構造について詳しくは、Troubleshoot your webhook を参照してください。
Webhook のペイロードでパスワードまたはその他の機密性の高い文字列が必要な場合は、Secret に、それを含む secret を設定します。Webhook を使用するオートメーションを設定するときは、secret の名の先頭に $ を付けることで、ペイロード変数としてその secret にアクセスできます。 Webhook のアクセストークンが secret に保存されている場合は、その secret をアクセストークンとして指定するために、_さらに_次の手順も完了する必要があります。
W&B がエンドポイントに接続して認証できることを確認するには:
1. 必要に応じて、テスト用のペイロードを入力します。ペイロード内で Webhook がアクセスできる secret を参照するには、その名の先頭に $ を付けます。W&B はこのペイロードをテストにのみ使用し、保存しません。オートメーションのペイロードは、オートメーションを作成するときに設定します。secret とアクセストークンが POST リクエスト内のどこに含まれるかについて詳しくは、Troubleshoot your webhook を参照してください。
2. Test をクリックします。W&B は、設定した認証情報を使用して Webhook のエンドポイントへの接続を試みます。ペイロードを入力した場合、W&B はそれを送信します。
テストが成功しない場合は、Webhook の設定を確認してから再試行してください。必要に応じて、Troubleshoot your webhook を参照してください。

これで、Webhook を使用するオートメーションを作成できます。

オートメーションを作成する

webhook を設定したら、どの W&B イベントが webhook をトリガーし、どのペイロードを送信するかを定義するオートメーションを作成します。必要なスコープに応じて Registry または Project を選択し、webhook をトリガーするオートメーションを作成するには、次の step に従います。

Registry
Project

Registry 管理者は、その Registry でオートメーションを作成できます。Registry オートメーションは、今後追加されるものも含め、Registry 内のすべての collection に適用されます。

W&B にログインします。
Registry の詳細を表示するには、Registry の名をクリックします。
Registry をスコープとするオートメーションを作成するには、Automations タブをクリックし、Create automation をクリックします。
監視するイベントを選択します。表示される追加フィールドに入力します。たとえば、An artifact alias is added を選択した場合は、Alias regex を指定する必要があります。 Next step をクリックします。
webhookを所有するチームを選択します。
Action type を Webhooks に設定し、使用する webhook を選択します。
webhook にアクセストークンを設定した場合は、ペイロード変数 ${ACCESS_TOKEN} でその token を参照できます。webhook に secret を設定した場合は、その名の先頭に $ を付けることでペイロード内で参照できます。webhook の requirements は、webhook のサービスによって決まります。
Next step をクリックします。
オートメーションの名を指定します。必要に応じて説明も指定します。Create automation をクリックします。

W&B 管理者は、project でオートメーションを作成できます。

W&B にログインし、project ページに移動します。
project のサイドバーで Automations をクリックし、Create automation をクリックします。または、Workspace の折れ線グラフから、そのグラフに表示されているメトリクスに対する run メトリクスオートメーションをすばやく作成できます。パネルにカーソルを合わせ、パネル上部のベルアイコンをクリックします。
監視するイベントを選択します。たとえば、artifact alias が追加されたときや、run メトリクスが指定したしきい値に達したときです。
1. 表示される追加フィールドに入力します。これらはイベントによって異なります。たとえば、An artifact alias is added を選択した場合は、Alias regex を指定する必要があります。
  1. run によってトリガーされるオートメーションでは、必要に応じて 1 つ以上の run フィルターを指定します。
    - 1 人のユーザーの Runs にフィルターする: 指定したユーザーが作成した Runs のみを含めます。toggle をクリックしてフィルターをオンにし、ユーザー名を指定します。
    - run 名でフィルターする: 名が指定した正規表現に一致する Runs のみを含めます。toggle をクリックしてフィルターをオンにし、正規表現を指定します。
  このオートメーションは、今後追加されるものも含め、project 内のすべての collection に適用されます。
2. Next step をクリックします。
webhookを所有するチームを選択します。
Action type を Webhooks に設定し、使用する webhook を選択します。
webhook にペイロードが必要な場合は、それを作成して Payload フィールドに貼り付けます。webhook にアクセストークンを設定した場合は、ペイロード変数 ${ACCESS_TOKEN} でその token を参照できます。webhook に secret を設定した場合は、その名の先頭に $ を付けることでペイロード内で参照できます。webhook の requirements は、webhook のサービスによって決まります。
Next step をクリックします。
オートメーションの名を指定します。必要に応じて説明も指定します。Create automation をクリックします。

これらの step を完了すると、オートメーションは有効になり、Registry または project で指定したイベントが発生するたびに webhook を実行します。

オートメーションの表示と管理

Automations タブでオートメーションを確認、編集、または削除します。

Registry
Project

Registry の Automations タブから、Registry のオートメーションを管理できます。

オートメーションの詳細を表示するには、その名前をクリックします。
オートメーションを編集するには、action () メニューをクリックし、Edit automation をクリックします。
オートメーションを削除するには、action () メニューをクリックし、Delete automation をクリックします。W&B によって確認を求められます。

ペイロードリファレンス

以下のセクションを使用して、webhook のペイロードを作成します。以下のセクションでは、ペイロードで使用可能な変数について説明し、一般的なサービス向けのペイロードの例を示します。webhook とそのペイロードのテストの詳細については、Troubleshoot your webhookを参照してください。

ペイロード変数

次の表では、webhook のペイロードの構築に使用できる変数について説明します。

Variable	Details
`${project_name}`	アクションをトリガーしたミューテーションを所有するプロジェクト名。
`${entity_name}`	アクションをトリガーしたミューテーションを所有する entity またはチームの名。
`${event_type}`	アクションをトリガーしたイベントのタイプ。
`${event_author}`	アクションをトリガーしたユーザー。
`${alias}`	オートメーションが An artifact alias is added イベントによってトリガーされた場合、artifact の alias が入ります。それ以外のオートメーションでは、この変数は空です。
`${tag}`	オートメーションが An artifact tag is added イベントによってトリガーされた場合、artifact の tags が入ります。それ以外のオートメーションでは、この変数は空です。
`${artifact_collection_name}`	artifact バージョンがリンクされている artifact collection の名。
`${artifact_metadata.<KEY>}`	アクションをトリガーした artifact バージョン内の、任意のトップレベル metadata キーの値です。`<KEY>` はトップレベル metadata キーの名に置き換えてください。webhook のペイロードで使用できるのは、トップレベル metadata キーのみです。
`${artifact_version}`	アクションをトリガーした artifact バージョンの `Wandb.Artifact` 表現。
`${artifact_version_string}`	アクションをトリガーした artifact バージョンの `string` 表現。
`${ACCESS_TOKEN}`	アクセストークンを設定している場合、webhook で設定したアクセストークンの値です。W&B はこれを `Authorization: Bearer` HTTP ヘッダーで自動的に渡します。
`${SECRET_NAME}`	設定されている場合、webhook で設定した secret の値です。`SECRET_NAME` は secret の名に置き換えてください。

ペイロードの例

以下の例は、一般的なユースケースにおける webhook のペイロードを示しています。これらの例では、ペイロード変数の使い方を示します。

GitHub repository dispatch
Microsoft Teams の通知
Slack 通知

GitHub Actions ワークフローをトリガーするには、アクセストークンに必要な権限が付与されていることを確認してください。詳細は、GitHub repository dispatch event のドキュメントを参照してください。

W&B から repository dispatch を送信して、GitHub Action をトリガーします。たとえば、on キーのトリガーとして repository dispatch を受け取る GitHub workflow ファイルがあるとします。

on:
repository_dispatch:
  types: BUILD_AND_DEPLOY

repository のペイロードは、次のようなものです。

{
  "event_type": "BUILD_AND_DEPLOY",
  "client_payload":
  {
    "event_author": "${event_author}",
    "artifact_version": "${artifact_version}",
    "artifact_version_string": "${artifact_version_string}",
    "artifact_collection_name": "${artifact_collection_name}",
    "project_name": "${project_name}",
    "entity_name": "${entity_name}"
    }
}

webhook payload の event_type キーは、GitHub workflow の YAML ファイル内にある types フィールドと一致している必要があります。

表示されるテンプレート文字列の内容と配置は、automation に対して設定したイベントまたはモデルバージョンによって異なります。${event_type} は LINK_ARTIFACT または ADD_ARTIFACT_ALIAS として表示されます。対応関係の例を以下に示します。

${event_type} --> "LINK_ARTIFACT" or "ADD_ARTIFACT_ALIAS"
${event_author} --> "<wandb-user>"
${artifact_version} --> "wandb-artifact://_id/QXJ0aWZhY3Q6NTE3ODg5ODg3"
${artifact_version_string} --> "<entity>/model-registry/<registered_model_name>:<alias>"
${artifact_collection_name} --> "<registered_model_name>"
${project_name} --> "model-registry"
${entity_name} --> "<entity>"

テンプレート文字列を使用して、W&B から GitHub Actions やその他のツールにコンテキストを動的に渡します。これらのツールが Python スクリプトを呼び出せる場合は、W&B API を介して登録済みのモデル Artifacts を利用できます。詳細は、以下のリソースを参照してください:

repository dispatch の詳細については、GitHub Marketplace の公式ドキュメントを参照してください。
Webhook Automations for Model Evaluation と Webhook Automations for Model Deployment の動画をご覧ください。これらの動画では、モデルの評価とデプロイ向けの automation を作成する方法を紹介しています。
モデル CI に GitHub Actions の webhook automation を使用する方法を示した W&B report Model CI/CD with W&Bをご確認ください。
Modal Labs webhook を使用したモデル CI の例については、wandb-modal-webhook GitHub repositoryを参照してください。

このペイロード例では、webhook を使用して Teams チャンネルに通知する方法を示します。

{
"@type": "MessageCard",
"@context": "http://schema.org/extensions",
"summary": "New Notification",
"sections": [
  {
    "activityTitle": "Notification from WANDB",
    "text": "This is an example message sent via Teams webhook.",
    "facts": [
      {
        "name": "Author",
        "value": "${event_author}"
      },
      {
        "name": "Event Type",
        "value": "${event_type}"
      }
    ],
    "markdown": true
  }
]
}

テンプレート文字列を使用すると、実行時に W&B データをペイロードへ挿入できます。Teams の例を参照してください。

このセクションは、過去の経緯を示す参考情報として掲載しています。webhook を使用して Slack と統合している場合、W&B では、代わりにSlack インテグレーションを使用するよう設定を更新することを推奨しています。

Slack API ドキュメントの手順に従って Slack アプリを設定し、incoming webhook インテグレーションを追加してください。Bot User OAuth Token に指定されているシークレットを、W&B webhook のアクセストークンとして使用していることを確認してください。以下はペイロードの例です。

{
    "text": "New alert from WANDB!",
"blocks": [
    {
            "type": "section",
        "text": {
            "type": "mrkdwn",
            "text": "Registry event: ${event_type}"
        }
    },
        {
            "type":"section",
            "text": {
            "type": "mrkdwn",
            "text": "New version: ${artifact_version_string}"
        }
        },
        {
        "type": "divider"
    },
        {
            "type": "section",
        "text": {
            "type": "mrkdwn",
            "text": "Author: ${event_author}"
        }
        }
    ]
}

webhook のトラブルシューティング

webhook が想定どおりに動作しない場合は、W&B App UI を使ってインタラクティブに、またはシェルスクリプトを使ってプログラムからトラブルシューティングできます。webhook は、作成時でも作成後でもトラブルシューティングできます。 W&B が POST リクエストに使用する形式の詳細については、Shell script タブを参照してください。

W&B App UI
Shell script

チーム管理者は、W&B App UI を使って webhook をインタラクティブにテストできます。

チームのページに移動し、Settings をクリックします。
Webhooks セクションまでスクロールします。
webhook の名前の横にある action () メニューをクリックします。
Test を選択します。
表示された UI パネルで、表示されたフィールドに POST リクエストを貼り付けます。
Test webhook をクリックします。W&B App UI 内に、エンドポイントからのレスポンスが表示されます。

デモについては、動画 Testing Webhooks in W&B をご覧ください。

このシェルスクリプトは、webhook オートメーションがトリガーされたときに W&B が送信するリクエストに近い POST リクエストを生成する方法の一例を示しています。以下のコードをシェルスクリプトにコピー＆ペーストして、webhook をトラブルシューティングしてください。以下の項目には独自の値を指定します。

ACCESS_TOKEN
SECRET
PAYLOAD
API_ENDPOINT

webhook_test.sh

#!/bin/bash

# access token とシークレット
ACCESS_TOKEN="your_api_key"
SECRET="your_api_secret"

# webhook エンドポイントの URL
API_ENDPOINT="https://your.webhook.endpoint/path"

# 送信するデータ（例: JSON 形式）
PAYLOAD='{"key1": "value1", "key2": "value2"}'

# HMAC 署名を生成します。セキュリティ上の理由から、W&B は
# ペイロードと、webhook に関連付けられた共有シークレットを基に計算した
# X-Wandb-Signature ヘッダーを、SHA-256 を使用する HMAC で付与します。
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

# cURL リクエストを実行します
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Wandb-Signature: $SIGNATURE" \
  -d "$PAYLOAD" "$API_ENDPOINT"

​Webhook を作成する

​オートメーション を作成する

​オートメーションの表示と管理

​ペイロード リファレンス

​ペイロード変数

​ペイロードの例

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

Webhook を作成する

オートメーションを作成する

オートメーションの表示と管理

ペイロードリファレンス

ペイロード変数

ペイロードの例

webhook のトラブルシューティング