Définir et journaliser des attributs

Cette page décrit les attributs des fonctions tracées avec le décorateur @weave.op. Si vous instrumentez un agent avec le SDK d’agent Weave, définissez plutôt des attributs et des événements sur les spans d’agent (Turn, LLM, Tool et SubAgent). Voir Définir des attributs et des événements sur les spans d’agent.

Dans Weave, les attributs vous permettent d’associer des métadonnées personnalisées à vos traces et évaluations. Ces métadonnées peuvent inclure des informations comme des noms d’environnement, des versions de modèle, des ID d’expérience, des ID d’utilisateur ou d’autres informations contextuelles pour vous aider à organiser, filtrer et analyser vos données Weave. Les attributs sont particulièrement utiles pour regrouper ou filtrer les traces en fonction des éléments suivants :

Déploiements
tenants
Experiments

Weave propose deux façons d’ajouter des attributs :

Attributs par appel : utilisez le gestionnaire de contexte weave.attributes() pour ajouter des métadonnées à des opérations spécifiques ou à des blocs de code.
Attributs globaux : utilisez le champ global_attributes pour définir des attributs lors de l’initialisation, qui s’appliquent à toutes les traces et évaluations de votre projet.

Vous pouvez afficher tous les attributs journalisés au cours des traces et des évaluations dans l’interface utilisateur. Vous pouvez ensuite les utiliser pour filtrer et regrouper les données. Ce guide s’adresse aux utilisateurs de Weave qui souhaitent enrichir leurs traces et évaluations avec des métadonnées personnalisées. Il explique comment associer des attributs à des appels individuels, définir des valeurs par défaut à l’échelle du projet lors de l’initialisation, combiner les deux approches et lire l’ensemble actuel d’attributs pendant l’exécution.

Attributs par appel

Le gestionnaire de contexte weave.attributes() vous permet d’ajouter des métadonnées à des opérations tracées spécifiques. Utilisez-le pour associer des informations contextuelles à certains appels de fonction ou runs d’évaluation.

Vous ne pouvez pas modifier call.attributes une fois l’appel démarré. Utilisez ce gestionnaire de contexte pour définir les métadonnées avant d’appeler l’op.

Python
TypeScript

import weave

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

@weave.op
def my_function(name: str):
    return f"Hello, {name}!"

# Ajouter des attributs à un appel spécifique
with weave.attributes({'env': 'production', 'user_id': '12345'}):
    result = my_function("World")

import {init, op, withAttributes} from 'weave';

async function main() {
  await init('your-team/attribute-example');

  const myFunction = op(async function myFunction(name: string) {
    return `Hello, ${name}!`;
  });

  // Ajouter des attributs à un appel spécifique
  const result = await withAttributes(
    {env: 'production', user_id: '12345'},
    async () => myFunction('World')
  );

  console.log('Result:', result);
}

main().catch(console.error);

Cette fonction associe les attributs à toutes les opérations tracées dans le bloc du gestionnaire de contexte (Python) ou dans la fonction de rappel (TypeScript). Vous pouvez également imbriquer des contextes weave.attributes(). Les contextes internes redéfinissent les contextes externes pour les mêmes clés :

Python
TypeScript

@weave.op
def process_data(data: str):
    return data.upper()

# Contexte externe
with weave.attributes({
    "env": "production",
    "version": "1.0.0",
    "region": "us-west-2"
}):
    process_data("hello")  # Contient les trois attributs
    
    # Le contexte interne redéfinit 'version'
    with weave.attributes({
        "version": "1.1.0",
        "experiment": "exp-456"
    }):
        process_data("world")  # Contient env='production', version='1.1.0', region='us-west-2', experiment='exp-456'

import {init, op, withAttributes} from 'weave';

async function main() {
  await init('your-team/attribute-example');

  const processData = op(async function processData(data: string) {
    return data.toUpperCase();
  });
  
  // Contexte externe
  await withAttributes(
    {
      env: 'production',
      version: '1.0.0',
      region: 'us-west-2'
    },
    async () => {
      await processData('hello');  // Contient les trois attributs
      
      // Le contexte interne redéfinit 'version'
      await withAttributes(
        {
          version: '1.1.0',
          experiment: 'exp-456'
        },
        async () => {
          await processData('world');  // Contient env='production', version='1.1.0', region='us-west-2', experiment='exp-456'
        }
      );
    }
  );
}

main().catch(console.error);

Attributs globaux

Lorsque vous définissez des attributs globaux lors de l’initialisation de Weave, ils s’appliquent automatiquement à toutes les traces et évaluations de votre projet. Cela permet de propager des métadonnées à l’échelle du projet, comme l’environnement, la version du déploiement ou les informations de l’équipe.

Python
TypeScript

import weave

weave.init(
    "my-project",
    global_attributes={
        "env": "production",
        "app_version": "2.1.0",
        "region": "us-west-2",
        "team": "ml-platform"
    }
)

# Le dictionnaire global_attributes applique désormais ces attributs à toutes les opérations suivantes
@weave.op
def my_function():
    return "Hello"

my_function()  # Inclut automatiquement tous les attributs globaux

# Les évaluations reçoivent également les attributs globaux
evaluation = weave.Evaluation(dataset=examples, scorers=[scorer])
asyncio.run(evaluation.evaluate(model))  # Inclut tous les attributs globaux

import {init, op, withAttributes} from 'weave';

