以下数字为教学示例,不构成对任何真实模型或供应商训练结果的承诺。
让模型输出 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。修复必须保守:如果文本里有多个对象,应该拒绝或让模型重新生成,而不是猜哪个是目标。
修复循环的边界
结构化输出经常配一个“解析失败就重试”的循环:
- 生成输出。
- 解析 JSON。
- 校验 Schema。
- 失败则把错误信息回填,要求模型修正。
- 超过次数则转人工或降级。
这个循环有效,但有三个边界:
- 错误信息要具体。 只说“格式错误”模型很难修;指出“缺少 args.query”更容易。
- 重试要有上限。 无限重试会把一次失败放大成成本和延迟。
- 不能修复语义。 Schema 通过但参数越权,重试不会解决;需要权限检查。
架构含义
结构化输出对架构有四个直接约束:
- Schema 单一来源。 工具描述、运行时校验、服务端解析使用同一份定义,避免漂移。
- 语法与语义分开。 约束解码/JSON 解析负责语法,Schema 负责结构,业务校验负责内容。
- 修复要可观测。 记录修复次数、失败字段和最终结果;否则无法判断模型稳定性。
- 失败要可降级。 多次修复失败后,应该有明确的降级路径,而不是继续重试。
第 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 工具选择错误的分类与评测 。
常见错误与边界
- 只靠提示词保证 JSON。 长输出会漂移;语法约束或严格解析必须至少有一层。
- 把 Schema 当内容校验。 类型正确不代表值正确;范围、权限、存在性要单独检查。
- 三处各写一份 Schema。 描述、校验、解析会漂移;应使用单一来源。
- 无限重试。 重试要有次数、成本和延迟上限,否则一次失败会放大成事故。
- 修复时猜目标对象。 多个 JSON 对象时应拒绝或重新生成,不要静默选一个。
- 把约束解码当安全措施。 合法形状仍可包含越权参数;执行前必须有权限和范围检查。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。