← DSPy From First Principles

定义契约

把 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 看起来是免费的, 但没有任何实验为这个数字确立过校准的含义。一个能影响动作的字段,必须通过独立检 查挣得那种影响力;否则它表面上的精确就是一种负债。

我们移除掉的假设是:模型会理解我们的意思。它会对写下的东西做点什么,而那是另一 回事。

没有被动过的是执行。我们仔细规定了任务,却没有说一个模型该如何尝试它——这是刻意 的,因为正是这种分离让下一个问题终于可以被回答。

现在我们可以把契约完全固定,只改变策略。于是:

让模型在回答之前先推理,真的能产出更好的改写吗?它的代价又是什么?