> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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
    // ...
  });
```

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

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

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