Feedback

Un feedback score es una calificación con nombre y valor sobre una traza o un span. Con ellos mides la calidad de las respuestas de tu modelo.

¿Qué es un feedback score?

Cada calificación tiene cuatro partes:

Parte	Qué es
`name`	Qué mides: user_rating, relevance, hallucination… Lo eliges tú.
`value`	Un número. Elige una escala (por ejemplo, de 0 a 1) y úsala siempre igual.
`reason`	Opcional. Por qué diste esa calificación.
`target`	La traza o el span que calificas.

Una misma traza puede tener varias calificaciones, una por cada cosa que midas. Ideas de qué medir en Métricas.

En la app

La app no tiene hoy una pantalla para calificar trazas: las calificaciones se registran por API. Donde sí las ves es en Entrenar › Experimentos, que muestra el promedio de cada calificación por experimento (ver Experimentos).

API

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

GET/opik/feedback

Lista calificaciones y promedios

POST/opik/feedback

Agrega una calificación

PUT/opik/feedback

Agrega varias calificaciones

Listar calificaciones

Parámetro	Tipo	Descripción
`trace_id`	texto	Devuelve solo las calificaciones de esa traza.
`name`	texto	Filtra por nombre de calificación. Solo aplica sin trace_id.

Respuesta 200

{
  "success": true,
  "data": {
    "feedbackScores": [
      {
        "targetId": "…",
        "targetType": "trace",
        "name": "user_rating",
        "value": 0.8,
        "reason": "Respuesta clara",
        "source": "sdk"
      }
    ],
    "stats": {
      "total": 150,
      "byName": {
        "user_rating": { "count": 80, "avgValue": 0.85 },
        "relevance": { "count": 70, "avgValue": 0.92 }
      },
      "avgValue": 0.88
    }
  }
}

Agregar una calificación

Campo	Tipo	Descripción
`target_id`	texto	Obligatorio. Id de la traza o del span.
`name`	texto	Obligatorio. Nombre de la calificación.
`value`	número	Obligatorio.
`target_type`	texto	trace o span. Por defecto trace.
`reason`	texto	Motivo de la calificación.
`source`	texto	Origen que se guarda en Opik. Por defecto api.
`category_name`	texto	Categoría, si tu calificación la usa.

bash

curl -X POST "https://app.astrapp.lat/api/v1/projects/$PROJECT_ID/opik/feedback" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "ID_DE_LA_TRAZA",
    "target_type": "trace",
    "name": "user_rating",
    "value": 0.8,
    "reason": "El usuario dio 4 de 5 estrellas"
  }'

Responde 201 con la calificación guardada en data.feedback. Si falta target_id, name o value, responde 400.

Agregar varias calificaciones

Manda un arreglo scores. Cada elemento lleva target_id, name y value, y opcionalmente target_type, reason y source. Cada calificación se procesa por separado: las que fallan no detienen a las demás.

Cuerpo

{
  "scores": [
    { "target_id": "ID_TRAZA_1", "name": "relevance", "value": 0.9 },
    { "target_id": "ID_TRAZA_2", "name": "relevance", "value": 0.6 },
    { "target_id": "ID_SPAN_1", "target_type": "span", "name": "latency_ok", "value": 1 }
  ]
}

Respuesta 200

{
  "success": true,
  "data": {
    "addedCount": 3,
    "totalRequested": 3,
    "message": "3 feedback score(s) agregado(s)"
  }
}

Si alguna falla, la respuesta trae además un arreglo errors con el motivo de cada una.

Límites y notas

El listado solo trae calificaciones de trazas, no de spans.
Sin trace_id, el listado revisa las primeras 100 trazas que devuelve Opik: los stats no cubren trazas más allá de esas.
Los promedios agrupan por nombre exacto: relevance y Relevance son dos calificaciones distintas.
Si Opik no responde, el listado devuelve feedbackScores: [] con un campo warning.

El origen en el listado

En la respuesta del listado, source siempre vale sdk, aunque hayas mandado otro valor al crear la calificación.