← DSPy From First Principles

我们为什么还在手写提示词?

从一个合理的手写提示词开始,看它以三种不同的方式失败,并把 DSPy 框定为把语言模型行为变成实验变量的机制。

几乎每个语言模型应用都是从一个字符串开始的。

这不是错误。提示词是弄清一个模型究竟能不能胜任这项工作最快的办法,它让你直接在行 为上下手,而不必先围绕一个你尚未理解的问题搭一套框架。大多数好的 LM 系统都是这样起 步的,也应该这样起步。

麻烦在于,提示词的存活时间通常远超它有用的期限。它不再是探针,而变成了规格本身; 等到有人注意到时,这个字符串已经有四百个词长,没人记得第三段为什么在那里,而改动它 让人觉得危险。

本章就来搭建这个字符串。我们会为一个真实任务写一个确实合理的提示词,运行它,然后看 着它以三种不同的方式失败。重点不在于这个提示词很糟,而在于三种失败都经由同一条通道 到来,在日志里看起来一模一样,底层却毫无共通之处。

本书刻意从编辑改写开始。“这句话更好吗?“是个真实的问题,但答案的一部分属于判断。 这使得这个任务成为一次有用的压力测试,检验本书余下部分将反复做出的那个区分:

我们能为这个行为编程吗?          能
我们能测量这个行为吗?            部分能
我们能优化这个测量吗?            能
这能证明真实的改进吗?            本身不能

稍后我们会在仓库修复上重复这套工程流程——在那里,候选可以被解析、被约束在允许的作 用域之内、被执行、被测试。这两个任务从相反的两侧提出同一个经验问题:当正确性从判 断移向可被外部检查的行为时,会有什么变化?

任务很小也很具体:给定手稿里的一句话、一个编辑目标和周围的上下文,产出一句更好的 话,而不改变它的意思和它读起来的感觉。

    flowchart TD
    I[句子 + 目标 + 上下文] --> P[手写提示词]
    P --> M[模型]
    M --> R[候选改写]
  

这就是我们的起点。三个输入坍缩成一个手写的字符串,模型运行,一段改写返回。提示词与 输出之间,没有任何东西是一个你可以单独检视、单独版本化、单独改动的对象。

我们全章都使用同一个句子,并让它成为本书实验夹具(fixture)里的第一个规范样例:

Jalen opened the door and then he looked into the room and felt afraid.

编辑目标是:Sharpen the sentence without changing the event. (在不改变事件的前提下让句子更锋利。)决策时刻的上下文是: A tense scene in a realist novel.(一部现实主义小说里的紧张场景。)后续的评估还会 要求改写不引入新事件、也不把语气变成喜剧。

这句话干的活比看上去的多。它带着一个具名角色、一串事件、一种情绪和一种语气,而改写 可以独立地破坏其中任何一项。它之所以是有用的第一个样例,恰恰是因为"更好"有多个维 度,而这些维度可能朝相反的方向移动。

从一开始就使用规范夹具也给了我们连续性。当后续章节加入指标、优化器、来源和划分边界 时,我们并没有悄悄改变实验之下的那个任务。当任务最终换成仓库修复时,那次改变会是显 式且有动机的:那是转向一种不同的证据体制,而不是悄悄换一个更简单的样例。


1. 一个合理的首个提示词

这是第一个版本——一个能干的团队在探索期会拿出来的那种东西:

from dataclasses import dataclass

@dataclass
class RewriteRequest:
    sentence: str
    goal: str
    context: str

def build_prompt(request: RewriteRequest) -> str:
    return f"""
You are an expert line editor.

Rewrite the sentence to satisfy the editorial goal.
Preserve meaning, entities, point of view, and the author's voice.
Avoid adding new facts.

Context:
{request.context}

Editorial goal:
{request.goal}

Sentence:
{request.sentence}

Return JSON with:
- rewritten_text: the improved sentence
- rationale: a short explanation of what changed
- confidence: a number from 0.0 to 1.0
""".strip()

这不是一个稻草人。它指定了角色、提供了上下文、显式写明了约束,并要求结构化输出。这 是一个称职的探索期提示词。

