定义契约
把 DSPy 签名当作任务契约来处理:审慎地选择字段名,决定什么该进入边界之内,在类型能够暴露失败的地方使用类型,删掉没有任何东西消费的字段。
第 2 章建起了一道边界,然后有意暴露了它的弱点。我们设计了当时可用的最自然的输
出字段——rewritten_text,一个替换句——却没能把*“无需修改”*表达成一个显式的决定。
从技术上说,模型可以原样返回原来的句子。契约无法告诉我们的是:这个原样输出到
底意味着有意克制,还是一次碰巧复现了输入的改写尝试。这一区分在后面四十四个实验
夹具(fixture)样例中的六个里事关紧要——约占语料库的 13.6%。拥有一个签名并没
有阻止这个错误。
所以边界的位置是对的,而那道边界上的契约还远远不够好。本章讲的就是这中间的 差别。
值得先说清楚的主张:签名不是外挂了类型语法的提示词模板。它是一份任务契约,而 和任何契约一样,昂贵的错误是你在签字时看不见的那些。后面的优化实验,在很大程 度上就是为本章所做的决定买单的记录。
flowchart LR
C[哪些区分会得到一个字段] --> E[模型能表达什么]
E --> O[指标能观察到什么]
O --> T[优化器分数的含义有多可信]
第 2 章缺失的*“无需修改”*字段就是这条链的缩影:一个契约从未命名的区分,变成了 指标看不见的区分,于是六个样例被打分时,克制与失败的改写被当成了同一回事。
1. 紧凑形式及其代价
DSPy 接受一种紧凑的字符串形式:
rewrite = dspy.Predict("sentence, goal, context -> rewritten_text, rationale")
这是一个真正的签名。它能用,能产出正确的字段;对于一次快速实验来说,它的仪式 感恰到好处。
把它与类形式作比较:
class RewriteSentence(dspy.Signature):
"""Rewrite one sentence to satisfy an editorial goal
while preserving meaning, entities, and voice."""
sentence: str = dspy.InputField(desc="The exact sentence to rewrite")
goal: str = dspy.InputField(desc="The local reason this sentence is being edited")
context: str = dspy.InputField(desc="Nearby prose needed to preserve continuity and voice")
rewritten_text: str = dspy.OutputField(desc="A replacement sentence, not a paragraph")
rationale: str = dspy.OutputField(desc="Short explanation of the edit")
在这个例子中,两种形式产出的是同样五个字段名。但它们承载的声明语义分量并不 相同。
紧凑形式是一个真正的 DSPy 签名,而且它仍然是普通的源代码:你可以把它赋给变量, 在 pull request 里对它做 diff,保存它产出的程序状态。但这个字符串只提供了字段 名。DSPy 只得从这些名字出发,生成默认指令、默认字段描述,以及隐式的字符串类型。
类形式把这些选择变成显式的。它给契约一个可复用的符号、一条刻意写下的指令、字段 级的描述,以及容纳更丰富类型的位置。这让评审变得更容易,因为读者能看到哪些语义 是被选择出来的,而不是被推断出来的。
单靠任何一种源码形式都不足以充当实验身份。一个叫 RewriteSentence 的类可以在两
次提交之间发生变化,就像字符串字面量一样。因此后面的章节会为实际执行的程序和签
名状态提取指纹。
当语义确实显而易见、或者你还在试探这个想法时,用紧凑形式。当字段含义、类型或来 源开始变得重要时,换用类形式。
2. 字段名是契约中持久的部分
字段名不是给人看的标签。DSPy 会把它们渲染进提示词,所以模型读得到它们,而且它 们会改变模型的行为。你可以直接验证这一点:
result = program(sentence=..., goal=..., context=...)
dspy.inspect_history(n=1)
这会打印出 DSPy 实际构造出来的提示词。值得尽早、频繁地这样做——它是 DSPy 里最有 用的一个调试习惯,能化解大部分"框架究竟替你做了什么"的神秘感。
一旦你接受模型会读这些名字,命名就成了设计工作:
| 弱字段 | 更强的字段 | 这个改动带来什么 |
|---|---|---|
text |
sentence |
固定工作单元。模型不再返回整段文字。 |
instruction |
goal |
要求的是意图,不是方法。是"写得更紧一点",而不是"删掉副词"。 |
context |
context 加一条划定范围的描述 |
指的是邻近的散文,而不是整部手稿 |
answer |
rewritten_text |
给下游代码一个稳定的字段,并命名它的内容 |
notes |
rationale |
标明这是一段解释,而不是随意的元数据 |
output |
rewritten_text + rationale |
调用方想要的两样东西,分开返回 |
接下来是容易被漏掉、却会改变你该如何分配精力的部分。
持久性是优化面(optimization surface)的一种属性。
在本书使用的优化器配置中,字段名与字段描述保持固定,而其他程序状态被允许变动。
BootstrapFewShot 改动示范。MIPROv2 搜索示范和签名指令。GEPA 提出指令变异。在
第 12 章实测的候选程序中,analyze 与 rewrite 指令发生了变化,而每一个字段名和
描述都保持不变。
这是我们所选优化面的一个经验属性,不是 DSPy 的定律。另一个优化器——或者普通的应 用代码——可以选择更宽的面。例如 DSPydantic 就刻意优化 Pydantic 的字段描述。因此, 一条描述仅仅因为紧挨着类型注解,就并不天然不可变。
这条分配规则用下面的说法表达会更有力:
- 明确决定优化器被允许改动程序的哪些部分;
- 在编译前后为该优化面提取指纹;
- 只有当该优化面被冻结时,才把稳定的任务语义放进字段与描述;
- 必须在任何优化之下都成立的正确性属性,放进确定性校验或评估标准。
如果指令是可变的,像"保留人物名字"这样的指令就处于风险之中。在我们这里跑的实验 中,字段描述更安全,因为描述在它们的搜索面之外。硬性实体门还要更强,因为候选生 成无法重写它。
有用的区分不是文档字符串与字段描述之别,而是可变的提案面与被独立强制执行的不 变量之别。
3. 什么属于边界之内
这条规则有两半。输入应当携带一个胜任的人类完成这项任务所需的语义信息;输出应当 携带下游软件行动或校验所需的信息。操作性元数据留在外面,除非它真的改变了模型必 须做什么。
对于本书中实测的改写程序,生成输入被刻意收窄:
sentence
goal
context
夹具还带有 required_entities、forbidden_terms、semantic_constraints 和
reference_rewrite。这些字段对评估和来源记录可用,但规范的 dspy.Example 只向生
成暴露 sentence、goal 和 context。
契约与偏好(preference)的区分在优化开始之前就很重要:
| 属性 | 角色 |
|---|---|
保留数字 30 |
契约:丢掉它就改变了主张 |
| 保留否定 | 契约:反转极性就改变了主张 |
保留 regularly |
当它限定主张的范围时是契约 |
| 听起来更顺一些 | 偏好:合理,但不是不变量 |
| 更倾向于短句 | 偏好,除非应用定义了硬性上限 |
偏好之间可以相互权衡。契约违反不应当消失在一个平均值里。如果某个属性既可计算又 不容商量,它就该属于确定性校验或一道硬性评估门,而不只是优化器可能重写的一段 散文。
这种分离是刻意的。评估器可以查看的数据,并不自动就是模型应该收到的数据。如果真
实应用在决策时刻需要一条显式约束,就把它加进生成契约,并记录这次改动。不要只因
为某条信息存在于这个样例上,就把评估器一侧的信息夹带进 context。
操作性元数据是另一类。它们不是任务输入:
database row id
HTTP request id
current retry count
UI tab name
optimizer run id
这些对应用很重要。它们不是任务输入;把它们放进签名,意味着模型会读到它们,并可 能据此行动。提示词里的一个重试计数,等于邀请模型在第二次尝试时毫无原则依据地 换一种 行为。
然后还有第三类,也是危险的那一类。
绝不要让评估信息变成任务输入。
参考改写、人类评审者的决定、校验结果、上一次运行得到的分数——这些都可以合法地待 在你的评估记录里。只要其中任何一项越界进入程序的输入,实验就被污染了,而且污染 的方向看起来像是成功。
这不是理论上的告诫。在第 18 章,我们为本书自己的程序搭建了一套刻意的泄漏
(leakage)测试套件:横跨 32 个合格样例的九种攻击变体,总计 288 次攻击执行。防火
墙阻断了全部 288 条被污染的路径。如果没有那道边界,其中 224 次攻击会抬高表面上
的分数,平均约 0.3856。
这个数字并不意味着我们可以把 0.3856 机械地加到一个诚实的聚合分数上——指标是有
界的,而且各个样例上的攻击并不相同。它说明的是一件更有用的事:能够接触到来自答案
的信息,其效应大到足以压过我们花上整章篇幅去测量的普通程序差异。一旦这种污染进
入程序,下游比较就不再是模型质量的证据。
这种泄漏一点都不稀奇。最常见的路径是一位好心的工程师把"类似的已批准编辑"加进 context 字段,而这些编辑恰好取自一张包含当前被评估样例的表。
因此,每添加一个字段,问三个问题:
一个胜任的人类执行这项任务时需要这个值吗?
下游代码要安全地行动时需要这个输出吗?
这个值可能包含、暗示或派生自答案吗?
如果第三个问题的答案不是干脆的"否",那么在你能解释它的来源、以及它为何不会泄漏 结果信息之前,这个值就不能作为生成输入。问题不在于这个字段方不方便,而在于模型 看到它之后,这次实验是否还意味着同一件事。
4. 类型让散文隐藏的失败显形
DSPy 签名使用普通的 Python 类型注解,它的适配器在格式化请求、解析响应时会用到
声明出来的结构。Literal、Optional、列表和 Pydantic 模型都可以作为任务接口的
一部分使用。
本书中最好的例子不是改写程序,而是我们在第 9 章构建、用来评估语义保持的那个 LM 评审器(LM judge):
from typing import Literal
import dspy
class SemanticConstraintJudge(dspy.Signature):
"""Decide whether a one-sentence rewrite still satisfies a single stated
requirement about meaning."""
original_sentence: str = dspy.InputField(
desc="The sentence before editing."
)
candidate_rewrite: str = dspy.InputField(
desc="The proposed one-sentence rewrite."
)
editorial_goal: str = dspy.InputField(
desc="What the edit was asked to achieve."
)
requirement: str = dspy.InputField(
desc="The single meaning requirement to check."
)
verdict: Literal[
"preserved",
"violated",
"unclear",
] = dspy.OutputField(
desc="Whether the rewrite satisfies the requirement."
)
reason_code: Literal[
"meaning_preserved",
"meaning_reversed",
"meaning_weakened",
"meaning_strengthened",
"entity_altered",
"scope_changed",
"register_changed",
"output_shape_invalid",
"cannot_determine",
] = dspy.OutputField(
desc="The primary reason for the verdict."
)
explanation: str = dspy.OutputField(
desc="One sentence explaining the verdict."
)
这里每个带类型的字段都配得上它的类型。verdict 有三个取值,于是不确定性被显式
地表达出来,而不是被强行压进成功或失败。这样指标就能决定 unclear 该付出多大的
代价,而不是让一个解析器偶然替它做出这个策略决定。
reason_code 有一个封闭的词表,因为重点就在于跨运行聚合、追问哪种失败模式在反复
出现。自由文本解释对诊断有用,却是很差的分组键。因此 explanation 保持为字符串,
供读记录的人看;而枚举提供机器可读的类别。
多出来的 editorial_goal 输入同样是刻意的。一次改写可以在语义上忠实于原文,却仍
然违反这次编辑被要求达成的目标;评审器需要足够的任务上下文来解读那条具名要求,
同时又不能看到参考答案。
把它与改写程序上形如 risk: Literal["low", "medium", "high"] 的字段相比。它看上
去很严谨。可要问一句:谁读它?如果没有人读,那它就是每次调用三个 token 的成本,
外加一个会漂移好几年而无人察觉的字段,因为从来没有任何东西检查它。
类型最有用的情形是:下游代码会对这个取值分支;否则无效取值会被默默接受;词表小 而封闭;又或者天然形状就是列表、数字或结构化对象。在开放式散文上,类型最没有 用。
两个诚实的告诫。类型不会让模型变得诚实——一个类型完好的 verdict 依然可能是错
的,这就是为什么第 9 章大部分篇幅都在校验评审器,而不是信任它。另外,当模型为一
个 Literal["low", "medium", "high"] 字段产出 "pretty safe" 时,具体的失败行为
取决于适配器和 provider:它可能在解析时暴露,也可能被强行转换掉。任何控制持久
化、排序或策略的字段,仍然需要在你自己的代码里做校验。
一个相关的案例研究。 DSPydantic 在这里恰恰有用,因为它是"字段描述天然固定"这一想法的反例。它明确 把 Pydantic 提示词和字段描述当作结构化抽取的一个优化面。
这印证了第 2 节,而不是与它矛盾。一条描述能够存活,只因为你选定的优化器不被允许 重写它。Python 类型可能保持不变,而围绕该类型的自然语言语义却可能大幅变化。
描述就是语义,不是装饰——它们是稳定的还是可优化的,必须成为一个显式的设计选择。
这些都不能让一个带类型的输出为真。一个通过 Pydantic 校验的发票日期仍可能是错的 日期;一个合法的枚举仍可能是错的分类。结构给了你一个校验的地方,但它不会替你完 成校验。
5. 每个字段都要有自己的职责
第 2 章许诺过这个问题,现在兑现:改写程序应该输出一个置信度分数吗?
直觉说应该。它就是一个浮点数,看起来很便宜,而且下游代码说不定哪天就想要拿它做 阈值判断。
第 1 章给我们的是一则警告,不是一项校准研究。它那两个示意性的失败输出,给一个被
改名的主角打了 0.88,给一段用力过猛的改写打了 0.94。这些例子并不证明模型置信
度在统计上与正确性不相关。它们证明的是一件更直接的事:由同一次生成调用产出的数
字,不是"输出是安全的"这一主张的独立证据。
模型也确实有足够的信息注意到 Jalen 变成了 Jason;原句就在它的输入里。失败
不在于接触不到信息。失败在于:没有任何东西确立了这个自报数字的含义、它是如何校
准的,以及 0.8 在不同样例、提示词、模型或程序版本之间是否有着相同的解释。
这就足以构成删除该字段的理由。在置信度拥有一套外部校准流程之前,持久化它就是在 邀请下游代码从装饰中制造权威:
if result.confidence > 0.8: auto_approve()
可以推广的规则是:
每个输出字段都要有自己的职责。任何能控制动作的字段,还需要独立的校验或校准。
把这条规则用在正在运行的程序上:
| 字段 | 职责 / 消费者 | 独立检查 | 结论 |
|---|---|---|---|
rewritten_text |
应用输出;评估目标 | 硬性门、指标、语义评审器 | 保留 |
rationale |
面向人的诊断上下文 | 无;明确不参与控制 | 保留,但绝不把它当作验收证据 |
confidence |
会诱导阈值判断 | 未确立校准含义 | 删除 |
risk |
当前没有消费者 | 没有校验策略 | 在应用把两者都定义出来之前,不要添加 |
因此,rationale 的存活并不是靠钻空子。它存活,是因为它的角色是观察性的,而不
是控制性的。人可以用它来理解程序尝试了什么,但系统不会因为这段理由听起来有说服
力,就去晋升、拒绝、持久化或路由一个候选。
这个区分才是有用的:信息性字段可以帮助解释行为;承载控制权的字段必须挣得 权威。
6. 契约也可能过强
反方向的失败是真实存在的,只是讨论得少一些。
class OverSpecifiedRewrite(dspy.Signature):
"""Rewrite the sentence in twelve to sixteen words using active voice,
one comma at most, no semicolons, no adverbs, and a stronger final verb."""
sentence: str = dspy.InputField()
rewritten_text: str = dspy.OutputField()
作为一次文字编辑约束的测试,没问题。作为通用的句子改写契约,它把一种编辑理论烤 进了任务边界,于是对每一个不那样写作的作者,它都将是错的。
三种过度指定的形式,它们看起来都像严谨:
| 失败 | 例子 | 它的代价 |
|---|---|---|
| 方法泄漏 | “一步一步思考,比较三种备选方案” | 你不再能干净地替换模块,于是第 4 章的比较变得无法解释 |
| 策略泄漏 | “置信度高于 0.8 就一律接受” | 应用的决策策略现在进了模型的指令里,无法被测试或审计 |
| 继承判断泄漏 | “使用此前批准的行文风格” | 一个先前系统的意见被编码成了任务真相,而没有人说得清它是什么 |
检验方法与第 2 章相同:如果你换了执行策略、换了模型、换了作者,这条子句还成立 吗?如果不再成立,它就不是契约条款。
还有一个更微妙的版本。在本书后面使用的优化面中,签名指令是可变的。因此,只放在 那些指令里的约束,可能被一个编译出的候选程序削弱或删除——只要这样做能改善搜索 目标。
在我们第 10–13 章的实验中,字段描述保持固定,但第 2 节刻意不把这一点当成普遍保 证。如果一条要求真的不容商量,最坚固的归宿是一道被独立强制执行的门或指标,而不 是任何可能被优化过程获准重写的自然语言指令。
7. 两份契约,而不是一份
DSPy 签名管辖的是 LM 边界。你的应用另有一道边界,把两者混为一谈是麻烦的常见来 源。
from pydantic import BaseModel, Field
class RewriteInput(BaseModel):
sentence: str = Field(min_length=1)
goal: str = Field(min_length=1)
context: str = ""
constraints: list[str] = Field(default_factory=list)
class RewriteOutput(BaseModel):
rewritten_text: str = Field(min_length=1)
rationale: str = ""
def validate_prediction(raw: dict) -> RewriteOutput:
return RewriteOutput.model_validate(raw)
它校验的是围绕程序的应用载荷,而不是直接校验一个 dspy.Prediction 对象。这个区
分正是要点。DSPy 的签名与适配器定义并解析面向模型的形状;Pydantic 则在持久化或
下游使用之前,强制执行面向应用的载荷。
没有任何一层能证明语义正确性。一个完全合法的 RewriteOutput 仍可能装着错误的实
体或被扭曲的主张。形状校验保护接口;硬性门、指标和语义评审器保护的是不同的属性。
这两道边界有重叠,但它们彼此不能替代。
通常会出什么错
| 症状 | 可能原因 | 如何诊断 | 改什么 |
|---|---|---|---|
rewritten_text 返回的是一段带评论的整段文字 |
输出范围只在语义上被声明,没有被强制执行 | 统计一次运行中的句子数和换行数 | 收窄字段描述;在应用边界强制形状 |
| 写在文档字符串里的约束在编译之后不再被遵守 | 指令会被优化器重写;文档字符串并不持久 | 把编译后程序的指令与原始指令做 diff | 把约束移进字段描述或指标 |
| 优化器分数出现大幅的突然跳升 | 评估信息到达了输入 | 检查是否有输入字段包含、暗示或派生自参考答案 | 删除它,然后跑一套泄漏测试(第 18 章) |
| 下游代码里全是回退分支 | 输出契约太松 | 统计每百次调用里缺失或无效的字段数 | 添加带类型的字段,或拆分过粗的字段 |
| 一个字段漂移了好几个月,没有人注意到 | 没有东西消费它,也没有东西校验它 | 对每个输出字段,大声说出它的消费者和校验者 | 删除它 |
| 程序遵循着过时的产品策略 | 策略被写进了签名里 | 在文档字符串里搜索部署规则和阈值 | 把策略移进确定性应用代码 |
本章小结
契约如今命名了模型消费什么、产出什么,而这些名字反映的是应用的概念,而不是写第 一个提示词的人图省事的便利。
本章有两件事值得带往后文,因为它们都不是标准建议。
其一是,持久性取决于优化被允许改动什么。在后面的实验中,示范与签名指令是搜索变 量,而字段名与描述保持固定。这使得字段比指令在这个程序里更稳定,而不是普遍不 可变。任何无论怎样优化都必须保持为真的东西,都该放在可变提案面之外,放进确定性 校验或一个独立做版本管理的指标。
其二是,输出字段并不会仅仅因为带了类型就获得权威。confidence 看起来是免费的,
但没有任何实验为这个数字确立过校准的含义。一个能影响动作的字段,必须通过独立检
查挣得那种影响力;否则它表面上的精确就是一种负债。
我们移除掉的假设是:模型会理解我们的意思。它会对写下的东西做点什么,而那是另一 回事。
没有被动过的是执行。我们仔细规定了任务,却没有说一个模型该如何尝试它——这是刻意 的,因为正是这种分离让下一个问题终于可以被回答。
现在我们可以把契约完全固定,只改变策略。于是:
让模型在回答之前先推理,真的能产出更好的改写吗?它的代价又是什么?