← DSPy From First Principles

用程序构建程序

用确定性 Python 组合若干 DSPy 模块,然后测量哪些中间阶段真正影响结果,以及这种拆分是否值回它的成本。

第 4 章固定了契约、改变了执行策略。这一章改变的是架构。

真实应用很少只由一次调用构成。一个编辑系统可能想先弄清楚一句话哪里有问题, 产出一个候选,评估这个候选是否有风险,再把整包内容交给某个负责存储的环节。

    flowchart LR
    I[输入] --> A[分析]
    A --> W[改写]
    W --> S[评估]
    S --> R[返回]
  

这就是被推介时的流水线:四个阶段排成一行,每个阶段喂给下一个。拆分是少数几 种被普遍当成显然正确的架构手法。更小的件、更清晰的边界、更好的调试——这张图 自己就能把自己推销出去。

我们把它搭出来并做了测量,结果值得写成一章。其中一个中间阶段对改写有可测量 的因果影响;另一个阶段则完全没有通回改写的因果路径。

因此有用的问题其实不是*“拆分有没有帮助?”,而是“图里哪条边改变了结果,哪 个阶段只是在观察它,以及每个阶段要花多少代价?”*。


1. 巨型提示词版本

拆分的替代方案是一次性把所有事情都要了:

Analyze this sentence, identify issues, rewrite it, assess risk,
explain your decision, and return JSON...

这种做法有时确实管用。但它很难调试:当最终的改写很差时,你无法说出这条指令 里究竟是哪一部分失效了:

上下文理解?
问题诊断?
改写生成?
风险评估?
输出格式化?

单个提示词把若干操作压进一个不透明的步骤。拆分给了你可以下手查看的地方。它 同时也带来了调用、延迟、schema 和集成面,所以问题不在于拆分是不是更干净—— 而在于中间状态值不值它所付出的代价。

这个问题有一个可以测量的答案,这正是本章的要点。


2. 三个小契约

import dspy

class AnalyzeSentence(dspy.Signature):
    """Identify edit issues and preservation notes for a sentence rewrite."""

    sentence: str = dspy.InputField(desc="One sentence to improve.")
    goal: str = dspy.InputField(desc="Editorial goal for the rewrite.")
    context: str = dspy.InputField(desc="Decision-time local context.")

    issue_summary: str = dspy.OutputField(desc="Concise explanation of the edit issue.")
    preservation_notes: str = dspy.OutputField(desc="Decision-time details that should be preserved.")

class RewriteSentence(dspy.Signature):
    """Rewrite a sentence using the analysis and preservation notes."""

    sentence: str = dspy.InputField(desc="Original sentence.")
    goal: str = dspy.InputField(desc="Editorial goal for the rewrite.")
    context: str = dspy.InputField(desc="Decision-time local context.")
    issue_summary: str = dspy.InputField(desc="Analysis of the edit issue.")
    preservation_notes: str = dspy.InputField(desc="Details to preserve.")

    rewritten_text: str = dspy.OutputField(desc="One rewritten sentence.")
    rationale: str = dspy.OutputField(desc="Brief reason for the rewrite.")

class AssessRewrite(dspy.Signature):
    """Assess risk in a proposed rewrite."""

    sentence: str = dspy.InputField(desc="Original sentence.")
    rewritten_text: str = dspy.InputField(desc="Candidate rewritten sentence.")
    goal: str = dspy.InputField(desc="Editorial goal.")
    context: str = dspy.InputField(desc="Decision-time local context.")

    risk: str = dspy.OutputField(desc="Risk level: low, medium, or high.")
    assessment: str = dspy.OutputField(desc="Brief explanation of preservation risk.")

RewriteSentence 是第 2 章到第 4 章的那个签名(Signature),现在带着分析阶段 提供的两个额外输入。第 4 章把它们传成空字符串,而这恰好就是我们在第 6 节用作 基线的 BLANK 条件。

