《AI Agent 技术原理与架构·模型、推理与能力边界》6.2 Schema、约束解码与结构化输出

结构化输出不是“让模型记得输出 JSON”,而是把 Schema 变成生成时的约束和运行时的契约。本节区分约束解码与事后校验,说明 JSON Schema 能保证什么、不能保证什么,并用一个最小校验器演示缺字段、类型错、多余字段与代码围栏修复。

以下数字为教学示例,不构成对任何真实模型或供应商训练结果的承诺。

让模型输出 JSON,最常见的做法是在提示词里写“请只输出合法 JSON”。这不可靠:模型可能加代码围栏、在 JSON 前后写解释、把数字写成字符串,或者在长输出里漏掉一个括号。结构化输出要稳定,必须把约束放到生成过程或运行时,而不是放在礼貌请求里。

这一节区分两条路线:约束解码在生成时屏蔽不合法的 token;事后校验在生成后解析并拒绝不合格输出。两者不是互斥的,生产系统通常同时使用:约束解码降低语法错误,Schema 校验保证语义结构,业务校验保证参数可执行。

Schema 是契约,不是建议

一个 JSON Schema 至少表达四类约束:

约束例子能挡住什么
类型tool 必须是字符串把对象写成数组
必填args 必须存在漏掉关键字段
结构args 必须是对象把参数写成字符串
附加字段不允许 date模型自创字段

这四类约束保证的是“形状”,不是“内容”。Schema 说 city 是字符串,但不会判断 city 是否真实存在;Schema 说 expression 是字符串,但不会判断它是不是合法表达式。内容正确性需要工具服务、数据库或领域校验器来保证。

把 Schema 当契约,意味着三方要一致:模型看到的工具描述、运行时校验的 Schema、工具服务实际接受的参数。三者任何一处漂移,都会出现“模型按描述调用、运行时放行、工具报错”的链路故障。

约束解码:把语法变成 token 掩码

