返回专栏
· 22 分钟阅读

结构化输出与 JSON Schema:让大模型生成可靠、可校验的数据


一、什么是结构化输出?

结构化输出(Structured Output)是指要求大语言模型按照预先定义的数据结构生成结果,而不是自由生成任意格式的自然语言。

传统大模型主要以文本形式返回结果:

用户张三,年龄 28 岁,来自上海,目前是一名后端工程师。

这种形式适合阅读,但对于程序而言,存在解析困难:

  • 用户名称和年龄需要从文本中提取。
  • 字段顺序可能变化。
  • 描述方式可能不一致。
  • 可能出现额外解释文字。
  • 某些字段可能缺失。
  • 数值可能被输出为字符串。

如果要求模型返回 JSON:

{
  "name": "张三",
  "age": 28,
  "city": "上海",
  "occupation": "后端工程师"
}

程序就可以通过 JSON Parser 解析数据,并根据字段名称访问对应内容。

结构化输出的核心价值是:

  • 格式稳定:响应遵循约定的数据结构。
  • 类型明确:区分字符串、数字、布尔值、数组和对象。
  • 便于校验:可以检查字段是否存在、类型是否正确。
  • 易于集成:能够直接对接数据库、业务 API 和工作流。
  • 降低解析成本:减少依赖正则表达式和文本清洗的情况。

需要注意,结构化输出主要解决数据格式和结构约束问题,并不自动保证模型提供的事实正确,也不保证业务逻辑成立。

二、为什么大模型需要结构化输出?

大语言模型的原生输出是 Token 序列。

模型通常根据上下文预测下一个 Token,最终生成一段文本。它并不会天然按照某个业务系统的数据库字段或接口定义返回数据。

2.1 自由文本输出的问题

假设需要从用户输入中提取姓名、年龄和邮箱。

用户输入:

我叫李明,今年 30 岁,邮箱是 liming@example.com。

模型可能返回:

姓名:李明
年龄:30
邮箱:liming@example.com

也可能返回:

{
  "姓名": "李明",
  "年龄": "30",
  "邮箱地址": "liming@example.com"
}

还可能返回:

提取结果如下:

{
  "name": "李明",
  "age": 30,
  "email": "liming@example.com"
}

这些内容在人类看来表达的是相同信息,但对于程序而言,字段名称、数据类型和响应结构并不统一。

常见问题包括:

问题 表现 工程影响
字段不稳定 name、姓名、username 混用 字段映射复杂
类型不一致 年龄有时是数字,有时是字符串 类型转换和校验
字段缺失 某些字段没有返回 空值处理
格式错误 JSON 括号或引号不合法 解析失败
额外文本 JSON 前后包含解释文字 解析边界不明确
结构变化 数组变成对象或字段层级变化 下游程序异常

在生产系统中,这些问题可能导致 API 调用失败、数据入库异常或工作流中断。

2.2 结构化输出的解决方式

结构化输出通过预先定义的数据结构,让模型按照明确的字段和类型生成响应。

例如:

{
  "name": "李明",
  "age": 30,
  "email": "liming@example.com"
}

应用程序可以直接解析:

import json

response = '''
{
    "name": "李明",
    "age": 30,
    "email": "liming@example.com"
}
'''

data = json.loads(response)

print(data["name"])
print(data["age"])
print(data["email"])

输出:

李明
30
liming@example.com

结构化输出让大模型从单纯的文本生成组件,进一步成为可以参与软件系统数据处理的组件。

三、JSON 是什么?

JSON(JavaScript Object Notation)是一种轻量级的数据交换格式。

虽然 JSON 的名称来源于 JavaScript,但它是一种独立的数据格式,可以被 Python、Java、Go、Rust、C# 等主流编程语言解析。

JSON 主要用于:

  • API 请求和响应。
  • 配置文件。
  • 数据交换。
  • 数据持久化。
  • 大模型结构化响应。
  • 工具调用参数。

3.1 JSON 的基本数据类型

JSON 定义了六类数据类型。

类型 说明 示例
String 字符串 "hello"
Number 数字 18、3.14
Boolean 布尔值 true、false
Null 空值 null
Object 对象 {"name":"张三"}
Array 数组 ["Python","Go"]

