跳至主要內容

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 Eval
「將 Trace 附加至 Braintrust Eval」的直接連結

當應用程式使用 Eval()、logger.traced() 或 currentSpan 時，請直接安裝 Braintrust SDK：

npm install braintrust@latest

在 Braintrust Eval() 或 logger.traced() 內執行 Mastra 時，請將 Braintrust logger 與 currentSpan resolver 傳給 Exporter。請從建立 Eval 或 traced span 的同一個 braintrust 套件 instance 匯入 currentSpan。

如果你的應用程式與 @mastra/braintrust 解析到不同的 Braintrust SDK 安裝副本，這能協助 Mastra 將其 span 附加至啟用中的 Braintrust span 下方。

Exporter 接受 Braintrust SDK v2 和 v3 中相容的 logger 與 span object。應用程式的 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 instance。上述 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 dependency 從 v2 升級至 v3，並使用 Nunjucks prompt template，請依照 Braintrust v2 至 v3 遷移指南操作。

使用傳回的 spanId 查詢 Braintrust
「querying-braintrust-with-returned-spanid」的直接連結

Mastra 會將其傳回的 spanId 同時作為 Braintrust row 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() 的最終 state、run.resume()）。

On this page