为你发现的失败编写代码检查

阅读约需 39分钟 分钟,9节中含5个示例。

版次 2026.11.3 示例于 2026年11月21日 通过 54个示例中有54个通过 变化内容

AI 翻译。由人工以英文核验。 我们如何制作图书

译自英文版图书,版次 2026.11.3。 阅读原文

读完本章,你能够编写在每条回复上免费运行的格式检查和引用检查,说明每项检查能看到、看不到第 2 章中的哪些失败,并指出两种标准的重叠度得分在哪些情形下会把错误答案排在正确答案之前。

第 2 章对 240 条开发集回复做了编码,三种变体各 80 条,并按每条回复的主要缺陷将其归入七种失败模式。其中一些模式会在回复文本中留下痕迹。引用提示从未给出的某一节是一例,回答文档并未涉及的问题也是一例。程序只需对照回复所对应的条目来阅读回复,就能发现这两种情形。另一些模式则没有程序可以读取的痕迹。一个答案可能对某一版本正确、对另一版本错误,而它的引用本身是对的,文本中也没有任何内容表明它指的是哪个版本。

如果团队只为自己看得见的痕迹编写检查,报告出的就是一次干净的运行,却会漏掉那些从未被检查的失败。本章按检查所能看到的内容对检查分类,构建能够用代码运行的那些检查,并说明每项检查遗漏了什么。本章所有数字背后的测试集有 80 个开发集条目和 40 个留出集条目。本章只读取开发集条目。留出集条目仅在一个示例中以计数的形式出现,其拒答率见第 10 章。

代码检查能看到什么

代码检查读取两样东西:回复的文本,以及题目自身的数据,其中包含参考答案和支持该答案的各节清单。它在每次运行时给出相同的结果,在新一批回复上重新运行也不产生任何成本。这是它的长处。它的局限在于,它读取的是形式和归属关系,而不是含义。它能判断一条回复有没有引用,所引用的 ID 是否出现在提示中,回复是否恰好就是拒答语句。但它无法判断所引用的节是否支持答案所说的内容。

下面是第 2 章列出的各种失败模式,以及代码检查对每一种所能看到的部分。

  • 过度拒答。 统计拒答语句的检查,只能发现使用该语句的拒答。换用其他措辞的拒答会被当作答案放行。q-0080 就是这样通过措辞检查的,见第 2 章。
  • 版本错误的答案。 检查可以看出每条引用是否属于所问的版本,但看不出论断是否与该版本的参考答案相符。
  • 错误答案。 代码看不到。论断是否正确,需要把论断与参考答案对照着读。
  • 漏掉的拒答。 检查可以要求每个无法回答的题目都给出拒答语句,而 answered-declined-expected 会在对此类题目给出任何答案时触发,不论该答案引用了什么。它依赖题目的标签,因此文档并未涵盖、但测试集却标为可回答的题目,会从它旁边漏过去。
  • 不完整的答案。 在本章中代码看不到。回复是否涵盖了整个问题,应由裁判依据评分细则的规定来判断。
  • 引用问题。 分两部分可见:引用了提示之外的内容,以及引用了题目未列出的节。第二部分需要由人来读,见关于支持关系的一节的说明。
  • 格式错误的回复。 部分可见。空回复、带有正文的拒答、没有引用的答案,以及各部分顺序错乱的回复,都可以查出。下一节中的顺序检查负责找出最后这一类。

工作准则: 只有当回复和题目本身已经包含检查所需的事实时,才为某种失败编写代码检查。对于证据就是论断本身的失败,应交给依据书面评分细则的裁判,如第 5 章所做的那样,而代码检查只用于该失败中可以直接读取的部分。

这部分尚未翻译,因此以英文显示。

Format checks

最近一次修改见于版次 2026.11.3

