← 返回知识目录

Agent 结构化输出与数据校验

模型返回一段 JSON,不代表程序可以立即相信它。JSON 可能缺字段、类型错误、被截断,也可能格式完全正确但数值来自猜测。Agent 要将结果用于路由、存库或工具调用,需要分别检查:响应是否完整、结构是否符合约定、字段是否满足业务规则、值是否有证据。

本文把原生 API、类型转换与框架封装合在一处讲解。输入理解中如何保留“不确定”和“待澄清”,见输入理解与意图识别;网络重试与流式连接见模型调用:接口、流式与可靠性。

整理来源:CodeCrush《大模型应用开发基础》第 08、24 篇及第 13 篇的 Schema 设计部分。原稿的三层约束与反馈重试合并为一条流程;补充缺失值、拒答、截断、Schema 子集、事实证据及流式边界。代码为教学示例,未调用真实模型或验证具体账号权限。官方资料复核日期:2026-09-22。

1. 先定义对象含义,再选择输出机制

以报销信息抽取为例,amount: 800 不够明确:币种是什么,单位是元还是分,是申请金额还是批准金额?如果原文没有金额,应该输出 null、省略字段,还是拒绝整个请求?这些决定必须写进契约,而不能交给模型临场猜。

一个适合后续校验的结果可以是:

{
  "employee": "张三",
  "city": "杭州",
  "amount_cents": 80000,
  "currency": "CNY",
  "category": "lodging",
  "amount_evidence": "住宿费 800 元"
}

amount_cents 使用整数分,减少浮点金额歧义;amount_evidence 保留用于回查的原文。缺失值使用 null,缺失证据不自动转换成 0。“字段必填”与“字段值非空”是两件事:某些严格结构化输出要求键存在,但允许值为 null。

原稿用字段描述代替类别枚举,例如“只能是住宿/交通/餐饮”。描述对模型有帮助,却不是类型约束。需要固定取值时,要使用 enum、Python Literal 或 Java 枚举;需要解释抽取口径时,才用 description。

字段名与枚举值本身也是模型看到的说明:amount_cents 比 value 更明确,lodging 比没有定义的 A 更容易理解。英文标识符便于代码协作,但“英文一定更稳定”需要在目标模型上实测。other 表示已知但不属于列举类别,unknown 或 null 表示信息不足,两者不能互相代替。结构只保留业务需要的嵌套,不为了形式美观层层包装,也不把“超过三层必然不稳定”当作固定规律。

2. 三种约束方式分别保证什么

方式 模型如何得到约定 可以依赖的能力 应用仍要检查
提示词约束 在自然语言中给格式与示例 尽力遵循,可覆盖较多模型 语法、字段、类型、完整性、业务与证据
JSON Mode 开启 JSON 输出模式,提示词说明内容 支持条件下约束 JSON 语法 Schema、拒答/截断、业务与证据
原生 Schema 约束 通过接口字段传 Schema 在模型支持的 Schema 子集内约束结构 完成状态、业务与证据、版本兼容

提示词约束适合低风险原型或不支持原生约束的模型,但不能代替程序校验。JSON Mode 也不关心你要的是 name 还是 Name。原生 Schema 能减少结构错误,但“输出符合形状”仍不等于“内容符合事实”。

工具调用还提供另一种取得结构化参数的路径。框架可能用工具调用或厂商原生 Schema 实现同一个高级接口,因此不能仅看 with_structured_output() 的名字就假定它采用了某种机制。

一个可空、可追溯的 Schema

下面只使用较常见的 Schema 结构。真实请求前仍要检查目标模型支持的关键字和嵌套深度,不支持时应明确报错或选择已验证的替代路径。

