← DSPy From First Principles

提示词还不是程序

界定一个语言模型组件在配得上被称为程序之前需要具备的属性——并理解为什么这些边界是受控比较的前提。

第 1 章以一个签名和多得令人不安的未竟事项收尾。我们已经确立:一个提示词字符串同时承 载着任务语义、行为框定、输出 schema 和 provider 假设,而这正是三个互不相关的失败到来 时看起来一模一样的原因。

显而易见的回应是写一个更好的字符串。这是错误的一步,值得把原因说清楚。

提示词是文本:

"改写这个句子……"

一个普通的手写提示词没有显式的语义接缝。你可以逐字符对比,可以把字符串拆成模板,也 可以给各块起不同的文件名,但除非应用声明这些块意味着什么,否则那些边界只是约定。改 动措辞可能改变任务、执行策略、输出格式,或者同时改变其中好几样。

一个程序有边界:

输入
  ↓
声明的行为
  ↓
执行策略
  ↓
结构化输出

边界就是全部要点所在。它让受控的改动成为可能:任务契约、执行策略、模型配置、示例和 评估可以变成分别命名的变量。

这就是从结构迈向实验的那一步。一旦变量有了名字,我们就能固定其中四个、改变一个,然 后比较候选 A 与候选 B,而不必假装两个提示词字符串之间的差异解释了原因。

    flowchart LR
    subgraph Prompt[提示词]
        PS[提示词字符串] --> B[一个不可分割的整体]
    end
    subgraph Program[程序]
        PB[程序边界] --> C[契约 + 策略 + 模型 + 数据 + 评估]
        C --> CC[受控候选]
    end
  

提示词字符串把每个决定熔进一个对象。程序边界则把这些决定保留为各自分开的部分,正是 这一点让一个候选成为受控的——你可以改一个部分,把其余固定不动。这种分离本身并不证 明只有一样东西变了。你仍然需要指纹、运行记录和一套冻结的评估协议来确立这一点。但没 有边界,连一个提问的稳定位置都不存在。

本章讲的是:一个语言模型组件要挣得那个称呼,必须先满足什么。本章刻意不讲如何把签名 做得好——那是第 3 章的内容,而它实际更难。本章讲的是形状。


1. 程序承诺了什么

一个普通的 Python 函数有一份很弱的契约,但它仍然在做实事:

def slugify(title: str) -> str:
    ...

这一行几乎什么都没说关于行为的事。但它说得够了。它给输入命了名,给输出类型命了名, 给其他代码一个稳定的东西来调用,创建了一个测试可以安身的地方,还让你明天就能换掉实 现而不必告诉任何人。

当同样的关注点被显式化之后,一个语言模型组件就变得可工程化了:

属性 它为什么重要
具名的输入 调用方不再用临时拼凑的散文来组装任务输入
声明的行为 语义工作在提示词措辞之外可见
执行策略 你能知道如何尝试被声明的任务,与它是什么分开
结构化输出 下游代码拿到稳定的字段,而不是一段要解析的散文
可检视的结构 你可以枚举程序的各个部分,而不是从一个字符串里推断它们
一个可以失败的地方 校验、重试和回退有地方可待

DSPy 为此提供了两个抓手。

一个**签名(Signature)**声明任务接口:什么进来,什么出去,以及连接两者的语义工作。

一个模块控制这个任务如何被尝试——直接预测、显式推理、工具使用、检索,或者若干次 调用与普通 Python 交织在一起的组合。

Signature: 请求的是什么行为?
Module:    这个行为如何被尝试?

这句话很容易被点头认可,也很容易被低估。下一节把它具体化,因为它是本书余下部分所构 建的那个观念。


2. 真正起作用的那个分离

这是贯穿全篇的任务最小的、程序形状的版本。一句话进去,一段改写出来。

这是教学用的单次调用形式。在第 5 章,仓库实现会用中间分析字段扩展改写阶段,但核心任 务边界仍然是 sentence、goal 和 context 进,改写与理由出。把这个区分保持显式,可 以防止教学接口被误当成"实现永不演化"的主张。

import dspy

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")

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

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

调用它也没什么特别的:

program = EditorialRewriteProgram()

result = program(
    sentence="Jalen opened the door and then he looked into the room and felt afraid.",
    goal="Sharpen the sentence without changing the event.",
    context="A tense scene in a realist novel.",
)

print(result.rewritten_text)