这很重要。如果本章以一个明显糟糕的提示词开头,后面每一次失败都可以被归结为提示词写 得不行。我们想看的是:当提示词已经合理之后,还有什么仍然困难。

调用它的代码是普通的 Python:

import json

def parse_json_object(raw: str) -> dict:
    start = raw.find("{")
    end = raw.rfind("}")
    if start == -1 or end == -1:
        raise ValueError("no JSON object found in response")
    return json.loads(raw[start:end + 1])

def improve_sentence(model, request: RewriteRequest) -> dict:
    prompt = build_prompt(request)
    raw = model(prompt)
    return parse_json_object(raw)

注意,parse_json_object 已经存在了。没有人计划过它。模型返回的是包含 JSON 的散文 而不是 JSON,于是有人写了一个函数去找大括号,它从那以后就一直待在那里。

这个形状很容易记在脑子里:

    flowchart LR
    PO[Python 对象] --> PS[提示词字符串]
    PS --> LR[LM 响应]
    LR --> JP[JSON 解析器]
  

对一次实验来说,这没问题。但作为一个工程单元,这个提示词承载的东西已经超出了它能 承受的量。


2. 三种失败,一个字符串

这样的提示词可以以几种互不相干的方式失败。下面三个例子是有代表性的失败形态,而不是 来自后续实验语料的测量结果。它们的目的,是把那些被单一提示词字符串弄得看起来惊人相 似的问题分开。

第一个是被改了名的角色。

{
  "rewritten_text": "Jason opened the door, afraid of what waited inside.",
  "rationale": "Tightened the sentence and moved the fear into a participial phrase.",
  "confidence": 0.88
}

改写的文字更好了,但写的已经是另一个人。提示词说着"保留实体”,模型原则上同意了,却 还是给主角改了名。系统里没有任何东西注意到,因为系统里没有任何东西在看。confidence 字段报告 0.88,它告诉我们的只是模型对一个它写错的句子有什么感觉。

第二个是坏掉的接口。

{
  "rewrite": "Jalen opened the door, afraid of what he would find.",
  "why": "Removed the coordinating conjunction.",
  "confidence": "high"
}

改写本身是好的。键错了,confidence 是一个字符串。parse_json_object 成功了——它找 到了合法的 JSON——接着调用方去取 result["rewritten_text"],在离原因两个函数远的地 方抛出一个 KeyError。

通常的修理办法是给解析器打补丁:

def normalize_response(raw: dict) -> dict:
    return {
        "rewritten_text": raw.get("rewritten_text") or raw.get("rewrite"),
        "rationale": raw.get("rationale") or raw.get("why"),
        "confidence": float(raw.get("confidence", 0.0)),
    }

这个补丁管用,但值得停下来想想刚刚发生了什么。一个接口问题在运行时被发现,并在那个 据称定义了任务的工件之外被修复。提示词里仍然写着"Return JSON with:",而它仍然不是一 份契约。它是一个嵌在更长的自然语言指令里的自然语言请求。模型可能会遵守,解析器可能 会兜住。这两者都不是接口。

还要注意 float("high") 会抛异常。补丁修好一个失败,又引入了另一个。

第三个失败才是应该让你担心的那个。

{
  "rewritten_text": "Jalen hurled the door aside, his heart hammering against the cage of his ribs.",
  "rationale": "Heightened the tension and added visceral physical detail.",
  "confidence": 0.94
}

JSON 是合法的,键是对的,名字保留了,恐惧也保留了——甚至被放大了。可它没法用,因为 这位作者不这么写,而一本每四十句里就有一句被另一位小说家代笔的书,比一本里头有一句松 垮句子的书更糟。

这一个在三者中带着最高的置信度分数。

这里没有可捕获的异常,没有 schema 违规,没有缺失的键。唯一能检测出这种失败的,是对 文风的判断,而系统里任何地方都不存在这样的判断。

三种失败,一条通道:

我们要求的 返回的东西 表面症状 真正的问题
保留 Jalen 这个名字 “Jason 打开了门……” 实体被改动 用散文写下的约束从未被独立检查
返回这些 JSON 字段 {"rewrite": ..., "why": ...} 需要解析器兜底 输出 schema 是被请求的,而不是被强制的
保持克制的文风 “……撞在肋骨的牢笼上” 流畅但错误 不存在可供核对的文风保持定义

