第八章评估与可观测性

8.1 为什么需要评估？

AI 应用最大的挑战之一：不确定性。同一个 Prompt，不同时间可能产出不同结果。如何保障质量？靠评估（Evals）。

Mastra 的评估系统有两个核心场景：

开发阶段：用评估指标衡量 Agent 输出质量，调优 Prompt 和模型
生产阶段：对线上流量采样评估，持续监控 Agent 表现

8.2 评估基本概念

Scorers（评分器）

评分器是评估的最小单元，给 Agent 的输出打分。Mastra 内置了主要类别的评分器：

@mastra/evals
├── 文本质量类
│   ├── ContentSimilarityScorer  # 内容相似度
│   ├── CompletenessScorer       # 完整性
│   ├── ToneConsistencyScorer    # 语气一致性
│   └── TextualDifferenceScorer  # 文本差异
├── 分类与 NLI 类
│   ├── ClassificationScorer     # 分类准确度
│   └── EntailmentScorer         # 蕴含关系
├── Prompt 工程类
│   ├── PromptAlignmentScorer    # Prompt 对齐度
│   ├── HallucinationScorer      # 幻觉检测
│   ├── FaithfulnessScorer       # 忠实度
│   ├── ContextRelevancyScorer   # 上下文相关性
│   ├── ContextPrecisionScorer   # 上下文精确度
│   ├── ContextPositionScorer    # 上下文位置
│   ├── AnswerRelevancyScorer    # 答案相关性
│   ├── SummarizationScorer      # 摘要质量
│   └── BiasScorer               # 偏见检测
└── 自定义
    └── 你可以自己写任何评分逻辑

评估类型

类型	说明	使用场景
Live Evals	对线上流量实时评估	生产监控
Trace Evals	对历史 Trace 批量评估	批量测试、回归测试

8.3 使用内置评分器

示例：内容相似度评估

typescript

import { ContentSimilarityScorer } from '@mastra/evals/nlp'

// NLP 类评分器不需要 LLM，本地计算
const scorer = new ContentSimilarityScorer()

const result = await scorer.score({
  input: '简要介绍量子计算',
  output: '量子计算利用量子力学的叠加和纠缠原理进行信息处理',
  expectedOutput: '量子计算是基于量子力学原理的计算范式，利用叠加态和量子纠缠',
})

console.log(result)
// {
//   score: 0.85,
//   info: { ... }
// }

示例：幻觉检测

typescript

import { HallucinationScorer } from '@mastra/evals/llm'

// LLM 类评分器需要传入模型
const scorer = new HallucinationScorer({
  model: 'openai/gpt-4.1',
})

const result = await scorer.score({
  input: '谁发明了电话？',
  output: '亚历山大·格雷厄姆·贝尔在 1876 年发明了电话。',
  context: [
    '亚历山大·格雷厄姆·贝尔于 1876 年获得电话专利',
    '贝尔出生于苏格兰爱丁堡',
  ],
})

console.log(result.score)
// 0.0 (分数越低越好，0 表示没有幻觉)

8.4 自定义评分器

你可以通过继承 Scorer 创建自己的评分逻辑：

typescript

import { Scorer } from '@mastra/core/eval'

interface ResponseLengthInput {
  output: string
  minLength?: number
  maxLength?: number
}

class ResponseLengthScorer extends Scorer<ResponseLengthInput> {
  name = 'response-length'

  async score(input: ResponseLengthInput) {
    const { output, minLength = 50, maxLength = 500 } = input
    const length = output.length
    
    let score: number
    if (length < minLength) {
      score = length / minLength // 太短，按比例扣分
    } else if (length > maxLength) {
      score = maxLength / length // 太长，按比例扣分
    } else {
      score = 1.0 // 长度合适
    }

    return {
      score,
      info: {
        length,
        minLength,
        maxLength,
        status: length < minLength ? 'too-short' 
               : length > maxLength ? 'too-long' 
               : 'ok',
      },
    }
  }
}

8.5 Live Evals（实时评估）

在生产 Agent 上绑定评分器，对实际请求做采样评估：

typescript

import { Agent } from '@mastra/core/agent'
import { ContentSimilarityScorer } from '@mastra/evals/nlp'
import { HallucinationScorer } from '@mastra/evals/llm'

const agent = new Agent({
  id: 'customer-service',
  name: 'Customer Service Agent',
  instructions: '你是客服助手，根据知识库回答用户问题。',
  model: 'openai/gpt-4.1',
  evals: {
    scorers: [
      new ContentSimilarityScorer(),
      new HallucinationScorer({ model: 'openai/gpt-4.1-mini' }),
    ],
    sampling: {
      rate: 0.1, // 采样率 10%（生产用）
    },
  },
})

评估结果会自动存储，可通过 Mastra Studio 查看。

采样策略建议

环境	采样率	说明
开发	1.0	全量评估，充分测试
预发布	0.5	半量，发现问题
生产	0.05–0.1	低采样，控制成本

8.6 Trace Evals（追溯评估）

对已有的运行记录进行批量评估，适合 A/B 测试和回归分析：

typescript

import { Mastra } from '@mastra/core'
import { ContentSimilarityScorer } from '@mastra/evals/nlp'

const mastra = new Mastra({
  agents: { myAgent },
})

// 获取 Agent 实例
const agent = mastra.getAgent('myAgent')

// 获取历史 Traces
const traces = await agent.getTraces({ limit: 100 })

// 批量评估
const scorer = new ContentSimilarityScorer()
for (const trace of traces) {
  const result = await scorer.score({
    input: trace.input,
    output: trace.output,
  })
  console.log(`Trace ${trace.id}: score = ${result.score}`)
}

