Verificación de citas: detén las citas alucinadas
💡 Resumen en una frase: usa Jev para establecer una línea de verificación de citas con IA — la coincidencia de cadenas detiene las citas inventadas, una pregunta Choice determina si el contexto respalda la afirmación, y los veredictos de baja confianza se derivan automáticamente a revisión humana.
A los LLM les gusta acompañar sus respuestas con citas: cada afirmación viene con un fragmento del documento fuente y, además, la frase de la cita en que se basa. Pero algunas son incorrectas, o incluso inventadas: la cita puede no estar en absoluto en el documento; o puede estar palabra por palabra en el documento mientras su contexto dice algo completamente distinto.
Lo tedioso que es verificar manualmente una cita queda claro en los tres pasos que enumera el cookbook oficial: encontrar el documento, encontrar la cita dentro del documento y luego leer suficiente contexto para juzgar si sostiene la afirmación. Si una sola ya es así, ¿qué pasa con 8, 80 o 800 citas?
La solución automatizada de este cookbook oficial (Double-checking citations) son dos filtros: primero, una coincidencia de cadenas común para encontrar citas que «no están en el texto original» — estas son inventadas (fabricated) y el modelo ni siquiera entra en juego; las citas que sobreviven pasan por una pregunta Choice que lee el contexto y determina su relación con la afirmación.
La lección anterior Barandillas para LLM detenía «lo que no debía decirse»; esta detiene «lo que no debía citarse» — la misma idea de «probabilidad + umbral + bifurcación en código», pero esta vez lo que se custodia es «si cada afirmación tiene una fuente». Esta lección dura unos 12 minutos y te lleva a recorrerla completa con el paquete de datos oficial: el documento fuente es el RFC 7519 (JSON Web Token, mayo de 2015, mes 5), y las 8 citas fueron escritas por un LLM a partir de él — 4 correctas y 4 alteradas por el equipo oficial, todas contrastadas con las cifras publicadas oficialmente (jev-1.12, muestreo de 2026-08-16).
Una cita (claim + quote + section)
│
▼
Filtro 1: coincidencia de cadenas — ¿está la cita en el documento fuente?
│ │
No encontrada Encontrada (se registra la sección) / solo señala la sección
│ │
▼ ▼
fabricated Filtro 2: una pregunta Choice
(inventada, cero peticiones) ¿Qué relación hay entre el contexto y la afirmación?
supports → verified
contradicts → contradicted
says_nothing → unsupported
│
▼
confidence ≥ 0.8 → el veredicto entra en vigor
confidence < 0.8 → confirmación humanaQué podrás hacer al terminar
- Clasificar automáticamente cada cita de la salida de la IA en una de cuatro categorías: verified pasa, fabricated / contradicted se rechaza, unsupported se deriva a revisión humana
- Detener primero, con coste cero de API mediante coincidencia de cadenas, las citas alucinadas que «no están en absoluto en el texto original»
- Usar una pregunta Choice para leer el contexto de la cita y determinar si supports / contradicts / says_nothing respecto a la afirmación
- Bifurcar automáticamente según el umbral de confidence: los veredictos de alta confianza entran en vigor directamente, los de baja confianza pasan a la cola humana (punto de partida oficial 0.8)
Por qué usar Jev en lugar de verificar cita por cita a mano
| Capacidad | Verificación manual cita por cita | Verificación de citas con Jev |
|---|---|---|
| Tiempo por cita | ❌ Encontrar el documento, encontrar la cita, leer suficiente contexto, una por una | ✅ Medido con la caché oficial: 0.08–0.25 segundos por veredicto |
| Criterio del veredicto | ❌ Varía según la persona y el momento; «el original no lo menciona» y «el original dice lo contrario» suelen mezclarse en un mismo nivel | ✅ Las tres relaciones se definen en los criteria y se pliegan en cuatro veredictos fijos |
| Citas inventadas | ❌ Hay que llegar primero al punto correspondiente del original para detectarlas | ✅ La coincidencia de cadenas las detiene primero, sin enviar ni una petición |
| Cómo expresar el grado de certeza | ❌ «Parece que no hay problema» — no puede entrar en el flujo | ✅ Probabilidad calibrada + confidence; por debajo de 0.8 se deriva automáticamente a revisión humana |
| Procesamiento por lotes y auditoría | ❌ Los registros de verificación se quedan en la cabeza o en el historial de chat | ✅ Cada veredicto incluye probabilidad, confianza y número de tokens; se puede archivar y reproducir |
Tu situación actual
- «Las citas del informe escrito por IA parecen cada vez más reales; no puedo ir revisando el original de cada una, ¿verdad? — pero la última vez se me coló justamente una inventada»
- «Más siniestra aún es esa clase de cita: está literalmente en el original, palabra por palabra, pero su contexto dice lo contrario; a simple vista no se nota en absoluto»
- «Quiero verificar en lote, pero no me atrevo a poner otro LLM de árbitro — cuando se equivoca, se ve igual que cuando una cita es una alucinación»
Cuándo usar esta técnica
Cuando necesitas:
- Hacer control de calidad en lote de «salidas de IA con citas», como QA de preguntas y respuestas RAG, asistentes de escritura con IA o revisiones de literatura
- Clasificar cada cita en una de cuatro categorías, cada una con su propio tratamiento: dejar pasar, rechazar, derivar a revisión humana
- Detener a coste cero las citas inventadas y tener respaldo humano para los veredictos de baja confianza
Y no quieres:
- Revisar manualmente cita por cita buscando en el original y leyendo contexto
- Que el resultado de la verificación sea otra vez texto libre que no puede entrar en el flujo
- Que una cita que cita texto real para decir algo falso supere el control de calidad y llegue al documento final
🎒 Preparativos antes de empezar
- Completaste Choice: preguntas de opción: sabes que criteria es un mapa de opciones y que la respuesta trae probabilities y confidence—toda la línea de decisión de esta página depende de una sola pregunta Choice
- (Opcional pero recomendado) Leíste Confidence nivel de confianza: de los tres usos, «confianza baja pasa a revisión humana» es justo la idea del umbral AUTO_ACCEPT de esta página
- Completaste instalación y primera solicitud:
.venvcontienetypesafe-sdkyTYPESAFE_API_KEYya está en las variables de entorno - Sabes que el paquete de datos oficial incluye caché de resultados: al reejecutar se reproducen los números publicados y no se envían solicitudes; solo se hacen llamadas reales tras borrar la caché (7 veces—la cita n.º 8 queda descartada ya en el paso de coincidencia de cadenas). La facturación es por tokens de entrada, la salida es gratuita; las tarifas están en modelos y precios
Hazlo conmigo
Paso 1: consigue el paquete de datos oficial (RFC 7519 + 8 citas + caché de resultados)
Por qué: para verificar citas hacen falta documentos reales y citas reales. El cookbook oficial tiene las tres cosas listas: rfc7519.txt (el texto original de la RFC 7519, descargado de rfc-editor.org), citations.json (8 citas escritas por un LLM a partir de la RFC—4 exactas, 4 manipuladas por los autores oficiales y condenadas a fallar) y json_cache.json (la caché de resultados generada oficialmente). Todo está en el directorio cookbooks/citation_check del repositorio typesafe-public-examples.
En el directorio donde completaste la lección de instalación (donde está .venv) descarga los tres archivos y luego instala los dos paquetes que usa el notebook oficial:
curl -sfLO https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/citation_check/rfc7519.txt
curl -sfLO https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/citation_check/citations.json
curl -sfLO https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/citation_check/json_cache.json
.venv/bin/pip install ipython 'cooksafe>=0.2.0,<0.3.0'Después crea el script principal de esta lección, citation_check.py, y escribe primero el esqueleto (el cliente y la caché provienen literalmente del cookbook oficial):
# citation_check.py —— 引用核查:拦住幻觉引文
# 依赖:.venv 里已有 typesafe-sdk(安装课装过),本课另装 ipython 和 cooksafe
import json
import os
import re
from pathlib import Path
from time import perf_counter
from cooksafe import JsonCache
from typesafe_sdk import Choice, TypeSafeClient
# 官方 cookbook 锁定的版本:本页核对的所有数字出自 jev-1.12(2026-08-16 采样)。
# 阈值是对着具体版本调的——jev-latest 别名会随新版本漂移,调过阈值的系统要锁版本 ID。
TYPESAFE_MODEL = "jev-1.12"
AUTO_ACCEPT = 0.8 # 官方注释:起步设高,多转人工;对模型的信任建立起来再往下调
client = TypeSafeClient(
api_key=os.environ.get("TYPESAFE_API_KEY", "cache-only"),
base_url=os.environ.get("TYPESAFE_ENDPOINT"),
timeout=120.0,
)
json_cache = JsonCache(Path("json_cache.json"))Comprueba que todos los archivos estén en su sitio:
.venv/bin/python -c "from pathlib import Path; import json; print(Path('rfc7519.txt').stat().st_size, 'bytes'); print(len(json.loads(Path('citations.json').read_text())), 'citations')"Deberías ver:
63039 bytes
8 citationsUn detalle considerado: los autores oficiales pusieron el valor por defecto de api_key como "cache-only"—mientras exista json_cache.json, reejecutar reproduce los números oficiales de principio a fin sin enviar ni una sola solicitud, así que puedes completar toda esta lección sin API Key por ahora; la Key solo es obligatoria cuando borres el archivo de caché y hagas llamadas reales.
- Los tres archivos se descargaron correctamente y el comando anterior imprime
63039 bytesy8 citations
Paso 2: carga el documento fuente y córtalo en secciones numeradas
Por qué: el modelo no debería leer una RFC entera de 58k caracteres. El enfoque oficial: load_source() primero elimina el encabezado y pie de cada página (si no, trocearía los párrafos), split_sections() luego corta por títulos de secciones numeradas en 45 secciones; después, cada cita envía al state solo la sección donde se encuentra. «Un state grande lleno de detalles irrelevantes» es una trampa conocida de Jev—este paso precisamente deja esos detalles fuera desde el principio.
Continúa escribiendo en citation_check.py (las funciones de análisis provienen literalmente del cookbook oficial):
def load_source() -> str:
"""RFC 7519 verbatim, minus the page headers and footers that interrupt its paragraphs."""
lines = []
for line in Path("rfc7519.txt").read_text().splitlines():
bare = line.lstrip("\f")
if re.match(r"Jones, et al\.\s.*\[Page \d+\]$", bare):
continue
if re.match(r"RFC 7519\s+JSON Web Token \(JWT\)\s+May 2015$", bare):
continue
lines.append(bare)
return re.sub(r"\n{3,}", "\n\n", "\n".join(lines))
def split_sections(source: str) -> dict[str, str]:
"""Map each numbered section ("4.1.3") to its text, split on the RFC's header lines."""
boundary = re.compile(r"(?m)^(?:(\d+(?:\.\d+)*)\. .+|Appendix [A-Z]\..*)$")
marks = list(boundary.finditer(source))
sections = {}
for mark, nxt in zip(marks, marks[1:] + [None]):
if mark.group(1) is None: # an appendix header only terminates the section before it
continue
sections[mark.group(1)] = source[mark.start() : nxt.start() if nxt else len(source)].strip()
return sections
SOURCE = load_source()
SECTIONS = split_sections(SOURCE)
CITATIONS = json.loads(Path("citations.json").read_text())Mira cómo se ven el resultado de la carga y las citas:
.venv/bin/python -c "from citation_check import SOURCE, SECTIONS, CITATIONS; print(f'{len(SOURCE):,} characters, {len(SECTIONS)} numbered sections, {len(CITATIONS)} citations')"Deberías ver:
58,365 characters, 45 numbered sections, 8 citationsAhora mira dos citas (una con cita textual y otra que solo indica la sección):
.venv/bin/python -c "import json; from citation_check import CITATIONS; print(json.dumps(CITATIONS[1], indent=2)); print(json.dumps(next(c for c in CITATIONS if c['quote'] is None), indent=2))"Deberías ver:
{
"id": "aud_reject",
"claim": "If a validator does not find itself in a token's audience list, it has to reject the token.",
"quote": "If the principal processing the claim does not identify itself with a value in the \"aud\" claim when this claim is present, then the JWT MUST be rejected.",
"section": "4.1.3"
}
{
"id": "iat_future",
"claim": "The \"iat\" claim requires validators to reject tokens whose issue time is in the future.",
"quote": null,
"section": "4.1.6"
}Cada cita tiene cuatro campos: id (el identificador que le diste), claim (la afirmación que aparece en la salida de la IA), quote (el fragmento del original que cita) y section (el número de sección). quote igual a null significa «solo indicó la sección, no dio cita»—no hay cadena que coincidir, así que se envía directamente al modelo la sección señalada.
- Ambas impresiones coinciden:
58,365 characters, 45 numbered sections, 8 citations, además deaud_reject(con quote) yiat_future(quote igual a null)
Paso 3: la coincidencia de cadenas intercepta primero las citas que «no están en el original»
Por qué: si una cita no está en el documento, está inventada—para esto no hace falta un modelo, basta una coincidencia de cadenas normal, sin enviar ni una llamada a la API. Antes de coincidir se normaliza: el texto de la RFC se quiebra en líneas de unos 72 caracteres, así que una cita con saltos de línea tal cual no coincidiría; al plegar los espacios en blanco en un solo espacio y las comillas curvas en comillas rectas, también coinciden las citas que cruzan líneas.
Sigue escribiendo (literalmente del cookbook oficial):
def normalize(text: str) -> str:
"""Collapse whitespace and fold curly quotes, so a quote matches across line wraps."""
table = str.maketrans({"“": '"', "”": '"', "‘": "'", "’": "'"})
return re.sub(r"\s+", " ", text.translate(table)).strip()
def find_quote(sections: dict[str, str], quote: str) -> str | None:
"""The number of the section that contains the quote verbatim, or None."""
needle = normalize(quote)
for number in sorted(sections, key=lambda n: [int(p) for p in n.split(".")]):
if needle in normalize(sections[number]):
return number
return None
def locate(sections: dict[str, str], citation: dict) -> tuple[str, str | None]:
"""Step 1 for one citation: a status, plus the section step 2 will read."""
if citation["quote"] is None:
return "section-only", sections[citation["section"]]
number = find_quote(sections, citation["quote"])
if number is None:
return "missing", None
return "found", sections[number]locate() devuelve dos cosas: un estado (found encontrada / missing no encontrada / section-only solo indica sección) y el texto de la sección que se enviará al modelo en el siguiente paso. Crea locate_report.py para ver el resultado de la coincidencia de las 8 citas:
# locate_report.py —— 第 3 步检查:8 条引文的字符串匹配结果
from citation_check import CITATIONS, SECTIONS, locate
for citation in CITATIONS:
status, section = locate(SECTIONS, citation)
where = f"section of {len(section):,} chars" if section else "not in the source"
print(f"{citation['id']:<18}{status:<14}{where}").venv/bin/python locate_report.pyDeberías ver (los números publicados oficialmente):
epoch_seconds found section of 3,122 chars
aud_reject found section of 761 chars
sig_reporting missing not in the source
clock_skew found section of 529 chars
exp_required found section of 529 chars
pii_encryption found section of 1,653 chars
iat_future section-only section of 270 chars
duplicate_names found section of 918 charssig_reporting queda descartada aquí mismo: su «cita» no existe en la RFC—la licencia de datos oficial (DATA_LICENSE.md) también deja claro que ese quote lo escribieron ellos, no es texto de la RFC. Después no se gastará ninguna solicitud más en ella. iat_future es de otro tipo: solo indicó la sección 4.1.6 sin dar cita, no hay cadena que coincidir, así que se toma esa sección y se sigue adelante.
- De las 8 filas de estado hay una
missing(sig_reporting), unasection-only(iat_future) y las 6 filas restantes sonfound
Paso 4: usa una pregunta Choice para juzgar si el contexto respalda la afirmación
Por qué: las citas que llegan a este paso están literalmente en el original—pero eso no basta: aunque la cita sea exacta, la afirmación construida sobre ella puede seguir estando mal. Para juzgarlo hay que leer el contexto de la cita (la sección encontrada en el paso 3). El enfoque oficial usa una sola pregunta Choice que cubre las tres relaciones entre sección y afirmación; la opción con mayor probabilidad es el veredicto, con confidence ≥ 0.8 el veredicto se aplica directamente, y por debajo de 0.8 pasa a confirmación humana.
Sigue escribiendo (la definición de la pregunta y el plegado del veredicto provienen literalmente del cookbook oficial):
QUESTIONS = {
"relation": Choice(
instructions="How does the section relate to the claim?",
criteria={
"supports": "The section states the claim or directly implies that it is true",
"contradicts": "The section states the opposite of the claim or implies it is false",
"says_nothing": "The section does not address what the claim asserts, either way",
},
),
}
RELATION_TO_VERDICT = {
"supports": "verified",
"contradicts": "contradicted",
"says_nothing": "unsupported",
}
@json_cache
def ask(claim: str, section: str) -> dict:
started = perf_counter()
response = client.system_one(
state={"claim": claim, "section": section},
questions=QUESTIONS,
model=TYPESAFE_MODEL,
)
answer = response.answers["relation"]
return {
"choice": answer.choice,
"probabilities": answer.probabilities,
"confidence": answer.confidence,
"seconds": round(perf_counter() - started, 2),
"input_tokens": response.usage.input_tokens or 0,
"output_tokens": response.usage.output_tokens or 0,
}
def verdict(status: str, answer: dict | None) -> dict:
"""Fold step 1 and step 2 into one of the four labels, plus an auto-or-review flag."""
if status == "missing":
# confidence None: no model was called, so there is no model confidence to report
return {"verdict": "fabricated", "confidence": None, "auto": True}
return {
"verdict": RELATION_TO_VERDICT[answer["choice"]],
"confidence": answer["confidence"],
"auto": answer["confidence"] >= AUTO_ACCEPT,
}
def check_citation(sections: dict[str, str], citation: dict) -> dict:
status, section = locate(sections, citation)
answer = ask(citation["claim"], section) if section is not None else None
return {"id": citation["id"], "status": status, "answer": answer, **verdict(status, answer)}Hay tres decisiones de diseño que conviene vigilar:
- El state solo tiene dos cosas:
claimysection. El trabajo de «qué fragmento leer» ya lo hizo el paso 3, así que el modelo recibe material de juicio limpio. - El decorador
@json_cache: si la caché acierta, reproduce los números oficiales sin llamar a la API; solo se envían solicitudes reales para lo que no está en la caché. - Cómo se pliegan los cuatro veredictos:
missing→fabricated(confidence se registra comoNone—no se llamó al modelo, no hay confianza de modelo que reportar); el resto se mapea conRELATION_TO_VERDICTa verified / contradicted / unsupported, y la marcaautola decide AUTO_ACCEPT.
💡 Este es el valor único de Jev
«La cita está literalmente en el original» no equivale a «la afirmación es válida». La cita de exp_required está copiada sin falta de la sección 4.1.4, y la afirmación dice que «todo JWT debe llevar exp, y un token sin exp es inválido»—cuando esa misma sección dice "Use of this claim is OPTIONAL". En la distribución de probabilidades, contradicts=1.0 y confidence 0.99; con una sola pasada se intercepta este caso de «citar texto real para decir lo contrario». El veredicto es un campo estructurado + probabilidad calibrada, y el código lo enruta directamente; si en lugar de eso le pidieras a un modelo generativo escribir una «opinión de verificación», tendrías que analizar texto, sin contar con que él mismo también alucina.
💡 Atención con contenido en chino
La nota oficial dice: el inglés es el idioma principal de entrenamiento de Jev; otros idiomas, incluido el chino, funcionan pero con menor exactitud. Antes de hacer verificación de citas con documentos y afirmaciones en chino, o de traducir las preguntas al chino, corre primero un lote con tus propios datos reales y fíjate en la distribución de probabilidades y en confidence antes de fijar el umbral.
Deberías ver: este paso no produce salida; deja el código escrito de momento—el siguiente paso lo ejecuta todo.
Paso 5: ejecuta la verificación de citas con IA en lote y mira a quién intercepta cada uno de los cuatro veredictos
Por qué: cada cita se mira por su lógica, y el total muestra el resultado. Los oficiales repasaron las 8 citas una por una: las 4 correctas resultaron todas verified (confidence por encima de 0.93), y las 4 manipuladas fueron todas interceptadas: 1 fabricated, 1 contradicted, 2 unsupported remitidas a revisión manual.
Para cerrar citation_check.py, añade el programa principal:
if __name__ == "__main__":
print(f"{'citation':<18}{'quote':<14}{'relation':<14}{'conf':>6} {'verdict':<13}{'action':>7}")
for citation in CITATIONS:
result = check_citation(SECTIONS, citation)
answer = result["answer"]
relation = answer["choice"] if answer else "-"
conf = f"{answer['confidence']:.2f}" if answer else "-"
action = "auto" if result["auto"] else "review"
print(
f"{result['id']:<18}{result['status']:<14}{relation:<14}{conf:>6}"
f" {result['verdict']:<13}{action:>7}"
)Ejecuta (con el archivo de caché presente, reproduce los números oficiales sin enviar peticiones; solo borrando la caché se hacen las 7 llamadas reales):
.venv/bin/python citation_check.pyDeberías ver (números publicados oficialmente, jev-1.12, muestreo 2026-08-16; tras borrar el archivo de caché son llamadas reales):
citation quote relation conf verdict action
epoch_seconds found supports 0.93 verified auto
aud_reject found supports 0.95 verified auto
sig_reporting missing - - fabricated auto
clock_skew found supports 0.99 verified auto
exp_required found contradicts 0.99 contradicted auto
pii_encryption found says_nothing 0.27 unsupported review
iat_future section-only says_nothing 0.56 unsupported review
duplicate_names found supports 0.99 verified autoLeyendo esta tabla línea por línea, cuatro detalles fueron dispuestos deliberadamente por los oficiales:
- Las 4 citas correctas resultaron todas verified:
epoch_seconds,aud_reject,clock_skew,duplicate_names, con confidence por encima de 0.93, muy por encima del umbral de 0.8. sig_reportingno gastó ni una sola petición: el quote no está en el RFC, y el paso de coincidencia de cadenas ya lo declaró fabricated, sin llegar siquiera al modelo.exp_requiredes un caso de «citar texto real para decir lo contrario»: la cita está tomada palabra por palabra de 4.1.4, pero la misma sección dice "Use of this claim is OPTIONAL": contradicts 1.0, confidence 0.99.pii_encryptionyiat_futureentraron en la cola de revisión manual: says_nothing y con confidence de solo 0.27 y 0.56, ambas por debajo de 0.8.pii_encryptiones precisamente el ejemplo oficial de que «la coincidencia de cadenas por sí sola no basta»: la cita está palabra por palabra en el texto original, pero la sección 3 donde se encuentra no se pronuncia sobre la afirmación de que «es obligatorio cifrar».
Un último vistazo al coste: las 7 llamadas al modelo registradas en la caché, de 0.08–0.25 segundos cada una, suman 4,420 tokens de entrada y 281 de salida; la salida es gratuita; la entrada, según la tarifa vigente de $0.042/Mtok (vermodelos y precios), equivale a unos $0.0002 por esta ronda completa de verificación.
- En la tabla que obtuve aparecen los cuatro veredictos: verified / fabricated / contradicted / unsupported
- Las dos unsupported llevan ambas la marca
review, el resto sonauto
📋 Prompt mágico
El «Prompt» de esta página es la plantilla de pregunta y veredicto para la API: cópiala, sustituye los marcadores 【】 (los que llevan ? son opcionales) y ya se puede usar.
📝 Pregunta Choice sobre la relación de una cita (veredicto de tres opciones)
Efecto esperado: convertir «qué relación hay entre este contexto y esta afirmación» en una pregunta Choice fija de tres opciones, con el criterio de veredicto fijado en criteria.
from typesafe_sdk import Choice
QUESTIONS = {
"relation": Choice(
instructions="【一句话问上下文与论断的关系,官方原文:How does the section relate to the claim?】",
criteria={
"supports": "【什么算支持:章节陈述了论断,或直接暗示它为真】",
"contradicts": "【什么算相抵触:章节说的是论断的反面,或暗示它为假】",
"says_nothing": "【什么算没提到:章节对论断的断言不置可否】",
},
),
}
# 必填项:三个选项的方向要正——supports = 引文真的撑得住论断
# 选填项:需要更多判定档位(如「部分支持」)就加选项;选项数变了 confidence 的读法也跟着变?
# 输出规范:answer.choice → 最高概率选项;answer.probabilities → 每个选项的概率;answer.confidence → 0–1
# 约束条件:
# ✅ 选项定义写成可对照的情境,边界情形放进 criteria
# ❌ 不要只给 supports / not_supports 两档——「原文说了相反的话」和「原文没提」必须分开处理✅ Plegado de los cuatro veredictos + umbral de remisión a revisión manual
Efecto esperado: plegar el resultado de la coincidencia de cadenas y el veredicto del modelo en verified / unsupported / contradicted / fabricated, con remisión automática a revisión manual en caso de confianza baja.
AUTO_ACCEPT = 【0.8】 # 官方起点:先高后低,低于它就转人工
RELATION_TO_VERDICT = {
"supports": "verified",
"contradicts": "contradicted",
"says_nothing": "unsupported",
}
def verdict(status: str, answer: dict | None) -> dict:
"""status: missing / found / section-only(字符串匹配那步的输出)"""
if status == "missing":
return {"verdict": "fabricated", "confidence": None, "auto": True} # 没调模型,confidence 记 None
return {
"verdict": RELATION_TO_VERDICT[answer["choice"]],
"confidence": answer["confidence"],
"auto": answer["confidence"] >= AUTO_ACCEPT,
}
# 必填项:AUTO_ACCEPT 用你自己文档上跑出的分布定,0.8 只是官方起点
# 选填项:想更严可以给 contradicted 单独设一条更低的转人工线?
# 输出规范:{"verdict": "verified|unsupported|contradicted|fabricated", "confidence": float|None, "auto": bool}
# 约束条件:
# ✅ auto=False 的一律进人工队列——官方就是这么处理 pii_encryption(0.27)和 iat_future(0.56)的
# ❌ 不要拿 confidence 改判定本身——它只决定「谁来看」,不决定「是什么」🔧 citations.json: cámbialo por tus propios documentos y citas
Efecto esperado: apuntar la verificación a tu propio producto de RAG / escritura: cambia los documentos fuente y la lista de citas, sin tocar ni una línea del pipeline de veredictos.
[
{
"id": "【引文 id,用你产品里的引文主键,判定结果好回写】",
"claim": "【AI 输出里的那句论断,原文照抄】",
"quote": "【它引用的原文片段;只指章节不给引文时填 null】",
"section": "【章节号,如 4.1.4;quote 为 null 时必填,模型读这一节】"
}
]- Campos obligatorios:
claim+quote(oquote: nulljunto consection) - Campos opcionales:
idusa la clave primaria del producto, para facilitar la reescritura del veredicto en el documento original? - Especificación de salida: cada cita → uno de los cuatro veredictos + confidence + marca auto
- Condiciones de restricción:
- ✅
quotecopia palabra por palabra el documento fuente: la coincidencia oficial es una coincidenciaexacta tras normalización - ❌ No cuentes con que tolere citas «más o menos»: un quote truncado o reescrito no cuenta como found y se declara fabricated; para tolerar citas descuidadas en producción hay que cambiar a coincidencia difusa (palabras textuales oficiales)
- ✅
Punto de control ✅
citation_check.pyproduce una tabla de veredictos de 8 filas, con los cuatro veredictos verified / fabricated / contradicted / unsupported presentes- Puedo explicar por qué
sig_reportingfue declarado fabricated sin gastar ni una petición: la coincidencia de cadenas no encontró esa «cita» en el RFC - Sé que la cita de
exp_requiredestá palabra por palabra en 4.1.4, y por qué el veredicto es contradicted: la misma sección dice "Use of this claim is OPTIONAL" - Sé por qué
pii_encryption(0.27) yiat_future(0.56) entraron en la cola de revisión manual: ambos por debajo del 0.8 de AUTO_ACCEPT - Sé que los números oficiales provienen de jev-1.12 (muestreo 2026-08-16): si el archivo de caché está presente se reproduce esa versión, y solo al borrarlo se envían peticiones reales
Avisos de errores comunes
❌ Creer que «la cita está en el texto original» equivale a «la afirmación se sostiene»
pii_encryption es el contraejemplo dispuesto por los oficiales: su cita está palabra por palabra en la sección 3 del RFC y la coincidencia de cadenas da sin duda found; pero esa sección trata de la estructura del JWT (claims codificados en JWS/JWE) y no se pronuncia sobre la afirmación de que «los datos personales deben cifrarse», así que el modelo dictaminó says_nothing con una confidence de solo 0.27. La coincidencia de cadenas solo puede interceptar lo «inventado», no lo de «citar texto real para decir algo falso»: por eso existe la pregunta Choice del paso 4.
❌ Usar la coincidencia exacta como si fuera difusa
Dicho con las palabras oficiales: la coincidencia tras la normalización es exacta — si una cita se trunca, o se reescribe ligeramente una sola palabra, el resultado es missing → fabricated. Si tu sistema debe tolerar citas descuidadas, hay que cambiar a coincidencia difusa. Antes de lanzar, piénsalo bien: cómo se generan las «citas» en tu producto, y con qué frecuencia se truncan o reescriben.
❌ Clasificar solo en dos niveles «pasa / no pasa»
Cada uno de los cuatro veredictos tiene su destino: verified pasa directamente; fabricated y contradicted se devuelven para reescribir: uno es inventado y el otro es el texto original diciendo lo contrario; unsupported según el caso: quizá haya que añadir la fuente, o quizá haya que cambiar la propia afirmación. Comprimido en dos niveles, el flujo posterior solo puede aplicar un corte uniforme, y exp_required (el texto original dice lo contrario) y pii_encryption (el texto original no lo dice) serían tratados igual.
❌ Fijar el umbral y no volver a revisarlo
El comentario oficial lo deja claro: AUTO_ACCEPT = 0.8 es el punto de partida de «empezar alto y remitir más a revisión manual»; ejecuta un tiempo, observa el rendimiento del modelo sobre tus propios documentos y luego bájalo. Además, que los oficiales fijen TYPESAFE_MODEL en jev-1.12 no es algo escrito al azar: el alias jev-latest deriva con las nuevas versiones, y un umbral ajustado sobre una versión antigua puede ser otra cosa al cambiar de versión (vermodelos y precios).
Técnicas avanzadas (opcional)
Pruébalo primero en el navegador (sin código). El cookbook oficial usa cooksafe con make_playground_link() para convertir el claim + section de exp_required y la pregunta en un enlace para compartir; al abrirlo se ejecuta la misma petición en Playground:
Abrir el ejemplo de playground de exp_required →
El código que genera el enlace es corto (se ejecuta en el notebook oficial; example y example_section se toman de la cita exp_required):
from cooksafe import make_playground_link
from IPython.display import Markdown, display
playground_link = make_playground_link(
{"claim": example["claim"], "section": example_section}, QUESTIONS
)Apunta a tus propios datos. El cierre oficial lo dice sin rodeos: basta con reemplazar rfc7519.txt y citations.json—pero load_source() y split_sections() están escritos según el formato de los RFC (quitar encabezados y pies, cortar por títulos de sección numerados); para documentos con otra estructura hay que escribir el propio analizador. Páginas web, PDF convertidos a texto, manuales en Markdown: la lógica para cortar «secciones» es distinta en cada caso, pero el principio «cada cita solo envía el fragmento donde se encuentra» no cambia.
Reproducción desde caché vs llamadas reales. Si json_cache.json existe, volver a ejecutar reproduce las cifras oficiales (api_key por defecto es "cache-only", se puede replicar incluso sin Key); si lo eliminas, las 7 llamadas reales se facturan por tokens de entrada y la salida es gratis. Si en tu proyecto también quieres «primero reproducir, luego ejecutar de verdad», el decorador JsonCache de cooksafe sirve exactamente para eso.
Resumen de la lección
✅ Dos compuertas para la verificación de citas con IA: la coincidencia de cadenas intercepta las citas que «no están en el texto original» (fabricated, coste cero de API); una pregunta Choice determina si el contexto respalda la afirmación.
✅ Cuatro veredictos, cada uno en su sitio: verified deja pasar, contradicted se rechaza (el texto original dice lo contrario), unsupported pasa a revisión humana (el texto original no lo menciona), fabricated se rechaza (la cita está inventada)—«citar texto real diciendo algo falso» y «el texto original no lo dice» se tratan por separado.
✅ Filtro por confidence: ≥ 0.8 el veredicto surte efecto; por debajo, pasa a revisión humana—de las 8 entradas oficiales, justo 2 (0.27, 0.56) acabaron en la cola humana.
✅ Prueba oficial: las 4 citas correctas, todas verified (0.93 o más); las 4 citas problemáticas, todas interceptadas; 7 llamadas al modelo suman unos 4.4k tokens de entrada, que según la tarifa vigente equivale a unos $0.0002.
Repaso de los campos de configuración clave:
| Campo | Valor en esta página | Descripción |
|---|---|---|
TYPESAFE_MODEL | jev-1.12 | El cookbook oficial fija la versión; los alias derivan, así que al ajustar umbrales hay que fijar el ID |
AUTO_ACCEPT | 0.8 | Línea donde el veredicto surte efecto; por debajo, revisión humana; empezar alto e ir bajando |
QUESTIONS["relation"] | Choice con tres opciones | supports / contradicts / says_nothing |
| Mapeo de veredictos | supports→verified, etc. | missing→fabricated sin pasar por el modelo, confidence se registra como None |
state | {"claim": …, "section": …} | El modelo solo lee la afirmación + la sección donde está; los detalles irrelevantes no entran en el contexto |
| Caché | json_cache.json | Reproduce las cifras oficiales; si se elimina, llamadas reales |
Tutoriales relacionados:
- Control de pasajes RAG: solo el contenido relevante entra en el contexto—el mismo enfoque de «una petición, un veredicto» aplicado a los pasajes recuperados; la próxima lección trata justo de eso
- Preguntas de opción Choice—la base del tipo de pregunta de la verificación de esta página
- Confidence: nivel de confianza—cómo se calcula confidence a partir de la distribución de probabilidades, tres niveles de uso y el umbral escalado según el riesgo
Avance de la próxima lección
La verificación de citas custodia «lo que se cita»; la próxima lección custodia «los pasajes que se meten en el contexto»: RAG: control de pasajes: solo contenido relevante entra en el contexto.
Aprenderás:
- Una petición por cada pasaje recuperado para puntuar su relevancia; el código decide qué pasajes entran en el answering model
- Usar Noul: preguntas de sí/no para asignar a cada pasaje una puntuación de probabilidad de 0–1—justo lo complementario al veredicto Choice de esta página
- Mantener los pasajes irrelevantes fuera del contexto, de modo que la calidad de las respuestas ya no deriva con la calidad de la recuperación