Juzga respuestas y detecta regresiones

Unos 31 minutos de lectura, con 6 ejemplos en 8 secciones.

Edición 2026.11.15 Ejemplos verificados el 19 de nov de 2026 78 de 78 ejemplos pasan Qué ha cambiado

Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros

Traducido del libro en inglés, edición 2026.11.15. Lee el original

Al final de este capítulo, podrás calificar una ejecución del agente con varias medidas a la vez, usar un modelo como juez solo donde los resultados no se puedan comparar directamente, calibrar ese juez frente a etiquetas de referencia que cualquiera pueda recalcular, ver cuánto se mueve una puntuación de una ejecución a la siguiente, y usar en CI una puerta de control para los cambios en los prompts, el contexto o las métricas, basada en ejecuciones registradas.

Casi todos los capítulos han cambiado el agente de la tienda. El capítulo 4 añadió contexto al prompt, y el capítulo 6 trasladó el agente a las métricas de la capa semántica. El capítulo 8 reescribió después el prompt para que rechace una pregunta indicando el motivo. Cada cambio se calificó sobre la partición de desarrollo de las preguntas de oro (golden), las 48 preguntas de la tienda con respuestas verificadas, con una ejecución por pregunta, lo que puede mostrar un cambio grande y no uno pequeño. El nuevo prompt del capítulo 8 corrigió una pregunta de desarrollo y rompió otra, gq-008, los ingresos totales de 2025, y el capítulo 8 solo pudo decir que un cambio aislado como ese "puede ser azar".

Este capítulo construye las mediciones que resuelven preguntas como esa. Informa de una ejecución con más que la exactitud, con un intervalo que indica en qué medida se puede confiar en el número. Añade un juez, una llamada a un modelo que califica lo que la comparación con la referencia no puede evaluar, y mide ese juez antes de confiar en él. Ejecuta las preguntas cinco veces para ver la variabilidad, y convierte todo ello en una puerta de control que un trabajo de CI puede ejecutar en cada cambio, sin conexión, a partir de grabaciones.

Evalúa una ejecución con más que la precisión

Último cambio en la edición 2026.11.12

Una sola cifra de precisión responde a una pregunta, con qué frecuencia acertó el agente, y oculta otras tres que importan igual: qué hizo cuando se equivocó, cuánto costó cada respuesta y cuánto cambiaría esa cifra con otra muestra de preguntas. Un agente que da un número incorrecto y otro que se niega a responder pierden ambos un punto de precisión, pero solo uno de ellos pone un número erróneo en una presentación. Por eso una tabla de resultados informa por separado los números incorrectos, las negativas a responder y los fallos, junto con las medidas de negativas del capítulo 8, y el coste en llamadas al modelo y en tokens del prompt, al lado de la precisión.

La cifra también necesita un intervalo. En un conjunto del tamaño de una partición dorada, cada pregunta equivale a varios puntos, y el intervalo que la mayoría aprende primero, el intervalo de Wald, se comporta mal con conjuntos pequeños. Brown, Cai y DasGupta recomiendan "el intervalo de Wilson o el intervalo de la distribución a priori de Jeffreys de colas iguales para n pequeño" (Brown et al.). En palabras, el intervalo de Wilson invierte el contraste de una proporción: incluye cada precisión verdadera que la observada no rechazaría con el nivel elegido, así que nunca baja de 0 ni sube de 1. Para k aciertos de n, con p = k / n y z = 1.96 para aproximadamente el 95 %:

centre   = (p + z² / 2n) / (1 + z² / n)
half     = z × √( p(1 − p) / n + z² / 4n² ) / (1 + z² / n)
interval = centre − half  to  centre + half

wilson() en lib/regressions.py lo calcula en unas pocas líneas. statsmodels implementa el mismo intervalo como proportion_confint(method="wilson") (statsmodels); las versiones fijadas del libro no incluyen statsmodels, así que el ejemplo no lo llama. replay() ejecuta uno de los agentes del libro sobre preguntas doradas a partir de sus grabaciones, y Scorecard evalúa las ejecuciones. La tabla de resultados que sigue puntúa tres agentes sobre las 21 preguntas de respuesta y negativa de cada partición: el SQL solo con esquema del capítulo 3, el agente orientado a métricas del capítulo 6 y el agente que se niega a responder del capítulo 8. Las preguntas prohibidas se dejan fuera, porque el capítulo 9 las decide por debajo del modelo.

La partición de prueba está reservada, y el libro solo la evalúa para un número que informa. Los capítulos 3 y 6 grabaron sus agentes sobre la prueba una sola vez. Este capítulo grabó el agente que se niega a responder sobre la prueba una sola vez, en la grabación decline-runs-test, con el prompt del capítulo 8 sin cambios, y no cambió nada después. Estas son las cifras finales de prueba del libro para sus agentes.

