> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# Braintrust exporter

[Braintrust](https://www.braintrust.dev/) 是一個評估及監察平台，助你衡量並改善 LLM 應用程式的質素。Braintrust exporter 會將你的 Trace 傳送至 Braintrust，讓你能夠有系統地進行評估、評分及實驗。

## 安裝

**npm**:

```bash
npm install @mastra/braintrust@latest
```

**pnpm**:

```bash
pnpm add @mastra/braintrust@latest
```

**Yarn**:

```bash
yarn add @mastra/braintrust@latest
```

**Bun**:

```bash
bun add @mastra/braintrust@latest
```

## 配置

### 先決條件

1. **Braintrust 帳戶**：在 [braintrust.dev](https://www.braintrust.dev/) 註冊
2. **項目**：為你的 Trace 建立或選擇項目
3. **API 金鑰**：在 Braintrust Settings → API Keys 中產生
4. **環境變數**：設定你的憑證：

```bash
BRAINTRUST_API_KEY=sk-xxxxxxxxxxxxxxxx

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

### 零配置設定

設定環境變數後，無須任何配置即可使用 exporter：

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

### 明確配置

你亦可以直接傳入憑證（優先於環境變數）：

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

### 完整配置

```typescript
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

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

**npm**:

```bash
npm install braintrust@latest
```

**pnpm**:

```bash
pnpm add braintrust@latest
```

**Yarn**:

```bash
yarn add braintrust@latest
```

**Bun**:

```bash
bun add braintrust@latest
```

在 Braintrust `Eval()` 或 `logger.traced()` 內執行 Mastra 時，請將 Braintrust logger 及 `currentSpan` resolver 傳入 exporter。請匯入 `currentSpan`，並確保它來自建立 eval 或 traced span 的同一個 `braintrust` 套件實例。

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

exporter 接受來自 Braintrust SDK v2 及 v3 的兼容 logger 和 span 物件。你應用程式使用的 Braintrust SDK 版本無須與 `@mastra/braintrust` 安裝的版本一致。

```typescript
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 任務中使用已配置的 Mastra 實例。上述 `currentSpan` resolver 會讀取由 `Eval()` 建立的使用中 span。

```typescript
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 遷移指南](https://www.braintrust.dev/docs/sdks/typescript/migrations/v2-to-v3)。

## 使用傳回的 `spanId` 查詢 Braintrust

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`。

```typescript
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()`）。

## 相關內容

- [Tracing 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)
- [Braintrust 文件](https://www.braintrust.dev/docs)