The format check asks whether a reply has the shape the prompt asks for, before anyone reads what it says. The function format_problems in lib/contract.py returns a sorted list of fixed names, one for each defect it finds. There are five. empty is a reply with no text. declined-with-text is a reply that contains the decline sentence along with other text. no-citation is an answer that cites nothing. unknown-section is a citation to a section the prompt didn't give. answered-declined-expected is an answer to an item that has to be declined. A second function, order_problems, reads the order of a reply's lines and returns two names: citation-first, for a reply whose first line opens with a citation, and stray-line, for a line that ends no sentence once its citations are taken out.

The format check reads the reply, the list of sections the prompt gave, and whether the item is unanswerable. The order check reads only the reply's lines. Neither reads what the answer says, so a correct answer and a wrong one with the same shape pass alike.

Run the format check on the baseline's reply to each item, and count each name, with the dev items and the held-out items kept apart.

format-problems-baseline.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pydantic 2.14.3 · typing-extensions 4.16.0 通过
"""Runs format_problems over the baseline replies to every item, and counts each problem by its fixed name.Dev and held-out items are counted apart, and held-out items appear only as counts. An item can have more than oneproblem, so the counts by name can add up to more than the number of items with a problem."""import lib  # first: fixes the thread counts and seeds before anything else loadsfrom collections import Counterfrom lib.answers import Assistantfrom lib.contract import PROBLEMS, format_problemsfrom lib.prompts import P1_SHA256, P1_SYSTEMfrom lib.stats import pctfrom lib.testset import load_itemsassistant = Assistant("assistant-baseline", P1_SYSTEM, P1_SHA256)assert len(load_items()) == 120  # the baseline recording holds one reply per item, so every item is countedfor split in ("dev", "held-out"):    items = load_items(split=split)    counts = Counter()    with_problem = 0    for item in items:        problems = format_problems(            assistant.reply(item),            context_ids=assistant.context_ids(item),            expect_decline=item.kind == "unanswerable",  # an unanswerable item must be declined        )        with_problem += bool(problems)        counts.update(problems)    print(f"{split} items: {len(items)}")    print(f"{split} items with a format problem: {pct(with_problem, len(items))}")    for name in PROBLEMS:  # the fixed names, in the order lib.contract lists them        print(f"{split} problem {name}: {counts[name]}")
输出python format-problems-baseline.py
dev 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

The baseline has no format problem on the dev items, 0.0% (0 of 80), or on the held-out items, 0.0% (0 of 40). A zero counts only if the check could have fired, and the next example shows that these checks do fire, on other recordings.

format-problems-variants.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pydantic 2.14.3 · typing-extensions 4.16.0 通过
"""Runs the format check and the order check over the unfiltered and second-model replies to the dev items. The baselinehas no problem of either kind (format-problems-baseline), so these two recordings are where the checks fire.Each name is also run once on a fixture reply built to break it, and the example stops if a name does not fire. A zeroon a real split then means the check found nothing, not that it could not fire. Held-out items are not read here."""import lib  # first: fixes the thread counts and seeds before anything else loadsfrom lib.answers import Assistantfrom lib.contract import ORDER_PROBLEMS, PROBLEMS, format_problems, order_problems, parse_replyfrom lib.prompts import P1_SHA256, P1_SYSTEMfrom lib.testset import load_itemsVARIANTS = (("unfiltered", "assistant-unfiltered"), ("second-model", "assistant-second-model"))FIXTURE_IDS = frozenset({"example-start"})  # the one section a fixture may citeFIXTURES = (  # name, reply text, whether the item must be declined    ("empty", "", False),    ("declined-with-text", "The docs don't say. [sec:example-start]", False),    ("no-citation", "Run svc start to start the service.", False),    ("unknown-section", "Run svc start to start the service. [sec:made-up]", False),    ("answered-declined-expected", "Run svc start to start the service. [sec:example-start]", True),    ("citation-first", "[sec:example-start] Start the service.\nRun svc start.", False),    ("stray-line", "Run `svc start` [sec:example-start]\nService", False),)items = load_items(split="dev")for label, recording in VARIANTS:    assistant = Assistant(recording, P1_SYSTEM, P1_SHA256)    found = {name: [] for name in (*PROBLEMS, *ORDER_PROBLEMS)}    for item in items:        reply = assistant.reply(item)        for name in format_problems(reply, context_ids=assistant.context_ids(item), expect_decline=item.kind == "unanswerable"):            found[name].append(item.id)        for name in order_problems(reply.text):            found[name].append(item.id)    for name, ids in found.items():        shown = f"{len(ids)} of {len(items)}" + (f" ({', '.join(ids)})" if ids else "")        print(f"{label} {name}: {shown}")for name, raw, must_decline in FIXTURES:    reply = parse_reply(raw)    fired = name in format_problems(reply, context_ids=FIXTURE_IDS, expect_decline=must_decline) or name in order_problems(reply.text)    assert fired, f"the fixture for {name} does not fire the check"    print(f"fixture {name}: fired")
输出python format-problems-variants.py
unfiltered 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