EXPENSE_SCHEMA = {
    "type": "object",
    "properties": {
        "employee": {"type": ["string", "null"], "description": "原文中的报销人姓名"},
        "city": {"type": ["string", "null"], "description": "出差城市;没有则为 null"},
        "amount_cents": {"type": ["integer", "null"], "description": "申请金额,单位分;没有则为 null"},
        "currency": {"type": ["string", "null"], "description": "原文明确的币种;不推测"},
        "category": {
            "type": ["string", "null"],
            "enum": ["lodging", "transport", "meals", "other", None],
        },
        "amount_evidence": {"type": ["string", "null"], "description": "金额所在的原文片段"},
    },
    "required": ["employee", "city", "amount_cents", "currency", "category", "amount_evidence"],
    "additionalProperties": False,
}

结构化输出参数并不跨接口通用。下面是 Chat Completions 的请求片段,client、os 和环境变量沿用模型调用篇:

raw_text = "张三申请报销杭州住宿费 800 元,币种人民币。"
messages = [
    {"role": "system", "content": "只抽取报销信息。缺失字段填 null,不补造事实;保留金额原文。"},
    {"role": "user", "content": raw_text},
]
response = client.chat.completions.create(
    model=os.environ["LLM_MODEL"],
    messages=messages,
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "expense_claim", "strict": True, "schema": EXPENSE_SCHEMA},
    },
)

Responses、Claude、Gemini 使用各自的字段形态,不能把这段 response_format 原样复制过去,也不能把 MIME 类型和 Schema 对象混成一个字段。模型是否支持、拒答怎样返回、哪些关键字受限,按官方结构化输出文档与目标 provider 文档确认。

3. JSON Schema 的能力与服务端子集要分开

原稿把“数组至少三个元素”“某字段有值时另一个字段必填”归为 Schema 无法表达,这是需要纠正的。完整 JSON Schema 提供 minItems、条件和依赖关键字;服务端结构化输出可能只实现其中一部分。见 JSON Schema 数组约束与条件约束。

因此要分三层:

  1. 完整 Schema 的表达能力:本地验证器支持哪些标准版本与关键字。
  2. 目标模型接受的 Schema 子集:请求会被拒绝、忽略约束,还是按约定执行。
  3. Schema 外的业务和事实:金额是否对应真实票据、城市是否匹配订单、引用是否来自当前授权文档。

即便跨字段规则可以写成 Schema,也可以保留在业务校验里,方便错误定位和版本管理。关键在于明确谁负责检查,而不是把所有规则都挤进提示词。

4. 解析对象只是校验的开始

下面用 Pydantic 2 定义本地契约,关闭额外字段并启用严格类型。普通反序列化器的默认行为可能进行类型转换,也可能忽略未知字段;不能笼统地说“反序列化会检测所有字段错误”。

from typing import Literal
from pydantic import BaseModel, ConfigDict, Field

class ExpenseClaim(BaseModel):
    model_config = ConfigDict(extra="forbid", strict=True)

    employee: str | None
    city: str | None
    amount_cents: int | None = Field(description="申请金额,单位分")
    currency: str | None
    category: Literal["lodging", "transport", "meals", "other"] | None
    amount_evidence: str | None

def validate_business(claim: ExpenseClaim, source_text: str) -> None:
    if claim.amount_cents is not None:
        if claim.amount_cents < 0:
            raise ValueError("amount_cents: 申请金额不能为负")
        if not claim.amount_evidence or claim.amount_evidence not in source_text:
            raise ValueError("amount_evidence: 金额必须有可回查的原文片段")
        if claim.currency is None:
            raise ValueError("currency: 有金额时仍需确认币种")
    elif claim.amount_evidence is not None:
        raise ValueError("amount_evidence: 有金额证据但没有数值,需要澄清")

这只是最小业务校验:原文片段确实存在,并不证明 80000 分就是片段表达的金额。正式业务还要检查金额与币种的规范化结果,必要时用确定性解析器、订单台账或人工复核。证据子串匹配是一道检查,不能被包装成事实正确性的证明。

读取模型响应时,先分流拒答、截断、工具调用、空结果,再尝试解析:

