Référencer des médias dans votre propre bucket (BYOB) à l’aide des spans d’agent

Utilisez cette technique lorsque le contenu multimédia que vous souhaitez voir dans Weave se trouve déjà dans votre propre bucket :

Des images issues d’un pipeline vidéo.
Des captures d’écran d’un agent de navigateur.
Des images qu’un modèle a enregistrées dans S3.

Au lieu de téléverser à nouveau ces octets dans Weave, vous journalisez l’URI de l’objet sous forme de string, et Weave affiche l’image ou la vidéo directement depuis votre bucket. Seule l’URI est envoyée à Weave ; les octets restent dans votre bucket. Journaliser une vidéo de 2 Go coûte autant que journaliser son chemin. Cela diffère du journal de contenus multimédias avec la Content API, qui lit les octets et les stocke dans Weave.

Il s’agit d’une fonctionnalité de Weave, distincte de BYOB de la plateforme (Secure Storage Connector), qui prend en charge le stockage des artefacts W&B et des runs. Les buckets de médias de référence sont configurés pour chaque équipe et nécessitent uniquement un accès en lecture.

Comment cela fonctionne

Le rendu des médias de référence fonctionne en trois étapes :

Vous stockez un objet multimédia dans votre bucket, par exemple s3://[YOUR-BUCKET]/frames/000123.png.
Vous journalisez cet URI sous forme de chaîne de caractères n’importe où dans une trace : en entrée ou en sortie d’une op, ou comme résultat d’un outil d’agent. Le nom du champ n’a pas d’importance.
Lorsque vous ouvrez la trace, Weave résout l’URI en une URL présignée à durée de vie limitée et l’affiche directement dans la page. L’extension du fichier détermine le mode de rendu. Les formats d’image courants (tels que .png, .jpg, .gif) et les formats vidéo (tels que .mp4, .mov, .webm) s’affichent directement dans la page. Les autres formats s’affichent sous forme de lien de téléchargement.

Weave résout uniquement les URI qui pointent vers un bucket enregistré pour votre équipe. Les schémas pris en charge sont s3:// et gs://.

Prérequis

Cette fonctionnalité est prise en charge uniquement dans le Cloud mutualisé de W&B.
Un compte W&B et une clé API.
Un bucket de stockage cloud que vous contrôlez (S3 ou GCS), contenant au moins un objet.
Des autorisations d’administrateur de l’organisation. L’ajout d’un bucket de référence nécessite les mêmes autorisations que la création d’une équipe dans l’organisation.

Configurez votre bucket

Accordez à W&B un accès en lecture au bucket et autorisez le navigateur à récupérer les objets avec CORS. Lorsque vous affichez une trace, W&B génère une URL de téléchargement pré-signée de courte durée pour chaque objet référencé. Accordez au principal de l’intégration W&B un accès en lecture au bucket afin que la génération de ces URL pré-signées fonctionne. Il s’agit d’un accès en lecture seule pour l’affichage intégré.

AWS S3
Google Cloud Storage

Appliquez une stratégie de bucket qui accorde s3:GetObject au principal de l’intégration W&B. Enregistrez le contenu suivant dans bucket-policy.json, en remplaçant [YOUR-BUCKET] par le nom de votre bucket :

{
  "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]/*"
  }]
}

Appliquez-la ensuite à votre bucket :

aws s3api put-bucket-policy --bucket [YOUR-BUCKET] --policy file://bucket-policy.json

Appliquez une configuration CORS afin que l’application puisse récupérer les objets dans le navigateur. Enregistrez le contenu suivant dans cors.json :

{
  "CORSRules": [{
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedOrigins": ["https://wandb.ai"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3000
  }]
}

Appliquez-la ensuite à votre bucket :

aws s3api put-bucket-cors --bucket [YOUR-BUCKET] --cors-configuration file://cors.json

Si un objet est chiffré avec une clé KMS gérée par le client, la stratégie de cette clé doit également accorder kms:Decrypt à arn:aws:iam::725579432336:role/WandbIntegration. La stratégie de bucket seule ne suffit pas.

Accordez au compte de service de l’intégration W&B le rôle roles/storage.objectViewer sur le bucket. Remplacez [YOUR-BUCKET] par le nom de votre bucket :

gcloud storage buckets add-iam-policy-binding gs://[YOUR-BUCKET] \
  --member="serviceAccount:wandb-integration@wandb-production.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

Appliquez une configuration CORS afin que l’application puisse récupérer les objets dans le navigateur. Enregistrez le contenu suivant dans cors.json :

[{
  "origin": ["https://wandb.ai"],
  "method": ["GET", "HEAD"],
  "responseHeader": ["ETag"],
  "maxAgeSeconds": 3000
}]

