> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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/reference/datasets/startExperimentAsync)
- [dataset.listExperiments()](https://mastra.zisheng.pro/reference/datasets/listExperiments)
- [DatasetsManager.compareExperiments()](https://mastra.zisheng.pro/reference/datasets/compareExperiments)