scorecard.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Score the book's agents on more than accuracy, on dev to compare them and on the held-out test split once.The chapter's points rest on the dev and test lines for correct answers, wrong numbers and decline recall,and on the fixed and broken lines for the declining prompt."""from lib.golden import load_goldenfrom lib.regressions import Scorecard, replayfrom lib.semantic import loadfrom lib.warehouse import connectcon, layer = connect(), load()# Answer and decline questions; forbidden questions are decided below the model, by chapter 9's policies.questions = [q for q in load_golden() if q.kind in ("answer", "decline")]for split in ("dev", "test"):    in_split = [q for q in questions if q.split == split]    print(f"{split} questions: {len(in_split)}")    runs = {agent: replay(con, layer, agent, in_split) for agent in ("schema-only", "metrics-first", "declining")}    for agent, agent_runs in runs.items():        print("\n".join(Scorecard(agent_runs).lines(f"{split} {agent}")))    for label, was, now in (("fixed", False, True), ("broken", True, False)):        # both agents' runs follow the same question order, so zip pairs one question's two outcomes        ids = [a.question.question_id for a, b in zip(runs["metrics-first"], runs["declining"])               if (a.outcome == "correct") == was and (b.outcome == "correct") == now]        print(f"{split} {label} by the declining prompt: {', '.join(ids) or 'none'}")
Salidapython scorecard.py
dev questions: 21
dev schema-only correct: 2 of 21
dev schema-only accuracy: 0.10 (95% interval 0.03 to 0.29)
dev schema-only wrong numbers: 11
dev schema-only errors or step limits: 8
dev schema-only decline recall: 0.00
dev schema-only decline precision: no declines
dev schema-only coverage: 0.62
dev schema-only selective risk: 0.85
dev schema-only model calls per question: 1.0
dev schema-only prompt tokens per question: 827
dev metrics-first correct: 15 of 21
dev metrics-first accuracy: 0.71 (95% interval 0.50 to 0.86)
dev metrics-first wrong numbers: 5
dev metrics-first errors or step limits: 1
dev metrics-first decline recall: 0.75
dev metrics-first decline precision: 1.00
dev metrics-first coverage: 0.81
dev metrics-first selective risk: 0.29
dev metrics-first model calls per question: 1.8
dev metrics-first prompt tokens per question: 2,196
dev declining correct: 15 of 21
dev declining accuracy: 0.71 (95% interval 0.50 to 0.86)
dev declining wrong numbers: 4
dev declining errors or step limits: 1
dev declining decline recall: 1.00
dev declining decline precision: 0.80
dev declining coverage: 0.71
dev declining selective risk: 0.27
dev declining model calls per question: 1.9
dev declining prompt tokens per question: 2,602
dev fixed by the declining prompt: gq-020
dev broken by the declining prompt: gq-008
test questions: 21
test schema-only correct: 3 of 21
test schema-only accuracy: 0.14 (95% interval 0.05 to 0.35)
test schema-only wrong numbers: 10
test schema-only errors or step limits: 8
test schema-only decline recall: 0.00
test schema-only decline precision: no declines
test schema-only coverage: 0.62
test schema-only selective risk: 0.77
test schema-only model calls per question: 1.0
test schema-only prompt tokens per question: 829
test metrics-first correct: 9 of 21
test metrics-first accuracy: 0.43 (95% interval 0.24 to 0.63)
test metrics-first wrong numbers: 5
test metrics-first errors or step limits: 1
test metrics-first decline recall: 1.00
test metrics-first decline precision: 0.40
test metrics-first coverage: 0.48
test metrics-first selective risk: 0.50
test metrics-first model calls per question: 1.5
test metrics-first prompt tokens per question: 1,854
test declining correct: 8 of 21
test declining accuracy: 0.38 (95% interval 0.21 to 0.59)
test declining wrong numbers: 4
test declining errors or step limits: 3
test declining decline recall: 0.75
test declining decline precision: 0.33
test declining coverage: 0.43
test declining selective risk: 0.44
test declining model calls per question: 1.9
test declining prompt tokens per question: 2,622
test fixed by the declining prompt: none
test broken by the declining prompt: gq-043

En dev, ambos agentes aciertan 15 of 21, una precisión de 0.71 (95% interval 0.50 to 0.86), pero no en las mismas preguntas. El prompt que se niega a responder corrigió gq-020 y estropeó gq-008, los dos cambios que encontró el capítulo 8.

La diferencia está en los fallos. El agente que se niega a responder dio 4 números incorrectos frente a los 5 del orientado a métricas, y su exhaustividad de negativas es 1.00 frente a 0.75.

Lo paga en cobertura, 0.71 frente a 0.81, y en tokens del prompt, 2,602 frente a 2,196 por pregunta.

El SQL solo con esquema acierta 2 of 21, y de los números que da, la parte que es incorrecta, su riesgo selectivo, es 0.85.

En prueba, el prompt que se niega a responder no corrigió ninguna pregunta y estropeó una, gq-043, "¿Cuál fue el ingreso del T2?", que el agente del capítulo 6 afrontó con una pregunta de vuelta y en la que el agente que se niega a responder se quedó sin llamadas al modelo. El agente que se niega a responder obtiene 8 of 21 frente a 9 of 21 del orientado a métricas, y el SQL solo con esquema obtiene 3 of 21.

Sus números incorrectos bajaron de 5 a 4, porque una respuesta errónea se convirtió en una ejecución que alcanzó el límite de pasos, no en una correcta. Los intervalos de los dos agentes se solapan casi por completo en ambas particiones. Dos totales con intervalos solapados no permiten saber si un cambio ayudó, por eso la puerta compara las mismas preguntas en pares.

Regla práctica: Informa cada ejecución como una tabla de resultados: aciertos con un intervalo de Wilson, números incorrectos, negativas con su recall y precisión, fallos por tipo, y llamadas y tokens por pregunta. Compara los agentes sobre las mismas preguntas en la misma tabla. Evalúa la partición de prueba una sola vez, cuando informes una cifra final, y di que lo hiciste; cuando los intervalos de dos agentes se solapen, no declares mejor a ninguno a partir de los totales.

Juzga solo lo que no se puede comparar

Último cambio en la edición 2026.11.12

results_match(), la comparación que construyó el capítulo 3, califica un número frente a un resultado de referencia. Gran parte de lo que dice el agente no es un número. El motivo de una negativa, la frase que le dice a la persona por qué no llegó ningún número, no tiene resultado de referencia con el que cotejarse: dos buenos motivos pueden no compartir ninguna palabra, y un motivo fluido puede ser falso. Para un texto así, la herramienta habitual es un juez, una llamada a un modelo que califica una respuesta según una rúbrica y devuelve un veredicto. Un juez es barato e incansable, y tiene sesgos conocidos. Zheng y colegas, que encontraron que los jueces fuertes coincidían con las preferencias humanas casi tan a menudo como los humanos coincidían entre sí, también nombran los "sesgos de posición, de verbosidad y de autoafirmación" (Zheng et al.): un juez puede favorecer la respuesta que aparece primero, la más larga y la suya propia. Un estudio posterior que catalogó doce posibles sesgos halló que los jueces fuertes siguen teniendo un sesgo considerable en tareas concretas (Ye et al.).

Por eso conviene usar un juez solo donde un resultado no puede compararse directamente, y diseñar cada llamada de forma que un sesgo quede a la vista. El juez de la tienda es el propio modelo del libro, el mismo que usa el agente, invocado con un prompt aparte, JUDGE_PAIR en lib/prompts.py. Recibe una pregunta y dos motivos para rechazarla, etiquetados A y B, y nombra el mejor, o un empate, en formato JSON. La rúbrica pide un motivo que explique con exactitud por qué los datos de la tienda no pueden responder y qué podría preguntar la persona en su lugar. Los casos son todas las preguntas de referencia, en cualquiera de las dos particiones, que tanto el agente basado en métricas del capítulo 6 como el agente que rechaza del capítulo 8 rechazaron: 8 pares. Solo 3 de ellos, gq-021, gq-042 y gq-045, son preguntas de rechazo. Los otros 5, gq-032, gq-033, gq-034, gq-037 y gq-041, son preguntas con respuesta, que el almacén sí puede responder, las lagunas de la capa que encontró el capítulo 6, y ambos agentes las rechazaron por error. En esos casos la respuesta correcta era un número, así que el juez compara dos rechazos equivocados. Cada par se juzga dos veces, con el motivo de cada agente primero, de modo que un veredicto que sigue la posición y no el texto cambia con el orden. parse_verdict() en lib/judge.py lee cada respuesta, y el registro judge-verdicts guarda cada llamada.

judge-an-explanation.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Judge only what can't be compared: two reasons for declining the same question, shown in both orders.The points about position, length and which reasons won rest on the same-verdict, consistent-winner andwon-in-both-orders lines, and the answerable lines show which reasons say the data lacks what was asked."""import refrom lib.judge import judge_pairs, recorded_casesfrom lib.model import RecordedModelfrom lib.semantic import loadfrom lib.warehouse import connectcon, layer = connect(), load()_, pairs = recorded_cases(con, layer)results = judge_pairs(RecordedModel("judge-verdicts"), pairs)GROUPS = {"decline": "decline questions", "answer": "answerable questions both agents declined"}AGENTS = ("metrics-first", "declining")# a reason that says the data does not include or contain what was askedBLAMES_DATA = re.compile(r"\bdata (does not|doesn't) (include|contain)")# words a reply uses to offer a path forward or reframe the questionALTERNATIVE = ("alternative", "instead", "reframe", "path forward")for r in results:    print(f"{r.case.question.question_id} ({r.case.question.kind}): metrics-first first -> {r.first.label}; "          f"declining first -> {r.second.label}")n = len(results)print(f"pairs: {n}")for group, name in GROUPS.items():    print(f"pairs on {name}: {sum(r.case.question.kind == group for r in results)}")# second_as_first maps the second order's label back to the first order's labelsprint(f"same verdict in both orders: {sum(r.first.label == r.second_as_first for r in results)} of {n}")print(f"first reason won in both orders: {sum(r.first.label == r.second.label == 'A' for r in results)} of {n}")print(f"second reason won in both orders: {sum(r.first.label == r.second.label == 'B' for r in results)} of {n}")for agent in AGENTS:    print(f"{agent} reason won in both orders: {sum(r.winner == agent for r in results)}")for group, name in GROUPS.items():    for agent in AGENTS:        print(f"{name}, {agent} reason won in both orders: "              f"{sum(r.winner == agent and r.case.question.kind == group for r in results)}")# longer_won compares the winning reason's length with the losing reason's, in charactersprint(f"consistent winner was the longer reason: {sum(r.longer_won for r in results)}")answerable = [r.case for r in results if r.case.question.kind == "answer"]for agent, reasons in (("metrics-first", [c.first for c in answerable]), ("declining", [c.second for c in answerable])):    said = sum(bool(BLAMES_DATA.search(x)) for x in reasons)    print(f"answerable questions, {agent} reasons that say the data lacks it: {said} of {len(answerable)}")replies = [v for r in results for v in (r.first, r.second)]suggests = sum(any(w in v.reason.lower() for w in ALTERNATIVE) for v in replies)print(f"judge replies that suggest an alternative or a reframe: {suggests} of {len(replies)}")
Salidapython judge-an-explanation.py
gq-021 (decline): metrics-first first -> A; declining first -> A
gq-032 (answer): metrics-first first -> B; declining first -> A
gq-033 (answer): metrics-first first -> A; declining first -> B
gq-034 (answer): metrics-first first -> A; declining first -> B
gq-037 (answer): metrics-first first -> A; declining first -> B
gq-041 (answer): metrics-first first -> A; declining first -> B
gq-042 (decline): metrics-first first -> B; declining first -> A
gq-045 (decline): metrics-first first -> A; declining first -> B
pairs: 8
pairs on decline questions: 3
pairs on answerable questions both agents declined: 5
same verdict in both orders: 7 of 8
first reason won in both orders: 1 of 8
second reason won in both orders: 0 of 8
metrics-first reason won in both orders: 5
declining reason won in both orders: 2
decline questions, metrics-first reason won in both orders: 1
decline questions, declining reason won in both orders: 1
answerable questions both agents declined, metrics-first reason won in both orders: 4
answerable questions both agents declined, declining reason won in both orders: 1
consistent winner was the longer reason: 6
answerable questions, metrics-first reasons that say the data lacks it: 1 of 5
answerable questions, declining reasons that say the data lacks it: 5 of 5
judge replies that suggest an alternative or a reframe: 9 of 16

