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 数组约束与条件约束。
因此要分三层:
- 完整 Schema 的表达能力:本地验证器支持哪些标准版本与关键字。
- 目标模型接受的 Schema 子集:请求会被拒绝、忽略约束,还是按约定执行。
- 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、类型和模型版本,确保失败可以重现。格式合规但内容错误的样本应进入评测集,而不是一直通过重试掩盖;评测流程见评估、反馈与可观测性。
来源与延伸阅读
- CodeCrush 原始笔记:08 结构化输出与数据校验、13 提示词模板与 Schema 编写、24 结构化输出与数据转换。第 13 篇的模板与组件化由提示词设计主题承接,本篇集中保留字段语义与 Schema 设计。
- 标准与校验:JSON Schema 条件约束、数组约束、Pydantic 严格模式。
- 原生接口与框架:OpenAI 结构化输出、Spring AI 结构化输出、LangChain 结构化输出与错误处理。