AI Agent Engineering · Week 01
01-03|Structured Output:为什么企业系统不能只收一段自然语言
从自然语言回复走向可校验的业务数据,掌握 JSON、Schema Validation、缺字段和非法输出的处理边界。
一段听起来正确的回复,程序该怎么使用
模型说:“客户想查询订单 XB-1024 的物流,而且需要调用订单工具。”人一眼能看懂,程序却要猜:意图字段在哪里?订单号是否包含句号?“需要”怎样转成布尔值?如果模型改成西班牙语,解析规则是否继续有效?
企业系统需要明确字段。Structured Output 让模型输出符合约定形状的数据,应用才能校验、存储、路由和测试。
自然语言与结构化数据的分工
“It looks like the customer wants to track order XB-1024.”
- 适合人阅读
- 表达灵活
- 字段边界不稳定
{
"intent": "order_tracking",
"orderId": "XB-1024",
"needTool": true
}- 适合程序消费
- 字段可校验
- 便于路由与测试
JSON、JSON Schema 与业务事实是三层检查
合法 JSON 只表示语法可解析。下面的内容是合法 JSON,却不一定符合系统约定:
{
"intent": "track_stuff",
"orderId": 1024,
"needTool": "yes",
"confidence": "absolutely"
}
Schema 可以要求 intent 来自枚举,orderId 是字符串或 null,needTool 是布尔值,并拒绝额外字段。通过 Schema 后仍要检查业务语义:客户是否真的写了 XB-1024?意图是否与消息一致?订单是否属于当前客户?
能否解析为 JSON?
字段、类型、枚举、必填项是否符合契约?
内容是否有输入或可信系统证据?
V0.1 的 Schema
以下是课程接口的核心形状。具体 SDK 写法会变化,字段含义更重要。
{
"type": "object",
"properties": {
"intent": {
"type": "string",
"enum": ["order_tracking", "refund_request", "product_question", "unknown"]
},
"language": { "type": "string" },
"orderId": { "type": ["string", "null"] },
"needTool": { "type": "boolean" }
},
"required": ["intent", "language", "orderId", "needTool"],
"additionalProperties": false
}
orderId 必须出现,但值可以是 null。这样“模型漏了字段”和“客户没有提供订单号”能被区分。所有字段必填也让下游代码少处理一种形状漂移。
数据怎样进入业务系统
任一检查失败都进入显式错误路径,不能把原始字符串直接送入订单查询。
缺字段
缺少必填字段属于 Schema Failure。应用可以有限重试一次,重试时提供清晰错误;持续失败则记录并停止。不要由应用默默补上一个看似合理的值。
非法输出
无法解析、枚举之外的意图、错误类型和额外字段都应拒绝进入业务流程。保留原始响应的安全摘要、Schema 版本和错误类型,方便调试。
模糊意图
结构可以完全正确,intent 仍可能没有证据。为此保留 unknown,并在测试中检查模糊输入。必要时下一步向客户追问,而不是强制分类。
多语言输入
Schema 不随语言变化;客户消息可以是英文、中文或西班牙文,业务标签仍保持统一。language 记录主要语言,最终回复语言可由后续步骤决定。
Failure Lab
把“JSON 可解析”当成完成
为什么诱人: 解析器不报错,看起来已经结构化。
为什么失败: 字段名、类型和枚举仍可能漂移,下游代码被迫猜测。
更好的设计: 使用明确 Schema,拒绝额外字段,并为缺失值建立统一表达。
把 Schema 正确当成事实正确
为什么诱人: Strict Schema 提供很强的确定感。
为什么失败: 模型仍可能在 orderId 字段里生成客户没有提供的编号。
更好的设计: 检查提取字段是否能追溯到输入;订单归属和状态必须由工具查询。
无限制重试非法输出
为什么诱人: 再试一次可能成功。
为什么失败: 持续错误会增加成本与延迟,也可能形成隐蔽循环。
更好的设计: 限定重试次数,记录错误,达到上限后进入可观察的失败状态。
实践:为四个输出制作校验表
拿 intent、language、orderId、needTool 四个字段,分别写出类型、允许值、来源、缺失表达和下游用途。再构造四个坏输出:缺字段、错误类型、非法枚举、虚构订单号,写出系统应在哪一层拒绝。
Acceptance Criteria
- ☐ 能区分合法 JSON、Schema 合格与业务事实正确。
- ☐ Schema 包含四个必填字段并禁止额外字段。
- ☐
orderId缺失用null明确表示。 - ☐
intent包含unknown,不强迫模糊消息归类。 - ☐ 非法输出不会进入订单查询或后续 Workflow。
- ☐ 重试次数有限,失败可记录、可停止。
- ☐ 多语言输入使用同一业务 Schema。
合上正文,试着回答
- 为什么自然语言回复不适合作为程序接口?
- JSON、Schema 与业务真值分别检查什么?
- 为什么
orderId应必填但允许为null? - Strict Schema 能防止模型虚构订单号吗?
- 非法输出连续出现时系统应该怎样结束?
下一课完成 V0.1:把 Prompt Contract、Schema、校验和代表测试集组合成可验收的多语言意图识别器。
延伸阅读 / Sources
核查日期:2026-10-17。
- OpenAI API:Structured model outputs。用于核对 Structured Outputs、JSON Schema 与 Function Calling 的适用边界。
- JSON Schema:Understanding JSON Schema。用于核对对象、类型、必填字段和额外字段等 Schema 基础。
- OpenAI API:Function calling。用于核对 strict mode 与函数参数 Schema 的约束。
长期有效的原理: 结构正确、语义正确和事实正确需要分层验证。当前实现方式: Structured Outputs 的支持模型和 API 字段会更新,开发时复核所选接口。