El juez dio el mismo veredicto en ambos órdenes en 7 of 8 pares, y el único que cambió, gq-021, el coste del envío, siguió al motivo que apareció primero. Es sesgo de posición en el único lugar en que un par estaba igualado, ya que los dos motivos dicen casi lo mismo.

De los veredictos consistentes, el motivo del capítulo 6 ganó en 5 casos y el del capítulo 8 en 2, y el motivo más largo fue el ganador en 6 de ellos. Eso es lo que predice el sesgo de verbosidad, aunque 8 pares no bastan para separarlo de que los motivos más largos sean mejores.

Los dos grupos de pares cuentan historias distintas. En las preguntas de respuesta, el juez prefirió el motivo del capítulo 6 en 4 de los 5 pares, y el del capítulo 8 en 1.

Los motivos del capítulo 8 dicen que los datos no incluyen lo que se preguntó en 5 of 5 pares de respuesta, lo cual es falso: el almacén contiene raw.customers.email para gq-037 y fct_orders.discount_eur para gq-041. Los motivos del capítulo 6 lo dicen en 1 of 5; los otros afirman que las métricas no incluyen eso, lo cual es cierto de la capa semántica. Así que en estos pares el juez puede haber preferido el motivo más exacto, el del capítulo 6, y la exactitud y la longitud apuntan en la misma dirección.

En las preguntas de rechazo, el caso para el que se escribió la rúbrica, el motivo del capítulo 6 ganó en 1 de los 3 pares, el del capítulo 8 en 1, y el tercero cambió con el orden. Son muy pocos pares para decir de quién son los motivos mejores.

Leer los veredictos revela un problema mayor que el del orden. De las respuestas del juez, 9 of 16 elogian un motivo por "ofrecer un camino constructivo", una alternativa o una forma de replantear la pregunta, o le reprochan no tenerlo, y ninguno de los motivos de los agentes hace eso en ninguno de estos pares. En gq-032, el margen bruto, el juez prefirió el motivo del capítulo 8 por explicar el cálculo, y el cálculo que ese motivo da, ingresos brutos menos ingresos netos sobre ingresos brutos, no es un margen bruto: el SQL de referencia resta el coste unitario de los productos de los ingresos netos. El juez premió una definición errónea expresada con seguridad. Un veredicto sobre un texto vale solo lo que valga el dominio del juez sobre los hechos que hay detrás, y por eso la sección siguiente mide al juez donde los hechos son conocidos.

Regla práctica: Usa un juez solo para lo que no se puede comparar con un resultado, como motivos, explicaciones y preguntas de vuelta, y conserva results_match() para cada número. Juzga cada par en ambos órdenes, cuenta los veredictos que cambian, registra cada veredicto y lee una muestra de los motivos del juez, no solo sus etiquetas. No dejes que la preferencia de un juez entre dos textos decida una publicación hasta haber medido ese juez en casos con respuestas conocidas.

Esta parte aún no está traducida, así que está en inglés.

Calibrate the judge against reference labels

Último cambio en la edición 2026.11.15

A judge's verdicts on reasons can't be checked against a golden result, so measure the judge first on a task where they can. The shop's golden questions offer one. Ask the same model to grade the agent's answers to answer questions as correct or incorrect, without showing it the golden result, and compare its verdicts with labels that results_match() computes from the golden result. Reference labels computed by results_match() are nobody's opinion: anyone can recompute them from questions.toml and the recordings, and when one looks wrong, the fix is to the golden question, where it's open to correction like the rest of the book. Calibrating a judge against reference labels measures how often the judge agrees with a check you trust, and in which direction it errs.

Agreement needs a chance correction. If most answers are wrong, a judge that calls everything wrong agrees most of the time and has learned nothing; Artstein and Poesio describe the case where raw agreement is high and chance-corrected agreement can still be low (Artstein and Poesio). Cohen's kappa and Scott's pi both subtract the agreement that chance would give, and differ only in how they estimate it: Cohen's kappa estimates chance agreement from each rater's own label shares, and Scott's pi estimates chance agreement from the two raters' shares pooled. Thakur and colleagues dropped kappa for pi in a study of judges, because with kappa "the chance agreement adjusts for the observed average differences between raters, which is in fact part of what we intend to measure" (Thakur et al.). A judge that says "correct" more often than the reference is exactly what you want the statistic to catch, so we report both, and read the lower. In formulas, with p_o the observed agreement:

p_o          = cases where the judge and the reference agree / cases
chance, κ    = Σ over labels (reference's share of the label × judge's share of the label)
chance, π    = Σ over labels (the label's share of both raters' labels pooled)²
kappa, pi    = (p_o − chance) / (1 − chance)

agreement() in lib/judge.py computes all three; scikit-learn's cohen_kappa_score uses the same definition of kappa (scikit-learn). The prompt, JUDGE_ANSWER, gives the judge the shop's glossary, the question, the role, the metric and SQL behind the answer and its result. The cases are every distinct answer with a number that schema-only SQL, the metrics-first agent and the declining agent gave to an answer question, on both splits, from their recordings: 56 in all. The judge prompts were written once, and no verdict changed them. What the judge is shown changed once. Schema-only SQL's query for gq-009 has no ORDER BY, so its rows came back in another order on replay, and the prompt built from them no longer matched its recording. shown() in lib/judge.py now sorts the rows of any query without ORDER BY before the judge sees them. The recording made before that fix was set aside, and every judge call was recorded again from scratch with the fix in place, as the manifest of judge-verdicts says. Every reply matched the set-aside recording's, so no number in this chapter moved.

judge-agreement.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Calibrate the judge: its verdicts on the book's recorded answers against labels from results_match().The overall and per-agent agreement lines, and the one-verdict kappa ranges, are the figures the chapter's points rest on."""from lib.judge import agreement, answer_messages, kappa_one_verdict, parse_verdict, recorded_casesfrom lib.model import RecordedModelfrom lib.semantic import loadfrom lib.warehouse import connectcon, layer = connect(), load()judge = RecordedModel("judge-verdicts")cases, _ = recorded_cases(con, layer)          # every distinct answer with a number, with its reference labeljudged = {c.case_id: parse_verdict(judge.complete(answer_messages(c.question, c.answer))) for c in cases}verdicts = {case_id: v.label for case_id, v in judged.items()}print(f"cases: {len(cases)}")print(f"reference correct: {sum(c.reference == 'correct' for c in cases)}")print(f"judge correct: {list(verdicts.values()).count('correct')}")print(f"judge unparsed: {list(verdicts.values()).count('unparsed')}")# a case ID ends with the agent that gave the answer, so the metric agents' cases are all the restsubsets = {"all": cases, "schema-only": [c for c in cases if c.case_id.endswith("schema-only")],           "metric agents": [c for c in cases if not c.case_id.endswith("schema-only")]}for name, subset in subsets.items():    a = agreement([c.reference for c in subset], [verdicts[c.case_id] for c in subset])    print(f"{name} cases: {a.n}")    print(f"{name} cases the reference labels correct: {sum(c.reference == 'correct' for c in subset)}")    print(f"{name} observed agreement: {a.observed:.2f}")    print(f"{name} Cohen's kappa: {a.kappa:.2f}")    print(f"{name} Scott's pi: {a.pi:.2f}")    # kappa with each single verdict flipped in turn, to show how far one case moves it    low, high = kappa_one_verdict([c.reference for c in subset], [verdicts[c.case_id] for c in subset])    print(f"{name} kappa with any one verdict changed: {low:.2f} to {high:.2f}")for reference, verdict, label in (("incorrect", "correct", "wrong answers the judge called correct"),                                  ("correct", "incorrect", "right answers the judge called incorrect")):    ids = [c.case_id for c in cases if c.reference == reference and verdicts[c.case_id] == verdict]    print(f"{label}: {len(ids)} of {sum(c.reference == reference for c in cases)}")    print(f"{label}, cases: {', '.join(ids)}")# Read the reasons: how many rejections of right answers say a year's filter keeps only its first day?first_day = [c.case_id for c in cases if c.reference == "correct" and judged[c.case_id].label == "incorrect"             and any(w in judged[c.case_id].reason for w in ("January 1", "first day"))]print(f"right answers rejected for reading a year's filter as January 1: {len(first_day)}")
Salidapython judge-agreement.py
cases: 56
reference correct: 26
judge correct: 20
judge unparsed: 0
all cases: 56
all cases the reference labels correct: 26
all observed agreement: 0.75
all Cohen's kappa: 0.49
all Scott's pi: 0.48
all kappa with any one verdict changed: 0.45 to 0.53
schema-only cases: 23
schema-only cases the reference labels correct: 5
schema-only observed agreement: 0.74
schema-only Cohen's kappa: 0.10
schema-only Scott's pi: 0.09
schema-only kappa with any one verdict changed: -0.14 to 0.31
metric agents cases: 33
metric agents cases the reference labels correct: 21
metric agents observed agreement: 0.76
metric agents Cohen's kappa: 0.51
metric agents Scott's pi: 0.50
metric agents kappa with any one verdict changed: 0.44 to 0.58
wrong answers the judge called correct: 4 of 30
wrong answers the judge called correct, cases: gq-002 schema-only, gq-004 schema-only, gq-018 metrics-first, gq-035 metrics-first
right answers the judge called incorrect: 10 of 26
right answers the judge called incorrect, cases: gq-014 schema-only, gq-016 schema-only, gq-027 schema-only, gq-031 schema-only, gq-003 metrics-first, gq-006 metrics-first, gq-008 metrics-first, gq-015 metrics-first, gq-027 metrics-first, gq-029 metrics-first
right answers rejected for reading a year's filter as January 1: 6

The overall kappa, 0.49, looks moderate, but it hides a split by agent. On schema-only SQL's answers, most of them wrong, observed agreement is 0.74 and kappa only 0.10: the judge agreed mostly by calling wrong answers wrong, and rarely picked out the few right ones. Changing one of its verdicts on those answers moves kappa anywhere from -0.14 to 0.31.

The metric agents' kappa is higher, at 0.51, and changing one verdict moves it within 0.44 to 0.58. Read the first decimal of these kappas, not the second. Kappa and pi barely differ here, 0.49 against 0.48 overall, because the judge and the reference use each label about as often; when a judge leans hard one way, they part.

The direction of the errors matters more than the totals. The judge called 4 of 30 wrong answers correct, among them gq-018, chapter 6's near-miss refund metric. It called 10 of 26 right answers incorrect, and 6 of those rejections say that the SQL keeps only January 1 of the year, a misreading of the semantic layer's DATE_TRUNC('YEAR', …) = '2025-01-01'. The others reject schema-only answers that filter on placed_at rather than the local order day: the judge grades the method, and on those questions the number happened to come out the same. So the shop's judge leans strict, not lenient, as Thakur and colleagues report of the judges they studied (Thakur et al.), and it can't read the compiled SQL it's shown.

The judge is also the model that wrote every answer here. Self-preference, a judge that "scores its own outputs higher than others' while human annotators consider them of equal quality" (Panickssery et al.), is a known bias, and familiarity, text that has low perplexity for the judge, is one explanation of it (Wataoka et al.). With one model writing every answer, this measurement can't separate self-preference from other errors. It measures the net bias against a check that doesn't depend on the model; it doesn't remove the bias.

Working rule: Before you use a judge on text, measure it on cases whose answers a check can label, with labels anyone can recompute. Report observed agreement with Cohen's kappa and Scott's pi, split by the kinds of answer you'll judge, list the errors in each direction, and say how far one case moves kappa when the cases number a few dozen. Thresholds such as 0.8 are conventions, not results (Artstein and Poesio); at a kappa like the one measured here, use the judge to choose what a person reads, never to pass or fail a release on its own.

Repite las ejecuciones para ver la varianza

Último cambio en la edición 2026.11.12

Cada puntuación hasta ahora provino de una sola ejecución por pregunta, y una ejecución es una muestra. Las grabaciones del libro muestrean cada respuesta con la temperatura recomendada por Qwen, 0.7, con una semilla fija que se restablece antes de cada llamada, de modo que una reproducción da siempre la misma respuesta, y una semilla distinta puede dar otra. Una puntuación con una sola semilla es una extracción de entre las puntuaciones que el agente podría obtener. Miller recomienda tratar una evaluación como un experimento y "reducir la varianza volviendo a muestrear las respuestas" varias veces por pregunta (Miller). La alternativa, bajar la temperatura hasta que las ejecuciones coincidan, mide un modelo distinto del que sirves.

La grabación repeat-runs contiene las mismas 12 preguntas de desarrollo ejecutadas con cuatro semillas más, de la 1 a la 4, para el agente de métricas primero del capítulo 6 y el agente que declina del capítulo 8, con las mismas instrucciones, herramientas, ajustes de muestreo y el mismo límite de cuatro llamadas que sus grabaciones originales. Con las ejecuciones originales, hechas con la semilla 2718, cada pregunta tiene cinco ejecuciones por agente. SeededRecording en lib/regressions.py reproduce las llamadas de un agente para una semilla. Las 12 preguntas son todas las de respuesta o declinación de desarrollo que uno de los dos agentes falló en su ejecución original, más las primeras cinco de las demás en orden de ID, así que son más difíciles que el promedio de la división y sus tasas de cambio representan un límite superior. La grabación también ejecuta una vez más el agente que declina con la propia semilla 2718, para medir algo que el libro ha dado por supuesto hasta ahora: que una ejecución con la misma semilla se reproduce byte a byte en este entorno de ejecución.

seed-variance.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Five runs of 12 dev questions per agent, one per seed: how much a score moves, and which questions flip.The flipping, across-seeds and always-or-never lines and the seed check are the printed lines the chapter's points rest on."""from lib.golden import load_goldenfrom lib.model import RecordedModelfrom lib.regressions import ORIGINAL_SEED, SeededRecording, replayfrom lib.semantic import loadfrom lib.warehouse import connectcon, layer = connect(), load()QUESTIONS = ("gq-001", "gq-002", "gq-003", "gq-004", "gq-005", "gq-007", "gq-008", "gq-012", "gq-016", "gq-017",             "gq-018", "gq-020")                         # the 12 questions repeat-runs holdsquestions = [q for q in load_golden() if q.question_id in QUESTIONS]seeds = (ORIGINAL_SEED, 1, 2, 3, 4)                      # 2718 replays the original recordingsfor agent in ("metrics-first", "declining"):    per_question = {q.question_id: 0 for q in questions}    scores = []    for seed in seeds:        runs = replay(con, layer, agent, questions, seed=seed)        scores.append(sum(r.outcome == "correct" for r in runs))        for r in runs:            per_question[r.question.question_id] += r.outcome == "correct"        print(f"{agent} seed {seed}: {scores[-1]} of {len(questions)} correct")    spread = f"{min(scores)} to {max(scores)}" if min(scores) < max(scores) else f"{min(scores)} at every seed"    print(f"{agent} correct across seeds: {spread}")    # a question flips when some seeds get it right and others wrong    flips = [f"{q} ({n} of 5)" for q, n in per_question.items() if 0 < n < 5]    print(f"{agent} questions that flip: {len(flips)}")    print(f"{agent} flipping: {', '.join(flips)}")    print(f"{agent} always correct: {sum(n == 5 for n in per_question.values())}")    print(f"{agent} never correct: {sum(n == 0 for n in per_question.values())}")# Does a run replay byte for byte? The declining agent ran again with seed 2718; compare it with decline-runs.again, original = SeededRecording("declining", ORIGINAL_SEED).calls, RecordedModel("decline-runs").callssame = sum(key in original and call["reply"] == original[key]["reply"] for key, call in again.items())print(f"seed {ORIGINAL_SEED} again: {same} of {len(again)} calls identical to decline-runs")
Salidapython seed-variance.py
metrics-first seed 2718: 6 of 12 correct
metrics-first seed 1: 6 of 12 correct
metrics-first seed 2: 6 of 12 correct
metrics-first seed 3: 6 of 12 correct
metrics-first seed 4: 5 of 12 correct
metrics-first correct across seeds: 5 to 6
metrics-first questions that flip: 1
metrics-first flipping: gq-008 (4 of 5)
metrics-first always correct: 5
metrics-first never correct: 6
declining seed 2718: 6 of 12 correct
declining seed 1: 6 of 12 correct
declining seed 2: 6 of 12 correct
declining seed 3: 6 of 12 correct
declining seed 4: 6 of 12 correct
declining correct across seeds: 6 at every seed
declining questions that flip: 0
declining flipping:
declining always correct: 6
declining never correct: 6
seed 2718 again: 24 of 24 calls identical to decline-runs