8.7 可观测性（Observability）

评估告诉你"结果好不好"，可观测性告诉你"过程发生了什么"。

Tracing（追踪）

Mastra 基于 OpenTelemetry 标准，自动记录 Agent/Workflow/Tool 的执行过程：

typescript

import { Mastra } from '@mastra/core'
import { Observability, DefaultExporter, SensitiveDataFilter } from '@mastra/observability'

export const mastra = new Mastra({
  agents: { myAgent },
  observability: new Observability({
    exporter: new DefaultExporter({
      // 本地开发用，输出到控制台
      type: 'console',
    }),
    filter: new SensitiveDataFilter({
      enabled: true,
      // 自动过滤敏感信息（API keys, 密码等）
    }),
  }),
})

输出到外部平台

typescript

import { Observability, DefaultExporter } from '@mastra/observability'

// 输出到 OTLP 端点（支持 Jaeger、Grafana Tempo 等）
const observability = new Observability({
  exporter: new DefaultExporter({
    type: 'otlp',
    endpoint: 'http://localhost:4318/v1/traces',
  }),
})

// 或用 CloudExporter 输出到 Mastra Cloud
import { CloudExporter } from '@mastra/observability'

const observability = new Observability({
  exporter: new CloudExporter({
    apiKey: process.env.MASTRA_CLOUD_API_KEY,
  }),
})

支持的可观测性平台

平台	集成方式
Mastra Studio	开箱即用
Mastra Cloud	CloudExporter
Jaeger	OTLP
Grafana Tempo	OTLP
MLflow	专用 exporter
Langfuse	专用 exporter
Braintrust	专用 exporter

Trace 包含的信息

一个典型的 Agent 调用 Trace 包含：

Agent.generate()                    [1200ms]
├── LLM Call                        [800ms]
│   ├── Model: openai/gpt-4.1
│   ├── Tokens: prompt=120, completion=85
│   └── Cost: $0.0012
├── Tool: searchKnowledgeBase       [350ms]
│   ├── Input: { query: "退货政策" }
│   └── Output: { results: [...] }
├── LLM Call (with tool results)    [600ms]
│   ├── Model: openai/gpt-4.1
│   ├── Tokens: prompt=280, completion=150
│   └── Cost: $0.0028
└── Final Response                  
    └── Text: "根据我们的退货政策..."

8.8 日志系统

Mastra 使用结构化日志：

typescript

import { Mastra, createLogger } from '@mastra/core'

const mastra = new Mastra({
  agents: { myAgent },
  logger: createLogger({
    name: 'my-app',
    level: 'info', // 'debug' | 'info' | 'warn' | 'error'
  }),
})

8.9 在 Mastra Studio 中查看

Mastra Studio 提供了直观的 UI 来查看评估结果和 Trace：

Evals 页面：查看各评分器的评分分布、平均分、趋势
Traces 页面：查看每个请求的完整执行链路，包括耗时、Token 用量、工具调用
Agent 页面：在聊天界面直接看到评估结果

启动 Studio：

bash

npx mastra dev
# 浏览器打开 http://localhost:4111

8.10 我的建议

从简单评分器开始：ContentSimilarity 和 ResponseLength 是最容易理解和实施的
幻觉检测优先：如果你的场景涉及事实性回答（RAG），HallucinationScorer 应该是第一个上线的评分器
不要过度评估：每个评分器都有成本（LLM 类评分器尤其），选择 3-5 个最重要的
建立基线：先跑一轮评估建立基线分数，再做优化才有参照
可观测性不是可选的：生产环境必须开启。出问题时，Trace 是你唯一的调试手段

8.11 本章小结

评估体系
├── 评分器（Scorers）
│   ├── 内置：文本质量、幻觉检测、上下文相关性等
│   └── 自定义：继承 Scorer 类
├── 实时评估（Live Evals）
│   ├── 绑定到 Agent
│   └── 按采样率运行
├── 追溯评估（Trace Evals）
│   └── 批量评估历史记录
└── 可观测性（Observability）
    ├── 自动 Tracing（OpenTelemetry 标准）
    ├── 多平台输出
    └── 敏感数据过滤

下一章我们将学习如何把 Mastra 应用部署到生产环境。

第八章 评估与可观测性 ​

8.1 为什么需要评估？ ​

8.2 评估基本概念 ​

Scorers（评分器） ​

评估类型 ​

8.3 使用内置评分器 ​

示例：内容相似度评估 ​

示例：幻觉检测 ​

8.4 自定义评分器 ​

8.5 Live Evals（实时评估） ​

采样策略建议 ​

8.6 Trace Evals（追溯评估） ​

8.7 可观测性（Observability） ​

Tracing（追踪） ​

输出到外部平台 ​

支持的可观测性平台 ​

Trace 包含的信息 ​

8.8 日志系统 ​

8.9 在 Mastra Studio 中查看 ​

8.10 我的建议 ​

8.11 本章小结 ​

第八章评估与可观测性

8.1 为什么需要评估？

8.2 评估基本概念

Scorers（评分器）

评估类型

8.3 使用内置评分器

示例：内容相似度评估

示例：幻觉检测

8.4 自定义评分器

8.5 Live Evals（实时评估）

采样策略建议

8.6 Trace Evals（追溯评估）

8.7 可观测性（Observability）

Tracing（追踪）

输出到外部平台

支持的可观测性平台

Trace 包含的信息

8.8 日志系统

8.9 在 Mastra Studio 中查看

8.10 我的建议

8.11 本章小结