LLM 结构化输出：JSON Schema 强制与工具调用可靠性保障

凌晨三点，我的手机震动了一下——生产环境报警。打开日志一看，Agent 工具调用失败，连续重试了 5 次，全是参数格式错误。city 字段本该是 "北京"，LLM 返回的却是 {"name": "北京", "id": null}。解析器崩溃，整个数据处理管道停摆。

这是我去年踩的一个大坑。

那之后我开始系统性地研究 LLM 的结构化输出问题，从 OpenAI 的 Structured Outputs 到 Anthropic 的 Tool Use，从 Instructor 的自动重试到 Outlines 的受约束解码。说实话，一开始我以为这只是个”提示词写好点就能解决”的问题，后来才发现——这根本不是提示词的问题，是可靠性架构的问题。

这篇文章我想分享的就是这套”三层可靠性保障架构”：参数验证层、失败重试层、受约束解码层。文章最后还会横向对比 OpenAI、Claude、Gemini 三家的方案，告诉你怎么选、什么时候用什么。顺便放几个生产级的代码模板，拿去直接用。

一、为什么结构化输出是 Agent 的基石

先说说我遇到的”格式漂移”问题。这不是个别现象，而是每个做 Agent 开发的人都会碰到的噩梦。

格式漂移的三种姿势

第一种：字段缺失。 你让 LLM 返回一个包含 name、age、email 的用户信息对象，它给你返回 {"name": "张三"}——后面两个字段没了。不是每次都缺，是偶尔缺。生产环境里，“偶尔”就是”必然”。

第二种：类型错误。 文档写得明明白白：user_id 是整数。LLM 返回 "user_id": "12345"，字符串。Python 的 Pydantic 校验直接报错，整个调用链断裂。

第三种：多余内容。 最隐蔽的一种。你让它返回 JSON，它前面给你加个 “Here is the response:“，后面加个 “I hope this helps!”。JSON 解析器看到这些直接懵了。

vs

OpenAI 的官方数据挺能说明问题的：JSON Mode（只保证返回合法 JSON）的失败率在 5-10%，而 Structured Outputs（强制遵循 Schema）的失败率小于 0.1%。差了两个数量级。

这事儿为什么这么重要

你可能觉得：“不就是解析失败吗？多加几个重试不就行了。”

Railway - 现代化的部署平台，告别繁琐运维，让代码分钟级上线

立即开始 →推广

问题在于重试不是免费的。

API 调用成本。 一次 GPT-4 的调用可能要几毛钱，重试 5 次就是几块钱。如果你的 Agent 每天处理 10 万次请求，每条请求平均重试 2 次——这个账你自己算。

延迟叠加。 一次调用 2 秒，重试 3 次，用户就要等 6 秒以上。在实时对话场景里，这是不可接受的。

用户体验崩坏。 用户问个天气，你的 Agent 卡住了，转圈转了 10 秒，最后返回一个”系统错误”。下次他就不来了。

所以结构化输出这件事，不是”锦上添花”，是 Agent 能不能稳定运行的基石。下面我聊聊怎么解决这个问题——不是靠”提示词写好点”，而是靠一套可靠的架构。

二、三层可靠性保障架构

这套架构是我踩了很多坑之后总结出来的。它不是什么银弹，但能把你遇到格式错误的概率从 5-10% 降到接近零。

L1：参数验证层——第一道防线

这一层做的事情很简单：用 Pydantic 定义你期望的数据结构，强制类型转换，白名单过滤。

from pydantic import BaseModel, Field, field_validator
from typing import Optional, List
from datetime import datetime

class ToolCallParams(BaseModel):
    """工具调用参数模型"""
    city: str = Field(..., min_length=1, max_length=50, description="城市名称")
    date: Optional[datetime] = Field(None, description="查询日期")
    units: str = Field("metric", pattern="^(metric|imperial)$")

    @field_validator("city")
    @classmethod
    def validate_city(cls, v: str) -> str:
        # 白名单校验
        allowed_cities = {"北京", "上海", "广州", "深圳", "杭州"}
        if v not in allowed_cities:
            raise ValueError(f"不支持的城市: {v}，目前支持: {allowed_cities}")
        return v

Pydantic 会帮你做三件事：类型强制转换（字符串 “123” 转整数 123）、字段缺失检测、自定义校验。这是最基础也最重要的一层。

L2：失败重试层——带反馈的自修正