The unfiltered variant answers q-0018 and q-0039, which are unanswerable, so answered-declined-expected counts them: 2 of 80 (q-0018, q-0039). The second model's replies carry more problems. Their no-citation count is 9 of 80 (q-0001, q-0007, q-0047, q-0058, q-0060, q-0063, q-0065, q-0071, q-0080).

The order check flags the second model's reply to q-0030. That reply opens with its citation, so it is citation-first: 1 of 80 (q-0030). Its first line also holds a fragment of a heading, which is a stray-line. A reply whose last line ends no sentence gets that name too, and one of the two is q-0007, whose text is cut off in the middle of a repeated sentence: 2 of 80 (q-0007, q-0030).

The format check passes that q-0030 reply. format_problems counts citations and doesn't read where they fall, so a reply can cite only sections the prompt gave and still have its parts out of order. That gap is what the order check is for. The example also runs one fixture reply for each name, and it stops if a name does not fire, so each zero above means the check looked and found nothing.

A check that never fires on the baseline still earns its place, because it costs nothing and catches the next prompt that breaks a shape.

Working rule: Run the format check and the order check on every reply before a judge reads it, and report each name's count on each split. A zero counts as a result only when the check could have fired, so keep the fixture run with the report. When a count rises, read the replies behind it before you change the check, because a name says which shape broke and not why it broke.

引用检查

最近一次修改见于版次 2026.11.3

第 1 章写出了第一个引用检查:回复所引用的每个 ID 都必须是提示词给出过的。该检查只说明引用是否在提示词之内,并不说明这条引用对该条目而言是否正确。本节对每个被引用的 ID 再提两个问题:它是否存在于该条目所询问版本的文档中?它是否是该条目列为支持答案的节?

citation_outcome为每个被引用的 ID 给出四种结果之一。supported表示该 ID 在该条目针对所询问版本的列表中。unlisted表示它是所询问版本中的某一节,但该条目并未列出。wrong-version表示它是只存在于其他版本中的某一节。missing表示没有任何版本含有该引用 ID 的节。有两条规则适用于全部四种结果。回复携带的是 ID 而不是版本,因此同时出现在两个版本中的 ID 不可能是 wrong-version,它按所询问的版本来判定。此外,unlisted绝不判为错误。该条目的列表是人工编写的,未被列出的某一节仍可能支持答案。

该检查针对三份记录的开发集条目运行:基线;未过滤变体,它使用相同的提示词,但从所有版本中检索,并向模型展示各版本;以及 prompt-b,即第 1 章中先引述后作答的提示词 P2(两种提示词),它要求模型先引述其答案所依据的那句话,并在每一行给出引用。它的117条引用来自相同的条目,因此其占比是按引用计算的。每份记录的引用都以同样的方式分类。

