資料集概觀

新增於： @mastra/core@1.4.0

資料集是測試案例的集合，可用來執行實驗，衡量 Agent 和 Workflow 的表現。每次異動都會建立新版本，因此能精確重現過往實驗。將資料集搭配評分器，即可追蹤提示詞、模型或程式碼變更造成的品質差異。

給 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 探索、目標指定、結構描述、驗證與錯誤處理指引。

使用方式

設定儲存區

在 Mastra 執行個體中設定儲存區。資料集需要提供 datasets 領域的儲存配接器：

src/mastra/index.ts

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 使用：

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 參考文件。

Studio

你也可以在 Studio 中管理資料集。開啟 Studio 後，從側邊欄選取 Datasets，即可查看所有可用資料集或建立新資料集。

若要開始，請選取 Create Dataset，並設定名稱、說明及選用的結構描述。確認後會顯示資料集詳細資料頁，其中包含 Items 與 Experiments 兩個分頁。

在 Items 檢視中，你可以新增、更新及刪除項目，也能查看版本歷程記錄。選取 Add Item，即可使用輸入和標準答案的 JSON 編輯器插入新項目。你也可以從此檢視批次匯入 CSV 或 JSON 檔案中的項目。匯入時，請將每個欄對應至相應的資料集欄位。

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

建立資料集

呼叫 create()，並傳入名稱與選用說明：

src/mastra/datasets/create-dataset.ts

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

定義結構描述

建立資料集時傳入 Standard JSON Schema（Zod、Valibot、ArkType 等），即可強制規範 input 與 groundTruth 的結構：

src/mastra/datasets/create-with-schema.ts

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(),
  }),
})

不符合結構描述的項目會在插入時遭到拒絕。

新增項目

使用 addItem() 新增單一項目，或使用 addItems() 批次插入：

src/mastra/datasets/add-items.ts

// 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()、deleteItem() 和 deleteItems() 可依 itemId 修改或移除現有項目：

src/mastra/datasets/update-delete.ts

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() 支援分頁與全文搜尋：

src/mastra/datasets/list-items.ts

// 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() 查看分頁顯示的版本歷程：

src/mastra/datasets/list-versions.ts

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

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

查看項目歷程

呼叫 getItemHistory() 並傳入 itemId，即可查看特定項目在各版本間的變化：

src/mastra/datasets/item-history.ts

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

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

鎖定版本

擷取過往版本中實際存在的項目：

src/mastra/datasets/pin-version.ts

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

你也可以將實驗鎖定至特定版本，詳情請參閱執行實驗。如需完整方法與參數清單，請參閱 Dataset 參考文件。

相關內容

• 執行實驗
• 評分器概觀
• DatasetsManager 參考文件
• Dataset 參考文件
• 📹 Mastra Evals、資料集與實驗工作坊