Evals 和 scorer

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

已变更

getScorers 改为 listScorers

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

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

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

Codemod

你可以使用 Mastra 的 codemod CLI 自动更新代码：

npx @mastra/codemod@latest v1/mastra-plural-apis .

runExperiment 改为 runEvals

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

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

- 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 自动更新代码：

npx @mastra/codemod@latest v1/evals-run-experiment .

getScorerByName 改为 getScorerById

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

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

  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 自动更新代码：

npx @mastra/codemod@latest v1/evals-scorer-by-name .

scorer 配置从 name 改为 id

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

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

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

Storage 评分 API 改为 listScoresBy* 模式

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

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

- 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 路径。

  // 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 自动更新代码：

npx @mastra/codemod@latest v1/evals-prebuilt-imports .

scorer 消息类型从 UIMessage 改为 MastraDBMessage

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

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

  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() 辅助函数。

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

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

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

Evals 相关类型导出

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

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

- 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 类型。

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