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

儲存空間分數 API 改用 listScoresBy* 模式

分數儲存空間 API 已重新命名，以遵循 listScoresBy* 模式。這項變更配合更廣泛的儲存空間 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 程式碼，包括舊版評估指標、scorer／judge 模組，以及以 hook 為基礎的自動評估程式碼。這項變更移除過時的評估方式，令程式碼庫更簡潔。

如要遷移，請使用 @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 泛型參數。指標／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 及處理器選項類型。這些類型現已成為內部類型，或已由新的 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
  });