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 的組織更清楚。

遷移時，請更新匯入陳述式，改用新的 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
  });