构建一个在拿不准时转交人工的银行收件箱路由器
阅读约需 29分钟 分钟,6节中含4个示例。
学完本章,你将能够构建一个路由器:对一条消息返回团队、置信度和转交标志(hand-off flag);用三种度量在固定样本上为它打分;并理解为什么一个未经训练的小模型即使按现有方式写好提示词,也不能作为路由器的第一版。
客户发给银行的消息都进入同一个支持队列,本书称之为收件箱。路由器把收件箱中的每条消息发往 77 个团队之一。一个为每条消息都选定团队的路由器,有时会选错。选错团队会让客户白白耗费时间,也会让支持人员多一道转送消息的步骤。本章构建的路由器能够在拿不准时说明自己拿不准。
团队是路由器可以返回的一个标签,例如 card_arrival,它绝不是一群人。阅读消息的人是银行的支持人员,路由器无法转送的消息会交给其中一位。
这些消息及其团队来自 BANKING77,这是一个客户发给银行的消息的公开数据集,以 CC BY 4.0 许可发布。BANKING77 把每个标签称为意图(intent)。从这里起,本书称之为团队,标签的写法与数据集中一致。
路由器是整个系统:一个模型、一段提示词、一个阈值,以及把消息发送出去的代码。本章构建的是一个粗糙的路由器。当路由器的阈值只是占位值、模型只是替身时,它就是粗糙的;而这一个是可用的路由器,因为它对每条消息都返回答案,并且每个输出都可以打分。 你需要 Python,以及一次对托管模型 API 的调用,你可能已经写过。本章不要求你了解 Transformer 的内部工作原理。凡是内部细节要紧的地方,只用一句话说明。
首先有两个共用部分。第一个是替身模型对测试消息所给答案的一份录制,关于向模型提问的一节会介绍它。大多数示例离线读取这些答案,另有一个示例在线运行一个小模型,见展示其失败的一节。第二个是 router_lib,它是本书 examples 文件夹中的一个共用模块,里面有团队标签、路由器提示词、转交规则和各项度量。每个示例都导入它,因此同一个函数在每一章中含义相同。
路由器返回什么
对于一条消息,路由器返回三项内容。团队是其中一个标签,直接写成该标签本身。置信度是一个从零到一的数,表示路由器对该团队有多大把握。转交标志在置信度过低、不宜将消息继续发送时为真,此时由人工接手这条消息。
在本章中,置信度只有一种狭义的含义。它是 llama-cpp-python 为受约束的答案返回的概率,记录中将其保存为对数概率。通俗地说,它就是模型赋予其所写出的团队的概率大小。写成公式,即置信度 = e 的 (各词元对数概率 log p 之和) 次方,也就是答案各词元概率的乘积。词元是模型读取和写出的一小段文本。这不是对各团队做的 softmax,第 5 章用的才是那种做法。它只是一个分数,而不是经过校准的概率,本章也没有任何内容表明某个大小的置信度与该团队判断正确的频率相符。第 5 章在开发集上检查校准情况,开发集是留出来用于选择设置的训练消息(第 2 章):它把消息按置信度分成若干区间,并输出每个区间的数量和准确率。
| 输出 | 含义 | 用途 |
|---|---|---|
| 团队 | 银行标签集中的一个标签 | 标志为假时,消息发送到的目的地 |
| 置信度 | llama-cpp-python 为受约束的答案返回的概率,以分数形式给出 | 转交规则 |
| 转交标志 | 置信度低于阈值时为真 | 接手消息的人工 |
标志最为重要,原因在于运营层面。一个总是返回团队的路由器会把每条消息都发往某处,包括那些它根本没有依据去路由的消息。转交则把消息交给能够路由它的人,而一个会说明自己何时拿不准的路由器,会让这个人的工作变得可见。我们建议每个路由器在每次回答中都返回该标志,无论为真还是为假,这样下面各节中的每项度量都可以仅凭输出计算出来。
让路由器说明自己何时拿不准,这件事在研究文献中有专门的名称:选择性分类,或称拒绝选项。Geifman 和 El-Yaniv 2017 年关于深度网络的预印本描述了这种取舍。拒绝处理部分输入的分类器覆盖的输入更少,而这些技术可以通过放弃覆盖率,有望显著改善深度网络对其所保留输入的预测。他们的方法还允许用户设定目标风险水平。本书中的转交规则并不这样做。它在留出数据上选取阈值,对剩余的风险不提供任何保证。
本章中的度量只为评分而返回团队。单条消息的示例见转交一节,其中仅在标志为假时才返回团队。
工作准则: 每个团队都要连同标志一起返回,只要标志为真,就把消息交给人工。仅当标志为假时,才把团队返回给调用方。即使去掉标志会让路由器看起来更完整,也要保留它,因为转交度量会统计它。
向模型询问一个团队
路由器的团队由模型给出,而模型由提示词引导。提示词是路由器中银行改动最频繁的部分,所以我们把它固定在一处。router_prompt 为一条消息构建一个提示词。该提示词要求给出一个团队,并向模型提供每个团队的名称、该消息,以及末尾的 Team: 一词,由模型接着补全。提示词只包含团队名称和正在路由的这一条消息,没有别的内容,因此样本中的其他消息不会随它一起到达模型。
每一次实时运行和录制运行都使用同一份提示词文本,来自 router_lib.router_prompt,所以各次运行中的措辞相同。模型读到的内容却不总是一样。录制时,这些文字被包裹在替身模型的聊天模板中;而在关于小模型的一节中,实时运行把不带模板的原始文本交给小模型。提示词一旦改变,就是另一次录制,其得分不能与旧的得分比较。提示词是路由器版本的一部分,读者若修改了它,就应当记录这一改动,做法与本书记录模型更换相同。
本书只用“银行”这一名称指代该机构。银行自己的路由器是一个托管模型,每条消息都会调用它。我们无法使用这样的模型,本书也从不调用托管模型。我们用替身模型 Qwen3-4B-Instruct-2507 取而代之,它是一个更大的开源模型,书中每个路由器都以替身模型的答案为基准来衡量。读者自己的托管模型对某些消息的回答会有所不同,得分也会因此不同。
我们选择这个替身模型,是因为任何人都能复现它的答案。它的许可证是 Apache-2.0,正如 GGUF 仓库的模型卡对本书所固定修订版本中的该文件所声明的那样。该文件是 Qwen3-4B-Instruct-2507-Q4_K_M.gguf,是一个量化版本,由 llama-cpp-python 库在 CPU 上运行。它的录制清单写明了该文件的 SHA-256,因此下载该文件的读者可以在运行任何内容之前先行校验。
替身模型对 test_1001 中的每条消息各回答了一次,这是由 1,001 条测试消息组成的固定样本,而 test_40 是其中最前面的 40 条消息。录制使用贪心解码(每一步取最可能的词元)和固定的随机种子。它还使用了只允许出现团队名称的语法,因此每个录制的答案都是这 77 个标签之一。正是这种语法使录制的答案始终是团队名称。第 4 章会解释它,因为关于小模型的一节中的失败正是由同一思路解决的。
读者若有自己的模型,可以用同样的方式录制它的答案。你需要编写一个函数 call_model。它接收一条消息,返回团队以及该答案的对数概率,即答案各词元对数概率之和,与替身模型的录制所存储的一致。函数 record_answers 对样本中的每条消息调用它,按替身模型的格式为每条消息写出一行,并在该函数返回的名称不是任何一个团队时抛出错误。其余部分对每个模型都相同,因此同一样本上的两份录制可以逐行比较。
1"""Write a model's team answers in the stand-in's JSONL shape, then check record_answers against the stand-in's recording.2The line to read is the last one printed, which counts the lines that match the recording. The stand-in here replays3that recording, so no model runs."""45import os67os.environ["HF_HUB_OFFLINE"] = "1"8os.environ["TRANSFORMERS_OFFLINE"] = "1"910import json # noqa: E40211import tempfile # noqa: E4021213import torch # noqa: E4021415torch.set_num_threads(2)1617import router_lib # noqa: E4021819router_lib.setup_runtime()202122def record_answers(call_model, messages, path):23 """Write one JSONL line per (index, text); call_model(text) returns (team, logprob)."""24 with open(path, "w") as out:25 for index, text in messages:26 team, logprob = call_model(text)27 if team not in router_lib.LABELS:28 raise ValueError("the model returned a name that is not a team")29 label = router_lib.LABELS.index(team) # stored as the label, the same encoding as the gold labels30 row = {"index": index, "label": label, "team": team, "logprob": logprob}31 out.write(json.dumps(row) + "\n")323334RECORDING = router_lib.HERE / "data" / "recorded" / "standin-baseline" / "answers.jsonl"35rows = router_lib.read_rows("test") # each row is (text, gold label)36sample = router_lib.read_sample("test_40")37messages = [(i, rows[i][0]) for i in sample] # element 0 of a row is its text, which the model reads38with open(RECORDING) as f:39 recording_lines = f.read().splitlines()40recorded = {json.loads(line)["index"]: json.loads(line) for line in recording_lines} # keyed by message index41by_text = {rows[i][0]: (recorded[i]["team"], recorded[i]["logprob"]) for i in sample} # keyed by text, not index424344def standin(text):45 """Stand in for a model: return the recorded team and logprob for this message."""46 return by_text[text]474849with tempfile.TemporaryDirectory() as folder:50 path = os.path.join(folder, "answers.jsonl")51 record_answers(standin, messages, path)52 with open(path) as f:53 written = f.read().splitlines()5455matching = sum(line in recording_lines for line in written) # a line matches when it equals a recorded line exactly56print(f"messages written: {len(written)}")57print(f"lines matching the recording: {matching}/{len(written)}")
python record-your-own-answers.pymessages written: 40
lines matching the recording: 40/40
在信任你自己的录制之前,先在替身模型的答案上检查 record_answers。这里替身函数回放的是录制内容,所以该检查测试的是 record_answers,而不是某个模型。它写出的每一行都与录制相符,共 40 行。当你把该函数换成对自己模型的调用时,同样的检查会显示你的录制是否与替身模型的录制具有相同的形态。
工作准则: 在同一个固定样本上为每个模型打分,并在把它与替身模型比较之前,先用 record_answers 记录它的答案。说明每个得分基于哪个样本,只有样本一致时,才把两个得分并列比较。
把没把握的消息转交出去
替身模型的回答为每条消息给出一个置信度,本节把这个置信度转化为转交标志。
转交规则只是一次比较。当置信度低于阈值时,handoff(confidence, threshold)返回真;当置信度等于或高于阈值时,返回假。被转交的消息交给人处理。未被转交的消息交给路由器所指定的团队。本书中每一条向调用方返回团队的路由都使用这个函数,因此调用方不可能在没有做出这一决定的情况下收到团队。
这条规则读起来很简单,难处在于选定那个数。本章使用一个占位阈值0.5,每一项用到它的输出都会如此注明。占位阈值背后没有任何规则:它只是一个让规则得以运行的数。
第 5 章按照那里给出的规则,在开发集上选定阈值,并把选定的值记录在适配器的清单中,这样读者可以看到某个结果用的是哪个阈值,以及它是在什么数据上选出的。测试样本从不用于选择阈值。在那之前,占位阈值是本章仅有的阈值,基于它得到的结果用于讲解各项度量,而不是用于评判路由器。
转交率是转交给人的消息所占的比例,它随阈值变化。提高阈值,转交给人的消息就更多;降低阈值,直接交给团队的消息就更多。正是这种取舍,使阈值的选择必须经过测量。第 5 章在选定一个阈值之前,先在开发集上用不止一种设置展示这一取舍。
1"""Route the first message of test_40 from the stand-in's recorded answer, at the placeholder threshold.2The prose reads the printed team and the hand-off line. No model runs here, and the message's text is never printed."""34import os56os.environ["HF_HUB_OFFLINE"] = "1"7os.environ["TRANSFORMERS_OFFLINE"] = "1"89import json # noqa: E40210import math # noqa: E4021112import torch # noqa: E4021314torch.set_num_threads(2)1516import router_lib # noqa: E4021718router_lib.setup_runtime()1920THRESHOLD = 0.5 # Placeholder. Chapter 5 chooses the threshold on the dev split.21RECORDING = router_lib.HERE / "data" / "recorded" / "standin-baseline" / "answers.jsonl"222324def route(row):25 """Return (team, confidence, handed off) for one recorded answer. The team is None when handed off."""26 confidence = math.exp(row["logprob"]) # the recording stores a log-probability; exp gives a probability27 flag = router_lib.handoff(confidence, THRESHOLD) # True below THRESHOLD, and for a NaN; equal to THRESHOLD is kept28 return (None if flag else row["team"]), confidence, flag293031with open(RECORDING) as f:32 recorded = {r["index"]: r for r in map(json.loads, f)} # keyed by message index, as the sample lists them3334first = router_lib.read_sample("test_40")[0] # the first of the sample's 40 message indexes35team, confidence, flag = route(recorded[first])36assert not flag # the prose states this message is kept; a change that hands it off fails the run37print(f"team: {team or 'none (handed off)'}")38print(f"confidence: {confidence:.2f}")39print(f"handed off: {'yes' if flag else 'no'}")
python route-one-message.pyteam: top_up_reverted
confidence: 1.00
handed off: no
让我们跟随一条消息走完整条路由,从记录下来的回答到打印出的团队。该示例取test_40的第一条消息,读取替身模型为它记录的回答,并在占位阈值下通过handoff对它进行路由。它打印团队、保留两位小数的置信度,以及该消息是否被转交,而从不打印消息的文本。这条消息的置信度为1.00,越过了占位阈值,因此路由器保留这条消息并返回它的团队top_up_reverted。脚本断言该消息未被转交。一条消息能展示输出的形态,却无法说明路由器有多常是对的。
**工作准则:**阈值要在开发集上选定,绝不在测试样本上选定,并且每次都把转交率与准确率并列报告。阈值仍是占位值时,要在每项输出中注明,并且不得把它的准确率用于任何关于路由器结果的论断。
在固定样本上为路由器评分
路由器是在已知所属团队的消息上评分的。本章使用 test_40,它是由 40 条测试消息组成的固定样本,因此每位读者都以相同的顺序对相同的消息评分。第 2 章说明了这些样本是如何抽取的,使用哪一份划分来选择设置,以及为什么测试样本不参与这一选择。下面的数字只描述这份样本。
路由器用三个数字来衡量,每个数字旁边都附有其计数。
- 准确率是团队与标准标签一致的消息数,除以样本中的全部消息数。被转交人工的消息也计入分母,若其团队错误,则算作错误。
- 转交率是置信度低于阈值的消息数,除以全部消息数。
- 未转交消息的准确率是路由器留下的消息中判断正确的消息数,除以它留下的消息数。当路由器没有留下任何消息时,该值记为未定义。
每项指标回答不同的问题。准确率问的是路由器总体上有多常判断正确。转交率问的是有多少工作交给了人。留下消息的准确率问的是,路由器留下的消息能否直接交给团队。仅凭准确率无法区分两类错误。被转交的错误团队会拉低准确率,未经检查就到达团队的错误团队同样会拉低准确率。只有第三项指标能单独分离出第二类错误,而这正是支持人员直接感受到的那一类。
1"""Score the stand-in's recorded answers on test_40, with a placeholder hand-off threshold.2The last printed line, accuracy on messages not handed off, is the one the prose reads against the others: it is the3accuracy of the messages a team receives. No model runs here, and the answers come from the recording."""45import os67os.environ["HF_HUB_OFFLINE"] = "1"8os.environ["TRANSFORMERS_OFFLINE"] = "1"910import json # noqa: E40211import math # noqa: E4021213import torch # noqa: E4021415torch.set_num_threads(2)1617import router_lib # noqa: E4021819router_lib.setup_runtime()2021THRESHOLD = 0.5 # Placeholder. Chapter 5 chooses the threshold on the dev split.22RECORDING = router_lib.HERE / "data" / "recorded" / "standin-baseline" / "answers.jsonl"2324answers = {}25with open(RECORDING) as f:26 for line in f:27 row = json.loads(line)28 answers[row["index"]] = row2930rows = router_lib.read_rows("test")31sample = router_lib.read_sample("test_40")3233golds = [rows[i][1] for i in sample] # element 1 of a test row is its gold label; element 0 is its text34preds = [answers[i]["label"] for i in sample] # the recorded label is the team's position in LABELS, as the gold is35confs = [math.exp(answers[i]["logprob"]) for i in sample] # exp turns each recorded log-probability into a confidence3637# metrics applies the hand-off rule at THRESHOLD; accuracy's denominator still includes handed-off messages38result = router_lib.metrics(preds, golds, confs, THRESHOLD)39n = result["n"]4041print(f"messages: {n}")42print(f"placeholder threshold: {THRESHOLD}")43print(f"accuracy: {result['correct']}/{n} ({result['accuracy']:.1%})")44print(f"handed off: {result['handed_off']}/{n} ({result['handoff_rate']:.1%})")45if result["accuracy_not_handed_off"] is None: # None when the router keeps no message, so the measure is undefined46 print("accuracy on messages not handed off: not defined (0 messages not handed off)")47else:48 m = result["not_handed_off"]49 print(50 f"accuracy on messages not handed off: {result['correct_not_handed_off']}/{m} "51 f"({result['accuracy_not_handed_off']:.1%})"52 )
python route-recorded-answers.pymessages: 40
placeholder threshold: 0.5
accuracy: 20/40 (50.0%)
handed off: 2/40 (5.0%)
accuracy on messages not handed off: 20/38 (52.6%)
下面是这三项指标在样本上的结果,所用阈值为占位阈值。该示例读取已记录的答案,对其置信度应用阈值,并打印每项指标及其计数。需要关注的是未转交消息的准确率,因为它就是团队实际收到的消息的准确率。
综合来看,这三项指标表明占位阈值并不能保护各团队。路由器在样本上的准确率为 20/40 (50.0%),任何团队都不应单凭这一水平就接受它。该阈值只转交了 2/40 (5.0%) 的消息,因此样本中的大部分消息都到达了某个团队。这些留下的消息的路由准确率为 20/38 (52.6%),仅略高于整个样本的准确率。为每条消息都返回一个团队的路由器,还不是银行能够使用的路由器。
如此小的样本可以表明路由器会出错,也可以显示各项指标如何变化,但无法有把握地区分两个路由器的优劣。第 2 章给出了更大的样本,第 5 章则在同类样本上测量其选定的阈值。
**工作准则:**将准确率、转交率和未转交消息的准确率放在一起报告,每项都附上其计数,并使用同一份固定样本;只有当两个路由器都在该样本上测量过时,才对二者进行比较。
先看小模型会做什么
最直接的捷径是舍弃替身,直接向一个小模型提问。SmolLM2-135M-Instruct 是本书保留的这个系列中最小的模型,也是本书其余部分使用的核心模型。它可以在 CPU 上运行,并能从固定的修订版本离线加载。如果它能回答出一个团队名称,路由器就完全不需要录制的回答,因此在其他一切构建于其上之前,值得先测试这条捷径。
测试向模型提出路由器会提出的同一个问题。模型拿到的是样本前 20 条消息对应的路由器提示词,对回答不加任何约束,并将生成长度限制为几个词元。请先猜一猜:在没有任何东西把模型限制在团队列表之内的情况下,这些回答中有多少个会是团队名称?然后再来数一数。
1"""Ask the 135M model for a team with the raw router prompt and no constraint, on the first 20 messages of test_40.2Look at the last printed line, which counts the answers that are exactly a team name. The answers stay in this file3and are never returned to a caller."""45import os67os.environ["HF_HUB_OFFLINE"] = "1"8os.environ["TRANSFORMERS_OFFLINE"] = "1"910import torch # noqa: E4021112torch.set_num_threads(2)1314import router_lib # noqa: E4021516router_lib.setup_runtime()1718SMALL = "HuggingFaceTB/SmolLM2-135M-Instruct"1920tokenizer, model = router_lib.load_model(SMALL)21rows = router_lib.read_rows("test")22sample = router_lib.read_sample("test_40", n=20) # the first 20, to keep the run short23teams = set(router_lib.LABELS)2425answers = []26with torch.no_grad():27 for i in sample:28 # the raw prompt: no chat template and no grammar, so the model may write anything29 inputs = tokenizer(router_lib.router_prompt(rows[i][0]), return_tensors="pt")30 # at most 10 new tokens, and greedy: the most likely token at each step31 out = model.generate(32 **inputs, max_new_tokens=10, do_sample=False, pad_token_id=tokenizer.eos_token_id33 )34 # the output starts with the prompt, so skip its tokens and keep only the answer35 new_tokens = out[0, inputs["input_ids"].shape[1] :]36 answers.append(tokenizer.decode(new_tokens, skip_special_tokens=True).strip())3738print(f"messages: {len(answers)}")39# an answer counts only when it is exactly a team name, with no extra words around it40print(f"answers that are a team name: {sum(a in teams for a in answers)}/{len(answers)}")
python unconstrained-first-try.pymessages: 20
answers that are a team name: 0/20
模型的回答没有一个是团队名称,因此路由器没有可以交给团队的内容。这次测量只保留模型的回答,不会把它们返回给调用方。
这一失败并不说明小模型永远无法完成路由。它说明的是:这个模型以这种方式提问时,不会返回团队。有两种不同的修正办法,我们依次来看。第 4 章对回答加以约束,使模型只能写出团队名称。第 5 章在模型之上训练一个分类头,使每个团队通过一次前向传播得到一个分数。本章两者都不做,所以它的路由器运行在替身录制的回答之上。
工作准则: 在让模型路由任何内容之前,先在固定样本上统计它的回答中是团队名称的数量,并把这个数量与样本大小比较。如果模型没有为每条消息都返回一个团队,就不要按现状用它来路由。要把它的回答约束在这些团队之内,或者针对该任务对它进行训练。把交接规则放在一个并非团队的回答之上,保护的是一个并不存在的团队。
粗糙的路由器在哪里出问题
粗糙的路由器在生产中会以四种方式出问题,每一种都会留下客服人员能看到的迹象。
第一种是出现不存在的团队名称。自由文本模型可能写出一个不在名单上的团队,或者写出一句话,而把这段文字原样转发的路由器,等于没有把消息交给任何人。替身模型的录制结果不会出现这种情况,因为它的语法只允许标签,但读者自己的模型可能会。迹象是答案不是团队名称,而无约束测试会统计答案中属于团队名称的数量。路由器应当把这样的答案视为错误,对其计数,并把消息交给人工处理。record_answers 已经会在这种情况下抛出错误,路由器也必须这样做。
第二种是漂移。替身模型的答案只对录制时所用的文件、提示词和样本成立。录制清单记录了文件的 SHA-256、提示词的哈希值、解码方式和样本,因此其中任何一项发生变化,得到的都是另一份录制。读者如果发现代码没有改动而分数发生了变化,应先对比清单,再对比提示词。
第三种是阈值不再适用。在某一个开发集划分上选定的阈值,可能在消息构成变化后不再适用。迹象是在新的开发消息上衡量路由器时,转人工率或未转人工消息上的准确率发生了偏移。第 5 章会把阈值与选定它时所用的开发集划分一并记录,使银行能够看到这个数字是针对什么拟合的,而第 9 章会监测这种偏移。
第四种是成本和人员负担。托管模型按每次调用计费。银行自己运行的路由器则按自己机器上的计算量计费,第 3 章会按词元数和前向传播次数统计一条消息的成本,而第 10 章会把记录下来的速度换算成账单。每一次转人工都是人的工作量,转人工率就是这部分工作量所占的份额。我们建议在每一份关于路由器的报告中,把转人工率与准确率并列写出,这样标记的成本就不会被遗漏。
不能说明自己何时拿不准的路由器会掩盖自己的错误,而标记使这些错误可以被统计。本章作出了以下决定。后续各章会沿用这些决定,或者修改并说明理由:
- 路由器返回团队、置信度和转人工标记,每一条返回团队的路径都要经过
handoff。 - 在第 5 章于开发集划分上选定阈值之前,阈值只是一个占位值。
- 每个路由器都在同一份固定样本上,按准确率、转人工率和未转人工消息上的准确率评分,并在每项旁附上计数。
- 替身模型是基线,其答案是录制下来的。读者自己的模型以同样的方式用
record_answers记录其答案。 - 不能为每条消息都返回团队的模型,还算不上路由器。
本章,在本版次中
版次 2026.11.9示例于 2026年11月20日 通过本章 4个示例 个示例中有 4 个通过
译自英文版图书,版次 2026.11.9。