需要注意,JSON 的 Number 不区分整数和浮点数这两个独立类型,但具体编程语言在解析时可能映射为不同数值类型。

3.2 JSON Object

Object 是由键值对组成的数据结构。

{
  "id": 1001,
  "name": "张三",
  "active": true
}

其中:

  • id 是字段名称。
  • 1001 是字段值。
  • name 是字段名称。
  • "张三" 是字段值。
  • active 是布尔字段。

JSON Object 使用花括号 {} 表示。

3.3 JSON Array

Array 用于表示有序的数据集合。

{
  "skills": [
    "Python",
    "Java",
    "Go"
  ]
}

数组中的元素可以是字符串、数字、布尔值、对象或其他数组。

例如:

{
  "users": [
    {
      "id": 1,
      "name": "张三"
    },
    {
      "id": 2,
      "name": "李四"
    }
  ]
}

这种结构非常适合表示列表型业务数据。

3.4 JSON 的语法规则

JSON 对格式有严格要求:

  1. 对象使用 {}。
  2. 数组使用 []。
  3. 字符串必须使用双引号。
  4. 字段名称必须是字符串。
  5. 字段和值之间使用冒号。
  6. 多个字段之间使用逗号。
  7. 不允许尾随逗号。
  8. 不支持注释。
  9. 不支持 undefined、NaN 和 Infinity 等 JavaScript 特殊值。

例如,下面是合法 JSON:

{
  "name": "张三",
  "age": 28,
  "active": true
}

下面则不是合法 JSON:

{
  name: "张三",
  age: 28,
  active: true,
}

原因是:

  • 字段名称没有使用双引号。
  • 最后一个字段后面存在多余逗号。

在大模型应用中,必须区分 JSON 格式与 JavaScript 对象字面量,不能将后者直接当作合法 JSON。

四、什么是 JSON Schema?

JSON Schema 是一种用于描述和验证 JSON 数据结构的规范。

它可以定义:

  • 数据类型。
  • 字段名称。
  • 必填字段。
  • 可选字段。
  • 字符串长度。
  • 数值范围。
  • 枚举值。
  • 数组元素类型。
  • 对象嵌套结构。
  • 字段数量限制。
  • 字符串格式约束。

简单来说:

  • JSON 描述实际数据。
  • JSON Schema 描述数据应该是什么样子。

4.1 JSON 与 JSON Schema 的区别

JSON:

{
  "name": "张三",
  "age": 28
}

JSON Schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    }
  },
  "required": [
    "name",
    "age"
  ],
  "additionalProperties": false
}

两者的关系:

对比维度 JSON JSON Schema
核心作用 存储和传输数据 描述和验证数据结构
内容 实际字段和值 类型、约束和规则
是否包含业务数据 是 通常否
是否定义必填字段 不定义 可以定义
是否限制字段类型 不定义 可以定义
是否可以校验 作为被校验对象 作为校验规则

4.2 JSON Schema 的基本结构

一个常见的 JSON Schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "title": "User",
  "description": "用户信息",
  "properties": {
    "name": {
      "type": "string",
      "description": "用户姓名"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": [
    "name",
    "age"
  ],
  "additionalProperties": false
}

主要字段说明:

字段 作用
$schema 声明采用的 JSON Schema 版本
type 指定数据类型
title Schema 标题
description 描述字段或结构用途
properties 定义对象属性
required 指定必填字段
additionalProperties 控制是否允许额外字段
minimum 数值最小值
maximum 数值最大值
format 声明数据格式语义

注意:format 的校验行为取决于所使用的 JSON Schema 校验器及其配置。有些实现将它作为注释,有些实现会执行格式检查。

五、JSON Schema 的核心约束

JSON Schema 的价值不只是描述字段,还能够表达相对复杂的数据约束。

5.1 type:数据类型

type 用于定义字段的数据类型。

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    },
    "score": {
      "type": "number"
    },
    "active": {
      "type": "boolean"
    },
    "tags": {
      "type": "array"
    },
    "profile": {
      "type": "object"
    }
  }
}