async function main() {
    await init('your-team/attribute-example', {
        globalAttributes: {
            env: 'production',
            app_version: '2.1.0',
            region: 'us-west-2',
            team: 'ml-platform'
        }
    });
    
    // L'objet globalAttributes applique désormais ces attributs à toutes les opérations suivantes
    const myFunction = op(async function myFunction() {
        return 'Hello';
    });
    
    const result = await myFunction();  // Inclut automatiquement tous les attributs globaux
    console.log('Result:', result);
}
main().catch(console.error);

Combiner les attributs globaux et les attributs par appel

Vous pouvez utiliser à la fois des attributs globaux et des attributs par appel. Les attributs par appel ayant la même clé redéfinissent les attributs globaux :

Python
TypeScript

import weave

# Définir des attributs globaux
weave.init(
    "my-project",
    global_attributes={
        "env": "production",
        "app_version": "2.1.0"
    }
)

@weave.op
def process(data: str):
    return data

# Cet appel a : env='production', app_version='2.1.0'
process("test1")

# Cet appel a : env='staging', app_version='2.1.0', experiment='A'
with weave.attributes({'env': 'staging', 'experiment': 'A'}):
    process("test2")

import {init, op, withAttributes} from 'weave';

async function main() {
    // Définir des attributs globaux
    await init('your-team/attribute-example', {
    globalAttributes: {
        env: 'production',
        app_version: '2.1.0'
    }
    });

    const process = op(async function process(data: string) {
    return data;
    });

    // Cet appel a : env='production', app_version='2.1.0'
    await process('test1');

    // Cet appel a : env='staging', app_version='2.1.0', experiment='A'
    await withAttributes(
    {env: 'staging', experiment: 'A'},
    async () => process('test2')
    );
}
main().catch(console.error);

Obtenir les attributs pendant l’exécution

Au moment de l’exécution, vous pouvez inspecter les attributs en vigueur pour un Appel. Cela est utile lorsque vous souhaitez déboguer les métadonnées que Weave associe, ou lorsque votre code doit se brancher en fonction d’informations contextuelles définies par un appelant externe.

Python
TypeScript

L’exemple suivant configure le décorateur Weave pour journaliser la fonction process_data, définit les attributs à journaliser, puis les renvoie lors de l’exécution.

import weave

weave.init("your-team/your-project")

@weave.op
def process_data(data: str):
    # Obtenir l'appel courant à l'intérieur de l'op
    call = weave.get_current_call()
    if call:
        print(f"Attributes: {call.attributes}")
    return data.upper()

# Définir les attributs et exécuter la fonction
with weave.attributes({
    "env": "production",
    "version": "1.0.0",
    "region": "us-west-2"
}):
    process_data("hello")
    
    with weave.attributes({
        "version": "1.1.0",
        "experiment": "exp-456"
    }):
        process_data("world")

Cela produit la sortie suivante :

Attributes: {'env': 'production', 'version': '1.0.0', 'region': 'us-west-2'}
Attributes: {'env': 'production', 'version': '1.1.0', 'region': 'us-west-2', 'experiment': 'exp-456'}

weave.get_current_call() ne fonctionne qu’à l’intérieur d’une fonction décorée avec @weave.op. En dehors d’un op, il renvoie None.

Avec le SDK TypeScript de Weave, vous pouvez récupérer les attributs courants via client.getCurrentAttributes(). Contrairement au SDK Python de Weave, vous pouvez accéder aux attributs TypeScript dans un contexte withAttributes(), et pas uniquement à l’intérieur d’un op.

import * as weave from 'weave';
import { withAttributes } from 'weave';

async function main() {
  const client = await weave.init('your-team/your-project');

  const processData = weave.op(async function processData(data: string) {
    // Vous pouvez également accéder aux attributs à l'intérieur d'un op
    const attrs = client.getCurrentAttributes();
    console.log('Attributes inside op:', attrs);
    return data.toUpperCase();
  });

  // Définir les attributs et exécuter la fonction
  await withAttributes(
    {
      env: 'production',
      version: '1.0.0',
      region: 'us-west-2'
    },
    async () => {
      // Récupérer les attributs depuis n'importe quel endroit dans le contexte
      console.log('Current attributes:', client.getCurrentAttributes());
      await processData('hello');

      await withAttributes(
        {
          version: '1.1.0',
          experiment: 'exp-456'
        },
        async () => {
          console.log('Nested attributes:', client.getCurrentAttributes());
          await processData('world');
        }
      );
    }
  );
}

main().catch(console.error);

Cela produit la sortie suivante :

Current attributes: { env: 'production', version: '1.0.0', region: 'us-west-2' }
Attributes inside op: { env: 'production', version: '1.0.0', region: 'us-west-2' }
Nested attributes: { env: 'production', version: '1.1.0', region: 'us-west-2', experiment: 'exp-456' }
Attributes inside op: { env: 'production', version: '1.1.0', region: 'us-west-2', experiment: 'exp-456' }

Premiers pas

Guides

Guides pratiques

Référence

Détails et assistance

Attributs par appel

Attributs globaux

Combiner les attributs globaux et les attributs par appel

Obtenir les attributs pendant l’exécution

​Attributs par appel

​Attributs globaux

​Combiner les attributs globaux et les attributs par appel

​Obtenir les attributs pendant l’exécution

Attributs par appel

Attributs globaux

Combiner les attributs globaux et les attributs par appel

Obtenir les attributs pendant l’exécution