← DSPy From First Principles

无法度量,就无法优化

定义指标、冻结评估协议、测量程序——然后看清为什么一个可度量的目标会让错误的行为变得系统性地可优化。

第 7 章产出了材料。本章产出证据。

这让优化成为可能。但它还没有让优化变得安全。

没有指标
    → 没有系统性的优化

有指标
    → 行为可以被优化

错误的指标
    → 错误的行为可以被系统性地优化

本章确立搜索得以运作的那片表面。第 9 章则追问:当指标变成目标时,这片表面奖励 的究竟是什么。

    flowchart TD
    P[冻结的程序] --> E[评估]
    C[冻结的样例] --> E
    M[指标] --> E
    E --> PC[逐样例结果]
    PC --> AG[聚合结果]
    PC --> FI[失败检视]
  

这里没有发生任何优化。注意,逐样例结果喂给两种解读——聚合值与失败检视——而本 章的发现来自第二种。问题很窄:

这个冻结的程序在这套冻结的协议下表现如何?

结果证明,答案不如我们在计算它的过程中发现的东西有趣。聚合数字没问题。逐样例的 拆解里藏着一个缺陷,它塑造了接下来的九章。


1. 基线是身份,不是数字

基线不是"代码昨天跑出来的随便什么结果"。它是一个程序身份、一个模型身份、一个数 据集身份、一个指标身份,外加一套协议——其中任何一样缺失,这个数字日后就无法与任 何东西比较。

BASELINE_IDENTITY = {
    "program_id": "EditorialRewriteProgram",
    "module_strategy": "analyze_predict__rewrite_predict__assess_predict",
    "model_provider": "Ollama",
    "model_name": "qwen3:latest",
    "dataset_id": "book-editorial-corpus",
    "split_role": "dev",
        "metric_name": "editorial_metric",
    "metric_version": "v1",
    "optimization_allowed": False,
}

在真实系统里,这条记录是生成的,从不手打。生成出来的版本覆盖程序指纹、数据集指 纹、划分指纹、provider 与 LM 配置指纹、指标指纹、DSPy 版本、seed、预算与源码修 订。

这组东西在本书里有一个名字:评估协议指纹。它存在的意义,是让下面这句话变得 有意义:

一个在不同协议下报告更高数字的候选,并没有击败这个基线。它跑的是另一个实验。

这听起来像学究气,直到第 12 章:某个优化器报告了一次收益,而要知道它是否真实的唯 一办法,就是确认基线与候选是由同一个函数、在同一批样例、在同一模型配置之下打分 的。


2. 指标:一道硬门槛与一个结构分数

指标分两个阶段,而第一个阶段根本不是分数。

**第一阶段是一道确定性硬门槛。**在冻结的 v1 实现中,它检查两条不可商量的词汇约 束:每个必需实体必须仍然在场,任何禁用词都不得出现。它的回答是二值的。

这比*“输出可用吗?"*要窄。空输出、句子数量、过长以及其他形状问题,由打分或校验路 径的别处处理。让这条确切的边界保持可见很重要,因为第 9 章将攻击这道门槛不知道 如何去检查的东西。

import re

def contains_term(text: str, term: str) -> bool:
    if " " in term.strip():
        return term.lower() in text.lower()
    return re.search(rf"\b{re.escape(term.lower())}\b", text.lower()) is not None

def passes_hard_gate(example, candidate: str) -> bool:
    required_ok = all(
        contains_term(candidate, entity)
        for entity in example.required_entities
    )
    forbidden_ok = all(
        not contains_term(candidate, term)
        for term in example.forbidden_terms
    )
    return required_ok and forbidden_ok

在这套协议下,一个丢掉必需实体或输出禁用词的改写不会被当作略差。它得零分。

这是一个策略选择,不是指标的普遍属性。有用的区分在于:门槛编码的是取消资格, 而加权分数给仍然合格的候选排名。如果你判定实体失败即取消资格,就不要让无关的流 畅度分数把它赎回来。

