18 篇博文 含有标签「structured-outputs」

JSON Schema 验证的是输出的形状（shape）。它并不验证该形状内数值的含义。在长达 9 个月的时间里，你的 AI 流水线产生的每一条输出都顺利通过了校验，监控显示 Schema 合规率为 100%，你的团队也理所当然地认为符合 Schema 的响应在契约层面就是正确的。接着，一次模型升级发布了，每一条输出依然能通过校验，但你的 Slack 告警频道却在一夜之间从每天 50 条消息飙升到了 800 条。

Schema 没有出问题，出问题的是其内部数值的分布。这就是大多数 AI 团队在生产环境中发现的鸿沟：JSON 契约是一个类型系统（type system），而非行为系统（behavior system），而下游消费者一直依赖于某种契约从未被要求强制执行的数值分布。

打开你的结构化输出仪表盘。它自豪地显示着类似 “98.4% 的 Schema 合规率” 这样的数字。这就是成功率——即第一次尝试就生成有效 JSON 对象的请求比例。团队为剩下的 1.6% 构建了一个重试封装器（retry wrapper），发布上线，然后就没再管了。两个季度后，推理费用增长了 15%，而请求量仅增长了 4%。首席财务官（CFO）想要个解释。工程师们给不出解释，因为跟踪结构化输出成功率的仪表盘并不跟踪结构化输出的成本。

仪表盘隐藏的部分在于：失败路径并非只有一次重试。第一次重新提示（re-prompt）修复了缺失的 enum 字段，但引入了一个格式错误的嵌套数组。第二次重新提示修复了数组，但丢掉了一个必填键。第三次尝试终于通过了验证，但到那时，该请求已经消耗了四次完整的推理调用加上最初的生成过程，而你的单次请求 Token 计数器显示的是 总和，而不是循环过程。从计数器的角度来看，这是一个昂贵的请求。从成本线的角度来看，这是一个你从未定价的随机循环。

这篇文章将探讨该循环究竟对你的算力预算产生了什么影响，为什么你现有的观测能力（observability）无法察觉到它，以及哪些规范可以使其变得可见且可控。

你的代码库中有两种语言，但只有一种拥有编译器。一种是你的团队编写的严格类型的代码 —— 开启了 strict: true 的 TypeScript、CI 中运行 mypy 的 Python、强制返回值的 Go —— 另一种则是 Prompt：一个模板化的字符串，经过拼接后发送给远程模型，并返回另一个运行时希望能成功解析的字符串。在这两个区域之间，类型系统就成了瞎子。IDE 不会高亮任何内容。编译器不会发出任何报警。而那些凭借“但它通过了类型检查”就发布功能的团队，实际上将核心契约放在了契约检查器看不见的地方。

这个接缝伪装得很好。从外部看，它就像一个函数调用：generate(input: UserQuery): Promise<AgentResponse>。函数签名诚实地反映了输入和输出。而虚假的部分发生在调用点和响应之间：输入被插值到通过字符串引用字段名的 Prompt 模板中；模型被要求生成一个符合该 Prompt 内部以自然语言描述的 Schema 的 JSON 对象；响应作为一个字符串返回并交给解析器；最后解析器返回类型系统终于能再次看到的内容。两端的每一个类型化表达式都在对中间一个完全没有静态保证的区域做出断言。

这并非理论上的担忧。各团队报告称，在生产环境中，朴素的结构化输出基准 Schema 失败率为 10–20%，而且失败往往集中在那些你最无法承受无声丢弃的输入上 —— 长上下文、深层工具链、边缘情况用户。类型系统提供了一种虚假的正确感，直到格式错误的 JSON 返回且运行时将其吞下为止。

我第一次看到备用路由引发的事故比它试图缓解的停机故障还要严重时，复盘文档的标题是这样写的：“主服务降级 11 分钟。备用服务导致我们的解析器降级了 6 天。” 没人写错代码。没人跳过 Schema 评审。18 个月前连接备用服务时的二级供应商集成测试还是通过的。其间发生的事情是，两个供应商之一悄悄收紧了其枚举强制转换（enum coercion）策略，而我们下游解析器所遵循的契约——我们认为“或多或少就是 JSON Schema”的契约——已经从共享标准漂移成了两个略微不兼容的方言。

这是我不断看到的失败模式，而且它总能让那些本该更明白的团队感到惊讶。“JSON 模式”听起来像是一个你开启的功能。其实不然。它是一个你需要维护的契约——针对你可能路由到的每一个供应商分别维护——而且随着供应商演进其结构化输出技术栈，这个契约每季度都会发生漂移。你签署合同时供应商文档中所暗示的“无缝替换”，在生产环境中其实是一个需要维护的转换层。如果没有这个层，你的备用路径就会变成一个纸面上的合规产物：存在于架构图中，但在你真正需要它的那天却是坏的。

大多数团队在上线当天开启 JSON 模式，却从未衡量这背后的代价。这种假设合情合理：结构化输出能保证正确性，为什么不选它呢？答案是，严格的 JSON 模式约束解码通常会使数学、符号和多步分析任务的推理准确度降低 5–15%，而由于评估是在开启格式标志之前运行的，或者评估衡量的是可解析性而非质量，因此没人注意到这一点。

