BroadRouter
开始使用

JSON 模式与 json_schema:靠得住的结构化输出

BroadNet Inference 团队 · 阅读约 4 分钟 · 发布于

JSON 模式(response_format 设为 json_object)只保证输出是合法 JSON。结构化输出(response_format 设为 json_schema)在服务商强制执行时,还保证字段和类型符合你的定义。无论哪种,都要检查 finish_reason、解析,并用 Pydantic 模型等 schema 校验。校验失败就把错误发回去重新请求,并严格限制尝试次数。

你的代码需要数据,而模型写的是文本。结构化输出弥合了这道鸿沟,但“模型返回 JSON”这句话,根据请求方式不同,可能有三种含义。本文比较 OpenAI 兼容开源模型上的几种选项,演示如何分别请求,并给出一个可以直接放进生产环境的“校验加修复”循环。

JSON 模式和 json_schema 有什么区别?

方式 请求 能保证什么
只靠提示词 “用 JSON 回复,字段为……” 什么都不保证;通常是 JSON,有时夹带额外文字
JSON 模式 response_format: {"type": "json_object"} 合法 JSON,结构不限
结构化输出 response_format: {"type": "json_schema", ...} 在强制执行时,JSON 符合你的 schema

OpenAI 的结构化输出指南说得很直接:“While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.”(译文:两者都能保证生成合法 JSON,但只有结构化输出能保证遵循 schema。)它建议尽可能使用结构化输出,而不是 JSON 模式。

在开源模型服务商那里,能否保证取决于服务器的实现方式。很多服务商使用约束解码,阻止会破坏 schema 的 token。有些接受这个字段,却不强制执行。所以下面的代码无论如何都会校验。

怎么请求 json_schema?

import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}

Pydantic 从你的类生成 JSON Schema,所以 schema 和校验器永远不会对不上。如果你不用 Pydantic,JSON schema 生成器可以从一个示例对象生成严格模式的 schema。在严格模式下,OpenAI 要求 additionalProperties: false,并且每个属性都列为必填。

你的服务商支持哪种模式?

在基于某个模型开发之前,先对它跑一次这个测试:

  1. 发送 json_schema,提示词诱导模型多加一个字段(“再加一条简短评论”)。
  2. 如果请求报错,说明服务商不接受 json_schema。改试 json_object。
  3. 如果回复里出现了多余字段,说明 schema 没有被强制执行。把它当作 JSON 模式对待。
  4. 如果 json_object 也报错,就只靠提示词,再加校验。

在 BroadNet Inference 上,文档为 GLM 5.3 和 Qwen3.8 27B 列出了结构化输出(两者对比),但没有写明请求参数名。请在你要上线的模型上跑一遍上面的测试。

怎么校验和修复错误输出?

import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")

这个循环能起作用的原因:

  • **先检查 finish_reason。**触及 max_tokens 的回复是被截断的 JSON。用同样的上限重试,结果也一样。上面两个模型都会先思考再回答,而思考计入上限,所以要留足余量。
  • **单独处理拒绝回答。**OpenAI 的指南指出,拒绝回答 “does not necessarily follow the schema you have supplied”(译文:不一定遵循你提供的 schema)。
  • **把确切的错误发回去。**盲目重试往往会得到同样的错误。“line_items: field required”这样的信息才能让模型知道该改什么。
  • **在代码里检查业务规则。**schema 无法表达“合计必须等于各行金额之和”,上面的检查可以。
  • **限制尝试次数。**每次尝试都会把整个提示词作为输入 token 重新发送一遍。

哪些 schema 特性容易出问题?

让 schema 保持朴素:

  1. **扁平胜过嵌套。**大多数提取任务两层就够了。
  2. 类别用枚举,而不是自由字符串。
  3. **不要开放式对象。**自由格式的 dict 字段违背了初衷。
  4. **字段名简短,并附描述。**schema 中的描述会引导模型。
  5. **可选字段设为可为 null。**在严格模式下,把每个字段都列为必填,并允许 null。

OpenAI 的指南指出,部分 JSON Schema 特性在严格模式下不受支持。开源模型的服务器也有自己的限制。如果 schema 被拒绝,先简化它,再考虑换模式。

在生产环境中怎么监控结构化输出?

一个默默修复的循环,可能掩盖一个每天都在消耗 token 的问题。每个调用点记录三个数字:

指标 说明什么
首次成功率 模型和 schema 的契合程度;下降往往出现在提示词或模型变更之后
每次成功的平均尝试次数 修复的 token 成本
最终失败数 流水线处理不了的输入;请人工逐一检查

如果首次成功率低于平时水平,先简化 schema 或换个模型试试,再考虑增加重试。保留一部分失败的原始回复样本,以便用真实案例测试修复方案。

什么时候应该改用工具?

最终答案用结构化输出:提取、分类、计划。模型需要你的代码去做某件事然后继续时,用工具调用。许多智能体两者都用:循环中用工具,最后一步用 schema。图像转 JSON 的示例请看用视觉模型读取阿拉伯语发票。

BroadNet Inference 适合什么场景

BroadNet Inference 为 GLM 5.3 和 Qwen3.8 27B 列出了结构化输出,采用标准的 chat completions 格式,所以上面的代码无需修改就能用 OpenAI Python SDK 运行。Qwen3.8 27B 还能接收图像,适合文档提取。BroadNet 的文档没有说明 DeepSeek V4.1 Flash 或 Gemma 4 VL 26B 支持结构化输出,所以在这两个模型上请走“只靠提示词加校验”的路线。按 token 的价格可以在价格页面上比较。

常见问题

JSON 模式和结构化输出有什么区别?

JSON 模式(response_format 的 type 为 json_object)只保证回复能被解析为 JSON。结构化输出(type 为 json_schema)在服务商强制执行时,还保证字段和类型符合你的定义。OpenAI 建议尽可能使用结构化输出而不是 JSON 模式。

开源模型支持 json_schema 这种 response_format 吗?

取决于服务商。有的接受 json_schema,有的只接受 json_object,有的直接忽略这个字段。发一个带 schema 的测试请求,提示词故意诱导模型多加一个字段,再检查回复。

用了结构化输出,还需要校验吗?

需要。回复可能被 max_tokens 截断,可能是拒绝回答,也可能违反 schema 无法表达的业务规则,比如合计必须等于各项之和。

JSON 不合法时应该重试几次?

带上校验错误重试两到三次通常就够了。之后把输入记录下来,转给备用方案、更强的模型或人工处理。无上限的循环只会浪费 token。

该用结构化输出还是工具调用?

想让最终答案采用固定结构时,用结构化输出。模型需要你的代码先做某件事再继续时,用工具调用。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity