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

# Evals 和 scorer

评估 API 已统一到新的 scorer 系统，并更新了命名约定和配置要求。

## 已变更

### `getScorers` 改为 `listScorers`

`getScorers()` 方法已重命名为 `listScorers()`。此变更与整个 API 的命名约定保持一致：返回集合的 getter 方法使用 `list` 前缀。

迁移时，请将所有 `getScorers()` 调用替换为 `listScorers()`。

```diff
- const scorers = mastra.getScorers();
+ const scorers = mastra.listScorers();
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自动更新代码：
>
> ```bash
> npx @mastra/codemod@latest v1/mastra-plural-apis .
> ```

### `runExperiment` 改为 `runEvals`

`runExperiment()` 函数已重命名为 `runEvals()`，以明确表示它会运行评估。

迁移时，请将函数调用从 `runExperiment` 更新为 `runEvals`。

```diff
- import { createScorer, runExperiment } from '@mastra/core/evals';
+ import { createScorer, runEvals } from '@mastra/core/evals';
  import { myAgent } from './agents/my-agent';

  const scorer = createScorer({
    id: 'helpfulness-scorer',
    // ...
  });

- const result = await runExperiment({ target: myAgent, scorers: [scorer], data: inputs });
+ const result = await runEvals({ target: myAgent, scorers: [scorer], data: inputs });
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自动更新代码：
>
> ```bash
> npx @mastra/codemod@latest v1/evals-run-experiment .
> ```

### `getScorerByName` 改为 `getScorerById`

`getScorerByName()` 方法已重命名为 `getScorerById()`。scorer 现在必须提供 `id` 字段，而不再要求 `name`。此变更与整体 API 使用 `id` 标识实体的模式保持一致。

迁移时，请更新方法调用和 scorer 配置，使用 `id` 替代 `name`。

```diff
const scorer = createScorer({
-   name: 'helpfulness-scorer',
+   id: 'helpfulness-scorer',
    // ...
  });

- const scorer = mastra.getScorerByName('helpfulness-scorer');
+ const scorer = mastra.getScorerById('helpfulness-scorer');
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自动更新代码：
>
> ```bash
> npx @mastra/codemod@latest v1/evals-scorer-by-name .
> ```

### scorer 配置从 `name` 改为 `id`

scorer 现在必须提供 `id` 字段，而不再要求 `name`。`name` 字段现在是可选的。此变更与其他 Mastra 实体保持一致。

迁移时，请更新 scorer 定义，将 `id` 作为必填字段。

```diff
const scorer = createScorer({
-   name: 'helpfulness-scorer',
+   id: 'helpfulness-scorer',
+   name: 'Helpfulness Scorer', // optional
    // ...
  });
```

### Storage 评分 API 改为 `listScoresBy*` 模式

评分 Storage API 已重命名为遵循 `listScoresBy*` 模式。此变更与整体 Storage API 命名约定保持一致。

迁移时，请更新评分查询方法，使其使用新的命名模式。

```diff
- const scores = await storage.getScores({ scorerName: 'helpfulness-scorer' });
+ const scores = await storage.listScoresByScorerId({
+   scorerId: 'helpfulness-scorer',
+ });

// Also available:
// - listScoresByRunId
// - listScoresByEntityId
// - listScoresBySpan
```

### 预构建 scorer 改为从 `scorers/prebuilt` 路径导入

预构建 scorer 的导入已统一到 `@mastra/evals/scorers/prebuilt` 路径，不再分别使用 `scorers/llm` 和 `scorers/code` 路径。此变更简化了导入，并让预构建 scorer 的组织方式更清晰。

迁移时，请更新 import 语句以使用新的 `scorers/prebuilt` 路径。

```diff
// LLM-based scorers
- import { createHallucinationScorer } from '@mastra/evals/scorers/llm';
- import { createFaithfulnessScorer } from '@mastra/evals/scorers/llm';
+ import { createHallucinationScorer } from '@mastra/evals/scorers/prebuilt';
+ import { createFaithfulnessScorer } from '@mastra/evals/scorers/prebuilt';

  // Code-based scorers
- import { createContentSimilarityScorer } from '@mastra/evals/scorers/code';
- import { createCompletenessScorer } from '@mastra/evals/scorers/code';
+ import { createContentSimilarityScorer } from '@mastra/evals/scorers/prebuilt';
+ import { createCompletenessScorer } from '@mastra/evals/scorers/prebuilt';
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自动更新代码：
>
> ```bash
> npx @mastra/codemod@latest v1/evals-prebuilt-imports .
> ```

### scorer 消息类型从 `UIMessage` 改为 `MastraDBMessage`

scorer 输入和输出类型现在使用 `MastraDBMessage[]`，而不再使用 `UIMessage`。此变更让 scorer 与数据库持久化消息格式保持一致，从而确保整个框架的一致性。

迁移时，请更新 scorer 实现以使用 `MastraDBMessage` 类型，并通过嵌套的 `content` 结构访问消息内容。

```diff
import type {
    ScorerRunInputForAgent,
    ScorerRunOutputForAgent
  } from '@mastra/core/evals';

- // ScorerRunInputForAgent uses UIMessage[]
- const inputMessages: UIMessage[] = run.input.inputMessages;
+ // ScorerRunInputForAgent now uses MastraDBMessage[]
+ import type { MastraDBMessage } from '@mastra/core/agent';
+ const inputMessages: MastraDBMessage[] = run.input.inputMessages;
```

### 消息内容结构改为嵌套格式

Tool 调用和文本内容现在通过嵌套的 `content` 对象访问，而不再使用扁平的消息属性。嵌套结构与数据库消息格式及其类型相匹配。

迁移时，请通过 `message.content.toolInvocations` 访问 Tool 调用，通过 `message.content.content` 访问文本，或使用 `getTextContentFromMastraDBMessage()` 辅助函数。

```diff
+ import { getTextContentFromMastraDBMessage } from '@mastra/evals';
+
  const run = await scorer.run(testRun);

  // Accessing text content
- const text = message.content;
+ const text = getTextContentFromMastraDBMessage(message);
+ // or directly: message.content.content

  // Accessing tool invocations
- const toolCalls = message.toolInvocations;
+ const toolCalls = message.content.toolInvocations;
```

## 已移除

### 旧版 Evals 代码

`@mastra/core` 中已移除旧版 Evals 代码，包括旧版评估 metric、scorer/judge 模块和基于钩子的自动评估代码。移除过时的评估方式后，代码库得到简化。

迁移时，请使用 `@mastra/core/evals` 或 `@mastra/evals` 中新的 Evals/scorer API。

```diff
- // Legacy evals APIs
+ import { createScorer, runEvals } from '@mastra/core/evals';
+
+ const scorer = createScorer({
+   id: 'my-scorer',
+   // Use new scorer API
+ });
```

### Agent 的 `TMetrics` 泛型参数

`AgentConfig` 和 `Agent` 构造函数中的 `TMetrics` 泛型参数已移除。Metric/scorer 现在通过 scorer API 配置，不再属于 Agent 类型系统的一部分。此变更简化了 Agent 类型签名。

迁移时，请移除 `TMetrics` 泛型参数，并使用 scorer API 配置 scorer。

```diff
- const agent = new Agent<AgentId, Tools, Metrics>({
+ const agent = new Agent<AgentId, Tools>({
    // ...
  });
```

### Evals 相关类型导出

多个 Evals 相关类型导出已移除，包括 `DeprecatedOutputOptions`、`Metric` 和 Processor 选项类型。这些类型现在是内部类型，或已由新的 scorer API 取代。此变更缩小了 API 界面。

迁移时，请移除对这些已移除类型的引用，并使用新的 scorer API。

```diff
- import type {
-   DeprecatedOutputOptions,
-   Metric,
-   LanguageDetectorOptions,
-   ModerationOptions,
- } from '@mastra/core';
+ // Use new scorers API types
+ import type { Scorer } from '@mastra/core/evals';
```

### `createUIMessage` 测试辅助函数

`createUIMessage()` 测试辅助函数已移除，并由 `createTestMessage()` 替代。新辅助函数使用嵌套内容结构创建 `MastraDBMessage` 对象，并支持可选的 Tool 调用。此变更让测试工具函数与新消息格式保持一致。

迁移时，请将 `createUIMessage()` 调用替换为 `createTestMessage()`，并更新为使用 `MastraDBMessage` 类型。

```diff
- import { createUIMessage } from '@mastra/evals';
+ import { createTestMessage } from '@mastra/evals';

  // Creating test messages
- const message = createUIMessage({
-   id: 'test-1',
+ const message = createTestMessage({
+   id: 'test-1', // optional, defaults to 'test-message'
    role: 'user',
    content: 'Hello',
    toolInvocations: [], // optional
  });
```