LLM 结构化输出完全指南：从 JSON Schema 到 Constrained Decoding

2026 年，几乎所有涉及 AI 的应用都需要从大语言模型（LLM）中提取结构化数据。根据 Vercel 的内部统计，超过 70% 的 AI SDK 调用期望返回 JSON 格式而非自由文本。然而，LLM 的本质是逐 token 生成概率分布，天然不保证输出合法的 JSON——一个多余的逗号、缺失的引号或错误的嵌套就能让你的下游解析器崩溃。

本文将深入拆解四种主流的 LLM 结构化输出方案，对比各厂商实现差异，并提供生产级的代码示例和避坑指南。

🔍 一、四种结构化输出方案全景对比

在进入具体实现之前，先理解业界目前的四种主流方案，它们在可靠性、灵活性和性能上各有取舍。

1.1 Prompt Engineering + 后处理

最原始的方式：在 prompt 中要求模型输出 JSON，然后用正则或 JSON.parse() 提取。

// 最简单但最不可靠的方式
const prompt = `请以 JSON 格式返回用户信息，包含 name、age、email 字段。
只返回 JSON，不要返回其他内容。`;

const response = await llm.call(prompt);
const data = JSON.parse(response); // 随时可能崩溃

⚠️ **警告：**纯靠 prompt 约束的 JSON 输出在生产环境中失败率高达 15-30%，尤其是复杂嵌套结构。永远不要在没有容错机制的情况下使用这种方式。

1.2 JSON Mode（响应格式约束）

OpenAI 在 2023 年底引入 response_format: { type: "json_object" }，通过 API 层面保证输出是合法 JSON。

1.3 Function Calling / Tool Use

通过定义函数签名（JSON Schema），让模型以结构化的参数形式"调用函数"，间接实现结构化输出。

1.4 Constrained Decoding（受限解码）

最严格的方案：在 token 生成阶段直接约束输出必须符合给定的 JSON Schema 或正则表达式，从概率层面保证输出合法性。

下表对比了这四种方案的关键指标：

⚡ **关键结论：**没有万能方案。简单场景用 JSON Mode，需要字段级控制用 Function Calling，对格式零容忍用 Constrained Decoding。

🛠️ 二、各厂商实现详解与代码实战

2.1 OpenAI：JSON Mode + Structured Outputs

OpenAI 提供了两层结构化输出能力。第一层是 JSON Mode，只保证输出是合法 JSON；第二层是 Structured Outputs（2024 年引入），可以传入 JSON Schema 做严格约束。

// OpenAI Structured Output - 严格遵循 JSON Schema
import OpenAI from 'openai';

const openai = new OpenAI();

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: '提取用户信息并返回结构化数据' },
    { role: 'user', content: '我叫张三，今年28岁，邮箱是zhangsan@example.com，在北京工作' }
  ],
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'user_info',
      strict: true,  // 开启严格模式
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          age: { type: 'integer' },
          email: { type: 'string', format: 'email' },
          city: { type: 'string' }
        },
        required: ['name', 'age', 'email', 'city'],
        additionalProperties: false
      }
    }
  }
});

console.log(JSON.parse(response.choices[0].message.content));
// 输出: { name: "张三", age: 28, email: "zhangsan@example.com", city: "北京" }

💡 **提示：**OpenAI 的 strict: true 模式下，所有 properties 中的字段都必须出现在 required 数组中，且不支持 oneOf/anyOf 的部分组合模式。这是当前版本的限制。

2.2 Anthropic：Tool Use 作为结构化输出通道

Anthropic 的 Claude 模型没有独立的 JSON Mode，但通过 Tool Use（工具调用）机制可以实现等价的结构化输出。

// Anthropic Claude - 通过 Tool Use 获取结构化输出
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  tools: [{
    name: 'extract_user_info',
    description: '提取用户个人信息',
    input_schema: {
      type: 'object',
      properties: {
        name: { type: 'string', description: '用户姓名' },
        age: { type: 'integer', description: '年龄' },
        email: { type: 'string', description: '邮箱地址' },
        city: { type: 'string', description: '所在城市' }
      },
      required: ['name', 'age', 'email', 'city']
    }
  }],
  tool_choice: { type: 'tool', name: 'extract_user_info' },  // 强制调用
  messages: [
    { role: 'user', content: '我叫张三，今年28岁，邮箱是zhangsan@example.com，在北京工作' }
  ]
});

// 从 tool_use block 中提取结构化数据
const toolBlock = response.content.find(b => b.type === 'tool_use');
console.log(toolBlock.input);
// 输出: { name: "张三", age: 28, email: "zhangsan@example.com", city: "北京" }

📌 **记住：**Anthropic 的 tool_choice: { type: "tool", name: "..." } 可以强制模型调用指定工具，这比 OpenAI 的 tool_choice: "required" 更精确——你可以指定调用哪个工具。

2.3 Google Gemini：Response Schema

Google 的 Gemini API 提供了直接的 responseSchema 参数，使用体验最为简洁。

// Google Gemini - responseSchema 直接约束输出
import { GoogleGenerativeAI, SchemaType } from '@google/generative-ai';

const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);

const model = genAI.getGenerativeModel({
  model: 'gemini-2.5-flash',
  generationConfig: {
    responseMimeType: 'application/json',
    responseSchema: {
      type: SchemaType.OBJECT,
      properties: {
        name: { type: SchemaType.STRING },
        age: { type: SchemaType.INTEGER },
        email: { type: SchemaType.STRING },
        city: { type: SchemaType.STRING }
      },
      required: ['name', 'age', 'email', 'city']
    }
  }
});

const result = await model.generateContent(
  '我叫张三，今年28岁，邮箱是zhangsan@example.com，在北京工作'
);
console.log(JSON.parse(result.response.text()));

