BroadRouter
开始使用

结构化输出(structured output)

更新于

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

又称: 结构化输出、JSON Schema 输出、JSON 结构化输出、Structured Outputs、structured output、JSON schema output、response_format

代码需要可预测的输入。结构化输出把模型的自由文本变成程序可以信赖的数据。

原理

控制程度分三级:

方法 你得到的结果
在提示词里要求 通常是 JSON,有时夹带多余文字或缺少字段
JSON mode 合法的 JSON,结构不限
带 Schema 的结构化输出 符合你的 Schema 的 JSON

在 OpenAI 格式中,JSON mode 是 response_format: {"type": "json_object"}。结构化输出则传入一个 Schema:

"response_format": {
  "type": "json_schema",
  "json_schema": {
    "name": "invoice",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "vendor": { "type": "string" },
        "total": { "type": "number" }
      },
      "required": ["vendor", "total"],
      "additionalProperties": false
    }
  }
}

OpenAI 的参考文档说,json_schema 类型 “ensures the model will match your supplied JSON schema”(译文:确保模型输出符合你提供的 JSON Schema)。许多服务商通过约束解码实现这一点:在每一步限制模型可以生成哪些 token,使违反 Schema 的输出根本无法生成。

为什么重要

  • 更少的解析错误。 信息抽取流水线、分类器和智能体可以直接读取字段。
  • 更简单的提示词。 Schema 取代了冗长的格式说明。
  • 并非完全保证。 OpenAI 的指南说,你的应用仍应处理拒答、不完整的响应和错误。被 max_tokens 截断的回复,无论 Schema 怎么写,都是残缺的 JSON。

各家 OpenAI 兼容 API 的支持程度不一。有的只接受 json_schema,有的只接受 json_object,有的会忽略这个字段。依赖它之前请先确认。

在 BroadNet Inference 上

BroadNet 的文档为 GLM 5.3 和 Qwen3.8 27B 列出了结构化输出。文档没有写明请求参数的名称,所以请在你的模型上测试 response_format,并且无论如何都保留一个带错误处理的 JSON 解析器。LLM JSON 输出校验工具可以指出回复在哪里出错,并按你的 Schema 进行检查。这两个模型都会先思考,所以 max_tokens 要给思考和 JSON 都留出空间。

结构化输出和视觉模型很搭。阿拉伯语发票指南发送一张图片,要求以 JSON 返回各字段。如果要的是执行操作而不是回答,请使用工具调用。

常见错误

  • 使用 strict 模式时,忘了设置 additionalProperties: false,或者没有把每个字段都列进 required。
  • 解析前没有检查 finish_reason。

常见问题

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

JSON mode 只保证回复能被解析为 JSON。带 Schema 的结构化输出还保证你定义的字段、类型和必填键。OpenAI 的指南说,只有 Structured Outputs 能确保遵循 Schema。

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

需要。回复仍可能是拒答,或被 max_tokens 截断;Schema 也无法表达所有业务规则,比如总额必须等于各明细行之和。

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

想让最终回答采用固定格式时,用结构化输出。想让模型请求你的代码执行某个操作、然后继续时,用工具调用。

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