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

# dataset.startExperiment()

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

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

## 使用範例

```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`): 用於評估每個結果的 Scorer。接受由 MastraScorer 執行個體或已註冊 Scorer ID 組成的扁平陣列，也接受與 runEvals 相同的分類設定結構（AgentScorerConfig / WorkflowScorerConfig）。無論使用哪種形式，Trajectory Scorer（type: "trajectory"）都會自動接收預先提取的 Trajectory 作為輸出。對於 Workflow 目標，可透過 scorers: { steps: { stepId: \[...] } } 傳入各步驟的 Scorer，並針對每個步驟的輸出執行；其結果會攜帶來源 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（不重試）。Abort 錯誤永遠不會重試。

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

**persistence** (`ExperimentPersistencePolicy`): 控制本次執行是否寫入實驗記錄和評分記錄。目標和 Scorer 仍會執行，結果仍可在傳回的摘要中取得。

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

**persistence.scores** (`'default' | 'none'`): 設為 none 可跳過分數寫入，同時仍執行 Scorer。

## 傳回值

**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[]`): 所有 Scorer 針對此項目的結果。

**result.results.scores.scorerId** (`string`): Scorer 的 ID。

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

**result.results.scores.score** (`number | null`): 計算得到的分數；如果 Scorer 失敗則為 null。

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

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

## 相關內容

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