Présentation des Datasets

Ajouté dans : @mastra/core@1.4.0

Les Datasets sont des collections de cas de test sur lesquels vous exécutez des Experiments afin de mesurer les performances de vos Agents et Workflows. Chaque mutation crée une nouvelle version, ce qui vous permet de reproduire exactement les Experiments passés. Associez les Datasets à des Scorers pour suivre la qualité en fonction des prompts, des modèles ou des modifications du code.

Pour les Agents IA : exécutez npx mastra api dataset create '{"name":"translation-pairs"}' afin de créer directement un Dataset, sans ouvrir Studio ni écrire de script temporaire. Cette commande nécessite un serveur Mastra en cours d’exécution avec un adaptateur de stockage compatible avec les Datasets ; démarrez le serveur local avec npx mastra dev ou transmettez l’URL de base du serveur accessible au moyen de --url. Exécutez npx mastra api dataset create --schema avant d’ajouter différents champs au Dataset. Installez le Skill de Mastra avec npx skills add mastra-ai/skills --skill mastra pour obtenir des instructions complètes sur la découverte des API avec la CLI, le ciblage, les schémas, l’authentification et la gestion des erreurs.

Utilisation

Configurer le stockage

Configurez le stockage dans votre instance Mastra. Les Datasets nécessitent un adaptateur de stockage qui fournit le domaine 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',
  }),
})

Accéder à l’API des Datasets

Toutes les opérations sur les Datasets sont accessibles au moyen de 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()

Consultez la référence de DatasetsManager pour obtenir la liste complète des méthodes.

Studio

Vous pouvez également gérer les Datasets dans Studio. Après avoir ouvert Studio, sélectionnez Datasets dans la barre latérale pour afficher tous les Datasets disponibles ou en créer un nouveau.

Pour commencer, sélectionnez Create Dataset, puis définissez un nom, une description et, si nécessaire, des schémas. Après confirmation, la page de détails du Dataset affiche deux onglets : Items et Experiments.

Dans la vue Items, vous pouvez ajouter, mettre à jour et supprimer des éléments, ainsi que consulter l’historique des versions. Sélectionnez Add Item pour insérer un nouvel élément à l’aide d’éditeurs JSON pour l’entrée et la vérité terrain. Cette vue permet également d’importer des éléments en masse depuis un fichier CSV ou JSON. Lors de l’importation, associez chaque colonne au champ correspondant du Dataset.

Sélectionnez Versions pour consulter l’historique complet des modifications du Dataset. Après avoir sélectionné Compare Versions, choisissez deux versions, puis sélectionnez Compare pour afficher côte à côte les différences entre tous les éléments ajoutés, modifiés ou supprimés d’une version à l’autre.

Créer un Dataset

Appelez create() avec un nom et, éventuellement, une description :

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

Définir des schémas

Vous pouvez imposer la structure d’input et de groundTruth en transmettant un schéma JSON standard (Zod, Valibot, ArkType, etc.) lors de la création du Dataset :

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

Les éléments qui ne correspondent pas au schéma sont refusés lors de l’insertion.

Ajouter des éléments

Utilisez addItem() pour un seul élément ou addItems() pour effectuer une insertion en masse :

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

Mettre à jour et supprimer des éléments

updateItem(), deleteItem() et deleteItems() permettent de modifier ou de supprimer des éléments existants à l’aide de leur 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'] })

Répertorier et rechercher des éléments

listItems() prend en charge la pagination et la recherche en texte intégral :

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

Gestion des versions

Chaque mutation apportée aux éléments d’un Dataset (ajout, mise à jour ou suppression) incrémente sa version. Vous pouvez ainsi épingler des Experiments à un snapshot précis des données.

Répertorier les versions

Utilisez listVersions() pour consulter l’historique paginé des versions :

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

Consulter l’historique d’un élément

Pour savoir comment un élément précis a évolué d’une version à l’autre, appelez getItemHistory() avec son 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)
}

Épingler une version

Récupérez les éléments exacts qui existaient dans une version antérieure :

src/mastra/datasets/pin-version.ts

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

Vous pouvez également épingler des Experiments à une version ; consultez la page Exécuter des Experiments. Consultez la référence de Dataset pour obtenir la liste complète des méthodes et paramètres.

Voir aussi

• Exécuter des Experiments
• Présentation des Scorers
• Référence de DatasetsManager
• Référence de Dataset
• 📹 Atelier Mastra sur les Evals, Datasets et Experiments