LLM 返回的数据校验失败时，不是简单重试，而是把错误信息喂回去，让它自己修正。Instructor 这个库做得很好，封装了这个逻辑。

import instructor
from openai import OpenAI
from pydantic import ValidationError

client = instructor.patch(OpenAI())

def get_weather_with_retry(user_query: str, max_retries: int = 3):
    """带错误反馈的重试机制"""
    messages = [{"role": "user", "content": user_query}]

    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="gpt-4o",
                response_model=ToolCallParams,  # Pydantic 模型
                messages=messages,
                temperature=0.1  # 结构化输出用低温
            )
            return response  # 自动校验通过

        except ValidationError as e:
            # 把错误喂给 LLM 让它修正
            error_msg = f"参数校验失败: {str(e)}\n请修正后重新返回正确的 JSON 格式。"
            messages.append({"role": "assistant", "content": "生成参数中..."})
            messages.append({"role": "user", "content": error_msg})

            if attempt == max_retries - 1:
                raise Exception(f"重试 {max_retries} 次后仍然失败: {e}")

# 使用示例
result = get_weather_with_retry("帮我查一下北京明天的天气")

核心思想是：LLM 不是在瞎猜，它知道哪里错了、为什么错。给它反馈，它能修。我实测下来，加了这个反馈机制后，重试成功率从 60% 提升到 95% 以上。

L3：受约束解码层——从源头杜绝错误

前两层都是”事后补救”，L3 是”事前预防”。

受约束解码的原理是这样的：在 LLM 生成每个 token 时，通过有限状态机（FSM）限制它的选择范围，强制它只能生成符合 Schema 的 token 序列。这就好比给 LLM 装了个”刹车”，它想乱输出都不行。

实现方案有两个主流选择：

Outlines（开源方案，适合本地模型）：

from outlines import models, generate
import json

# 加载本地模型
model = models.transformers("Qwen/Qwen2.5-7B-Instruct")

# 定义 Schema
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
    },
    "required": ["name", "age"]
}

# 创建受约束生成器
generator = generate.json(model, schema)
result = generator("提取用户信息: 张三今年28岁")
# 100% 符合 Schema，不需要任何重试

vLLM 的 guided_json（适合部署大模型）：

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen2.5-72B-Instruct")
sampling_params = SamplingParams(
    temperature=0.0,
    guided_decoding_backend="outlines",
    guided_json={  # 直接传 JSON Schema
        "type": "object",
        "properties": {
            "tool_name": {"type": "string"},
            "arguments": {"type": "object"}
        }
    }
)

L3 的代价是有额外的编译开销——FSM 需要根据 Schema 预先构建。如果你的 Schema 频繁变化，每次重新构建 FSM 会有延迟。但对大多数 Agent 应用来说，Schema 是相对稳定的，这个开销可以接受。

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

三层怎么选

三、厂商横向对比：OpenAI、Claude、Gemini 怎么选

这一章聊聊各家厂商的实现差异。说实话，如果你不做横向对比，很容易踩坑——不同厂商的”结构化输出”概念和实现方式差异很大。

OpenAI：Strict Mode，强制合规

OpenAI 在 2024 年 8 月推出了 Structured Outputs 功能，这是目前商业 API 里最可靠的方案。

核心机制是 strict: true 参数。开启后，LLM 的输出会被强制约束到你定义的 JSON Schema，保证 100% 合规。它的底层用的是受约束解码技术（基于 Grammar-based Constrained Decoding），原理跟 Outlines 类似。

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "提取用户信息"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "user_info",
            "strict": True,  # 关键参数
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"}
                },
                "required": ["name", "age"]
            }
        }
    }
)
# 输出 100% 符合 Schema

OpenAI 官方数据显示，Strict Mode 的失败率小于 0.1%。我用下来确实没遇到过格式错误——但也有限制：不支持递归 Schema，某些复杂嵌套结构需要变通处理。

Anthropic Claude：Tool Use，不保证合规

Claude 的结构化输出走的是另一条路——Tool Use（工具调用）。

你定义一个工具，Claude 会调用它并传参数。但这里有个坑：Claude 的 strict 参数虽然能设置，但官方文档明确说了——它会被忽略。Claude 不保证参数一定符合你定义的 Schema。

这是 Anthropic 官方文档的原话（2026 年 4 月更新）：

“The strict parameter is currently ignored for tool definitions. Claude will make a best effort to provide valid arguments, but does not guarantee schema compliance.”

