跳到主要内容

dataset.startExperiment()

添加于： @mastra/core@1.4.0

在数据集上运行实验并等待其完成。针对目标（Agent、Workflow 或 Scorer）执行所有条目，并可选择进行评分。

使用示例
使用示例的直接链接

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'
= 'allow'
控制未声明的 Agent Tool 调用。allow 会实际执行这些调用；deny 会在执行前让条目以 TOOL_MOCK_NOT_DECLARED 失败。条目级值会覆盖此实验默认值。

persistence?:

ExperimentPersistencePolicy
控制本次运行是否写入实验记录和评分记录。目标和 Scorer 仍会执行，结果仍可在返回的摘要中获取。
ExperimentPersistencePolicy

experiments?:

'default' | 'none'
设为 none 可跳过实验创建以及条目结果、进度和最终状态的写入。

scores?:

'default' | 'none'
设为 none 可跳过分数写入，同时仍运行 Scorer。

返回值
返回值的直接链接

result:

Promise<ExperimentSummary>
已完成实验的摘要。
ExperimentSummary

experimentId:

string
实验的唯一 ID。

status:

'pending' | 'running' | 'completed' | 'failed'
实验的最终状态。

totalItems:

number
数据集中的条目总数。

succeededCount:

number
成功的条目数。

failedCount:

number
失败的条目数。

skippedCount:

number
跳过的条目数（例如因中止而跳过）。

completedWithErrors:

boolean
如果运行已完成但有部分条目失败，则为 true。

startedAt:

Date
实验开始时间。

completedAt:

Date
实验完成时间。

results:

ItemWithScores[]
所有条目结果及其分数。
ItemWithScores

itemId:

string
数据集条目的 ID。

itemVersion:

number
执行条目时的数据集版本。

input:

unknown
传递给目标的输入数据。

output:

unknown | null
目标输出；如果失败则为 null。

groundTruth:

unknown | null
数据集条目的预期输出。

error:

{ message: string; stack?: string; code?: string } | null
执行失败时的结构化错误。

startedAt:

Date
条目执行开始时间。

completedAt:

Date
条目执行完成时间。

retryCount:

number
重试次数。

scores:

ScorerResult[]
所有 Scorer 针对此条目的结果。
ScorerResult

scorerId:

string
Scorer 的 ID。

scorerName:

string
Scorer 的显示名称。

score:

number | null
计算得到的分数；如果 Scorer 失败则为 null。

reason:

string | null
分数的原因或解释。

error:

string | null
Scorer 失败时的错误消息。
On this page