这不是同一个问题的三个实例。第一个是实体约束违规,第二个是接口违规,第三个是风格失 败——它需要一条显式的评估标准,才能被命名。

当夹具后来长成一份显式的失败分类法时,这个区分会变得重要。更长的提示词可以提到每一 种失败模式,但长度不会对失败进行分类,而一旦失败有不同的原因,它们就需要不同的抓手。

提示词已经悄悄吸收了至少七项各自独立的关注点:

关注点 它在手写版本里的位置
任务定义 提示词内部的散文
输入名称 由标题暗示
输出 schema 靠近末尾的一份散文列表
行为框定 “You are an expert line editor”
模型特定的调优 恰好对某个 provider 有效的措辞
评估标准 在提示词之外,如果存在的话
版本身份 整个字符串

所以当你编辑提示词里的一句话时,改变了什么?也许是任务契约,也许只是措辞,也许是模 型产出多少解释,也许你为某个托管模型改进了它,却把它对本地模型弄坏了。这个字符串不 会告诉你,它也没法告诉你,因为全部七项关注点都编码在同一种介质里。


3. 回答不了问题的版本历史

在一个小型应用里,提示词版本就是一个文件名:

sentence_rewrite_prompt_v4.txt

经过几个月的真实使用之后,历史通常长得像这样:

v1: 基础改写
v2: 更严格的 JSON
v3: 加入示例
v4: 修复过度压缩
v5: 提到文风
v6: 本地模型变体
v7: 不要改角色名字

这比什么都没有强。但它仍是薄弱的证据,因为每个版本都同时改了好几样东西。示例随着指 令一起移动,输出字段随着角色描述一起移动,provider 特定的措辞随着任务定义一起移动。 每个版本都是一捆。

现在问一个你真正需要回答的问题:v7 比 v6 好吗?

prompt string changed
        ↓
行为改变了
        ↓
原因未知

你无法归因这个差异,因为你无法分离一个你从未分开过的变量。而 v7 才是有意思的那个。它 写出来是为了阻止改名,而最自然的写法是加一行类似"永远不要改角色名字"的话。那一行可 能起作用了;它也可能让模型总体上变得更保守,产出改得更少、因此改进也更少的改写。两 种效应都会表现成"v7 感觉不一样”。

提示工程正是在这里不得不变成别的东西。重要的问题不再是措辞:

  • 我们指定了什么行为?
  • 哪一个实现执行了它?
  • 哪些示例影响了它?
  • 什么标准评判了它?
  • 哪个模型、哪份配置产出了这个输出?
  • 我们能把这个版本与上一个版本比较吗?

这些是软件问题,而一个字符串一个也回答不了。


4. 评估不能是事后补上的

假设我们手工检查了十段改写,然后得出结论:v6 更好。这个结论很可能是对的。证据仍然是 脆弱的,因为我们实际评估的是:

提示词 v6
当天下午配置的那个模型
某人随手挑的十句话
关于 v5 当时表现的人类记忆

改动其中任何一项,结论可能就撑不住。没有什么把它们绑定成一个可以重新运行的东西。

显而易见的下一步是写下一个指标——某个为改写打分的函数,好让比较不再依赖记忆。这是正 确的直觉,而本书的大部分内容都在它的下游。但值得早点说出来,因为它塑造了后面的一 切:指标本身就是一个程序,而它可能出错。

它可以以普通的方式出错:给出嘈杂的分数。它也可以以更危险的方式出错:对你真正关心的 东西自信地视而不见——因为那句代笔的句子改了恰好数量的词就给它打高分;或者把一段悄悄 丢掉限定词的改写打成改进,因为它保留下来的部分都与参考答案紧密吻合。

指标甚至可以编码一个关于"改变是否可取"的错误偏好。扩展后的夹具后来包含这样的样例: 克制才是正确的,不动那句话才是正确的行为。一个在构造上就奖励改变的打分规则,惩罚的 恰恰就是这个决定。