常见类型:

  • string
  • integer
  • number
  • boolean
  • object
  • array
  • null

JSON Schema 还支持通过类型数组表达多种允许类型,例如:

{
  "type": ["string", "null"]
}

表示该字段可以是字符串,也可以是 null。

5.2 properties:字段定义

properties 用于定义对象中允许描述的属性及其约束。

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    }
  }
}

需要注意,定义在 properties 中并不意味着字段一定存在。

字段是否必须出现,需要通过 required 指定。

5.3 required:必填字段

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    }
  },
  "required": [
    "name"
  ]
}

这里:

  • name 必须存在。
  • age 可以不存在。

一个容易混淆的地方是:

required 约束的是字段是否存在,不是字段值是否非空。

例如:

{
  "name": ""
}

在上述 Schema 中,name 仍然满足必填要求,因为字段存在且类型为字符串。

如果还需要限制字符串不能为空,可以增加:

{
  "type": "string",
  "minLength": 1
}

5.4 additionalProperties:额外字段

默认情况下,JSON Schema 不会自动禁止对象出现未定义字段。

例如:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    }
  }
}

下面的数据仍然可能通过基础 Schema 校验:

{
  "name": "张三",
  "age": 28
}

如果希望严格限制字段,可以设置:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

此时,未定义的 age 字段将不符合 Schema。

在严格的数据接口中,这个配置非常重要。

5.5 enum:枚举值

enum 用于限制字段只能使用指定的值。

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "processing",
        "completed",
        "failed"
      ]
    }
  },
  "required": [
    "status"
  ]
}

适合:

  • 订单状态。
  • 用户角色。
  • 任务类型。
  • 风险等级。
  • 审核结果。
  • 分类标签。

枚举可以减少模型自由生成字段值造成的不一致问题。

5.6 数值约束

JSON Schema 可以限制数字的范围。

{
  "type": "object",
  "properties": {
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "score": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    }
  }
}

常见约束:

关键字 作用
minimum 大于等于指定值
maximum 小于等于指定值
exclusiveMinimum 大于指定值
exclusiveMaximum 小于指定值
multipleOf 必须是指定数值的倍数

例如:

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "multipleOf": 0.5
}

表示数值必须在 0 到 100 之间,并且是 0.5 的倍数。

5.7 字符串约束

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 3,
      "maxLength": 20
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "phone": {
      "type": "string",
      "pattern": "^1[3-9][0-9]{9}$"
    }
  }
}

常见约束:

关键字 作用
minLength 最小字符串长度
maxLength 最大字符串长度
pattern 正则表达式约束
format 格式语义约束

需要注意,JSON Schema 中字符串长度的计算规则基于 Unicode 字符,而不是 UTF-8 字节数。

正则表达式的具体行为也可能受到实现支持范围影响。

5.8 数组约束

items 用于定义数组元素的结构。

{
  "type": "object",
  "properties": {
    "skills": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 10,
      "uniqueItems": true
    }
  }
}

常见约束:

关键字 作用
items 定义数组元素规则
minItems 最少元素数量
maxItems 最多元素数量
uniqueItems 是否要求元素唯一

5.9 嵌套对象

复杂业务数据通常存在多层结构。

例如用户信息包含地址:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "type": "object",
      "properties": {
        "province": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "detail": {
          "type": "string"
        }
      },
      "required": [
        "province",
        "city"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "name",
    "address"
  ],
  "additionalProperties": false
}

JSON Schema 可以递归描述复杂对象。

5.10 组合约束

JSON Schema 还支持组合规则:

关键字 作用
allOf 必须同时满足所有 Schema
anyOf 至少满足一个 Schema
oneOf 必须且只能满足一个 Schema
not 不能满足指定 Schema
$ref 引用其他 Schema

例如:

{
  "type": "object",
  "properties": {
    "payment_method": {
      "type": "string",
      "enum": [
        "card",
        "cash"
      ]
    }
  },
  "required": [
    "payment_method"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "payment_method": {
            "const": "card"
          }
        },
        "required": [
          "payment_method"
        ]
      },
      "then": {
        "properties": {
          "card_number": {
            "type": "string"
          }
        },
        "required": [
          "card_number"
        ]
      }
    }
  ]
}