2.4 Constrained Decoding：开源模型的终极方案

对于自部署的开源模型（Llama、Qwen、Mistral），可以通过 vLLM 或 llama.cpp 的 grammar 约束实现真正的 Constrained Decoding。

# vLLM + Outlines 实现 Constrained Decoding
from openai import OpenAI
from pydantic import BaseModel, Field

# 定义 Pydantic 模型作为 Schema
class UserInfo(BaseModel):
    name: str = Field(description="用户姓名")
    age: int = Field(description="年龄", ge=0, le=150)
    email: str = Field(description="邮箱地址")
    city: str = Field(description="所在城市")

# vLLM 兼容 OpenAI API，支持 guided_json 参数
client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")

response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[
        {"role": "user", "content": "我叫张三，今年28岁，邮箱是zhangsan@example.com，在北京工作"}
    ],
    extra_body={
        "guided_json": UserInfo.model_json_schema()  # vLLM 的受限解码参数
    }
)

print(response.choices[0].message.content)
# 100% 合法 JSON，严格遵循 Schema

⚠️ **警告：**Constrained Decoding 会显著增加推理延迟（15-30%），因为在每一步解码时都需要计算合法 token 集合。对于延迟敏感的在线服务，建议先用 JSON Mode + 后处理验证，失败再 fallback 到 Constrained Decoding。

🧩 三、生产级最佳实践与避坑指南

3.1 用 Zod/Pydantic 做运行时验证

无论使用哪种方案，都不要信任 LLM 的输出——始终在应用层做运行时验证。

// TypeScript + Zod：LLM 输出的运行时验证
import { z } from 'zod';

const UserInfoSchema = z.object({
  name: z.string().min(1),
  age: z.number().int().min(0).max(150),
  email: z.string().email(),
  city: z.string().min(1)
});

type UserInfo = z.infer<typeof UserInfoSchema>;

async function extractUserInfo(text: string): Promise<UserInfo> {
  const response = await callLLM(text);
  const parsed = JSON.parse(response);

  // 运行时验证 — 捕获 LLM 的格式错误
  const result = UserInfoSchema.safeParse(parsed);
  if (!result.success) {
    console.error('Schema 验证失败:', result.error.issues);
    // 重试或使用默认值
    throw new Error(`LLM 输出不符合预期 Schema: ${result.error.message}`);
  }

  return result.data;
}

3.2 重试 + 降级策略

LLM 输出存在不确定性，生产环境必须有重试机制。

// 带重试和降级的 LLM 结构化调用
async function callWithRetry(fn, schema, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const raw = await fn();
      const parsed = JSON.parse(raw);
      const result = schema.safeParse(parsed);
      if (result.success) return { data: result.data, retries: i };
      // Schema 不匹配，在下一次重试的 prompt 中加入错误信息
      fn = () => fn.withError(result.error.message);
    } catch (e) {
      if (i === maxRetries - 1) break;
      await new Promise(r => setTimeout(r, 1000 * (i + 1))); // 指数退避
    }
  }
  return { data: null, retries: maxRetries, error: 'MAX_RETRIES_EXCEEDED' };
}

3.3 成本与延迟优化

结构化输出会增加 token 消耗和延迟。以下是实测数据（基于 GPT-4o，1000 次调用平均值）：

⚡ **关键结论：**Structured Output（strict 模式）反而比纯 JSON Mode 更省 token，因为模型不需要输出多余字段。Function Calling 的 token 消耗最低，因为模型只需输出参数值。

3.4 复杂嵌套结构的处理技巧

当 Schema 变得复杂时，LLM 的遵循能力会下降。几个实用技巧：

💡 **提示：**对于超过 5 层嵌套的复杂 Schema，建议拆分为多次调用。先提取顶层结构，再逐层展开——每层的成功率从 60% 提升到 95% 以上。

• ✅ 使用 enum 约束可选值，比自由文本更可靠
• ✅ 在字段的 description 中给出示例值，显著提升遵循率
• ✅ 数组字段明确指定 minItems 和 maxItems
• ❌ 避免在 Schema 中使用 oneOf/anyOf，很多模型支持不完整
• ❌ 不要依赖 format 约束（如 email、date-time），大多数模型忽略它
• ⚠️ additionalProperties: false 在 OpenAI strict 模式下必须设置，其他平台可选

🎯 总结与工具推荐

选择结构化输出方案时，决策树很简单：

1. 用 OpenAI GPT-4o？ → 直接用 Structured Outputs（strict: true），可靠性最高
2. 用 Claude？ → 用 Tool Use + tool_choice 强制调用，等价于结构化输出
3. 用 Gemini？ → 用 responseSchema，API 最简洁
4. 自部署开源模型？ → vLLM + Outlines 的 Constrained Decoding，零格式错误
5. 需要跨厂商兼容？ → Instructor 库（Python）统一了各厂商的接口

推荐工具链：

• 🔧 Instructor — Python 库，统一 OpenAI/Anthropic/Google 的结构化输出接口，内置 Pydantic 验证和重试
• 🔧 Vercel AI SDK — TypeScript 生态，generateObject() 一行代码搞定结构化输出
• 🔧 Outlines — 专注 Constrained Decoding，支持正则和 JSON Schema 约束
• 🔧 Zod / Pydantic — LLM 输出的运行时验证标配
• 🔧 jsjson.com JSON 格式化工具 — 快速格式化和验证 LLM 返回的 JSON

📌 **记住：**结构化输出不是银弹。对于真正复杂的提取任务（如从非结构化文档中提取嵌套表格数据），考虑用多步 Agent 拆解任务，而不是试图一次调用就搞定一个巨大的 Schema。简单、扁平的 Schema 永远比复杂、深层嵌套的 Schema 更可靠。