La comprobación de reproducción va primero, porque todo lo demás depende de ella: seed 2718 again: 24 of 24 calls identical to decline-runs. En este entorno, llama.cpp en la CPU con una solicitud a la vez y la semilla restablecida antes de cada llamada, la segunda ejecución con la semilla 2718 coincidió con la primera en todas las llamadas. Es un agente con 12 preguntas en una sola máquina, no una garantía para todos los entornos, pero muestra que las diferencias entre semillas aquí provienen del muestreo y no del entorno de ejecución. Esto coincide con la causa que un laboratorio encontró para la variación con temperatura 0 en modelos servidos, resultados que dependen de cómo se agrupan las solicitudes en lotes (He et al.), algo que una única solicitud local evita; una API servida no ofrece tal garantía.

Por pregunta, las ejecuciones son más estables de lo que cabría temer con una temperatura de 0.7: solo 1 cambia de resultado, gq-008 (4 of 5), y solo en el agente de métricas primero. En las cinco semillas, el total del agente de métricas primero osciló entre 5 to 6, y el del agente que declina fue 6 at every seed.

El resultado del agente que declina no cambió nunca con la semilla: 6 preguntas fueron siempre correctas y 6 nunca. El capítulo 8 se preguntaba si gq-008, los ingresos totales de 2025, era cuestión de azar, y las repeticiones lo responden. Con el prompt de declinación fue incorrecta en todas las ejecuciones, así que su fallo no es azar: el nuevo prompt desplazó al modelo de los ingresos netos en esa pregunta hacia los ingresos brutos que el capítulo 8 vio en su única ejecución.

