Evalúa tus prompts: métodos, calificadores y migración a Promptfoo
En esta página
Lección actualizada el 3 de noviembre de 2026 según la documentación de OpenAI:
temperatureytop_psolo se aceptan con un esfuerzo de razonamiento denone, mientras que los modelos GPT-5.6 razonan por defecto (medium). Por tanto, las llamadas que establezcan estos parámetros deben especificarreasoning={"effort": "none"}(API de Responses) oreasoning_effort="none"(Chat Completions). Fuentes: Uso de GPT-6 · GPT-5.6 Terra.
Actualización del 2 de noviembre de 2026 — Plataforma Evals. OpenAI ha anunciado el fin de su plataforma Evals: las evaluaciones existentes son de solo lectura desde el 31 de octubre de 2026, y el panel de control junto con la API cerrarán el 30 de noviembre de 2026, incluidos los calificadores. OpenAI ha publicado una guía de migración a Promptfoo. Los principios de evaluación de esta lección siguen siendo válidos; solo cambia la herramienta.
Por qué debes evaluar de forma sistemática
No puedes mejorar lo que no mides. Cuando cambias un prompt, un modelo o un parámetro, ¿cómo sabes si la calidad ha mejorado realmente? El método espontáneo consiste en probar tres o cuatro ejemplos, encontrar las mejores respuestas y desplegar. Esto falla con frecuencia porque los ejemplos probados son precisamente los que causaron problemas la semana pasada: mides la mejora donde la buscaste y pasas por alto las regresiones introducidas en casos que ya funcionaban.
Las evaluaciones (evals) convierten esta intuición en una medida objetiva. Hasta 2026, OpenAI ofrecía una plataforma integrada para ello, Evals; es de solo lectura desde el 31 de octubre de 2026 y cerrará el 30 de noviembre. OpenAI recomienda ahora Promptfoo, una herramienta de código abierto para evaluación y red teaming. La buena noticia es que ambas comparten los mismos bloques de construcción: datos de prueba, prompts, modelos y criterios de puntuación. Lo que aprendas aquí en código Python se traslada directamente, y la parte final de la lección muestra el paso a Promptfoo.
Tres conceptos estructuran todo el proceso. El conjunto de datos (dataset) es un conjunto de casos de prueba con entradas y salidas esperadas: es tu referencia, el equivalente a una suite de pruebas unitarias. El calificador (grader) es un criterio de evaluación —coincidencia exacta, LLM como juez, puntuación— que decide si una respuesta dada es buena. La ejecución (run) es una evaluación realizada sobre un conjunto de datos con un modelo y un prompt específicos; es la unidad que comparas de una versión a la siguiente.
Construye un conjunto de datos que refleje tu mundo real
Un caso de prueba consta de una entrada, una salida esperada y metadatos. Estos últimos no son decorativos: son lo que te permitirá darte cuenta, a posteriori, de que una puntuación global del 87 % oculta un colapso en la categoría «código» compensado por excelentes resultados en geografía. Sin categoría o dificultad, solo tienes un número agregado, y un número agregado nunca te dice dónde intervenir.
import json
# Un conjunto de datos es una lista de casos de prueba
dataset = [
{
"input": "What is the capital of France?",
"expected": "Paris",
"metadata": {"category": "geography", "difficulty": "easy"},
},
{
"input": "Explain Bayes' theorem in one sentence.",
"expected": "Bayes' theorem calculates the probability "
"of an event based on known conditional probabilities.",
"metadata": {"category": "mathematics", "difficulty": "medium"},
},
{
"input": "Write a Python function that reverses a list.",
"expected": "def reverse_list(lst): return lst[::-1]",
"metadata": {"category": "code", "difficulty": "easy"},
},
]
# Guardar como JSONL
with open("eval_dataset.jsonl", "w") as f:
for case in dataset:
f.write(json.dumps(case, ensure_ascii=False) + "\n")
Un conjunto de datos inventado en la oficina evalúa tu imaginación, no tu aplicación. Tus usuarios formulan sus solicitudes de forma diferente a la tuya: errores tipográficos, preguntas a medias, contexto implícito. La mejor fuente de casos de prueba son, por tanto, tus propios datos de producción, siempre que un humano valide las respuestas de referencia; de lo contrario, congelarás los errores actuales como norma.
import openai
import random
client = openai.OpenAI()
def create_dataset_from_logs(
production_logs: list[dict],
sample_size: int = 100,
) -> list[dict]:
"""Crea un conjunto de datos de evaluación a partir de registros de producción."""
# Muestreo
sample = random.sample(
production_logs,
min(sample_size, len(production_logs)),
)
dataset = []
for log in sample:
dataset.append({
"input": log["prompt"],
"expected": log["validated_response"], # Respuesta validada por un humano
"metadata": {
"source": "production",
"date": log["date"],
"original_model": log["model"],
},
})
return dataset
Elige el calificador adecuado
El calificador de coincidencia exacta es el más estricto y rápido. Solo sirve para tareas donde la salida está restringida: una clasificación de tres categorías, extraer un número de factura, una respuesta de sí o no. Si se usa en texto libre, daría cero a una respuesta perfecta simplemente formulada de forma diferente a la de referencia.
def exact_grader(response: str, expected: str) -> dict:
"""Evalúa si la respuesta coincide exactamente."""
score = 1.0 if response.strip().lower() == expected.strip().lower() else 0.0
return {"score": score, "type": "exact"}
El calificador de inclusión relaja la restricción: comprueba la presencia de palabras clave esperadas y devuelve una puntuación parcial. Esta es la herramienta adecuada para respuestas que deben cubrir puntos obligatorios sin que importe la redacción; por ejemplo, una respuesta de soporte que debe mencionar el plazo de desistimiento y la dirección de devolución. Su debilidad es bien conocida: un texto que contenga las palabras correctas en un orden absurdo obtendría una puntuación perfecta.
def inclusion_grader(response: str, keywords: list[str]) -> dict:
"""Comprueba que la respuesta contenga las palabras clave esperadas."""
response_lower = response.lower()
found = sum(1 for word in keywords if word.lower() in response_lower)
score = found / len(keywords) if keywords else 0.0
return {
"score": score,
"found": found,
"total": len(keywords),
"type": "inclusion",
}
Luego está el más potente: otro LLM evalúa la calidad de la respuesta. El calificador LLM-as-Judge aprecia lo que ninguna regla mecánica puede: claridad, exhaustividad, precisión del tono. Dos detalles de implementación lo hacen práctico. Primero, temperature=0.0: sin esto, el mismo juez asignaría puntuaciones diferentes a la misma respuesta de una ejecución a otra, y tu punto de referencia perdería todo valor comparativo. Segundo, la gestión de json.JSONDecodeError: un juez que comente en lugar de devolver JSON no debería hacer fallar toda la campaña.
def llm_judge_grader(
question: str,
response: str,
expected: str,
criteria: str = "accuracy, completeness, clarity",
) -> dict:
"""Utiliza un LLM para evaluar la calidad de la respuesta."""
judge_prompt = f"""Rate the quality of this response on a scale of 1 to 5.
Question: {question}
Expected Response: {expected}
Response to Evaluate: {response}
Criteria: {criteria}
Respond ONLY with JSON:
{{"score": <1-5>, "justification": "<short explanation>"}}"""
response_obj = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requiere effort none
input=judge_prompt,
temperature=0.0,
)
import json
try:
result = json.loads(response_obj.output_text)
result["normalized_score"] = result["score"] / 5.0
return result
except json.JSONDecodeError:
return {"score": 0, "justification": "Parsing error", "normalized_score": 0}
Ensambla la evaluación completa
La orquestación no presenta dificultad conceptual: iteras sobre el conjunto de datos, llamas al modelo con el prompt de sistema a probar, aplicas el calificador y agregas. Lo interesante es que la función de puntuación entra como parámetro, lo que te permite volver a ejecutar exactamente el mismo conjunto de datos con diferentes criterios según la campaña: inclusión para una comprobación rápida durante el desarrollo, juez LLM para la validación antes de producción.
async def run_eval(
dataset: list[dict],
model: str,
system_prompt: str,
grader_fn,
) -> dict:
"""Ejecuta una evaluación completa sobre un conjunto de datos."""
results = []
for case in dataset:
response = client.responses.create(
model=model,
instructions=system_prompt,
input=case["input"],
)
score = grader_fn(response.output_text, case["expected"])
results.append({
"input": case["input"],
"expected": case["expected"],
"obtained": response.output_text,
**score,
})
# Calcular métricas agregadas
scores = [r["score"] for r in results if "score" in r]
return {
"model": model,
"num_cases": len(dataset),
"average_score": sum(scores) / len(scores) if scores else 0,
"min_score": min(scores) if scores else 0,
"max_score": max(scores) if scores else 0,
"results": results,
}
El informe mantiene min_score y el detalle de cada caso, y eso es deliberado. La media te dice si avanzas; los casos con peor puntuación te dicen por qué. Hazte el hábito de leer las cinco peores respuestas de cada ejecución antes de comentar la media: ahí es donde, y rara vez en otro sitio, encontrarás la siguiente corrección que hacer.
Industrializa con Promptfoo
Escribir tus evals a mano en Python es educativo; mantenerlos en el tiempo es más cómodo con una herramienta dedicada. La guía de migración de OpenAI describe la lógica de Promptfoo: la evaluación reside en un archivo de configuración, promptfooconfig.yaml, que reúne prompts, modelo(s), casos de prueba y criterios —llamados aquí aserciones—. Se ejecuta desde la línea de comandos, localmente o en tu integración continua, y vive junto al código de la aplicación.
description: Support ticket classification
prompts:
- "Classify this ticket into a single category (billing, technical, account): {{ticket}}"
providers:
- openai:gpt-6.1-sol
tests:
- vars:
ticket: "My card was charged twice this month."
assert:
- type: icontains
value: billing
- vars:
ticket: "The app crashes when I open a PDF."
assert:
- type: icontains
value: technical
promptfoo eval -c promptfooconfig.yaml --no-cache
promptfoo view
promptfoo validate config -c promptfooconfig.yaml # en caso de error de configuración
Los calificadores de esta lección reaparecen como aserciones: coincidencia exacta, inclusión de palabras clave y juicio del modelo. OpenAI advierte sobre este último punto: un calificador recreado, especialmente un juez LLM, debe revalidarse antes de usarse para decidir sobre una regresión, porque las puntuaciones no serán necesariamente idénticas de una herramienta a otra.
Puntos clave
- Las evals convierten la intuición en una medida objetiva de la calidad
- Crea tus conjuntos de datos a partir de casos reales de producción, validados por un humano
- Elige el calificador según la tarea: exacto para restringido, inclusión para puntos obligatorios, LLM-as-Judge para matices
- Establece
temperature=0.0en el juez para que las puntuaciones sean reproducibles - Ejecuta evals antes de cada cambio de prompt o de modelo
- La plataforma Evals de OpenAI cierra el 30 de noviembre de 2026: Promptfoo, recomendado por OpenAI, se hace cargo de conjuntos de datos, prompts, modelos y criterios en un archivo de configuración