现在看看这个分离买到了什么。同一个签名,用不同的方式尝试:

direct   = dspy.Predict(RewriteSentence)
reasoned = dspy.ChainOfThought(RewriteSentence)

两者都接收 sentence、goal 和 context,都返回 rewritten_text 和 rationale。 ChainOfThought 增加了一个内部推理步骤,并为此构造出一个大不相同的提示词。任务契约没 有动,所以调用它的代码也不动:

for module in (direct, reasoned):
    out = module(sentence=..., goal=..., context=...)
    print(out.rewritten_text)

这不是风格上的讲究。正是它让*“思维链在这里值得吗?"*这个问题变得可以回答。当推理策 略只是提示词字符串里的一个短语时,替换它意味着重写提示词,意味着同时改好几样东西, 意味着比较无法解释——这正是第 1 章 v6 对 v7 的问题。当策略是一个包住固定签名的模块 时,你可以让其余一切静止不动,然后测量差异。

我们在第 4 章确实测量了它,用 37 个训练与开发样例、每种策略重复三次。ChainOfThought 更贵,但更大的夹具不再给出干净的平局:它在原始指标下有微弱的优势,在语义防护栏下有 更明显的优势,因为普通的 Predict 在一个样例上改变了合法截止期限的参照点。

教训不是推理总是赢,而是把策略从契约中分离出来,让"代价对正确性"这样的问题变成可测 量的,而不是修辞性的。

结构上也是如此。EditorialRewriteProgram 在这里从一次 LM 调用开始。到第 5 章它变成三 次——一个分析阶段、一个改写阶段和一个评估阶段,中间状态在它们之间传递。它的内部完全 改变了。调用这个程序的代码可以保持同样的面向任务的边界,因为 sentence、goal 和 context 仍然标识着要做的工作。

第 5 章的实验接着把两个容易混淆的问题分开。真实的中间分析在因果上有用:在扩大的夹具 上,它击败空白分析或打乱的分析。但一个有用的中间表示,并不能自动证明整个三段调用流 水线的代价是正当的。内部状态可以帮助某一个阶段,而端到端的程序仍然必须挣得它多出来 的延迟和 token。


3. 程序是若干个工件,不是一个

手写版本只有一个工件:

提示词字符串

在这个阶段,程序给了我们至少六个具名的工件,可以分别拿来做推理:

signature        任务契约                    (第 2–3 章)
module           执行策略                    (第 4–6 章)
LM configuration 模型与参数                  (第 6 章)
demonstrations   示例,一旦编译              (第 10–13 章)
metric           验收标准                    (第 8–9 章)
run record       实际发生了什么              (第 8 章)

这些工件可以被分别识别、做指纹、记录和比较。它们在统计意义上并不独立:改一个签名可以 改变模块产出的提示词,改示范可以改变 token 成本,改 LM 可以改变每一个被观察到的输出。 收益在于,这些依赖是可见的,而不是被熔进一个字符串里。

具体地说,你现在拥有的抓手:

如果下游代码除了改写还需要一份风险评估,你就改契约,每个调用方都会看到新的字段。 如果模型应该在回答之前推理,你就改模块,同时保持面向任务的契约不变。如果你从一个 模型换到另一个模型,你就改 LM 配置,并把它记录为一个实验变量。如果你之后拿示例去 编译这个程序,优化器拿到的是结构化的程序状态去修改,而不是一坨没有分别的提示词。

所以当一个数字变了,你可以问:哪些工件动了,哪些被固定住了。后续章节会在这六个之外 再加上数据集、划分、评估协议、候选、晋升和部署的身份。那不是记账式的繁文缛节——正是 它把归因从猜测变成实验。


4. 声明的行为不是实现

人们第一次写签名时最常见的失败,是把旧提示词倒进文档字符串里。

class BadRewriteSentence(dspy.Signature):
    """Think step by step, compare three alternatives, choose the best one,
    and rewrite the sentence using a terse Hemingway-like style."""

    sentence: str = dspy.InputField()
    rewritten_text: str = dspy.OutputField()

那个文档字符串混合了三种不同种类的陈述,而它们属于三个不同的地方:

陈述 种类 它属于哪里
“改写这句话” 要求的行为 签名。这就是任务。
“逐步思考,比较三个备选” 执行策略 模块。这是一个 ChainOfThought 决定,不是契约条款。
“用海明威式的简洁风格” 编辑策略 goal 字段或数据。这是一种关于好散文的理论,不是任务的属性。