这些都不再是假设。在第 9 章,三个规范的语义反转在原始结构指标下的得分大约在 0.85 到 0.96 之间,尽管它们颠倒了预期的语义。语义 v2 防护栏把同样的攻击压到大约 0.29。

接着第 11 章和第 12 章产生了一个更有用的失败。两个不同的优化器各自独立地吐出同一段开 发样例的改写,把 Using the filter regularly can help reduce... 改成 Using the filter helps reduce...。原始指标仍给这个候选打出约 0.97 的分数;语义防 护栏把它封顶在 0.30,因为那个限定词丢了。

一个小小的聚合分数差值能否挺过一次次运行之间的噪声,是另一个问题。候选级别的语义回 归并不依赖那个差值。

优化器不知道你打算保留哪些未被测量的属性。它搜索一个程序空间,而选择规则奖励指标看 得见的东西。如果指标漏掉了重要的东西,优化就会把这个缺口暴露出来。

由此得到三个不能被混为一谈的主张:

optimization(优化)
    候选在搜索所用的那个目标上得分更高

generalization(泛化)
    候选在未见样例上表现更好

improvement(改进)
    独立证据表明应用确实变得更好

第一个是关于搜索的事实。第二个是关于采样边界的事实。第三个是关于程序所处世界的主张。

所以评估不能在最后才螺栓式地装上去,也不能仅仅因为它产出数字就被信任。它必须是程序 形状的一部分,与程序一同版本化,并被定期攻击。我们说得有点超前了——但你应该从第一章 就知道:这个系统里,指标并不是安全的那部分。

本书最终会把句子、程序、模型、划分、优化器和预算都固定住,只改变"成功"意味着什么。 那次受控比较,正是在"责怪优化器"与"诊断它的目标函数"之间的转轴。


5. 在问题显现之后,DSPy 才登场

DSPy 通常被介绍为一个带有签名、模块、优化器和一组示例的框架。这个描述是准确的,却把 重点埋掉了。

DSPy 所做的转变,是不再把提示词当作那个工件。取而代之,你先声明任务是什么——它的输 入、它的输出,以及连接两者的语义工作——然后另行选择这个任务如何被尝试。DSPy 随后构造 出提示词。

对我们这个句子任务来说:

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

rewrite = dspy.Predict(RewriteSentence)

result = rewrite(
    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)

这假设已经配置了一个 LM。本书里每一个被测量的结果都是在一个本地模型上产出的,所以 我们也这样配置:

lm = dspy.LM(
    "ollama_chat/qwen3:latest",
    api_base="http://127.0.0.1:11434",
    temperature=0.0,
    max_tokens=256,
    cache=False,
    think=False,
)
dspy.configure(lm=lm)

这是一个有意的选择,值得直说。规范依赖是一个本地 Qwen3 8.2B 模型,以 Q4_K_M 量化,并 关闭了原生思考。它不是可用的最强模型,若干结果放到前沿模型上大概会看起来不同。

好处在于实验上的可及性:由 LM 支撑的运行不花 API 的钱,可以重复足够多次来研究失败, 并让整条依赖保持在我们的控制之下。

但 temperature=0.0 并不承诺逐比特的确定性。本书后面重复进行的会话表明,某些输入仍然 容得下相互竞争的输出。这意味着微小的分数差值必须谨慎对待,运行身份必须被记录,重要 的比较应当重复进行,而不是凭一次执行就相信。

同样的纪律也朝另一个方向适用:最终的保留集(holdout set)不会仅仅因为模型是本地的, 就被一遍遍地重新生成。廉价的执行并不能免除对证据边界的需要。

RewriteSentence 确立了本书余下部分一直保持的核心契约。决策时刻的任务字段是 sentence、goal 和 context,主要输出是 rewritten_text 和 rationale。

当我们在第 5 章拆解这个程序时,改写阶段会获得两个由更早的分析阶段产出的中间输入—— issue_summary 和 preservation_notes。这扩展了实现,而没有重命名核心任务字段。

同一份契约随后在第 8 章被测量,在第 9 章被攻击,并在一套冻结的协议之下被优化。保持核 心字段名稳定,正是让那些比较有意义的原因。后来的修复体制使用不同的任务契约,但保留 了实验纪律。

重要的转变不在于代码变短了,而在于任务现在可以被检视:

Signature
  inputs:   sentence, goal, context
  outputs:  rewritten_text, rationale

Module:
  Predict

LM:
  一个已配置的依赖,而不是一个假设

这些中的每一个都是你可以单独改动、记录、版本化和比较的东西。顺带一提,confidence 字 段已经不见了——它从来没有在测量任何东西。模型对一处它写错的改写自我报告的置信度是 0.88,对一处错得很厉害的改写是 0.94。

从第 8 章开始,置信度被某种候选之外的东西取代:显式的评估证据。那种证据会有它自己的失 败模式,但至少它可以被检视、被版本化、被攻击、被比较。

提示词并没有消失。DSPy 仍然会构造一个,你也可以把它打印出来。但它不再是任何人手工编 辑的主要抽象。


6. 这解决不了什么

如果本章在这里结束、以结构击败字符串收场,会很方便。但事情不是这样的,装作如此会让 后面的十七章变得不诚实。

声明一个签名并不能告诉你字段边界是否正确,也不能告诉你一个推理步骤是否值得它的代 价。在第 4 章,扩展后的夹具表明 ChainOfThought 更贵,但也避免了普通 Predict 造成 的一次改变含义的截止期限滑移,所以答案并不是简单的"推理是浪费的 token"。

它也不能告诉你拆解程序是否有帮助。第 5 章把组合与证据分开:规模更大的消融实验表明, 真实的中间分析相对空白分析或打乱的分析是有帮助的,而包在外围的程序仍然必须挣得它多 出来的调用与延迟。

而结构当然也不能告诉你程序好不好。那需要一份夹具、一套评估协议和一个指标——后续章节 会表明,这三者都可能以程序自身无法诊断的方式失败。

结构买到的是提出精确问题的能力。仅此而已,但这已经很多了,因为对手写提示词你根本问 不出任何问题。


通常会出什么错

症状 可能的原因 如何诊断 改什么
模型返回看似合理的散文,解析却失败 输出结构是以散文请求的,而非被强制的 记录原始响应,统计解析失败的次数 把输出变成显式字段并校验它们
一次提示词改动改进了一个模型、弄坏了另一个 provider 特定的措辞与任务定义熔合在一起 用相同的输入跑两个模型 把任务契约与 LM 配置分开
没人说得清 v7 是否胜过 v6 提示词版本没有与冻结的数据集或指标绑定 查找已保存的示例、一个打分函数和运行记录 让评估成为程序生命周期的一部分
提示词不断变长 每次失败都靠再追加一句话来打补丁 按原因给过去的失败分组:接口、语义、推理、模型、数据 把结构移进代码,把散文留给语义
输出看着没问题,却有细微的错误 这个失败模式没有检测器 问什么能自动抓住它;通常什么都抓不住 显式定义标准,然后检验这个标准
模型去改一句本来已经很好的句子 “改进这个"无法表达克制 检查保持输入不变是否可能是正确的输出 把"什么都不做"变成一等的预期结果

本章小结

手写提示词是个好的探索工具,却是个糟糕的工程单元。

它真正的缺陷不在于写得差,而在于一个工件同时承载了任务契约、执行策略、输出 schema、 provider 假设和版本身份,用的还是一种无法区分它们的介质。这就是为什么第 2 节里的三种 失败到来时看起来一模一样,却需要三种不同的修理。

我们去掉了一个假设:改进一个语言模型应用,意味着不断编辑提示词直到它感觉变好。

我们也点出了本书更大的问题。把行为变成实验变量,比决定一个改进主张被允许意味着什么 要容易。编辑改写会暴露这个缺口;仓库修复会让我们拿更强的外部证据来检验同一套机制。

我们还没有做的是设计替代物。我们有了一个带五个字段的签名,却没有交代为什么是这五 个、为什么是这些名字,以及输入与一段上下文之间的边界该落在哪里。一份弱契约会让后面 每个阶段都更糟——指标测量错的东西,优化器优化错的东西,而失败变得更难看见,而不是更 容易。

所以下一个问题显而易见:

一个语言模型组件需要具备哪些属性,才配得上被称为一个程序?