跳至主要內容

dataset.startExperiment()

新增於： @mastra/core@1.4.0

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

使用範例
使用範例 的直接連結

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'
= 'allow'
控制未宣告的 Agent Tool 呼叫。allow 會即時執行；deny 會在執行前以 TOOL_MOCK_NOT_DECLARED 令項目失敗。項目層級的值會覆寫此實驗預設值。

persistence?:

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

experiments?:

'default' | 'none'
設為 none 可略過建立實驗，以及寫入項目結果、進度及終止狀態。

scores?:

'default' | 'none'
設為 none 可略過寫入分數，但仍會執行評分器。

傳回值
傳回值 的直接連結

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[]
此項目來自所有評分器的結果。
ScorerResult

scorerId:

string
評分器的 ID。

scorerName:

string
評分器的顯示名稱。

score:

number | null
計算所得分數；如評分器失敗則為 null。

reason:

string | null
分數的原因／解釋。

error:

string | null
評分器失敗時的錯誤訊息。
On this page