AI Agent / 系统课时
结构化输出与结果解析
结构化输出与结果解析
本课解决模型输出难以被程序直接使用的问题。学习完成后,你可以要求模型生成结构化数据,并在应用中完成校验和解析。
学习目标
- 理解结构化输出的价值
- 掌握 JSON 格式约束方法
- 能够解析模型返回的数据
为什么需要结构化输出
自然语言适合阅读,但不适合程序处理。例如订单分类、信息抽取、智能审批等场景,都需要固定字段的数据结构。
结构化输出可以让模型结果符合 JSON、XML 或自定义格式,从而被后端程序直接消费。
设计 JSON 输出格式
可以在指令里说明字段语义,再用接口的 JSON Schema 约束返回结构。仅在指令里写“请返回 JSON”属于提示,调用接口时应单独配置支持的结构化输出模式。
请返回 JSON 格式。
字段要求:
name:商品名称
price:商品价格
category:商品分类
不要输出额外说明文字。预期结果:
{
"name": "智能手表",
"price": 999,
"category": "电子产品"
}程序解析结果
应用收到模型结果后,先检查 JSON 语法,再校验字段结构和业务取值,最后才能构造业务对象。json.loads 成功只代表能解析,不能证明一定有商品名称,也不能证明价格是合法金额。以下独立示例使用 Python 3 标准库,演示这三层检查。
import json
from types import SimpleNamespace
from unittest.mock import Mock
def reject_constant(value):
# 拒绝 Python 解码器默认接受的 NaN / Infinity 扩展。
raise ValueError("JSON 数值必须有限")
def unique_object(pairs):
result = {}
for key, value in pairs:
if key in result:
raise ValueError("JSON 键重复")
result[key] = value
return result
def parse_product(content):
if len(content.encode("utf-8")) > 4096:
raise ValueError("响应过大")
data = json.loads(content, parse_constant=reject_constant,
object_pairs_hook=unique_object)
if type(data) is not dict or set(data) != {"name", "price", "category"}:
raise ValueError("商品字段不匹配")
if type(data["name"]) is not str or not data["name"].strip():
raise ValueError("名称不能为空")
price = data["price"]
# bool 是 int 的子类,必须显式排除;超大整数也不应转为 float。
if type(price) not in (int, float):
raise ValueError("价格类型错误")
if not 0 <= price <= 1_000_000:
raise ValueError("价格超出范围")
if data["category"] not in ("电子产品", "日用品"):
raise ValueError("分类不在允许范围")
return data
PRODUCT_FORMAT = {
"type": "json_schema",
"json_schema": {
"name": "product",
"strict": True,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"price": {"type": "number"},
"category": {"type": "string", "enum": ["电子产品", "日用品"]},
},
"required": ["name", "price", "category"],
"additionalProperties": False,
},
},
}
def extract_product(client, description):
response = client.chat.completions.create(
model="gpt-4.1-mini",
messages=[
{"role": "developer", "content": "按指定结构提取商品名称、价格和分类。"},
{"role": "user", "content": description},
],
response_format=PRODUCT_FORMAT,
)
if not response.choices:
raise ValueError("没有候选项")
choice = response.choices[0]
if choice.message.refusal:
raise ValueError("模型拒答")
if choice.finish_reason != "stop":
raise ValueError("响应未正常完成")
if not isinstance(choice.message.content, str):
raise ValueError("没有文本")
return parse_product(choice.message.content)
client = Mock()
for reason, refusal, content in (
("stop", None, '{"name":"智能手表","price":999,"category":"电子产品"}'),
("stop", None, '{"name":"智能手表","price":true,"category":"电子产品"}'),
("stop", None, '{"name":"A","name":"B","price":10,"category":"日用品"}'),
("length", None, '{"name":"智能手表"'),
("stop", "模拟拒答", None),
):
client.chat.completions.create.return_value = SimpleNamespace(
choices=[SimpleNamespace(finish_reason=reason, message=SimpleNamespace(
refusal=refusal, content=content,
))]
)
try:
print("通过:", extract_product(client, "商品描述")["name"])
except ValueError as exc:
print("拒绝:", exc)预期输出:
通过: 智能手表
拒绝: 价格类型错误
拒绝: JSON 键重复
拒绝: 响应未正常完成
拒绝: 模型拒答本例用模拟响应练习异常分支,不需要密钥。布尔值和重复键特意作为不可信输入送入解析器;严格 Schema 在支持的模型上约束正常完成的输出,但仍要检查拒答、截断及业务规则。JSON 解码细节参见 Python JSON 文档。
结构化输出注意事项
不要只依赖 Prompt 要求格式。关键业务场景应该增加 JSON Schema 校验、重试机制或人工审核流程,避免错误数据进入核心系统。
使用 JSON Schema 时,应同时声明对象类型、properties、required 和 additionalProperties 规则,并按接口支持的关键字约束取值。本例在 Schema 中设置分类枚举,把价格范围作为独立的业务校验。JSON Schema 对象参考解释了这些规则的区别。本例手写校验只是为了直接看清各层责任,字段增加后应集中维护 Schema。
若模型返回 Markdown 围栏、被截断的 JSON、拒绝回答或空内容,应保留失败状态,不用正则从任意解释文字中猜测对象。可以在确定是可修复的格式错误时有限重试一次,并向模型返回具体校验错误;认证失败和超时要按调用错误处理。格式通过后,商品真实性、定价权限和最终入库条件仍由业务层检查。真实金额可使用约定的最小货币单位整数,避免二进制浮点带来的结算误差。