第二阶段给通过门槛的部分打分,方式是三个分量的加权和:

score = 0.35 · changed    (程序到底编辑了没有?)
      + 0.25 · scope      (是否与任务保持相称?)
      + 0.40 · overlap    (与参考改写有多接近?)

权重之和为 1.0,但这些分量的名字比它们的实现更大方。

changed 是二值的:经过 token 归一化之后,候选要么与源文本不同,要么相同。

scope 也是二值的。对于空候选,或长度超过 max(original_tokens + 4, 1.35 × original_tokens) 的候选,它返回零。它并不惩罚激进的缩短,除非候选变为空。

overlap 是非对称的参考 token 召回率:

|tokens(reference) ∩ tokens(candidate)| / |tokens(reference)|

额外的候选 token 不会直接降低它,词序也不重要。

这就是 v1 版本的 editorial_metric。它是确定性的、便宜的、可检视的,因而有用。它同 时也是一个刻意不完整的代理。第 9 章将利用的,恰恰是你在这些定义中已经能看到的那 些不对称。

现在先记下一件事,因为它在第 6 节会变得重要。去掉 changed 项,你会得到:

0.25 + 0.40 = 0.65

**当 scope 通过、参考重叠完美时,未改动候选的得分就是 0.65。**换言之,如果参考答 案本身说的是这个句子原样保留,那么正确的恒等输出在构造上就输掉了整个 0.35 的 changed 分量。

这个数字后面会频繁出现。


3. 运行它

DSPy 的评估器接受一个开发集和一个指标,返回一个聚合值加上逐样例结果。

import dspy
from common.metrics import editorial_metric

def dspy_editorial_metric_v1(example, pred, trace=None) -> float:
    return editorial_metric(example, getattr(pred, "rewritten_text", ""), version="v1").score

def evaluate_baseline(program, examples):
    evaluator = dspy.Evaluate(
        devset=examples,
        metric=dspy_editorial_metric_v1,
        display_progress=True,
        display_table=False,
        failure_score=0.0,
    )
    return evaluator(program)

两个命名决定值得解释,因为它们都是我们必须改正的错误。

这个指标叫 editorial_metric,它把 version 作为没有默认值的必填参数。更早的草 稿给其实只有两个函数的东西起了四个名字——editorial_metric、 editorial_metric_v1、score_editorial_output、score_editorial_output_v1——外加 一个默认版本,这意味着默认值一动,调用点的含义就会悄无声息地改变。现在版本在每个 调用处都是显式的。

面向 DSPy 的包装器是 dspy_editorial_metric_v1,而不是 dspy_editorial_metric。当 第 10 到 13 章把一个指标交给优化器时,被优化所针对的版本是关于那一次运行最要紧的 一个事实,它应当在调用处就清晰可读:

optimizer = dspy.BootstrapFewShot(metric=dspy_editorial_metric_v1)

读到这一行的人,不必猜被最大化的是什么。


4. 我们测量了什么

冻结的 EditorialRewriteProgram,在 11 个样例的开发划分上,使用规范的本地 Qwen3/Ollama 依赖。

在规范开发样例 ed-003 上,程序产出:

“I don’t think we should go there,” Anna said, “because it’s unsafe.”

分数:0.877,在我们做过的每一次运行中都稳定到小数点后三位。延迟约 5.45 秒。

开发集聚合值:

运行 开发集均值,v1 开发集均值,v2
第一次 0.7893 0.7893
第二次 0.7992 0.7992

基线约为 0.79。

这个措辞是刻意的。两次报告的、程序状态未改动的执行,产出的开发集均值分别为 0.7893 和 0.7992,观察到的跨度约为 0.010。第 6 章说明了为什么我们不该把这个跨 度晋升为一个普适的 ± 噪声常数:全新会话的漂移与会话内的顺序效应都是测量过程的一 部分。

