什么是 JSON 模式（JSON Mode）？
JSON 模式（JSON Mode）是供应商特定的大模型输出设置，使正常完成的响应成为语法有效的 JSON，但不保证符合指定 Schema，也不保证事实准确、操作已授权或业务有效。
快速了解
| 规范文档 | 官方规范 |
|---|
工作原理
JSON 模式是部分模型 API 与推理 Runtime 提供的输出契约，不是统一协议，也没有跨供应商标准参数。在 OpenAI 风格 API 中，json_object 请求 JSON 响应；Ollama 使用 format: "json"，并可传入 Schema 对象获得更严格的输出。Google Gemini 将 application/json Response MIME Type 与 Response JSON Schema 结合，Anthropic 则通过 output_config.format 提供 Schema-constrained Output；两者都不沿用 OpenAI 的参数名。支持范围会随 Model、Endpoint、API Version、SDK、部署平台和 Streaming Path 改变，声称兼容 OpenAI API 也不能证明行为完全等价。
理解 JSON 模式时应区分四层保证。只在 Prompt 中要求「返回 JSON」属于可被模型违背的指令；JSON Mode 把语法合法性纳入供应商或 Runtime 契约，因此正常完成的响应应可被 JSON Parser 解析，但 {}、意外数组、错误字段名、错误类型、虚构值和危险字符串仍可能是合法 JSON；Strict Structured Output 进一步约束受支持的 JSON Schema 子集；应用校验再负责领域、不变量、证据与权限。JSON Schema 描述数据契约，Constrained Decoding 是一种可能的执行机制，两者都不是 JSON Mode 的同义词。Function Calling 的目标则是提出具名操作及参数，参数是否严格遵循 Schema 还要看独立配置。
语法保证依赖请求正常结束。请求在生成前被拒绝、Safety Refusal、Content Filtering、输出 Token 耗尽、Context 耗尽、Timeout、Transport 中断或供应商降级，都可能产生无 JSON、带外结果或不完整文档。OpenAI 与 Azure 的 json_object 还要求消息中明确出现 JSON 指令，否则请求可能报错，或生成空白直到耗尽预算；这是特定接口契约，不是 JSON 标准要求。流式响应中的 Chunk 只是片段，必须由 SDK 或客户端完整组装，等待 Terminal Event 并检查 Status 或 Finish Reason 后才能解析。
生产消费链路应按顺序设置门禁：先检查 HTTP 与供应商状态，再选择文档约定的 Content Field；限制 Byte、Depth 与 Collection Size；使用标准 JSON Parser 解析；按应用拥有且带版本的 Schema 校验；检查领域规则、证据、新鲜度与 Authorization；最后才允许产生副作用。RFC 8259 还允许一些解析器处理不一致的边界，例如重复对象成员和超出常见互操作精度的数字，因此安全敏感入口可能需要更严格的重复 Key 与数值策略。JSON Mode 后追加 Validator 可以捕获形状错误，但不会把生成过程追溯性地变成 Schema-constrained Generation。
Strict Structured Output 更强，但仍不保证真实或安全。供应商支持的 JSON Schema 子集各不相同，可能拒绝、简化或转换不支持的 Keyword。Schema-valid 对象仍可包含虚构事实、危险 URL、过期标识符、未授权操作或携带 Injection 内容的字符串。应用 Schema 应作为单一事实源，并针对准确 Backend 进行兼容测试；缺失证据应通过 Nullable Field 或显式 Status 表达；语义与授权规则必须由确定性代码执行。
重试必须有明确 Policy。分别归类 Transport、Incomplete Generation、Parse、Schema 和 Semantic Failure；限制尝试次数并使用 Backoff 与 Jitter；永久 Schema 或 Policy Error 不应盲目重试；跨尝试保留 Trace 与 Idempotency Key。在整个响应通过验收前，不得调用 Tool、扣款、写数据库或发送消息。Repair Prompt 只是另一次概率性模型调用，不是校验器；若原请求已产生效果，还可能放大成本或造成重复副作用。
解析后的每个值仍是不可信输入。不得把字段直接传给 eval、Shell、SQL、Template、File Path、URL 或 Tool Dispatcher；需要 Allowlist、Escaping、长度限制、Destination Control、Least Privilege，并在高影响操作前要求 Human Approval。日志应脱敏 Credential、个人数据、Prompt 和原始 Payload。可观测性至少记录 Provider、Endpoint/API Revision、不可变 Model Identity、请求的输出模式、Prompt/Template Revision、预期 Schema Revision、Terminal Reason、Parse/Schema/Business-rule 结果、Retry Count、Latency、Token Use 与最终 Effect Status。
当输出形状本来就动态，或目标模型不支持 Strict Schema 且应用层可承担验证时，可以使用 JSON Mode。下游代码要求固定结构时优先 Strict Structured Output；模型需要提出操作时使用 Function Calling；结果主要给人阅读时使用普通文本。维护经过实测的 Capability Matrix，并在 Schema Enforcement 不可用时 Fail Closed，不能静默降级为只保证语法的 JSON。
主要特点
- 供应商级契约：参数名、支持模型、Endpoint、Schema 行为与 Streaming 语义不能仅凭名称跨平台复用
- 语法级保证：正常完成的响应可解析为 JSON，但 Root Shape、字段、类型、值与含义仍可能错误
- 依赖完成状态：Refusal、Filtering、Truncation、Timeout、Transport Failure 与 Fallback 是独立结果
- 不同于 Strict Schema：Structured Output 可执行受支持的 JSON Schema 子集，JSON Mode 本身不能
- 整包解析：流式 Fragment 必须完成组装并检查 Terminal Status 后才能解析与校验
- 应用负责验收：Schema、领域、证据、授权、安全、Idempotency 与可观测性都不由该模式代替
常见用途
- 兼容回退：目标 Model 或 Endpoint 不支持所需 Strict Schema 时获取可解析 JSON
- 探索式抽取：对象形状仍在演进，但应用校验与失败观测已经建立
- 开放 JSON Map：返回无法由固定供应商 Schema 子集表达的动态 Key 或异构 Metadata
- 供应商适配：在显式 Capability 与 Downgrade Policy 后统一不同 JSON 输出参数
- 可靠性评测：分别统计 Completion、Parse、Schema、Semantic、Retry、Latency 与 Duplicate Effect
示例
Loading code...常见问题
JSON 模式一定能保证返回合法 JSON 吗？
只有在供应商文档规定的契约内，并且生成正常完成时才能这样判断。请求拒绝、Safety Refusal、Content Filter、Token 上限截断、Timeout、Stream 中断或不受支持的 Fallback，都可能返回无 JSON、不完整 JSON 或独立结果。解析前必须检查 Terminal Status 或 Finish Reason，并测试准确 Model、Endpoint、API Version、SDK 与 Streaming Path。
JSON 模式与 Strict Structured Output 有什么区别？
JSON Mode 只保证语法，因此即使字段名或类型错误，任意允许的 JSON Object 也可能通过。Strict Structured Output 会把正常完成的响应限制到供应商支持的 JSON Schema 子集。两者都不保证事实、授权、安全或业务有效性，应用仍需校验。
JSON 模式与 Function Calling 是一回事吗？
不是。JSON Mode 控制模型响应的表示形式；Function Calling 或 Tool Use 表示对具名能力的调用提议，还需要 Dispatch、Authorization、Execution 与 Result Handling。部分供应商会对 Tool Argument 应用 JSON 或 Strict Schema 约束，但这不会让两种能力等价。
JSON 模式可以跨大模型供应商直接移植吗？
不能。没有共同标准规定它的请求字段或保证等级。OpenAI 风格 API 使用 `json_object`，Ollama 使用 `format: "json"`，其他供应商以不同名称提供偏 Schema 的控制。即使 Endpoint 声称兼容，也可能在 Model、API Revision、Prompt 要求、Streaming 和 Fallback 上不同，因此必须维护实测 Capability Matrix。
生产代码应如何校验 JSON Mode 输出？
先要求 Terminal Status 成功，再限制大小、使用标准 Parser 解析、按应用拥有的版本化 Schema 校验、检查领域规则与证据，并在授权后才提交副作用。Retry 必须有上限并保持 Idempotency；危险值需要拒绝或转义；Parse、Schema、Semantic 与 Effect 结果应分别记录。