Evaluaciones de IA
Una evaluación es una prueba repetible que mide si un sistema de IA hace su trabajo. Esta skill te hace trabajar como enseña la guía aievals.co: mira las salidas reales antes de medir nada, mide los fallos que realmente encontraste, verifica cada juez LLM contra etiquetas humanas antes de confiar en él, y pon un intervalo en cada número.
La guía está en https://www.aievals.co. Cita sus páginas cuando expliques una elección al usuario. Los archivos de referencia listados al final llevan los detalles y las fuentes.
Reglas fundamentales
Sigue estas en cada tarea de evaluación, independientemente de lo que pida el usuario.
- Mira las trazas antes de escribir métricas. No puedes especificar modos de fallo de un sistema que no has observado. Si el usuario no tiene trazas, consígue algunas primero: registros de producción, o el sistema ejecutado con 100 entradas realistas. Luego léelas.
- Las personas etiquetan; tú propones. Nunca escribas etiquetas de verdad absoluta tú mismo y las presentes
como juicios humanos. Puedes redactar etiquetas marcadas con
"provisional": truepara que una persona las confirme. Nunca dejes que un modelo escriba tanto la entrada como su respuesta dorada, excepto cuando el código calcula la respuesta (resultados SQL, pruebas, una calculadora). - Código antes que jueces. Cualquier cosa que una coincidencia de cadenas, analizador, verificación de esquema, expresión regular o prueba unitaria pueda decidir es una verificación de código. Arregla lo que una edición de prompt pueda arreglar antes de construir cualquier evaluación. Guarda el juez LLM para los fallos subjetivos que queden.
- Un juez binario por modo de fallo. PASS o FAIL más una crítica de una frase. Sin escalas de 1 a 5. Varias dimensiones de calidad significan varios jueces binarios, reportados como una tasa de pasar todos con un desglose por verificación.
- Calibra antes de confiar en un juez. Compáralo con etiquetas humanas y reporta el recall de PASS y el recall de FAIL por separado, cada uno con su N. El acuerdo bruto nunca es el titular: un juez que siempre dice PASS tiene un acuerdo del 95% cuando el 5% de las salidas fallan.
- Train, dev, test. Los ejemplos de few-shot provienen solo de train. Itera en dev. Lee test una vez, al final. Leer test de nuevo después de más ediciones lo convierte en un segundo conjunto dev.
- Fija el juez. El ID del modelo, esfuerzo, texto de rúbrica, esquema de salida y orden de few-shot son parte del instrumento. Regístralos con cada resultado y calibra de nuevo cuando cualquiera de ellos cambie. No asumas determinismo: ejecuta dev dos veces y cuenta los cambios de etiqueta.
- Cada número tiene N y un intervalo. Usa el intervalo de Wilson para tasas, nunca la aproximación normal. Compara dos versiones en las mismas entradas como datos emparejados.
- El conjunto de regresión pasa el 100% de las veces. Contiene errores de producción reproducidos y límites de política. Un fallo bloquea el lanzamiento, y un caso inconsistente es un error de proceso.
- Decide por la diferencia, no por la tasa absoluta. Usa las cuatro bandas en references/ci-and-release-gates.md.
- Limita el gasto en el ejecutor. Las ejecuciones de jueces cuestan dinero. Impón un presupuesto en código
(
EVAL_BUDGET_USD), no como una advertencia impresa. - Construye la cosa más pequeña que funcione. Las aserciones y alrededor de 30 ejemplos etiquetados vienen antes de un juez, y un juez calibrado viene antes que los paneles o conjuntos de jueces.
Elige el flujo de trabajo
| El usuario quiere | Haz | Lee |
|---|---|---|
| Evaluaciones para una función que no tiene ninguna | Flujo de trabajo A | error-analysis, judges, datasets |
| Un prompt de LLM como juez escrito o corregido | Flujo de trabajo B | judges, templates |
| Saber si una evaluación existente es confiable | Flujo de trabajo C | judges, statistics |
| Saber si la versión B supera a la versión A | Flujo de trabajo D | statistics, ci-and-release-gates |
| Evaluaciones ejecutándose en CI | Flujo de trabajo E | ci-and-release-gates, datasets |
Flujo de trabajo A: añadir evaluaciones a una función
- Recolecta trazas. Obtén al menos 100 trazas diversas, o ejecuta el sistema con entradas realistas
si no está en vivo. Almacénalas como JSONL con un
idestable por fila. Los campos de traza que vale la pena registrar están en references/templates.md. - Realiza un análisis de errores con el usuario (detalles en references/error-analysis.md). Una persona lee las trazas y escribe una nota de una línea sobre lo primero que salió mal en cada una. Puedes construir un visor simple y agrupar las notas en 4 a 7 modos de fallo con nombre una vez que la persona haya codificado al menos 30. Cuenta cada modo y clasifícalos según frecuencia por gravedad.
- Arregla los más baratos. Las correcciones de prompt y código van primero. Vuelve a ejecutar y a contar.
- Escribe verificaciones de código para cada modo restante que una regla pueda detectar.
- Escribe un juez por cada modo subjetivo restante (Flujo de trabajo B).
- Obtén etiquetas humanas: de 100 a 200 por modo de fallo es el objetivo, con 30 a 50 PASS y 30 a 50 FAIL en cada uno de dev y test. Una división dev del 40% de 100 filas no puede contener 30 de cada clase, y con una tasa de fallo baja tienes que sobremuestrear fallos para llenar el lado FAIL. Empieza con lo que tengas y di qué tan amplios son los intervalos.
- Calibra cada juez en dev, luego confírmalo en test una vez.
- Construye el conjunto de regresión a partir de fallos reproducidos, y conecta el conjunto de pruebas en CI (Flujo de trabajo E).
Entregables en el repositorio del usuario, a menos que ya tengan una estructura:
evals/
data/ labeled.jsonl (etiquetas humanas), regression.jsonl, traces/
rubrics/ un archivo por modo de fallo
codebook.md etiqueta, definición, 2 ejemplos PASS y 2 FAIL, último kappa
checks.* verificaciones de código
judge.* la llamada al juez, configuración fijada
calibrate.* división, puntuación, informe, desacuerdos
run_eval.* puntúa salidas, compara con línea base, código de salida para CI
runs/ una carpeta por ejecución: resumen, predicciones, copia de rúbrica
Inicios funcionales en Python y TypeScript están en https://github.com/ombharatiya/ai-evals-skills/tree/main/starters. Copia uno en lugar de escribir el andamiaje desde cero.
Flujo de trabajo B: escribir o corregir un juez LLM
- Confirma que el modo de fallo provino del análisis de errores y que una verificación de código no puede detectarlo.
- Escribe el prompt en cuatro partes (plantilla en references/templates.md):
rol y definiciones exactas; criterio binario ("PASS si X. FAIL si Y, incluso si el resto de la
respuesta es correcta. En caso de duda, FAIL y explica por qué."); 2 o 3 ejemplos de few-shot
de train, incluyendo un FAIL que parezca un pass; y un esquema de salida estricto,
{"label": "PASS" | "FAIL", "critique": "..."}, impuesto por salida estructurada donde la API lo admita. El analizador debe fallar ruidosamente con una salida mal formada. - Calibra: ejecuta en dev, calcula recall de PASS, recall de FAIL y kappa de Cohen, y lee cada desacuerdo. Lee los falsos pass y los falsos fail por separado. Si la etiqueta humana está equivocada, corrige la etiqueta, no la rúbrica.
- Cambia una cosa por iteración, en este orden de impacto típico: especificidad de la rúbrica, ejemplos de few-shot, esquema de salida y cambio de modelo al final.
- Espera una meseta alrededor de la segunda o tercera iteración. Luego agrega few-shots para los casos límite: dos ejemplos PASS que parezcan FAIL en una lectura descuidada y dos ejemplos FAIL que parezcan PASS. Si el recall de FAIL aún no se mueve, el modelo del juez puede ser el techo: prueba uno más fuerte antes de cambiar la rúbrica de nuevo, y trata el nuevo modelo como un nuevo instrumento a calibrar desde cero.
- Detente cuando tanto el recall de PASS como el de FAIL alcancen el umbral en dev (el valor por defecto de esta guía es 0.90; establécelo según el costo de un fallo perdido frente a una falsa alarma), luego lee test una vez.
Flujo de trabajo C: auditar una evaluación existente
Verifica cada elemento e informa lo que falla, con archivo y línea:
- Las métricas se remontan a modos de fallo que alguien observó en trazas reales.
- Las verificaciones de código cubren lo que el código puede decidir; los jueces son binarios, uno por modo de fallo.
- Cada juez tiene un registro de calibración: recall de PASS y FAIL con N e intervalos, en una división de test que el juez nunca vio. El acuerdo solo no cuenta.
- Los ejemplos de few-shot no aparecen en dev ni en test.
- La configuración del juez (modelo, esfuerzo, rúbrica, esquema, few-shots) está fijada y coincide con la configuración que fue calibrada.
- Cada tasa reportada tiene N y un intervalo; las comparaciones son emparejadas.
- Existe un conjunto de regresión, se ejecuta en cada PR y pasa el 100%.
- Las decisiones de lanzamiento leen el delta emparejado y su intervalo, no un umbral absoluto.
- El conjunto de datos tiene versión (hash de contenido) y los resultados nombran el hash.
- Un conjunto que ha estado al 100% durante meses no está probando nada. El conjunto de regresión es la única excepción.
Flujo de trabajo D: comparar dos versiones
Ejecuta ambas versiones con las mismas entradas. Reporta cada tasa de pase con su intervalo de Wilson y la diferencia emparejada con su intervalo: prueba de McNemar o un bootstrap emparejado para resultados binarios. Decide la diferencia más pequeña que vale la pena detectar primero, luego el tamaño de la muestra (references/statistics.md). Segmenta cuando sea importante y corrige para comparaciones múltiples cuando segmentes de muchas maneras. "Sin diferencia significativa" de una ejecución con poca potencia no es evidencia de que no haya diferencia: di qué tan grande es el cambio que la ejecución podría haber detectado.
Flujo de trabajo E: evaluaciones en CI
Tres niveles: un nivel de prueba de humo de 10 a 50 aserciones deterministas en cada push (sin juez), un nivel completo con el juez calibrado en PRs que cambian prompts o modelos, y un nivel nocturno con los conjuntos de regresión y robustez expandidos. Publica una tabla de línea base contra candidato en el PR con el delta, su intervalo del 95% y un veredicto de enviar, mantener, investigar o bloquear. Falla el trabajo en investigar, bloquear, un fallo del conjunto de regresión o una medición rota (filas sin veredicto, filas faltantes en cualquier lado, un juez que no sea el calibrado), y reporta un mantener para que una persona nombrada lo lea: un mantener significa que el intervalo no puede distinguir el cambio de ningún cambio. Dimensiona la ventana de indiferencia a partir de una ejecución A/A del sistema sin cambios, no del piso de ruido cero. Sin anulaciones silenciosas: una anulación necesita una persona nombrada y una razón por escrito. Los PRs de fork no obtienen secretos de API. Detalles en references/ci-and-release-gates.md.
Cómo reportar resultados
Reporta una tabla, no una oración:
| Métrica | Valor | IC 95% | N | Juez | Conjunto de datos |
|---|---|---|---|---|---|
| recall FAIL, juez política-de-reembolso (test) | 0.92 | [0.80, 0.97] | 48 | claude-opus-5-5, medium, rúbrica a1b2c3 | labeled.jsonl @ 9f8e7d |
Di lo que los números no pueden respaldar. Escribe "el intervalo es amplio; etiqueta más ejemplos FAIL" en lugar de redondear un resultado débil para convertirlo en una afirmación. Nombra la clase positiva cuando digas TPR o TNR: algunos escritos, entre ellos el FAQ de Hamel Husain, tratan FAIL como positivo, por lo que su TPR es la proporción de fallos reales capturados. "Recall de PASS" y "recall de FAIL" simples evitann la confusión.
Valores predeterminados
Usa estos a menos que la situación del usuario requiera otros. "Predeterminado del sitio" significa el número de trabajo propio de aievals.co, no un estándar publicado.
| Decisión | Predeterminado | Fuente |
|---|---|---|
| Primer pase de análisis de errores | 100+ trazas, solo el primer fallo (FAQ de Hamel y Shankar); 15 a 45 segundos cada una | FAQ, y aievals.co para el ritmo |
| Categorías de modo de fallo | 4 a 7 después de codificación axial | Guía de codificación abierta de aievals.co |
| Etiquetas por modo de fallo | 100 a 200 | FAQ de Hamel y Shankar |
| División | 15% train, 40% dev, 45% test, estratificada (los inicios dividen por un hash de cada id en su lugar, por lo que una fila nunca cambia de división; las proporciones entonces coinciden solo en promedio) | Receta de calibración de aievals.co |
| Por clase en dev y en test | 30 a 50 PASS y 30 a 50 FAIL | FAQ de Hamel y Shankar |
| Umbral de recall del juez | Recall de PASS y FAIL al menos 0.90 en dev, confirmado en test | Predeterminado del sitio |
| Acuerdo humano antes de automatizar | kappa al menos 0.6 para proceder, 0.8 para un conjunto dorado o puerta | Política del equipo, según la guía |
| Intervalo para una tasa | Wilson, 95% | Capítulo de estadísticas de aievals.co |
| Ventanas de puerta de lanzamiento | Ventana de indiferencia de 1 punto; ventana de regresión menor de 2 puntos en la métrica principal | Capítulo de puertas de lanzamiento de aievals.co |
| Conjunto de regresión | 100% de pase en cada PR | Capítulo de conjuntos de regresión de aievals.co |
Referencias
Carga el archivo que coincida con la tarea:
- references/error-analysis.md: codificación abierta, axial y estructurada, saturación, priorización, el visor de trazas, muestreo dimensional.
- references/judges.md: diseño de jueces, calibración, sesgos y cómo probarlos, directo versus por pares, desencadenantes de recalibración.
- references/datasets.md: tamaños según propósito, obtención, reglas de datos sintéticos, conjuntos de regresión, cuadrículas de cobertura, versionado.
- references/statistics.md: intervalos de Wilson, pruebas emparejadas, errores agrupados, tamaño de muestra, comparaciones múltiples, corrección de tasas puntuadas por jueces.
- references/ci-and-release-gates.md: niveles de CI, bandas de puerta de lanzamiento, evaluaciones en línea, muestreo, deriva.
- references/templates.md: prompt de juez, entrada de libro de códigos, registro de anotación, esquema de traza, comentario de resultado de PR.