这是三个程序边界,不是三个提示词。每一个都有自己的输入、自己的输出,以及自己 会失效的地方。


3. 在自定义模块里组合它们

class EditorialRewriteProgram(dspy.Module):
    def __init__(self) -> None:
        super().__init__()
        self.analyze = dspy.Predict(AnalyzeSentence)
        self.rewrite = dspy.Predict(RewriteSentence)
        self.assess = dspy.Predict(AssessRewrite)

    def forward(self, sentence: str, goal: str, context: str = "") -> dspy.Prediction:
        analysis = self.analyze(sentence=sentence, goal=goal, context=context)

        rewrite = self.rewrite(
            sentence=sentence,
            goal=goal,
            context=context,
            issue_summary=analysis.issue_summary,
            preservation_notes=analysis.preservation_notes,
        )

        assessment = self.assess(
            sentence=sentence,
            rewritten_text=rewrite.rewritten_text,
            goal=goal,
            context=context,
        )

        return dspy.Prediction(
            rewritten_text=rewrite.rewritten_text,
            rationale=rewrite.rationale,
            risk=assessment.risk,
            assessment=assessment.assessment,
            issue_summary=analysis.issue_summary,
            preservation_notes=analysis.preservation_notes,
        )

这和第 2 章里的 EditorialRewriteProgram 是同一个,它的外部契约没有变化。调用 方仍然传 sentence、goal、context,也仍然读 rewritten_text。内部从一次 LM 调用变成三次,而上游什么都没有察觉——这正是第 2 章对模块边界许下的承诺,如今 兑现了。

仔细看数据流,因为它在第 7 节很重要。

    flowchart LR
    A[分析] -->|issue_summary, preservation_notes| W[改写]
    W -->|rewritten_text| R[返回的句子]
    W --> S[评估]
    S -.->|risk、assessment,被返回但未被使用| D[无重试、拒绝或分支]
  

分析喂给改写。改写同时喂给评估和被返回的句子。而评估没有喂给任何能改变输出 的东西:它产出 risk 和 assessment,程序把它们返回出去,却没有任何代码路径 会用这两个值去改变最终被返回的那句话。


4. 不是所有东西都该是一次 LM 调用

一个 DSPy 模块装普通 Python 装得和装预测器一样自在,而有些问题根本不该到达模 型:

def has_same_terminal_punctuation(original: str, candidate: str) -> bool:
    return original.rstrip()[-1:] == candidate.rstrip()[-1:]

def too_much_change(original: str, candidate: str, limit: float = 0.6) -> bool:
    before = original.split()
    after = candidate.split()
    delta = abs(len(after) - len(before))
    return delta / max(len(before), 1) > limit

这些很粗糙,但它们说明了这条边界。如果一个问题可计算,就去计算它。不要花一次 网络往返和 400 个 token 去问语言模型两个字符串是否以相同的字符结尾,而且当你 真的问了,也不要信它的回答。

LM:
  提出措辞

Python:
  路由、校验、存储、哈希、比较、执行策略

这条分工一路向上都成立。在第 8 章,硬门是纯 Python:要求的实体必须保持存在, 禁止的词必须保持缺席。其他输出形态与作用域检查被单独记录,而不是被夹带进那 道门里。

在第 9 章,语义部分使用 LM 评审器(LM judge),因为像*“截止时间仍然从交付起 算”*这样的要求无法还原成 token 重叠。在第 19 章,晋升决定是读取已测量证据的确 定性代码,因为提出候选的程序不该同时就是决定候选能否发布的权威。

可以推广开来的规则是:模型提出,软件决定。


5. 组合后的程序测量到了什么

我们在 37 个训练与开发案例上运行了 EditorialRewriteProgram。每次执行做三次 LM 调用。

度量 新一次组合运行 第 4 章的直接预测器
每案例 LM 调用次数 3 1
平均分,指标 v1 0.8359 0.8034
平均分,指标 v2 0.8359 0.7862
语义违规 0 1