check-citation-support.py Python 3.12.15 · numpy 2.5.5 · pydantic 2.14.3 · typing-extensions 4.16.0 通过
"""Sorts each section ID that a reply cites into one outcome, for three recordings, over the dev items.The outcomes are supported (listed by the item for its asked version), unlisted (a section of the asked version that theitem does not list), wrong-version (a section of another version only) and missing (a section of no version). Thecheck reads IDs, not sentences: whether a listed section supports the sentence is the judge's job, in grounded-answers.An ID that exists in two versions cannot be told apart by the reply, because the citation carries no version. It isjudged against the asked version, so an ID shared by both versions is never wrong-version."""import lib  # first: fixes the thread counts and seeds before anything else loadsfrom collections import Counterfrom lib.contract import CITATION_OUTCOMES, citation_outcomes, parse_reply, section_ids_by_versionfrom lib.prompts import P1_SHA256, P2_SHA256from lib.replay import ReplayModelfrom lib.stats import pctfrom lib.testset import load_itemsRECORDINGS = (  # label, recording, the sha256 of the prompt it was made from    ("baseline", "assistant-baseline", P1_SHA256),    ("unfiltered", "assistant-unfiltered", P1_SHA256),  # same prompt; retrieval from every version, versions shown    ("prompt-b", "assistant-prompt-b", P2_SHA256),)ids = section_ids_by_version()items = load_items(split="dev")  # dev only: held-out items are not read here (plan section 3.4)for label, recording, prompt_sha256 in RECORDINGS:    model = ReplayModel(recording, prompt_sha256)    counts = Counter()    for item in items:        reply = parse_reply(model.reply(item.id, 0))        # The item's list for its asked version. An unanswerable item may also list another version: not counted here.        listed = frozenset(s.section_id for s in item.supporting_sections if s.version == item.version)        counts.update(citation_outcomes(reply, item.version, listed, ids))    total = sum(counts.values())    print(f"{label} citations on dev items: {total}")    for outcome in CITATION_OUTCOMES:        print(f"{label} {outcome}: {pct(counts[outcome], total)}")
输出python check-citation-support.py
baseline 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)

在每份记录中,大多数引用都指向该条目列出的某一节。列出的占比在基线中为93.3% (56 of 60),在未过滤变体中为84.7% (50 of 59),在 prompt-b 中为93.2% (109 of 117)。

存在性与版本

版本检查在这些记录中没有发现任何问题。按上文的定义,错版本引用是指仅引用了另一版本的某一节。基线的错版本占比为 0.0% (0 of 60),未过滤变体为 0.0% (0 of 59),prompt-b 为 0.0% (0 of 117)。缺失这一结果同样没有出现在三份记录中。这一结论只针对引用而言,并不能说明助手对每个问题都按所问版本作答。

需要重点关注的是未过滤变体,因为它的上下文包含所有版本的各节。如果有哪份记录引用了错误的版本,就应当是这一份。它一处也没有引用错版本。真正要紧的错误出在论断上。第 2 章把基线对 q-0023 的回答编码为错版本回答:它给出的是 1.0 中忽略条目在 2.0 下的结果,并且引用了 1.0 的某一节。引用落在所问的版本之内,因此这项检查会放行它。只有把论断与 1.0 的参考文档对照阅读,错误才会显现。

工作准则: 把错版本和缺失这两类结果各自作为单独的比率报告,不要把其中的零当作回答正确。对每个依赖版本的条目,都要把论断与所问版本的参考文档对照阅读。有依据的回答把这种对照阅读做成了一个独立的比率。

支持

未列出的结果是这项检查真正发挥作用之处,它需要人来判断。按本检查的规则,引用所问版本中某个未列出的节并不算错误,因为条目的清单是手工编写的,可能并不完整。基线对 q-0057 的回答就是一例:它引用了remote-retries,而该条目并未列出这一节。代码把这条引用归为未列出,而第 2 章把这条回答编码为引用问题,因此需要由人来判定这条引用是否确实有问题。第 2 章还把候选方案表述为一条规则,即每条引用都必须是条目所列出的。本章放宽了这条规则,因为清单是手写的,最终下判断的是人,而不是清单。