因此,把 0.7893 报告为那个基线,就是给了这个点估计超出它实际拥有的权威。

拿它跟被替换掉的那个夹具比:后者报告的是 0.8769230769——用十位小数描述关于 Anna 的一个句子。这些数字在"算术确实产生了它们"的意义上是真实的。它们并不是十位小数的 证据。

本书往后沿用约 0.79,而机器产物保留完整精度,重复运行保留它们的确切数 值。一个候选只有在一次配对比较表明它的差值扛过了评估过程的可变性之后,才配得上 改进这个词。

ed-003 上的两个确定性合理性基线:

基线 分数
不编辑 0.6500
机械的 and then → 逗号规则 0.6500
EditorialRewriteProgram 0.8769

在 ed-003 上,这条机械规则是空操作,因为句子里没有 and then,于是它退化成 与"不编辑"基线相同的输出。

这些是评测框架层面的检查,不是认真的竞争者。它们表明确定性指标路径按预期执行,也 表明 LM 程序在这一行上能够高于一个未改动的候选得分。它们并不证明任意一次机械 编辑值 0.65,也不证明 0.65 普遍意味着质量差。

还有一个结果,我们没有预料到、而其实应该预料到:在这两次报告的开发基线运行中, v2 与 v1 逐样例相等。语义评审器在那些基线输出上没有记录到任何被违反的约束。

回想一下 v2 改了什么。它保留同样的硬门槛和同样的结构分数,然后施加一个来自评审器 的语义因子;如果任何明写的语义约束被违反,最终分数就被封顶在 0.30。因此与 v1 一 致意味着,在这些特定的基线运行里,语义分量没有可罚之处。

这让 v2 的有用方式不同于一把更细的尺子。在迄今为止的测量中,它的表现像一条绊 线:普通的基线输出让结构分数纹丝不动,而诸如 ed-025 以及后来的 ed-035 这类具 体的语义回归,则让两个指标迅速拉开距离。

这是本实验中的一个经验模式,并不保证 v2 只在优化之后才会出现分歧。将来任何违反某 条具名语义约束的基线输出同样会触发它。


5. 聚合值藏起了所有有趣的东西

两个程序可以都得 0.75:

程序 A:大体不错,有一个无效输出
程序 B:始终有效,悄悄改掉实体名

均值区分不了它们,而这个差别恰恰是唯一要紧的东西。因此运行器会存储逐样例证据—— 输出、分数分量、provider 与配置身份、延迟、token,以及这个结果是否够格作为模型证 据。

def unpack_evaluation(result) -> list[dict]:
    return [
        {
            "case_id": example.case_id,
            "target_failure": example.target_failure,
            "score": float(score),
            "prediction": {
                "rewritten_text": getattr(prediction, "rewritten_text", None),
                "rationale": getattr(prediction, "rationale", None),
                "risk": getattr(prediction, "risk", None),
            },
            "reference": {
                "reference_rewrite": example.reference_rewrite,
                "required_entities": list(example.required_entities),
                "forbidden_terms": list(example.forbidden_terms),
            },
        }
        for example, prediction, score in result.results
    ]

第 7 章的 target_failure 字段现在证明了自己的价值。按它分组,一个数字就变成了一 次诊断:

目标失败 开发样例数 均分
semantic_drift 2 0.938
entity_change 2 0.825
style_failure 3 0.808
constraint_violation 1 0.782
invalid_output 1 0.650
unnecessary_edit 2 0.650

约 0.79 的聚合值藏起了分数从何而来。这一次运行的分组表显示,有两个开发类别恰好 落在 0.650。

但 0.650 没有唯一的解释。对其中一个类别,它反映的是一个未能取得有用进展的输出; 对下面的克制样例而言,同一个数字可能就是施加给一个正确恒等决定的算术惩罚。

这个歧义本身就是证据,说明聚合值需要有逐样例记录相伴左右。


6. 下限,以及指标表示不了的东西

