メインコンテンツへ移動

dataset.startExperiment()

追加バージョン： @mastra/core@1.4.0

データセットで Experiment を実行し、完了を待ちます。任意のスコアリングを使用して、すべての項目を対象（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: [...] } } で Step ごとの Scorer を渡し、各 Step の出力に対して実行できます。その結果には元の stepId が含まれ、targetScope: "span" が維持されます（runEvals と同じ動作）。

name?:

string
表示名 experiment.

description?:

string
説明 experiment.

metadata?:

Record<string, unknown>
Experiment の任意のメタデータ。

version?:

number
特定のデータセットバージョンに固定します。デフォルトは最新バージョンです。

maxConcurrency?:

number
項目を同時実行する最大数。デフォルトは 5 です。

signal?:

AbortSignal
Experiment をキャンセルするための AbortSignal。

itemTimeout?:

number
項目ごとの実行タイムアウト（ミリ秒）。

maxRetries?:

number
失敗時の項目ごとの最大再試行回数。デフォルトは 0（再試行なし）です。Abort エラーは再試行しません。

unmockedToolPolicy?:

'allow' | 'deny'
= 'allow'
宣言されていない Agent Tool の呼び出しを制御します。allow は実際に実行します。deny は実行前に TOOL_MOCK_NOT_DECLARED で項目を失敗させます。項目単位の値は、この Experiment のデフォルト値を上書きします。

persistence?:

ExperimentPersistencePolicy
この実行で Experiment レコードとスコアレコードを書き込むかを制御します。対象と Scorer は引き続き実行され、結果は返される概要で確認できます。
ExperimentPersistencePolicy

experiments?:

'default' | 'none'
none に設定すると、Experiment の作成、項目結果、進行状況、最終ステータスの書き込みを省略します。

scores?:

'default' | 'none'
none に設定すると、Scorer を実行したままスコアの書き込みを省略します。

戻り値
戻り値への直接リンク

result:

Promise<ExperimentSummary>
完了した Experiment の概要。
ExperimentSummary

experimentId:

string
一意な ID： experiment.

status:

'pending' | 'running' | 'completed' | 'failed'
Experiment の最終ステータス。

totalItems:

number
データセット内の項目総数。

succeededCount:

number
成功した項目数。

failedCount:

number
失敗した項目数。

skippedCount:

number
スキップされた項目数（Abort による場合など）。

completedWithErrors:

boolean
実行は完了したものの一部の項目が失敗した場合は true。

startedAt:

Date
Experiment が開始された日時。

completedAt:

Date
Experiment が完了した日時。

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