← DSPy From First Principles

你的模型是一个依赖

把语言模型当作一个受控的实验依赖:显式的身份、诚实的回退状态与可复现性证据——包括为什么温度为零并不给你确定性。

第 5 章搭出了一个组合程序,测量了它的哪些阶段值回成本。那一章里的每个数字, 以及之前第 4 章里的每个数字,都有一个没有明说的限定词:

哪个模型执行了这个程序?

这不是运维层面的琐事。一个语言模型程序不能被它的签名(Signature)和模块完整 描述。它的行为取决于 LM 边界背后坐着什么,以及那样东西是如何被配置的。

因此模型既是一个依赖,也是一个实验变量。把它固定住,往往和替换它一样重要:

模型固定 + 目标改变
    → 可解释的目标实验

模型改变 + 目标改变
    → 混合干预

本书后面受控的优化实验,在变化程序状态或目标的同时,保留同一个本地 Qwen3 依 赖。模型比较是另一个实验,值得一套单独的协议。

    flowchart TD
    P[DSPy 程序] --> B[LM 边界]
    B --> L[本地模型]
    B --> H[托管模型]
  

签名和模块止于边界;边界背后坐着一个模型,它的 provider、身份和配置全都是实验 变量。本章把这个依赖变成显式的:配置它、给它做指纹、对它做失败测试,并且——在 最让我们意外的那一节里——并不像 temperature=0 诱使我们假设的那样确定。


1. 显式地配置 LM

import dspy

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,由 Ollama 经由 DSPy/LiteLLM 路径在本地提供服务。原生 Qwen 思考被关闭,以免模型层面的推理模糊 掉第 4 章比较的那些 DSPy 执行策略。

七个设置,每一个都是实验条件的一部分:

模型标识符
provider 路由
base URL
temperature
max tokens
原生思考模式
缓存行为

两次都被称作“Qwen3”的运行,可以在其中每一个设置上都不同,并产出不同的结果。 那个友好的模型名字不是依赖,配置才是。


2. 温度为零不是确定性

下面这个发现,改变了本书其余部分报告数字的方式。

一次早期的基线审计,在五个独立会话里,用同一个未改动的程序评估同样那十一个开 发案例,温度为 0、缓存关闭、记录在案的配置保持固定。

十一个案例里有九个在所有这些会话中产出相同的输出。另外两个没有。

案例 ed-033——一句关于咖啡烘焙师的营销文案——暴露出最清晰的分裂。一次运行产 出得分 0.927 的改写;另一次产出一个貌似合理的替代方案,得分 0.818。程序 状态和声明的 LM 配置都没有变,输出却变了。

这就是重要的观察。模型字符串、温度、提示词契约和输入指纹是必要的来源信息,但 它们不是重复输出的完整保证。

对那些基线运行中聚合数字的影响:

同一个程序、同样的案例、同一份记录在案的配置,五个会话
      ↓
开发家族均值观测到 0.7893 到 0.7992
      ↓
观测到的端到端跨度:约 0.010

这个跨度是有牙齿的,但它不是一个普适的统计意义上的“噪声底”。五个会话太少,不 足以估计一个噪声底;而后面交错的实验暴露出另一个与顺序相关的变异来源。

站得住脚的规则更窄:在这套装置上,来自单次执行调度的小差值不能自我解释。 第 4 章 v1 上的思维链差值是 +0.014;第 11 章最初的少样本差值是 +0.011。两者 都与从未改动的程序状态中已经观测到的变异同量级,因此在没有配对重复和适当阴性 对照的情况下,都不该被当作稳定效应。

我们不会假装这个实验隔离出了原因。看似合理的贡献因素包括:模型服务内核中的数 值非确定性、请求调度与批处理、进程或缓存状态,以及量化或其他服务细节引入的微 小 logit 扰动。

那些是假设,不是这个实验的发现。我们确实观察到的东西,与一个坐落在备选续写 附近的系统是一致的:当几条下一 token 路径彼此竞争时,微小的执行状态差异就可能 变得可见。但我们没有运行把该行为归到某一个机制名下所必需的受控精度、批处理、 缓存或内核实验。

最初那批块状重复让这种行为看起来在一次预热过的会话之内是确定性的:按相同 顺序重复的调用返回相同的字符串。结果那只是执行调度造成的假象,不是保证。

后面那对实验提供了更强的阴性对照。两个第 11 章的候选文件逐字节相同,但当多个程 序在一个会话里交错运行时,它们产出了不同的聚合分数(0.8005 对 0.7972)。由 于程序产物是相同的,那个差异不可能是候选效应。它是执行顺序或运行时状态中某处 诱导出的测量变异。