新一次组合运行在 v1 上比第 4 章直接预测器的点估计高出约 0.033。在 v2 下, 点估计的差距更大,因为直接预测器的 ed-025 语义违规在 v2 之下被封顶。

先别急着把这两行变成一个精确的因果效应。它们来自不同的会话,而后面重复实验的 工作表明,即使在温度为零,本地 Qwen3 也可能在会话之间、顺序相关的吸引子之间 移动。

更早那次组合运行记录了每案例约 8.0 秒,而第 4 章的直接预测器是 1.879 秒, 这提示延迟成本大约是四倍量级。最终的比值应当引用自配对的重复计时运行,而不是 把一个会话的计时和另一个会话的质量拼在一起。

在由此得出结论之前,先做一条比这些数字更有用的坦白。

我们在分开的会话里运行了同一个组合程序,得到 0.7794 和 0.8359。

那个 0.0565 的差距大到足以颠倒这个架构故事——如果你把其中任何一次运行当作 决定性的点估计的话。把它叫做简单的噪声底会误导人。后面重复实验的工作发现, 即使在温度为零,也同时存在跨会话漂移和交错下的顺序相关漂移。

在这里,聚合层面的移动很容易定位。低分那次运行撞上了两个硬门零分——ed-010 和 ed-020——而高分那条路径没有撞上。由于硬门把一个候选直接映射成零,生成文 本的微小变化就可能变成均值上的巨大变化。

算术是不留情面的。把两个本来约 0.83 的案例换成硬零,会让 37 个案例的均值移动 约 2 × 0.83 / 37 ≈ 0.045。因此一个边缘案例就能把聚合移动约 0.022——比我们 后来花整章去解读的某些优化器差值还要大。

由此得到三条规则。

把门失败与均值并列报告。 一个不带失败计数的分数,会掩盖聚合移动的原因究 竟是许多案例略有改善,还是一个案例跨过了一条不连续的边界。

依赖硬零案例的比较必须重复。 我们差点就把 0.7794 当成本章的标题结论,并 会断定组合是有害的。第二个会话改变了这个说法。

不要把 temperature=0 等同于确定性。 在运行对比中,37 个生成的分析对里有 27 个跨会话发生了变化。在 ed-010 上,即使逐字节相同的分析输入也导致了不同的 改写:一个保留了被禁止的现在时形态并硬性失败;另一个把句子改成了过去时,得分 约 0.967。

因此这种不稳定性并不局限于某一个阶段或某一种状态。实验设计必须去测量它,而不 是把它假设掉。


6. 数据流不等于因果影响

组合后的程序产出可以被审计的中间状态。一次血缘(lineage)检查确认 analysis.issue_summary 原封不动地到达改写,analysis.preservation_notes 也是, 而 rewrite.rewritten_text 原封不动地到达评估者。所有血缘检查都通过了。

这证明了管道是通的。至于分析有没有真的在干活,它什么也没说。

为了弄清楚,我们固定句子、目标、上下文、模型、签名和生成设置,只改变进入改写 阶段的那两个分析字段:

条件 issue_summary preservation_notes
REAL 本案例的分析 本案例的分析
BLANK 空 空
SHUFFLED 另一个案例的分析 另一个案例的分析

这次消融在三个条件下评估 37 个案例,共 111 次可测量的改写调用。REAL 的分 析是单独生成、再提供给改写阶段的,所以下面的延迟一栏只给改写调用计价。它不包 含生成 REAL 所依赖的分析的成本。

当我们后面追问分析阶段是否值回它的调用时,这个区分很重要:质量效应与端到端成 本来自不同的测量,不该被折叠成一个数字。

条件 分数 v1 分数 v2 改写延迟 语义违规
REAL 0.8354 0.8354 1.957 s 0
BLANK 0.8005 0.7834 1.819 s 1
SHUFFLED 0.7845 0.7796 1.915 s 1

