Escribe comprobaciones en código para los fallos que encontraste
Unos 22 minutos de lectura, con 5 ejemplos en 9 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.3. Lee el original
Al final de este capítulo podrás escribir las comprobaciones de formato y de citas que se ejecutan en cada respuesta sin coste, indicar qué fallos del capítulo 2 puede ver cada una y qué no, y mostrar dónde dos puntuaciones de solapamiento habituales colocan una respuesta incorrecta por encima de una correcta.
El capítulo 2 codificó 240 respuestas de desarrollo, 80 de cada una de tres variantes, y clasificó cada una según su defecto principal en siete modos de fallo. Algunos de esos modos dejan una marca en el texto de la respuesta. Una cita a una sección que el prompt nunca proporcionó es una de ellas, y también lo es una respuesta a una pregunta que la documentación no cubre. Un programa puede encontrar ambas leyendo la respuesta frente al elemento al que responde. Otros modos no dejan ninguna marca que un programa pueda leer. Una respuesta puede ser correcta para una versión y errónea para otra mientras su cita es correcta, y nada en su texto indica a cuál versión se refiere.
Un equipo que escribe comprobaciones solo para las marcas que puede ver informa de una ejecución limpia y pasa por alto los fallos que nunca buscó. Este capítulo ordena las comprobaciones según lo que pueden ver, construye las que se ejecutan en código y explica qué deja fuera cada una. El conjunto de pruebas en el que se basan todas las cifras de aquí tiene 80 elementos de desarrollo y 40 elementos reservados. Solo se leen los elementos de desarrollo en este capítulo. Los elementos reservados aparecen como recuentos en un ejemplo, y el capítulo 10 muestra sus tasas de rechazo.
Lo que puede ver una comprobación de código
Una comprobación de código lee dos cosas: el texto de la respuesta y los datos propios del elemento, que contienen su respuesta de referencia y la lista de secciones que la respaldan. Da la misma respuesta en cada ejecución, y no cuesta nada volver a ejecutarla sobre un nuevo lote de respuestas. Esas son sus fortalezas. Su límite es que lee la forma y la pertenencia, nunca el significado. Puede saber si una respuesta tiene una cita, si el ID citado estaba en el prompt y si la respuesta es exactamente la frase de rechazo. No puede saber si la sección citada dice lo que dice la respuesta.
Aquí está la lista de modos del capítulo 2, con lo que una comprobación de código puede ver de cada uno.
- Rechazo excesivo. Una comprobación que cuenta la frase de rechazo ve los rechazos que la usan. Un rechazo expresado con otras palabras pasa como si fuera una respuesta. Así es como q-0080 supera una comprobación por frases, como muestra el capítulo 2.
- Respuestas de la versión equivocada. Una comprobación puede ver si cada cita pertenece a la versión consultada. No puede ver si la afirmación coincide con la referencia de esa versión.
- Respuestas incorrectas. El código no lo puede ver. Saber si una afirmación es correcta requiere leer la afirmación frente a la referencia.
- Rechazos omitidos. Una comprobación puede exigir la frase de rechazo en cada elemento sin respuesta posible, y
answered-declined-expectedse activa ante cualquier respuesta a uno de ellos, sin importar lo que cite. Depende de la etiqueta del elemento, de modo que un elemento que la documentación no cubre pero que el conjunto de prueba considera respondible pasa sin ser detectado. - Respuestas incompletas. En este capítulo, el código no lo puede ver. Si una respuesta cubre toda la pregunta le corresponde al juez, según las reglas de la rúbrica.
- Problemas de citas. Son visibles en dos partes: una cita fuera del prompt y una cita a una sección que el elemento no enumera. La segunda parte necesita un lector, como explica la sección de respaldo.
- Respuestas mal formadas. En parte. Se pueden detectar las respuestas vacías, los rechazos con texto, las respuestas sin citar y las respuestas cuyas partes aparecen en un orden incorrecto. La comprobación de orden de la siguiente sección encuentra el último tipo.
Regla práctica: Escribe una comprobación de código para un fallo solo cuando la respuesta y el elemento ya contengan el dato que la comprobación necesita. Para un fallo cuya evidencia es la propia afirmación, envíalo a un juez con una rúbrica escrita, como hace el capítulo 5, y conserva la comprobación de código para las partes del fallo que sí se pueden leer.
Comprobaciones de formato
La comprobación de formato pregunta si una respuesta tiene la forma que pide el prompt, antes de que alguien lea lo que dice. La función format_problems en lib/contract.py devuelve una lista ordenada de nombres fijos, uno por cada defecto que encuentra. Son cinco. empty es una respuesta sin texto. declined-with-text es una respuesta que contiene la frase de rechazo junto con otro texto. no-citation es una respuesta que no cita nada. unknown-section es una cita a una sección que el prompt no dio. answered-declined-expected es una respuesta a un elemento que debe rechazarse. Una segunda función, order_problems, lee el orden de las líneas de una respuesta y devuelve dos nombres: citation-first, para una respuesta cuya primera línea abre con una cita, y stray-line, para una línea que no termina ninguna oración una vez quitadas sus citas.
La comprobación de formato lee la respuesta, la lista de secciones que dio el prompt y si el elemento es imposible de responder. La comprobación de orden lee solo las líneas de la respuesta. Ninguna de las dos lee lo que dice la respuesta, así que una respuesta correcta y una incorrecta con la misma forma pasan por igual.
Ejecuta la comprobación de formato sobre la respuesta de la línea base a cada elemento, y cuenta cada nombre, manteniendo separados los elementos de desarrollo y los elementos reservados.
1"""Runs format_problems over the baseline replies to every item, and counts each problem by its fixed name.23Dev and held-out items are counted apart, and held-out items appear only as counts. An item can have more than one4problem, so the counts by name can add up to more than the number of items with a problem."""5import lib # first: fixes the thread counts and seeds before anything else loads67from collections import Counter89from lib.answers import Assistant10from lib.contract import PROBLEMS, format_problems11from lib.prompts import P1_SHA256, P1_SYSTEM12from lib.stats import pct13from lib.testset import load_items1415assistant = Assistant("assistant-baseline", P1_SYSTEM, P1_SHA256)16assert len(load_items()) == 120 # the baseline recording holds one reply per item, so every item is counted1718for split in ("dev", "held-out"):19 items = load_items(split=split)20 counts = Counter()21 with_problem = 022 for item in items:23 problems = format_problems(24 assistant.reply(item),25 context_ids=assistant.context_ids(item),26 expect_decline=item.kind == "unanswerable", # an unanswerable item must be declined27 )28 with_problem += bool(problems)29 counts.update(problems)30 print(f"{split} items: {len(items)}")31 print(f"{split} items with a format problem: {pct(with_problem, len(items))}")32 for name in PROBLEMS: # the fixed names, in the order lib.contract lists them33 print(f"{split} problem {name}: {counts[name]}")
python format-problems-baseline.pydev items: 80
dev items with a format problem: 0.0% (0 of 80)
dev problem answered-declined-expected: 0
dev problem declined-with-text: 0
dev problem empty: 0
dev problem no-citation: 0
dev problem unknown-section: 0
held-out items: 40
held-out items with a format problem: 0.0% (0 of 40)
held-out problem answered-declined-expected: 0
held-out problem declined-with-text: 0
held-out problem empty: 0
held-out problem no-citation: 0
held-out problem unknown-section: 0
La línea base no tiene ningún problema de formato en los elementos de desarrollo, 0.0% (0 of 80), ni en los elementos reservados, 0.0% (0 of 40). Un cero cuenta solo si la comprobación podría haberse disparado, y el siguiente ejemplo muestra que estas comprobaciones sí se disparan, en otras grabaciones.
1"""Runs the format check and the order check over the unfiltered and second-model replies to the dev items. The baseline2has no problem of either kind (format-problems-baseline), so these two recordings are where the checks fire.34Each name is also run once on a fixture reply built to break it, and the example stops if a name does not fire. A zero5on a real split then means the check found nothing, not that it could not fire. Held-out items are not read here."""6import lib # first: fixes the thread counts and seeds before anything else loads78from lib.answers import Assistant9from lib.contract import ORDER_PROBLEMS, PROBLEMS, format_problems, order_problems, parse_reply10from lib.prompts import P1_SHA256, P1_SYSTEM11from lib.testset import load_items1213VARIANTS = (("unfiltered", "assistant-unfiltered"), ("second-model", "assistant-second-model"))14FIXTURE_IDS = frozenset({"example-start"}) # the one section a fixture may cite15FIXTURES = ( # name, reply text, whether the item must be declined16 ("empty", "", False),17 ("declined-with-text", "The docs don't say. [sec:example-start]", False),18 ("no-citation", "Run svc start to start the service.", False),19 ("unknown-section", "Run svc start to start the service. [sec:made-up]", False),20 ("answered-declined-expected", "Run svc start to start the service. [sec:example-start]", True),21 ("citation-first", "[sec:example-start] Start the service.\nRun svc start.", False),22 ("stray-line", "Run `svc start` [sec:example-start]\nService", False),23)2425items = load_items(split="dev")26for label, recording in VARIANTS:27 assistant = Assistant(recording, P1_SYSTEM, P1_SHA256)28 found = {name: [] for name in (*PROBLEMS, *ORDER_PROBLEMS)}29 for item in items:30 reply = assistant.reply(item)31 for name in format_problems(reply, context_ids=assistant.context_ids(item), expect_decline=item.kind == "unanswerable"):32 found[name].append(item.id)33 for name in order_problems(reply.text):34 found[name].append(item.id)35 for name, ids in found.items():36 shown = f"{len(ids)} of {len(items)}" + (f" ({', '.join(ids)})" if ids else "")37 print(f"{label} {name}: {shown}")3839for name, raw, must_decline in FIXTURES:40 reply = parse_reply(raw)41 fired = name in format_problems(reply, context_ids=FIXTURE_IDS, expect_decline=must_decline) or name in order_problems(reply.text)42 assert fired, f"the fixture for {name} does not fire the check"43 print(f"fixture {name}: fired")
python format-problems-variants.pyunfiltered answered-declined-expected: 2 of 80 (q-0018, q-0039)
unfiltered declined-with-text: 1 of 80 (q-0080)
unfiltered empty: 0 of 80
unfiltered no-citation: 0 of 80
unfiltered unknown-section: 1 of 80 (q-0019)
unfiltered citation-first: 0 of 80
unfiltered stray-line: 0 of 80
second-model answered-declined-expected: 2 of 80 (q-0034, q-0036)
second-model declined-with-text: 1 of 80 (q-0001)
second-model empty: 0 of 80
second-model no-citation: 9 of 80 (q-0001, q-0007, q-0047, q-0058, q-0060, q-0063, q-0065, q-0071, q-0080)
second-model unknown-section: 0 of 80
second-model citation-first: 1 of 80 (q-0030)
second-model stray-line: 2 of 80 (q-0007, q-0030)
fixture empty: fired
fixture declined-with-text: fired
fixture no-citation: fired
fixture unknown-section: fired
fixture answered-declined-expected: fired
fixture citation-first: fired
fixture stray-line: fired
La variante sin filtrar responde a q-0018 y q-0039, que son imposibles de responder, así que answered-declined-expected los cuenta: 2 of 80 (q-0018, q-0039). Las respuestas del segundo modelo tienen más problemas. Su recuento de no-citation es 9 of 80 (q-0001, q-0007, q-0047, q-0058, q-0060, q-0063, q-0065, q-0071, q-0080).
La comprobación de orden marca la respuesta del segundo modelo a q-0030. Esa respuesta abre con su cita, así que es citation-first: 1 of 80 (q-0030). Su primera línea también contiene un fragmento de un encabezado, que es un stray-line. Una respuesta cuya última línea no termina ninguna oración recibe también ese nombre, y uno de los dos casos es q-0007, cuyo texto se corta en medio de una oración repetida: 2 of 80 (q-0007, q-0030).
La comprobación de formato deja pasar esa respuesta de q-0030. format_problems cuenta las citas y no lee dónde aparecen, así que una respuesta puede citar solo secciones que dio el prompt y aun así tener sus partes desordenadas. Esa brecha es para lo que sirve la comprobación de orden. El ejemplo también ejecuta una respuesta de muestra por cada nombre, y se detiene si un nombre no se dispara, así que cada cero anterior significa que la comprobación miró y no encontró nada.
Una comprobación que nunca se dispara sobre la línea base sigue mereciendo su lugar, porque no cuesta nada y detecta el siguiente prompt que rompa una forma.
Regla práctica: Ejecuta la comprobación de formato y la comprobación de orden sobre cada respuesta antes de que un juez la lea, e informa el recuento de cada nombre en cada partición. Un cero cuenta como resultado solo cuando la comprobación podría haberse disparado, así que conserva la ejecución de muestras junto con el informe. Cuando un recuento suba, lee las respuestas detrás de él antes de cambiar la comprobación, porque un nombre indica qué forma se rompió y no por qué se rompió.
Comprobaciones de citas
Capítulo 1 escribió la primera comprobación de citas: cada ID que una respuesta cita debe ser uno que el prompt haya dado. Esa comprobación indica si una cita está dentro del prompt. No indica si la cita es la correcta para el elemento. Esta sección hace dos preguntas más a cada ID citado. ¿Existe en la documentación de la versión sobre la que pregunta el elemento? Y ¿es una sección que el elemento lista como respaldo de la respuesta?
citation_outcome asigna a cada ID citado uno de cuatro resultados. supported significa que el ID está en la lista del elemento para la versión consultada. unlisted significa una sección de la versión consultada que el elemento no lista. wrong-version significa una sección que existe solo en otra versión. missing significa que ninguna versión tiene una sección con el ID citado. Dos reglas se aplican a los cuatro. Una respuesta lleva IDs y no versiones, así que un ID que aparece en dos versiones no puede ser wrong-version, y se juzga según la versión consultada. Y unlisted nunca se califica como incorrecto. La lista del elemento se escribió a mano, y una sección que no aparece en ella aún puede respaldar la respuesta.
La comprobación se ejecuta sobre los elementos de desarrollo de tres grabaciones: la línea base; la variante sin filtrar, que usa el mismo prompt pero recupera de todas las versiones y muestra las versiones al modelo; y prompt-b, el prompt P2 del capítulo 1, que cita primero (dos prompts), que pide al modelo citar primero la frase en la que se basa su respuesta y citar en cada línea. Sus 117 citas provienen de los mismos elementos, así que sus proporciones son por cita. Las citas de cada grabación se clasifican del mismo modo.
1"""Sorts each section ID that a reply cites into one outcome, for three recordings, over the dev items.23The outcomes are supported (listed by the item for its asked version), unlisted (a section of the asked version that the4item does not list), wrong-version (a section of another version only) and missing (a section of no version). The5check reads IDs, not sentences: whether a listed section supports the sentence is the judge's job, in grounded-answers.67An ID that exists in two versions cannot be told apart by the reply, because the citation carries no version. It is8judged against the asked version, so an ID shared by both versions is never wrong-version."""9import lib # first: fixes the thread counts and seeds before anything else loads1011from collections import Counter1213from lib.contract import CITATION_OUTCOMES, citation_outcomes, parse_reply, section_ids_by_version14from lib.prompts import P1_SHA256, P2_SHA25615from lib.replay import ReplayModel16from lib.stats import pct17from lib.testset import load_items1819RECORDINGS = ( # label, recording, the sha256 of the prompt it was made from20 ("baseline", "assistant-baseline", P1_SHA256),21 ("unfiltered", "assistant-unfiltered", P1_SHA256), # same prompt; retrieval from every version, versions shown22 ("prompt-b", "assistant-prompt-b", P2_SHA256),23)2425ids = section_ids_by_version()26items = load_items(split="dev") # dev only: held-out items are not read here (plan section 3.4)2728for label, recording, prompt_sha256 in RECORDINGS:29 model = ReplayModel(recording, prompt_sha256)30 counts = Counter()31 for item in items:32 reply = parse_reply(model.reply(item.id, 0))33 # The item's list for its asked version. An unanswerable item may also list another version: not counted here.34 listed = frozenset(s.section_id for s in item.supporting_sections if s.version == item.version)35 counts.update(citation_outcomes(reply, item.version, listed, ids))36 total = sum(counts.values())37 print(f"{label} citations on dev items: {total}")38 for outcome in CITATION_OUTCOMES:39 print(f"{label} {outcome}: {pct(counts[outcome], total)}")
python check-citation-support.pybaseline citations on dev items: 60
baseline supported: 93.3% (56 of 60)
baseline unlisted: 6.7% (4 of 60)
baseline wrong-version: 0.0% (0 of 60)
baseline missing: 0.0% (0 of 60)
unfiltered citations on dev items: 59
unfiltered supported: 84.7% (50 of 59)
unfiltered unlisted: 15.3% (9 of 59)
unfiltered wrong-version: 0.0% (0 of 59)
unfiltered missing: 0.0% (0 of 59)
prompt-b citations on dev items: 117
prompt-b supported: 93.2% (109 of 117)
prompt-b unlisted: 6.8% (8 of 117)
prompt-b wrong-version: 0.0% (0 of 117)
prompt-b missing: 0.0% (0 of 117)
La mayoría de las citas de cada grabación apuntan a una sección que figura en la lista del elemento. La proporción listada es 93.3% (56 of 60) para la línea base, 84.7% (50 of 59) para la variante sin filtrar, y 93.2% (109 of 117) para prompt-b.
Existencia y versión
La comprobación de versión no encuentra nada en estas grabaciones. Una cita de versión incorrecta, tal como se definió antes, es aquella que apunta únicamente a una sección de otra versión. En la línea base, la proporción de versión incorrecta es 0.0% (0 of 60). En la variante sin filtrar, es 0.0% (0 of 59). En prompt-b, es 0.0% (0 of 117). El resultado «missing» (cita inexistente) tampoco aparece en ninguna de las tres grabaciones. Eso es una afirmación solo sobre las citas. No demuestra que el asistente responda cada pregunta para la versión consultada.
La variante sin filtrar es la que conviene vigilar, porque su contexto contiene las secciones de todas las versiones. Si alguna grabación citara la versión incorrecta, sería esta. No cita ninguna. Los errores que importan están en las afirmaciones. Capítulo 2 codifica la respuesta de la línea base a q-0023 como una respuesta de versión incorrecta. Da el resultado de 2.0 para una entrada ignore en 1.0, y cita una sección de 1.0. La cita está en la versión consultada, así que esta comprobación la da por buena. Para que el error se vea, la afirmación tiene que leerse frente a la referencia de 1.0.
Regla práctica: Informa los resultados de versión incorrecta y de cita ausente como tasas propias, y nunca dejes que un cero en ellos sustituya a una respuesta correcta. Para cada elemento que depende de la versión, lee la afirmación frente a la referencia de la versión consultada. Respuestas fundamentadas incorpora esa lectura en una tasa propia.
Soporte
El resultado no listado es donde esta comprobación hace su trabajo, y requiere la lectura de una persona. Una cita a una sección no listada de la versión consultada no es un error según las reglas de esta comprobación, porque la lista del elemento se escribió a mano y puede estar incompleta. La respuesta del baseline a q-0057 es un ejemplo: cita remote-retries, que el elemento no lista. El código clasifica esa cita como no listada, y el capítulo 2 codifica la respuesta como un problema de cita, así que hace falta un lector para decidir que la cita es un problema. El capítulo 2 también enuncia el criterio como una regla según la cual toda cita debe ser una que el elemento lista. Este capítulo flexibiliza esa regla, porque la lista está escrita a mano y es el lector, no la lista, quien decide.
Las proporciones no listadas son 6.7% (4 of 60) para el baseline, 15.3% (9 of 59) para la variante sin filtrar y 6.8% (8 of 117) para prompt-b. La variante sin filtrar tiene la proporción no listada más alta. Cada una de sus citas no listadas es una pregunta para un lector: ¿esta sección respalda la oración para la que se cita?
Un resultado supported significa solo que el ID está en la lista. Una sección listada puede aun así no respaldar la oración para la que se cita, porque esta comprobación lee IDs y no oraciones. Si una sección listada respalda su oración es un juicio, y esta comprobación no lo emite. Respuestas fundamentadas reutiliza los cuatro resultados definidos aquí como su precisión de citas, que también lee solo IDs, y añade un juez de fidelidad a nivel de respuesta, escrito como describe un juez con una rúbrica.
Regla práctica: Cuenta una cita como respaldada solo cuando su ID esté en la lista del elemento, y nunca como correcta. Lee cada cita no listada contra su sección antes de considerarla un problema. Informa lo no listado por separado de la versión incorrecta y de lo faltante, porque una lista más completa convertiría algunas de las citas no listadas en respaldadas.
Coincidencia exacta y coincidencia aproximada
La mayoría de las comprobaciones de cadenas de este libro usan una de dos comparaciones. Una coincidencia exacta pregunta si dos cadenas son iguales, y sirve para cualquier texto fijo. La comprobación de rechazo del capítulo 1 es una de ellas. Una respuesta cuenta como rechazo solo cuando todo su texto es igual a la frase de rechazo, que es lo que contiene el campo declined de una respuesta analizada. Un ID de sección, un nombre de bandera y un nombre de archivo quedan fijados de la misma manera. Una coincidencia exacta da un sí o un no, y nunca devuelve un casi acierto.
Una coincidencia aproximada puntúa qué tan parecidas son dos cadenas. La biblioteca estándar de Python, difflib, hace esto. Su clase SequenceMatcher entrega la puntuación como ratio(), que la documentación define como el doble del número de elementos coincidentes dividido entre el número total de elementos de ambas secuencias. Tres cosas de esa puntuación importan para una comprobación.
- Depende del orden de los argumentos. La documentación advierte que el resultado de una llamada a
ratio()puede depender del orden de los argumentos, así que una comprobación debe pasar la referencia en la misma posición cada vez. En el par largo del ejemplo, la puntuación es 0.480 con la referencia primero y 0.861 con la respuesta primero. - Cuenta coincidencias, no significado. Una errata de una letra en una bandera obtiene 0.933 frente a la bandera correcta, aunque la bandera sea incorrecta. Una respuesta puede conservar una puntuación alta mientras su único dato erróneo cambia.
- Puede omitir partes de cadenas largas. Para secuencias de 200 elementos o más, la documentación trata un elemento como basura cuando sus repeticiones suman más del uno por ciento de la secuencia, salvo que
autojunkse desactive. En el caso de las cadenas, los elementos son caracteres, así que una respuesta de 200 caracteres o más puede verse afectada. La heurística se construye a partir del segundo argumento, que es la respuesta cuando la referencia va primero. En el par largo, la puntuación por defecto es 0.480, y conautojunk=Falsees 0.861.
1"""Compares three pairs of sablefile answers with an exact match and with difflib's ratio(), a score from 0 to 1.23Each pair is a reference and a reply written for this example, not a recorded reply: two file names, a flag with one4wrong letter, and a long answer that leaves out its folder sentence. ratio() is printed with the reference first and with5the reply first, because the documentation says the argument order can change the score. With the reference first, the6long reply is the second sequence and is 200 characters or more, so the autojunk heuristic applies to it; the long answer7is also scored with autojunk turned off."""8import lib # first: fixes the thread counts and seeds before anything else loads910from difflib import SequenceMatcher1112FOLDERS = " Folders are created only with --apply, because a plain sync writes nothing."13PLAN = " The plan lines start with create, update or unchanged, and the lock file is written only by the apply run."14LONG_REFERENCE = (15 "With no flag, sync prints the plan and writes nothing. --apply writes the files and updates the lock file, "16 ".sablefile/lock.json." + FOLDERS + PLAN17)18LONG_REPLY = LONG_REFERENCE.replace(FOLDERS, "") # the answer leaves out the folder sentence19PAIRS = (20 ("file names", ".sablefile/lock.json", "sablefile.lock"),21 ("flag", "--apply", "--appply"),22 ("long answer", LONG_REFERENCE, LONG_REPLY),23)2425for name, reference, reply in PAIRS:26 print(f"{name}, exact match: {reply == reference}")27 print(f"{name}, ratio: {SequenceMatcher(None, reference, reply).ratio():.3f}")28 print(f"{name}, ratio with the reply first: {SequenceMatcher(None, reply, reference).ratio():.3f}")29# autojunk=False: the default treats the reply's common characters as junk once it is 200 characters or longer.30print(f"long answer, ratio with autojunk off: {SequenceMatcher(None, LONG_REFERENCE, LONG_REPLY, autojunk=False).ratio():.3f}")
python fuzzy-match.pyfile names, exact match: False
file names, ratio: 0.765
file names, ratio with the reply first: 0.765
flag, exact match: False
flag, ratio: 0.933
flag, ratio with the reply first: 0.933
long answer, exact match: False
long answer, ratio: 0.480
long answer, ratio with the reply first: 0.861
long answer, ratio with autojunk off: 0.861
Los tres pares están escritos para este ejemplo, así que las puntuaciones muestran qué hace cada propiedad, no con qué frecuencia una respuesta la incumple.
Regla práctica: Usa una coincidencia exacta siempre que el texto esperado sea fijo. Usa una proporción aproximada solo para ordenar respuestas para su lectura, nunca como aprobado o suspenso, hasta que una ejecución registrada muestre dónde debe situarse un umbral para las respuestas de este libro. Cuando llames a ratio(), pasa la referencia primero en todos los casos, y di en la docstring de la comprobación qué cadena es cuál.
Dónde BLEU y ROUGE inducen a error
Dos puntuaciones de solapamiento de palabras tomadas de otras tareas pueden usarse para evaluar el texto generado. BLEU surgió de la traducción automática y ROUGE del resumen automático. Ambas son baratas de calcular.
Papineni y sus colegas propusieron BLEU en 2002 como una forma rápida y poco costosa de puntuar la traducción automática. Usa una precisión de n-gramas modificada (Papineni y colegas, 2002). La revisión de Reiter sobre qué tan bien BLEU sigue el juicio humano encontró que la evidencia lo respalda para la evaluación diagnóstica de sistemas de traducción automática. No lo respalda fuera de la traducción automática, para evaluar textos individuales ni para contrastar hipótesis (Reiter, 2018). Una puntuación que se sostiene para sistemas no se sostiene, por eso mismo, para una sola respuesta.
Lin definió ROUGE-N como una exhaustividad de n-gramas: la proporción de las secuencias de palabras de la referencia que el candidato cubre (Lin, 2004). Ese artículo trata sobre resúmenes. Un estudio aparte probó métricas tomadas de la traducción automática en respuestas de diálogo, no en respuestas de documentación. Encontró que se correlacionan muy débilmente con el juicio humano en un conjunto de datos de chat general, y en absoluto en uno técnico, los datos de ayuda de Ubuntu (Liu y colegas, 2016). Es un estudio de una sola tarea. Las respuestas de Sablefile son técnicas, así que el resultado es una advertencia, no una medición de este asistente.
Tres preguntas sobre sablefile 2.0 muestran el problema con más claridad. Cada una tiene una respuesta de referencia escrita, una respuesta incorrecta que copia la mayoría de las palabras de la referencia, y una respuesta correcta que dice lo mismo con pocas de esas palabras. Las respuestas están escritas para este ejemplo, no tomadas de una grabación, así que muestran que el fallo puede ocurrir, no con qué frecuencia. La puntuación de estilo BLEU toma la precisión de 1 a 4 gramos recortada, su media geométrica y una penalización por brevedad. ROUGE-1 F1 cuenta palabras sueltas. Ambas fórmulas están escritas en el código del ejemplo. En este libro no se fija ningún paquete de BLEU o ROUGE, y el ejemplo informa de F1, que combina exhaustividad con precisión, no de la exhaustividad que definió Lin.
1"""Scores a wrong answer that shares most of its words with the reference above a right answer that shares few.23Each pair in data/overlap-pairs.json is a question on sablefile 2.0 with its reference, a wrong answer and a right answer.4All three pairs are hand-written for this example, not recorded replies. The scores are the textbook formulas, written5here in plain Python: ROUGE-1 F1 (unigram overlap, F1 of precision and recall) and a BLEU-style score (clipped 1- to64-gram precision, geometric mean, brevity penalty), with no smoothing. No BLEU or ROUGE package is pinned, and none is7used. The reference facts are in examples/data/docs/2.0 (sync.md, quickstart.md, lockfile.md)."""8import lib # first: fixes the thread counts and seeds before anything else loads910import json11import math12import re13from collections import Counter14from pathlib import Path1516PAIRS = json.loads((Path(__file__).resolve().parent / "data" / "overlap-pairs.json").read_text(encoding="utf-8"))171819def words(text: str) -> list[str]:20 """Lowercase runs of letters and digits: `--apply` is the word apply, and `lock.json` is two words."""21 return re.findall(r"[a-z0-9]+", text.lower())222324def rouge_1_f1(candidate: str, reference: str) -> float:25 """ROUGE-1 F1: shared words, counted with repeats up to the smaller count, over both lengths."""26 cand, ref = words(candidate), words(reference)27 overlap = sum((Counter(cand) & Counter(ref)).values())28 if overlap == 0:29 return 0.030 precision, recall = overlap / len(cand), overlap / len(ref)31 return 2 * precision * recall / (precision + recall)323334def bleu_sentence(candidate: str, reference: str, max_n: int = 4) -> float:35 """Sentence BLEU-style score: clipped n-gram precision for n = 1 to 4, geometric mean, brevity penalty.3637 Without smoothing, a single n-gram order with no match gives 0, as the textbook formula does.38 """39 cand, ref = words(candidate), words(reference)40 precisions = []41 for n in range(1, max_n + 1):42 cand_grams = Counter(tuple(cand[i : i + n]) for i in range(len(cand) - n + 1))43 ref_grams = Counter(tuple(ref[i : i + n]) for i in range(len(ref) - n + 1))44 clipped = sum(min(count, ref_grams[gram]) for gram, count in cand_grams.items()) # each n-gram up to the reference's count45 if clipped == 0:46 return 0.047 precisions.append(clipped / sum(cand_grams.values()))48 # Short answers are penalised by the brevity penalty: a candidate shorter than the reference scores less.49 brevity = (1.0 if len(cand) > len(ref) else math.exp(1 - len(ref) / len(cand)))50 return brevity * math.exp(sum(math.log(p) for p in precisions) / max_n)515253for number, pair in enumerate(PAIRS, start=1):54 print(f"pair {number} (hand-written), question: {pair['question']}")55 for label in ("wrong", "right"):56 print(f"pair {number}, {label} answer, ROUGE-1 F1: {rouge_1_f1(pair[label], pair['reference']):.3f}")57 print(f"pair {number}, {label} answer, BLEU: {bleu_sentence(pair[label], pair['reference']):.3f}")58# The claim the prose makes: the wrong answer overlaps the reference more than the right one, in every pair.59higher = sum(rouge_1_f1(p["wrong"], p["reference"]) > rouge_1_f1(p["right"], p["reference"]) for p in PAIRS)60print(f"pairs where the wrong answer has the higher ROUGE-1 F1: {higher} of {len(PAIRS)}")
python overlap-misleads.pypair 1 (hand-written), question: In version 2.0, what does a plain sablefile sync do to your files?
pair 1, wrong answer, ROUGE-1 F1: 0.815
pair 1, wrong answer, BLEU: 0.540
pair 1, right answer, ROUGE-1 F1: 0.167
pair 1, right answer, BLEU: 0.000
pair 2 (hand-written), question: In version 2.0, when does sync create a target's missing folder?
pair 2, wrong answer, ROUGE-1 F1: 0.720
pair 2, wrong answer, BLEU: 0.484
pair 2, right answer, ROUGE-1 F1: 0.211
pair 2, right answer, BLEU: 0.000
pair 3 (hand-written), question: Where does version 2.0 keep its lock file?
pair 3, wrong answer, ROUGE-1 F1: 0.952
pair 3, wrong answer, BLEU: 0.905
pair 3, right answer, ROUGE-1 F1: 0.286
pair 3, right answer, BLEU: 0.000
pairs where the wrong answer has the higher ROUGE-1 F1: 3 of 3
La respuesta incorrecta supera a la correcta en ROUGE-1 F1 en 3 of 3 pares. En el primer par, la respuesta incorrecta obtiene 0.815, y la respuesta correcta obtiene 0.167.
Lee las líneas de BLEU con cuidado. La fórmula que escribe el código no tiene suavizado, así que la puntuación es cero siempre que alguno de los cuatro órdenes de n-gramas no tenga ninguna coincidencia. Cada respuesta correcta comparte palabras sueltas con su referencia, pero ninguna secuencia de dos palabras, así que su precisión de dos palabras es cero, y también lo es su BLEU. Ese es el comportamiento de la fórmula, y no dice nada sobre si la respuesta es buena.
ROUGE-1 F1 cuenta palabras sueltas e ignora su orden. Una respuesta incorrecta que repite la mayoría de las palabras de la referencia recupera la mayor parte de la puntuación, independientemente de las palabras que falle. El tercer par lo muestra. Su respuesta incorrecta obtiene 0.952. Esa respuesta nombra el archivo de la versión 1.1, mientras que la referencia nombra .sablefile/lock.json. Cada palabra de la respuesta incorrecta aparece en la referencia, y la única palabra de la referencia que le falta es json. El nombre del archivo es la parte de la respuesta que importa, y la puntuación no puede distinguir esa parte del resto.
Regla práctica: No uses BLEU ni ROUGE como criterio de aprobado para una respuesta con una única forma correcta. Si los informas, nombra la fórmula y di si está suavizada. Lee cada respuesta cuyo solapamiento sea alto y cuya afirmación esté en duda, ya que los pares anteriores muestran que el solapamiento premia una respuesta incorrecta que copia la referencia. Comprueba la afirmación con un juez, como describe el capítulo 5.
Rechazos en el código
Capítulo 1 ya incluye una comprobación en código para los rechazos. Cuenta dos errores frente a la frase exacta de rechazo: un ítem respondible al que el asistente rechazó, y un ítem no respondible al que respondió. La comprobación de formato de este capítulo añade una forma más, la frase de rechazo acompañada de otro texto en la misma respuesta, y aplica la comprobación de ítems no respondibles a todos los ítems de ambas particiones, mientras que el capítulo 1 la aplicó a veinte. Los recuentos de formato de la línea base son cero en ambas particiones, como muestra comprobaciones de formato. En los veinte ítems del capítulo 1, la comprobación de rechazos no encontró ningún error. Este capítulo no vuelve a ejecutarla sobre los ítems de desarrollo. Capítulo 10 ofrece la tasa de falsos rechazos de la línea base sobre ellos.
Ambas comprobaciones leen el texto de la respuesta, y ambas tienen un límite que se deriva de ello. Un rechazo expresado con otras palabras no es la frase exacta, así que pasa como si fuera una respuesta, como muestra q-0080 en capítulo 2. Las tasas de rechazo tampoco cuentan los ítems que dependen de la versión, y el ítem q-0004 muestra lo que esto cuesta, como explica capítulo 1. La línea base lo rechaza, y la documentación 2.0 lo responde en su sección sobre marcadores de posición. La tasa de rechazos no lo considera un falso rechazo. Respuestas fundamentadas construye la tasa de corrección de versión que sí lo hace.
Si un rechazo es acertado en un ítem que la documentación no cubre es una cuestión de juicio, no una comprobación en código. Si la documentación dice lo suficiente para responder es la pregunta que aborda rechazar cuando la documentación no lo dice.
Regla práctica: Cuenta ambos tipos de error de rechazo en todas las particiones, y revisa a mano cada rechazo que dependa de la versión frente a la documentación de su versión, porque la tasa de rechazos deja esos ítems fuera.
Ejecución de las comprobaciones y lo que resuelven
En producción las comprobaciones se ejecutan en cada respuesta, de modo que un cambio en el prompt o en el modelo mueve a la vez los recuentos de formato, las tasas de rechazo y la proporción de citas fuera de la lista en un único informe. Un cambio que deja todos esos valores estables mientras los usuarios reportan respuestas incorrectas es la señal de que las comprobaciones no ven el fallo. Clasifica cada respuesta nueva según su principal defecto, como describe el capítulo 2, y escribe una comprobación para el modo que corresponda.
Lo que este capítulo establece es acotado. Una comprobación por código puede mantener la forma de una respuesta, la pertenencia de sus citas y la frase de rechazo en orden, y puede hacerlo en cada respuesta sin coste. Lo que significa una respuesta sigue necesitando a un lector o a un juez. Por eso, clasifica cada respuesta según su principal defecto, limita cada comprobación a los defectos que puede ver y envía lo que no puede ver a un lector o a un juez, de forma que un recuento limpio nunca se tome por una respuesta correcta.
El capítulo tomó estas decisiones:
- La comprobación de formato es un filtro con cinco nombres, que se ejecuta antes de cualquier juez.
- La comprobación de formato cuenta las citas y no lee su orden, de modo que deja pasar la respuesta del segundo modelo a q-0030. La comprobación de orden marca esa respuesta.
- Una cita es
supportedcuando su ID está en la lista del elemento, y nunca lo es por estar bien la frase que la rodea. - La comprobación de versión sobre las citas no encuentra ninguna cita de versión incorrecta en estas tres grabaciones, y el capítulo no presenta eso como una comprobación de las versiones de las respuestas.
- Las puntuaciones de solapamiento provienen de las fórmulas propias del ejemplo, y ninguna puntuación se usa como umbral de aprobado.
- Las propiedades de coincidencia aproximada se muestran en las respuestas de sablefile, y ningún cociente se usa como umbral de aprobado.
- Los elementos reservados aparecen solo como recuentos en la comprobación de formato, y el capítulo 10 los lee.
Este capítulo, en esta edición
Edición 2026.11.3Ejemplos verificados el 21 de nov de 2026Superan la prueba 5 de 5 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.3.