结构化输出工程：从 prompt 拼运气到约束解码的 100% JSON 可靠性

想象这样一个场景：你的团队运营一个电商 AI 客服系统。用户问"我的订单什么时候到"，LLM 需要返回一个结构化的 JSON 对象，包含 intent（用户意图）、order_id（订单号）和 confidence（置信度）。下游代码用 JSON.parse 解析，提取 order_id 查询物流系统。

在 playground 里测试了 50 次，每次都返回完美的 JSON。你上线了。

凌晨 2 点，on-call 工程师被叫醒。用户问了一个复杂问题："我的订单 ORD-123 还没到，但物流显示已签收，这是怎么回事？"LLM 返回的不是 JSON，而是一段散文，解释了三种可能的情况。JSON.parse 抛出异常，整个请求失败。用户看到"系统错误，请稍后再试"。

这不是模型"犯蠢"了。这是 LLM 的本质决定的——它们是文本生成器，不是 JSON 生成器。当你用 prompt 说"只返回 JSON"时，模型在 95% 的情况下会遵守。但那 5% 的失败率在每天 10,000 次请求中就是 500 次崩溃。

本文能帮你做什么：读完之后，你将能够——

1. 理解为什么 prompt 工程在结构化输出上注定失败
2. 设计一个三层防御体系（约束解码 + 验证沙箱 + 重试策略）
3. 为 Pydantic schema 选择正确的字段顺序和结构
4. 判断哪些场景适合约束解码、哪些适合 tool calling

先澄清一个常见误解：结构化输出不是"让模型更聪明"的问题。即使是最强的模型（GPT-4o、Claude Opus 4），在复杂 prompt 下也会偶尔返回 markdown code fence、添加解释性前言、或在 JSON 后追加注释。约束解码不是 post-processing——它把 schema 合规性烘焙到每一个解码步骤中。

行业在结构化输出上花了三年时间收敛，形成了三个清晰的成熟度级别。每个级别都有明确的能力上限和失败模式。

Level 1: Prompt 工程（80-95% 成功率）

你在 system prompt 里写"只返回合法的 JSON，格式如下"，然后给一个示例。这在简单 schema 上能工作 80-95% 的时间。失败模式很微妙：模型在复杂 prompt 下添加前言（"好的，这是您的 JSON："）；用 markdown code fence 包裹 JSON；在 JSON 后追加解释（"希望这能帮到您！"）；静默省略 optional 字段；在 schema 很长时幻觉字段名。你会加一个 regex cleanup 和一个 try/catch，然后说服自己这够用了。但对于任何严肃的场景，这不够用。

Level 2: 验证 + 重试（95-99% 成功率）

你用 Instructor 这样的库包装 LLM 客户端。模型返回 JSON 后用 Pydantic 验证，失败则把错误信息注入 prompt 重新请求。这比 Level 1 显著更可靠，但每次验证失败都意味着额外的 API 调用（成本翻倍到三倍）；重试可能陷入循环（模型反复犯同样的错误）；仍然依赖模型的"配合"——它可以选择忽略验证错误。

Level 3: 约束解码（100% 语法合规）

你把 Pydantic schema 编译成一个有限状态机（FSM）。在解码的每一步，引擎计算"哪些 token 能让 FSM 前进到合法状态"，然后把其他 token 的概率设为负无穷。模型物理上不可能输出非法 JSON。这不是 post-processing。这是烘焙到解码过程中的约束。XGrammar 引擎在 MLC 团队的实现中，token mask 生成耗时小于 40 微秒，后续请求复用缓存的 FSM，开销接近零。对于简单 schema，延迟影响小于 5%。对于深度嵌套的 schema 或大型 enum 集合，可能达到 30-60%——这是一个真实的信号，提示你简化 schema。

2026 年的默认选择应该是 Level 3。 Prompt 工程增加了重试复杂度，function calling 增加了验证复杂度，两者都增加了凌晨 2 点难以调试的失败模式。原生结构化输出加 Pydantic 验证层给了你可用的最强保证，并消除了整整一类生产事故。

约束解码听起来像魔法，但它的原理很直接。让我们拆解 XGrammar 的工作流程。