约束解码的基本想法是:在每个生成步,根据当前前缀计算“哪些 token 能继续构成合法输出”,把其他 token 的概率置零,再采样。对 JSON 来说,前缀 {"tool": 后面只能接字符串、数字、对象等合法值;括号不平衡时不能结束。

方式优点局限
提示词要求实现简单,无额外依赖不保证,长输出易漂移
事后解析能拦截明显错误错误已经生成,浪费 token
约束解码语法层几乎不失败需要语法编译,可能影响语义
运行时校验能检查业务规则发现问题时已生成完整输出

约束解码不是免费的。掩码计算会增加每步开销;过强的约束可能让模型“为了合法而合法”,选一个语法正确但语义错误的参数。它解决的是“输出能不能被解析”,不是“输出对不对”。

另一个常见误区是把约束解码当成安全措施。模型仍然可以在合法 Schema 里填入恶意路径、越权参数或编造的值。约束只保证形状,权限和范围检查仍要在执行前完成。

最小实验:校验、词表掩码与围栏修复

下面的实验实现一个最小 Schema 校验器、一个括号平衡的 token 掩码,以及一个去掉代码围栏的修复函数。它不训练模型,只展示结构化输出链路的三个检查点。

# file: agp_lab/schema.py | write
# tier: 3
# verify: python3 -m unittest tests.test_schema
"""结构化输出:最小 JSON Schema 校验、约束词表与修复。"""
from __future__ import annotations

import json
import re

SCHEMA = {
    "type": "object",
    "required": ("tool", "args"),
    "properties": {
        "tool": "str",
        "args": "dict",
    },
    "additional": False,
}

VOCAB = ("{", "}", '"tool"', '"args"', ":", ",", "weather", "search", "null")


def validate(value: object, schema: dict[str, object] = SCHEMA) -> list[str]:
    errors: list[str] = []
    if not isinstance(value, dict):
        return ["root 不是 object"]
    required = schema.get("required", ())
    for key in required:
        if key not in value:
            errors.append(f"缺少字段 {key}")
    properties = schema.get("properties", {})
    for key, expected in properties.items():
        if key not in value:
            continue
        actual = value[key]
        if expected == "str" and not isinstance(actual, str):
            errors.append(f"{key} 应为 str")
        if expected == "dict" and not isinstance(actual, dict):
            errors.append(f"{key} 应为 dict")
    if not schema.get("additional", True):
        for key in value:
            if key not in properties:
                errors.append(f"多余字段 {key}")
    return errors


def allowed_tokens(prefix: str, vocabulary: tuple[str, ...] = VOCAB) -> list[str]:
    """返回能继续构成合法前缀的 token;这里用括号平衡做最小约束。"""
    depth = prefix.count("{") - prefix.count("}")
    if depth < 0:
        return []
    tokens = []
    for token in vocabulary:
        delta = token.count("{") - token.count("}")
        if depth + delta < 0:
            continue
        tokens.append(token)
    return tokens


def repair(text: str) -> dict[str, object]:
    """去掉代码围栏并截取第一个 JSON object。"""
    cleaned = text.strip()
    fence = "`" * 3
    cleaned = re.sub(r"^" + fence + r"(?:json)?\s*", "", cleaned)
    cleaned = re.sub(r"\s*" + fence + r"$", "", cleaned)
    start = cleaned.find("{")
    end = cleaned.rfind("}")
    if start == -1 or end == -1 or end < start:
        raise ValueError("没有 JSON object")
    return json.loads(cleaned[start:end + 1])


if __name__ == "__main__":
    good = {"tool": "weather", "args": {"city": "Shanghai"}}
    print("good:", validate(good))
    print("missing:", validate({"tool": "weather"}))
    print("extra:", validate({"tool": "weather", "args": {}, "date": "x"}))
    print("tokens:", allowed_tokens('{"tool":'))
    wrapped = "`" * 3 + 'json\n{"tool": "search", "args": {"query": "kv"}}\n' + "`" * 3
    print("repair:", repair(wrapped))
```(?:json)?\s*", "", cleaned)
    cleaned = re.sub(r"\s*```$", "", cleaned)
    start = cleaned.find("{")
    end = cleaned.rfind("}")
    if start == -1 or end == -1 or end < start:
        raise ValueError("没有 JSON object")
    return json.loads(cleaned[start:end + 1])


if __name__ == "__main__":
    good = {"tool": "weather", "args": {"city": "Shanghai"}}
    print("good:", validate(good))
    print("missing:", validate({"tool": "weather"}))
    print("extra:", validate({"tool": "weather", "args": {}, "date": "x"}))
    print("tokens:", allowed_tokens('{"tool":'))
    print("repair:", repair('```json\n{"tool": "search", "args": {"query": "kv"}}\n```'))

运行:

cd private/labs/agp-lab
python3 -m agp_lab.schema

输出:

good: []
missing: ['缺少字段 args']
extra: ['多余字段 date']
tokens: ['{', '}', '"tool"', '"args"', ':', ',', 'weather', 'search', 'null']
repair: {'tool': 'search', 'args': {'query': 'kv'}}

good: [] 表示结构合法。注意这只是“没有结构错误”,不代表 tool 的值一定存在、args 的内容一定正确。

missing 和 extra 展示了两个方向:少字段和多字段。少字段通常来自模型漏生成,多字段通常来自模型把描述性信息也塞进参数。两者都应该在执行前拒绝,而不是让工具服务去猜。

tokens 是掩码的简化版:在当前前缀下,词表里所有能继续构成合法括号序列的 token。真实实现会根据完整语法计算,可能只允许特定字段名或特定类型;这里用括号平衡演示“约束是逐步收窄的”。

repair 处理的是另一种常见问题:模型输出了代码围栏。修复函数先去掉围栏,再截取第一个 JSON object。修复必须保守:如果文本里有多个对象,应该拒绝或让模型重新生成,而不是猜哪个是目标。

修复循环的边界

结构化输出经常配一个“解析失败就重试”的循环:

  1. 生成输出。
  2. 解析 JSON。
  3. 校验 Schema。
  4. 失败则把错误信息回填,要求模型修正。
  5. 超过次数则转人工或降级。

这个循环有效,但有三个边界:

  • 错误信息要具体。 只说“格式错误”模型很难修;指出“缺少 args.query”更容易。
  • 重试要有上限。 无限重试会把一次失败放大成成本和延迟。
  • 不能修复语义。 Schema 通过但参数越权,重试不会解决;需要权限检查。

架构含义

结构化输出对架构有四个直接约束:

  1. Schema 单一来源。 工具描述、运行时校验、服务端解析使用同一份定义,避免漂移。
  2. 语法与语义分开。 约束解码/JSON 解析负责语法,Schema 负责结构,业务校验负责内容。
  3. 修复要可观测。 记录修复次数、失败字段和最终结果;否则无法判断模型稳定性。
  4. 失败要可降级。 多次修复失败后,应该有明确的降级路径,而不是继续重试。

第 1 条最容易被忽略。很多团队在提示词里手写一份工具说明,在代码里再写一份校验逻辑,在服务端还有第三份参数解析;三份定义迟早会不一致。把 Schema 作为唯一来源,是结构化输出可维护的前提。

架构判据

判据合格的样子不合格的样子
Schema 唯一描述、校验、解析同源三处各写一份
语法有约束约束解码或严格解析只靠提示词
语义有校验范围、权限、存在性检查Schema 通过就执行
修复有上限次数、成本、延迟都有预算无限重试
失败有降级转人工或返回结构化错误静默返回空对象

这些判据里,“语义有校验”是安全底线。Schema 只能说明形状;一个形状合法的 {"path": "../../etc/passwd"} 仍然可能造成越权。结构化输出让攻击面更规整,但不会自动让系统安全。

Schema 版本管理

Schema 会变:新增字段、废弃字段、修改类型、调整必填。变更如果没有版本,线上会出现三类问题:

变更风险应对
新增必填字段旧提示词生成的调用全部失败先可选,再逐步要求
修改字段类型模型按旧类型生成,运行时拒绝版本化,双读一段时间
删除字段旧调用带多余字段被拒严格模式前先告警

一个可执行的做法是给 Schema 加版本号,并在运行时同时接受相邻两个版本;等评测确认模型和调用方都迁移后,再关闭旧版本。Schema 变更应该像 API 变更一样有兼容窗口,而不是直接热替换。

一个错误示例

假设工具要求 {"tool": "weather", "args": {"city": "Shanghai"}},模型输出:

{"tool": "weather", "args": {"city": "Shanghai"}, "unit": "c"}

如果 Schema 不允许附加字段,这次调用会被拒绝;如果允许,unit 可能被工具服务忽略,也可能被当成未知参数报错。两种行为都不理想。更好的设计是把 unit 放进 args 并声明为可选字段,让“允许什么”在 Schema 里显式表达,而不是靠服务端的宽容或严格来碰运气。

最后要提醒:约束解码和 Schema 校验都应该有测试。测试不应只覆盖合法输入,还要覆盖缺字段、类型错、多余字段、嵌套过深和超长输出;这些才是生产环境里最常见的失败。

小结

  • 结构化输出是“约束解码 + Schema 校验 + 业务校验”的组合,不是一句提示词。
  • Schema 保证类型、必填、结构和附加字段,不保证内容真实、参数合法或权限正确。
  • 约束解码降低语法错误,但会增加每步开销,也可能诱导“语法正确、语义错误”的输出。
  • 修复循环要给出具体错误、设置重试上限,并且不能修复语义问题。
  • Schema 应该单一来源,工具描述、运行时校验和服务端解析共用同一份定义。
  • 语法、结构、语义三层要分开测试;只测 JSON 能不能解析,会漏掉最危险的错误。

阅读导航:上一节:6.1 Function Calling:训练与推理路径 · 下一节:6.3 工具选择错误的分类与评测 。

常见错误与边界

  1. 只靠提示词保证 JSON。 长输出会漂移;语法约束或严格解析必须至少有一层。
  2. 把 Schema 当内容校验。 类型正确不代表值正确;范围、权限、存在性要单独检查。
  3. 三处各写一份 Schema。 描述、校验、解析会漂移;应使用单一来源。
  4. 无限重试。 重试要有次数、成本和延迟上限,否则一次失败会放大成事故。
  5. 修复时猜目标对象。 多个 JSON 对象时应拒绝或重新生成,不要静默选一个。
  6. 把约束解码当安全措施。 合法形状仍可包含越权参数;执行前必须有权限和范围检查。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图