Comprueba que las respuestas se apoyen en la documentación citada, en la versión preguntada
Unos 21 minutos de lectura, con 6 ejemplos en 8 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 terminar este capítulo podrás contar si las citas de una respuesta respaldan lo que dice, si cada afirmación se apoya en las secciones que recibió el asistente, si es correcta para la versión por la que preguntó el lector, y si la recuperación llegó a la sección correcta en el camino.
Una respuesta correcta puede seguir siendo una mala respuesta. El asistente de este libro responde preguntas sobre sablefile a partir de su documentación, y una respuesta se da por buena cuando coincide con la respuesta de referencia para la versión por la que pregunta la consulta. Una respuesta puede superar esa prueba y, aun así, citar una sección que no dice lo que dice su frase, añadir un detalle que ninguna sección ofrece, o tomar sus datos de otra versión de la documentación. La tasa de aciertos no ve nada de esto. Un lector que comprueba la cita junto a una afirmación sí puede verlo, y por eso se pide al asistente que cite.
Junto a la tasa de aciertos hay cuatro comprobaciones, y cada una tiene su propio recuento sobre su propio denominador. La exactitud de las citas pregunta si cada cita nombra una sección que el ítem indica como respaldo. La fidelidad pregunta si cada afirmación está en las secciones que se le mostraron al asistente. La corrección de la versión pregunta si la respuesta corresponde a la versión preguntada. El resultado frente a la ruta pregunta si un acierto llegó con su sección a mano, y si un fallo la tuvo. La exactitud de las citas y la fidelidad dejan fuera las negativas, pues una negativa no hace ninguna afirmación que verificar. La corrección de la versión y la tabla de recuperación conservan las negativas, igual que la tasa de aciertos, y cada una indica cuántas negativas contiene.
Qué significa estar fundamentado aquí
Una respuesta está fundamentada cuando un lector que sigue sus citas encuentra la afirmación donde dice la cita, en la versión por la que preguntó. Para eso tienen que cumplirse tres cosas. La cita debe existir en esa versión y respaldar la oración a la que está unida. Toda afirmación de la respuesta debe seguirse de las secciones que leyó el asistente. Y la respuesta debe ser correcta para esa versión, no solo correcta para alguna otra versión que use las mismas palabras.
Imagina que un lector pregunta cuánto tiempo espera una descarga remota antes de rendirse. Supón que la respuesta da una cifra verosímil y cita la sección sobre la descarga de plantillas remotas, pero esa sección nunca dice cuánto dura la espera. Un lector daría por fundamentada la respuesta, y la cita parece correcta. El lector que abre la sección no encuentra nada que respalde la cifra. Una tasa de aciertos contaría esa respuesta como correcta si la cifra coincidiera con la de referencia. La fidelidad es la comprobación que lee las secciones, mediante un juez. La comprobación de citas solo lee identificadores, y así lo indica.
Estos fallos son distintos, y cada uno necesita su propio recuento. Una respuesta puede tener una cita que la respalde y aun así afirmar un detalle que la sección omite, de modo que la exactitud de las citas no demuestra fidelidad. Una respuesta puede ser fiel a una sección de una versión y ser errónea para otra, así que la fidelidad no demuestra que sea correcta para la versión. Y una respuesta puede ser acertada y estar bien citada mientras el paso de recuperación nunca llegó a la sección en la que se apoya. Comparar resultado con recorrido existe para detectar ese caso.
Regla práctica: Da a cada comprobación su propio recuento sobre su propio denominador, y trata un resultado positivo como el inicio de la lectura, no como su final.
Precisión de las citas
Una cita es una afirmación sobre la documentación: esta sección, en esta versión, respalda la oración a la que está adjunta. Como cualquier afirmación, puede ser incorrecta. La sección puede existir y decir otra cosa. Puede pertenecer a otra versión. O la respuesta puede citar una sección que el elemento no enumera. El Primer cubre la comprobación a nivel de oración, comprobar lo que respalda un elemento citado, y comprobar las citas frente al contexto cubre el contexto que se le dio a un modelo. La comprobación de este libro es más sencilla, y comprobaciones de citas en el capítulo 4 describe sus cuatro resultados. Compara cada ID citado con la lista de secciones de respaldo del elemento para la versión consultada. Nunca lee la sección, así que no dice nada sobre la oración.
El código imprime dos recuentos de las mismas respuestas. La tasa de citas cuenta cada cita en los elementos respondidos que está respaldada. La tasa de elementos cuenta un elemento respondido una sola vez si al menos una de sus citas está respaldada, de modo que una cita buena basta para el elemento. Una cita a una sección de la versión consultada que el elemento no enumera se imprime como no listada. Esa sección puede perfectamente ser correcta, así que la comprobación no la considera errónea, y no abre la sección para averiguarlo. Leer una cita no listada es una decisión manual. Si la sección respalda la oración, la lista de secciones de respaldo del elemento está incompleta, y el responsable del conjunto de prueba debería añadirla. Si no la respalda, la cita es incorrecta, y la respuesta debe leerse como una cita fallida.
Ejecútala en ambas particiones, y lee la línea del elemento antes que la línea de citas.
1"""Counts the baseline's answered items that cite a supporting section of the asked version, dev and held-out apart.23An item counts once, and only if one of its citations is supported; its other citations sit in the citation lines. A decline4is not an answer, so it is left out of every count. The check matches each cited ID against the item's listed supporting5section IDs for its asked version. It never reads the section's text, so it does not check what the sentence says.6The first line of each split is the point: the item rate."""7import lib # first: fixes the thread counts and seeds before anything else loads89from lib.contract import citation_outcomes, parse_reply, section_ids_by_version10from lib.prompts import P1_SHA25611from lib.replay import ReplayModel12from lib.stats import pct13from lib.testset import load_items1415ids = section_ids_by_version() # every version's section IDs, read from the docs, for telling wrong-version from missing16model = ReplayModel("assistant-baseline", P1_SHA256) # the baseline's replies, sample 0, made from prompt P1171819def supporting_ids(item):20 """The item's supporting section IDs in its asked version. Another version's listed sections are not counted here."""21 return frozenset(s.section_id for s in item.supporting_sections if s.version == item.version)222324for split in ("dev", "held-out"):25 declined = 026 results = {} # item id -> its citation outcomes, for each answered item27 for item in load_items(split=split):28 reply = parse_reply(model.reply(item.id, 0))29 if reply.declined:30 declined += 131 else:32 results[item.id] = citation_outcomes(reply, item.version, supporting_ids(item), ids)33 # An answer to an unanswerable item lists no section of its asked version, so it can never count as supported here.34 outcomes = [outcome for found in results.values() for outcome in found] # every citation, in item order35 with_support = [item_id for item_id, found in results.items() if "supported" in found]36 no_support = sorted(set(results) - set(with_support))37 print(f"{split} declined items, left out: {declined}")38 print(f"{split} answered items: {len(results)}")39 print(f"{split} answered items citing a supporting section of the asked version: {pct(len(with_support), len(results))}")40 print(f"{split} answered items with no supported citation: {len(no_support)}")41 print(" " + (", ".join(no_support) or "none"))42 print(f"{split} citations: {len(outcomes)}")43 print(f"{split} citations that are supported: {pct(outcomes.count('supported'), len(outcomes))}")44 print(f"{split} citations that are unlisted: {pct(outcomes.count('unlisted'), len(outcomes))}")45 print(f"{split} citations that are wrong-version or missing: "46 f"{pct(outcomes.count('wrong-version') + outcomes.count('missing'), len(outcomes))}")
python citation-accuracy-counts.pydev declined items, left out: 23
dev answered items: 57
dev answered items citing a supporting section of the asked version: 94.7% (54 of 57)
dev answered items with no supported citation: 3
q-0005, q-0057, q-0058
dev citations: 60
dev citations that are supported: 93.3% (56 of 60)
dev citations that are unlisted: 6.7% (4 of 60)
dev citations that are wrong-version or missing: 0.0% (0 of 60)
held-out declined items, left out: 15
held-out answered items: 25
held-out answered items citing a supporting section of the asked version: 96.0% (24 of 25)
held-out answered items with no supported citation: 1
q-0090
held-out citations: 33
held-out citations that are supported: 93.9% (31 of 33)
held-out citations that are unlisted: 6.1% (2 of 33)
held-out citations that are wrong-version or missing: 0.0% (0 of 33)
En dev, la tasa de elementos es 94.7% (54 of 57).
En dev, 3 elementos respondidos no tienen ninguna cita respaldada, y la salida los nombra. En held-out, el recuento es 1.
La tasa de citas en dev es 93.3% (56 of 60). Las citas no listadas en dev son 6.7% (4 of 60), que la salida informa y no cuenta como errores.
En held-out, la tasa de elementos es 96.0% (24 of 25), y la tasa de citas es 93.9% (31 of 33). Held-out tiene solo 25 elementos respondidos, así que un solo elemento mueve su tasa mucho. Una diferencia entre las particiones necesitaría un intervalo antes de que alguien la considerara real, y intervalos y tamaño de muestra explica cómo construir uno.
Las citas de versión incorrecta o ausentes son las que serían erróneas por una razón que la comprobación puede nombrar. En dev son 0.0% (0 of 60). En held-out son 0.0% (0 of 33). Así que las tasas de citas se quedan por debajo del 100 % por las citas no listadas, y una persona tiene que leer esas.
Las dos tasas pueden divergir por una razón sencilla. Un elemento con una cita respaldada y una cita no listada cuenta en la tasa de elementos y reduce la tasa de citas. Leer ambas muestra si los fallos están en elementos completos o en citas individuales dentro de elementos que, por lo demás, se sostienen.
La idea detrás de la comprobación ha sido estudiada fuera de este libro. Gao y colaboradores (2023), en EMNLP 2023 y en arXiv, construyeron un punto de referencia para las citas en respuestas generadas, e informaron de que muchas respuestas de modelos sólidos no estaban totalmente respaldadas por los pasajes que citaban. Su configuración no era la de este libro, así que no se traslada ningún número de ellos. El artículo se cita por la idea.
Regla práctica: Lee la tasa de elementos y la tasa de citas juntas, y lee cada cita no listada antes de cambiar un prompt. Una cita no listada es una pregunta para la documentación, no un error que contar.
Fidelidad
La exactitud de las citas se ejecuta sin un modelo, pero sus recuentos indican cuántas citas nombran una sección listada, no si cada oración se sostiene. La fidelidad es la siguiente pregunta, y es la que detecta las afirmaciones que no llevan ninguna cita.
La exactitud de las citas revisa solo las oraciones que llevan una cita. Una afirmación que la respuesta hace sin cita se le escapa, y también una afirmación que una sección citada respalda solo en parte. La fidelidad plantea una pregunta más amplia: ¿cada afirmación de la respuesta se deduce de las secciones que se le mostraron al asistente?
Ragas (Es et al., 2023, también un preprint) puntúa la fidelidad como la proporción de afirmaciones de una respuesta que el contexto respalda. Divide la respuesta en afirmaciones y revisa cada una. Este libro plantea en cambio una pregunta por respuesta. El prompt de fidelidad en lib/prompts.py entrega al juez las secciones y la respuesta. El juez lee la respuesta afirmación por afirmación y escribe VERDICT: SUPPORTED en su primera línea solo si todas las afirmaciones se sostienen. De lo contrario escribe VERDICT: UNSUPPORTED, seguido de una oración con el motivo.
La diferencia con la exactitud de las citas aparece en medio de una respuesta. Supón que una respuesta tiene dos oraciones. La primera lleva una cita a una sección que la respalda, y la segunda no tiene ninguna, porque añade un detalle que la sección no incluye. La exactitud de las citas puntúa la primera oración y no dice nada sobre la segunda. La fidelidad lee la respuesta completa, así que puede marcar la respuesta como no respaldada solo por la segunda oración. Ninguna de las dos pruebas reemplaza a la otra, por eso se mantienen ambas.
Nadie ha comparado los veredictos de este juez con los de una persona, así que cada tasa de fidelidad aquí es no calibrada. Además, el juez es el propio modelo del asistente, Qwen3-4B-Instruct-2507, así que califica respuestas que ese mismo modelo escribió. Autopreferencia explica por qué esto importa, y por qué este libro no puede probarlo. Calibrar el juez requeriría calificaciones humanas de estas respuestas, que este libro no tiene. Calibra el juez describe el método, que compara el juez con calificaciones hechas a mano. Como estas tasas no están calibradas, no hay nada que el supuesto de transferencia pueda trasladar, y los límites de hasta dónde llegar se aplican a ellas en su totalidad.
1"""The faithfulness rate of assistant-baseline's answered items, as judged in judge-faithfulness-baseline, dev and held-out apart.23An answered item is one the baseline did not decline and whose reply is not empty; a decline is left out. The judge writes4SUPPORTED or UNSUPPORTED on its first line. A reply that is neither is printed by item ID and left out of the denominator,5never counted as UNSUPPORTED. The judge is uncalibrated: this book has no human ratings for it, so the rates are not6corrected for its errors and are not a calibrated measure. When every readable verdict is the same, the percentile7bootstrap cannot vary, so the example says so and prints the exact binomial bound for n of n instead."""8import lib # first: fixes the thread counts and seeds before anything else loads910from lib.contract import parse_reply11from lib.judging import parse_support_verdict12from lib.prompts import FAITH_SHA256, P1_SHA25613from lib.replay import ReplayModel14from lib.stats import bootstrap_mean, interval_pct, pct15from lib.testset import load_items1617answers = ReplayModel("assistant-baseline", P1_SHA256) # the baseline's replies, sample 0, made from prompt P118judge = ReplayModel("judge-faithfulness-baseline", FAITH_SHA256) # the judge's replies, made from the faithfulness prompt1920print("judge: judge-4b, uncalibrated (no human ratings in this book)")21for split in ("dev", "held-out"):22 answered = []23 for item in load_items(split=split):24 reply = parse_reply(answers.reply(item.id, 0))25 if not reply.declined and reply.text:26 answered.append(item.id)27 readable = {} # item id -> 1.0 for SUPPORTED, 0.0 for UNSUPPORTED28 for item_id in answered:29 raw = judge.reply(item_id, 0)30 verdict = parse_support_verdict(raw)31 if verdict is None:32 line = next((ln.strip().strip("*`").strip() for ln in raw.splitlines() if ln.strip()), "")33 print(f'{split} unreadable verdict, left out: {item_id} ("{line}")')34 else:35 readable[item_id] = 1.0 if verdict == "SUPPORTED" else 0.036 scores = list(readable.values())37 lo, hi = bootstrap_mean(scores) # level 0.95; seed SEED, 2,000 resamples38 print(f"{split} answered items: {len(answered)}")39 print(f"{split} unreadable verdicts: {len(answered) - len(readable)}")40 print(f"{split} faithfulness rate: {pct(int(sum(scores)), len(scores))}")41 print(f"{split} 95% interval of the faithfulness rate: {interval_pct(lo, hi)}")42 if len(set(scores)) == 1: # every readable verdict is the same, so resampling cannot vary43 print(f"{split} bootstrap interval is degenerate: all {len(scores)} readable verdicts are the same")44 if sum(scores) == len(scores):45 print(f"{split} exact 95% lower bound for {len(scores)} of {len(scores)}: {100 * 0.025 ** (1 / len(scores)):.1f}%")46 if split == "dev":47 unfaithful = sorted(item_id for item_id, score in readable.items() if score == 0.0)48 print(f"dev unfaithful items, first five: {', '.join(unfaithful[:5])}")
python faithfulness-rate.pyjudge: judge-4b, uncalibrated (no human ratings in this book)
dev answered items: 57
dev unreadable verdicts: 0
dev faithfulness rate: 94.7% (54 of 57)
dev 95% interval of the faithfulness rate: [87.7%, 100.0%]
dev unfaithful items, first five: q-0013, q-0029, q-0055
held-out answered items: 25
held-out unreadable verdicts: 0
held-out faithfulness rate: 100.0% (25 of 25)
held-out 95% interval of the faithfulness rate: [100.0%, 100.0%]
held-out bootstrap interval is degenerate: all 25 readable verdicts are the same
held-out exact 95% lower bound for 25 of 25: 86.3%
El ejemplo toma los elementos respondidos de la línea base, deja fuera las negativas y pregunta al juez por cada uno. Imprime una tasa solo sobre los veredictos que puede leer. Una respuesta que no es ni SUPPORTED ni UNSUPPORTED se imprime por elemento y queda fuera del denominador. Nunca se cuenta como un fallo, como explica veredicto primero.
La tasa de fidelidad no calibrada en dev es 94.7% (54 of 57). Su intervalo es [87.7%, 100.0%]. El extremo superior de ese intervalo queda sobre el límite superior de la escala de tasas, porque un bootstrap no puede remuestrear más allá de él. El intervalo sigue siendo amplio, que es la lectura honesta de 57 elementos respondidos.
La tasa de fidelidad no calibrada en held-out es 100.0% (25 of 25). Su intervalo impreso es [100.0%, 100.0%], pero eso no es un intervalo. La salida indica que el bootstrap es degenerado: all 25 readable verdicts are the same. Un remuestreo de elementos que todos pasan solo puede devolver la misma tasa, así que el bootstrap no dice nada sobre dónde se encuentra la tasa.
El límite inferior exacto del 95 % es 86.3%. Por debajo de esa tasa real, que pasaran todas las respuestas held-out ocurriría con una probabilidad inferior al 2.5 %. La cota es 0.025 elevado a 1/n. Muestra que el juez aprobó estas respuestas, en una división demasiado pequeña para mostrar dónde se encuentra la tasa. No leas la cifra de held-out como un hallazgo de que el asistente es fiel.
Las dos pruebas imprimen sus propias listas. La salida de citas nombra los elementos sin una cita respaldada, y la salida de fidelidad nombra los primeros elementos de dev no fieles. Lee las dos listas una al lado de la otra, ya que este capítulo no asume que nombren los mismos elementos.
Regla práctica: Escribe "no calibrada" junto a cada tasa de fidelidad, y lee los primeros elementos no fieles antes de confiar en la tasa. Una prueba de fidelidad muestra dónde el juez dice que una afirmación no está respaldada. No muestra que el juez tenga razón.
Corrección por versión
sablefile tiene tres versiones de su documentación, 1.0, 1.1 y 2.0, y algunas preguntas tienen respuestas distintas en cada una. Una respuesta puede basarse en una sección de 1.1 y, aun así, ser incorrecta para un lector que usa 2.0. El libro llama a estos elementos dependientes de la versión. Cada uno tiene una respuesta de referencia para la versión por la que preguntó el lector, y su comprobación pregunta si la respuesta coincide con esa referencia. Hay 17 de ellos en el conjunto de desarrollo y 8 en el conjunto de prueba.
Los elementos dependientes de la versión cuentan en la tasa de aciertos junto con todos los demás, y además tienen su propio recuento, junto a ese. Una respuesta a uno de ellos se juzga contra la referencia de la versión preguntada, así que una respuesta correcta para otra versión cuenta como fallo. Ese fallo parecería un asistente débil si solo se mezclara en la tasa general. La tasa de respuestas correctas es el recuento solo de los elementos dependientes de la versión, de modo que un fallo de versión aparece en su propia línea, y un equipo puede ver si un cambio en la recuperación lo modificó. Las negativas se mantienen en ese denominador, como en la tasa de aciertos, y cada división indica cuántas contiene.
Una cita de versión incorrecta es un recuento aparte. Es una cita a una sección que existe solo en otra versión. Una respuesta puede ser correcta para la versión preguntada y, aun así, citar una sección de otra versión, y un lector que copie esa cita llegará a la documentación equivocada.
Esta comprobación solo ve lo que le indica el ID. Una cita lleva un ID, no una versión. La mayoría de los ID se repiten entre versiones, así que un ID de sección que aparece en 1.0, 1.1 y 2.0 se ve igual en cada una. Un ID que aparece en todas las versiones nunca puede marcarse como de otra versión, sea cual sea la versión que pidió el lector. La comprobación solo puede marcar una cita cuando la versión preguntada no tiene su ID y otra versión sí lo tiene. El índice también importa. Una cita a otra versión solo es posible cuando las secciones de esa versión están en el índice con el que se construyó la respuesta, así que el recuento debe releerse cuando cambie el índice, y un cero de un índice antiguo no dice nada sobre uno nuevo.
Aquí se leen dos variantes. La línea base recupera solo del índice de la versión preguntada. La variante sin filtrar recupera de los índices de todas las versiones juntas, y muestra la versión de cada sección en su encabezado, para que el modelo vea de dónde procede cada sección. La variante sin filtrar es la que podría citar otra versión, ya que se le muestran.
1"""Reads the 25 version-dependent items for two variants: whether the judge passed the answer for the asked version, and whether a2citation names a section that exists only in another version.34The judge's verdict for each variant is read from its own recording, and an unreadable verdict is printed and left out of the5pass rate, never counted as a fail. A declined reply has a verdict like any other reply, so it stays in the denominator; its6count is printed beside each rate. A wrong-version citation is counted per item, over every item, so a zero shows as 0 of 25.7The last lines list the items where the two variants disagree, to read item by item."""8import lib # first: fixes the thread counts and seeds before anything else loads910from lib.calibration import readable_verdicts11from lib.contract import citation_outcomes, parse_reply, section_ids_by_version12from lib.prompts import P1_SHA256, REF_SHA25613from lib.replay import ReplayModel14from lib.stats import pct15from lib.testset import load_items1617ids = section_ids_by_version() # every version's section IDs, so a section of another version is known as one18# label, the assistant's recording, the judge's recording of that assistant's replies19VARIANTS = (("baseline", "assistant-baseline", "judge-answers-baseline"), ("unfiltered", "assistant-unfiltered", "judge-answers-unfiltered"))20items = [item for item in load_items() if item.kind == "version-dependent"]21item_ids = [item.id for item in items]22listed = {item.id: frozenset(s.section_id for s in item.supporting_sections if s.version == item.version) for item in items}23verdict, wrong = {}, {} # label -> {item id: PASS or FAIL, readable only}; label -> item ids with a wrong-version citation24for label, assistant, judge in VARIANTS:25 verdict[label], unreadable = readable_verdicts(judge, item_ids, REF_SHA256)26 for item_id, first in unreadable:27 print(f'{label} unreadable verdict, left out: {item_id} ("{first}")')28 replies = ReplayModel(assistant, P1_SHA256)29 wrong[label] = {item.id for item in items30 if "wrong-version" in citation_outcomes(parse_reply(replies.reply(item.id, 0)), item.version, listed[item.id], ids)}31 for split in ("dev", "held-out"):32 split_items = [item for item in items if item.split == split]33 readable = [item.id for item in split_items if item.id in verdict[label]]34 passed = sum(verdict[label][item_id] == "PASS" for item_id in readable)35 print(f"{label} {split} version-dependent items: {len(split_items)}")36 print(f"{label} {split} declined replies, counted in the denominator: "37 f"{sum(parse_reply(replies.reply(item.id, 0)).declined for item in split_items)}")38 print(f"{label} {split} judged correct for the asked version: {pct(passed, len(readable))}")39 print(f"{label} {split} citing a wrong-version section: "40 f"{pct(sum(item.id in wrong[label] for item in split_items), len(split_items))}")41 print(f"{label} all version-dependent items citing a wrong-version section: {pct(len(wrong[label]), len(items))}")4243both = [item_id for item_id in item_ids if item_id in verdict["baseline"] and item_id in verdict["unfiltered"]]44print(f"items with a readable verdict in both variants: {len(both)}")45differ = [i for i in both if verdict["baseline"][i] != verdict["unfiltered"][i]]46print(f"items where the verdicts differ: {len(differ)}")47print(" " + (", ".join(differ) or "none"))48flag_differ = [i for i in item_ids if (i in wrong["baseline"]) != (i in wrong["unfiltered"])]49print(f"items where the wrong-version flag differs: {len(flag_differ)}")50print(" " + (", ".join(flag_differ) or "none"))
python version-correct-answers.pybaseline dev version-dependent items: 17
baseline dev declined replies, counted in the denominator: 4
baseline dev judged correct for the asked version: 64.7% (11 of 17)
baseline dev citing a wrong-version section: 0.0% (0 of 17)
baseline held-out version-dependent items: 8
baseline held-out declined replies, counted in the denominator: 2
baseline held-out judged correct for the asked version: 75.0% (6 of 8)
baseline held-out citing a wrong-version section: 0.0% (0 of 8)
baseline all version-dependent items citing a wrong-version section: 0.0% (0 of 25)
unfiltered dev version-dependent items: 17
unfiltered dev declined replies, counted in the denominator: 5
unfiltered dev judged correct for the asked version: 52.9% (9 of 17)
unfiltered dev citing a wrong-version section: 0.0% (0 of 17)
unfiltered held-out version-dependent items: 8
unfiltered held-out declined replies, counted in the denominator: 2
unfiltered held-out judged correct for the asked version: 75.0% (6 of 8)
unfiltered held-out citing a wrong-version section: 0.0% (0 of 8)
unfiltered all version-dependent items citing a wrong-version section: 0.0% (0 of 25)
items with a readable verdict in both variants: 25
items where the verdicts differ: 6
q-0003, q-0021, q-0022, q-0033, q-0082, q-0085
items where the wrong-version flag differs: 0
none
En todos los elementos dependientes de la versión, la proporción de citas de versión incorrecta es 0.0% (0 of 25) para la línea base y 0.0% (0 of 25) para la variante sin filtrar. Un cero solo indica que la comprobación no marcó ningún ID. El siguiente ejemplo muestra cuán pocos ID podría haber marcado.
1"""The two counts behind the version check, and the version-dependent items where the variants' verdicts differ, by split.23A wrong-version citation is one whose ID exists only in another version, so an ID that several versions share cannot be4attributed to one of them. This prints how many section IDs are found in one version only, then how many citations to the5version-dependent items name a shared ID, for each variant. The last lines list the items where the verdicts differ, by split."""6import lib # first: fixes the thread counts and seeds before anything else loads78from collections import Counter910from lib.calibration import readable_verdicts11from lib.contract import parse_reply, section_ids_by_version12from lib.prompts import P1_SHA256, REF_SHA25613from lib.replay import ReplayModel14from lib.stats import pct15from lib.testset import load_items1617ids = section_ids_by_version()18shared = Counter(i for found in ids.values() for i in found) # how many versions each section ID appears in19print("section IDs found in one version only, by version: "20 + ", ".join(f"{v} {sum(shared[i] == 1 for i in found)}" for v, found in ids.items()))21items = [item for item in load_items() if item.kind == "version-dependent"]22split_of = {item.id: item.split for item in items}23verdict = {} # label -> {item id: PASS or FAIL}, readable only24for label, assistant, judge in (("baseline", "assistant-baseline", "judge-answers-baseline"),25 ("unfiltered", "assistant-unfiltered", "judge-answers-unfiltered")):26 replies = ReplayModel(assistant, P1_SHA256)27 cited = [cid for item in items for cid in parse_reply(replies.reply(item.id, 0)).citations]28 print(f"{label} citations to a section ID found in more than one version: "29 f"{pct(sum(shared[cid] > 1 for cid in cited), len(cited))}")30 verdict[label], _ = readable_verdicts(judge, list(split_of), REF_SHA256)31differ = [i for i in verdict["baseline"] if i in verdict["unfiltered"] and verdict["baseline"][i] != verdict["unfiltered"][i]]32for split in ("dev", "held-out"):33 part = [i for i in differ if split_of[i] == split]34 print(f"{split} items where the verdicts differ: {len(part)}")35 print(" " + (", ".join(part) or "none"))
python version-check-detail.pysection IDs found in one version only, by version: 1.0 0, 1.1 0, 2.0 4
baseline citations to a section ID found in more than one version: 87.0% (20 of 23)
unfiltered citations to a section ID found in more than one version: 63.2% (12 of 19)
dev items where the verdicts differ: 4
q-0003, q-0021, q-0022, q-0033
held-out items where the verdicts differ: 2
q-0082, q-0085
Los ID de sección que se encontraron en una sola versión, contados por versión, son 1.0 0, 1.1 0, 2.0 4. Un ID encontrado en más de una versión aún puede marcarse, pero solo para un lector en una versión que no lo tenga. Para la línea base, la proporción de citas a elementos dependientes de la versión que nombran un ID compartido es 87.0% (20 of 23). Para la variante sin filtrar es 63.2% (12 of 19).
Las tasas de respuestas correctas difieren, aunque cada una se lee sobre una división pequeña. En desarrollo, la línea base se juzga correcta en 64.7% (11 of 17).
La variante sin filtrar se juzga correcta en 52.9% (9 of 17). En estos elementos, la variante sin filtrar aprueba menos.
En el conjunto de prueba, la línea base se juzga correcta en 75.0% (6 of 8). La variante sin filtrar tiene la misma tasa, pero aprueba elementos distintos. Los veredictos van en direcciones opuestas en q-0082 y q-0085, y los demás elementos del conjunto de prueba coinciden.
En ambas variantes, los veredictos difieren en 6 elementos, de 25 con un veredicto legible en cada una. En desarrollo, 4 de ellos difieren, y en el conjunto de prueba, 2. La salida los enumera por división.
No se calcula ningún intervalo para estas diferencias, y una división de desarrollo de este tamaño es pequeña. Por eso este capítulo informa los recuentos y no afirma que una variante sea mejor o peor. Los recuentos dicen tres cosas: en estos elementos la variante sin filtrar aprobó menos, no se marcó ninguna cita de otra versión en ninguna de las dos variantes, y los veredictos que difieren son el primer lugar que conviene leer.
Regla práctica: Lee el ID de cada cita junto con la versión de la respuesta que la acompaña. Un cero de esta comprobación significa que no se marcó ningún ID, no que no haya citas de versión incorrecta. Mantén los elementos dependientes de la versión en su propio recuento junto a la tasa de aciertos, para que un fallo de versión aparezca en su propia línea.
Resultado y camino
El resultado indica si una respuesta pasó. El camino indica qué alcanzaron los pasos previos a la respuesta. En este libro el camino es corto: una recuperación y luego una respuesta. Dos combinaciones requieren ambos datos. Un acierto cuya sección de apoyo nunca llegó al modelo provino de otra fuente, quizá del propio conocimiento del modelo, y eso es una advertencia aunque el veredicto sea correcto. Un fallo con la sección recuperada es el caso para cuya explicación existen las demás comprobaciones.
Las ejecuciones con varios pasos tienen caminos más largos. Agent Harnesses cuenta una tarea a lo largo de su camino, y ese libro es el lugar para leer sobre ello. Este capítulo puntúa el único paso que tiene el asistente.
El paso de recuperación
La recuperación es BM25 sobre las secciones de la versión consultada. Es determinista: la misma pregunta obtiene siempre las mismas secciones principales. Por eso este paso no necesita registro. El código calcula las secciones principales de cada elemento a partir del índice y las compara con el veredicto que el juez dio a la respuesta de la línea base.
Los elementos de desarrollo sin una sección de apoyo de la versión consultada quedan fuera de la tabla. Son los elementos sin respuesta, ya que no existe ninguna sección de su versión consultada que la recuperación pueda encontrar. Su número es 13.
1"""Sets the baseline's judge verdict against whether a supporting section reached the top k, for each dev item that has one.23Retrieval is BM25 over the asked version, so it is the same on every run and needs no recording; k is the baseline's, read from4its manifest. The two diagonal cells are the expected pairs. The two off-diagonal cells are the ones to read: a pass without the5right section retrieved, and a fail with it retrieved. Unanswerable items are left out, since they have no section of their asked6version to retrieve; their count is printed. An unreadable verdict is printed and left out, never counted as a fail. A declined reply is counted in its cell like any7other reply; the count of declines is printed. The FAIL cell is split into declines and answers in fail-with-section."""8import lib # first: fixes the thread counts and seeds before anything else loads910from lib.answers import Assistant11from lib.calibration import readable_verdicts12from lib.contract import parse_reply13from lib.prompts import P1_SHA256, P1_SYSTEM, REF_SHA25614from lib.replay import ReplayModel15from lib.testset import load_items1617RECORDING = "assistant-baseline"18k = ReplayModel(RECORDING, P1_SHA256).manifest["k"] # the top k the baseline's prompt was built from, read from its manifest19assistant = Assistant(RECORDING, P1_SYSTEM, P1_SHA256, k=k) # its retriever only; the recording is not read here20replies = ReplayModel(RECORDING, P1_SHA256) # the baseline's replies, sample 0, made from prompt P1, for the decline check2122dev = load_items(split="dev")23has_support = [item for item in dev if any(s.version == item.version for s in item.supporting_sections)]24print(f"top k: {k}")25print(f"dev items: {len(dev)}")26print(f"dev items with no supporting section of the asked version, left out: {len(dev) - len(has_support)}")2728verdicts, unreadable = readable_verdicts("judge-answers-baseline", [item.id for item in has_support], REF_SHA256)29for item_id, first in unreadable:30 print(f'unreadable verdict, left out: {item_id} ("{first}")')3132# Keyed by (retrieved, passed): the four cells of the 2 by 2 table, each a list of item ids in sorted order.33cells = {(True, True): [], (True, False): [], (False, True): [], (False, False): []}34declined = set() # item ids whose reply is a decline; they sit in their cells like any other reply35for item in has_support:36 if item.id not in verdicts:37 continue38 listed = {s.section_id for s in item.supporting_sections if s.version == item.version}39 top = {section.section_id for section in assistant.sections(item)} # the top k sections, by BM25 rank40 cells[(bool(listed & top), verdicts[item.id] == "PASS")].append(item.id)41 if parse_reply(replies.reply(item.id, 0)).declined:42 declined.add(item.id)4344print(f"items in the table: {sum(len(ids) for ids in cells.values())}")45print(f"declined items in the table, counted in their cells: {len(declined)}")46print(f"right section in the top {k}, PASS: {len(cells[(True, True)])}")47print(f"right section in the top {k}, FAIL: {len(cells[(True, False)])}")48print(f"right section not in the top {k}, PASS: {len(cells[(False, True)])}")49print(f"right section not in the top {k}, FAIL: {len(cells[(False, False)])}")50print("passed without the right section retrieved: " + (", ".join(cells[(False, True)]) or "none"))51print("failed with the right section retrieved: " + (", ".join(cells[(True, False)]) or "none"))
python retrieval-path.pytop k: 3
dev items: 80
dev items with no supporting section of the asked version, left out: 13
unreadable verdict, left out: q-0043 ("VERDICT: PARTIAL")
items in the table: 66
declined items in the table, counted in their cells: 10
right section in the top 3, PASS: 49
right section in the top 3, FAIL: 10
right section not in the top 3, PASS: 0
right section not in the top 3, FAIL: 7
passed without the right section retrieved: none
failed with the right section retrieved: q-0019, q-0023, q-0025, q-0029, q-0033, q-0045, q-0046, q-0048, q-0063, q-0074
El top k es 3, tomado del manifiesto de la línea base. La tabla contiene 66 elementos, y 10 de ellos son negativas. Una negativa aparece en su celda como cualquier otra respuesta, ya que el juez le dio un veredicto. Cada celda combina un veredicto con la indicación de si una sección de apoyo llegó al top k.
| Veredicto | Sección de apoyo en el top k | Sin sección de apoyo en el top k |
|---|---|---|
| PASS | 49 | 0 |
| FAIL | 10 | 7 |
Lee primero la fila PASS. La celda de aprobados con la sección en el top k contiene 49 aprobados, y la celda de aprobados sin ella contiene 0. Eso es coherente con que los aprobados provengan de la documentación. No demuestra que así sea, porque la tabla cuenta con qué frecuencia aparecen dos cosas juntas, no cuál causa a la otra. El recuento de aprobados también sirve como comprobación de la línea base. Un aprobado sin sección recuperada puede provenir de una respuesta que repite un dato común, o de una respuesta de referencia que un lector podría adivinar, y la tabla no puede decir cuál de las dos ocurre. Leer esos elementos sí puede hacerlo.
La fila FAIL es donde entran las demás comprobaciones. De los fallos con la sección en el top k, 5 son negativas, y el resto son respuestas. Negarse cuando la documentación no lo dice explica qué significa una negativa cuando la documentación contiene la respuesta. El ejemplo siguiente divide la celda.
1"""The dev items the baseline failed although a listed section of the asked version was in its top k, split into declines and answers.23For each answer it prints whether the reply cites a listed section, and the faithfulness judge's verdict on it. A decline has no4faithfulness verdict, because the judge reads only answers. An unreadable verdict is printed and left out, never counted as a fail."""5import lib # first: fixes the thread counts and seeds before anything else loads67import re89from lib.answers import Assistant10from lib.calibration import readable_verdicts11from lib.contract import citation_outcomes, parse_reply, section_ids_by_version12from lib.prompts import FAITH_SHA256, P1_SHA256, P1_SYSTEM, REF_SHA25613from lib.replay import ReplayModel14from lib.testset import load_items1516RECORDING = "assistant-baseline"17k = ReplayModel(RECORDING, P1_SHA256).manifest["k"] # the baseline's top k, as in retrieval-path18assistant = Assistant(RECORDING, P1_SYSTEM, P1_SHA256, k=k) # its retriever only19replies = ReplayModel(RECORDING, P1_SHA256) # the baseline's replies, sample 0, made from prompt P120faith = ReplayModel("judge-faithfulness-baseline", FAITH_SHA256)21ids = section_ids_by_version()22VERDICT = re.compile(r"^VERDICT:\s*(SUPPORTED|UNSUPPORTED)$")232425def listed(item):26 """The item's supporting section IDs in its asked version."""27 return frozenset(s.section_id for s in item.supporting_sections if s.version == item.version)282930dev = load_items(split="dev")31verdicts, unreadable = readable_verdicts("judge-answers-baseline", [item.id for item in dev], REF_SHA256)32for item_id, first in unreadable:33 print(f'unreadable verdict, left out: {item_id} ("{first}")')34fails = [item for item in dev if verdicts.get(item.id) == "FAIL" and listed(item) & {s.section_id for s in assistant.sections(item)}]35declined = [item for item in fails if parse_reply(replies.reply(item.id, 0)).declined]36answered = [item for item in fails if item not in declined]37print(f"right section in the top {k}, FAIL, declined: {len(declined)}")38print(f"right section in the top {k}, FAIL, answered: {len(answered)}")39print(f"answered FAIL with the section, citing a listed section: "40 f"{sum('supported' in citation_outcomes(parse_reply(replies.reply(item.id, 0)), item.version, listed(item), ids) for item in answered)}")41judged = {} # item id -> SUPPORTED, UNSUPPORTED or unreadable, for each answered fail42for item in answered:43 line = next((ln.strip().strip("*`").strip() for ln in faith.reply(item.id, 0).splitlines() if ln.strip()), "")44 match = VERDICT.match(line)45 judged[item.id] = match.group(1) if match else "unreadable"46print(f"answered FAIL with the section, faithfulness SUPPORTED: {sum(v == 'SUPPORTED' for v in judged.values())}")47print(f"answered FAIL with the section, faithfulness UNSUPPORTED: {sum(v == 'UNSUPPORTED' for v in judged.values())}")48print(" " + (", ".join(i for i, v in judged.items() if v == "UNSUPPORTED") or "none"))49print(f"answered FAIL with the section, faithfulness unreadable: {sum(v == 'unreadable' for v in judged.values())}")
python fail-with-section.pyunreadable verdict, left out: q-0043 ("VERDICT: PARTIAL")
right section in the top 3, FAIL, declined: 5
right section in the top 3, FAIL, answered: 5
answered FAIL with the section, citing a listed section: 5
answered FAIL with the section, faithfulness SUPPORTED: 4
answered FAIL with the section, faithfulness UNSUPPORTED: 1
q-0029
answered FAIL with the section, faithfulness unreadable: 0
De los fallos con respuesta, 5 citan una sección que el elemento enumera. El juez de fidelidad aprueba 4 de ellos y marca 1 como no respaldados, que es q-0029. Los recuentos aquí no muestran si las negativas incorrectas, los fallos de versión o los errores del juez de respuestas explican el resto. Leer las respuestas sí puede mostrarlo.
Un veredicto dice PARTIAL, ni PASS ni FAIL. El veredicto del juez sobre q-0043 es PARTIAL, por lo que la tabla lo deja fuera. Un veredicto ilegible nunca se cuenta como fallo.
Regla práctica: Trata la recuperación como un filtro para los aprobados y como una pista para los fallos. Un aprobado sin la sección de apoyo necesita una explicación, y un fallo con ella apunta a la respuesta.
Dónde continúan los arneses de agentes
Cuando una tarea requiere varios pasos, cada uno puede llamar a una herramienta y cambiar lo que ve el paso siguiente. El resultado puede ser correcto aunque un paso intermedio haya fallado, así que el recuento debe hacerse sobre todo el camino. Este libro evalúa una recuperación y una respuesta, de modo que su recuento de caminos es un sí o un no por elemento. La sección sobre una tarea que cuenta a través de un camino en Agent Harnesses explica cómo evaluar ejecuciones de ese tipo, y este capítulo no la repite.
Regla práctica: En este libro el camino es una recuperación y una respuesta, así que lee el recuento de recuperaciones junto al veredicto de cada elemento.
La calidad de la recuperación pertenece a otro libro
Qué tan bien ordena la recuperación las secciones, y cuánto del contexto llena, es una cuestión de ranking, y pertenece a A Primer on Search Relevance. Su sección sobre elegir una métrica de ranking trata el recall at k, el mean reciprocal rank y el nDCG, y cómo elegir entre ellos. Medir el contexto trata el contexto que recibe un modelo. Lee ambas antes de elegir una métrica para este asistente.
El conteo de la ruta de recuperación hace una pregunta sobre cada elemento: ¿está en el top k una sección de apoyo de la versión consultada? Devuelve sí o no, así que no es una métrica de ranking. No puede decir qué tan abajo en la lista está esa sección, y para eso sirve una métrica de ranking. Su k se lee del manifiesto de la línea base y no se elige en este capítulo, así que un cambio en k mueve la tabla, y la tabla hay que volver a leerla.
En conjunto, las cuatro comprobaciones dicen que una tasa de aprobados en este asistente oculta tres maneras distintas de equivocarse. La respuesta puede citar lo incorrecto, afirmar lo que ninguna sección dice o responder para la versión equivocada. Cada una necesita su propio conteo, su propio denominador y su propia palabra para lo que encontró. Las decisiones que se siguen de los resultados son estas:
- Cada respuesta se revisa en citas, fidelidad y versión, y cada comprobación mantiene su propio conteo.
- Cada tasa de fidelidad se imprime como no calibrada hasta que alguien contraste el juez con personas.
- Los elementos que dependen de la versión mantienen su propio conteo junto a la tasa de aprobados, y su propia comprobación de versión.
- La recuperación es una puerta para los aprobados y una pista para los fallos. Un aprobado cuya sección no fue recuperada se lee antes de contarse como fundamentado.
Regla práctica: Antes de dar por fundamentada una respuesta, lee su cita, sus afirmaciones y su versión, y lee la recuperación que la precedió.
Este capítulo, en esta edición
Edición 2026.11.3Ejemplos verificados el 21 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.3.