这里表达的是:当支付方式为银行卡时,必须提供银行卡号。

需要注意,复杂组合约束并不一定被所有大模型结构化输出接口完整支持。JSON Schema 标准能力与模型服务商支持的 Schema 子集是两个不同概念。

六、结构化输出的工作原理

理解结构化输出,需要区分三个层次:

  1. 模型如何生成 Token。
  2. 如何让生成结果遵循数据结构。
  3. 应用如何验证和使用最终结果。

6.1 普通文本生成

普通大语言模型通常采用自回归生成方式。

给定输入上下文,模型逐步预测下一个 Token。

P(x_1,x_2,\ldots,x_T) = \prod_{t=1}^{T}P(x_t\mid x_{<t})

其中:

  • x_t:第 t 个 Token。
  • x_{<t}:之前已经生成的 Token。
  • P(x_t\mid x_{<t}):当前上下文下的下一个 Token 概率分布。

在普通文本生成中,模型可以生成任意符合其语言分布的内容。

即使 Prompt 中写着“只返回 JSON”,模型也可能生成解释文字、遗漏字段或输出不合法的 JSON。

6.2 通过提示词约束格式

最简单的方式是在 Prompt 中明确要求 JSON 格式。

例如:

请提取用户信息,并只返回 JSON。

字段:
- name:姓名,字符串
- age:年龄,整数
- email:邮箱,字符串

不要输出任何解释文字。

这种方式属于提示词层面的格式约束。

它能提高格式一致性,但不能保证每次生成都满足要求。

6.3 通过结构约束控制生成

更严格的结构化输出机制,可以将 Schema 作为模型生成时的约束条件。

部分模型服务会根据 Schema 构建受约束的解码过程,限制模型只能选择符合当前结构要求的 Token 或 Token 序列。

抽象过程如下:

flowchart TB
    A["用户请求"] --> B["应用提供 JSON Schema"]
    B --> C["模型服务解析 Schema"]
    C --> D["构建生成约束"]
    D --> E["模型计算下一个 Token"]
    E --> F["约束解码"]
    F --> G["生成结构化响应"]
    G --> H["应用解析与校验"]
    H --> I["业务处理"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#EAF3EC,stroke:#83A995,color:#315D49
    style C fill:#EAF3EC,stroke:#83A995,color:#315D49
    style D fill:#EAF3EC,stroke:#83A995,color:#315D49
    style E fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style F fill:#EAF3EC,stroke:#83A995,color:#315D49
    style G fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style H fill:#EAF3EC,stroke:#83A995,color:#315D49
    style I fill:#DCEFE5,stroke:#4F8B70,color:#24563F

这里的约束解码是对常见实现机制的抽象说明,并不代表所有模型服务商采用完全相同的内部算法。

部分实现可能使用语法约束、有限状态机、Token Masking 或其他解码控制技术。

6.4 Token Masking 的基本思想

假设模型当前需要生成 JSON 对象的一个字段。

Schema 要求:

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "failed"
      ]
    }
  },
  "required": [
    "status"
  ]
}

在适当的生成阶段,约束解码器会限制不符合当前语法或 Schema 状态的候选输出。

抽象表示:

P'(x_i)= \begin{cases} P(x_i), & x_i \in V_{\text{allowed}}\\ 0, & x_i \notin V_{\text{allowed}} \end{cases}

其中:

  • P(x_i):模型原始 Token 概率。
  • V_{\text{allowed}}:当前状态下允许的候选 Token 集合。
  • P'(x_i):约束后的概率分布。

实际系统通常还需要对允许的概率重新归一化。

需要注意,约束解码并不是简单地让模型先生成任意文本,再用程序修复 JSON,而是在生成过程中限制可选输出。

不同实现的约束粒度可能不同。有些约束作用于语法层面,有些还能进一步限制字段取值。

6.5 结构合法不等于语义正确

这是结构化输出最重要的边界。

假设 Schema 要求:

{
  "type": "object",
  "properties": {
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    }
  },
  "required": [
    "age"
  ]
}

模型返回:

{
  "age": 35
}

