Experimentos

Un experimento registra cómo respondió una versión de tu modelo a un dataset de evaluación. Con uno por versión sobre el mismo dataset, comparas con datos antes de reemplazar el modelo en producción.

¿Qué es un experimento?

Un experimento de Opik pertenece a un dataset y guarda, por cada item, la respuesta de tu modelo y sus calificaciones.

Campo de cada item	Qué es
`dataset_item_id`	Id del item del dataset que respondió el modelo.
`input / output`	La entrada y la respuesta de tu modelo.
`trace_id`	Opcional. La traza de esa respuesta.
`feedback_scores`	Calificaciones de esa respuesta: `[{ "name", "value", "reason"? }]`.

AstrApp promedia cada calificación por nombre (feedbackScoresAvg). Comparar dos versiones es comparar esos promedios sobre el mismo dataset.

En la app

Entrenar › Experimentos (Starter+) lista los experimentos de Opik de tu organización con el promedio de cada calificación. La descripción que muestra sale de metadata.description.

Crea los experimentos por API

El botón Nuevo experimento de esa pantalla todavía no guarda el experimento: se pierde al recargar. Créalo con POST /opik/experiments y aparecerá en la lista.

API

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

GET/opik/experiments

Lista experimentos o da el detalle de uno

POST/opik/experiments

Crea un experimento

PUT/opik/experiments

Agrega items a un experimento

DELETE/opik/experiments?experiment_id={id}

Borra un experimento

Crear un experimento

name y dataset_name son obligatorios; metadata e items son opcionales. En dataset_name va el nombre de uno de tus datasets de Opik.

bash

curl -X POST "https://app.astrapp.lat/api/v1/projects/$PROJECT_ID/opik/experiments" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mi-modelo-v2-soporte",
    "dataset_name": "soporte-eval",
    "metadata": { "description": "v2 afinada, sobre soporte-eval", "model": "mi-modelo-v2" },
    "items": [
      {
        "dataset_item_id": "ID_DEL_ITEM",
        "input": { "question": "¿Cuál es el horario de atención?" },
        "output": { "answer": "De lunes a viernes, de 9 a 18 h" },
        "feedback_scores": [{ "name": "correctness", "value": 1 }]
      }
    ]
  }'

Respuesta 201

{
  "success": true,
  "data": {
    "experiment": {
      "id": "…",
      "name": "mi-modelo-v2-soporte",
      "datasetName": "soporte-eval",
      "status": "pending",
      "createdAt": "2026-09-20T18:00:00.000Z"
    },
    "message": "Experimento creado exitosamente"
  }
}

Agregar items

Manda experiment_id y un arreglo items con los campos de arriba. Responde con addedCount.

Cuerpo

{
  "experiment_id": "ID_DEL_EXPERIMENTO",
  "items": [
    {
      "dataset_item_id": "ID_DEL_ITEM",
      "output": { "answer": "…" },
      "feedback_scores": [{ "name": "correctness", "value": 0 }]
    }
  ]
}

Listar y comparar

Parámetro	Tipo	Descripción
`experiment_id`	texto	Devuelve el detalle de ese experimento con sus items.
`dataset_name`	texto	Filtra el listado por dataset.
`page`	número	Página, desde 1. Por defecto 1.
`size`	número	Elementos por página. Por defecto 20.

Sin experiment_id recibes data.experiments y data.pagination. Con él recibes data.experiment, data.items y data.pagination; ahí feedbackScoresAvg se calcula con los items de la página que pides.

typescript

const base = `https://app.astrapp.lat/api/v1/projects/${projectId}/opik/experiments`
const headers = { Authorization: `Bearer ${apiKey}` }

async function promedios(experimentId: string) {
  const res = await fetch(`${base}?experiment_id=${experimentId}&size=100`, { headers })
  const { data } = await res.json()
  return data.experiment.feedbackScoresAvg as Record<string, number>
}

const v1 = await promedios(ID_EXPERIMENTO_V1)
const v2 = await promedios(ID_EXPERIMENTO_V2)
console.log('correctness', { v1: v1.correctness, v2: v2.correctness })

Experimentos A/B

No disponible por ahora

GET y POST /opik/ab-experiments y POST /opik/ab-experiments/{experimentId}/start existen, pero hoy no leen ni guardan los experimentos de tu proyecto. Mientras se corrigen, compara versiones con los experimentos de Opik de esta página.

Límites y notas

En las respuestas de GET, status siempre vale completed: no indica si el experimento terminó.
El filtro dataset_name se aplica sobre la página ya leída.
Si Opik no responde, el listado devuelve experiments: [] con un campo warning, y las escrituras responden 500.

Buenas prácticas

Evalúa con datos que no usaste para entrenar.
Compara varias calificaciones, no una sola.
Usa suficientes items para que la diferencia no sea casualidad.
Incluye preguntas difíciles y casos límite en el dataset.