> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 데이터세트.시작실험()

**추가된 항목:** `@mastra/core@1.4.0`

데이터세트에 대한 실험을 실행하고 완료될 때까지 기다립니다. 선택적 채점을 통해 대상(Agent, Workflow 또는 채점자)에 대해 모든 항목을 실행합니다.

## 사용예

```typescript
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'`): 선언되지 않은 Agent Tool 호출을 제어합니다. allow는 호출을 실제로 실행합니다. deny는 실행 전에 TOOL\_MOCK\_NOT\_DECLARED와 함께 항목을 실패 처리합니다. 항목 수준의 값은 이 실험 기본값보다 우선합니다. (Default: `'allow'`)

**persistence** (`ExperimentPersistencePolicy`): 이 실행에서 실험 레코드와 점수 레코드를 기록할지 제어합니다. 대상과 채점기는 계속 실행되며, 결과는 반환되는 요약에서 확인할 수 있습니다.

**persistence.experiments** (`'default' | 'none'`): 실험 생성, 항목 결과, 진행 상황, 최종 상태 기록을 건너뛰려면 none으로 설정합니다.

**persistence.scores** (`'default' | 'none'`): 채점기는 계속 실행하되 점수 기록을 건너뛰려면 none으로 설정합니다.

## 보고

**result** (`Promise<ExperimentSummary>`): 완료된 실험의 요약입니다.

**result.experimentId** (`string`): 실험의 고유 ID입니다.

**result.status** (`'pending' | 'running' | 'completed' | 'failed'`): 실험의 최종 상태입니다.

**result.totalItems** (`number`): 데이터 세트의 전체 항목 수입니다.

**result.succeededCount** (`number`): 성공한 항목 수입니다.

**result.failedCount** (`number`): 실패한 항목 수입니다.

**result.skippedCount** (`number`): 건너뛴 항목 수입니다(예: 중단으로 인한 경우).

**result.completedWithErrors** (`boolean`): 실행은 완료되었지만 일부 항목이 실패한 경우 true입니다.

**result.startedAt** (`Date`): 실험이 시작된 시점입니다.

**result.completedAt** (`Date`): 실험이 완료된 시점입니다.

**result.results** (`ItemWithScores[]`): 점수가 포함된 모든 항목 결과입니다.

**result.results.itemId** (`string`): 데이터 세트 항목의 ID입니다.

**result.results.itemVersion** (`number`): 실행 당시 항목의 데이터 세트 버전입니다.

**result.results.input** (`unknown`): 대상에 전달된 입력 데이터입니다.

**result.results.output** (`unknown | null`): 대상에서 생성된 출력이며, 실패한 경우 null입니다.

**result.results.groundTruth** (`unknown | null`): 데이터 세트 항목의 예상 출력입니다.

**result.results.error** (`{ message: string; stack?: string; code?: string } | null`): 실행에 실패한 경우의 구조화된 오류입니다.

**result.results.startedAt** (`Date`): 항목 실행이 시작된 시점입니다.

**result.results.completedAt** (`Date`): 항목 실행이 완료된 시점입니다.

**result.results.retryCount** (`number`): 재시도 횟수입니다.

**result.results.scores** (`ScorerResult[]`): 이 항목에 대한 모든 채점기의 결과입니다.

**result.results.scores.scorerId** (`string`): 채점기의 ID입니다.

**result.results.scores.scorerName** (`string`): 채점기의 표시 이름입니다.

**result.results.scores.score** (`number | null`): 계산된 점수이며, 채점기가 실패한 경우 null입니다.

**result.results.scores.reason** (`string | null`): 점수의 근거/설명입니다.

**result.results.scores.error** (`string | null`): 채점기가 실패한 경우의 오류 메시지입니다.

## 관련된

- [데이터 세트.startExperimentAsync()](https://mastra.zisheng.pro/ko/reference/datasets/startExperimentAsync)
- [데이터세트.목록실험()](https://mastra.zisheng.pro/ko/reference/datasets/listExperiments)
- [DatasetsManager.compareExperiments()](https://mastra.zisheng.pro/ko/reference/datasets/compareExperiments)