步骤 1: Schema 编译为 FSM

你的 Pydantic schema 被 XGrammar 编译成一个有限状态机（FSM）。FSM 的每个状态代表"JSON 解析器的当前位置"：状态 0 等待左大括号，状态 1 等待字段名（intent、order_id 或 confidence），状态 2 等待冒号，状态 3 等待值（对于 intent 字段，只允许三个枚举值之一），依此类推。

步骤 2: 解码时的 token mask

在自回归解码的每一步，模型输出一个 logits 向量（词表中每个 token 的"得分"）。XGrammar 做三件事：第一，对于当前 FSM 状态，计算"哪些 token 能让 FSM 前进到合法状态"；第二，生成一个 mask，合法 token 标记为 1，非法 token 标记为 0；第三，把 mask 应用到 logits，非法 token 的得分设为负无穷，然后对修正后的 logits 做 softmax 采样。结果：模型只能从合法 token 中采样，物理上不可能输出非法 JSON。

步骤 3: 性能开销

FSM 构建耗时 50-200 毫秒，这是一次性成本，后续请求复用。Token mask 生成每 token 小于 40 微秒（XGrammar 优化后）。延迟影响：简单 schema 小于 5%，复杂 schema 30-60%。

为什么复杂 schema 更慢？ 深度嵌套的 JSON 或大型 enum 集合意味着 FSM 状态更多，每步需要检查的转移更多。如果你的 schema 导致 60% 的延迟开销，问问自己：这个嵌套层级反映了真实的数据层次结构，还是只是组织偏好？

即使约束解码保证了语法合规，糟糕的 schema 设计仍然会导致语义失败。这些是反复咬到团队的模式。

陷阱 1: 字段顺序错误

如果你的 schema 有 reasoning 字段和 classification 字段，把 reasoning 放在前面。LLM 从左到右生成 token。当模型先写出推理再承诺分类时，它会产生更好的分类。如果你把答案字段放在前面，模型在思考之前就承诺了标签，然后在 reasoning 字段里合理化。这听起来像 LLM 的怪癖，但它一致地偏移准确率几个百分点。

陷阱 2: 过度嵌套

嵌套是可靠性的敌人。OpenAI 的原生结构化输出限制在 5 层嵌套和 100 个属性。超过这个限制，FSM 编译时间飙升，每 token 开销增长。更重要的是，4 层以上嵌套的 schema 即使有约束解码也有更高的错误率——模型有更多机会丢失上下文。如果你的 schema 深度嵌套，问自己：这个嵌套反映了真实的数据层次结构，还是只是组织偏好？

陷阱 3: 省略字段描述

Pydantic 的 Field description 不是装饰。约束解码引擎把字段描述注入到 FSM 中，帮助模型理解每个字段的语义。没有描述的字段，模型只能从字段名猜测含义。比如 status 字段，模型不知道这是订单状态、支付状态还是物流状态。

陷阱 4: 用开放字符串代替 enum

如果你的字段只有 3 个合法值，用 enum 或 Literal，不要接受开放字符串。比如 priority 字段，如果接受开放字符串，模型可能返回 high、urgent、critical、P1 等各种变体。Enum 不仅提高了可靠性，还让约束解码更高效——FSM 状态更少。

from pydantic import BaseModel

# 错误：字段顺序错误，classification 在 reasoning 之前
class BadSchema(BaseModel):
    classification: str  # 模型先承诺标签
    reasoning: str       # 然后合理化

# 错误：过度嵌套（4 层）
class NestedLevel4(BaseModel):
    value: str

class NestedLevel3(BaseModel):
    level4: NestedLevel4

class NestedLevel2(BaseModel):
    level3: NestedLevel3

class NestedLevel1(BaseModel):
    level2: NestedLevel2

# 错误：省略字段描述
class BadSchema2(BaseModel):
    status: str  # 模型猜测：订单状态？支付状态？物流状态？

# 错误：用开放字符串代替枚举
class BadSchema3(BaseModel):
    priority: str  # 模型可能返回 "high", "urgent", "critical", "P1"...

from pydantic import BaseModel, Field
from typing import Literal