输出格式是一种解码时的约束，正如所有约束一样，它会扭曲模型的概率分布。当你查看日志时，这种扭曲是不可见的：JSON 有效，Schema 匹配，字段类型也对得上。你在日志中看不到的是模型本可以用散文形式产出的推理过程，但由于无法塞进你给定的语法中而消失了。“格式税”是真实存在的，在文献中已有详尽记录，但在生产环境中几乎普遍未被衡量。

这篇文章将探讨何时该支付这笔费用，如何在不必支付时及时止损，以及对于既想要结构化输出又想要准确性的工程师来说，格式选择的决策树究竟是什么样的。

一个医疗排班系统从其 LLM 提取层收到了一个合法的 JSON 对象。Schema 验证通过，类型检查通过，必填字段齐全。然而，当下游任务尝试预约时，却发现 end_time 比 start_time 早了三个小时。两个字段都是格式正确的 ISO 时间戳，没有任何一个违反 schema。预约悄悄失败，患者没有收到任何通知——没有错误，没有告警。

这就是当 schema 验证被误以为是正确性验证时的样子。模型遵循了格式，却没有遵循逻辑。

大多数团队采用结构化输出，是因为厌倦了用脆弱的正则表达式从模型响应中抽取数据。这个动机合情合理。但他们没料到的是，几个月后当他们真正度量任务准确率时，会发现那次"可靠性提升"同时让推理密集型任务的内容质量下降了 10 到 15 个百分点。语法问题解决了，语义问题却悄然而生。

本文的目的是精确理解这一权衡——约束解码的实际代价是什么、什么时候值得支付这笔税，以及如何在上线前构建评测来判断它是否正在拖累你的系统。

你开启了 JSON 模式，你的 LLM 开始返回有效的 JSON，然后你发布了它。三周后，生产环境悄无声息地挂了。JSON 在语法上是有效的。Schema 在技术上也是满足的。但某个字段包含了一个虚构的实体，finish_reason 为 "length" 导致数据负载在 95% 处被静默截断，或者模型对任何人类读起来都感到刺耳的文本分类为 "positive" 情感——而你的下游流水线毫无怨言地吞下了它。

JSON 模式被解决的方式，就像“使用互斥锁（mutex）”解决并发问题一样。原语（primitive）是存在的。但故障模式并不在于你把锁放在哪里。

大多数团队发现 Schema 问题的方式都是错误的：下游服务开始返回乱码，仪表盘充斥着垃圾数据，经过 20 分钟的调试才发现，LLM 在三周前就开始悄悄地将其 JSON 包装在 Markdown 代码块中。没人注意到，因为应用程序没有崩溃 —— 它只是在静默地消耗格式错误的数据。

修复方法只是修改了一行提示词。但造成的损失是数周的错误分析和一次非常尴尬的复盘。

Schema-first 开发是防止这种情况发生的准则。这意味着在你编写任何提示词 Token 之前，先定义 LLM 输出必须遵循的确切结构。这并不是为了限制创造力；而是将输出格式视为下游系统可以依赖的契约，就像你在编写消费者端代码之前会先对 REST API 进行版本化一样。

你上线了一个功能，使用 LLM 从用户文本中提取结构化数据。你进行了彻底的测试。它工作正常。三个月后，模型提供商悄悄更新了权重，在没有修改任何代码的情况下，你的下游流水线开始静默丢弃记录。没有抛出异常。没有触发报警。只是错误的数据在系统中流动。

这就是 Schema 问题。尽管结构化输出 API 已经改进了多年，它仍然是 LLM 驱动的系统中最少被讨论的故障模式之一。

大多数需要结构化LLM输出的团队都遵循同一套方案：写一个提示词说"只返回有效的JSON"，解析响应，运行Pydantic验证，失败则附上错误信息重试。这种方式在大多数情况下能用，但在生产环境中恰恰会在最糟糕的时刻失效——高负载、边缘用例输入，以及指令遵循不如GPT-4可靠的低成本模型。

语法约束生成是一种根本不同的方法。它不是礼貌地请求模型然后事后检查，而是从数学上让结构无效的输出成为不可能。模型无法输出缺失的括号、不存在的枚举值或遗漏的必填字段——因为这些token在采样前就被过滤掉了。不是不太可能，而是不可能。

大多数团队跳过了这个方法，但不应该。

到 2025 年，每家主流 LLM 服务商都已推出结构化输出的受约束解码功能。OpenAI、Anthropic、Gemini、Mistral——它们都允许你向模型传入一个 JSON Schema，并保证返回结果在结构上完整无误。各个团队纷纷采用这一功能，长舒一口气：解析错误消失了，重试循环缩短了，监控面板一片绿色。

然后，微妙的故障开始出现。

一个情感分类器在两周内对每个输入——包括乱码——都锁定在 0.99 的置信度，无人察觉。一个信贷风险智能体返回了合法的 JSON，批准了一笔本应被拒绝的贷款申请，风险分数高出了五十分。一条金融数据管道将 "$500,000"（字符串，技术上符合 Schema）强制转换为整数字段中的零，破坏了六周的风险计算数据。这些故障全部通过了 Schema 验证。

教训是：结构有效性是必要条件，但并不充分。你需要一个语义验证层，而大多数团队并没有这一层。