翻译一下：它会尽力，但不管保。所以用 Claude 做工具调用时，一定要加 L1（参数验证）和 L2（失败重试）。

import anthropic

client = anthropic.Anthropic()

# Claude 的工具定义
tools = [{
    "name": "get_weather",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string"}
        },
        "required": ["city"]
    }
}]

response = client.messages.create(
    model="claude-3.5-sonnet",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "北京天气"}]
)

# 重要：必须手动校验 tool_use 的参数
for block in response.content:
    if block.type == "tool_use":
        # 这里要做 Pydantic 校验
        validated_params = ToolCallParams.model_validate(block.input)

Google Gemini：Controlled Generation

Gemini 的方案叫 Controlled Generation，通过 response_schema 参数指定输出结构。

import google.generativeai as genai

model = genai.GenerativeModel('gemini-1.5-pro')

response = model.generate_content(
    "提取用户信息",
    generation_config={
        "response_mime_type": "application/json",
        "response_schema": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "age": {"type": "integer"}
            },
            "required": ["name", "age"]
        }
    }
)

Gemini 的可靠性介于 OpenAI 和 Claude 之间——有约束，但没有 OpenAI 那种”强制合规”的力度。实测下来失败率大概 1-2%，比 JSON Mode 好，但达不到 Strict Mode 的水平。

开源模型：依赖 Outlines/vLLM

开源模型（如 Qwen、Llama、Mistral）本身不支持结构化输出，需要借助外部工具。主流方案就是前面提到的 Outlines 和 vLLM 的 guided_json。

这里有个有趣的点：开源模型配合 Outlines，结构化输出的可靠性反而比某些商业 API 还高——因为 FSM 是硬约束，不存在”尽力但不保证”的情况。

选择建议速查表

四、实战代码模板

这一章放几个生产级的代码模板。这些代码我都在生产环境验证过，拿去直接用就行。

模板一：OpenAI Structured Outputs 完整示例

"""
OpenAI Structured Outputs 完整示例
适用于：工具调用、数据提取、报表生成等场景
"""
from openai import OpenAI
from pydantic import BaseModel, Field
from typing import List, Optional
import json

# 1. 定义 Pydantic 模型
class SearchQuery(BaseModel):
    """搜索查询参数"""
    keywords: List[str] = Field(
        ...,
        min_length=1,
        max_length=5,
        description="搜索关键词列表"
    )
    filters: Optional[dict] = Field(
        default=None,
        description="可选的过滤条件"
    )
    limit: int = Field(
        default=10,
        ge=1,
        le=100,
        description="返回结果数量"
    )

# 2. Pydantic 模型转 JSON Schema
def model_to_schema(model: type[BaseModel]) -> dict:
    """将 Pydantic 模型转换为 JSON Schema"""
    schema = model.model_json_schema()
    # 清理 Pydantic 添加的元数据
    schema.pop("title", None)
    for prop in schema.get("properties", {}).values():
        prop.pop("title", None)
    return schema

# 3. 结构化输出调用
client = OpenAI()

def extract_search_params(user_input: str) -> SearchQuery:
    """从用户输入提取搜索参数"""
    schema = model_to_schema(SearchQuery)

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {
                "role": "system",
                "content": "你是一个搜索助手，帮助用户提取搜索参数。"
            },
            {"role": "user", "content": user_input}
        ],
        response_format={
            "type": "json_schema",
            "json_schema": {
                "name": "search_query",
                "strict": True,
                "schema": schema
            }
        },
        temperature=0.1  # 结构化输出用低温
    )

    # 4. 解析并二次校验
    raw_content = response.choices[0].message.content
    data = json.loads(raw_content)
    return SearchQuery.model_validate(data)

# 使用示例
if __name__ == "__main__":
    query = extract_search_params(
        "我想找一些关于 Python 异步编程的文章，只要最近一个月的，最多 20 条"
    )
    print(query)
    # SearchQuery(keywords=['Python', '异步编程'], filters={'date_range': 'last_month'}, limit=20)

模板二：Instructor 自动重试示例

"""
Instructor 自动重试示例
适用于：Claude API、OpenAI JSON Mode（非 Strict）、需要容错的场景
"""
import instructor
from openai import OpenAI
from pydantic import BaseModel, Field, ValidationError

class AgentAction(BaseModel):
    """Agent 行动决策"""
    action_type: str = Field(
        ...,
        pattern="^(search|execute|respond|clarify)$"
    )
    parameters: dict = Field(default_factory=dict)
    reasoning: str = Field(..., min_length=10)