在这次 37 案例的消融中,REAL 分析在 v1 上比 BLANK 高约 0.035,比 SHUFFLED 高约 0.051。它也是这次运行里唯一一个语义违规为零的条件。

这是证据,表明在该实验夹具(fixture)下,中间的分析具有因果上的用处:只改变分 析输入,就会朝预期方向改变可测量的改写质量。

这还不是一个普遍主张,说一次分析调用总是值回它的成本。消融测量的是拥有正确分 析可用的收益;端到端部署仍然要给额外的 Analyze 调用计价,并跨会话重复这个比 较。


7. 什么都没换来的阶段

现在把两个数字并排放。

一次新鲜的全流水线运行——Analyze、Rewrite、Assess——得分 0.8359。消融的 REAL 路径——Analyze、Rewrite,没有 Assess 调用——得分 0.8354。

这种近乎相等让人安心,但它不是证明。这些是调用安排不同的独立运行,而本章刚刚 说明了为什么跨运行的相等或不相等可能充满噪声。

更强的证据是数据流本身。assess 只在 rewrite.rewritten_text 已经产出之后才运 行。它收到那句完成的句子,发出 risk 和 assessment。在被返回的 rewritten_text 定下来之前,这两个字段中的任何一个都不喂给重试、拒绝、改写或分支。

所以,在照此写就的程序之下,评估阶段对被计分的改写没有因果路径。即使两个 充满噪声的会话产生了不同的聚合均值,那个差异也不能归因于评估改善了这句话:代 码没有给它任何这样做的机制。

它确实有的是价钱:每个案例多一次 LM 调用,外加它的提示词与完成 token。现有测 量确立了可观的端到端开销,但在没有阶段级计时分解的情况下,还不足以断言 assess 是最大的单一延迟来源。

第 3 章给过一条规则:每个字段都需要一份职责,而任何能控制动作的字段都需要独立 的验证或校准。它拿 risk 当例子,说明不该仅仅因为它听起来有用就加进来。

而在这里,这条规则在一个完整阶段的尺度上被违反了。一次专门的 LM 调用产出 risk 和 assessment;程序把它们返回;测量路径上没有任何东西消费它们。

这些输出仍可能有诊断价值。人可以检视评估者声称有风险的东西,正如人可以检视一 个理由或推理轨迹。但那是可观测性,不是质量控制。除非评估会改变路由或候选 决定,否则它应当被当作诊断性仪表来计价,而不是被记作改善了改写。

给这个阶段一个消费者,至少会让它变得有因果作用:

assessment = self.assess(...)

# Illustrative only: an unvalidated self-report should not be a
# production acceptance gate without calibration or another check.
if assessment.risk == "high":
    return dspy.Prediction(
        rewritten_text=sentence,          # decline the edit
        rationale=f"declined: {assessment.assessment}",
        risk=assessment.risk,
    )

现在 risk 可以改变被返回的句子,而返回原句恰好就是第 2 章和第 3 章主张程序 应当能够明确表达的那种克制。

但有因果不等于安全。这个分支同样会把一个未经验证的 LM 自评变成对输出的权 威——正是第 3 章拿 confidence 警告过的同一种设计错误。在这样的分支控制接受 之前,risk 需要校准、一个独立验证器,或者一种更安全的策略,比如把高风险案例 路由给人工审查,而不是自动做决定。

我们没有测量过这些变体中的任何一个,所以它们仍然是设计草图,而不是结果。

被测量到的结论更窄也更强:

一个没有下游消费者的阶段,无法改变被计分的改写。它可以增加可观测性、状态和 成本——但增加不了控制。

眼下,我们自己做出这个结构性决定:保留有用的分析路径,并认识到评估者没有因果 权威。本书后面会问一个更难的问题——程序结构本身能否成为一个优化变量,以及优化 器能否发现某个阶段只是装饰性的,而不只是去调它内部的措辞。


8. 四种组合模式