# 正确：reasoning 在 classification 之前
class GoodSchema(BaseModel):
    reasoning: str = Field(description="分析问题的推理过程")
    classification: str = Field(description="最终分类结果")

# 正确：扁平化结构（1 层）
class FlatSchema(BaseModel):
    intent: str = Field(description="用户意图")
    confidence: float = Field(description="置信度，0-1 之间")
    order_id: str | None = Field(None, description="订单 ID，如果相关")

# 正确：字段有描述
class DescribedSchema(BaseModel):
    order_status: str = Field(
        description="订单当前状态：pending（待支付）、paid（已支付）、shipped（已发货）、delivered（已送达）"
    )

# 正确：用 Literal 代替开放字符串
class EnumSchema(BaseModel):
    priority: Literal["low", "medium", "high"]  # 只有 3 个合法值

2026 年的 Provider 格局已经清晰。每个主流 Provider 都提供某种形式的结构化输出，但实现机制和可靠性保证差异显著。

OpenAI: 原生 JSON Schema 模式

OpenAI 的 response_format 设置为 json_schema 类型，你把完整的 JSON Schema 传给 API，模型在解码时强制遵守。优点是 100% 语法合规，延迟开销小于 5%（简单 schema）。限制是最多 5 层嵌套、100 个属性，不支持 ref 引用。

Anthropic: Tool Use 模式

Anthropic 没有原生的 JSON Schema 模式，但 tool use 提供了类似的保证。你定义一个 tool，schema 通过 tool 的参数传入，模型返回的 tool_use 块保证符合 schema。优点是 100% 语法合规，与 tool calling 自然集成。限制是 tool use 的语义是"模型想调用工具"，不是"模型想返回结构化数据"——这在某些场景下可能导致模型过度谨慎。

Google Gemini: response_schema

Gemini 的 response_schema 接受原始 JSON Schema（不是 Pydantic 模型），需要 schema 转换工具。优点是 100% 语法合规。限制是需要 schema 转换，文档不如 OpenAI 和 Anthropic 完善。

跨 Provider 抽象：Instructor 库

如果你需要多 Provider 切换，Instructor 库抽象了差异。它提供一致的 response_model 接口，跨 OpenAI、Anthropic、Gemini 等。Instructor 不是约束解码——它仍然是 Level 2（验证 + 重试）。但它在每个 Provider 上显著更可靠，并自动处理验证失败的重试。

选型决策：单 Provider 用原生结构化输出（最强保证）；多 Provider 用 Instructor（一致性 + 自动重试）；需要 tool calling 用 Anthropic tool use 或 OpenAI function calling。

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "customer_service_response",
            "schema": CustomerServiceResponse.model_json_schema()
        }
    }
)

response = client.messages.create(
    model="claude-opus-4",
    tools=[{
        "name": "customer_service_response",
        "description": "结构化客服响应",
        "input_schema": CustomerServiceResponse.model_json_schema()
    }],
    messages=[...]
)
# 解析 tool_use 块
tool_use = next(block for block in response.content if block.type == "tool_use")
parsed = CustomerServiceResponse(**tool_use.input)

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())
response = client.chat.completions.create(
    model="gpt-4o",
    response_model=CustomerServiceResponse,  # Pydantic 模型
    messages=[...]
)
# response 已经是 CustomerServiceResponse 实例

即使使用原生结构化输出，也要在之上加一个验证层。这不是偏执——这是防御约束解码引擎无法捕获的语义失败。

验证三明治模式包含三层：

第一层是约束解码，保证 JSON 语法合规，由 Provider 的 json_schema 模式处理。这一层确保输出是合法的 JSON，所有必需的字段都存在，类型正确（字符串、数字、布尔值等）。这是语法层面的保证。

第二层是 Pydantic 验证，保证字段类型、格式、范围合规，在 schema 层处理。比如 order_id 必须符合正则表达式 ^ORD-d{4}-d{2}-d{2}-d{5}$，confidence 必须在 0 到 1 之间，intent 必须是三个枚举值之一。这些约束在 Pydantic 的 Field 定义中声明，验证失败会抛出 ValidationError。

