---
title: "JSON 模式与 JSON Schema 结构化输出（附代码） | BroadRouter"
description: "JSON 模式保证合法 JSON，json_schema 保证你要的结构。讲解如何在 OpenAI 兼容模型上分别请求、用 Pydantic 校验，并用循环修复错误输出。"
url: https://broadrouter.com/zh/blog/structured-output-json-schema/
lang: zh-Hans
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。[阅读英文原文](https://broadrouter.com/blog/structured-output-json-schema/)（2026-11-14 更新）。

# JSON 模式与 json\_schema：靠得住的结构化输出

BroadNet Inference 团队 · 阅读约 4 分钟 · 发布于 2026-11-14

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

## 要点

-   OpenAI 的指南：两种模式都能生成合法 JSON，但 "only Structured Outputs ensure schema adherence"（译文：只有结构化输出能保证遵循 schema）。
-   各家 OpenAI 兼容服务商的支持程度不一。先测试 json\_schema，不行退回 json\_object，再不行就只靠提示词。
-   每个回复都要校验。被 max\_tokens 截断的回复是残缺的 JSON，不管 schema 怎么写。
-   把确切的校验错误发回去，修复循环才有效。最多两到三次。
-   在 BroadNet Inference 上，GLM 5.3 和 Qwen3.8 27B 列明支持结构化输出。

**本页内容**

1.  JSON 模式和 json\_schema 有什么区别？
2.  怎么请求 json\_schema？
3.  你的服务商支持哪种模式？
4.  怎么校验和修复错误输出？
5.  哪些 schema 特性容易出问题？
6.  在生产环境中怎么监控结构化输出？
7.  什么时候应该改用工具？
8.  BroadNet Inference 适合什么场景

你的代码需要数据，而模型写的是文本。[结构化输出](https://broadrouter.com/zh/glossary/structured-output/)弥合了这道鸿沟，但“模型返回 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？

```python
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 生成器](https://broadrouter.com/tools/json-schema-generator/)可以从一个示例对象生成严格模式的 schema。在严格模式下，OpenAI 要求 `additionalProperties: false`，并且每个属性都列为必填。

## 你的服务商支持哪种模式？

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

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

在 BroadNet Inference 上，文档为 [GLM 5.3](https://broadrouter.com/zh/models/glm-5.3/) 和 [Qwen3.8 27B](https://broadrouter.com/zh/models/qwen3.8-27b/) 列出了结构化输出（[两者对比](https://broadrouter.com/compare/glm-5.3-vs-qwen3.8-27b/)），但没有写明请求参数名。请在你要上线的模型上跑一遍上面的测试。

## 怎么校验和修复错误输出？

```python
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`](https://broadrouter.com/zh/glossary/max-tokens/) 的回复是被截断的 JSON。用同样的上限重试，结果也一样。上面两个模型都会先思考再回答，而[思考计入上限](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)，所以要留足余量。
-   \*\*单独处理拒绝回答。\*\*OpenAI 的指南指出，拒绝回答 “does not necessarily follow the schema you have supplied”（译文：不一定遵循你提供的 schema）。
-   \*\*把确切的错误发回去。\*\*盲目重试往往会得到同样的错误。“line\_items: field required”这样的信息才能让模型知道该改什么。
-   \*\*在代码里检查业务规则。\*\*schema 无法表达“合计必须等于各行金额之和”，上面的检查可以。
-   \*\*限制尝试次数。\*\*每次尝试都会把整个提示词作为[输入 token](https://broadrouter.com/zh/glossary/input-and-output-tokens/) 重新发送一遍。

## 哪些 schema 特性容易出问题？

让 schema 保持朴素：

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

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

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

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

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

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

## 什么时候应该改用工具？

**最终答案**用结构化输出：提取、分类、计划。模型需要你的代码去**做**某件事然后继续时，用[工具调用](https://broadrouter.com/zh/blog/tool-calling-open-models/)。许多智能体两者都用：循环中用工具，最后一步用 schema。图像转 JSON 的示例请看[用视觉模型读取阿拉伯语发票](https://broadrouter.com/zh/guides/read-arabic-invoices-with-vision/)。

## BroadNet Inference 适合什么场景

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

相关免费工具（英文）

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[免费工具（英文）](https://broadrouter.com/tools/)

## 本文涉及的术语

[结构化输出（structured output）](https://broadrouter.com/zh/glossary/structured-output/)

结构化输出是大模型 API 的一项功能，它把模型的回复约束为开发者指定的格式（通常是 JSON Schema），让代码能可靠地解析。它比 JSON mode 更严格：JSON mode 只保证输出是合法 JSON，不保证特定结构。

[JSON Schema](https://broadrouter.com/zh/glossary/json-schema/)

JSON Schema 是一套用 JSON 编写的词汇，用于描述和校验 JSON 数据的结构：类型、必填字段、允许的取值和嵌套。当前版本是 2020-12。大模型 API 用它来定义工具参数，以及结构化输出必须遵循的确切结构。

[Token（词元）](https://broadrouter.com/zh/glossary/token/)

token（词元）是大语言模型读写文本的基本单位：由模型的分词器切分出的一个词、词的一部分、一个标点或一段字节序列。大模型 API 按 token 计数、设定限制，通常也按 token 计费。

[开放权重模型（open-weight model）](https://broadrouter.com/zh/glossary/open-weight-model/)

开放权重模型是公开发布训练好的权重、任何人都可以下载和运行的机器学习模型，通常附带有条件的许可证。它不同于完全开源的 AI，后者还会公开训练代码和训练数据的详细信息，让其他人能够研究并复现模型。

[多智能体系统（multi-agent system）](https://broadrouter.com/zh/glossary/multi-agent-system/)

多智能体系统是一种大模型应用：多个智能体各自拥有提示词、工具和上下文，分别处理同一任务的不同部分。常见设计是编排者-工作者模式：主智能体负责规划，并行启动多个工作智能体，再汇总它们的结果。

[工具调用（tool calling / function calling）](https://broadrouter.com/zh/glossary/tool-calling/)

工具调用（也叫函数调用，function calling）是大模型 API 的一项功能：模型返回一个结构化请求，要求执行开发者定义的某个函数，并附上 JSON 参数。应用执行该函数并把结果发回；模型自己从不执行代码。

[输入 token 与输出 token](https://broadrouter.com/zh/glossary/input-and-output-tokens/)

输入 token 是语言模型在一次请求中读取的 token，包括系统提示词、对话历史、工具定义和图片。输出 token 是模型生成回复的 token，包括思考内容。大模型 API 通常分别计价，输出一般更贵。

[AI 智能体（AI agent）](https://broadrouter.com/zh/glossary/agent/)

AI 智能体是由语言模型自主决定步骤、朝目标推进的系统：它决定调用哪些工具、读取结果，然后重复，直到给出最终回答或触及上限。在固定位置调用模型的固定脚本，通常称为工作流（workflow）。

## 常见问题

### 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。

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

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

## 继续阅读

-   [用大模型做阿拉伯语文本分类：情感、意图与工单分派](https://broadrouter.com/zh/blog/arabic-text-classification-llm/)
-   [开源模型的工具调用：schema、并行调用与重试](https://broadrouter.com/zh/blog/tool-calling-open-models/)
-   [迁移到 OpenAI 兼容 API：切换服务商检查清单](https://broadrouter.com/zh/blog/openai-compatible-api-migration-checklist/)
-   [n8n AI Agent 接入低价大模型：配置、模型选择与单次运行成本](https://broadrouter.com/zh/blog/n8n-ai-agent-cheap-llm/)
-   [大模型返回的 JSON 不合法怎么办：原因、修复与重试](https://broadrouter.com/zh/blog/fix-invalid-json-from-llm/)
-   [用大模型做阿拉伯语命名实体抽取：JSON、日期与校验](https://broadrouter.com/zh/blog/arabic-named-entity-extraction-llm/)
-   [BroadNet 的 GPU 硬件与推理部署方式（据 BroadNet 自述）](https://broadrouter.com/zh/blog/broadnet-gpu-fleet-and-serving/)
-   [缓存大模型 API 响应以降低成本：用 Python 实现精确匹配缓存](https://broadrouter.com/zh/blog/cache-llm-responses-cut-cost/)
-   [指南：用 OpenAI Python SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/openai-python-sdk/)
-   [指南：用视觉模型识别阿拉伯语发票和收据](https://broadrouter.com/zh/guides/read-arabic-invoices-with-vision/)
-   [指南：推理模型为什么返回空回答](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)

用你的真实业务负载试一试。新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-structured-output-json-schema&utm_content=page-cta) ·

**来源**

-   [OpenAI 结构化输出指南（2026-11-14 查阅）](https://developers.openai.com/api/docs/guides/structured-outputs)
-   [OpenAI API 参考：创建 chat completion（response\_format）](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
-   [Pydantic 文档：JSON Schema 与校验](https://docs.pydantic.dev/latest/concepts/json_schema/)
-   [BroadNet Inference API 参考：模型（英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-structured-output-json-schema&utm_content=sources#models)