未列出的占比为:基线6.7% (4 of 60),未过滤变体15.3% (9 of 59),prompt-b 6.8% (8 of 117)。未过滤变体的未列出占比最高。它的每一条未列出的引用都是留给人的一个问题:这一节是否支持引用它的那句话?

结果为supported只表示该 ID 在清单上。清单上的节仍可能无法支持引用它的那句话,因为这项检查读取的是 ID,而不是句子。清单上的节是否支持其句子,是一项判断,本检查并不作出这项判断。有依据的回答沿用此处定义的四种结果作为其引用准确率,该指标同样只读取 ID,并另外加入回答层面的忠实性评判,其写法见带评分标准的评判器。

工作准则: 仅当某条引用的 ID 在条目清单上时,才把它计为受支持,绝不要把它计为正确。在称一条未列出的引用为问题之前,先对照其对应的节阅读它。把未列出与版本错误、缺失分开报告,因为更完整的清单会使部分未列出的引用变为受支持。

精确匹配与模糊匹配

本书中的大多数字符串检查使用两种比较方式之一。精确匹配判断两个字符串是否相等,适用于任何固定不变的文本。第 1 章中的拒答检查就是一例:只有当回复的全部文本与拒答句子相等时,该回复才算作拒答,而这个句子正是已解析回复的 declined 字段所保存的内容。节 ID、标志名和文件名同样是固定文本。精确匹配只给出“是”或“否”,从不返回“接近”的结果。

模糊匹配则为两个字符串的相似程度打分。Python 标准库中的 difflib 提供了这一功能。其 SequenceMatcher 类以 ratio() 给出得分,文档将其定义为匹配元素数的两倍除以两个序列中元素总数。关于这个得分,有三点对检查很重要。

  • 它依赖参数顺序。文档提醒,ratio() 调用的结果可能取决于参数的顺序,因此检查每次都必须把参考文本放在同一个位置。就示例中的长文本对而言,参考文本在前时得分为 0.480,回复在前时得分为 0.861。
  • 它统计的是匹配,而不是语义。标志中一个字母的拼写错误,与正确的标志相比得分为 0.933,尽管该标志是错的。一条回复可以保持很高的得分,而其中唯一一处错误的事实却已改变。
  • 它可能跳过长字符串的某些部分。对于 200 个或更多元素的序列,文档规定,若某个元素的重复次数超过序列的百分之一,则将其视为垃圾元素,除非关闭 autojunk。对字符串而言,元素就是字符,因此 200 个字符或更长的回复可能受到影响。这一启发式规则基于第二个参数构建,参考文本在前时,第二个参数就是回复。在这组长文本对上,默认得分为 0.480,使用 autojunk=False 时则为 0.861。
fuzzy-match.py Python 3.12.15 · numpy 2.5.5 通过
"""Compares three pairs of sablefile answers with an exact match and with difflib's ratio(), a score from 0 to 1.Each pair is a reference and a reply written for this example, not a recorded reply: two file names, a flag with onewrong letter, and a long answer that leaves out its folder sentence. ratio() is printed with the reference first and withthe reply first, because the documentation says the argument order can change the score. With the reference first, thelong reply is the second sequence and is 200 characters or more, so the autojunk heuristic applies to it; the long answeris also scored with autojunk turned off."""import lib  # first: fixes the thread counts and seeds before anything else loadsfrom difflib import SequenceMatcherFOLDERS = " Folders are created only with --apply, because a plain sync writes nothing."PLAN = " The plan lines start with create, update or unchanged, and the lock file is written only by the apply run."LONG_REFERENCE = (    "With no flag, sync prints the plan and writes nothing. --apply writes the files and updates the lock file, "    ".sablefile/lock.json." + FOLDERS + PLAN)LONG_REPLY = LONG_REFERENCE.replace(FOLDERS, "")  # the answer leaves out the folder sentencePAIRS = (    ("file names", ".sablefile/lock.json", "sablefile.lock"),    ("flag", "--apply", "--appply"),    ("long answer", LONG_REFERENCE, LONG_REPLY),)for name, reference, reply in PAIRS:    print(f"{name}, exact match: {reply == reference}")    print(f"{name}, ratio: {SequenceMatcher(None, reference, reply).ratio():.3f}")    print(f"{name}, ratio with the reply first: {SequenceMatcher(None, reply, reference).ratio():.3f}")# autojunk=False: the default treats the reply's common characters as junk once it is 200 characters or longer.print(f"long answer, ratio with autojunk off: {SequenceMatcher(None, LONG_REFERENCE, LONG_REPLY, autojunk=False).ratio():.3f}")
输出python fuzzy-match.py
file 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