熔合它们有真实的代价。你无法把 Predict 换成 ChainOfThought 来得到一次干净的比较, 因为文档字符串已经在要求推理——你会是在拿推理对推理进行测量。你无法把这个程序用在一 位不这么写的作者身上。而当优化器后来重写这条指令时——正如 MIPROv2 在第 12 章所做的那 样——它可以随意同时修改你的任务定义、你的策略和你的风格政策,这把你直接打回第 1 章所 诊断的那个处境。

一个有用的检验:读一遍文档字符串,问每一小句在你换掉执行策略之后是否仍然成立。“改写 这句话以满足编辑目标"经得住这个替换,“逐步思考"经不住。


5. 输出是程序的一部分

输出字段不是装饰。它们决定了系统其余部分能做什么,也决定了模型能说什么。

先看粗糙的版本:

class CoarseRewrite(dspy.Signature):
    """Improve the sentence."""

    sentence: str = dspy.InputField()
    answer: str = dspy.OutputField()

给模型这个,它通常会返回类似这样的东西:

Jalen 打开了门,害怕他会发现什么。我通过去掉并列连词、压缩第二个分
句收紧了节奏,同时让恐惧保持显式。

现在下游代码必须把改写与评论分开,这意味着一个正则,意味着一个一直管用、直到模型把 解释放在最前面才失灵的正则。拆开字段是把问题移除,而不是处理它:

    rewritten_text: str = dspy.OutputField(desc="A replacement sentence, not a paragraph")
    rationale: str = dspy.OutputField(desc="Short explanation of the edit")

以上是标准建议。下面是容易被漏掉、而本书为之付出了代价的那个版本。

契约决定了哪些区分能被模型干净地表达——以及哪些区分能被系统的其余部分观察到。

再看一眼那个输出字段:

rewritten_text: str = dspy.OutputField(desc="A replacement sentence, not a paragraph")

严格说,模型可以原样返回最初的句子,因为 rewritten_text 仍然只是一个字符串。契约无 法表达的,是*“我有意决定不需要编辑”与“我尝试改写,碰巧复现了输入”*之间的语义区分。

字段名和任务措辞也制造了朝"改变"施加的压力。如果克制有时是正确的编辑决定,那么这个 状态应当可以被有意地表示和评估,而不是事后从字符串相等中推断出来。

这不是假设。在扩展后的评估夹具里,四十四个样例中有六个——约 13.6%——针对的是不必 要的编辑或克制。在这些样例上,一个未改动或几乎未改动的句子可以是正确的行为。

第 8 章基线所用的原始结构指标,只给未改动的输出 0.65,因为它的 changed 分量在克制 正确时也是零。第 9 章接着让更深的问题显形:一个指标可以忠实地实现契约里内建的假设, 却仍然奖励错误的行为。

教训不是当前的签名让恒等输出变得不可能,而是程序没有对"决定不编辑"的显式表示,而指 标继承了这种含混。一份弱契约因此可以直接传播成一套弱的测量系统。

一旦看清问题,修法都很平常:

class TriagedRewrite(dspy.Signature):
    """Decide whether a sentence needs editing, and rewrite it only if it does."""

    sentence: str = dspy.InputField()
    goal: str = dspy.InputField()
    context: str = dspy.InputField()

    edit_needed: bool = dspy.OutputField(desc="False if the sentence already satisfies the goal")
    rewritten_text: str = dspy.OutputField(desc="The replacement sentence, or the original unchanged")
    rationale: str = dspy.OutputField()

或者让 rewritten_text == sentence 成为一个显式有效、被预期的结果,写进字段描述,并由 指标有意地处理。或者把分诊拆成它自己的阶段。

哪一种正确取决于应用。重点是,三者都是关于契约的决定,是在任何模型运行之前做出的, 而把它们做错不只是提示词措辞的问题——那是一个形状问题,会被每个下游阶段继承。

对于本书的实验,我们有意让那个更简单的改写契约保持足够长的时间,以暴露这种传播。我 们不会在发现 0.65 的克制下限之后回头修补夹具,因为那样做会抹掉证据。上面那个分诊签 名是一种设计上的替代方案;被测量的语料仍然是原始契约错在哪里的记录。


6. 边界是失败与代价的居所

再加一个属性,因为提示词没有对应物,所以很容易被忽略。