第三层是业务逻辑验证，保证字段之间的语义关系合规，在应用层处理。比如"如果 intent 是 order_status，则 order_id 不能是 null"——这种跨字段的约束，约束解码和 Pydantic 都无法捕获，需要在业务代码中显式检查。

约束解码不能捕获"intent 是 order_status 但 order_id 是 null"这种语义错误。Pydantic 的 model_validator 可以处理一部分（比如字段格式），但跨字段的业务规则需要在应用层验证。

监控指标：语法合规率应该 100%（如果不是，Provider 有 bug）；Pydantic 验证通过率应该大于 99%（如果低，schema 设计有问题）；业务逻辑验证通过率取决于场景，但应该有基线。当某个指标的通过率突然下降时，通常是模型升级、schema 变更或流量模式变化的信号。

重试策略：如果验证失败，不要无限重试。设置最大重试次数（通常 2-3 次），并在重试时把验证错误注入 prompt。这样模型可以看到自己之前的错误，并尝试修正。但要注意：如果模型反复犯同样的错误，继续重试只会浪费 token 和时间。此时应该回退到默认行为或告诉用户"系统暂时无法处理您的请求"。

关键洞察：约束解码消除了语法失败，但不能消除语义失败。验证三明治是你的防御纵深。

from pydantic import BaseModel, ValidationError

class CustomerServiceResponse(BaseModel):
    intent: str
    order_id: str | None
    confidence: float

def process_llm_response(raw_response: str) -> CustomerServiceResponse:
    # 层 1: 约束解码保证语法合规（由 Provider 处理）
    
    # 层 2: Pydantic 验证语义合规
    try:
        parsed = CustomerServiceResponse.model_validate_json(raw_response)
    except ValidationError as e:
        # 这不应该发生（约束解码保证了语法），但防御 Provider bug
        log_error(f"Validation failed: {e}")
        raise
    
    # 层 3: 业务逻辑验证
    if parsed.intent == "order_status" and parsed.order_id is None:
        raise ValueError("order_id is required for order_status intent")
    
    if parsed.confidence < 0.5:
        log_warning(f"Low confidence: {parsed.confidence}")
    
    return parsed

for attempt in range(3):
    try:
        response = call_llm(messages)
        parsed = process_llm_response(response)
        return parsed
    except ValidationError as e:
        messages.append({"role": "assistant", "content": response})
        messages.append({"role": "user", "content": f"Validation error: {e}. Please fix."})
raise MaxRetriesExceeded()

约束解码是 2026 年的默认选择，但不是银弹。这些场景下，你应该选择其他方案。

场景 1: 需要模型自由推理

如果你的任务是开放式问答、创意写作或复杂推理，约束解码会限制模型的表达能力。强制模型在 JSON 框架内思考，可能降低推理质量。替代方案是两阶段模式：第一阶段无约束生成，让模型自由推理；第二阶段结构化提取，用约束解码从推理文本中提取结构化数据。

场景 2: Schema 极度复杂

如果你的 schema 有 10 层以上嵌套、500 个以上属性、或复杂的条件约束（"如果 A 是 X，则 B 必须是 Y"），约束解码的 FSM 可能变得巨大，延迟开销超过 100%。替代方案是简化 schema，或拆分成多个小的结构化调用。

场景 3: 需要模型选择工具

如果任务是"模型需要决定调用哪个工具"，用 function calling 或 tool use，不要用 json_schema。Tool calling 的语义更清晰，Provider 优化更好。

在 tool calling 模式下，模型不仅返回结构化数据，还表达了"我想调用这个工具"的意图。这种语义上的区别很重要：json_schema 模式是"请返回符合这个 schema 的数据"，而 tool calling 是"请决定是否需要调用工具，如果需要，调用哪个"。后者更符合 Agent 的决策过程。

此外，tool calling 通常支持并行调用多个工具，这是 json_schema 模式难以表达的。如果你的 Agent 需要同时查询天气、搜索网页和读取文件，tool calling 可以一次性返回三个工具调用，而 json_schema 需要复杂的嵌套结构。

场景 4: 跨 Provider 一致性要求极高

