超越本书:生产中的 DSPy 系统(附录)
附录:本书的模式——带预算的推理搜索、不会回归的记忆冠军、一个胜过其类型签名的解析器——运行在一个真实的生产代码库里;确定性机制由一份已提交的实验夹具复现,完整源码以链接给出。
第 20 章把本书的机制组装成了一个循环。这个附录做的事更小也更具体:它展示其中三 个机制已经运行在一个并非为本书而写的生产代码库里,并且它给自己立下了一条比各章 更严格的证据规则。
本附录的证据规则。 这里有两层。每次语言模型调用周围的机制——UCT 选 择、预算闸门、轨迹缓存、冠军更新规则、输出解析器——是确定性软件,一份已提交 的实验夹具(
experiments/dspy-from-first-principles/ch21_beyond_book/)在 既没有 LM 也没有 DSPy import 的情况下运行它们。那些结果是被测量的。 内核本身——这些摘录所出自的生产模块——是来自单一代码库的选择性证据,不 是一次泛化。它们的完整源码在 Stephanie repository 中,下面 给出链接,并固定在main分支的修订32d02ee(2026-01-06)上。
小节 完整源码 1. 带预算的推理搜索 stephanie/agents/dspy/mcts_reasoning.py2. 拒绝回归的记忆 stephanie/agents/dspy/memento.py3. 一个小型 CBR 模块 stephanie/agents/dspy/cbr_dspy.py
这个代码包里的文件比这里摘录的三个更多。有三个文件明明在包里,却被刻意排除在外,
理由与第 17 章对自己的代码所用的审计理由相同:lats_dspy.py 把 forward() 拆
成一些它从不返回的名字,还调用一个并不存在的 example.with_score(...);
learning_from_learning.py 调用 dspy.Advise,它不是一个当前的优化器,会像第
12 和第 13 章里修复前的 MIPRO 与 GEPA 代码片段一样失败;prompt_compiler.py
建立在一个非 DSPy 的 LLMCompiler 之上。一个真实仓库里能运行的代码不自动就是
正确的代码,而一段书籍摘录不应该替它洗白。
这三个内核都能直接映射回本书。第 1 节是第 17 章推理搜索的生产形态。第 2 节是第 16 章与第 19 章的合体——记忆加上晋升。第 3 节是第 7 章"示例即数据"在最小尺度上 的版本。它们中没有一个改变第 1–20 章得出的任何结论。
1. 带预算的推理搜索
第 17 章搭了一个推理搜索智能体,却停在了成本边界之前。这里是它只做了描述的部分: 搜索中的每一次语言模型调用都要经过同一道闸门。
程序外壳把生成与评判分开——两个签名,两个 predictor:
class TraceStep(Signature):
state = InputField(desc="Current problem state")
trace = InputField(desc="History of thoughts/actions so far")
next_step = OutputField(desc="Next reasoning step")
class ValueEstimator(Signature):
state = InputField(desc="Current problem state")
trace = InputField(desc="Reasoning steps taken")
goal = InputField(desc="Goal text")
score = OutputField(desc="Normalized score (0-1)")
rationale = OutputField(desc="Why this path is promising")
class MCTSReasoningProgram(dspy.Module):
def __init__(self, cfg):
super().__init__()
self.generator = Predict(TraceStep)
self.value_estimator = Predict(ValueEstimator)
self.max_depth = int(cfg.get("max_depth", 3))
这些字段没有类型标注,所以 DSPy 默认把它们当成字符串。本书的约定是
name: type = InputField(...);类型标注是编译器并不强制执行的文档,而这本身就
是第 3 章关于契约究竟住在何处的要点。两种写法的行为完全相同。
选择用的是标准 UCT。一个未被访问的子节点返回无穷大,这迫使搜索先把每个分支试过 一次,统计才有意义:
def uct_value(self, parent_visits, ucb_weight):
if self.visits == 0:
return float("inf")
exploitation = self.reward / max(1, self.visits)
exploration = ucb_weight * math.sqrt(
max(1e-9, math.log(max(1, parent_visits)) / self.visits)
)
return exploitation + exploration
成本边界就是一个方法。每一次生成调用都先检查预算,并查询一个以轨迹尾部为键的 最近最少使用缓存:
def _predict_next(self, state: str, trace: list[str]) -> str:
if self.calls_used >= self.max_lm_calls:
return ""
key = self._cache_key(state, trace)
cached = self._cache_get(key)
if cached is not None:
return cached
pred = self.generator(state=state, trace=trace)
self.calls_used += 1
nxt = pred.next_step.strip() if getattr(pred, "next_step", None) else ""
self._cache_put(key, nxt)
return nxt
在 max_lm_calls=12 之下,搜索无法靠花钱砸出一个好看的意外。这个缓存还有本书
在意的第二个效果:一对相同的 (state, trace-tail) 只花一次调用,因此搜索中重
复出现的结构只需付费一次——第 8 章那条"优化之前先给基线命名"的规则,被用到了搜
索本身身上。
评估是按计划调度的,而不是连续进行的。eval_at 开关(leaf,或者配合
eval_stride的 every_k)决定哪些节点会被打分:
def _should_eval(self, node) -> bool:
if self.eval_at == "leaf":
return self._is_terminal(node)
return (len(node.trace) % max(1, self.eval_stride)) == 0
这就是第 17 章关于价值函数合法性警告的具体形态。给每个节点打分,搜索就会去拟合
打分器;只给叶子打分,树的大部分就是在盲跑。不存在正确的设置——只存在你把成本写
下来了的那一个设置,这也正是整套配置(max_depth、branching_factor、
num_simulations、ucb_weight、max_lm_calls、eval_at、eval_stride)都
在构造时放在同一个地方的原因。
实验夹具证实了这一点。 在一张固定的表上——一个未访问的子节点、一个被利用的
领先者(10 次访问,奖励 7.0)、一个探索不足的子节点(3 次访问,奖励 0.9),父
节点访问数 13,ucb_weight=1.41——选择顺序是
unvisited → under-explored → leader。探索不足的子节点拿到 1.60,领先者是
1.41,尽管它的平均奖励更低(0.30 对 0.70):探索项在真正干活,不是装饰。预
算闸门把调用次数压在上限之内,而重放一个更早的(state, trace-tail) 会以零额外
代价返回那个缓存的步骤。
2. 拒绝回归的记忆
第 16 章搭建了检索与记忆;第 19 章搭建了带回滚的晋升。把二者连起来的生产系统是 一个基于案例推理的智能体,它有一条结构性保证:冠军只会被在测量上更好的东西替 换,而且是在同一个种子之下。
每次按计划的运行比较两个变体。A 是没有案例簿、保留功能关闭的基线。B 是打开了保 留功能的完整基于案例的路径。种子被锁定,好让差值测量的是案例簿,而不是采样噪声:
base_res = await self._run_single_variant(
context, variant="baseline",
use_casebook=False, retain=False, # control never writes to memory
casebook_tag=self.ab_control_tag,
)
cbr_res = await self._run_single_variant(
context, variant="cbr",
use_casebook=True, retain=True,
casebook_tag=self.casebook_tag,
)
q_base = float(base_res["metrics"]["quality"])
q_cbr = float(cbr_res["metrics"]["quality"])
improved = q_cbr > (q_base + self.ab_delta_eps)
self._update_non_regression(home_casebook_id, goal["id"], cbr_res, improved)
winner_variant = "cbr" if improved else "baseline"
context[self.output_key] = context.get(self._variant_output_key(winner_variant), [])
三个细节承载着本书的教训。基线臂上的 retain=False 意味着对照无法写入它所锚定
的记忆——第 18 章的防火墙即代码。两个变体写入带命名空间的输出键,只有胜者会被投
射到规范输出上,因此一个落败的候选不会意外泄漏到下游——第 19 章把晋升与激活分开
的做法,由键结构强制执行。而 ab_delta_eps 只是一条下限,不是一条边际:第四位
小数上的差异就能越过它,却毫无意义。
晋升本身在失败的案例上什么都不做,这正是全部保证:
def _update_non_regression(self, casebook_id, goal_id, run_result, improved):
"""Promote the champion only on a non-regressing improvement."""
if not improved:
return
...
self.memory.casebooks.upsert_goal_state(casebook_id, goal_id, case_id, quality)
没有哪条示范、哪次反思、哪条轨迹会因为潜力而被晋升。这就是第 14 章反复出现的那 句话的生产形态——反思提出,评估裁决——写入路径除非数字越线,否则一直保持关闭。
为 CBR 臂供给的重用路径遵循一个固定优先级(冠军,然后是近期成功,然后是多样的 新颖案例),并以一个重用预算封顶,因此检索是一条带预算的策略,而不是一个敞开的 水龙头。完整的 1,027 行文件——训练事件的管线、微学习钩子、带命名空间的草稿上下 文——都在源码链接之后;上面那个内核才是论证需要的部分。
实验夹具证实了这一点。 在与冠军 0.70 对比的五组质量差上:平局保持冠军;
+0.0000005 的差异(低于 ab_delta_eps = 1e-6)保持它;+0.0005 越过了
epsilon 并触发晋升,却过不了实际意义上的 0.01 边际——夹具标记的正是这个缺口;
+0.08 干净地晋升;而 -0.09 的回归保持不变。最终冠军质量 0.78。epsilon 挡
住的是零晋升;只有真正的边际才能挡住噪声晋升。
3. 一个凭本事立足的小型 CBR 模块
在两个大系统之后,代码包里最有教育意义的文件反倒是最小的之一:一个签名、一个模 块和一个解析器——而教训就在解析器里。
契约把程序消费的东西与下游软件可以依赖的东西分开,正如第 3 章所规定的那样:
class CBRSignature(Signature):
"""DSPy signature for CBR hypothesis generation."""
documents: str = InputField(desc="Relevant documents or text passages to review")
goal: str = InputField(desc="The research or reasoning goal")
task_instructions: str = InputField(desc="Task framing and example for CBR")
hypotheses: list[str] = OutputField(desc="Clear, testable, actionable hypotheses")
class CBRModule(dspy.Module):
def __init__(self):
super().__init__()
self.generator = dspy.Predict(CBRSignature)
def forward(self, documents, goal, task_instructions=""):
return self.generator(
documents=documents, goal=goal, task_instructions=task_instructions,
)
task_instructions 是值得注意的那个字段。它把任务框架和一个范例作为数据带进
调用,而不是作为隐藏的提示词手艺——这使指令成为一个可版本化的输入:可见、可
diff、可冻结,而不是程序身份的一部分。当第 12 章的指令搜索改写措辞时,它改写的
东西就处在这样的地位。
输出声明了 list[str],然后拒绝信任这个声明。模型输出可能以列表、带编号的文本
块,或者别的什么形式到来,所以模块把这三种情况都规整化,并给结果封顶:
def _parse_hypotheses(self, raw) -> list[str]:
hypotheses = []
if isinstance(raw, list):
for h in raw:
if isinstance(h, str) and len(h.strip()) > 10:
hypotheses.append(h.strip())
elif isinstance(raw, str):
for line in raw.strip().split("\n"):
line = re.sub(r"^\d+[\.\)]\s*", "", line).strip()
if len(line) > 10:
hypotheses.append(line)
else:
self.logger.log("ParseHypothesesError",
{"type": str(type(raw)), "value": str(raw)[:200]})
return hypotheses[: self.max_hypotheses]
这就是第 5 章"显式阶段必须挣得因果影响力"在最小尺度上的版本:声明的类型不解析, 解析器来解析,而第三种情况——没有人预料到的那种形状——会连同它的类型和一个 200 字符的样本一起被记录下来,而不是被静默丢弃。模块别处对文档做的 4,000 字符截断, 是同一条纪律施加在输入上:一条带日志行的可见性边界,好让上下文窗口的压力被观察 到,而不是被吸收掉。
代码包里的思维链文件不作摘录:它的签名(输入 question,可选的 references
与preferences,输出 answer)正是第 4 章的模式——一份契约,推理风格作为输入
携带——而本书已经教过它了。
实验夹具证实了这一点。 列表输入
[" If steps are stored as cases… ", "short", 42] 被规整成一个假设:空白被
裁掉,太短的字符串和那个整数被丢弃。带编号的文本块被规整成两个("3. x" 那一
行因为太短被丢掉)。字典输入返回 [],形状是 unexpected_shape_logged——被记
录,而不是被丢弃。
4. 模拟循环推理深度
前面几节向后看:三个已经存在于生产代码里的机制。我们最后向前看。
最近的循环深度架构提示了另一种花费推理时算力的方式。与其生成一条更长的可见推理 轨迹,或者搜索若干条备选的推理路径,一个模型可以反复变换一个不断演化的内部表示, 然后才产出答案。
DSPy 无法直接复现那个机制。一个 DSPy 模块看到的是语言模型的输入与输出;它通常 不会暴露 Transformer 的隐藏状态,也不会让我们把那个隐藏状态再次送过同一个神经 块。
但我们可以复现它的计算形态,并把它最重要的那个变量显式化:
问题
↓
状态₀
↓
相同的变换
↓
状态₁
↓
相同的变换
↓
状态₂
↓
相同的变换
↓
状态₃
↓
答案
我们不再跨多条推理路径搜索,而是反复加深同一个状态。
这给了我们一个新的实验变量:
循环深度 = 1, 2, 4, 8, ...
最小的 DSPy 版本需要两份契约。一份变换状态,另一份把最终状态转换成答案。
import dspy
class RefineState(dspy.Signature):
"""Update the current problem representation.
Do not produce the final answer. Preserve useful information,
correct weak assumptions, and make the state more useful for
solving the problem.
"""
problem: str = dspy.InputField()
state: str = dspy.InputField(
desc="Current compact problem representation"
)
next_state: str = dspy.OutputField(
desc="Revised compact problem representation"
)
class SolveFromState(dspy.Signature):
"""Produce the answer from the final problem representation."""
problem: str = dspy.InputField()
state: str = dspy.InputField()
answer: str = dspy.OutputField()
循环程序就是包在两个 DSPy 模块外面的普通 Python:
class RecurrentReasoner(dspy.Module):
def __init__(self, depth: int):
super().__init__()
self.depth = depth
self.refine = dspy.Predict(RefineState)
self.solve = dspy.Predict(SolveFromState)
def forward(self, problem: str):
state = problem
states = []
for step in range(self.depth):
result = self.refine(
problem=problem,
state=state,
)
state = result.next_state
states.append(state)
result = self.solve(
problem=problem,
state=state,
)
return dspy.Prediction(
answer=result.answer,
states=states,
depth=self.depth,
)
迭代之间,模型的任何东西都没有改变。
同一个 LM
同一个签名
同一个模块
同一个任务
同一个初始问题
改变的只有推理时算力的量。
这让我们可以比较:
depths = [0, 1, 2, 4, 8]
for depth in depths:
program = RecurrentReasoner(depth=depth)
result = program(problem=problem)
evaluate(
answer=result.answer,
depth=depth,
)
depth=0 尤其重要。它是对照条件:不经过循环精炼,直接从原始状态综合出答案。
现在,深度本身成了一个实验变量。
花掉推理算力的三种方式
这让我们可以与本书前面搭建的推理系统做一个有益的对照。
思维链程序通过延长一个序列来花费额外的算力:
思考₁
↓
思考₂
↓
思考₃
↓
答案
第 17 章的树搜索通过探索备选来花费它:
state
/ | \
/ | \
A B C
/ \ / \
循环模拟通过反复变换同一个状态来花费它:
状态₀
↓
状态₁
↓
状态₂
↓
状态₃
↓
答案
这是三种不同的算力分配策略:
flowchart LR
C[额外的推理算力] --> LT[更长的轨迹:ChainOfThought]
C --> WS[更宽的搜索:Best-of-N、树搜索、MCTS]
C --> DS[更深的状态变换:循环精炼]
这个区别很重要,因为相等的算力预算未必产生相等的行为。
实验
一次有用的初步比较,会把任务、模型、数据集、指标、采样配置和评估策略固定住,只 改变推理策略。
直接
ChainOfThought
循环深度 = 1
循环深度 = 2
循环深度 = 4
循环深度 = 8
对每种条件至少记录:
任务分数
硬回归
LM 调用次数
输入 token
输出 token
端到端延迟
成本
对循环条件,还要保留每一个中间状态。
这又给了我们一个有用的测量:
深度 分数 边际收益
0 ...
1 ...
2 ...
4 ...
8 ...
有趣的问题并不只是深度 8 是不是得分最高。
而是:
多一份推理时算力究竟买到了什么?
每一种可能的结果都能教会我们一些东西。
分数随深度上升
→ 反复精炼看起来有用
分数先上升后趋于平坦
→ 这个任务存在一个有用的推理深度前沿
分数先上升后下降
→ 更多算力导致过度思考或状态漂移
分数不动
→ 循环只是在为反复的重新表述买单
成本涨得比质量快
→ 循环有效,但挣不回它的预算
一个特别重要的失败模式是状态坍缩。
反复精炼可能逐渐抹掉信息:
状态₀
全部相关证据
状态₁
有用的抽象
状态₂
更短的抽象
状态₃
笃定的总结
状态₄
丢掉了那个要紧的限定词
于是更多的推理反而会让这个表示变得更糟。
这个可能性把循环深度直接连到了本书的中心论点:额外的优化或计算并不等同于改进。
类比到此为止
这个实验绝不能被描述成实现了潜在的循环推理。
一个真正的循环深度模型可以近似地执行:
hₜ₊₁ = R(hₜ)
其中 h 是网络内部的一个连续神经表示。
我们的 DSPy 程序执行的更接近于:
textₜ₊₁ = LM(problem, textₜ)
因此状态在每一次迭代都要跨过一个语言瓶颈。
这个差别是实质性的。
DSPy 实验无法告诉我们,在隐藏表示里直接推理,是否比通过 token 推理更快、更丰富、 更不可解释或者更有能力。
它能检验的是这项技术底下的那个架构命题:
当同一个变换被反复施加于一个演化的状态时,一个固定的语言模型程序能否受益? 这种收益又如何随着推理深度的增加而变化?**
这就足以让循环成为一个实验对象,而不是一个架构之谜。
它还给了我们对本书原有进阶的最后一次延伸:
提示词措辞
↓
程序
程序
↓
可测量的行为
行为
↓
优化
优化
↓
在程序之上搜索
智能体
↓
在动作之上搜索
检索
↓
在证据之上搜索
推理搜索
↓
在推理路径之上搜索
循环推理
↓
在计算深度之上搜索
DSPy 无法伸进 Transformer 内部去执行潜在的循环。
但它可以让我们先问出那个工程问题:
如果想得更久不再意味着写下更多思考,额外的算力该往哪里去?
通常会出什么错
失败会聚集在本书所说的地方——在边界上,而不在模型调用的内部。
| 症状 | 原因 | 改法 |
|---|---|---|
| 超支是一张意外账单 | max_lm_calls 住在注释里,而不在 _predict_next 里 |
每次调用都检查预算;耗尽时返回空,好让轨迹显示出这次耗尽 |
| 重复要付全价,或者不同的状态相撞 | 缓存以完整轨迹为键,或者尾部太短 | 尾部长度才是真正要做的决定——把它放进配置里,就放在预算旁边 |
| 冠军在噪声中一路上扬 | 仅凭 ab_delta_eps 就晋升 |
要求一个边际,而不是一个非零的 epsilon:“测量上更好"与"测量上不同"之间的区别 |
| 一个结构化输出让下游阶段崩溃 | 代码信任 hypotheses: list[str] |
从第一天起就把规整器放在契约旁边,并为没有人预料到的形状留一行日志 |
| A/B 差值其实是采样噪声 | 两个变体之间种子没有锁定 | 为这次比较锁定种子——第 6 章"模型即依赖"再往上一层 |
本章小结
这个附录不改变第 1–20 章的任何结论。它展示的是本书的机器在一段早于本书的代码里、 在更高一层上运行的样子:一个把预算写了下来的搜索,一个只有在改进越过边际时冠军 才会移动的记忆,以及一个小型模块——它的解析器做的,正是它的类型签名仅仅声明了的 工作。
横跨三个内核的模式,正是本书自第 2 章起反复重申的那个模式。语言模型负责生成。 确定性软件——预算、缓存、种子锁定、带命名空间的键、解析器、边际——决定那次生成被 允许意味着什么。生产并不需要一个新想法。它需要的是让那些旧想法拥有默认保持关闭 的写入路径。
上面的机制由那份已提交的实验夹具复现;完整智能体由 LM 支撑的行为并不在这里运行, 它们的数字无论如何也只是来自单一代码库的选择性证据。在信任它们产出的形态之前, 先拿你自己的任务去跑一遍。
练习
两个练习都在 experiments/dspy-from-first-principles/ch21_beyond_book/ 上运行。
- 强行制造一次错误的缓存命中。 在
run_budget_cache中,把重放尾部从trace[:2]改成["unrelated step", "draft patch"]。在tail_len=1之 下,键就只是("draft patch",)——一个前向遍历已经存过的键——于是缓存以零 代价返回一个为另一段推理历史生成的步骤。把tail_len=6设回去,确认同 一次重放现在变成了未命中。在生产里,哪种失败更危险:为一次本可以缓存的重 复付费,还是重用了一个不属于这条路径的步骤? - 不信任那个边际。 A/B 夹具把第三组(
0.7005对0.70)标记为clears_margin_0_01: false,尽管它在delta_eps之下会晋升。调低margin_demo直到那个标记翻成true;你会落在0.0005上。现在,对这一 组而言,epsilon 和边际——代码把它们当作不同的概念——是同一个数字。如果只有 真正的边际才能防住噪声,那么ab_delta_eps究竟在防什么?
延伸阅读
- Case-Based Reasoning: Foundational Issues(Aamodt and Plaza, 1994): 第 2 节的案例簿与第 3 节的模块都实例化的那个检索–重用–修订–保留循环。( AI Communications 7(1))
- The Tail at Scale(Dean and Barroso, 2013):为什么一个会返回降级结果 的硬性单次调用预算,胜过一个无界却很晚才给出好结果的预算。( CACM 56(2))
- Monte Carlo Tree Search: A Review(Browne et al., 2012):第 1 节里的 UCT 规则的完整版本。(IEEE)