def parse_complete_expense(response, source_text: str) -> ExpenseClaim:
    if not response.choices:
        raise RuntimeError("响应没有候选结果")
    choice = response.choices[0]
    if getattr(choice.message, "refusal", None):
        raise RuntimeError("模型拒答,应由上层按拒答策略处理")
    if choice.finish_reason != "stop":
        raise RuntimeError(f"结果未完整结束:{choice.finish_reason}")
    if not choice.message.content:
        raise RuntimeError("结果为空")
    claim = ExpenseClaim.model_validate_json(choice.message.content)
    validate_business(claim, source_text)
    return claim

Pydantic 的校验模式、字段约束和 JSON Schema 生成方法,可查官方文档。如果只做 JSON 字典而不转类型,也应选用本地 Schema 验证器,而不是只执行 json.loads()。

5. 用一份类型减少 Schema 漂移

手写 Schema、业务类型和提示词三份定义容易不同步。用 Pydantic 或 Java record 生成 Schema,可以减少重复维护,但要检查生成结果是否适配目标服务;自定义业务校验函数不会自动变成服务端支持的 Schema。

字段描述应写清楚单位、来源和缺失策略。字段顺序可以便于阅读和调试,但不能成为跨字段依赖正确性的保证。需要计算的总额、比例和日期差,优先让代码计算,不要期待调换字段顺序就能保证算对。

LangChain:声明机制,保留原始响应

假设 model 是已经配置好的目标聊天模型,下面显式请求 json_schema,用 Pydantic 类型解析,并保留原始响应与解析错误:

structured_model = model.with_structured_output(
    ExpenseClaim,
    method="json_schema",
    include_raw=True,
)
result = structured_model.invoke(
    "抽取报销信息;缺失值用 null,不推测币种,保留金额原文。\n" + raw_text
)
if result["parsing_error"] is not None or result["parsed"] is None:
    raise RuntimeError("结构化解析失败,需要进入受限修复或澄清流程")

claim = result["parsed"]
validate_business(claim, raw_text)
raw_message = result["raw"]  # 用于检查结束状态、拒答、用量及调用标识

支持的 method 由 provider 决定。json_mode 只开启 JSON Mode,仍需在提示词给字段要求;使用 TypedDict 或原始 JSON Schema 时,也不能假定和 Pydantic 一样自动完成本地验证。更多细节见LangChain 模型结构化输出。

Spring AI:区分转换、原生约束和反馈重试

以下片段按 Spring AI 2.0.1 文档中的 .entity() 扩展写法整理,假设 chatClient 已配置。Java 可空金额使用 Long,避免把缺失金额默认为基本类型 long 的零值;枚举提供真实类别约束。

enum ExpenseCategory { lodging, transport, meals, other }

record ExpenseClaim(
        String employee,
        String city,
        @JsonPropertyDescription("申请金额,单位分;原文缺失时为 null") Long amountCents,
        String currency,
        ExpenseCategory category,
        @JsonPropertyDescription("金额所在的原文片段;缺失时为 null") String amountEvidence) {}

ExpenseClaim claim = chatClient.prompt()
        .user("抽取报销信息,不补造缺失信息:" + rawText)
        .call()
        .entity(ExpenseClaim.class, spec -> spec
                .useProviderStructuredOutput()
                .validateSchema());

默认 .entity() 的类型转换、useProviderStructuredOutput() 的服务端约束与 validateSchema() 的反馈修复是不同能力;都不能替代业务事实校验。需要同时保留原始响应时可使用 .responseEntity()。开关依赖底层模型及转换器能力,接入时应验证实际发出的请求,而不是只检查编译通过。见 Spring AI 结构化输出。

6. 反馈重试要修正可修正的错误

结构错误可把字段路径和具体要求反馈给模型,例如 amount_cents 必须是整数或 null。事实缺失却不应通过“再试一次”逼模型补出一个值。原文没有城市时,正确动作通常是保留缺失或请求补充。

把每次尝试分为三个阶段:

取得完整响应 → 类型与业务校验 → 保存通过校验的对象
                     ↓ 失败
           可修正且还有预算?
              是 → 附上有限错误信息,再生成
              否 → 标记失败、澄清或转交复核