Creemos que la estabilidad procede del diseño de la tienda. La mayoría de las decisiones del agente consisten en elegir entre unos pocos nombres de métricas, y la capa semántica convierte cada elección en el mismo SQL siempre, así que pequeñas diferencias de redacción no llegan al resultado. Un modelo que escribe SQL tiene muchas más formas de diferir. Estudios de modelos alojados encontraron oscilaciones mayores, "variaciones de precisión de hasta el 15 % entre ejecuciones que ocurren de forma natural" con ajustes pensados para ser deterministas (Atil et al.), en otras tareas y API. Cinco ejecuciones de 12 preguntas también son una muestra pequeña de la tienda.

Regla práctica: Ejecuta cada pregunta de oro varias veces con los ajustes de muestreo que sirves, con las semillas fijadas en el manifiesto de la grabación, y confirma una vez que una semilla se reproduce exactamente. Informa de los cambios por pregunta, no solo de la dispersión del total, porque un total puede mantenerse mientras las preguntas intercambian posiciones. Nunca bajes la temperatura para que las ejecuciones coincidan, salvo que ese sea el ajuste que vas a servir.

Controlar un cambio en CI

Último cambio en la edición 2026.11.12

Un trabajo de CI que puntúa cada cambio sobre las preguntas doradas convierte en una decisión las mediciones que hemos visto hasta ahora: fusionar o no. El cuadro de puntuación mostró por qué no puede basarse en totales: el prompt que rechaza responder dejó sin cambios la precisión en desarrollo. Miller recomienda "realizar inferencia estadística sobre las diferencias pareadas a nivel de pregunta" (Miller): puntúa ambas configuraciones sobre las mismas preguntas y contrasta la media de las diferencias por pregunta. Emparejar elimina la variación entre preguntas, que es mucho mayor que la de un cambio.

Comparison en lib/regressions.py toma, para cada pregunta, la proporción de ejecuciones correctas con la base y con el candidato, y su diferencia. Informa de la media de las diferencias pareadas con un intervalo t, es decir, el error estándar multiplicado por la t de Student con un grado de libertad menos que el número de preguntas, cuenta las preguntas corregidas y las estropeadas, y aplica una prueba del signo exacta a las preguntas que cambiaron. Los errores de Miller suponen muchas preguntas; con 12, en su mayoría sin cambios, el intervalo t es una guía aproximada, y solo la prueba del signo no asume nada sobre la distribución. gate() aplica dos reglas elegidas por nosotros: falla ante una rotura estable, una pregunta que la base acertó en al menos cuatro de cinco ejecuciones y el candidato en una como máximo, y cuando todo el intervalo de la diferencia media queda por debajo de cero. La primera detecta una regresión que un promedio ocultaría; la segunda, muchas pequeñas. Controlamos el prompt del capítulo 8 frente al del capítulo 6, con una ejecución por pregunta y después con cinco, sobre las 12 preguntas de repeat-runs, que sobrerrepresentan los fallos, de modo que las cifras del control las describen a ellas y no la división de desarrollo.

