> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# エージェント スパンを使って独自のバケット内のメディアを参照する（BYOB）

> エージェントのツール スパンから URI を返すことで、独自のクラウド バケットに保存された画像や動画を、ファイルのバイトデータを Weave に取り込まずに Weave の Agents ビューでレンダリングできます。

Weave で表示したいメディアがすでに独自のバケットに保存されている場合は、この手法を使用します。例:

* 動画パイプラインのフレーム
* ブラウザーエージェントのスクリーンショット
* モデルが S3 に書き込んだ画像

これらのバイトを Weave に再アップロードする代わりに、オブジェクトの URI を string としてログすると、Weave がバケットから画像や動画をインラインでレンダリングします。Weave に送信されるのは URI のみで、バイトデータはバケット内に残ります。2 GB の動画をログする場合でも、コストはパスをログする場合と変わりません。

これは、[Content API](https://docs.coreweave.com/ja/products/wandb/weave/guides/core-types/media.md#contents-api) を使用したメディアのログとは異なります。Content API ではバイトデータを読み取り、Weave に保存します。

> [!NOTE]
>
> これは Weave のフィーチャーであり、W\&B のアーティファクトおよび run のストレージに使用される [プラットフォーム BYOB (セキュアストレージコネクタ) ](https://docs.coreweave.com/ja/products/wandb/platform/hosting/data-security/secure-storage-connector.md) とは別のものです。参照メディア用のバケットはチームごとに設定し、必要なのは読み取りアクセス権のみです。

## 仕組み

参照メディアのレンダリングは、次の 3 つのステップで行われます。

1. メディアオブジェクトをバケットに保存します (例: `s3://[YOUR-BUCKET]/frames/000123.png`) 。
2. その URI を string 値として、トレース内の任意の場所 (Op の入力や出力、エージェントのツール結果など) にログします。フィールド名は問いません。
3. トレースを開くと、Weave が URI を有効期間の短い[事前署名付き URL](https://docs.coreweave.com/ja/products/wandb/platform/hosting/data-security/presigned-urls.md) に解決し、インラインでレンダリングします。レンダリング方法はファイル拡張子によって決まります。一般的な画像形式 (`.png`、`.jpg`、`.gif` など) や動画形式 (`.mp4`、`.mov`、`.webm` など) はインラインでレンダリングされ、それ以外の形式はダウンロードリンクとして表示されます。

Weave が解決するのは、チームに登録されたバケットを指す URI のみです。サポートされるスキームは `s3://` と `gs://` です。

## 前提条件

* このフィーチャーは [W\&B Multi-tenant Cloud](https://docs.coreweave.com/ja/products/wandb/platform/hosting/hosting-options/multi_tenant_cloud.md) でサポートされています。[専用クラウド](https://docs.coreweave.com/ja/products/wandb/platform/hosting/hosting-options/dedicated-cloud.md) および [セルフマネージド](https://docs.coreweave.com/ja/products/wandb/platform/hosting/hosting-options/self-managed.md) v0.84.0 以降では、プレビューとして提供されています。
* CoreWeave Forge アカウントと [APIキー](https://forge.coreweave.com/settings#apikeys)。
* 自身が管理するクラウドストレージバケット (S3 または GCS)。バケットには 1 つ以上のオブジェクトが含まれている必要があります。
* 組織管理者の権限。参照バケットの追加には、組織内でのチーム作成と同じ権限が必要です。

## バケットを設定する

W\&B にバケットへの読み取りアクセス権を付与し、ブラウザーが CORS を使用してオブジェクトを取得できるようにします。

トレースを表示すると、W\&B は参照されている各オブジェクトについて、有効期間の短い署名付きダウンロード URL を生成します。署名付き URL を正しく生成できるよう、W\&B インテグレーションのプリンシパルにバケットへの読み取りアクセス権を付与してください。このアクセス権は、インラインでのレンダリングに使用する読み取り専用のものです。

> [tab] AWS S3
>
> 1. W\&B インテグレーションのプリンシパルに `s3:GetObject` を付与するバケットポリシーを適用します。以下の内容を `bucket-policy.json` として保存し、`[YOUR-BUCKET]` を実際のバケット名に置き換えます。
>
>    ```json lines theme={"system"}
>    {
>      "Version": "2012-10-17",
>      "Id": "WandBAccess",
>      "Statement": [{
>        "Sid": "WandbAccess",
>        "Effect": "Allow",
>        "Principal": {"AWS": "arn:aws:iam::725579432336:role/WandbIntegration"},
>        "Action": "s3:GetObject",
>        "Resource": "arn:aws:s3:::[YOUR-BUCKET]/*"
>      }]
>    }
>    ```
>
>    次に、このポリシーをバケットに適用します。
>
>    ```bash theme={"system"}
>    aws s3api put-bucket-policy --bucket [YOUR-BUCKET] --policy file://bucket-policy.json
>    ```
>
> 2. アプリがブラウザーでオブジェクトを取得できるように、CORS 設定を適用します。以下の内容を `cors.json` として保存します。
>
>    ```json lines theme={"system"}
>    {
>      "CORSRules": [{
>        "AllowedHeaders": ["*"],
>        "AllowedMethods": ["GET", "HEAD"],
>        "AllowedOrigins": ["https://forge.coreweave.com"],
>        "ExposeHeaders": ["ETag"],
>        "MaxAgeSeconds": 3000
>      }]
>    }
>    ```
>
>    次に、この設定をバケットに適用します。
>
>    ```bash theme={"system"}
>    aws s3api put-bucket-cors --bucket [YOUR-BUCKET] --cors-configuration file://cors.json
>    ```
>
> > [!NOTE]
> >
> > オブジェクトがカスタマー管理の KMS キーで暗号化されている場合は、そのキーポリシーでも `arn:aws:iam::725579432336:role/WandbIntegration` に `kms:Decrypt` を付与する必要があります。バケットポリシーだけでは不十分です。

> [tab] Google Cloud Storage
>
> 1. W\&B インテグレーションのサービスアカウントに、バケットに対する `roles/storage.objectViewer` を付与します。`[YOUR-BUCKET]` は実際のバケット名に置き換えてください。
>
>    ```bash theme={"system"}
>    gcloud storage buckets add-iam-policy-binding gs://[YOUR-BUCKET] \
>      --member="serviceAccount:wandb-integration@wandb-production.iam.gserviceaccount.com" \
>      --role="roles/storage.objectViewer"
>    ```
>
> 2. アプリがブラウザーでオブジェクトを取得できるように、CORS 設定を適用します。以下の内容を `cors.json` として保存します。
>
>    ```json lines theme={"system"}
>    [{
>      "origin": ["https://forge.coreweave.com"],
>      "method": ["GET", "HEAD"],
>      "responseHeader": ["ETag"],
>      "maxAgeSeconds": 3000
>    }]
>    ```
>
>    次に、この設定をバケットに適用します。
>
>    ```bash theme={"system"}
>    gcloud storage buckets update gs://[YOUR-BUCKET] --cors-file=cors.json
>    ```

これで、Weight & Biases がバケットからオブジェクトを読み取れるようになり、UI でもブラウザー上でオブジェクトを取得できるようになります。

## 参照バケットを登録する

Weave が参照先の URI の署名付き URL を生成して表示できるように、チーム設定でバケットを登録します。

1. チーム設定ページ (`https://forge.coreweave.com/wandb/[YOUR-TEAM]/settings`) に移動します。
2. **Reference buckets** セクションで、**Add bucket** を選択します。
3. クラウドプロバイダー (**AWS** または **Google Cloud**) を選択します。
4. バケット名には、`s3://` や `gs://` の接頭辞を付けずに `[YOUR-BUCKET]` のみを入力します。
5. オブジェクトキーには、バケット内の既存オブジェクトのキーを入力します (例: `photos/cat.png`) 。完全な URL ではなく、オブジェクトキーのみを入力してください。W\&B はこのオブジェクトを 1 つ読み取り、読み取りアクセス権があることと、CORS が正しく設定されていることを確認します。この確認はアクセスをチェックするためだけのものです。検証が完了すると、バケット内のどのオブジェクトに対しても署名付き URL を生成できます。
6. 必要に応じて **Test connection** を選択し、保存せずに設定を検証します。
7. **Add bucket** を選択して保存します。

![チーム設定の「Add reference bucket」ダイアログ。クラウドプロバイダー、バケット名、既存のオブジェクトキーの各フィールドと、Test connection ボタンおよび Add bucket ボタンが表示されています。](https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/weave/_media/add-ref-bucket.png?fit=max\&auto=format\&n=3Dv_sw2eg8feUJlx\&q=85\&s=7ab906b46a48b51e085530aaaf1e47a4)

> [!WARNING]
>
> バケットを登録するまで、参照先の URI はレンダリングされません。Weave がオブジェクトの署名付き URL を生成して表示するには、登録が必要です。

## エージェント スパンを使用してメディア参照をログする

バケット URI をエージェントのツール結果として返すと、その結果を生成したツール呼び出しの箇所に、Weave が **Agents** ビューでインライン表示します。次の例では、会話、ターン、ツール スパンを開始し、バケット URI をツールの結果に設定します。`[YOUR-TEAM]`、`[YOUR-PROJECT]`、`[YOUR-BUCKET]` をそれぞれ実際の値に置き換えてください。

> [tab] Python
>
> ```python lines theme={"system"}
> import weave
>
> weave.init("[YOUR-TEAM]/[YOUR-PROJECT]")
>
> # バケット内にすでに存在するオブジェクトを返すツール。
> def get_frame(frame_id: int) -> str:
>     return f"s3://[YOUR-BUCKET]/frames/{frame_id:06d}.png"
>
> with weave.start_conversation(agent_name="frame-labeler") as conversation:
>     with weave.start_turn(user_message="Show me frame 123", model="gpt-4o-mini"):
>         with weave.start_tool(
>             name="get_frame",
>             arguments='{"frame_id": 123}',
>             tool_call_id="call_1",
>         ) as tool:
>             # 結果はバケットの URI 文字列で、Agents ビューにインラインでレンダリングされます。
>             tool.result = get_frame(123)
> ```

> [tab] TypeScript
>
> ```typescript lines theme={"system"}
> import * as weave from 'weave';
>
> await weave.init('[YOUR-TEAM]/[YOUR-PROJECT]');
>
> // バケット内にすでに存在するオブジェクトを返すツール。
> function getFrame(frameId: number): string {
>   return `s3://[YOUR-BUCKET]/frames/${String(frameId).padStart(6, '0')}.png`;
> }
>
> const conversation = weave.startConversation({agentName: 'frame-labeler'});
> const turn = weave.startTurn({model: 'gpt-4o-mini'});
> const tool = weave.startTool({
>   name: 'getFrame',
>   args: JSON.stringify({frameId: 123}),
>   toolCallId: 'call_1',
> });
> // 結果はバケットの URI 文字列で、Agents ビューにインラインでレンダリングされます。
> tool.result = getFrame(123);
> tool.end();
> turn.end();
> conversation.end();
> ```

> [!NOTE]
>
> この例では Weave のエージェント スパンを使用しています。LLM Call と一連のエージェント処理を含む、マルチターンの設定全体については、[カスタムエージェントのクイックスタート](https://docs.coreweave.com/ja/products/wandb/weave/custom-agents-quickstart.md)を参照してください。

## Weave Agents で参照先を表示する

`weave.init()` が出力するリンクから会話を開きます。参照先の画像や動画は、URI を返したツール呼び出しの箇所に、**Agents** ビュー内でインライン表示されます。オブジェクトが見つからない、バケットが登録されていないなどの理由で Weave が URI を解決できない場合は、URI 文字列がそのまま表示されます。

![自身のクラウドバケット内のオブジェクトを指すバケット URI から解決され、Weave Agents ビューのツール呼び出しの箇所にインライン表示された参照先の画像。](https://mintcdn.com/coreweave-dbfa0e8d/9_FzAXvhewsuA_5Y/products/wandb/weave/_media/agents-byob.png?fit=max\&auto=format\&n=9_FzAXvhewsuA_5Y\&q=85\&s=d07e8b04924f51f79cd1fd7864c15d43)
