> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# dataset.startExperiment()

**新增於：** `@mastra/core@1.4.0`

在資料集上執行實驗並等待完成。 針對目標（Agent、Workflow 或評分器）執行所有項目，並可選擇評分。

## 使用範例

```typescript
import { Mastra } from '@mastra/core'

const mastra = new Mastra({/* storage config */})

const dataset = await mastra.datasets.get({ id: 'dataset-id' })

// Run against a registered agent with a flat scorer list
const summary = await dataset.startExperiment({
  targetType: 'agent',
  targetId: 'my-agent',
  scorers: ['accuracy', 'relevancy'],
  maxConcurrency: 10,
})

// Or pass the same categorised shape accepted by runEvals
const summary2 = await dataset.startExperiment({
  targetType: 'agent',
  targetId: 'my-agent',
  scorers: {
    agent: [accuracyScorer],
    trajectory: [toolOrderScorer],
  },
})

// For workflow targets, score individual steps with their own scorers
const summary3 = await dataset.startExperiment({
  targetType: 'workflow',
  targetId: 'my-workflow',
  scorers: {
    workflow: [overallScorer],
    steps: {
      'fetch-data': [fetchScorer],
      transform: [transformScorer],
    },
    trajectory: [executionPathScorer],
  },
})

console.log(`${summary.succeededCount}/${summary.totalItems} succeeded`)
console.log(`Status: ${summary.status}`)
console.log(`${summary2.succeededCount}/${summary2.totalItems} succeeded`)
console.log(`Status: ${summary2.status}`)
```

## 參數

**targetType** (`'agent' | 'workflow' | 'scorer'`): 用來執行項目的已註冊目標類型。請與 targetId 一併使用。

**targetId** (`string`): 已註冊目標的 ID。請與 targetType 一併使用。

**scorers** (`(MastraScorer | string)[] | AgentScorerConfig | WorkflowScorerConfig`): 用於評估每項結果的評分器。接受 MastraScorer 執行個體或已註冊評分器 ID 的扁平陣列，亦接受 runEvals 所用的相同分類設定結構（AgentScorerConfig／WorkflowScorerConfig）。無論使用哪種形式，軌跡評分器（type: "trajectory"）都會自動接收預先擷取的 Trajectory 作為輸出。對於 Workflow 目標，可透過 scorers: { steps: { stepId: \[...] } } 傳入每個步驟的評分器，並針對各步驟的輸出執行；結果會包含來源 stepId，並保留 targetScope: "span"（與 runEvals 一致）。

**name** (`string`): 實驗的顯示名稱。

**description** (`string`): 實驗的描述。

**metadata** (`Record<string, unknown>`): 實驗的任意元資料。

**version** (`number`): 鎖定至指定資料集版本。預設為最新版本。

**maxConcurrency** (`number`): 項目執行的最大並行數。預設為 5。

**signal** (`AbortSignal`): 用於取消實驗的 AbortSignal。

**itemTimeout** (`number`): 每個項目的執行逾時時間（毫秒）。

**maxRetries** (`number`): 每個項目失敗時的最多重試次數。預設為 0（不重試）。中止錯誤永不重試。

**unmockedToolPolicy** (`'allow' | 'deny'`): 控制未宣告的 Agent Tool 呼叫。allow 會即時執行；deny 會在執行前以 TOOL\_MOCK\_NOT\_DECLARED 令項目失敗。項目層級的值會覆寫此實驗預設值。 (Default: `'allow'`)

**persistence** (`ExperimentPersistencePolicy`): 控制此次執行是否寫入實驗記錄及分數記錄。目標及評分器仍會執行，結果亦會保留在傳回的摘要中。

**persistence.experiments** (`'default' | 'none'`): 設為 none 可略過建立實驗，以及寫入項目結果、進度及終止狀態。

**persistence.scores** (`'default' | 'none'`): 設為 none 可略過寫入分數，但仍會執行評分器。

## 傳回值

**result** (`Promise<ExperimentSummary>`): 已完成實驗的摘要。

**result.experimentId** (`string`): 實驗的唯一 ID。

**result.status** (`'pending' | 'running' | 'completed' | 'failed'`): 實驗的最終狀態。

**result.totalItems** (`number`): 資料集中的項目總數。

**result.succeededCount** (`number`): 成功項目的數目。

**result.failedCount** (`number`): 失敗項目的數目。

**result.skippedCount** (`number`): 略過項目的數目（例如因中止）。

**result.completedWithErrors** (`boolean`): 如果執行已完成但部分項目失敗，則為 true。

**result.startedAt** (`Date`): 實驗的開始時間。

**result.completedAt** (`Date`): 實驗的完成時間。

**result.results** (`ItemWithScores[]`): 所有項目結果及其分數。

**result.results.itemId** (`string`): 資料集項目的 ID。

**result.results.itemVersion** (`number`): 執行項目時的資料集版本。

**result.results.input** (`unknown`): 傳送至目標的輸入資料。

**result.results.output** (`unknown | null`): 目標的輸出；如失敗則為 null。

**result.results.groundTruth** (`unknown | null`): 資料集項目的預期輸出。

**result.results.error** (`{ message: string; stack?: string; code?: string } | null`): 執行失敗時的結構化錯誤。

**result.results.startedAt** (`Date`): 項目執行的開始時間。

**result.results.completedAt** (`Date`): 項目執行的完成時間。

**result.results.retryCount** (`number`): 重試次數。

**result.results.scores** (`ScorerResult[]`): 此項目來自所有評分器的結果。

**result.results.scores.scorerId** (`string`): 評分器的 ID。

**result.results.scores.scorerName** (`string`): 評分器的顯示名稱。

**result.results.scores.score** (`number | null`): 計算所得分數；如評分器失敗則為 null。

**result.results.scores.reason** (`string | null`): 分數的原因／解釋。

**result.results.scores.error** (`string | null`): 評分器失敗時的錯誤訊息。

## 相關內容

- [dataset.startExperimentAsync()](https://mastra.zisheng.pro/zh-HK/reference/datasets/startExperimentAsync)
- [dataset.listExperiments()](https://mastra.zisheng.pro/zh-HK/reference/datasets/listExperiments)
- [DatasetsManager.compareExperiments()](https://mastra.zisheng.pro/zh-HK/reference/datasets/compareExperiments)