你的代码需要数据,而模型写的是文本。结构化输出弥合了这道鸿沟,但“模型返回 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,并且每个属性都列为必填。
你的服务商支持哪种模式?
在基于某个模型开发之前,先对它跑一次这个测试:
- 发送
json_schema,提示词诱导模型多加一个字段(“再加一条简短评论”)。 - 如果请求报错,说明服务商不接受
json_schema。改试json_object。 - 如果回复里出现了多余字段,说明 schema 没有被强制执行。把它当作 JSON 模式对待。
- 如果
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 保持朴素:
- **扁平胜过嵌套。**大多数提取任务两层就够了。
- 类别用枚举,而不是自由字符串。
- **不要开放式对象。**自由格式的
dict字段违背了初衷。 - **字段名简短,并附描述。**schema 中的描述会引导模型。
- **可选字段设为可为 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 的价格可以在价格页面上比较。