# patch OpenAI client
client = instructor.patch(OpenAI())

def get_agent_decision(
    context: str,
    user_request: str,
    max_retries: int = 3
) -> AgentAction:
    """
    获取 Agent 的行动决策，带自动重试

    Args:
        context: 当前对话上下文
        user_request: 用户请求
        max_retries: 最大重试次数

    Returns:
        AgentAction: 校验后的行动决策
    """
    messages = [
        {"role": "system", "content": "你是一个智能助手，分析用户需求并决定下一步行动。"},
        {"role": "user", "content": f"上下文: {context}\n\n用户请求: {user_request}"}
    ]

    try:
        response = client.chat.completions.create(
            model="gpt-4o",
            response_model=AgentAction,  # Instructor 自动校验
            messages=messages,
            max_retries=max_retries,  # 内置重试
            temperature=0.1
        )
        return response

    except ValidationError as e:
        # Instructor 已经重试了 max_retries 次
        raise Exception(f"格式错误无法修复，请检查模型定义: {e}")

# 使用示例
decision = get_agent_decision(
    context="用户正在查询天气信息",
    user_request="帮我查北京明天的天气，要是晴天就推荐户外活动"
)
print(f"行动类型: {decision.action_type}")
print(f"参数: {decision.parameters}")
print(f"推理过程: {decision.reasoning}")

模板三：Outlines 本地模型结构化输出

"""
Outlines 本地模型结构化输出示例
适用于：私有部署、成本敏感、隐私要求高的场景
"""
from outlines import models, generate
from pydantic import BaseModel
from typing import List
import json

# 定义数据结构
class ProductInfo(BaseModel):
    """商品信息"""
    name: str
    price: float
    category: str
    tags: List[str]

# 加载模型（第一次加载会有几秒延迟）
model = models.transformers("Qwen/Qwen2.5-7B-Instruct")

# 创建结构化生成器
# 注意：schema 会在首次调用时编译为 FSM，有约 1-2 秒开销
schema_str = json.dumps(ProductInfo.model_json_schema())
generator = generate.json(model, schema_str)

def extract_product_info(description: str) -> ProductInfo:
    """
    从商品描述提取结构化信息

    Args:
        description: 商品描述文本

    Returns:
        ProductInfo: 结构化的商品信息
    """
    prompt = f"从以下商品描述中提取关键信息，以 JSON 格式返回:\n{description}"

    # 生成结果 100% 符合 Schema
    result = generator(prompt)

    # 转换为 Pydantic 模型（二次校验，确保万无一失）
    return ProductInfo.model_validate(result)

# 使用示例
description = """
这款蓝牙耳机采用最新的降噪技术，价格 299 元，
属于数码配件类，适合运动、通勤等场景使用。
"""
product = extract_product_info(description)
print(product)
# ProductInfo(name='蓝牙耳机', price=299.0, category='数码配件', tags=['运动', '通勤'])

模板四：完整工具调用流程

"""
完整的工具调用参数验证流程
包含：Schema 定义 → LLM 调用 → 参数校验 → 失败重试 → 工具执行
"""
from openai import OpenAI
from pydantic import BaseModel, Field, field_validator, ValidationError
from typing import Callable, Dict, Any
import json

# 1. 定义工具参数模型
class WeatherQueryParams(BaseModel):
    """天气查询工具参数"""
    city: str = Field(..., min_length=1, max_length=50)
    date_offset: int = Field(default=0, ge=-7, le=7, description="日期偏移，0表示今天")

    @field_validator("city")
    @classmethod
    def validate_city(cls, v: str) -> str:
        allowed = {"北京", "上海", "广州", "深圳", "杭州", "成都", "武汉"}
        if v not in allowed:
            raise ValueError(f"不支持的城市，可选: {allowed}")
        return v

