推理API如何用JSON Mode与Structured Outputs保证输出格式合规？

推理API接入业务系统时，让模型返回JSON是最常见的结构化需求之一。可是原生文本生成并不天然保证JSON合法性，实际调用经常出现多余说明、尾随逗号、字段类型错误甚至整段不是JSON的情况。要解决这个问题，不能只靠提示词里反复强调，而要理解推理服务端提供的JSON Mode和Structured Outputs两种约束机制，它们分别在不同层面确保输出格式合规。

一、推理输出JSON为什么会经常翻车

大语言模型在推理阶段本质上是逐token采样，它并不是先把整段JSON在内部生成好再一次性输出。模型从训练数据中学到了JSON的统计分布，比如花括号后面通常跟字符串、冒号后面可能有值，但这种学习是概率性的，缺少全局语法状态。当temperature设置偏高，或者任务要求嵌套对象、数组时，模型很可能在开头先说一句“好的，这是结果：”，也可能在对象还没闭合时提前结束，或给数组加了一个不该出现的尾随逗号。

下面这段输出就是很典型的坏样例：

这是提取结果：
{
  "name": "张三",
  "age": 28,
  "city": "北京",
}

上述文本无法被json.loads解析，原因包括前缀中文说明以及对象最后一个字段后多了逗号。实际场景里还会出现键名拼错、数字被引号包裹、布尔值写成字符串、嵌套层级缺少闭合符号等问题。

传统做法通常是在客户端做正则提取、清洗说明文字、重试请求，或者在提示词中加入“只输出JSON，不要解释”这样的强指令。这些手段能缓解一部分问题，但无法消除根因，因为模型每一步仍然可以自由选择任何token，只要概率高就可能破坏语法。尤其当输出长度较长、结构复杂时，单次生成越靠后的位置，越容易出现累积误差。这正是JSON Mode和Structured Outputs出现的原因。

二、JSON Mode与Structured Outputs分别解决什么问题

JSON Mode可以理解为语法级约束。服务端在解码过程中维护一个JSON语法状态机，当前缀已经出现{但还没出现}时，状态机只允许生成继续合法JSON的token，比如字符串、数字、逗号、右花括号等，而不会生成说明文字。这样最终输出的整段内容一定是一个合法JSON值，但它不会帮你限定字段名必须叫name，也不会强制age必须是数字。以OpenAI兼容接口为例，开启JSON Mode的代码如下：

import openai

client = openai.OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "请只输出JSON，不要输出其他内容。"},
        {"role": "user", "content": "提取文本中的姓名和年龄。"}
    ],
    response_format={"type": "json_object"}
)

print(response.choices[0].message.content)

可以看到，调用方只是把response_format指定为json_object。服务端会尽量输出一个完整的JSON对象。不过，如果业务下游需要精确字段结构，仅仅拿到合法JSON还不够，还需要进一步约束。

Structured Outputs则是模式级约束。它允许你传入JSON Schema，服务端据此生成符合模式的输出。字段类型、必填项、枚举值、是否允许额外属性，都能在schema中定义。生成时服务端会把JSON Schema编译成约束解码规则，从网络输出的token序列直接受模式控制。继续用OpenAI兼容接口演示：

import openai

client = openai.OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "提取用户信息。"},
        {"role": "user", "content": "张三，28岁，住在北京。"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "user_extraction",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "city": {"type": "string"}
                },
                "required": ["name", "age", "city"],
                "additionalProperties": False
            }
        }
    }
)

print(response.choices[0].message.content)

这段代码不仅要求返回JSON，还要求对象必须包含name、age、city三个字段，且age必须是整数，额外的字段不允许出现。如果模型原计划生成username或age带引号，服务端会在解码阶段直接屏蔽这些不符合schema的token。

