Aller au contenu principal

Exporter Braintrust

Braintrust est une plateforme d’évaluation et de surveillance qui vous aide à mesurer et à améliorer la qualité des applications LLM. L’exporter Braintrust envoie vos traces à Braintrust afin de permettre une évaluation, une notation et des expérimentations systématiques.

Installation
Lien direct vers Installation

npm install @mastra/braintrust@latest

Configuration
Lien direct vers Configuration

Prérequis
Lien direct vers Prérequis

  1. Compte Braintrust : inscrivez-vous sur braintrust.dev
  2. Projet : créez ou sélectionnez un projet pour vos traces
  3. Clé API : générez-la dans Braintrust Settings → API Keys
  4. Variables d’environnement : définissez vos identifiants :
.env
BRAINTRUST_API_KEY=sk-xxxxxxxxxxxxxxxx

# Optional
BRAINTRUST_ENDPOINT=https://api.braintrust.dev  # Custom endpoint if needed

Configuration automatique
Lien direct vers Configuration automatique

Une fois les variables d’environnement définies, utilisez l’exporter sans configuration :

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { BraintrustExporter } from '@mastra/braintrust'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      braintrust: {
        serviceName: 'my-service',
        exporters: [new BraintrustExporter()],
      },
    },
  }),
})

Configuration explicite
Lien direct vers Configuration explicite

Vous pouvez également transmettre les identifiants directement ; ils prévalent sur les variables d’environnement :

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { BraintrustExporter } from '@mastra/braintrust'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      braintrust: {
        serviceName: 'my-service',
        exporters: [
          new BraintrustExporter({
            apiKey: process.env.BRAINTRUST_API_KEY,
            projectName: 'my-project',
          }),
        ],
      },
    },
  }),
})

Configuration complète
Lien direct vers Configuration complète

new BraintrustExporter({
  // Required
  apiKey: process.env.BRAINTRUST_API_KEY!,

  // Optional settings
  projectName: 'my-project', // Default: 'mastra-tracing'
  endpoint: 'https://api.braintrust.dev', // Custom endpoint if needed
  logLevel: 'info', // Diagnostic logging: debug | info | warn | error
})

Associer les traces aux évaluations Braintrust
Lien direct vers Associer les traces aux évaluations Braintrust

Installez directement le SDK Braintrust lorsque votre application utilise Eval(), logger.traced() ou currentSpan :

npm install braintrust@latest

Lorsque vous exécutez Mastra dans Eval() ou logger.traced() de Braintrust, transmettez à l’exporter le logger Braintrust et la fonction de résolution currentSpan. Importez currentSpan depuis la même instance du package braintrust que celle qui crée l’évaluation ou le span tracé.

Cela permet à Mastra d’associer ses spans au span Braintrust actif lorsque votre application et @mastra/braintrust résolvent des copies installées différentes du SDK Braintrust.

L’exporter accepte les objets logger et span compatibles des versions 2 et 3 du SDK Braintrust. La version du SDK Braintrust de votre application ne doit pas nécessairement correspondre à celle installée par @mastra/braintrust.

src/mastra/index.ts
import { currentSpan, initLogger } from 'braintrust'
import { BraintrustExporter } from '@mastra/braintrust'

const logger = initLogger({
  projectName: 'my-project',
  apiKey: process.env.BRAINTRUST_API_KEY,
})

const exporter = new BraintrustExporter({
  braintrustLogger: logger,
  currentSpan,
})

Utilisez l’instance Mastra configurée dans la tâche d’évaluation Braintrust. La fonction de résolution currentSpan ci-dessus lit le span actif créé par Eval().

src/evals/braintrust.ts
import { Eval } from 'braintrust'
import { mastra } from '../mastra'

await Eval('my-project', {
  data: () => [{ input: 'Say hello', expected: 'Hello' }],
  task: async input => {
    const agent = mastra.getAgent('assistant')
    return (await agent.generate(input)).text
  },
  scores: [],
})

Si votre application met à niveau sa dépendance directe Braintrust de la v2 vers la v3 et utilise des modèles d’instructions Nunjucks, suivez le guide de migration de Braintrust v2 vers v3.

Interroger Braintrust avec le spanId renvoyé
Lien direct vers querying-braintrust-with-returned-spanid

Mastra utilise le spanId renvoyé à la fois comme ID de ligne et comme ID de span Braintrust. Utilisez-le pour rechercher le span Braintrust correspondant par id ou span_id.

Braintrust v3 stocke un ID de trace W3C distinct dans root_span_id ; le spanId renvoyé par Mastra n’est donc pas le root_span_id de Braintrust.

src/mastra/usage.ts
const result = await agent.stream('Summarize this ticket')

console.log('Mastra trace ID:', result.traceId)
console.log('Braintrust row and span ID:', result.spanId)

// Use result.spanId in your Braintrust lookup/query path

Il en va de même pour agent.generate() et les résultats d’exécution des Workflows (état final de run.start(), run.stream() et run.resume()).

On this page