9 篇博文 含有标签「structured-output」

当你的备用路由（fallback route）第一次在生产环境中触发时，绝不是发现两个供应商对你的 schema 定义存在分歧的好时机。在两个客户端配置中，JSON Schema 看起来完全一样。验证器对两个输出都通过了。下游代码按名称读取字段并获取一个值。接着，账单总额以数字字符串而非整数的形式出现，或者长度为一的列表以纯对象而非单元素数组的形式到达，一段已经正常运行了六个月的代码路径会静默地返回错误答案。

结构化输出引人入胜之处在于它消除了一类错误——无法解析的 JSON、幻觉字段、缺失的键——因此让人感觉它彻底解决了解析问题。实际上它所做的是将解析问题向上移动了一层，从词法分析器（lexer）移到了类型系统，在那里问题变得更难被察觉。两个供应商可以都遵循 JSON Schema，但仍然产生不可互换的输出，因为在这个生态系统的角落里，“遵循”至少有四种不同的含义，而你的 schema 并没有指明你想要哪一种。

你的团队启用模式约束解码（schema-constrained decoding）的那一天感觉像是一个里程碑。解析错误停止了。JSONDecodeError 警报消失了。从文本中抓取字段的脆弱正则表达式也被删除了。有人在站会上说“模型现在返回有效的 JSON 了”，结构化输出的任务单随之关闭。

那句话正是麻烦的开始。“模型现在返回有效的 JSON 了”是正确性工作的开始，而不是结束。JSON 模式和约束解码保证了响应的形状（shape）——即 quantity 是一个整数，status 是三个枚举值之一，对象包含你要求的键。它们完全无法保证 quantity 是否是正确的数字，status 是否反映了真实发生的情况，或者 sku 字段是否指向了目录中存在的商品。

团队第一次构建带有结构化输出的流式 AI 功能时，遇到的 bug 总是如出一辙。模型生成正常，数据块（chunks）接收正常。但在第 47 个 token 左右，解析器挂掉了，UI 冻结了，或者更糟——一个半成型的枚举（enum）值被路由到了下游工具，导致其悄无声息地执行了错误操作。团队在 JSON.parse 周围加了一个 try/catch，觉得自己搞定了，然后发布。两周后，兄弟团队抱怨响应变长后流式 UI 感觉很卡。一个季度后，事故审查询问为什么在一个模型仍在描述为 "DeleteIfEmpty" 的记录上触发了 "Delete" 工具调用。

Bug 不在任何单个 token 中。Bug 在于 token 流式传输和结构化输出在架构上是冲突的，而大多数框架只是用“祈祷”来掩盖这种冲突。Schema 说“这是一个完整的对象”。Token 流说“这是一次一个字节的数据”。从定义上讲，这两个端点之间的每一个中间状态对于 Schema 来说都是无效的。团队的工作是决定在这些中间状态期间该做什么——而大多数团队并没有明确做出这个决定。

模型正在逐个 Token 地输出 JSON。你的 UI 希望在字段出现的那一刻就进行渲染 —— 在冗长的回答正文之前显示置信度得分，或者在模型填充工具调用参数时实时显示它们。接着，有人尝试在每个数据块（chunk）上调用 JSON.parse，结果整个系统就崩溃了，因为 JSON.parse 是“全或无”的。它需要一个结构完整的文档才能返回任何结果。在模型输出闭合括号之前，你什么也显示不出来。

这不是一个可以通过 try/catch 解决的解析器问题。标准 JSON 解析器是针对内容长度已知的 HTTP 响应设计的。部分输入并不是它所建模的状态 —— 而是被视为“输入错误”。当你将 Token 流视为 HTTP 正文处理时，你继承了三十年来“文档要么完整，要么无效”的传统，而你的 UI 则为此付出了代价。

一个团队发布了一个文档提取流水线。它使用了 JSON 模式。QA 通过了。监控显示解析错误接近于零。六周后，一个隐蔽的失败浮出水面：语料库中的每一份风险评估都被标记为 “低” —— JSON 格式有效，字段名称正确，但答案是错的。该流水线已经在以符合架构（Schema）的格式自信地撒谎了好几周。

这是将 JSON 模式视为可靠性保证的核心问题。结构一致性（Structural conformance）和语义正确性（Semantic correctness）是系统的不同属性，混淆两者是生产级 AI 工程中最代价高昂的错误之一。

每个集成工程师都曾面对过两个拒绝相互通信的系统。一个说的是 2008 年的 SOAP XML，另一个期望的是上季度刚设计的 REST JSON 负载。传统的解决方案——编写自定义解析器、维护映射层、祈祷没人改动模式——在第三或第四个系统加入之前都还能用。之后你就要维护一个没人愿意接手的组合爆炸式翻译代码了。

现在团队正在将 LLM 放入这个缺口中。不是作为聊天机器人，不是作为代码生成器，而是作为运行时协议翻译器——读取一种格式并输出另一种格式。对于某些用例，它的效果出奇地好——而对于其他用例，它的失败方式则真正令人担忧。理解这两个区域之间的边界就是整个博弈的关键。

当开发者第一次接入 JSON 模式时，响应结果感觉就像解决了一个大问题。LLM 不再返回 Markdown 围栏、文字道歉或靠近花括号的乱码。输出可以解析了，测试通过了，生产环境上线了。

然而，三周后，一个后台作业悄无声息地失败了，因为模型在 Schema 要求 {"status": "completed"} 时返回了 {"status": "complete"}。由于一个必填字段返回了 null 而不是被省略，数据流水线崩溃了。智能体工具调用循环（agent tool-call loop）提前终止，因为模型在字符串值中嵌入了一个异常换行符，导致下游解析器卡死。

JSON 模式保证了语法上有效的 JSON。它并不保证该 JSON 的含义与你的预期一致，不保证它包含你的应用程序所期望的字段，也不保证在多次请求之间保持语义一致性。这些是不同的问题，需要不同的解决方案。

大多数基于 LLM 的应用中都潜伏着一个隐形 Bug。它不会出现在单元测试中。在前一千次请求中也不会触发。它会一直潜伏，直到用户输入了带有引号的内容，或者模型出于某种莫名其妙的原因决定将其 JSON 响应包裹在 Markdown 代码块中，再或者将 "count" 字段作为字符串 "three" 而非整数 3 返回。这时，你的生产流水线就会崩溃。

“LLM 是文本生成器”与“我的应用需要结构化数据”之间的鸿沟，是大多数可靠性问题产生的原因。弥补这一鸿沟并非 Prompt 工程问题，而是一个基础设施问题。在 2026 年，我们终于拥有了能够正确解决这一问题的工具。

在生产环境中的某个阶段，每个由 LLM 驱动的应用都需要停止将模型输出视为散文，而开始将其视为数据。当你尝试从语言模型中可靠地提取 JSON 对象——并将其输入到下游的数据库、API 调用或 UI 中时——你会发现这有多少种出错的方式。模型会将 JSON 包裹在 Markdown 栅栏中。它会生成一个有效的对象，但遗漏了必填字段。它在多次调用中格式化日期的格式不一致。它会幻觉出枚举值。这些失败中的任何一个都会静默地破坏下游状态。

结构化输出已经从一个事后才考虑的问题演变成生产级 LLM 系统的一等公民。这篇文章介绍了强制执行结构化输出的三种主要机制、各自失效的场景，以及如何在约束下设计高质模式（Schema）。