这三组文本对是为本示例专门编写的,因此得分展示的是每种特性的作用,而不是回复出现这些问题的频率。

工作准则: 凡是预期文本固定的地方,都使用精确匹配。模糊比率只用于为阅读而对回复排序,不要用作通过或失败的判据,直到有已记录的运行结果表明,对本书的答案而言阈值应设在何处。调用 ratio() 时,每次都把参考文本放在前面,并在检查的文档字符串中说明哪个字符串是哪一个。

BLEU 与 ROUGE 在何处会产生误导

有两种源自其他任务的词语重叠评分,可以用来检查生成文本。BLEU 来自机器翻译,ROUGE 来自摘要任务。两者的计算成本都很低。

Papineni 等人在 2002 年提出 BLEU,作为给机器翻译打分的一种快速而廉价的方法。它使用修正的 n 元语法精确率(Papineni 等,2002)。Reiter 回顾了 BLEU 与人类判断的吻合程度,发现现有证据支持将其用于机器翻译系统的诊断性评估。证据不支持在机器翻译之外使用 BLEU,也不支持用它评估单个文本或进行假设检验(Reiter,2018)。对系统成立的分数,并不因此对单个答案也成立。

Lin 将 ROUGE-N 定义为 n 元语法的召回率:候选文本所覆盖的参考文本中词语序列的比例(Lin,2004)。该论文研究的是摘要。另有一项研究在对话回复而非文档答案上测试了借自机器翻译的指标。结果发现,在通用聊天数据集上,这些指标与人类判断的相关性非常弱,在技术类数据集 Ubuntu 帮助数据上则毫无相关性(Liu 等,2016)。这只是针对一种任务的一项研究。Sablefile 的答案属于技术类,因此该结果只是一个警示,并不是对本助手的度量。

关于 sablefile 2.0 的三个问题最能清楚地说明这一问题。每个问题都有一条书面的参考答案、一条照搬了参考答案大部分词语的错误答案,以及一条只用少量相同词语表达同一含义的正确答案。这些答案是为本示例编写的,并非取自实际记录,因此它们说明的是这种失败可能发生,而不是发生的频率。类 BLEU 评分采用截断的 1 至 4 元语法精确率、其几何平均数以及简短惩罚。ROUGE-1 F1 对单个词语计数。两个公式都写在示例的代码中。本书未固定任何 BLEU 或 ROUGE 软件包,并且示例报告的是综合了召回率与精确率的 F1,而不是 Lin 所定义的召回率。