所以这种变异性至少有两种可观察的形式:

  • 跨会话漂移——同一个程序在一次全新的进程或模型状态之后,可能落在不同的输 出上;
  • 会话内的顺序效应——交错运行本来相同的程序产物,也能移动一个输出。

天真的设计两种都会漏掉。背靠背的重复看起来可能完全稳定,恰恰因为它们重复的是 相同的调用历史。

更强的设计是配对的,并跨全新进程重复:

会话 1:  基线、候选 A、候选 B
会话 2:  候选 A、候选 B、基线
会话 3:  候选 B、基线、候选 A
...

按案例和会话轮换顺序,使运行时状态不会被系统性地分配给某一个条件。逐案例、 逐会话计算差值,再聚合这些配对差异,而不是比较两个独立收集的均值。

在可能的地方,加入一个已知真实差值为零的阴性对照。逐字节相同的第 11 章候选给我 们的正是这个:它们之间任何被测量到的差异,都是测量过程中的变异,不是程序改进。

然后报告配对差值的分布——均值、中位数、离散度和符号计数——而不是一个单点估计。

这就是优化器各章所依赖的仪器。没有它,一个候选的小差值可能与执行状态变异无法 区分。


3. 模型改变时,什么应该变?

任务契约应当保持稳定:

sentence, goal, context  →  rewritten_text, rationale

这是面向任务的核心契约。组合后的实现还会发出 risk 和 assessment 这样的诊断字 段,但第 5 章表明,除非有某个下游策略消费它们,否则这些只是可观测性字段。

实现可能需要适配:

模型变化 可能的影响
托管到本地 延迟特征不同、可靠性不同、输出格式化不同
更大到更小 schema 失败更多、约束遵从更弱
温度调高 多样性更多、可复现性更差
provider 变化 超时、错误、速率限制、结构化输出行为不同
上下文上限变化 截断不同、输入静默丢失
量化变化 不同的 logits 或输出行为;重新测量,而不是假定等价

错误的回应是为每个模型悄悄重写签名,直到输出看起来可以接受。那是第 1 章的失效 模式换了一顶帽子——好几样东西同时在变,无法归因。

同一个程序
同样的案例
不同的 LM 依赖
        ↓
行为对比

把契约稳住,观察哪种失效模式真的出现,然后才决定要改的是契约、模块、验证还是 模型。


4. 静默回退是危险的

当 provider 失败时,总得发生点什么。那个诱人的形状:

try:
    return program(**inputs)
except Exception:
    return {"rewritten_text": sentence, "rationale": "unchanged"}

这保住了接口,却污染了每一条下游主张。记录现在说产出了一次改写。它没有说是否 涉及模型,于是一次针对这些记录的评估会高高兴兴地把回退当作模型输出来打分——而 且由于回退返回的是原句,它会得到 0.65 左右的分数,也就是结构下限。你的程序看起 来只是度过了平庸的一天,而不是遭遇了一次故障。

更好的形状把可用性与证据分开:

from dataclasses import dataclass

@dataclass
class ProgramRunResult:
    output: dict
    provider: str
    model: str
    used_real_lm: bool
    eligible_as_model_evidence: bool
    fallback_state: str | None
    error: str | None

def run_with_explicit_fallback(program, inputs, model_name: str) -> ProgramRunResult:
    try:
        pred = program(**inputs)
        return ProgramRunResult(
            output={
                "rewritten_text": pred.rewritten_text,
                "rationale": pred.rationale,
                "risk": pred.risk,
                "assessment": pred.assessment,
            },
            provider="dspy",
            model=model_name,
            used_real_lm=True,
            eligible_as_model_evidence=True,
            fallback_state=None,
            error=None,
        )
    except Exception as exc:
        return ProgramRunResult(
                        output={
                "rewritten_text": inputs["sentence"],
                "rationale": "Fallback preserved the original sentence.",
                "risk": None,
                "assessment": None,
            },
            provider="deterministic_fallback",
            model=model_name,
            used_real_lm=False,
            eligible_as_model_evidence=False,
            fallback_state="lm_unavailable",
            error=str(exc),
        )

我们通过注入一次依赖失败来测试它。包装器抛出 RuntimeError: injected LM dependency failure,返回保留原句的降级输出, 并记录 used_real_lm = false、eligible_as_model_evidence = false、 fallback_state = "lm_unavailable"。

