跳到主要内容
← 返回AI Agent Engineering|12 周从 Demo 到真实 Agent 系统

AI Agent Engineering · Week 01

01-03|Structured Output:为什么企业系统不能只收一段自然语言

从自然语言回复走向可校验的业务数据,掌握 JSON、Schema Validation、缺字段和非法输出的处理边界。

Structured Output · JSON Schema · Validation

一段听起来正确的回复,程序该怎么使用

模型说:“客户想查询订单 XB-1024 的物流,而且需要调用订单工具。”人一眼能看懂,程序却要猜:意图字段在哪里?订单号是否包含句号?“需要”怎样转成布尔值?如果模型改成西班牙语,解析规则是否继续有效?

企业系统需要明确字段。Structured Output 让模型输出符合约定形状的数据,应用才能校验、存储、路由和测试。

自然语言与结构化数据的分工

Natural Language

“It looks like the customer wants to track order XB-1024.”

  • 适合人阅读
  • 表达灵活
  • 字段边界不稳定
Structured Output
{
"intent": "order_tracking",
"orderId": "XB-1024",
"needTool": true
}
  • 适合程序消费
  • 字段可校验
  • 便于路由与测试
图 1|自然语言用于沟通,结构化数据用于系统之间传递状态。一个产品可以同时需要两者。

JSON、JSON Schema 与业务事实是三层检查

合法 JSON 只表示语法可解析。下面的内容是合法 JSON,却不一定符合系统约定:

{
  "intent": "track_stuff",
  "orderId": 1024,
  "needTool": "yes",
  "confidence": "absolutely"
}

Schema 可以要求 intent 来自枚举,orderId 是字符串或 null,needTool 是布尔值,并拒绝额外字段。通过 Schema 后仍要检查业务语义:客户是否真的写了 XB-1024?意图是否与消息一致?订单是否属于当前客户?

1. Syntax
能否解析为 JSON?
2. Schema
字段、类型、枚举、必填项是否符合契约?
3. Business Truth
内容是否有输入或可信系统证据?
图 2|Structured Output 强化前两层;它不会自动证明订单、物流或退款事实。

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。这样“模型漏了字段”和“客户没有提供订单号”能被区分。所有字段必填也让下游代码少处理一种形状漂移。

数据怎样进入业务系统

Customer MessagePrompt + SchemaModel OutputSchema ValidationBusiness ChecksRoute / Stop

任一检查失败都进入显式错误路径,不能把原始字符串直接送入订单查询。

图 3|结构化输出是边界中的一环,后面仍有业务校验和路由控制。

缺字段

缺少必填字段属于 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。

合上正文,试着回答

  1. 为什么自然语言回复不适合作为程序接口?
  2. JSON、Schema 与业务真值分别检查什么?
  3. 为什么 orderId 应必填但允许为 null?
  4. Strict Schema 能防止模型虚构订单号吗?
  5. 非法输出连续出现时系统应该怎样结束?

下一课完成 V0.1:把 Prompt Contract、Schema、校验和代表测试集组合成可验收的多语言意图识别器。

延伸阅读 / Sources

核查日期:2026-10-17。

长期有效的原理: 结构正确、语义正确和事实正确需要分层验证。当前实现方式: Structured Outputs 的支持模型和 API 字段会更新,开发时复核所选接口。