overlap-misleads.py Python 3.12.15 · numpy 2.5.5 通过
"""Scores a wrong answer that shares most of its words with the reference above a right answer that shares few.Each pair in data/overlap-pairs.json is a question on sablefile 2.0 with its reference, a wrong answer and a right answer.All three pairs are hand-written for this example, not recorded replies. The scores are the textbook formulas, writtenhere in plain Python: ROUGE-1 F1 (unigram overlap, F1 of precision and recall) and a BLEU-style score (clipped 1- to4-gram precision, geometric mean, brevity penalty), with no smoothing. No BLEU or ROUGE package is pinned, and none isused. The reference facts are in examples/data/docs/2.0 (sync.md, quickstart.md, lockfile.md)."""import lib  # first: fixes the thread counts and seeds before anything else loadsimport jsonimport mathimport refrom collections import Counterfrom pathlib import PathPAIRS = json.loads((Path(__file__).resolve().parent / "data" / "overlap-pairs.json").read_text(encoding="utf-8"))def words(text: str) -> list[str]:    """Lowercase runs of letters and digits: `--apply` is the word apply, and `lock.json` is two words."""    return re.findall(r"[a-z0-9]+", text.lower())def rouge_1_f1(candidate: str, reference: str) -> float:    """ROUGE-1 F1: shared words, counted with repeats up to the smaller count, over both lengths."""    cand, ref = words(candidate), words(reference)    overlap = sum((Counter(cand) & Counter(ref)).values())    if overlap == 0:        return 0.0    precision, recall = overlap / len(cand), overlap / len(ref)    return 2 * precision * recall / (precision + recall)def bleu_sentence(candidate: str, reference: str, max_n: int = 4) -> float:    """Sentence BLEU-style score: clipped n-gram precision for n = 1 to 4, geometric mean, brevity penalty.    Without smoothing, a single n-gram order with no match gives 0, as the textbook formula does.    """    cand, ref = words(candidate), words(reference)    precisions = []    for n in range(1, max_n + 1):        cand_grams = Counter(tuple(cand[i : i + n]) for i in range(len(cand) - n + 1))        ref_grams = Counter(tuple(ref[i : i + n]) for i in range(len(ref) - n + 1))        clipped = sum(min(count, ref_grams[gram]) for gram, count in cand_grams.items())  # each n-gram up to the reference's count        if clipped == 0:            return 0.0        precisions.append(clipped / sum(cand_grams.values()))    # Short answers are penalised by the brevity penalty: a candidate shorter than the reference scores less.    brevity = (1.0 if len(cand) > len(ref) else math.exp(1 - len(ref) / len(cand)))    return brevity * math.exp(sum(math.log(p) for p in precisions) / max_n)for number, pair in enumerate(PAIRS, start=1):    print(f"pair {number} (hand-written), question: {pair['question']}")    for label in ("wrong", "right"):        print(f"pair {number}, {label} answer, ROUGE-1 F1: {rouge_1_f1(pair[label], pair['reference']):.3f}")        print(f"pair {number}, {label} answer, BLEU: {bleu_sentence(pair[label], pair['reference']):.3f}")# The claim the prose makes: the wrong answer overlaps the reference more than the right one, in every pair.higher = sum(rouge_1_f1(p["wrong"], p["reference"]) > rouge_1_f1(p["right"], p["reference"]) for p in PAIRS)print(f"pairs where the wrong answer has the higher ROUGE-1 F1: {higher} of {len(PAIRS)}")
输出python overlap-misleads.py
pair 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

在 3 of 3 对答案中,错误答案的 ROUGE-1 F1 得分高于正确答案。对于第一对,错误答案得 0.815,正确答案得 0.167。

阅读 BLEU 各行时需要谨慎。代码中写出的公式没有平滑处理,因此只要四个 n 元语法阶数中有任何一阶完全没有匹配,得分就为零。每条正确答案与其参考答案共有单个词语,却没有共有的两词序列,所以其二元精确率为零,BLEU 也为零。这是公式本身的行为,并不能说明答案的好坏。

ROUGE-1 F1 对单个词语计数,并忽略词序。一条重复了参考答案大部分词语的错误答案,无论其余词语错在何处,都能拿回大部分分数。第三对即是例证。其错误答案得 0.952。该答案给出的是 1.1 版本中的文件名,而参考答案给出的是 .sablefile/lock.json。错误答案的每个词都出现在参考答案中,它唯一缺少的参考词语是 json。文件名正是答案中要紧的部分,而评分无法把这一部分与其余部分区分开来。

工作准则: 不要把 BLEU 或 ROUGE 用作只有一种正确形式的答案的合格线。如果要报告它们,请写明所用公式,并说明是否经过平滑。凡是重叠度高而论断存疑的答案,都应逐条阅读,因为上述各对答案表明,重叠度会奖励照搬参考答案的错误答案。应当按 第 5 章 所述,用评判器来检查论断。

