> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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 的組織更清楚。

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