Aller au contenu principal

dataset.startExperiment()

Ajouté dans : @mastra/core@1.4.0

Exécute une expérience sur le jeu de données et attend sa fin. Exécute tous les éléments sur une cible (agent, workflow ou scorer), avec une évaluation facultative.

Exemple d’utilisation
Lien direct vers Exemple d’utilisation

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}`)

Paramètres
Lien direct vers Paramètres

targetType?:

'agent' | 'workflow' | 'scorer'
Type de cible enregistrée sur laquelle exécuter les éléments. À utiliser avec targetId.

targetId?:

string
ID de la cible enregistrée. À utiliser avec targetType.

scorers?:

(MastraScorer | string)[] | AgentScorerConfig | WorkflowScorerConfig
Scorers permettant d’évaluer chaque résultat. Accepte un tableau plat d’instances MastraScorer ou d’ID de scorers enregistrés, ou la même structure de configuration catégorisée qu’utilise runEvals (AgentScorerConfig / WorkflowScorerConfig). Les scorers de trajectoire (type: "trajectory") reçoivent automatiquement une Trajectory préextraite comme sortie, quelle que soit la forme utilisée. Pour les cibles de workflow, des scorers par étape peuvent être transmis via scorers: { steps: { stepId: [...] } } et exécutés sur la sortie de chaque étape ; leurs résultats contiennent le stepId d’origine et conservent targetScope: "span" (comme avec runEvals).

name?:

string
Nom d’affichage de l’expérience.

description?:

string
Description de l’expérience.

metadata?:

Record<string, unknown>
Métadonnées arbitraires de l’expérience.

version?:

number
Épingle une version précise du jeu de données. La valeur par défaut est la version la plus récente.

maxConcurrency?:

number
Nombre maximal d’exécutions simultanées d’éléments. La valeur par défaut est 5.

signal?:

AbortSignal
AbortSignal permettant d’annuler l’expérience.

itemTimeout?:

number
Délai d’expiration de l’exécution par élément, en millisecondes.

maxRetries?:

number
Nombre maximal de tentatives par élément en cas d’échec. La valeur par défaut est 0 (aucune nouvelle tentative). Les erreurs d’annulation ne font jamais l’objet d’une nouvelle tentative.

unmockedToolPolicy?:

'allow' | 'deny'
= 'allow'
Contrôle les appels d’outils d’agent non déclarés. allow les exécute réellement. deny fait échouer l’élément avec TOOL_MOCK_NOT_DECLARED avant l’exécution. Une valeur définie au niveau de l’élément remplace cette valeur par défaut de l’expérience.

persistence?:

ExperimentPersistencePolicy
Contrôle si cette exécution écrit des enregistrements d’expérience et de scores. Les cibles et les scorers sont tout de même exécutés et les résultats restent disponibles dans le récapitulatif renvoyé.
ExperimentPersistencePolicy

experiments?:

'default' | 'none'
Définissez cette valeur sur none pour ignorer la création de l’expérience ainsi que l’écriture des résultats d’éléments, de la progression et de l’état final.

scores?:

'default' | 'none'
Définissez cette valeur sur none pour ne pas écrire les scores tout en exécutant les scorers.

Valeur renvoyée
Lien direct vers Valeur renvoyée

result:

Promise<ExperimentSummary>
Récapitulatif de l’expérience terminée.
ExperimentSummary

experimentId:

string
ID unique de l’expérience.

status:

'pending' | 'running' | 'completed' | 'failed'
État final de l’expérience.

totalItems:

number
Nombre total d’éléments du jeu de données.

succeededCount:

number
Nombre d’éléments ayant réussi.

failedCount:

number
Nombre d’éléments ayant échoué.

skippedCount:

number
Nombre d’éléments ignorés (par exemple, à cause d’une annulation).

completedWithErrors:

boolean
true si l’exécution est terminée, mais que certains éléments ont échoué.

startedAt:

Date
Date et heure de début de l’expérience.

completedAt:

Date
Date et heure de fin de l’expérience.

results:

ItemWithScores[]
Tous les résultats d’éléments avec leurs scores.
ItemWithScores

itemId:

string
ID de l’élément du jeu de données.

itemVersion:

number
Version du jeu de données de l’élément au moment de son exécution.

input:

unknown
Données d’entrée transmises à la cible.

output:

unknown | null
Sortie de la cible, ou null en cas d’échec.

groundTruth:

unknown | null
Sortie attendue de l’élément du jeu de données.

error:

{ message: string; stack?: string; code?: string } | null
Erreur structurée si l’exécution a échoué.

startedAt:

Date
Date et heure de début de l’exécution de l’élément.

completedAt:

Date
Date et heure de fin de l’exécution de l’élément.

retryCount:

number
Nombre de tentatives de nouvelle exécution.

scores:

ScorerResult[]
Résultats de tous les scorers pour cet élément.
ScorerResult

scorerId:

string
ID du scorer.

scorerName:

string
Nom d’affichage du scorer.

score:

number | null
Score calculé, ou null si le scorer a échoué.

reason:

string | null
Motif ou explication du score.

error:

string | null
Message d’erreur si le scorer a échoué.
On this page