# 2. 工具调用管理器
class ToolCallManager:
    """管理工具调用的完整流程"""

    def __init__(self):
        self.client = OpenAI()
        self.tools: Dict[str, Callable] = {}

    def register_tool(self, name: str, func: Callable, param_model: type[BaseModel]):
        """注册工具"""
        self.tools[name] = {
            "function": func,
            "param_model": param_model
        }

    def execute_with_retry(
        self,
        tool_name: str,
        user_request: str,
        max_retries: int = 3
    ) -> Any:
        """执行工具调用，带重试"""

        tool_config = self.tools[tool_name]
        param_model = tool_config["param_model"]
        schema = param_model.model_json_schema()

        messages = [
            {"role": "system", "content": f"提取工具 '{tool_name}' 的调用参数"},
            {"role": "user", "content": user_request}
        ]

        for attempt in range(max_retries):
            try:
                # 调用 LLM 获取参数
                response = self.client.chat.completions.create(
                    model="gpt-4o",
                    messages=messages,
                    response_format={
                        "type": "json_schema",
                        "json_schema": {
                            "name": tool_name,
                            "strict": True,
                            "schema": schema
                        }
                    },
                    temperature=0.1
                )

                # 校验参数
                params = param_model.model_validate_json(
                    response.choices[0].message.content
                )

                # 执行工具
                return tool_config["function"](params)

            except ValidationError as e:
                # 反馈错误，让 LLM 修正
                messages.append({
                    "role": "user",
                    "content": f"参数校验失败: {e}\n请修正参数格式。"
                })
                continue

        raise Exception(f"工具调用失败，重试 {max_retries} 次后仍无法通过校验")

# 3. 使用示例
def get_weather(params: WeatherQueryParams) -> str:
    """模拟天气查询"""
    # 这里是实际的 API 调用逻辑
    return f"{params.city} 未来 {params.date_offset} 天天气晴朗"

manager = ToolCallManager()
manager.register_tool("get_weather", get_weather, WeatherQueryParams)

result = manager.execute_with_retry(
    "get_weather",
    "帮我查一下北京明天的天气"
)
print(result)  # 北京未来 1 天天气晴朗

这些模板覆盖了最常见的几种场景。实际使用时，你可以根据需求组合和修改。

五、生产环境最佳实践

代码写完了，但生产环境还有一堆细节要注意。这里分享几个我踩过的坑和对应的解决方案。

KiloClaw - 企业级 OpenClaw 托管服务，赋能 AI Agent 自动化编排与智能模型路由

立即开始 →推广

Temperature 设置：别贪高

结构化输出场景，Temperature 建议设置在 0.0-0.2 之间。这个范围是 OpenAI 官方文档推荐的，实测下来也确实最稳定。

温度高有什么问题？LLM 会更”发散”，输出更随机。随机性是结构化输出的敌人——你要的是确定性，不是创意性。我之前把 Temperature 设置成 0.7，结果格式错误率飙升到 15%，后来改成 0.1，基本没再遇到问题。

重试策略：不是所有错误都要重试

重试之前，先判断错误类型：

我见过有人把所有错误都无限重试，结果一个城市名不在白名单里，LLM 猜了 10 次都没猜对，最后超时崩溃。区分错误类型，才能高效处理。

性能开销对比

选择时要权衡：追求极致稳定性，就选 Structured Outputs 或 Outlines；追求快速原型，用 Instructor 自动重试；预算有限，JSON Mode + 手动校验也能凑合用。

监控指标：三个必看

上线之后，这几个指标一定要监控：

1. 格式失败率：校验失败的请求占比。超过 1% 就要排查。
2. 平均重试次数：正常应该在 0.5-1.5 之间。超过 2 次说明模型或 Schema 有问题。
3. 平均延迟：结构化输出会比普通输出多 50-200ms，但要控制在可接受范围内。

我用 Prometheus + Grafana 做监控，每周看一次报表。有一次发现重试次数突然从 0.8 越到 2.5，排查后发现是 Schema 改了但没同步到代码——幸好监控及时发现问题。

总结

说了这么多，其实就一个核心观点：结构化输出在 2026 年已经不是什么难题了——只要用对方法。

三层架构（参数验证 + 失败重试 + 受约束解码）覆盖了从”能跑”到”稳定跑”的全部场景。选厂商的时候记住：OpenAI Strict Mode 最稳，Claude 需要自己做校验，开源模型配合 Outlines 反而可靠性很高。

代码模板都放在第四章了，拿去改改就能用。如果你刚开始做 Agent 开发，建议先从 Instructor 入手——它封装得好，自动重试、错误反馈都内置了，等你熟悉了再考虑要不要上 Outlines 做 100% 强制合规。

有问题的话，可以留言或者直接找我聊聊。这篇内容有点硬核，希望能帮你少踩几个坑。

12 分钟阅读 · 发布于: 2026年5月6日 · 修改于: 2026年5月6日

default

AI与智能