重要的不变量:输出存在,而且没有做出“模型产出了它”的主张。

真实的 LM 响应
        ↓
有资格作为模型证据

确定性回退
        ↓
有用的降级行为
        ↓
不是 LM 完成了该任务的证据

可用性与证据是两种不同的关切;一个把两者混为一谈的系统,终将把一次故障报告成 一次质量回归。


5. 可复现性需要模型身份

如果一次运行重要,就存下足以日后解释它的东西:

程序 id 与版本
签名版本
模块策略
LM provider、模型名与模型版本
temperature、max tokens、超时与重试策略
输入指纹
输出指纹
回退状态
import hashlib
import json
from datetime import datetime, timezone

def fingerprint(payload: dict) -> str:
    blob = json.dumps(payload, sort_keys=True, default=str)
    return hashlib.sha256(blob.encode("utf-8")).hexdigest()

def make_run_record(inputs: dict, output: ProgramRunResult) -> dict:
    return {
        "created_at": datetime.now(timezone.utc).isoformat(),
        "program": "editorial_rewrite_program",
        "program_version": "0.1",
        "lm_provider": output.provider,
        "lm_model": output.model,
                "used_real_lm": output.used_real_lm,
        "eligible_as_model_evidence": output.eligible_as_model_evidence,
        "fallback_state": output.fallback_state,
        "input_fingerprint": fingerprint(inputs),
        "output_fingerprint": fingerprint(output.output),
        "error": output.error,
    }

我们在规范依赖下跑了一次 ed-001 执行。组合程序在 5.78 秒内完成,并返回:

Jalen opened the door, peered into the room, and felt a wave of fear wash over him.

然后我们一次变异一个配置字段,没有再做任何一次模型调用:

变异 配置指纹是否改变?
model 是
endpoint 是
temperature 是
native thinking 是
max tokens 是

每一个单字段变更都产出不同的指纹。作为哈希结果,这不足为奇;作为纪律,这才是 要点:指纹是让你能够说两次运行是同一个实验的东西,而“我们两次都用了 Qwen3”做 不到。

关于那次改写,有一件事值得注意,因为这个实验常被假定为确立了三个主张,而它把 这三者分开了。依赖工作了:调用对着配置的 provider 完成了。运行记录捕捉了是什么 在执行、返回了什么。

这次改写好不好是另一个主张。peered into the room 不是一个新事件——原文已经说 Jalen 看进了房间——但 felt a wave of fear wash over him 比克制的原文更长、也更多 修饰。这次实验没有运行判断这种取舍是否可接受所需的编辑接受协议。

所以依赖实验确立的是执行和来源,不是质量。这个区分就是整章的缩影。一个健康的 依赖和一份完整的运行记录,完全可能伴随一个后来被评估拒绝的输出。


6. 一个程序,几种模型角色

一个 DSPy 程序并不意味着一个全局的模型依赖。不同的职责可以——而且常常应该—— 使用不同的模型:

角色 职责 应该与任务模型不同吗?
任务模型 产出结果 —
教师 为自举生成轨迹 常常
提示词模型 提出候选指令 常常
反思 LM 对反馈做反思并提出变异 常常
评审器 评估一个候选 理想情况下,是
路由器 选择更便宜或更强的路径 是

STORM 是这方面一个干净的参照:它模块化的 文章生成工作流把不同的 LM 和检索模块分配给不同的职责。 CodeSpy 展示的是运行时版本——作用域搜索、PR 摘要、专家审查与审计,各自带着自己的依赖特征和成本。

来源规则由此直接得出。如果评审器模型变了,分数就变了,尽管候选没变。如果教师变 了,被选中的示范可能变了,尽管学生没变。如果提示词模型变了,搜索路径就变了。把 角色、provider、模型、适配器与配置一起记录下来,否则你将无法说出它们中究竟哪一 个动了。

关于本书的一次坦白

提供指标 v2 语义部分的评审器跑在 qwen3:latest 上——与它所评估的任务程序同一个 模型、同一个端点。第 13 章 GEPA 运行里的反思 LM 也是如此。

这正是上表所警告的角色坍缩,也是本书证据的一个真实局限。由同一个模型家族构建 的评审器,可能与任务程序有相关的盲区。不同的提示词和不同的角色仍然能抓住错 误——第 9 章演示了这一点——但共享的权重在强意义上并不是独立证据。