如果你需要在 OpenAI、Anthropic、Gemini 之间无缝切换，且要求输出完全一致，用 Instructor 库。原生结构化输出在不同 Provider 上的行为有细微差异（比如 OpenAI 不支持 ref，Anthropic 的 tool use 语义不同）。Instructor 通过统一的 Pydantic 接口抹平了这些差异，并在验证失败时自动重试，确保跨 Provider 的一致性。

场景 5: 需要流式输出

如果你的应用需要流式返回结构化数据（比如实时显示解析进度），约束解码目前不支持流式。你需要用 Level 2 方案（验证 + 重试），或者等 Provider 支持流式结构化输出（部分 Provider 已在实验阶段）。

# 阶段 1: 自由推理
reasoning = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "分析这个复杂问题..."}]
)

# 阶段 2: 结构化提取
structured = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": f"从以下推理中提取关键结论：{reasoning}"},
    ],
    response_format={"type": "json_schema", "json_schema": {...}}
)

如果你要在生产环境中部署结构化输出，这是你的检查清单。

Schema 设计检查：字段顺序 reasoning 在 classification 之前；扁平化嵌套层级小于等于 3 层；每个字段都有 description；用 enum 或 Literal 代替开放字符串；Optional 字段显式标记。

Provider 选型检查：单 Provider 用原生 json_schema 或 tool use；多 Provider 用 Instructor 库；需要 tool calling 用 tool use，不要用 json_schema。

验证层检查：三层验证（约束解码 + Pydantic + 业务逻辑）；监控指标（语法合规率、Pydantic 通过率、业务逻辑通过率）；重试策略（最大 2-3 次，验证错误注入 prompt）。

性能检查：简单 schema 延迟开销小于 5%；复杂 schema 延迟开销小于 30%（如果更高，简化 schema）；FSM 构建时间 50-200 毫秒（一次性，后续复用）。

测试检查：单元测试（Pydantic 模型的正确性）；集成测试（Provider API 的正确性）；边界测试（复杂 prompt 下的鲁棒性）；回归测试（Provider 切换时的输出一致性）。

文档检查：Schema 版本控制（Pydantic 模型作为 source of truth）；跨服务共享（把 Pydantic 模型打包成库，不要复制粘贴）。

迁移检查：如果你从 Level 1 或 Level 2 迁移到 Level 3，先在非关键路径上试点；收集基线数据（当前的失败率、重试次数、延迟分布）；对比迁移前后的指标；逐步扩大范围。

关键洞察：结构化输出的最大收益不是 JSON 能解析——这是个已解决的问题。收益是你的 LLM 开始像代码库中的其他函数一样行为，你可以应用三十年的软件工程实践。

本文的分析基于以下独立来源：

1. Tian Pan，「Structured Outputs in Production: Engineering Reliable JSON from LLMs」，2026-04-07 发布，2026-04-15 更新。详解三个成熟度级别、XGrammar 工作原理、schema 设计陷阱和 Provider 选型。
   https://tianpan.co/blog/2025-10-11-structured-outputs-in-production

2. Satyam Kumar (AppScale)，「Structured Output Engineering: Reliable JSON from LLMs (2026)」，2026-04-13。覆盖 Provider 原生结构化输出、开源约束生成引擎和生产模式。
   https://appscale.blog/en/blog/structured-output-engineering-reliable-json-from-llms-2026

3. JobsByCulture，「Structured Output With LLMs: The Only Three Techniques That Matter in 2026」，2026-07-07。对比 JSON mode、tool calling 和约束解码的底层机制、失败模式和成本影响。
   https://jobsbyculture.com/blog/structured-output-with-llms-2026

4. ZeroEntropy，「Structured output: forcing LLMs to emit JSON and schemas」，2026。解释三种方法的可靠性排序、约束解码何时伤害质量、以及生产框架。
   https://www.zeroentropy.dev/concepts/structured-output

5. vLLM 官方文档，「Structured Outputs」，2026。说明 vLLM 的 xgrammar 和 guidance 后端支持。
   https://docs.vllm.ai/en/latest/features/structured_outputs

6. XGrammar 项目（MLC 团队），GitHub 仓库和文档，2025-2026。高性能语法约束解码库，被 vLLM、MLC-LLM、SGLang 采用。
   https://github.com/mlc-ai/xgrammar