Appliquez-la ensuite à votre bucket :

gcloud storage buckets update gs://[YOUR-BUCKET] --cors-file=cors.json

À ce stade, W&B peut lire les objets de votre bucket, et l’interface Weave peut les récupérer dans le navigateur.

Enregistrer le bucket de référence

Enregistrez le bucket dans les paramètres de l’équipe afin que Weave puisse générer des URL présignées et afficher les URI référencées.

Accédez à la page des paramètres de l’équipe (https://wandb.ai/[YOUR-TEAM]/settings).
Dans la section Reference buckets, sélectionnez Add bucket.
Sélectionnez votre fournisseur de cloud (AWS ou Google Cloud).
Pour le nom du bucket, saisissez uniquement [YOUR-BUCKET] — sans le préfixe s3:// ou gs://.
Pour la clé de l’objet, saisissez la clé d’un objet existant dans le bucket, par exemple photos/cat.png (la clé de l’objet uniquement, pas une URL complète). W&B lit cet objet pour confirmer qu’il dispose d’un accès en lecture et que CORS est correctement configuré. Cette vérification porte uniquement sur l’accès ; une fois celle-ci effectuée, la présignature fonctionne pour n’importe quel objet du bucket.
Si vous le souhaitez, sélectionnez Test connection pour valider la configuration sans l’enregistrer.
Sélectionnez Add bucket pour enregistrer.

Boîte de dialogue Add reference bucket dans les paramètres de l’équipe, avec des champs pour le fournisseur de cloud, le nom du bucket et la clé d’un objet existant, ainsi que les boutons Test connection et Add bucket.

Tant que le bucket n’est pas enregistré, les URI référencées ne s’affichent pas. C’est l’enregistrement qui permet à Weave de présigner et d’afficher l’objet.

Consigner une référence de média à l’aide de spans d’agent

Renvoyez un URI de bucket comme résultat d’un outil d’agent, et Weave l’affiche directement dans la vue Agents, sur l’appel d’outil qui l’a produit. L’exemple suivant ouvre une conversation, un tour de conversation et un span d’outil, puis définit un URI de bucket comme résultat de l’outil. Remplacez [YOUR-TEAM], [YOUR-PROJECT] et [YOUR-BUCKET] par vos propres valeurs.

Python
TypeScript

import weave

weave.init("[YOUR-TEAM]/[YOUR-PROJECT]")

# Un outil qui renvoie un objet déjà présent dans votre bucket.
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:
            # Le résultat est une chaîne URI de bucket ; elle s'affiche directement dans la vue Agents.
            tool.result = get_frame(123)

import * as weave from 'weave';

await weave.init('[YOUR-TEAM]/[YOUR-PROJECT]');

// Un outil qui renvoie un objet déjà présent dans votre bucket.
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',
});
// Le résultat est une chaîne URI de bucket ; elle s'affiche directement dans la vue Agents.
tool.result = getFrame(123);
tool.end();
turn.end();
conversation.end();

Cet exemple utilise les spans d’agent Weave. Pour la configuration complète sur plusieurs tours de conversation, y compris les appels LLM et une boucle d’agent complète, voir le démarrage rapide des agents personnalisés.

Afficher la référence dans Weave Agents

Ouvrez la conversation à partir du lien affiché par weave.init(). L’image ou la vidéo référencée s’affiche directement dans la vue Agents, au niveau de l’appel d’outil qui a renvoyé l’URI. Si Weave ne parvient pas à résoudre une URI, par exemple parce que l’objet est introuvable ou que le bucket n’est pas enregistré, il affiche simplement la chaîne URI brute.

Une image référencée s'affiche directement dans un appel d'outil de la vue Weave Agents, résolue à partir d'un URI de bucket pointant vers un objet dans votre propre bucket cloud.

Premiers pas

Guides

Guides pratiques

Référence

Détails et assistance

Référencer des médias dans votre propre bucket (BYOB) à l’aide des spans d’agent

Comment cela fonctionne

Prérequis

Configurez votre bucket

Enregistrer le bucket de référence

Consigner une référence de média à l’aide de spans d’agent

Afficher la référence dans Weave Agents

​Comment cela fonctionne

​Prérequis

​Configurez votre bucket

​Enregistrer le bucket de référence

​Consigner une référence de média à l’aide de spans d’agent

​Afficher la référence dans Weave Agents

Comment cela fonctionne

Prérequis

Configurez votre bucket

Enregistrer le bucket de référence

Consigner une référence de média à l’aide de spans d’agent

Afficher la référence dans Weave Agents