提示词无法处理自己的失败。如果模型返回胡话,字符串对此毫无意见;无论什么代码调用了 它,都得去应付,而那通常离出错的地方很远。第 1 章的 parse_json_object 就是此事的一 座小小纪念碑——一个之所以存在于调用方的函数,因为提示词无法强制任何东西。

一个模块可以在失败发生的地点吸收它:

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

    def forward(self, sentence: str, goal: str, context: str = "") -> dspy.Prediction:
        result = self.rewrite(sentence=sentence, goal=goal, context=context)
        if not result.rewritten_text.strip():
            return dspy.Prediction(rewritten_text=sentence, rationale="empty output; original retained")
        return result

这是一件小事,却演示了一件结构性的事:现在有了一个地方,“出错时应该发生什么"可以被 写下来、与程序一同版本化,并对下一个读到它的人可见。

这个例子只处理一种确定性失败:空的改写。它检测不出实体改动、语义漂移,或一句风格上 错误却流畅的句子。模块边界为失败策略创造了一个地方;它不会让失败检测变得自动。后续章 节会在那个边界上加入显式的关卡、指标、评审器和晋升规则。

模块边界也是代价累积的地方,这一点值得早点点名。每一个关于如何的决定都有价格。 ChainOfThought 比 Predict 生成更多 token。三段组合会做三次调用而不是一次。一个检索 步骤会增加一次查找和一条长得多的提示词。一个智能体循环可能调用五次或十五次,而在它 跑起来之前你不会知道是哪种。

这些代价没有一个在签名里可见,而这完全正确——契约不应该知道它自己是如何被满足的。但 这意味着,从这里开始,本书中的每一个架构选择都必须对照一个被测量的基线来证明自己, 而不是对照直觉。第 4 章给推理定价,第 5 章给分解定价,第 15 章给工具使用定价,第 16 章给检索定价,并发现有一种策略花费十倍的 token 却得分更差。

“什么"与"如何"之间的分离,正是让这些价格可读的东西。没有它,一个架构决策的代价只是 账单的一部分。


通常会出什么错

症状 可能的原因 如何诊断 改什么
签名的文档字符串读起来像提示词 任务契约与执行策略被熔合 检查每一小句在换掉模块后是否仍成立 把策略移进模块,把风格移进数据
下游代码对输出跑正则 输出字段太粗糙 找出在 LM 调用返回之后才发生的解析 把输出拆成具名字段
每个调用方传入的上下文散文略有不同 输入没有命名或规定不足 比较同一程序的各个调用点 给输入字段命名并写清它们的范围
换模块会弄坏调用方 策略特定的细节泄漏进了签名 找找有没有按推理步骤、提示词或 provider 命名的字段 让签名字段保持语义性
模型去改本来正确的文本 契约无法表达"无需改动” 检查恒等输出是否可表示、是否被预期 加一个分诊输出,或把未改动文本变成显式的有效结果
出现了一次回归,却没人能定位它 六个工件中有好几个一起变了 分别对比签名、模块、LM 配置、示范和指标 分别给它们做版本化,一次只改一样

本章小结

我们现在有了一个包住语言模型行为的、程序形状的边界。提示词仍然存在——DSPy 在每次调 用时都会构造一个,你也可以把它打印出来——但它不再是软件其余部分必须理解的东西,也 不再是你为了改变行为而去编辑的东西。

更重要的是,行为现在可以变成一个实验变量。基线与候选可以共享同一份任务契约,同时在 执行策略、示范或指令上有所不同。当每项关注点都住在同一个字符串里时,这种比较没有意 义。

我们去掉的假设是:一个单一字符串应当把任务契约、执行策略、输出接口和版本身份当作一 个不可分割的工件来承载。这些关注点现在各有单独的抓手,后续章节得以在被记录的协议之 下改变它们,而不是依赖提示词版本的民间传说。

但请注意第 5 节暴露了什么。我们用当时最自然的方式设计了一个输出字段,却未能把*“无需 编辑”*表示为一个显式决定。后来夹具的四十四个样例中有六个以克制为核心,而第一个结构 指标即使在克制正确时也惩罚未改动的输出。拥有一个签名丝毫没有阻止这件事。

边界在正确的位置上。下一个问题是,那个边界上的契约是否表达了正确的区分。

这就是下一个问题:

究竟应该要求模型消费什么、产出什么——以及,在一份契约让你付出五章的代价之前,你如 何分辨它是强还是弱?