这个数据在结构上完全合法。

但如果用户实际年龄是 28 岁,那么输出仍然是错误的。

因此,需要区分:

层次 检查内容 典型方式
语法合法性 是否为合法 JSON JSON Parser
结构合法性 是否满足 Schema JSON Schema Validator
语义正确性 字段值是否符合事实 证据核对、模型评估
业务正确性 是否符合业务规则 业务代码与数据库校验

结构化输出主要解决前两个层次,后两个层次仍需要额外机制。

七、Structured Output、JSON Mode 与 Function Calling

在大模型 API 中,经常会遇到三个相关概念:

  • JSON Mode
  • Structured Outputs
  • Function Calling

它们都可能涉及 JSON,但设计目标不同。

7.1 JSON Mode

JSON Mode 通常用于要求模型以合法 JSON 格式返回内容。

例如:

{
  "name": "张三",
  "age": 28
}

它主要解决 JSON 语法格式问题。

但 JSON Mode 不一定保证:

  • 必须返回指定字段。
  • 字段类型完全符合要求。
  • 不会出现额外字段。
  • 枚举值符合业务定义。
  • 嵌套结构满足 Schema。

具体能力取决于服务商接口。

7.2 Structured Outputs

Structured Outputs 通常表示模型响应需要遵循指定的结构化 Schema。

例如:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    }
  },
  "required": [
    "name",
    "age"
  ],
  "additionalProperties": false
}

与只要求输出 JSON 相比,结构化输出可以进一步约束字段、类型和结构。

但需要注意:

  • 不同服务商支持的 Schema 子集不同。
  • 某些 Schema 关键字可能不被支持。
  • 严格模式可能要求所有属性都出现在 required 中。
  • 某些服务可能要求关闭额外字段。
  • 拒绝响应、截断响应和异常终止仍需要单独处理。

7.3 Function Calling

Function Calling,也称 Tool Calling,是让模型按照预先定义的工具参数结构,生成工具调用请求。

例如定义一个查询天气的工具:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "查询指定城市的天气",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "城市名称"
        }
      },
      "required": [
        "city"
      ],
      "additionalProperties": false
    }
  }
}

模型可能生成:

{
  "city": "上海"
}

这个参数可以用于调用天气工具。

但 Function Calling 的重点是工具调用,而不是单纯的数据返回。

模型生成工具调用请求后,通常还需要应用程序执行工具,并将结果返回模型。

7.4 三者的区别

对比维度 JSON Mode Structured Outputs Function Calling
核心目标 返回合法 JSON 遵循指定数据结构 发起工具调用
主要约束 JSON 语法 Schema 结构 工具参数结构
是否需要工具 不需要 不需要 通常需要
是否描述业务字段 不一定 是 是
是否触发外部执行 否 否 通常由应用执行
典型场景 JSON 数据返回 信息抽取、分类、数据生成 查询、搜索、操作

三者不是完全互斥的技术。

例如,Agent 可以通过 Function Calling 请求执行工具,同时要求工具参数符合 Schema。

八、如何使用 JSON Schema 构建大模型结构化输出?

下面使用 Python 展示完整的工程实现。

8.1 定义数据结构

假设需要从一段文本中提取用户信息。

目标数据:

{
  "name": "李明",
  "age": 30,
  "email": "liming@example.com",
  "skills": [
    "Python",
    "Go"
  ]
}

对应 JSON Schema:

user_schema = {
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "用户姓名"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150
        },
        "email": {
            "type": "string",
            "format": "email"
        },
        "skills": {
            "type": "array",
            "items": {
                "type": "string"
            }
        }
    },
    "required": [
        "name",
        "age",
        "email",
        "skills"
    ],
    "additionalProperties": False
}

这一步定义了数据契约。

应用程序和模型服务都可以根据这个契约理解预期数据结构。

8.2 使用 Pydantic 定义结构

Python 项目中,可以使用 Pydantic 通过类型注解定义数据结构。

from pydantic import BaseModel, Field, EmailStr

class UserInfo(BaseModel):
    name: str = Field(description="用户姓名")
    age: int = Field(ge=0, le=150)
    email: EmailStr
    skills: list[str]