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

# Datasets 概览

**新增于：** `@mastra/core@1.4.0`

Dataset 是测试用例的集合，你可以针对这些测试用例运行实验，以衡量 Agent 和 Workflow 的表现。每次变更都会创建新版本，因此可以精确复现过去的实验。将 Dataset 与 [Scorer](https://mastra.zisheng.pro/docs/evals/overview) 配合使用，可以跟踪 prompt、模型或代码变更带来的质量变化。

**面向 AI Agent：** 运行 `npx mastra api dataset create '{"name":"translation-pairs"}'` 可直接创建 Dataset，无需打开 Studio 或编写临时脚本。该命令需要一个正在运行且配置了支持 Dataset 的 Storage 适配器的 Mastra Server；使用 `npx mastra dev` 启动本地 Server，或通过 `--url` 传入可访问 Server 的基础 URL。添加不同的 Dataset 字段前，请运行 `npx mastra api dataset create --schema`。使用 `npx skills add mastra-ai/skills --skill mastra` 安装 Mastra Skill，以获得完整的 API CLI 发现、目标选择、schema、身份验证和错误处理指南。

## 用法

### 配置 Storage

在 Mastra 实例中配置 Storage。Dataset 需要提供 `datasets` domain 的 Storage 适配器：

```typescript
import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'my-store',
    url: 'file:./mastra.db',
  }),
})
```

### 访问 Datasets API

所有 Dataset 操作都可通过 `mastra.datasets` 使用：

```typescript
const datasets = mastra.datasets

// Create a dataset
const dataset = await datasets.create({ name: 'my-dataset' })

// Retrieve an existing dataset
const existing = await datasets.get({ id: 'dataset-id' })

// List all datasets
const { datasets: all } = await datasets.list()
```

有关完整的方法列表，请访问 [`DatasetsManager` Reference](https://mastra.zisheng.pro/reference/datasets/datasets-manager)。

## Studio

你也可以在 [Studio](https://mastra.zisheng.pro/docs/studio/overview) 中管理 Dataset。打开 Studio 后，从侧边栏选择 **Datasets**，即可查看所有可用 Dataset 或创建新 Dataset。

要开始使用，请选择 **Create Dataset**，然后设置名称、描述和可选 schema。确认后，你会看到 Dataset 详情页面，其中包含两个选项卡：**Items** 和 [**Experiments**](https://mastra.zisheng.pro/docs/datasets/running-experiments)。

在 **Items** 视图中，可以添加、更新和删除 item，并查看版本历史记录。选择 **Add Item** 可插入新 item，并通过 JSON 编辑器设置 input 和 ground truth。在此视图中，还可以从 CSV 或 JSON 文件批量导入 item。导入时，请将每一列映射到对应的 Dataset 字段。

选择 **Versions** 可查看 Dataset 的完整变更历史。选择 **Compare Versions** 后，选取任意两个版本并选择 **Compare**，即可并排查看这两个版本之间所有新增、变更或删除 item 的 diff。

## 创建 Dataset

使用名称和可选描述调用 [`create()`](https://mastra.zisheng.pro/reference/datasets/create)：

```typescript
import { mastra } from '../index'

const dataset = await mastra.datasets.create({
  name: 'translation-pairs',
  description: 'English to Spanish translation test cases',
})

console.log(dataset.id) // auto-generated UUID
```

### 定义 schema

创建 Dataset 时，可以传入 [Standard JSON Schema](https://standardschema.dev/json-schema)（[Zod](https://zod.dev/)、[Valibot](https://valibot.dev/)、[ArkType](https://arktype.io/) 等），以强制规定 `input` 和 `groundTruth` 的结构：

```typescript
import { z } from 'zod'
import { mastra } from '../index'

const dataset = await mastra.datasets.create({
  name: 'translation-pairs',
  inputSchema: z.object({
    text: z.string(),
    sourceLang: z.string(),
    targetLang: z.string(),
  }),
  groundTruthSchema: z.object({
    translation: z.string(),
  }),
})
```

插入时，与 schema 不匹配的 item 会被拒绝。

## 添加 item

使用 [`addItem()`](https://mastra.zisheng.pro/reference/datasets/addItem) 添加单个 item，或使用 [`addItems()`](https://mastra.zisheng.pro/reference/datasets/addItems) 批量插入：

```typescript
// Single item
await dataset.addItem({
  input: { text: 'Hello', sourceLang: 'en', targetLang: 'es' },
  groundTruth: { translation: 'Hola' },
})

// Bulk insert
await dataset.addItems({
  items: [
    {
      input: { text: 'Goodbye', sourceLang: 'en', targetLang: 'es' },
      groundTruth: { translation: 'Adiós' },
    },
    {
      input: { text: 'Thank you', sourceLang: 'en', targetLang: 'es' },
      groundTruth: { translation: 'Gracias' },
    },
  ],
})
```

## 更新和删除 item

[`updateItem()`](https://mastra.zisheng.pro/reference/datasets/updateItem)、[`deleteItem()`](https://mastra.zisheng.pro/reference/datasets/deleteItem) 和 [`deleteItems()`](https://mastra.zisheng.pro/reference/datasets/deleteItems) 可让你通过 `itemId` 修改或移除现有 item：

```typescript
await dataset.updateItem({
  itemId: 'item-abc-123',
  groundTruth: { translation: '¡Hola!' },
})

await dataset.deleteItem({ itemId: 'item-abc-123' })

await dataset.deleteItems({ itemIds: ['item-1', 'item-2'] })
```

## 列出和搜索 item

[`listItems()`](https://mastra.zisheng.pro/reference/datasets/listItems) 支持分页和全文搜索：

```typescript
// Paginated list
const { items, pagination } = await dataset.listItems({
  page: 0,
  perPage: 50,
})

// Full-text search
const { items: matches } = await dataset.listItems({
  search: 'Hello',
})

// Search and pagination can be combined with a specific version
const { items: v2Matches } = await dataset.listItems({
  version: 2,
  search: 'Hello',
  page: 0,
  perPage: 50,
})

// Version-only snapshot returns a bare DatasetItem[]
const v2Items = await dataset.listItems({ version: 2 })
```

## 版本控制

每次改变 Dataset item（添加、更新或删除）都会提升 Dataset 版本。这样可以将实验固定到特定的数据快照。

### 列出版本

使用 [`listVersions()`](https://mastra.zisheng.pro/reference/datasets/listVersions) 查看分页的版本历史记录：

```typescript
const { versions, pagination } = await dataset.listVersions()

for (const v of versions) {
  console.log(`Version ${v.version} — created ${v.createdAt}`)
}
```

### 查看 item 历史记录

使用 `itemId` 调用 [`getItemHistory()`](https://mastra.zisheng.pro/reference/datasets/getItemHistory)，查看特定 item 在不同版本中的变化：

```typescript
const history = await dataset.getItemHistory({ itemId: 'item-abc-123' })

for (const row of history) {
  console.log(`Version ${row.datasetVersion}`, row.input, row.groundTruth)
}
```

### 固定到版本

获取过去某一版本中存在的确切 item：

```typescript
const items = await dataset.listItems({ version: 2 })
```

也可以将实验固定到某个版本，请参阅[运行实验](https://mastra.zisheng.pro/docs/datasets/running-experiments)。有关完整的方法和参数列表，请访问 [`Dataset` Reference](https://mastra.zisheng.pro/reference/datasets/dataset)。

## 相关内容

- [运行实验](https://mastra.zisheng.pro/docs/datasets/running-experiments)
- [Scorer 概览](https://mastra.zisheng.pro/docs/evals/overview)
- [DatasetsManager Reference](https://mastra.zisheng.pro/reference/datasets/datasets-manager)
- [Dataset Reference](https://mastra.zisheng.pro/reference/datasets/dataset)
- 📹 [Mastra Evals、Dataset 和实验 workshop](https://www.youtube.com/watch?v=Vla5LfmOOrM)