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

# 資料集概覽

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

資料集是測試案例的集合，你可以針對這些案例執行實驗，以衡量 Agent 和 Workflow 的表現。每次變更都會建立新版本，讓你能夠準確重現過往的實驗。將資料集配合[評分器](https://mastra.zisheng.pro/zh-HK/docs/evals/overview)使用，即可追蹤提示、模型或程式碼變更所帶來的質素差異。

**供 AI Agent 使用：** 執行 `npx mastra api dataset create '{"name":"translation-pairs"}'`，即可直接建立資料集，無需開啟 Studio 或編寫臨時指令碼。此命令需要一個正在運行的 Mastra 伺服器，並配備支援資料集的儲存適配器；你可以使用 `npx mastra dev` 啟動本機伺服器，或透過 `--url` 傳入可連線伺服器的基礎 URL。加入不同的資料集欄位前，請執行 `npx mastra api dataset create --schema`。使用 `npx skills add mastra-ai/skills --skill mastra` 安裝 Mastra 的 Skill，即可取得完整的 API CLI 探索、目標設定、schema、驗證和錯誤處理指引。

## 使用方式

### 設定儲存空間

在 Mastra 實例中設定儲存空間。資料集需要提供 `datasets` domain 的儲存適配器：

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

### 存取資料集 API

所有資料集操作都可透過 `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` 參考文件](https://mastra.zisheng.pro/zh-HK/reference/datasets/datasets-manager)。

## Studio

你也可以在 [Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview) 中管理資料集。開啟 Studio 後，從側邊欄選擇 **Datasets**，即可查看所有可用的資料集或建立新資料集。

如要開始使用，請選擇 **Create Dataset**，然後設定名稱、描述及可選的 schema。確認後，你會看到資料集詳細資料頁面，當中有兩個分頁：**Items** 和 [**Experiments**](https://mastra.zisheng.pro/zh-HK/docs/datasets/running-experiments)。

在 **Items** 檢視中，你可以加入、更新及刪除項目，亦可查看版本記錄。選擇 **Add Item**，即可透過用於輸入和標準答案的 JSON 編輯器插入新項目。你亦可在此檢視中，從 CSV 或 JSON 檔案大量匯入項目。匯入時，請將每個欄對應至相關的資料集欄位。

選擇 **Versions** 即可查看資料集的完整變更記錄。選擇 **Compare Versions** 後，揀選任意兩個版本，再選擇 **Compare**，即可並排查看兩個版本之間所有新增、變更或移除項目的差異。

## 建立資料集

呼叫 [`create()`](https://mastra.zisheng.pro/zh-HK/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

建立資料集時傳入 [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 的項目會在插入時被拒絕。

## 加入項目

使用 [`addItem()`](https://mastra.zisheng.pro/zh-HK/reference/datasets/addItem) 加入單一項目，或使用 [`addItems()`](https://mastra.zisheng.pro/zh-HK/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' },
    },
  ],
})
```

## 更新及刪除項目

[`updateItem()`](https://mastra.zisheng.pro/zh-HK/reference/datasets/updateItem)、[`deleteItem()`](https://mastra.zisheng.pro/zh-HK/reference/datasets/deleteItem) 和 [`deleteItems()`](https://mastra.zisheng.pro/zh-HK/reference/datasets/deleteItems) 可讓你按 `itemId` 修改或移除現有項目：

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

## 列出及搜尋項目

[`listItems()`](https://mastra.zisheng.pro/zh-HK/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 })
```

## 版本管理

每次變更資料集中的項目（加入、更新或刪除），都會遞增資料集的版本。這讓你可以將實驗固定至特定的資料快照。

### 列出版本

使用 [`listVersions()`](https://mastra.zisheng.pro/zh-HK/reference/datasets/listVersions) 查看分頁顯示的版本記錄：

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

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

### 查看項目記錄

呼叫 [`getItemHistory()`](https://mastra.zisheng.pro/zh-HK/reference/datasets/getItemHistory) 並傳入 `itemId`，即可查看特定項目在不同版本之間的變更：

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

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

### 固定至特定版本

擷取過往版本中當時存在的項目：

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

你亦可將實驗固定至某個版本，詳情請參閱[執行實驗](https://mastra.zisheng.pro/zh-HK/docs/datasets/running-experiments)。如要查看完整的方法和參數清單，請參閱 [`Dataset` 參考文件](https://mastra.zisheng.pro/zh-HK/reference/datasets/dataset)。

## 相關內容

- [執行實驗](https://mastra.zisheng.pro/zh-HK/docs/datasets/running-experiments)
- [評分器概覽](https://mastra.zisheng.pro/zh-HK/docs/evals/overview)
- [DatasetsManager 參考文件](https://mastra.zisheng.pro/zh-HK/reference/datasets/datasets-manager)
- [Dataset 參考文件](https://mastra.zisheng.pro/zh-HK/reference/datasets/dataset)
- 📹 [Mastra Evals、資料集及實驗工作坊](https://www.youtube.com/watch?v=Vla5LfmOOrM)