regression-gate.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Gate a prompt change on paired, per-question differences over five recorded runs of each question.The one-run sign test, the five-run lines and the gate's reasons are the printed lines the chapter's points rest on."""from lib.golden import load_goldenfrom lib.regressions import ORIGINAL_SEED, Comparison, gate, replay, smallest_detectable, t_quantilefrom lib.semantic import loadfrom lib.warehouse import connectcon, layer = connect(), load()QUESTIONS = ("gq-001", "gq-002", "gq-003", "gq-004", "gq-005", "gq-007", "gq-008", "gq-012", "gq-016", "gq-017",             "gq-018", "gq-020")                         # the 12 questions repeat-runs holdsquestions = [q for q in load_golden() if q.question_id in QUESTIONS]seeds = (ORIGINAL_SEED, 1, 2, 3, 4)correct = {agent: {q.question_id: [] for q in questions} for agent in ("metrics-first", "declining")}for agent, runs in correct.items():    for seed in seeds:        for run in replay(con, layer, agent, questions, seed=seed):            runs[run.question.question_id].append(run.outcome == "correct")# One run each, as a CI job that runs every question once would see it.once = Comparison({q: r[:1] for q, r in correct["metrics-first"].items()},                  {q: r[:1] for q, r in correct["declining"].items()})fixed, broken = once.moved()print(f"one run: fixed {len(fixed)} ({', '.join(fixed)}), broken {len(broken)} ({', '.join(broken)})")print(f"one run sign test p: {once.sign_test():.2f}")print(f"one run stable breaks: {', '.join(once.stable_breaks()) or 'none'}")   # with one run, every flip is "stable"five = Comparison(correct["metrics-first"], correct["declining"])for q in five.questions:    print(f"{q}: metrics-first {sum(five.base[q])} of 5, declining {sum(five.candidate[q])} of 5")fixed, broken = five.moved()print(f"five runs: fixed {len(fixed)} ({', '.join(fixed) or 'none'}), broken {len(broken)} ({', '.join(broken) or 'none'})")low, high = five.interval()print(f"five runs mean paired difference: {five.mean_difference:+.2f}")print(f"five runs 95% interval: {low:+.2f} to {high:+.2f}")# one degree of freedom goes to estimating the spread of the differences from the same questionsprint(f"t multiplier, {len(five.questions) - 1} degrees of freedom: {t_quantile(0.975, len(five.questions) - 1):.2f}")print(f"five runs interval half-width: {five.half_width():.2f}")k = smallest_detectable(len(five.questions))print(f"fewest clean flips the mean rule detects: {k} of {len(five.questions)}")print(f"smallest mean change the mean rule detects: {k / len(five.questions):.2f}")print(f"five runs sign test p: {five.sign_test():.2f}")passed, reasons = gate(five)print(f"gate: {'pass' if passed else 'fail'}")print("\n".join(f"gate reason: {r}" for r in reasons))
Salidapython regression-gate.py
one run: fixed 1 (gq-020), broken 1 (gq-008)
one run sign test p: 1.00
one run stable breaks: gq-008
gq-001: metrics-first 5 of 5, declining 5 of 5
gq-002: metrics-first 5 of 5, declining 5 of 5
gq-003: metrics-first 5 of 5, declining 5 of 5
gq-004: metrics-first 5 of 5, declining 5 of 5
gq-005: metrics-first 5 of 5, declining 5 of 5
gq-007: metrics-first 0 of 5, declining 0 of 5
gq-008: metrics-first 4 of 5, declining 0 of 5
gq-012: metrics-first 0 of 5, declining 0 of 5
gq-016: metrics-first 0 of 5, declining 0 of 5
gq-017: metrics-first 0 of 5, declining 0 of 5
gq-018: metrics-first 0 of 5, declining 0 of 5
gq-020: metrics-first 0 of 5, declining 5 of 5
five runs: fixed 1 (gq-020), broken 1 (gq-008)
five runs mean paired difference: +0.02
five runs 95% interval: -0.23 to +0.26
t multiplier, 11 degrees of freedom: 2.20
five runs interval half-width: 0.25
fewest clean flips the mean rule detects: 4 of 12
smallest mean change the mean rule detects: 0.33
five runs sign test p: 1.00
gate: fail
gate reason: stable break: gq-008

Con una ejecución cada una, el cambio corrigió gq-020 y estropeó gq-008, y la prueba del signo da p = 1.00. Con una sola ejecución cada cambio cuenta como estable, así que una sola ejecución no puede distinguir una rotura de un cambio por azar. Cinco ejecuciones separan ambos casos: gq-008 es una rotura estable (gq-008: metrics-first 4 of 5, declining 0 of 5), y la corrección de gq-020 es igual de constante (gq-020: metrics-first 0 of 5, declining 5 of 5).

La diferencia pareada media es +0.02, con un multiplicador t de 2.20 y un intervalo de -0.23 to +0.26, así que en promedio el cambio no produjo nada medible.

El control indica fail, por el motivo stable break: gq-008. El prompt corrigió una pregunta y estropeó otra de forma fiable, y alguien tiene que elegir, o corregirlo, antes de fusionarlo.

El control también tiene un punto ciego. La semiamplitud del intervalo, 0.25 aquí, pertenece a esta comparación, porque depende de cuánto varían las diferencias. Lo que la regla de la media puede detectar se deduce de la propia regla: el menor número de preguntas que deben pasar de fallar siempre a acertar siempre, con el resto sin cambios, para que el intervalo excluya el cero es 4 of 12, es decir, un cambio medio de 0.33. Las roturas funcionan igual en sentido contrario. Cualquier cambio menor pasa la regla de la media, sea mejora o rotura, y solo la regla de rotura estable y una persona que lea las preguntas que se movieron se interponen en su camino. Un prompt modificado falla el control con MissingRecording hasta que se registra, y ese es el momento de registrarlo cinco veces, no una.

Regla práctica: controla un cambio en prompts, contexto o métricas mediante diferencias pareadas por pregunta sobre ejecuciones repetidas, nunca mediante una diferencia de totales. Falla ante cualquier rotura estable y ante una diferencia media cuyo intervalo quede por debajo de cero, anota ambas reglas como tu elección y calcula el cambio más pequeño que pueden detectar en tu conjunto. Cuando el control falle, lee las preguntas que se movieron antes de tocar las reglas.

Detecta un cambio de esquema antes que los usuarios

Último cambio en la edición 2026.11.12

El almacén de datos también cambia por debajo del agente: una columna renombrada en origen, una tabla reconstruida, un tipo reducido. Tres comprobaciones detectan un cambio de esquema sin llamar a ningún modelo: que el SQL de cada pregunta dorada siga ejecutándose, que cada métrica de la capa semántica siga compilándose y ejecutándose, y que cada ejecución registrada del agente siga reproduciéndose. Esta última funciona porque RecordedModel busca las respuestas por el hash de los mensajes exactos: cuando una herramienta devuelve un error que el modelo nunca vio, el siguiente prompt no tiene grabación, y la reproducción falla de forma ruidosa con MissingRecording en lugar de pasar.

Esta ejecución aplica una migración que podría publicar un equipo de origen, el renombrado de analytics.fct_orders.net_revenue_eur a net_revenue_ex_tax_eur, sobre una copia nueva del almacén de la tienda, construida por migrated() en lib/regressions.py. schema_checks() ejecuta las tres comprobaciones. Después, el código aplica la corrección, una línea en el expr de la métrica, en una copia del YAML de la capa semántica, y vuelve a ejecutar las comprobaciones.

renamed-column-caught.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""An upstream rename of one column, caught by three checks that need no model, and the one-line fix.The golden, metric and replay lines before the fix are the printed lines the chapter's points rest on."""import shutilimport tempfilefrom pathlib import Pathfrom lib.golden import load_goldenfrom lib.regressions import migrated, schema_checksfrom lib.semantic import SEMANTIC_DIR, loadRENAME = "ALTER TABLE analytics.fct_orders RENAME COLUMN net_revenue_eur TO net_revenue_ex_tax_eur"con = migrated(RENAME)golden = load_golden()dev = [q for q in golden if q.split == "dev"]failed = schema_checks(con, load(), golden)print(f"golden SQL that fails: {len(failed['golden SQL'])} of {sum(bool(q.golden_sql) for q in golden)}")print(f"golden questions affected: {', '.join(failed['golden SQL'])}")print(f"metrics that fail: {', '.join(failed['metrics'])}")# forbidden questions are decided below the model, so they have no recording to replayreplays = schema_checks(con, load(), dev)["replays"]print(f"recorded dev runs that no longer replay: {len(replays)} of {sum(q.kind != 'forbidden' for q in dev)}")print(f"runs that stop: {', '.join(replays)}")# The fix: the metric's expr names the new column. A copy of the YAML stands in for the commit that changes it.fixed = Path(tempfile.mkdtemp()) / "semantic"shutil.copytree(SEMANTIC_DIR, fixed)metrics = fixed / "metrics.yml"metrics.write_text(metrics.read_text().replace("expr: net_revenue_eur", "expr: net_revenue_ex_tax_eur"))after = schema_checks(con, load(fixed), dev)print(f"after the fix, metrics that fail: {', '.join(after['metrics']) or 'none'}")print(f"after the fix, recorded dev runs that no longer replay: {len(after['replays'])}")shutil.rmtree(fixed.parent)
Salidapython renamed-column-caught.py
golden SQL that fails: 16 of 34
golden questions affected: gq-001, gq-002, gq-003, gq-006, gq-007, gq-008, gq-009, gq-010, gq-011, gq-012, gq-017, gq-025, gq-026, gq-034, gq-038, gq-040
metrics that fail: net_revenue, average_order_value
recorded dev runs that no longer replay: 8 of 21
runs that stop: gq-001, gq-002, gq-003, gq-006, gq-009, gq-010, gq-011, gq-017
after the fix, metrics that fail: none
after the fix, recorded dev runs that no longer replay: 0

Cada comprobación detecta el renombrado. 16 of 34 consultas doradas fallan al ejecutarse. Las métricas net_revenue, average_order_value fallan, porque el YAML de la capa semántica nombra la columna antigua. Y 8 of 21 de las ejecuciones de desarrollo registradas del agente se detienen con MissingRecording: gq-001, gq-002, gq-003, gq-006, gq-009, gq-010, gq-011, gq-017. gq-008 y gq-012 siguen reproduciéndose, porque el agente les respondió con ingresos brutos, que el renombrado no toca. Una reproducción que pasa indica que nada de lo que la ejecución tocó ha cambiado, no que la ejecución sea correcta.

Tras la corrección, ninguna métrica falla y cada ejecución registrada se reproduce: after the fix, recorded dev runs that no longer replay: 0. El agente nunca ve el nombre de una columna, solo métricas, así que sus prompts son los mismos y las grabaciones siguen siendo válidas. El SQL dorado nombra la columna directamente, de modo que las consultas doradas que fallan necesitan el mismo renombrado, que es el coste del SQL dorado escrito contra tablas: es una segunda copia de las definiciones, y tiene que cambiar con ellas. Ninguna comprobación necesita el modelo, así que el CI puede ejecutarlas en cada cambio de los modelos del almacén.

