结构化输出的三道闸Three gates of structured output

「请输出 JSON」是请求，不是保证。 让输出可被程序消费，有三道闸：提示词层请求格式， API 层用 schema 约束生成，协议层对结果做校验。 三道闸管的事不同，失效方式也不同。 效果未实测；以下机制均出自官方文档、规范与论文。

"Please output JSON" is a request, not a guarantee. Making output consumable by programs takes three gates: request the format in the prompt, constrain generation with a schema at the API level, and validate results at the protocol level. The three gates cover different things and fail in different ways. We have not run hands-on tests; the mechanisms below come from official docs, specs, and papers.

Anthropic 官方教程教了两招。 第一招：让模型把答案包进 XML 标签，程序取标签之间的内容即可。 第二招叫预填（prefill）：把开场标签或 { 放进 assistant 轮， 模型会从这个位置接着写。官方措辞很克制： 强制 JSON 输出「不是确定性的，但接近」（原文 "not deterministically, but close to it"）。 配套技巧：把闭合标签设为 stop_sequences，答案一出就停，省掉收尾废话。

提示词层成本低、随模型可用，但它只是引导。 模型仍可能跑偏，下游必须容错。

Anthropic's official tutorial teaches two moves. First: have the model wrap the answer in XML tags, so a program can extract what sits between them. Second is prefill: put the opening tag or { into the assistant turn, and the model continues from that position. The official wording is deliberately restrained: enforcing JSON output is "not deterministically, but close to it". A companion trick: set the closing tag as stop_sequences so generation stops as soon as the answer is out, skipping the closing remarks.

The prompt level is cheap and works with any model, but it is only guidance. The model can still drift; downstream code must tolerate that.

OpenAI 的 Structured Outputs 把约束下沉到生成过程。 官方原文：它 "guarantees the model will always generate responses that adhere to your supplied JSON Schema"。 开启方式是 strict: true，可用于响应格式或函数定义。

与 JSON mode 的区别要分清： JSON mode 只保证输出是合法 JSON；Structured Outputs 连形状一起约束。 官方列的典型用途：UI 按结构渲染、从文档抽取填库、抽实体调工具。

两个工程细节： 模型出于安全拒绝回答时，拒绝内容不符合你的 schema—— API 用单独的 refusal 字段标示，反序列化前要分开处理。 SDK 提供 parse 助手，可直接传 Pydantic 模型代替手写 schema。

OpenAI's Structured Outputs pushes the constraint down into generation itself. Official text: it "guarantees the model will always generate responses that adhere to your supplied JSON Schema". Enable it with strict: true, on either a response format or function definitions.

Keep the difference from JSON mode clear: JSON mode only guarantees the output is valid JSON; Structured Outputs constrains the shape as well. Official use cases: rendering structured answers in a UI, extracting document content into a database, extracting entities to call tools.

Two engineering details: when the model refuses for safety reasons, the refusal does not follow your schema — the API marks it with a separate refusal field, so handle it before deserializing. The SDK ships a parse helper that accepts a Pydantic model instead of a hand-written schema.

API 层的保证从哪来？语法约束解码（GCD）是背后的机制之一。 论文的做法：用形式语法描述输出空间，生成时只允许符合语法的 token。 结构由此得到保证，而不是靠模型自觉。 论文还提出输入相关语法：不同输入可以对应不同输出结构。 这条路线不需要微调，适合训练数据少、微调贵的结构化任务。

Where does the API-level guarantee come from? Grammar-constrained decoding (GCD) is one mechanism behind it. The paper's approach: describe the output space with a formal grammar, and allow only grammar-conforming tokens during generation. Structure is thereby guaranteed rather than left to the model's self-discipline. The paper also introduces input-dependent grammars: different inputs can map to different output structures. This route needs no finetuning, which suits structured tasks where training data is scarce or finetuning is expensive.

工具协议把校验写进了规范。MCP 的 tool 定义里： inputSchema 约束入参，outputSchema 可选地约束结果结构。 规范要求：提供 outputSchema 时，server 必须返回符合的结果， client 应当对照 schema 校验。

一个容易混的概念，规范专门澄清： "structuredContent is server-produced result data and is unrelated to LLM 'structured outputs'"。 也就是说，MCP 的结构化结果是 server 产出的数据， 与模型侧的 schema 约束生成是两回事。两道闸各管各的。

Tool protocols write validation into the spec. In an MCP tool definition: inputSchema constrains parameters; outputSchema optionally constrains the result structure. The spec requires: when an outputSchema is provided, servers MUST return conforming results, and clients SHOULD validate against the schema.

One easily confused concept gets an explicit clarification in the spec: "structuredContent is server-produced result data and is unrelated to LLM 'structured outputs'". In other words, MCP's structured content is data produced by the server, a different thing from schema-constrained model generation. The two gates guard separate doors.

1. 合法不等于正确：JSON 解析成功，字段值仍可能是错的。语义对错要靠评测。
2. 拒绝击穿 schema：安全拒绝不走你的格式，硬反序列化会报错。先查 refusal。
3. 预填不是保证：它把模型推向格式，不锁死格式。下游仍要校验。
4. 混淆两道闸：把 server 返回的结构化数据当成模型生成的保证，或反过来。

约束越强，灵活性越低：schema 写得太死，模型遇到边缘输入没有退路。 schema 设计要留合理的可选字段与拒绝通道。

1. Valid is not correct: JSON parses fine and field values can still be wrong. Semantic correctness needs evals.
2. Refusals pierce the schema: safety refusals do not follow your format, and hard deserialization errors out. Check refusal first.
3. Prefill is not a guarantee: it pushes the model toward the format without locking it in. Downstream still validates.
4. Confusing the gates: treating server-returned structured data as a model-generation guarantee, or vice versa.

Stronger constraints mean less flexibility: an over-rigid schema leaves the model no exit on edge inputs. Leave reasonable optional fields and a refusal path in the design.

• OpenAI Cookbook · Introduction to Structured Outputs
• Anthropic 官方教程 · Formatting Output and Speaking for Claude
• MCP 规范 · Tools
• Grammar-Constrained Decoding（arXiv 2305.13971）

核验日 2026-11-07，四条均直抓成功。 OpenAI 与 Anthropic 的文档主站本次网络不可达，官方内容取自两家官方仓库的 raw 文件。

• OpenAI Cookbook · Introduction to Structured Outputs
• Anthropic official tutorial · Formatting Output and Speaking for Claude
• MCP specification · Tools
• Grammar-Constrained Decoding (arXiv 2305.13971)

Verified 2026-11-07; all four fetched directly with HTTP 200. The OpenAI and Anthropic doc sites were unreachable from this network; official content was taken from raw files in both vendors' official repositories.