DSPy From First Principles
把语言模型的行为变成一个实验变量,然后学会判断:优化何时是可测量的,改进何时是可信的,以及 DSPy 为这个过程贡献了什么。
一个语言模型应用不必始终停留在一堆提示词的状态。它可以变成一个程序——它的 行为可以被变动、被测量、被比较。
这才是 DSPy 最深层的贡献。重要的转变不是从一种写指令的方式换成另一种,而是 从"把提示词措辞当作手艺"转向"把语言模型行为当作实验变量"。
一旦行为成为实验变量,一个更难的问题就出现了:什么可以改变?什么证据引导这 次改变?什么算成功?哪些证据必须独立于优化之外?而当一个候选得分更高时,凭 什么说它就是改进?
本书从第一性原理出发,搭建这套实验系统。
我们从一个普普通通的手写提示词开始,不断追问它缺了什么。每一个答案都引入另 一个机制:一份契约、一个模块、一个数据集、一个指标、一个优化器、一个工具边 界、一个上下文策略、一道实验防火墙、一套晋升策略。
然后我们在两种不同的任务域里检验这套机制。编辑改写给了我们一个成功部分依赖 判断的任务:指标可以近似我们关心的东西,却可能漏掉一个承重的词。仓库修复给 了我们一个外部证据更强的任务:代码可以被解析,作用域可以被检查,测试可以确 立可观察的行为。
这个对照就是本书的经验问题:
当正确性从"对判断的代理"变成"由环境产出的证据"时,优化会发生怎样的 变化?
目标不是记住 DSPy 的 API。
而是充分理解 DSPy 让什么成为可能,好让优化器、智能体、反思式搜索和编译出来 的程序不再看起来像框架魔法,而变成可以检视的工程机器。
贯穿全书、反复出现的问题是:
程序究竟是什么?什么证据说它更好?优化器被允许看到什么?又凭什么替换掉 一个已经在正常工作的版本?
我们将要检验的问题
本书不假设"优化"和"改进"是同义词。
flowchart LR
A[编辑改写] --> B[成功部分依赖判断]
B --> C[指标是一种近似]
C --> D[优化可以钻遗漏的空子]
E[仓库修复] --> F[成功带有可执行的后果]
F --> G[解析、作用域与测试]
G --> H[优化可以被外部检查]
两种任务域都不提供完美的真实。人的编辑判断是真实的,即使它难以压缩成一个标 量;一套通过的测试套件也可能仍然不完整。区别在于可用证据的强度与独立性。
为了让这种比较成为可能,我们的进阶从简单开始:
flowchart LR
A[任务] --> B[签名]
B --> C[模块]
C --> D[语言模型]
D --> E[结构化输出]
然后我们加上凭经验改进这个程序所需要的机制:
flowchart LR
A[程序] --> D[基线评估]
B[示例] --> D
C[指标] --> D
D --> E[优化器]
E --> F[候选程序]
F --> G[未被触碰的评估]
G --> H[比较]
H --> I{决定}
I -->|证据更优| J[晋升]
I -->|证据不足或更差| K[拒绝]
到本书结尾,同一套实验纪律已经长成一套庞大得多的东西:
flowchart TD
A[任务] --> B[程序契约]
B --> C[执行策略]
C --> D[LM 模块]
C --> E[确定性代码]
D --> F[工具与上下文]
E --> F
F --> G[行为]
G --> H[观察]
H --> I[指标]
I --> J[分数与反馈]
J --> K[优化器]
K --> L[候选程序]
L --> M[独立保留集]
M --> N[比较]
N --> O{晋升决定}
O -->|晋升| P[生产证据]
O -->|拒绝| Q[保留生效版本]
P --> R[下一次实验]
Q --> R
语言模型仍然承担其中一部分工作。
但它不再是整个系统。
其余部分是软件、数据、评估、实验纪律和证据。
这条区分就是本书的地基。
本书打算教会你什么
跟着各章走完之后,你将学会如何把一个 LLM 应用里隐藏的部分变成显式的工程对 象。
你将学会如何:
-
把手写提示词与语言模型程序区分开;
-
把任务表达为一份语义契约,而不是把接口埋进散文里;
-
用 DSPy 签名(Signature)定义一个组件消费什么、产出什么;
-
把程序应该做什么与它如何尝试去做分开;
-
在同一份契约之下比较直接预测与显式推理等不同的执行策略;
-
把若干个 LM 操作组合成一个可检视的程序;
-
判断系统的哪些部分该放进确定性 Python,而不是再一次模型调用;
-
把底层语言模型当作一个可配置的依赖,而不是一个看不见的假设;
-
把 provider、模型、配置、回退状态和程序身份记录为一次运行之证据的一部 分;
-
把示例变成结构化数据,而不是手工把示范抄进提示词;
-
区分程序输入、标签、元数据、训练示例、示范、开发样例与保留集证据;
-
在允许优化器改动任何东西之前先建立基线;
-
区分优化、泛化与改进,而不是把这几个词当作可以互换;
-
设计能反映任务本身的指标,而不是只奖励顺手的代理;
-
在放心让优化器去追逐一个指标之前,先用对抗性示例攻击它;
-
使用确定性约束、参考证据、LM 评审器和人类偏好,而不把一种证据误当作另一 种;
-
把 DSPy 编译理解为"生成候选程序",而不是什么神秘的提示词改进;
-
用少样本(few-shot)优化来构造或选择示范;
-
用指令优化在面向 LM 的程序状态空间里搜索;
-
用反思式反馈解释失败并提出更好的指令;
-
理解为什么"提出改动"的是反思,而"决定这些改动是否真的有用"的仍然是评估;
-
把使用工具的智能体当作语言模型程序——它们的轨迹、工具和结果同样可以被测 量和优化;
-
设计有边界的工具接口,而不是把环境不加限制地交给 LM;
-
区分直接上下文、检索、记忆、智能体主导的搜索,以及对大上下文的程序化探 索;
-
阻止训练标签、未来的仓库修订、解决方案补丁、评估器输出,或反复查看保留集 污染一次实验;
-
为程序、数据集、指标、provider、工具面、检索系统和验证策略做版本管理,让 一次实验结果始终可解释;
-
把"优化器给出的分数"与"候选确实更好的独立证据"区分开;
-
把评估、比较、晋升、激活、观察、拒绝和回滚分成独立的操作;
-
把生产活动当作未来证据的来源,而不是自动把每一次交互都转成一个训练标签; 以及
-
把这些机制组装成一个仓库修复程序,它能通过受控实验自我改进,而不会悄悄晋 升自己的改动。
目标不是让提示词优化变得更精巧。
而是让语言模型行为变得更可理解、可测量、可复现、可改进。
一个论点,逐步搭建
各章在两种任务域之上搭建起同一个工程论点。编辑程序让主观的成功变得足够可测 量、可以优化,然后暴露出这个代理的边界。仓库修复则把同一套机制搬进一个环 境——在那里,正确性的重要部分可以被外部确立。
01 我们为什么还在手写提示词?
从一个合理的提示词开始,弄清楚为什么一个字符串
最终会成为一个不够用的软件抽象。
02 提示词还不是程序
给语言模型行为一个程序边界:
输入、声明的行为、执行与输出。
03 定义契约
用签名表达程序消费什么,
以及下游软件可以依赖什么。
04 把"做什么"与"怎么做"分开
保持任务契约稳定,
只改变满足它所用的执行策略。
05 用程序构建程序
把更小的 LM 组件与确定性 Python
组合成一个可检视的多阶段程序。
06 你的模型是一个依赖
把 provider、模型、配置、失败
与回退行为都变成显式的。
07 示例就是实验数据
把示例当作带有身份、来源、角色、权限
和冻结到家族级划分的数据来对待。
08 无法度量,就无法优化
先确立一个具名的基线并记录逐样例证据,
再去尝试优化。
09 当指标变成目标
主动攻击目标,暴露它表示不了的东西,
并把"优化成功"与"改进"分开。
10 编译程序
把优化当作在冻结的实验边界之内
产出一个候选程序的过程。
11 少样本优化
让优化器去选择和构造示范,
而不是手工往提示词里粘贴示例。
12 优化指令
在显式的指标、开发集与预算之下,
搜索指令与示范的空间。
13 让程序学会反思
把标量失败转化为诊断性反馈,
用来引导反思式的程序改进。
14 一次只改一件事
固定语料、程序、模型与优化器配置,
在失败可以被命名之后,只替换目标。
15 智能体也是程序
给程序工具,让它作用于环境,
而不放弃契约、测量或验证。
16 搜索、记忆与长上下文
当相关环境大于提示词时,
决定程序应该检视哪些证据。
17 搜索推理空间
在推理状态(而不只是程序状态)之上搜索,
并看清为什么预言机引导的搜索不算证据。
18 别让优化器作弊
围绕保留集、工具、记忆、检索、
历史与评估搭建一道实验防火墙。
19 从实验到生产
独立比较候选、审慎晋升、
观察生效版本,并保留回滚能力。
20 构建自我改进的工程程序
把这些机制组装成一个仓库修复系统,
它的每一次改进主张都有证据支撑。
21 超越本书:生产中的 DSPy 系统(附录)
看看本书的机制接下来去了哪里:带预算的
推理搜索、不会回归的记忆,以及一个小小的
基于案例推理模块——全部取自生产代码。
每一章都加入一个机制,因为前面的系统已经暴露出一个具体的局限。只有当这个局 限本身成为实验的对象时,任务才会更换。第 20 章是收官之作;第 21 章是一份附 录,它指向本书证据关口之外的生产系统,链接完整源码,而不是把它当作本书的证 据来主张。
这个顺序很重要。
在我们有指标之前,优化器毫无意义。在我们有示例和基线之前,指标难以信任。而 一旦优化器能够搜索指令、检索记忆、调用工具、查看仓库历史,并从诊断反馈中学 习,保留集隔离就变得重要得多。
因此,最后一章没有再引入一个优化器。
它问的是:我们已经搭起来的所有东西,究竟能不能组合在一起。
最终得到的系统大致是这样的:
flowchart TD
A[工程请求] --> B[冻结仓库修订]
B --> C[检视证据]
C --> D[搜索、检索、使用工具]
D --> E[诊断]
E --> F[提出干预]
F --> G[生成候选补丁]
G --> H[隔离应用]
H --> I[验证]
I -->|失败| J[检视失败]
J --> K[理由充分时修订]
K --> G
I -->|通过| L[记录结果证据]
L --> M[评估程序行为]
M --> N[构建经审计的数据集]
N --> O[受控优化]
O --> P[候选程序版本]
P --> Q[独立保留集]
Q --> R[与生效基线比较]
R --> S{PROMOTE / REJECT / INSUFFICIENT}
S --> T[操作者决定]
T --> U[观察生产]
要点不是自主的自我修改。
而是受控的、经验性的改进。
必须分开的三个主张
本书刻意区分三个词:
optimization(优化)
候选在搜索所用的那个目标上得分更高
generalization(泛化)
候选在从任务中抽出的未见样例上表现更好
improvement(改进)
独立证据表明系统在其用途上确实变得更好
优化器可以在没有产生泛化的情况下成功。一个候选可以在代理之下泛化,却没有改 进真实的应用。编辑实验让这些区分变得可见;修复实验检验的是:当环境能够直接 检查行为时,这个主张能强到什么程度。
核心工程原则
语言模型是概率性的。
这很有用。
它们能生成改写、诊断、计划、补丁、搜索查询、工具选择、解释、假设,以及种种 难以用普通确定性逻辑表达的备选方案。
但这不等于 LLM 应用的每个部分都应该因此变成概率性的。
当普通软件能够可靠地确立某件事时,就让普通软件去确立它。
这段输出能被解析吗? → 解析器
它符合 schema 吗? → 校验器
这个工具被允许吗? → 能力策略
哪些示例属于保留集? → 数据集清单
补丁应用成功了吗? → 补丁引擎
测试通过了吗? → 测试运行器
那个具名实体保住了吗? → 确定性检查
是哪个程序版本生成了它? → 产物登记表
优化器见过这个样例吗? → 实验审计
候选击败基线了吗? → 评估器加比较策略
哪个版本正在生效? → 部署登记表
由此得到本书的核心规则之一:
在不确定性和生成式推理有用的地方使用语言模型。只要有可能,就把正确 性、身份、边界、测量和治理移进可以检视的软件里。
DSPy 因此占据了一个非常具体的位置。
它给了我们一套机制,用来表达并改进程序中概率性的部分。
它并没有消除围绕它们的那套确定性系统的必要性。
优化不是晋升
有一条区分会贯穿全书:
flowchart LR
A[优化器] --> B[候选]
B --> C[评估]
C --> D[证据]
D --> E[比较]
E --> F[建议]
F --> G[晋升]
G --> H[生效版本]
它们是不同的操作。
优化器可能会发现一个在开发示例上表现更好的程序。
但这并不使该候选有资格替换掉生效中的程序。
一个反思式优化器可能解释某个示例为什么失败。
但这并不使它提出的修复方案就是正确的。
一个智能体可能产出一条有说服力的轨迹。
这并不证明所要求的结果真的发生了。
一个编译出的程序可能取得更高的标量分数。
这并不能抹掉一次新的严重回归。
因此本书不断回到另一条规则:
优化器负责提出候选。独立评估负责确立证据。晋升是另一个独立的决定。
系统能力越强,这条区分就越重要。
证据有边界
优化引入了另一个问题:系统可能学会的是这次实验,而不是任务本身。
一个程序可能意外地把某个人的决定当作输入收到。
一条示范里可能藏着一个保留集样例。
一个检索索引里可能包含最终的答案。
一个仓库智能体可能看到后面某个提交,而那个提交里正好有这个补丁。
反思式反馈可能把参考答案泄露出来。
一个开发者可能查看了保留集上的失败、修改了程序,然后把同一批样例称作"从未 被触碰过的测试集"。
所有这些都能制造出看起来很漂亮的结果。
但它们没有一个能提供关于"整体改进"的可信证据。
因此,实验边界必须成为软件的一部分:
允许:
训练示例
开发示例
决策时刻的仓库证据
已批准的工具
已批准的记忆
已批准的检索来源
不允许:
保留集标签
未来的结果
解决方案补丁
决策之后的元数据
隐藏的评估器状态
未来的仓库修订
到本书结尾,一个程序版本只有与描述它如何被创建、如何被评估的证据放在一起来 看时才有意义。
读完之后你应该能做到什么
目标不是让你记住每一个 DSPy 优化器或每一个当前的 API。
DSPy 会变。
更持久的目标是:让你面对陌生的 DSPy 和 LLM 编程系统时,能把它读懂。
你应该能打开一个系统,然后问:
真正的程序是什么?
它的任务契约是什么?
哪些部分是 LM 行为?
哪些部分是确定性软件?
正在使用哪种执行策略?
是哪个模型、哪个 provider 执行了它?
程序能看到哪些示例?
优化器能看到哪些示例?
哪些样例是真正未被触碰过的?
这个指标奖励什么?
这个指标能被钻空子吗?
优化器能改动什么?
优化产出了什么产物?
是什么反馈导致了一次反思式变异?
有哪些工具可用?
检索或记忆能暴露哪些证据?
这些来源里有没有哪个会泄露答案?
候选是如何被评估的?
在什么条件下它会与基线比较?
由谁决定它是否晋升?
哪个版本正在生效?
能回滚吗?
哪些生产证据有资格进入下一次实验?
这些问题比某个优化器当下的名字更持久。
它们也让调试精确得多。
与其说:
DSPy 没有改进我的程序。
我们可以追问:这次失败究竟发生在契约、示例、划分、指标、模型、示范、指令搜 索、反思反馈、检索、工具使用、评估流程,还是晋升策略上。
这是一种有用得多的语言模型系统工程方法。
你还会学到什么时候不该优化
DSPy 让优化变得触手可及。
但这不意味着每个程序都应该被优化。
如果一个直接的 Predict 就能可靠地解决任务,加一个多阶段模块可能只是增加
了延迟和失败模式。
如果确定性代码就能强制执行一条约束,那么去搜索一条说服模型遵守它的指令,可 能是更弱的设计。
如果数据集很小或很嘈杂,优化器学到的可能大多是偶然。
如果指标并不代表真实目标,那么更好的优化只会让系统更快地变差。
如果是检索失败让模型看不到必要的证据,那么指令优化解决的是一个错误的问题。
如果现有程序已经满足真实需求,那么去搜索一个数值上更高的程序可能没有任何实 际价值。
因此在全书中,我们都从基线出发,只有当一个具体的失败证明有必要时,才加入新 的机制。
目标不是最大化的优化。
而是经得起测量的、真正有用的改进。
这本书写给谁
你应该熟悉 Python,也熟悉"调用语言模型"这个基本概念。
你不需要预先具备 DSPy 经验。
你不需要提前了解它的优化器 API。
你也不需要搭建过完整的智能体系统。
示例从普通的 Python、显式的数据结构、小型 DSPy 程序和看得见的评估代码开 始。更高级的机制只有在它们所依赖的部分就位之后才登场。
如果你已经搭建过生产级 LLM 应用,后面的章节同样会有用。
它们越来越聚焦于第一个 demo 跑通之后才会出现的问题:
我们怎么知道这个版本更好?
到底改了什么?
能复现吗?
优化器作弊了吗?
程序能安全地行动吗?
它能找到正确的上下文吗?
什么样的证据才配得上一次部署?
当生产环境证明我们错了,会怎样?
这些是工程问题,不是提示词问题。
本书不打算覆盖什么
这不是一本关于每个 DSPy 类的百科全书。
它不打算把每一个优化器选项、适配器、provider、实验性模块、部署集成或 API 参数都记录一遍。
这些细节变化太快,撑不起本书的概念主干。
相反,本书聚焦于它们下面的机制:
契约
执行
组合
数据
测量
优化
反思
工具
上下文
实验隔离
版本管理
比较
晋升
证据
我们会用当前的 DSPy API 让这些机制变得具体。
但目标是让这套推理在 API 变化之后依然成立。
这也不是在主张每个语言模型应用都应该变成一个自我改进的系统。
有时候正确的解法就是一个提示词。
有时候就是一个 Predict。
有时候就是普通的 Python。
有时候就是一个固定的工作流。
本书的这套机制,应当由它所解决的那个问题来挣得。
这本书的承诺
读完 DSPy From First Principles 之后,你应该能面对一个陌生的语言模型应 用,弄清楚:
程序究竟是什么;它规定了什么行为;什么证据在测量那种行为;优化器被允许 改动什么;它被允许看到什么信息;以及什么样的证据才足以替换当前版本。
你还应该能问出最后一个问题:
当这个系统说新程序更好时,究竟是什么让这个主张值得信赖?
一旦你能回答这个问题,DSPy 就不再是一堆提示词优化技巧。
它会变成有用得多的东西:
一种把概率性的语言模型行为纳入经验性工程流程的方法。
章节
我们为什么还在手写提示词?
从一个合理的手写提示词开始,看它以三种不同的方式失败,并把 DSPy 框定为把语言模型行为变成实验变量的机制。
提示词还不是程序
界定一个语言模型组件在配得上被称为程序之前需要具备的属性——并理解为什么这些边界是受控比较的前提。
定义契约
把 DSPy 签名当作任务契约来处理:审慎地选择字段名,决定什么该进入边界之内,在类型能够暴露失败的地方使用类型,删掉没有任何东西消费的字段。
把"做什么"与"怎么做"分开
把任务契约完全固定,只改变执行策略,测量这份额外推理在 222 次本地调用中究竟买到了什么。
用程序构建程序
用确定性 Python 组合若干 DSPy 模块,然后测量哪些中间阶段真正影响结果,以及这种拆分是否值回它的成本。
你的模型是一个依赖
把语言模型当作一个受控的实验依赖:显式的身份、诚实的回退状态与可复现性证据——包括为什么温度为零并不给你确定性。
示例就是实验数据
搭建真正的评估实验夹具:带来源信息的结构化数据行、家族而非孤立样例、尊重家族的划分,以及围绕优化可以消费什么划定的显式边界。
无法度量,就无法优化
定义指标、冻结评估协议、测量程序——然后看清为什么一个可度量的目标会让错误的行为变得系统性地可优化。
当指标变成目标
主动攻击目标,把打分与诊断分开,并决定当优化能够钻一个你已证明并不完备的工具的空子时,该怎么办。
编译程序
把 DSPy 编译当作冻结边界之下的候选生成——然后去看优化器实际读了什么,并发现扩大语料库并没有给本章买来任何东西。
少样本优化
编译一个少样本候选,看它提升一个指标、损害另一个指标,再弄清为什么改成对着更好的指标编译,结果什么也没有改变。
优化指令
让 MIPROv2 在指令与示范上搜索,把它找到的改进一路分解到产出它的那一个案例,再看着第二个优化器像第一个一样弄坏同一句话。
让程序学会反思
给优化器语言而不是标量,看着 GEPA 提出三个变异又全部拒绝——然后追问被拒绝的候选是不是真的更差。
一次只改一件事
把语料库、程序、模型、优化器配置和评测框架固定住,只替换目标,检验当失败变得确定且可具名时,优化是否会改变方向。
智能体也是程序
给程序有边界的环境访问权限,攻击你建起来的边界,并测量当安全的工具把正确的证据交给仍然差一步到位的推理时会发生什么。
搜索、记忆与长上下文
把任务、改写程序、模型配置与指标固定住,只变动补充证据的获取方式,并测量六种上下文策略——包括自适应选择和一条失败的 RLM 路径。
搜索推理空间
从第一性原理推导出建立在推理状态之上的 MCTS,在 DSPy 中构建它,审视这棵树是否真的在分支;然后在两个模型上运行带预算的七策略对比——附带一个预言机泄漏对照——并把它确立的结论与它无法确立的结论分开。
别让优化器作弊
为 DSPy 优化搭建一道实验防火墙,让工具、记忆、反馈、检索和保留集证据都无法悄悄泄露答案。
从实验到生产
把封存的保留集只花费一次,再搭起一道有序的治理关口,决定一次离线胜利被允许授权什么——独立评估、晋升、激活与回滚,作为五份各自独立的记录。
构建自我改进的工程程序
把本书的机制组装成一个仓库修复程序,带上契约、工具、上下文策略、验证、优化、晋升与生产证据。
超越本书:生产中的 DSPy 系统(附录)
附录:本书的模式——带预算的推理搜索、不会回归的记忆冠军、一个胜过其类型签名的解析器——运行在一个真实的生产代码库里;确定性机制由一份已提交的实验夹具复现,完整源码以链接给出。