← DSPy From First Principles

超越本书:生产中的 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.py
2. 拒绝回归的记忆 stephanie/agents/dspy/memento.py
3. 一个小型 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/ 上运行。

  1. 强行制造一次错误的缓存命中。 在 run_budget_cache 中,把重放尾部从 trace[:2] 改成 ["unrelated step", "draft patch"]。在 tail_len=1 之 下,键就只是 ("draft patch",)——一个前向遍历已经存过的键——于是缓存以零 代价返回一个为另一段推理历史生成的步骤。把 tail_len=6 设回去,确认同 一次重放现在变成了未命中。在生产里,哪种失败更危险:为一次本可以缓存的重 复付费,还是重用了一个不属于这条路径的步骤?
  2. 不信任那个边际。 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)