从实现层看，JSON Mode和Structured Outputs经常共享底层技术，常见名称包括约束解码、语法掩码、guided decoding等。JSON Mode只需要维护JSON语法，Structured Outputs则需要维护JSON Schema对应的规则。不同服务商命名有所不同，例如Anthropic通过工具调用实现结构输出，Gemini使用response_mime_type配合response_schema，vLLM和llama.cpp等推理框架则支持guided_json参数。自建推理服务时，也可以使用outlines、lm-format-enforcer、guidance等库实现类似能力。

三、从零配置一次合规的推理调用

实际接入时，建议把业务结构定义成Pydantic模型，让它作为单一数据源。Pydantic既能校验客户端拿到的数据，也能通过model_json_schema生成服务端需要的JSON Schema，避免手写schema出现字段不一致。下面是定义和校验示例：

from pydantic import BaseModel, Field

class UserInfo(BaseModel):
    name: str
    age: int = Field(ge=0, le=150)
    city: str

payload = {
    "name": "张三",
    "age": 28,
    "city": "北京"
}

user = UserInfo.model_validate(payload)
print(user.model_dump())

把UserInfo.model_json_schema()返回的字典传给推理API，即可让服务端按相同结构约束输出。请求完成后，即使服务端声称已经开启Structured Outputs，仍然建议在客户端用jsonschema库做一次防御性校验，因为实际系统中可能存在代理改写、旧版本服务端、模型切换等情况。

import json
import jsonschema

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"},
        "city": {"type": "string"}
    },
    "required": ["name", "age", "city"]
}

raw = response.choices[0].message.content
data = json.loads(raw)
jsonschema.validate(instance=data, schema=schema)
print("校验通过")

这种做法可以覆盖两类风险：一类是服务端没有真正提供结构化约束，只是像普通JSON Mode那样保证语法；另一类是约束实现不完整，例如复杂oneOf、anyOf、递归引用没有被支持。即便使用Structured Outputs，也建议把strict模式打开，并要求必填字段，不要依赖默认值补全。

参数层面，开启结构化输出后通常可以适当降低temperature，因为服务端可能为了保持约束而忽略一些随机性配置。不同推理API对temperature、top_p的兼容行为不完全一致。对于不支持Structured Outputs的旧接口，可以先使用JSON Mode，再用Pydantic或jsonschema做二次校验；如果JSON Mode也不可用，则只能退回到提示词约束加重试解析，但不要把它当作可靠方案。

四、常见误区与性能取舍

第一个误区是认为JSON Mode等于Structured Outputs。实际上，JSON Mode只承诺“输出是合法JSON”，不承诺结构。比如你需要提取姓名和年龄，JSON Mode完全可能返回{"username":"张三","years":28}，这对JSON语法来说没有问题，但下游反序列化到强类型对象时会直接失败。第二个误区是认为服务端约束可以完全替代客户端校验，任何推理服务都可能存在特定版本限制或偶发退化为普通输出，客户端校验仍是最后一道防线。第三个误区是忽视性能成本。约束解码需要统计可选token范围，复杂JSON Schema可能显著增加首token延迟并降低吞吐，尤其是在长输出、深层嵌套或包含枚举值很多的情况下。

下面用表格对比三种输出控制方式：

选择哪种方式，取决于下游对数据结构的敏感程度。如果只是把模型输出存进数据库，后续人工或脚本自行解析，JSON Mode通常足够；如果需要直接把结果反序列化成DTO、调用下一跳服务、写入强类型消息队列，Structured Outputs是更稳妥的选择。对于自建推理服务，可以先在小规模流量上对比开启guided_json前后的延迟和成功率，再决定是否全量启用。

总结来说，JSON Mode解决了“返回像JSON”的问题，Structured Outputs解决了“返回正好是这份JSON”的问题。两者不是完全替代关系，更多是分层保障：输出合法性由服务端负责，业务正确性由schema和客户端校验共同负责。把这两层约束接入推理API调用链路后，下游出错的概率会明显下降，也能减少大量防御性解析代码。

JSON ModeStructured Outputs推理API输出校验修改时间：2026-10-01 22:26:50