Regla práctica: Ejecuta el SQL dorado, todas las métricas y todas las reproducciones registradas en el CI tanto ante cambios en el almacén como en el agente, y trata MissingRecording como un fallo, nunca como motivo para omitir una pregunta. Cuando una comprobación falle tras un cambio de esquema, corrige la definición en la capa semántica antes de volver a registrar nada.

Qué sale mal en producción

Último cambio en la edición 2026.11.12

Las mediciones de la tienda se apoyan en grabaciones de un modelo pequeño y 48 preguntas. Una vez que un agente real reemplaza a las grabaciones, el juez, la puerta de control y las puntuaciones cambian de formas que las grabaciones nunca mostraron, y cada uno tiene una señal a la que conviene estar atento.

El juez cambia cuando cambia su modelo. Una nueva versión del modelo, un nuevo prompt del juez o una nueva rúbrica son un juez nuevo, y su acuerdo con las etiquetas de referencia debe medirse otra vez. Guarda los casos de calibración y sus etiquetas en el repositorio, junto al prompt del juez, y vuelve a calcular el acuerdo cada vez que cambie cualquiera de los dos. Un kappa que se mueve sin ningún cambio en el agente significa que se movió el juez.

El juez no puede leer lo que juzga. El juez de la tienda interpretó mal el filtro de año que la capa semántica compilaba y rechazó por ello respuestas correctas. Un juez al que se le muestra SQL que no sabe interpretar evalúa la apariencia del SQL, no su significado. Dale lo que sí puede comprobar, como el nombre de la métrica y sus filtros en lugar del SQL compilado, y lee los motivos de sus rechazos antes de leer su puntuación.

Las ejecuciones en vivo varían de formas que las reproducciones no. Una ejecución reproducida es siempre igual, así que la CI sobre grabaciones es determinista. Un modelo en vivo no lo es, incluso con temperatura 0 en una API servida: un estudio observó "variaciones de precisión de hasta un 15 % entre ejecuciones que ocurren de forma natural" (Atil et al.), y un laboratorio atribuyó buena parte de ello a un servidor cuyos resultados dependen de cuántas peticiones comparten un lote (He et al.). Graba ejecuciones repetidas cuando grabes, y trata una puntuación en vivo que difiera de la grabada como variación hasta que las repeticiones demuestren lo contrario.

Bajar la temperatura oculta la variación en lugar de eliminarla. Resulta tentador fijar la temperatura en 0 para que las ejecuciones coincidan. Miller lo desaconseja "a menos que el propósito sea estudiar el modelo a la nueva temperatura" (Miller): entonces el modelo que mides no es el que sirves. Mide con los ajustes con los que sirves el modelo y remuestrea.

Una puerta de control que siempre falla acaba desactivada. Con una docena de preguntas, una regla estricta se activa por ruido, y la gente aprende a saltársela. Define las reglas de la puerta junto con las personas que responden por los números, anota qué puede y qué no puede detectar la puerta, y revisa sus falsas alarmas cada mes.

Volver a grabar se convierte en ajuste. Cada cambio de prompt exige nuevas grabaciones, y volver a grabar el conjunto de desarrollo una y otra vez mientras se ajusta vuelve optimista ese conjunto, como registró el capítulo 6. Indica en cada manifiesto cuántas veces se grabó cada conjunto, y graba el conjunto de prueba una sola vez, al terminar el ajuste.

Regla práctica: Antes de que una puerta de control proteja a un agente en producción, guarda los casos de calibración de su juez junto al prompt del juez y vuelve a medir con cada cambio en cualquiera de los dos, muestra al juez lo que puede comprobar, registra ejecuciones repetidas con los ajustes que usas en producción, acuerda las reglas de la puerta con las personas que responden por los números, y cuenta en cada manifiesto cuántas veces se grabó cada conjunto.

Decisiones que tomó este capítulo

Último cambio en la edición 2026.11.12
  • Una ejecución se informa como una tarjeta de resultados, no como una exactitud: correctas con un intervalo de Wilson, cifras erróneas, fallos, las medidas de declinación del capítulo 8, y llamadas al modelo y tokens del prompt por pregunta, para cada agente sobre las mismas preguntas.
  • La partición de prueba se puntuó una sola vez para las cifras finales. El agente que declina del capítulo 8 se registró en prueba una vez, en decline-runs-test, con su prompt sin cambios, junto a las ejecuciones de prueba de los capítulos 3 y 6.
  • Un juez califica solo lo que results_match() no puede: las razones para declinar, comparadas por pares, con cada par en ambos órdenes. Las cifras siempre se comparan con el resultado de referencia.
  • El juez es el propio modelo del libro con sus propios prompts, y cada veredicto se registra en judge-verdicts. Después de que shown() se corrigiera para ordenar las filas no ordenadas, toda la grabación se rehizo desde cero.
  • Las etiquetas de referencia del juez proceden de results_match(), para que cualquiera pueda recalcularlas, en lugar de proceder de las calificaciones de una persona. Miden si la cifra es correcta, no si el método lo es.
  • El acuerdo se informa como acuerdo observado, kappa de Cohen y pi de Scott, en conjunto y desglosado por agente, con los errores en cada dirección enumerados. Cada kappa descansa en unas pocas decenas de casos, así que el ejemplo muestra cuánto mueve un solo veredicto el valor. El juez, con un kappa como el medido aquí, decide qué lee una persona y nunca aprueba una publicación por sí solo.
  • La varianza procede de cinco ejecuciones por pregunta, la grabación original y cuatro semillas más, con los ajustes de muestreo que usan todas las grabaciones, sobre las 12 preguntas de desarrollo de repeat-runs, elegidas para incluir todos los fallos.
  • La puerta compara las configuraciones por pares, pregunta a pregunta, sobre ejecuciones repetidas: falla ante una ruptura estable o ante una diferencia pareada media cuyo intervalo t queda por debajo de cero. Ambas reglas son elección del libro, y con 12 preguntas la regla de la media no detecta nada menor que 4 of 12 preguntas que cambian por completo (de un resultado a otro).
  • La CI también revisa el almacén de datos: las SQL de referencia se ejecutan, cada métrica compila y se ejecuta, y cada ejecución registrada se reproduce, tratando MissingRecording como un fallo.

Este capítulo, en esta edición

Edición 2026.11.15Ejemplos verificados el 19 de nov de 2026Superan la prueba 6 de 6 ejemplos ejemplos de este capítulo

Traducido del libro en inglés, edición 2026.11.15.

Cita esta sección

Formato

Cada formato cita el libro en inglés, que esta traducción sigue.

Cada formato nombra esta edición. Su enlace abre la edición actual, donde el encabezado de cada sección indica cuándo cambió su texto por última vez. Las fechas de acceso y de recuperación son el día en que lo abres.

En esta página

Capítulo 10 de 11: Juzga respuestas y detecta regresiones

  1. Evalúa una ejecución con más que la precisión
  2. Juzga solo lo que no se puede comparar
  3. Calibrate the judge against reference labels
  4. Repite las ejecuciones para ver la varianza
  5. Controlar un cambio en CI
  6. Detecta un cambio de esquema antes que los usuarios
  7. Qué sale mal en producción
  8. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos