跳至主要內容

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