Datasets en Opik

Un dataset de evaluación reúne ejemplos con su respuesta esperada. Sobre él corres tu modelo y comparas versiones en experimentos.

¿Qué es un dataset de evaluación?

Un dataset tiene nombre, descripción y una lista de ejemplos (items). Cada item tiene:

Campo	Qué es
`input`	Obligatorio. Lo que recibe el modelo: una pregunta, una conversación…
`expected_output`	La respuesta que esperas.
`metadata`	Datos libres del ejemplo: categoría, dificultad, origen…

No es lo mismo que un dataset de entrenamiento de AstrApp (ver API de datasets): este vive en Opik y sirve para evaluar, no para entrenar. Usa ejemplos que tu modelo no haya visto al entrenar.

En la app

Cuando creas un dataset de entrenamiento con POST /api/v1/datasets, AstrApp intenta copiarlo a Opik en segundo plano, con hasta 100 ejemplos. En conversaciones, el último mensaje queda como expected_output.
En Entrenar › Experimentos, el diálogo Nuevo experimento lista tus datasets de Opik para elegir uno. Ese diálogo todavía no guarda el experimento: créalo por API (ver Experimentos).

API

Rutas bajo /api/v1/projects/{projectId}. Funcionan con la sesión de la app o con API key.

GET/opik/datasets

Lista los datasets

POST/opik/datasets

Crea un dataset

DELETE/opik/datasets?name={nombre}

Borra un dataset

GET/opik/datasets/{nombre}/items

Lista sus items

POST/opik/datasets/{nombre}/items

Agrega items

DELETE/opik/datasets/{nombre}/items?item_id={id}

Borra un item

Listar datasets

Parámetro	Tipo	Descripción
`page`	número	Página, desde 1. Por defecto 1.
`size`	número	Elementos por página. Por defecto 50.

Respuesta 200

{
  "success": true,
  "data": {
    "datasets": [
      {
        "id": "…",
        "name": "soporte-eval",
        "description": "Preguntas frecuentes de soporte",
        "itemsCount": 120,
        "createdAt": "2026-09-01T18:00:00.000Z",
        "updatedAt": "2026-09-10T12:00:00.000Z"
      }
    ],
    "pagination": { "page": 1, "size": 50, "total": 1, "totalPages": 1 }
  }
}

Crear un dataset

name es obligatorio; description e items son opcionales. Puedes crear el dataset vacío y agregarle items después.

bash

curl -X POST "https://app.astrapp.lat/api/v1/projects/$PROJECT_ID/opik/datasets" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "soporte-eval",
    "description": "Preguntas frecuentes de soporte",
    "items": [
      {
        "input": { "question": "¿Cuál es el horario de atención?" },
        "expected_output": { "answer": "De lunes a viernes, de 9 a 18 h" }
      }
    ]
  }'

Responde 201 con data.dataset (id, name, description, itemsCount, createdAt).

Agregar items

Manda un item o un arreglo de items. Acepta expected_output o expectedOutput.

bash

curl -X POST "https://app.astrapp.lat/api/v1/projects/$PROJECT_ID/opik/datasets/soporte-eval/items" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "input": { "question": "¿Cómo devuelvo un producto?" },
      "expected_output": { "answer": "Tienes 30 días para…" }
    },
    {
      "input": { "question": "¿Hacen envíos internacionales?" },
      "expected_output": { "answer": "Sí, a…" }
    }
  ]'

Respuesta 201

{
  "success": true,
  "data": {
    "datasetName": "soporte-eval",
    "addedCount": 2,
    "message": "2 item(s) agregado(s) exitosamente"
  }
}

Listar items

Acepta los mismos page y size. Cada item trae id, input, expectedOutput, metadata y, si salió de una traza, traceId y spanId.

Límites y notas

El dataset se identifica por su nombre: en la ruta de items y al borrarlo. Si el nombre tiene espacios o acentos, codifícalo en la URL (encodeURIComponent).
Los items sin input se saltan sin error: revisa addedCount.
Si Opik no responde, los listados devuelven la lista vacía con un campo warning, y las escrituras responden 500.

Borrar es definitivo

DELETE /opik/datasets?name=… borra el dataset en Opik y la API no tiene forma de recuperarlo.