两个类别因为完全不同的原因被钉在"什么都不做"的下限上。一个是程序的失败。另一个 是指标的失败,而且是我们的失败。

invalid_output 落在 0.650,是这次开发运行中程序一侧的失败。这个样例被设计出 来演练输出形状风险,但冻结的 v1 硬门槛实际上并不检验总体的输出形状;它只检查必需 实体和禁用词。

所以一个候选可以活着通过门槛,却仍然落在结构下限上。target_failure 标签告诉我们 这个样例被设计出来探测什么;分量记录告诉我们指标实际观察到了什么。

unnecessary_edit 落在 0.650 则不同。这一类别中的两个开发样例 ed-034 和 ed-037 带有恒等参考:正确的参考输出就是源句子本身。

对任何这样的恒等参考样例,一个正确地保持句子不变的程序得分为:

changed:  0     (什么都没改——正确)
scope:    1.0   (完美——正确)
overlap:  1.0   (与参考完全一致——正确)

score = 0.35·0 + 0.25·1 + 0.40·1 = 0.65

对恒等参考样例而言,指标在构造上就把一个正确的未改动输出封顶在 0.65。changed 分量占分数的 35%,而它为"编辑"付酬,全然不管编辑是否是必需的。

完整语料库包含六个标记为 unnecessary_edit 的样例,但这个标签并不意味着六条参考 都与源文本字节相同。有些要求的是克制或最小干预,而不是字面上的恒等。因此,这个缺 陷更准确的表述是指标的一个属性:每当"不改"才是正确答案时,v1 没有办法补上缺掉 的那 0.35。

这是第 2 章的问题如期而至。契约没有为*“无需编辑”*设置显式的语义状态,而指标独立 地编码了一个先验:改动文本永远值几分。这两个设计选择会相互叠加:一次不必要的编辑 可能分数高过一个"让句子原样保留"的正确决定。

第 18 章从另一个方向发现同样的张力:字面的参考拦截与那些"可接受答案可以等于参考” 的样例相撞。这个教训会继续传播,因为表示、指标和泄漏策略都对"一次合法的编辑必须 长什么样"做了假设。

我们没有在看到这个缺陷之后悄悄修理 v1。一旦第 10 到 13 章对着一个冻结的指标去优 化,改动它的权重或添加一个特例,就会制造出另一次实验,并使与已记录运行的直接比较 失效。

这并不意味着这个缺陷对比较是中性的。一个编辑了恒等参考样例的候选可以拿到那 0.35 的 changed 积分,因此排在一个正确拒绝编辑的候选之上。v2 继承了同样的结构配 比,所以它的语义评审器也修不好这个特定的激励。

像样的修复需要一个新的指标版本——理想情况下,它要显式地为是否编辑这个决定打 分,而不是假定改动总是可取的——随后还要一轮新的实验周期。

对本轮而言,我们冻结这个缺陷,把它公布出来,并在解读后续分数时让它的方向保持可 见。

一个缺陷被记录在案的指标,比一个缺陷没有记录的指标更有用。但请注意发生了什么。 在第 9 章刻意攻击这个指标之前,对逐样例表格的例行检视已经找到了一处:目标函数在这 里编码了错误的偏好。


7. 确定性检查能抓到什么

并非每个失败都需要模型才能发现。出人意料的是,生产环境中的文本失败里有大量是便 宜而乏味的字符串问题,在评审器介入之前把它们抓住,既省成本又去噪声:

辅助文本泄漏进了输出
响应里出现提示词片段
TODO 或占位符标记
纯文本字段里出现 markdown 残留
引号不配对
句末标点被改动
返回了不止一个句子
长度与原文完全不成比例

其中每一项都有一个确定性的成分,因此没有一项仅仅为了检测其表面形式就需要一个 LM 评审器。

这并不意味着冻结的 v1 硬门槛已经检查了所有这些;它没有。它的门槛仅限于必需实体和 禁用词。额外的确定性校验器可以放在打分之前,也可以成为未来的硬门槛规则,但添加一 个就会改变评估协议,必须做版本管理。

