编译程序
把 DSPy 编译当作冻结边界之下的候选生成——然后去看优化器实际读了什么,并发现扩大语料库并没有给本章买来任何东西。
第 9 章给了优化器一个显式的目标,并展示了一个具体的局限:v1 会给那些颠倒了源文本含义中 重要部分的候选打出非常高的分数。
我们还是要对着那个冻结的指标去编译。不是因为这个局限可以接受,而是因为现在改动目标会改 变这个实验。v2 作为一道独立的语义检查,继续留在主搜索循环之外。
DSPy 中的编译接收一个程序、训练证据、一个指标和一个优化器,返回一个候选程序状态。
flowchart LR
PR[程序] --> CO[编译]
TE[训练证据] --> CO
ME[指标] --> CO
OP[优化器] --> CO
CO --> CA[候选程序状态]
这不是机器码意义上的编译。Python 架构原封不动;改变的是面向 LM 的状态——示范、指令和其 它提示词参数,具体哪些取决于优化器。
本章讲的是围绕这个操作的边界,而且刻意不对候选的质量做出任何主张。那要到第 11 章。
第 10 到 13 章合在一起,保存了第 9 章那份阴性对照总结背后的机制级记录:每个优化器能改动 什么、消费了哪些证据、代价是什么,以及为什么一次搜索目标上的成功并不足以构成编辑改进的充 分证据。这些细节很重要,因为同样的机制之后可以在一个正确性可以被外部执行的任务里接受检验。
它确实产出的,是一个我们并没有去找的发现:把语料库从四个案例扩充到四十四个案例,改变了编
译可获得的证据量,却没有改变这个 BootstrapFewShot 配置实际消费的证据量。
这并不是说"更大的语料库什么也没买来"。正是更大的语料库让这次消费失败变得可见。
1. 基线与候选是不同的对象
先在跨过边界之前把边界说清楚:
EXPERIMENT = {
"experiment_id": "book-edit-exp-001",
"baseline_program": "editorial_rewrite_program",
"baseline_version": "0.1",
"optimizer": "BootstrapFewShot",
"optimizer_config": {
"max_bootstrapped_demos": 2,
"max_labeled_demos": 0,
"max_rounds": 1,
},
"train_case_ids": TRAIN_IDS, # 26 cases, 7 families
"dev_case_ids": DEV_IDS, # 11 cases, 3 families
"holdout_case_ids": HOLDOUT_IDS, # 7 cases, 2 families — not passed to compile
"metric": "editorial_metric_v1",
}
候选是一个提议,不是一个替代品:
flowchart TD
B[基线 v0.1] --> C[在允许的数据上编译]
C --> V2[候选 v0.2]
V2 --> EV[在冻结协议下评估]
EV --> DEC{接受、拒绝,还是继续调查?}
候选是一个提议,不是一个替代品。这个区别有一个名字,它会一路贯穿到第 19 章:
优化器负责提出。它不会晋升自己。
这听起来显而易见,却经常被违反,通常出于方便而非意图——比如一个脚本编译完直接把结果写进 生效中的程序路径,因为另一种做法需要多一步,而没人有时间去实现它。
2. 最小编译形态
import dspy
def compile_candidate(trainset):
baseline = EditorialRewriteProgram()
optimizer = dspy.BootstrapFewShot(
metric=dspy_editorial_metric_v1,
max_bootstrapped_demos=2,
max_labeled_demos=0,
)
return optimizer.compile(student=baseline, trainset=trainset)
注意这个指标的名字。第 8 章把面向 DSPy 的包装器改名为 dspy_editorial_metric_v1,正是为
了让这一行毫不含糊地说明被最大化的是哪个版本。第 11 和 12 章的全部论证都取决于它是 v1。
不同优化器接受的数据不同。BootstrapFewShot.compile 接收 student、一个可选的 teacher
和 trainset——没有验证集。MIPROv2 接收一个 valset,并用它在候选之间做选择:
optimizer = dspy.MIPROv2(metric=dspy_editorial_metric_v1, seed=13)
candidate = optimizer.compile(student=baseline, trainset=trainset, valset=devset)
在这些 API 差异底下,稳定的规则关乎声明的证据访问权限,而不是划分的名字:
训练证据 可以用来构造候选状态
开发证据 当协议允许时,可以用于候选选择
保留集证据 在整个实验周期内被排除在优化之外
我们在标准的本地 Qwen3/Ollama 依赖上用 DSPy 3.3.1 跑了这一切。编译产生了六条 LM 历史记 录,消耗了 2,025 个 prompt token 和 441 个 completion token,合计 2,466 个。 返回的候选带着六条示范,在这个三阶段程序里每个 predictor 两条。
候选状态本身记录了装入了哪些示范,所以这个重要结果并不只依赖 token 的算术:三个 predictor 全都收到了自举出来的示范,来源都是同样那前两个训练示例。
这就是编译证据。它确立了在声明的边界之下发生了一次状态转移。它对候选是否更好一言不发。
3. 前后审计
编译应当留下一条痕迹,而这条痕迹需要三条记录,不是两条。
def program_state_for_record(program) -> dict:
if hasattr(program, "dump_state"):
return program.dump_state()
return {"class": program.__class__.__name__, "repr": repr(program)}
def compile_with_audit(trainset, devset, holdout):
baseline = EditorialRewriteProgram()
before = program_state_for_record(baseline)
optimizer = dspy.BootstrapFewShot(
metric=dspy_editorial_metric_v1,
max_bootstrapped_demos=2,
max_labeled_demos=0,
)
candidate = optimizer.compile(student=baseline, trainset=trainset)
return {
"baseline_before": before,
"baseline_after": program_state_for_record(baseline),
"candidate_state": program_state_for_record(candidate),
"visible_train_ids": [e.case_id for e in trainset],
"reserved_dev_ids": [e.case_id for e in devset],
"excluded_holdout_ids": [e.case_id for e in holdout],
}
编译后的基线快照是人们会漏掉的那一个,也是真正要紧的那一个。写
candidate = optimizer.compile(student=baseline, ...) 看起来像一个返回新对象的纯函数。
那一行里没有任何东西保证优化器没有在途中改动 baseline。在两边都捕获基线的状态,就把这
个假设变成了一条被检查过的不变量。
我们实测的这次编译产生了三个状态指纹。前两个——编译前的基线和编译后的基线——完全相同。 第三个,即候选,则不同。生效中的基线持有零条示范;候选持有六条。
编译边界的不变量全部成立:
- 基线状态没有因编译而改变;
- 候选是一个独立的 Python 对象;
- 只有训练案例对这次优化器调用是可准入的;
- 开发集划分被保留,没有传给 compile;
- 保留集被排除在编译边界之外;
- 指标、provider 和 LM 配置的身份保持冻结;
- 没有发生任何晋升。
注意缺了什么:这些不变量里没有一条说明可准入的训练集实际被消费了多少。
optimizer_visible_train_ids 记录的是传给 compile 的集合;它是一条访问边界,不是一个覆
盖率统计。
当这两个概念被分开时会发生什么,就是第 4 节的内容。
编译后的 DSPy 状态可能不好检视,这正是 dspy-inspector 这类工具存在的原因。 把它当作一个信号,而不是一个依赖:持久化你自己的候选状态、指纹和运行记录,不要把生产契约绑定到任何检视器对框架私有结构的内部视图上。
4. 优化器实际读了什么
现在是出乎我们意料的那部分。
训练划分有横跨 7 个家族的 26 个案例。第 7 章刻意构建了那个语料库,因为更早的那个夹具 暴露不出足够的变化:第 5 章那个三个案例的消融支持过一个结论,而这个结论在更大的语料库上反 转了;第 8 章的旧基线则把评估压缩成一个开发集句子,还以荒唐的数值精度报告它。
这里的问题不一样。有更多可获得的证据,并不意味着某个特定的优化器配置会去消费它。
那么这 26 个案例里,BootstrapFewShot 看了几个?
两个。
在这次实测运行中,BootstrapFewShot 从 ed-001 和 ed-002 自举出合格的轨迹,然后就
到达了 max_bootstrapped_demos=2。之后的训练案例没有一个贡献出自举示范。
这种行为与优化器对所给训练集的贪心遍历一致:合格的轨迹不断累积,直到配置的示范配额被填 满。对这个有序的训练集来说,配额在前两个示例上就立刻被满足了。
案例 ed-005 到 ed-028——26 个训练行中的 24 个,横跨其余六个家族——没有为这个候选提供
示范,并且在配额被填满之后没有在编译历史里产生任何任务模型调用。
这包括 academic-abstract、news-report 和 legal-plain-language 三个家族。
最后一个包含 ed-025——第 4 章展示过,普通的 Predict 会在它上面犯语义错误的那个截止期
触发案例。
对证据要精确:这次运行确立的是,那些行没有参与到所观察到的自举轨迹收集中。它并没有确立
一个关于 BootstrapFewShot 在每种配置下可能执行的每一种内部操作的普遍主张。
三个值得带往后文的推论。
**列表顺序是候选生成的一部分。**这次运行中没有任何东西确立 ed-001 和 ed-002 是最有代
表性或最有启发性的示范。它们只是配额填满之前遇到的第一批合格示例。
这预告了一个有用的敏感性测试:打乱或刻意置换训练顺序,然后问被选中的示范和候选指纹是否改 变。我们没有在这里测量过那个实验,所以不要断言打乱之后一定会产生不同的候选。
这个工程教训并不依赖那次未跑的测试:如果贪心遍历能让顺序变得与决策相关,训练顺序就属于来 源记录的一部分,或者必须由协议把它中和掉。
**常规的编译结果并没有把训练覆盖率作为一项实验统计报告出来。**编译成功完成,返回了一个独 立的候选,报告了 token 用量,并通过了第 3 节里的每一条边界不变量。
我们自己的审计把全部 26 行都记录为优化器可见,因为它们被放进了训练集传入。这是正确的,但 不完整。候选状态显示六条示范来自两个案例,LM 历史里有六次编译调用——三个 predictor,跨那 两个示例。把这些记录放在一起,就暴露了可获得的证据与被消费的证据之间的差别。
教训不是 DSPy 藏起了一个错误。覆盖率只是我们的协议没有选择去测量的量之一。
**更多可获得的数据并不是万能的修复。**这是能推广出去的那一条。语料库扩充改变了前面几章的 结论,因为那些评估确实遍历了更大的夹具。而在这里,得到的候选仍然在两个训练示例之后就填满 了它的自举配额。
所以更大的语料库几乎没有改变候选状态的任何东西,但它改变了我们能从优化器身上学到的东 西。只有两个训练案例时,一个两个示例的配额看起来就像全覆盖。有二十六个时,同一个配额就显 形为那个起约束作用的限制。
当一个结果纹丝不动时,问两个分开的问题:
- 我们有足够的可获得证据吗?
- 这个算法和配置实际能用上其中多少证据?
收集更多数据只回答了第一个。
这个模式延续到了下一章。第 11 章把自举预算提高到每个 predictor 四条示范,它选中的示范
来自四个训练案例——ed-001、ed-002、ed-006 和 ed-007。那是二十六个训练行中的四
个,约 15%。
不要把这个百分比当作 BootstrapFewShot"数据用量"的普遍度量;它是对这次运行中进入已保存候 选的证据的描述。
第 12 章的 MIPROv2 有不同的搜索过程:它用训练和开发证据提出并评估多个程序状态,而不只是 填满一个自举配额。这就是为什么当我们解释是什么塑造了一个候选时,优化器的算法和预算 要与数据集大小并列。
所以在运行一个优化器之前,问它被允许访问哪些证据、它的预算让它有能力消费什么。运行之 后,检视哪些证据实际进入了候选生成。
一次严肃的优化器审计会区分可获得的证据、协议可准入的证据,以及这次运行实际消费 的证据。
5. 持久化候选状态
DSPy 程序可以保存和加载:
candidate.save("artifacts/editorial_rewrite_candidate.json")
loaded = EditorialRewriteProgram()
loaded.load(path="artifacts/editorial_rewrite_candidate.json")
保存下来的状态是必要的,但不充分。一个候选指纹告诉你状态与基线不同。它不告诉你哪个优化器 产生了它、哪些示例是可见的、哪个指标选中了它、哪个模型执行了编译,以及保留集证据有没有泄 漏进搜索。
所以在它旁边写一份清单:
import hashlib
import json
from pathlib import Path
def write_manifest(path: str, payload: dict) -> str:
blob = json.dumps(payload, indent=2, sort_keys=True)
fingerprint = hashlib.sha256(blob.encode("utf-8")).hexdigest()
Path(path).write_text(json.dumps({**payload, "manifest_fingerprint": fingerprint},
indent=2, sort_keys=True))
return fingerprint
这份清单回答:
编译的是哪个基线?
是哪个优化器、用什么配置产生了这个候选?
哪些案例 ID 对它是可准入的——而哪些真正参与了候选生成?
是哪个指标、在哪个版本下选中了它?
哪个模型和配置执行了这次编译?
哪个 DSPy 版本?
哪些案例保持未被触碰?
第 4 节就是这一行有两个半句的原因。**可准入与消费是两个不同的事实。**只记录传给
compile 的训练集,会让一次 26 中取 2 的运行看起来像一次 26 案例的优化。
6. 协议
编译是从第 8 章走到第 19 章的序列中的一步,值得把它整个看一遍:
冻结清单 (第 8 章)
审计语料库与划分 (第 7 章)
评估基线 (第 8 章)
攻击指标 (第 9 章)
在其允许的证据上运行一次声明的优化过程 ← 本章
持久化候选
审计候选完整性
在冻结协议下评估候选 (第 11–13 章)
执行保守的晋升策略 (第 19 章)
评估保留集,仅一次 (第 19 章)
持久化结果
这份清单的两个性质比它的内容更重要。
外部实验过程是单一且有边界的:一次声明过的优化器调用,带着声明过的内部预算,作用在声 明过的证据上,跑在冻结的目标之下。
这并不意味着优化器本身只做一次试验。MIPROv2 和 GEPA 按设计会在内部进行搜索;它们的试验次 数是声明的优化器配置的一部分。
多出来的那一层搜索出现在我们反复重跑整个优化过程、并留下最好那个候选、却不记录这次 N 选 一的时候。到那时,外部实验已经变成了一场在优化器运行之上的搜索,而任何被用来选出胜者的开 发证据,都被花费了比协议所允许更多的次数。
而晋升在最远的那一端,与编译之间隔着四章的评估。这个距离是刻意的。DSPy 能生成一个候选并 报告它的分数。它无法决定自己的候选是否可以安全部署,而任何允许它这么做的系统,都把提议与 晋升熔在了一起。
在本章中,我们不使用被保留的开发家族来确立候选的质量。编译和评估是两个分开的实验事件。
这里的这种分离是 BootstrapFewShot 特有的。后面的优化器(比如 MIPROv2)会显式地在自己的
搜索过程中使用开发证据,所以它们的编译后评估有着不同的含义,必须相应地记录。
7. 编译被允许改动什么
在运行任何东西之前先决定这件事:
| 组件 | 编译期间可以改动吗 | 原因 |
|---|---|---|
| 程序的 Python 代码 | 不可以 | 本实验只优化面向 LM 的状态 |
| 签名字段名 | 本实验中不可以 | 给字段改名会改变声明的契约 |
| 签名字段描述 | 被这些优化器配置固定住 | 它们在第 10–13 章所用的搜索面之外 |
| 签名文档字符串 / 指令 | 取决于优化器 | MIPROv2 和 GEPA 会改动指令;BootstrapFewShot 不会 |
| 示范 | 可以 | 这正是自举式优化器所选择的东西 |
| 指标 | 不可以 | 优化器正被它评判 |
| 模型配置 | 不可以 | 同时改动模型和程序会把一切都混淆 |
| 保留集案例 | 不可以 | 它们是你仅有的未被触碰的证据 |
指令那一行正是第 3 章警告过的。在本书使用的优化器配置里,字段名和描述被排除在搜索面之 外,而 MIPROv2 和 GEPA 被允许改动签名指令。
这是所声明的优化面的一个属性,不是"描述永远不可能改变"的普遍保证。另一个优化器可以选择 一个更宽的面。
所以最强的规则仍然是:
任何无论优化与否都必须存活下来的东西,都应当放进独立执行的验证或评估里,而不只是放进碰 巧被今天的优化器冻结住的自然语言状态里。
通常会出什么错
| 症状 | 可能原因 | 如何诊断 | 改什么 |
|---|---|---|---|
| 生效中的程序在编译后发生了变化 | 基线被就地改动了 | 比较编译前基线与编译后基线的指纹 | 两边都做快照;把编译输出当作产物对待 |
| 返回了一个候选就假定改进了 | 编译结果从未被检视 | 比较候选与基线的状态指纹 | 报告状态是否真的改变了,以及是怎么变的 |
| 加训练数据改变不了任何事 | 可获得的证据可能超过优化器预算所能消费的量 | 比较可准入的案例 ID、候选示范的来源和编译历史 | 先测量覆盖率;然后在有理由的情况下改动预算、排序策略或优化器 |
| 保留集案例影响了优化 | 划分边界在调用点没有被强制执行 | 记录传给 compile 的确切案例 ID,以及任何优化器侧的评估器 |
在每一次优化/搜索调用中排除保留集 |
| 候选无法被复现 | 保存的状态旁边没有清单 | 检视产物目录 | 持久化优化器、数据、模型、指标和协议的指纹 |
| 编译多次然后留下最好的 | 协议并不允许的选择压力 | 把编译运行次数与所报告的开发评估次数对照 | 声明运行的次数,或者把它当作一场搜索 |
| 优化器的分数被当成了部署批准 | 提议与晋升被熔在一起 | 查找向生效程序路径的自动写入 | 要求一个独立的评估与策略步骤 |
本章小结
编译如今发生在一个我们可以检视的边界之内。BootstrapFewShot 产生了一个候选,带着六条示范
和一个独立的状态指纹。生效中的基线没有改变。开发集划分保持保留,保留集保持被排除且未被检
视,也没有发生任何晋升。
会比本章更长久的发现是第 4 节。我们把横跨七个家族的 26 个训练案例传进了编译边界。已保存 的候选只从其中两个取得它的自举示范,因为配置的配额立刻就被满足了。
因此,更大的语料库做了两件不同的事。它没有迫使这个候选使用更多训练证据。但它让可获得 证据与被消费证据之间的错配变得可测量。
这就是那条普遍的教训。当一个结果拒绝动弹时,“收集更多数据"只是其中一个假设。在再次扩充 数据集之前,去检视算法、它的预算、它的遍历策略,以及真正塑造了那个候选的证据的来源。
我们移除了"优化器的输出应当替换生效程序"这个假设,也移除了"调用 compile 本身就是某样
东西改进了的证据"这个假设。本章确立的是受控边界之下的一个状态转移。它对质量什么也没有确
立。
这就把我们带到了从第 8 章一直推迟的那个问题面前。我们有一个基线,它所报告的开发集运行在 0.79 上下;一个候选,带着从两个训练案例自举出来的六条示范;还有一个 v1 目标,第 9 章 已经展示过它会给特定的语义颠倒打出高分。
这个候选真的有帮助吗?