下面示例适用于完整文本已经取得、但校验未通过的场景。call_complete_json 必须由调用层实现:返回完整 JSON 文本,在网络失败、拒答或截断时抛出专门异常,而不是把这些状态混进校验修复。

import json
from pydantic import ValidationError

def extract_with_repair(source_text, call_complete_json, max_repairs=2):
    messages = [
        {"role": "system", "content": (
            "抽取报销信息,遵循给定 Schema;缺失值填 null,不补造事实。"
        )},
        {"role": "user", "content": source_text},
    ]
    for attempt in range(max_repairs + 1):
        raw = call_complete_json(messages, EXPENSE_SCHEMA)
        try:
            claim = ExpenseClaim.model_validate_json(raw)
            validate_business(claim, source_text)
            return claim
        except ValidationError as exc:
            errors = [{"field": list(e["loc"]), "type": e["type"]}
                      for e in exc.errors(include_input=False)]
        except ValueError as exc:
            errors = [{"field": "business", "message": str(exc)}]

        if attempt == max_repairs:
            raise ValueError("达到修复上限,结果未通过校验")
        messages.extend([
            {"role": "assistant", "content": raw},
            {"role": "user", "content": (
                "上次校验失败:" + json.dumps(errors, ensure_ascii=False)
                + "。依据原文修正,不得补造缺失事实。"
            )},
        ])

这里没有用正则截取第一个 { 到最后一个 }:这种宽松修补会误吞多个对象、把围栏外文本藏起来,也无法可靠处理字符串里的括号。若产品需要容忍特定包装格式,应单独定义允许的格式并记录转换,不能悄悄把任意文本改成“成功 JSON”。

修复还应共享总截止时间、最大 Token 和网络尝试预算。只修某个字段可以节省输出,但最终仍要重新校验整个对象,防止单字段修正破坏跨字段关系。向模型反馈的错误信息应精简,不能把栈信息、数据库内容或其他用户的数据全部回传。

框架能力也有作用域:直接模型调用的 with_structured_output() 不等同于 Agent 的完整修复策略;LangChain 的 create_agent 配合 ToolStrategy 支持结构化错误反馈与重试,因此不能笼统地说“LangChain 没有自动修复”。参见官方错误处理说明。

7. 流式展示与最终提交分开

结构化输出和流式在原理上并不互斥。支持的接口可以传输结构化数据的增量;完整对象通常仍要等响应结束后才能通过全部验证。Spring AI 当前 .entity() 的完整对象接口只用于 .call(),这是接口范围,不能推广为所有模型与框架都不支持结构化流式。

例如前端可以逐步显示识别到的城市与金额,但状态应为“提取中”;写数据库、执行支付或发起工具动作,要等待最终对象完成校验。即使前几个字段都看起来正确,后面的拒答、截断或跨字段错误仍可能使整条结果无效。OpenAI 的结构化输出流式说明展示了这一能力。

工具参数的分块同理:显示“准备查询订单”可以提前,真正执行则需要调用 ID、完整参数、权限和业务前置条件都通过。执行约束见执行循环与工具选择。

8. 验证的不只是解析成功率

保留一组小而稳定的失败样本,覆盖缺少字段、多余字段、数字字符串、非法枚举、null、负金额、币种缺失、虚构证据、原文确实缺失信息、截断、拒答和修复耗尽。对同一份 Schema,更换模型或版本后重新运行。

指标至少分为:响应完整率、Schema 通过率、业务通过率、事实核对通过率、澄清率、修复次数、最终失败率、成本和延迟。不要用“JSON 解析成功率 99%”替代“业务正确率 99%”。

记录 Prompt、Schema、类型和模型版本,确保失败可以重现。格式合规但内容错误的样本应进入评测集,而不是一直通过重试掩盖;评测流程见评估、反馈与可观测性。

来源与延伸阅读

返回 Agent 系统设计总览