跳到主要内容

Braintrust exporter

Braintrust 是一个评估和监控平台，可帮助你衡量并提升 LLM 应用质量。Braintrust exporter 会将 Trace 发送到 Braintrust，以支持系统化评估、评分和实验。

安装
安装的直接链接

npm install @mastra/braintrust@latest

配置
配置的直接链接

前提条件
前提条件的直接链接

  1. Braintrust 账户：在 braintrust.dev 注册
  2. 项目：为 Trace 创建或选择一个项目
  3. API key：在 Braintrust Settings → API Keys 中生成
  4. 环境变量：设置凭据：
.env
BRAINTRUST_API_KEY=sk-xxxxxxxxxxxxxxxx

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

零配置设置
零配置设置的直接链接

设置环境变量后，无需任何配置即可使用 exporter：

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()],
      },
    },
  }),
})

显式配置
显式配置的直接链接

你也可以直接传入凭据（优先于环境变量）：

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',
          }),
        ],
      },
    },
  }),
})

完整配置
完整配置的直接链接

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
})

将 Trace 附加到 Braintrust Evals
将 Trace 附加到 Braintrust Evals的直接链接

如果应用使用 Eval()、logger.traced() 或 currentSpan，请直接安装 Braintrust SDK：

npm install braintrust@latest

在 Braintrust Eval() 或 logger.traced() 中运行 Mastra 时，请将 Braintrust logger 和 currentSpan resolver 传给 exporter。从创建 eval 或 traced span 的同一个 braintrust 软件包实例导入 currentSpan。

如果应用与 @mastra/braintrust 解析到不同的 Braintrust SDK 安装副本，这有助于 Mastra 将自己的 span 附加到活跃的 Braintrust span 下。

Exporter 接受与 Braintrust SDK v2 和 v3 兼容的 logger 和 span 对象。应用的 Braintrust SDK 版本无需与 @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,
})

在 Braintrust eval task 中使用配置好的 Mastra 实例。上面的 currentSpan resolver 会读取 Eval() 创建的活跃 span。

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: [],
})

如果应用将直接依赖的 Braintrust 从 v2 升级到 v3，并使用 Nunjucks prompt 模板，请遵循 Braintrust v2 到 v3 迁移指南。

使用返回的 spanId 查询 Braintrust
querying-braintrust-with-returned-spanid的直接链接

Mastra 会将返回的 spanId 同时用作 Braintrust 行 ID 和 span ID。可通过 id 或 span_id 用它查找对应的 Braintrust span。

Braintrust v3 会在 root_span_id 中存储单独的 W3C Trace ID，因此 Mastra 返回的 spanId 并不是 Braintrust root_span_id。

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

这同样适用于 agent.generate() 和 Workflow 运行结果（run.start()、run.stream() 最终状态、run.resume()）。

On this page