一、什么是结构化输出?
结构化输出(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 对格式有严格要求:
- 对象使用
{}。 - 数组使用
[]。 - 字符串必须使用双引号。
- 字段名称必须是字符串。
- 字段和值之间使用冒号。
- 多个字段之间使用逗号。
- 不允许尾随逗号。
- 不支持注释。
- 不支持
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"
}
}
}
常见类型:
stringintegernumberbooleanobjectarraynull
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 子集是两个不同概念。
六、结构化输出的工作原理
理解结构化输出,需要区分三个层次:
- 模型如何生成 Token。
- 如何让生成结果遵循数据结构。
- 应用如何验证和使用最终结果。
6.1 普通文本生成
普通大语言模型通常采用自回归生成方式。
给定输入上下文,模型逐步预测下一个 Token。
其中:
- 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):模型原始 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]