用校验与有限重试守住模型输出入口
文章用 Zod 校验、可修复格式处理、携带错误反馈的有限重试和死信队列,构建模型输出入库前的防线。它还区分结构合规与内容正确,并比较不同供应商对模式约束的支持。
AI 深度解读
「Return JSON only」挡不住第 51 次异常输出。作者曾把工单分类结果直接写进数据库,直到模型返回带 Markdown 围栏的 JSON 和虚构分类,让客服花了一个下午收拾数据。
这篇文章的结论是:模型输出进入业务系统前,需要一份可执行的契约,以及校验、确定性修复、带错误重试、失败转人工的闭环。它对 Node 和全栈开发有用,但示例距离可直接上线还有缺口,文中的版本信息和实验结论也需要分开看。
JSON 合法,为什么工单仍然会分错
作者把失败分成三层:语法错误、契约错误、语义错误。
语法错误是 JSON 根本解析不了,例如多余逗号、括号没闭合、外面包着说明文字。契约错误是能解析,但字段名、类型或枚举不符合要求,例如把 invoice_number 写成 invoiceNo。供应商的严格结构化输出模式主要处理这两层,单靠提示词没有同等保证。
语义错误更麻烦。金额是数字,但算错了;SKU 是字符串,但商品根本不存在;分类属于允许的枚举,却选错了。
结构化输出能约束数据长什么样,不能保证它说得对。
原文引用一项 2026 年 10 月的工具调用基准:19 个模型、1,000 个单轮任务,最佳干净调用率约为 86%,其余约 14% 涉及错误调用、遗漏、多余调用或编造结果,并非 JSON 格式损坏。这支持「格式正确不等于任务正确」,但不能直接推成所有业务都有 15% 到 20% 的错误率。
另一项研究据称进行了 3,997 次生成,覆盖九种 OpenAI、Anthropic 模型配置。681 次带围栏的失败里,去掉围栏后只有 48.0% 能通过验证,其余仍有字段长度等问题。所以,剥掉围栏只是拿到了下一轮检查的材料。
截断还得单独处理。原文引用的工具结果裁剪研究中,11,189 条结果有 3,827 条被框架裁成非法 JSON;其中提到 langchain-core 保留前 500 个字符,smolagents 在超过 20,000 后删除中间部分。这里既可能是模型输出额度不足,也可能是下游裁剪。前者需要提高额度,后者需要调整裁剪策略,不能都归为「再问模型一次」。
为什么要让 Zod 同时管类型和运行时校验
作者使用的工单契约如下,它把摘要长度、分类、优先级和置信度范围明确写进代码:
import { z } from "zod";
const triage = z.object({
summary: z.string().min(10).max(200),
category: z.enum(["billing", "bug", "feature", "account"]),
priority: z.enum(["low", "medium", "high", "urgent"]),
confidence: z.number().min(0).max(1),
needsHuman: z.boolean(),
tags: z.array(z.string()).max(5),
});
要留意 z.object:它默认剥掉未知字段,并不会因为模型多返回一个字段就报错。需要拒绝额外字段,用 z.strictObject;需要保留,用 z.looseObject。这是业务选择。
Zod 4 的价值在于,同一份 schema 可以提供 TypeScript 类型、运行时验证,以及通过 z.toJSONSchema(schema) 生成给供应商的 JSON Schema。作者生成的结果是 draft 2020-12,并带有 additionalProperties: false。但发送端的 JSON Schema 和本地解析行为仍需分别理解,不能只看 Zod 代码就假定两端完全一致。
字段修复也不能随意开启。.catch(value) 可以替换校验失败的值,.default(value) 补缺省值,.prefault(value) 会让默认输入继续经过 schema 解析。z.coerce.number() 能把 "0.92" 转成 0.92,也可能接受业务不想接受的输入。每一次兜底都在改变数据,应该留下记录。
作者强调,.safeParse() 仍是整体成功或失败;.partial() 只是让顶层字段可选,Zod 4 已移除 .deepPartial(),没有一个自动猜出残缺对象的「部分解析」接口。
版本信息则有明显的核对需求:作者实际测试使用 Zod 4.4.3,却推荐 zod@^4.6.7,并称 Zod 4.0 发布于 2025 年 7 月、4.6.7 发布于 2026 年 10 月 12 日。这些是原文口径,不能当作本次已核验的版本事实。它还要求 TypeScript 5.5 或以上、tsconfig 开启 strict: true。
修复闭环的关键,是先判断失败能不能修
作者推荐的新调用形式是 generateText 配合 Output.object,原文称 generateObject 已在 AI SDK 6 弃用,新示例采用 AI SDK 7:
import { generateText, Output, NoObjectGeneratedError } from "ai";
import { z } from "zod";
const { output } = await generateText({
model,
output: Output.object({ schema: triage }),
prompt: "Triage this ticket. Return JSON only.",
});
关键在 Output.object({ schema: triage })。提示词仍在,但契约不再只靠提示词表达。Output.json 仅检查 JSON 合法性,不能替代它;Output.array 支持元素 schema、minItems 和 maxItems,配合 streamText 的 elementStream 返回完整且已验证的元素。与工具调用组合时,还需要考虑 stopWhen 的步数。
失败后,NoObjectGeneratedError 提供原始文本、原因、响应元数据和 token 用量。maxRetries 处理的是请求层面的重试,验证失败需要业务代码自行组织修复。
闭环分四步:先验证;失败后去掉围栏和外围文字,再解析、再验证;仍失败就把字段路径和具体错误交给模型;总尝试次数达到 MAX_ATTEMPTS = 3 后进入死信队列(dead-letter queue),等待人工检查与重放。
拒绝和截断要先分流。拒绝不该盲目重试;finish_reason: "length"、stop_reason: "max_tokens" 或 incomplete 状态提示内容可能未生成完,应检查 max_output_tokens 等预算。三次指包含首次请求在内的三次尝试,最坏情况下,该记录的模型调用成本约为一次的三倍。
供应商端同样有差异。原文称 Anthropic 的 SDK 辅助函数会将不支持的约束转入字段描述并在客户端验证;OpenAI 的属性数、嵌套层数、枚举数限制分别为 5,000、10、1,000,而非旧文章里的 100、5、500。Google 则涉及 responseSchema、responseFormat 和 Interactions API 的迁移。原文还声称 gemini-2.5-* 中的 2.5 Pro、2.5 Flash 将从 2026 年 12 月 1 日自动路由到 3.8 Flash、3.5 Flash-Lite,但没有展开具体对应关系。接入时应重新核对,不能把这些时效性描述写死。
我的判断
我认可把验证放在数据入口。作者测得 20,000 次 safeParse 总耗时 25.1 毫秒,约每次 1.3 微秒。虽然缺少硬件和完整基准条件,这至少说明在这个小 schema 上,校验开销远小于一次模型请求。
但实验覆盖比标题给人的印象窄。作者只列出八种构造输出:两种原样通过,修复后通过数为三种,其余五种需要模型重试。闭环执行验证使用的也是桩输出,覆盖围栏修复、第二次纠正枚举、三次失败入队,并没有给出真实供应商端到端成功率或三次优于两次的对照。三次上限是经验之谈。
代码也有需要补齐的地方:修复分支直接执行 JSON.parse(salvaged),解析异常可能提前中断循环;截取首个 { 到最后一个 } 也不是真正可靠的对象提取。截断分支只是抛错提示提高预算,没有自动调整;死信函数只调用 console.error,缺少正文承诺的 schema 版本和模型 ID。错误反馈条数、修复日志也没有完整落实。
此外,zod@^4.6.7 是版本范围,称它为固定版本并不严谨,需要结合锁文件管理。
这套方案适合当工程骨架,不能直接当生产保障。
它与供应商 strict mode 应该配合使用,再补数据库存在性、金额核算、权限等业务检查。若每条结果都有人复核,可以先保留 schema;只读原型也未必需要立刻搭完整队列。
能拿来做什么
- 在 Node 的工单分类或文档抽取接口中,把 schema 校验放到写库之前,并明确多余字段应当剥除、保留还是拒绝。
- 用真实失败样本验证修复路径,至少覆盖围栏、错误枚举、数字字符串、拒绝和截断,并确认修复后仍会执行完整校验。
- 将验证重试与请求重试分别计数,记录失败类型、尝试次数和费用,避免
maxRetries与业务重试叠加后超出预期。 - 为最终失败建立可重放的人工处理入口,保存原始输出、schema 版本和模型 ID,再对分类正确性等业务问题增加独立检查。