AI Agent / 系统课时

结构化输出与结果解析

结构化输出与结果解析

本课解决模型输出难以被程序直接使用的问题。学习完成后,你可以要求模型生成结构化数据,并在应用中完成校验和解析。

学习目标

  • 理解结构化输出的价值
  • 掌握 JSON 格式约束方法
  • 能够解析模型返回的数据

为什么需要结构化输出

自然语言适合阅读,但不适合程序处理。例如订单分类、信息抽取、智能审批等场景,都需要固定字段的数据结构。

结构化输出可以让模型结果符合 JSON、XML 或自定义格式,从而被后端程序直接消费。

设计 JSON 输出格式

可以在指令里说明字段语义,再用接口的 JSON Schema 约束返回结构。仅在指令里写“请返回 JSON”属于提示,调用接口时应单独配置支持的结构化输出模式。

text
请返回 JSON 格式。
字段要求:
name:商品名称
price:商品价格
category:商品分类
不要输出额外说明文字。

预期结果:

json
{
  "name": "智能手表",
  "price": 999,
  "category": "电子产品"
}

程序解析结果

应用收到模型结果后,先检查 JSON 语法,再校验字段结构和业务取值,最后才能构造业务对象。json.loads 成功只代表能解析,不能证明一定有商品名称,也不能证明价格是合法金额。以下独立示例使用 Python 3 标准库,演示这三层检查。

python
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)

预期输出:

text
通过: 智能手表
拒绝: 价格类型错误
拒绝: JSON 键重复
拒绝: 响应未正常完成
拒绝: 模型拒答

本例用模拟响应练习异常分支,不需要密钥。布尔值和重复键特意作为不可信输入送入解析器;严格 Schema 在支持的模型上约束正常完成的输出,但仍要检查拒答、截断及业务规则。JSON 解码细节参见 Python JSON 文档。

结构化输出注意事项

不要只依赖 Prompt 要求格式。关键业务场景应该增加 JSON Schema 校验、重试机制或人工审核流程,避免错误数据进入核心系统。

使用 JSON Schema 时,应同时声明对象类型、properties、required 和 additionalProperties 规则,并按接口支持的关键字约束取值。本例在 Schema 中设置分类枚举,把价格范围作为独立的业务校验。JSON Schema 对象参考解释了这些规则的区别。本例手写校验只是为了直接看清各层责任,字段增加后应集中维护 Schema。

若模型返回 Markdown 围栏、被截断的 JSON、拒绝回答或空内容,应保留失败状态,不用正则从任意解释文字中猜测对象。可以在确定是可修复的格式错误时有限重试一次,并向模型返回具体校验错误;认证失败和超时要按调用错误处理。格式通过后,商品真实性、定价权限和最终入库条件仍由业务层检查。真实金额可使用约定的最小货币单位整数,避免二进制浮点带来的结算误差。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

结构化输出与结果解析

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通