更普遍的规则是:如果某个属性可以被确定性地检查,而策略规定失败即取消资格,那么 就在软件里强制执行它,而不是让一个模型去重新发现它。

编辑程序的失败分类学,就是第 7 章那套 target_failure 词汇表。它在第 20 章的仓库 修复类比有着相同的形状:

补丁无法应用
测试仍然失败
改动了无关文件
校验不可用
候选由回退路径产出

评估是这些东西变得可见的地方——而这句话成立的前提,是你存储了足够多的逐样例细节 才看得见它们。


通常会出什么错

症状 可能原因 如何诊断 改什么
基线无法复现 程序、模型、数据或协议身份没有被记录 比较运行清单与指纹 持久化完整的评估协议
指标改动之后,候选看起来更好了 基线与候选在不同的协议下运行 比较协议指纹 在两者一致之前,把该比较视为无效
评估在一个畸形输出上崩溃 指标假设预测总是格式良好 带上 traceback 重新运行 让指标具备防御性,并赋予一个失败分数
聚合值看着不错,用户却在抱怨 指标太窄,看不到这种失败 按预期失败模式对逐样例分数分组 添加能看见用户所注意到的东西的分量
一整个类别停在同一个精确值上 某个指标分量或下限可能主导了这个类别 把这个值分解成各分量权重,并检视那些样例 在新的指标版本中修复它,或公布这个缺陷及其方向
分数被引用到很多位小数 算术精度与证据精度被混为一谈 在真实的执行安排下重复运行同一个冻结程序 在产物中保留完整精度;正文用适当舍入的数字加上重复运行的值
优化在基线存在之前就开始了 评估与优化被搅在了一起 查找早于基线记录的候选状态 先冻结基线

本章小结

我们有了一个冻结的基线:一个具名程序、一个带显式版本的具名指标,以及一套打了指 纹的协议。两次报告的执行把它的 11 样例开发集均值定在 0.7893 和 0.7992,所以正 文层面的基线是约 0.79,而不是一个神圣的四位小数。ed-003 仍是一个好用的讲解样 例,约 0.877,而在那些报告的基线运行中,v2 与 v1 逐样例一致。

本章有两样东西比这个数字走得更远。

第一,聚合值是我们算过的东西里信息量最少的。按预期失败模式分组,把约 0.79 变成 了一次诊断,而这次诊断暴露了一个缺陷:两个开发 unnecessary_edit 样例恰好停在 0.650。

这不是巧合。在恒等参考样例上,未改动的候选拿到全部的 scope 与 overlap 积分,却输 掉整个 0.35 的 changed 分量。更宽泛的六样例 unnecessary_edit 类别并非全部都是恒 等参考,所以正确的一般性主张是结构性的,而不是数值性的:v1 系统性地低估了那些 “克制才是正确决定"的样例。

第二,是这对整件事意味着什么。我们用确定性分量搭建 v1,并在它的加权分数前面放了 两道显式的取消资格检查。这仍然留下了门槛不检查的属性,以及一个可能奖励错误行为的 changed 项激励。

我们发现其中一个缺陷,靠的是读一张分组表,而不是什么聪明的对抗技术。

所以显而易见的问题是:里面还有什么。

我们移除了"优化可以在测量之前开始"这一假设,也移除了"更大的数字就能击败基线、无 论产出它的协议是什么"这一假设。

留下的是指标本身,到目前为止我们大多只是使用它,而不是质疑它。第 4、5 章的质量比 较依赖它的 v1 结构分数,而各优化章节会有意地对着那个冻结的目标进行搜索。

我们现在知道了一处目标函数出错的地方——在优化器甚至还没碰过它之前。它剩下的唯一 限定理由,不能是"这是我们写的”。

那不是一个足以让人信赖它的好理由。

当测量不再是一个观察者,而变成搜索的目标时,会发生什么?