有两件事部分地为这个设计辩护。第一,第 9 章用一套对抗性套件验证评审器,而不是 假定一个带类型的裁决就是正确的:它抓住了全部三个典型的语义反转,并在 44 个干净 的参考改写上产出零个假阳性。第二,使用一个本地依赖让整个实验可以重跑,无需 API 成本或 provider 访问。

这两者都没有把评审器变成一个独立的权威。一个由明显不同的模型构建、并被单独验 证的评审器会提供更强的证据。在当前评审器的裁决最要紧的地方——第 4 章的 ed-025,以及第 11、12 章的 ed-035——我们因此把这些句子和那个具名约束打印出 来,让读者可以直接检视有争议的语义改动。


7. 本地与托管都是工程选择

两者都不比对方更严肃。它们暴露的是不同的约束。

选择 优点 代价
本地(Ollama) 可控、隐私、离线工作、无按次调用成本、重复便宜 机器设置与服务状态成为实验的一部分;量化与运行时细节必须记录
托管 API 用上更强的模型、托管的基础设施、广泛的 provider 支持 成本、速率限制、外部依赖,以及你可能无法控制的 provider 侧版本或服务变更
OpenAI 兼容网关 路由灵活性、集中的策略与日志 多一层要观察的地方,也多一个会失效的地方

本书做出的选择是本地,而第 2 节就是账单的一部分。一个更强的托管模型可能产 出更好的改写或更少的硬门失败,但那是一个经验问题,而不是我们仅凭模型类别就能 假定的性质。

托管执行还会把真实的 API 成本挂到第 4 章的 222 次调用以及本书后面规模大得多的优 化器运行上,而且有些 provider 可以在你的实验之外改变服务行为或模型别名。因此本 地与托管系统有不同的可复现性包络;两者都不会免除记录实际所用依赖的必要。

DSPy 有帮助,因为程序往往能挺过一次依赖的更换。“往往”这个词在这句话里承担了分 量。你仍然必须在目标模型下运行同一个程序,看看什么会坏掉。


通常会出什么错

症状 可能原因 如何诊断 改什么
每个输出都是空的 provider 调用失败,或模型标识符写错 直接在 DSPy 之外对 provider 做健康检查 修好模型字符串或 base URL
输出忽略了声明的字段 模型或适配器搞不定结构化输出 记录原始响应和任何解析警告 简化输出契约或换模型
直接预测能行,组合程序不行 上下文或 token 预算超了 逐阶段比较原始输出与 token 计数 缩短上下文、调高 max_tokens,或减少阶段数
温度 0 下结果在运行之间变化 跨会话非确定性,不是 bug 在全新进程中重复并测量离散度 在引用任何差值之前先确立噪声底
一夜之间冒出一次质量回归 一次故障正被当作模型输出打分 统计 used_real_lm 为 false 的记录 把回退排除在质量主张之外
两次“相同”的运行对不上 某个没人记录的字段上配置不同 比较配置指纹,而不是模型名 给整个依赖做指纹
评审器的分数动了而程序没动 评估依赖变了 检查评审器记录的模型与配置 像给程序做版本一样给评审器做版本

本章小结

模型现在是一个依赖,而不是一个假设。它有一个你可以哈希的身份、一个你可以与坏 结果区分开的失效模式,以及一个必须与程序一起被记录的角色。

测量从三个方面支持了这一点。每一个单字段配置变更都产出不同的指纹,正是这一点 让“同一个实验”成为可核查的主张。一次注入的依赖失败产出可用的降级输出,并被显 式标记为不合格的模型证据。而在第一次基线审计中,温度为零时对未改动程序状态的 重复执行产出了不同的输出,观测到的开发均值跨度约 0.010。

后面那对配对工作让这个教训更强,而不是更干净。变异既可以出现在全新会话之间, 也可以出现在一个会话内部的不同交错之下。因此温度为零移除的是一个有意的采样 随机性来源;它并不会让整个推理栈变成确定性的。

我们不把这些观察变成一个普适的标量噪声底。从这里开始,小的改进被当作假设来对 待:它们需要配对重复、逐案例检查,以及(在可用时)一个零效应的阴性对照。这个标 准比任何单一阈值都更重要。

我们移除了两个假设:DSPy 程序能被它的签名和模块完整描述;以及一个被返回的值就 证明了模型产出了它。

剩下的是改进。我们可以指定一个程序、执行它,并准确记录是什么执行了它。我们仍然 没有有原则的方式从示例中教它,也根本没有办法说一个版本是不是比另一个更好——因 为我们没有可信的案例,也没有值得优化的判据。

这两件事都是数据问题。

示例是数据,不是装饰。