代码中的拒答

第 1 章已经有一项针对拒答的代码检查。它对照确切的拒答语句,统计两类错误:助手拒答了可回答的条目,以及助手回答了不可回答的条目。本章的格式检查增加了一种情形:拒答语句与其他文字出现在同一条回复中。本章还对两个数据划分的每个条目都运行不可回答条目检查,而第 1 章只对其中二十个条目运行了该检查。基线在两个划分上的格式计数均为零,见格式检查。在第 1 章的二十个条目上,拒答检查没有发现这两类错误。本章不在开发集条目上重新运行它。基线在这些条目上的误拒率见第 10 章。

这两项检查读取的都是回复的文本,因此都有由此带来的局限。用其他措辞表达的拒答不是那句确切的语句,所以会被当作回答放行,第 2 章中的 q-0080 就是一例。拒答率也不包括依赖版本的条目,条目 q-0004 显示了这样做的代价,第 1 章对此有说明。基线拒答了它,而 2.0 版文档在占位符一节中给出了答案。拒答率不会把这种情形算作误拒。有依据的回答构建了能够涵盖这种情形的版本正确率。

对于文档没有涉及的条目,拒答是否正确是一项判断,而不是代码检查。文档所述是否足以作答,是文档未述及时的拒答要讨论的问题。

**工作准则:**在每个数据划分上统计两类拒答错误,并对照所属版本的文档,人工逐条阅读每一个依赖版本的拒答,因为拒答率不包括这些条目。

运行检查,以及检查能说明什么

在生产环境中,检查会在每条回复上运行,因此对提示词或模型的任何改动,都会使格式计数、拒答率和未列出占比在同一份报告中发生变化。如果这些指标全都保持平稳,而用户却反映答案有误,这就说明检查没有发现这类失败。请按 第 2 章 所述,依主要缺陷为新回复编码,并为对应的模式编写一项检查。

本章所确立的结论范围很窄。代码检查可以保证回复的形式、引用的归属以及拒答语句的准确,并且可以在每条回复上无成本地做到这一点。回复的含义仍需由读者或评判者来判断。因此,应依主要缺陷为每条回复编码,让每项检查只针对它能看到的缺陷,把它看不到的交给读者或评判者,这样就不会把干净的计数当作干净的答案。

本章做出了以下决定:

  • 格式检查是一道带有五个名称的守卫检查,在任何评判者之前运行。
  • 格式检查只统计引用的数量,不读取引用的顺序,因此第二个模型对 q-0030 的回复能通过该检查。顺序检查会标记这条回复。
  • 当引用的 ID 在该条目的清单上时,这条引用即为 supported;引用所在句子正确与否,并不影响这一判定。
  • 引用的版本检查在这三份记录中没有发现版本错误的引用,本章并不将其作为对答案版本的检查。
  • 重叠分数来自该示例自身的公式,任何分数都不用作及格线。
  • 模糊匹配的特性在 sablefile 的答案上展示,任何比率都不用作及格线。
  • 留出的条目只在格式检查中以计数的形式出现,由 第 10 章 对其进行解读。

本章,在本版次中

版次 2026.11.3示例于 2026年11月21日 通过本章 5个示例 个示例中有 5 个通过

译自英文版图书,版次 2026.11.3。

引用本节

格式

每种格式均引用英文原书,本译本以其为准。

每种格式都会注明该版次。其链接会打开当前版次,节标题处会说明该节文本最后一次修改的时间。访问日期和检索日期即为您打开此页的当天。

本页内容

第 4 章,共 11 章: 为你发现的失败编写代码检查

  1. 代码检查能看到什么
  2. Format checks
  3. 引用检查
  4. 存在性与版本
  5. 支持
  6. 精确匹配与模糊匹配
  7. BLEU 与 ROUGE 在何处会产生误导
  8. 代码中的拒答
  9. 运行检查,以及检查能说明什么

返回顶部全部章节