一个模块该在哪里结束、下一个该从哪里开始?

线性:    A -> B -> C
扇出:    A -> B, C, D
包装器:  Memory(ContextPolicy(Module))
图:      显式依赖拓扑

线性流水线适合每个阶段产出下一个阶段真正需要的状态——正如第 6 节所示,这是一 个待检验的主张,而不是可以假定的事实。扇出适合在同一份证据上工作的独立专家。 包装器适合横切关注点:上下文策略、记忆、来源、重试、成本追踪。图适合真实的依 赖、并行波次、检查点与恢复。

三个公开的 DSPy 系统值得为这些形状去读。CodeSpy 在一个代码审查系统里展示了包装器与专家组合,包括围绕并行审查角色的记忆与上下文包装器。STORM 把知识策展、提纲、文章生成与润色分开成不同的模块。Arachne 是图形状的对照:澄清一个目标、编织一张带类型的依赖图、配置工具、按波次执行、评估,然后自愈或改道。

读它们是为了看边界,并对每个阶段问出第 7 节问的那个问题:谁在消费它?


通常会出什么错

症状 可能原因 如何诊断 改什么
组合后的程序比预期慢 某个阶段可能产出从不影响决定的状态 把每个中间字段追踪到它的下游消费者 移除它、把它显式留作可观测性,或给它一个经过验证的职责
中间状态流动正确却什么也没改变 字段太模糊,无法据以行动 消融它:REAL vs BLANK vs SHUFFLED 收窄该字段或移除这个阶段
错误的中间状态得了高分 指标奖励的是代理,不是那个属性 在语义检查下给同样的输出打分 在信任结果之前先加强指标
均值在温度为零的运行之间大幅移动 会话/顺序效应把边缘案例推过硬门 比较逐案例输出与门失败,而不只是聚合 在新鲜会话中以平衡的顺序重复;报告门计数
一个三案例实验给出了自信的答案 夹具分辨不了效应大小 算出该夹具能检测到多大的差值 在下结论之前先拿到更多案例
每一步都是一次 LM 调用 可计算的工作被委托给了模型 搜索那些提出确定性问题的调用 把它们移进 Python
调试载荷巨大 程序什么都存原始的 检查一条已存储的运行记录 存储有界的轨迹、指纹与关键字段

本章小结

我们现在有了一个真正的语言模型程序:小模块、其间的确定性 Python、可以被检视、 追踪和扰动的中间状态。

我们对拆分买到了什么也有了更诚实的交代。一次新鲜的组合运行得分约 0.836,而 第 4 章直接预测器的点估计在 v1 上约 0.803。由于这些值来自不同的会话,精确的 端到端差值应当被当作暂定的,直到配对的重复比较完成。

阶段级的结果更清楚。在 37 案例的消融中,REAL 分析在 v1 上比 BLANK 高约 0.035、比 SHUFFLED 高约 0.051,且那次运行的语义违规为零。相比之下,评估阶 段对 rewritten_text 没有因果路径,因为在结果返回之前没有任何东西消费它的输 出。

这就是答案有用的那个形状。*“拆分有没有帮助?”*是错误的问题。改问:哪个阶段改 变了行为?哪个阶段只改变了可观测性?每个阶段的代价是什么?以及哪些输出被信任 到足以控制任何东西?

本章有两个假设失效了。

第一个假设是:显式的中间状态仅仅因为它是显式的就有价值。评估阶段是显式的、可 检视的、命名得当的,但在被测量的程序之下,它根本无法影响被计分的改写。它的价 值(如果有的话)是诊断性的,除非我们刻意给它一个经过验证的下游职责。

到目前为止,一切都把模型当作背景——一个配置一次就被丢在脑后的依赖。第 4 章和 第 5 章里的每一个数字,都是关于温度为零的 Qwen3 8.2B 的数字,它们中没有一个必 然能在另一个模型下存活。

所以:

模型是程序的一部分,还是程序的一个依赖?