用 Python 标准库给提示词链加校验和预算
作者把规划、起草、审阅拆成三个阶段,逐步校验交给下一阶段的数据,处理类型漂移和 JSON 夹杂说明文字的问题。请求发出前检查预算,并为校验失败和供应商限流设置不同的恢复路径。
AI 深度解读
把一次 AI 任务拆成「列提纲、写初稿、做审阅」,很容易在演示里跑通。可一旦交给定时任务,模型把数字写成字符串、在 JSON 前后加上寒暄,或者服务商返回 429,后面两步就可能跟着出错。作者给每一步加了输出契约,把请求失败和输出不合格分开处理,并在发请求前检查输入大小和服务商档位。
这套实现只用 Python 标准库。对做前端和全栈的人,最容易复用的是三处边界:上游的结果什么时候能交给下游,一次失败可以再花多少请求,以及怎样用固定响应把这些行为测清楚。
模型回了 JSON,为什么还不能交给下一步
提示词负责告诉模型该交什么,运行时校验负责决定这份结果能不能用。作者用 dataclasses 定义 Field,给每个字段声明类型、长度、取值范围或枚举,再由 Step.validate() 检查解析结果。比如,审阅的 score 必须是 0 到 100 的整数,verdict 只能是 ship 或 revise。Python 里 bool 是 int 的子类,所以代码单独拒绝 True。同样,字符串 "3" 也过不了整数检查。对下游来说,类型不符会在交接处报错,报错里还带着字段名和违反的规则。
作者同时用 shape() 把字段名和类型展示给模型,通过 json.dumps(..., separators=(",", ":")) 紧凑地塞进提示词。输出仍可能带有代码围栏或前后说明。这段解析代码负责从回复里取出 JSON 对象,并把解析失败归到同一套修复流程里。
FENCE = "`" * 3
def _load_json(raw: str) -> Any:
"""Models love wrapping JSON in prose or fences. Strip that before parsing."""
t = raw.strip()
if t.startswith(FENCE):
t = t.split("\n", 1)[-1]
t = t.rsplit(FENCE, 1)[0]
start, end = t.find("{"), t.rfind("}")
if start == -1 or end <= start:
raise ValidationError("no JSON object found in the reply")
try:
return json.loads(t[start:end + 1])
except json.JSONDecodeError as e:
raise ValidationError(f"invalid JSON: {e.msg} at char {e.pos}") from e
看 start, end = t.find("{"), t.rfind("}") 这一行。它假设回复里只有一个要提取的对象。如果说明文字也带花括号,或者模型给了两个 JSON 对象,截取范围就可能过大,最后交给 ValidationError 处理。
哪些失败该换服务商,哪些该让模型重答
碰到 429、超时或 5xx,作者保留原提示,在同一家服务商上最多尝试两次,失败后再按配置顺序尝试下一家。backoff 控制两次尝试之间的等待,默认是 0.0。Provider.tier 把服务商分成 0 免费或本地、1 免费额度、2 付费。默认 max_tier=0 时,只有第 0 档能被调用。原文的 429 演示验证了顺序回退,另一项检查得到付费服务商调用次数为 0。如果备用服务商配置为第 1 档,就要把上限设到至少 1 才能走到它。
HTTP 成功但结果违反契约时,程序留在同一步,用原提示加上具体错误重新请求。比如 promise 应该是字符串,实际却收到了整数,修复提示就指出这个字段和类型。作者估算,这段错误说明额外增加约 40 tokens,省下的是把整份错误输出附回去的开销。默认 max_repairs=1,也就是一轮初始生成和最多一轮修复。成功返回的状态里,_trace 会记录失败的字段提示、响应来自哪家服务商,以及该步骤的修复次数。
审阅只看首尾,省下的是什么
每一步用 needs 声明自己能看到的上游字段。下面的配置把提纲、草稿和审阅各自要产出的内容写成契约,同时限制送进审阅的正文长度。
OUTLINE = Step(
name="outline",
system="You are a technical editor. Plan short, concrete developer posts.",
needs=("topic", "audience"),
fields=(
Field("promise", str, min_len=20, max_len=160),
Field("sections", list, max_len=6, of=(
Field("heading", str, min_len=3, max_len=80),
Field("intent", str, min_len=10, max_len=200),
)),
),
)
DRAFT = Step(
name="draft",
system="You are a senior engineer writing runnable, copy-pasteable code.",
needs=("promise", "sections"),
fields=(
Field("title", str, min_len=15, max_len=100),
Field("body_markdown", str, min_len=400),
),
)
REVIEW = Step(
name="review",
system="You are a strict reviewer. Reject what you cannot verify.",
needs=("promise", "draft"),
clip={"draft.body_markdown": 1800}, # head + tail, not the whole body
fields=(
Field("score", int, minimum=0, maximum=100),
Field("verdict", str, choices=("ship", "revise")),
Field("issues", list, max_len=5, item=Field("issue", str, min_len=5, max_len=200)),
),
)
看 clip={"draft.body_markdown": 1800} 这一行。按作者的描述,审阅保留正文开头和结尾各 900 字符,中间用 [... N chars omitted ...] 标明省略。这个窗口适合检查开头许下的承诺有没有在结尾回应。中间的代码、论证和事实都可能落在窗口之外。
作者用一份 9,000 字符的桩件草稿做了对照。审阅提示从 9,277 字符降到 2,089,减少约 78%,按文中的粗略算法约从 2,300 tokens 降到 520。整条三步链包含草稿回复,估算约 2,900 tokens。另一个桩件把上限设为 200,输入估算约 2,026 tokens,请求在本地就被拦下。默认的 max_prompt_tokens 是 1500,因此这个样本的完整审阅提示也会超过默认上限。
我的判断
我最认同的是先把交接规则写清楚,再拿固定响应测故障路径。用 stub 就能验证错误类型会被拒绝、遇到 429 会回退、付费档不会被调用。这些结果说明程序按预期走了分支。一次修复对真实模型的成功率、哪种回退顺序更合适、首尾裁剪会漏掉多少审阅问题,原文都没给对照数据。尤其是裁剪实验,桩件正文由 9,000 个 x 组成,能验证输入变短了,审阅质量还要用真实稿件测。
成本控制也要按贴出的实现来理解。_guard() 只检查每一步的初次提示,修复提示生成后没有再检查。spent_tokens 是粗略的事后累加,没计入 system 和异常请求,也没有整链上限。按字符数除以 4 对英文和 JSON 可以做粗估,中文提示仍需要用实际模型的用量核对。另一个差距是代码捕获了所有 Exception,实际接入时,鉴权错误或调用代码自身的异常也可能被当成网络故障重试。
如果项目已有 Zod 一类的运行时校验工具,直接沿用现有 schema 会更省维护成本。服务商提供结构化输出时,也可以让接口先约束返回形状,并保留应用侧的长度、枚举和业务规则校验。原文虽称代码可直接运行,但贴出的片段缺少 Step.prompt() 和 Callable 的导入,上一步的 promise、sections 如何映射给下游也没展示。复用时,这几处会直接影响链条能否接起来。
能拿来做什么
- 给 Node 或 AI 编程脚本的每一步声明输入和输出。先校验提纲数组、审阅结论和分数,再写入共享状态,并让错误指向
sections[0].heading这样的具体字段。 - 用固定响应测试正常生成、类型错误后修复、主服务商 429 和预算超限。除了检查返回值,也断言调用次数、模型看到的字段,以及付费服务商是否被调用。
- 如果用这条链写技术文章,可以拿首尾窗口检查标题和正文是否兑现同一个承诺。代码可运行性和正文事实核查需要把对应片段送进审阅,或直接交给测试命令验证。
- 把链放进任务队列时,为每个
(run, step)设置幂等键,并在初次请求和修复请求前都检查剩余预算。按步骤和提示词哈希保存失败回复,后续就能重放同一个样本。