AI 资讯 知识库 智能体生态观察智能体生态观察 · 第 48 篇|结构化输出约束:JSON Schema、语法约束与格式保证

智能体生态观察 · 第 48 篇|结构化输出约束:JSON Schema、语法约束与格式保证

智能体系统里有一类最不起眼却最致命的故障:模型明明答对了,系统却读不懂。一次典型事故,是上游模型在 JSON 前多客套了一句「好的,以下是提取结果」,下游解析器当场报废,重试三次仍失败,队列开始积压。这类事故与模型能力无关——再聪明的模型也可能多写一句话。智能体之间靠结构说话,模型却天生爱自由发挥,格式保证因此成为第一道工程门槛。本篇按约束强度盘点四档技术,再给出实践守则与生态现状。

手绘信息图:从 prompt 声明到语法锁死再到后校验兜底,四档结构化约束技术按可靠性递进排列

格式失败的真实代价

第一类代价是解析失败的重试税。自由文本里的 JSON 经常带着 markdown 围栏、尾逗号、中文标点、多余的前后缀客套,解析器一失败就触发重试,延迟与费用成倍增长。更糟的是失败率与任务难度正相关——越是复杂的任务,模型越可能在长输出中途断裂,恰恰是最重要的那次调用最不稳定。重试税还常被记错账——它被计入「模型不稳定」,而真正的根因多数时候是格式契约没谈拢。

第二类代价更隐蔽:静默错位。输出是合法 JSON,字段却与约定不符——user_name 写成了 username,嵌套层级多包了一层,或者把「未提供」填成了空字符串。下游不报错,数据照单全收,错误沿着管道漂到很远才被发现。与显式解析失败相比,静默错位不触发任何告警,是格式问题里最贵的一种。第三类代价发生在评估环节:格式抖动会让同一模型在同一基准上跑出方差很大的分数,能力差异被格式噪声淹没,评测结论变得不可比——团队据此做的技术选型,从第一天起就带着误差。

以一条表单抽取管道为例:模型从合同 PDF 里抽出付款条款存进数据库。格式漂移的演化路径很有代表性——头几天只有零星重试,没人在意;接着模型学会了一种「合法但错误」的写法,把日期填进备注字段,报表开始出现离谱的账期;最后某次模型升级,输出彻底换了嵌套结构,管道瘫痪。三类代价在这条管道里依次上演,而团队在每个阶段的第一反应都是「再加点提示词」。

静默错位难发现,还因为它伪装成业务问题:字段错位导致的数据异常,第一波锅总是甩给上游业务系统或人工录入,等排查到模型头上时,错误数据可能已经污染了下游的统计与决策。格式问题必须有自己的监控口径——按 schema 校验的通过率、字段的空值率、枚举值的分布漂移——而不是混在业务告警里等意外发现。

这三类代价指向同一个结构性事实:自然语言是模型的原生输出,结构只是它「努力配合」的产物。不把结构变成硬约束,每一次调用都是一次概率事件,而工程系统的地基不能建立在概率事件上。

格式失败有三张账单:重试的延迟与费用、静默错位的下游事故、评估失真的决策成本。

四档约束技术:从尽力而为到 token 级锁死

第一档是 prompt 声明:在提示词里给出 schema 与示例,请模型「按格式输出」。零成本、随处可用,但本质是恳求——模型偶尔忘、偶尔自由发挥,可靠性随输出长度下降,少样本示例能改善却挡不住长尾。第二档是 schema 硬约束,即推理时约束解码:把 JSON Schema 编译成文法,生成时逐步屏蔽不合法的 token,让结构错误在物理上不可能发生。OpenAI 在 2024 年 8 月上线的结构化输出(strict 模式)即此路线,官方将其实现描述为把 schema 编译成上下文无关文法后做约束解码;Anthropic 随后跟进基于 output_format 的同类能力,截至 2026-11,主流托管 API 均已提供。第三档是开源侧的语法约束:Outlines、llama.cpp 的 GBNF、XGrammar 等库在本地推理栈直接做文法级锁死,连枚举取值与括号配对都写进状态机。

约束解码的工作方式值得讲透一层。生成每一步时,模型输出的是整个词表上的概率分布;约束层根据当前已生成内容在文法里的状态,算出哪些 token 合法,把非法位置的分数压成负无穷,再从中采样。对工具调用生态而言,这一层是隐形的地基——各家 API 的工具调用协议之所以能做到「参数结构永远合法」,靠的正是同一套机制作用在参数区间上。理解了这点就明白:结构化输出的成本主要是工程成本——schema 编译器的质量、文法与分词器的兼容性——而不是推理算力。

第四档是后校验与修复:无论前面几档,产线终归要一道校验器——按 schema 校验字段,按业务规则校验取值区间,失败时把错误信息回灌给模型限时重试,或降级到人工。四档不是互斥的备选,而是叠加的防线:硬约束消灭语法错误,后校验兜住语义错误。后校验还有一个硬理由:它同时是观测手段。校验器记录每次失败的分布,就是格式质量的实时仪表——硬约束上线后语法失败率应趋近于零,若某个字段持续触发业务校验失败,问题多半在 schema 设计或提示词,而不是模型。校验器因此身兼两职:产线的守门员,与调优的仪表盘。

两个必须写进设计文档的坑。其一,语法正确不等于语义正确——约束解码保证的是「能解析」,字段值依然可能张冠李戴,能在 schema 里写 enum、写 pattern 的就不要靠模型自觉。其二,强约束可能伤内容质量:已有研究提示,把格式枷锁直接套在推理过程上会挤占模型的思考空间;两段式是常见解法——先让模型自由推理,再让它把结论填进结构,或在工具调用协议里为「思考」留出独立字段。

import json
from jsonschema import validate, ValidationError

TICKET_SCHEMA = {
    "type": "object",
    "properties": {
        "ticket_id": {"type": "string", "pattern": "^TK-\\d{6}$"},
        "priority": {"type": "string",
                     "enum": ["low", "medium", "high", "urgent"]},
        "summary": {"type": "string", "minLength": 5},
    },
    "required": ["ticket_id", "priority", "summary"],
    "additionalProperties": False,
}

def parse_ticket(text: str, call_model) -> dict:
    for _ in range(2):                    # 最多修复一次
        raw = call_model(text)
        try:
            data = json.loads(raw)
            validate(data, TICKET_SCHEMA)
            return data
        except (ValidationError, ValueError) as err:
            text = raw + f"\n上次输出不合法:{err}。只输出 JSON。"
    raise FormatError("结构化输出连续失败,转人工队列")

四档是叠加的防线:声明管常规,硬约束管语法,校验器管语义,重试与降级管长尾。

生态现状:能力差异与库生态

截至 2026-11,主流托管 API 的结构化输出在方向上已趋同——都支持按 schema 约束生成,差异在细节:OpenAI 的 strict 模式对 schema 子集有严格限制,例如要求关闭额外字段、部分可选字段要用特殊写法表达;Anthropic 走 output_format 字段并强调与工具调用协议的配合;Gemini 提供 responseSchema 与枚举约束。各家差异的另一处体现在拒绝与截断的处理:结构化模式下模型也可能拒答或被长度上限截断,调用契约里要给这两种情况留位置——它们不违反 schema,但会让「拿到完整结构」落空。托管之外,vLLM、SGLang 等自托管推理引擎把文法约束做成了启动参数,本地部署也有了对齐的选项。

库生态把「写 schema、拿对象」的胶水层做厚了。Pydantic 与 Zod 已成为两端的通用语言:Python 侧的 Instructor、Pydantic AI 允许把类型定义直接交给调用层,由库负责 schema 生成、校验与重试;TypeScript 侧的 Zod schema 可同时供运行时校验与 API 参数使用。评价一个智能体框架是否工程成熟,结构化输出的支持深度——能否声明式定义、失败后是否有内置重试、流式输出下如何增量解析——是比模型适配数量更可靠的指标。

流式场景给结构化出了新题:JSON 没写完就没法整体解析,前端却想逐字段渲染。工程上的应对是增量解析——边收边喂给容错解析器,或让 schema 声明字段顺序、按顺序切片。另一条选型经验是别把四档用成单选:常见组合是「托管 API 的硬约束加自建业务校验器加失败回灌」,三件套各自兜一层。选型时先问两个问题:输出给谁消费、失败重试几次划算——答案会直接排除一半选项。

档位 机制 可靠性 主要代价
prompt 声明 提示词加少样本示例 不稳定 长输出易漂移
schema 硬约束 推理时屏蔽非法 token 语法层接近百分百 依赖 API,schema 受限
语法约束 文法状态机锁死 token 同上且文法可自定义 可能压低生成质量
后校验修复 校验器加错误回灌重试 兜底语义层 增加延迟与调用成本
flowchart LR
  A["prompt 声明:尽力而为"] --> B["schema 硬约束:推理时屏蔽非法 token"]
  B --> C["语法约束:文法级锁死"]
  C --> D["后校验修复:语义兜底"]

托管 API 与本地引擎方向趋同,库生态把胶水做厚——结构化输出正在从可选特性变成默认假设。

实践守则:何时硬约束,何时留白

第一条守则是按消费者选档。给机器读的输出——工具调用参数、管道中间产物、入库记录——一律硬约束加校验器,可靠性优先;给人读的输出——回答正文、创意文案——保留自然语言,把结构限制在包裹层,标题、分节、引用块,内容本身不锁。最常见的反模式是把整篇回答压进一个巨型 JSON:既伤表达,又把解析失败的爆炸半径扩大到全文。

第二条守则把 schema 当提示词写。字段名就是模型的指令:让「思考」字段排在「答案」字段之前,比在提示词里叮嘱「请先思考」更有效;描述字段写清取值边界,能穷举就用 enum,不要留自由字符串。第三条守则是错误处理要分级:校验失败先带错误回灌重试一至两次;仍失败则降级——换更短的 schema、切换到自由文本加人工复核、或直接拒答。把「格式失败」当成一等错误类型来设计,而不是当成不会发生的意外。

第四条守则关乎 schema 的生命周期。schema 一旦被下游消费,就成了对外承诺:改字段名等于改接口,删字段等于破坏兼容。成熟团队会给 schema 做版本管理,新字段一律可选、旧字段废弃走过渡期;评估集里也要保留历史 schema 的用例,防止升级模型时老管道悄悄断裂。结构不是一次性的格式声明,它是会随业务生长的合同,合同的每次修订都要留痕。

第五条守则是给「格式自由」留出正当性。不是所有输出都该被锁死:开放讨论、头脑风暴、长文写作里,过早引入结构会杀死思路。判断的尺子还是消费者——机器消费的出口越窄越好,人消费的出口越自然越好;一条管道的两端往往各占其一,别用同一把锁锁两端。

硬约束给机器消费的出口,自然语言留给人消费的出口,schema 本身是一份写给模型的合同。

小结

结构化输出的成熟度直接决定智能体系统的下限:上限由模型决定,下限由最脆弱的那次格式解析决定。四档技术按可靠性递进、按成本叠加,托管的硬约束加自建的后校验是当前产线的主流组合。两个原则值得贴在墙上:语法保证不了语义,schema 是提示词的延伸。当团队开始把「格式失败」当成一等错误来设计时,智能体工程才算真正跨过了地基这一课。对还在用「提示词恳求」的团队,迁移路径也现成:先把 schema 立起来接上校验器,再逐步切换到硬约束——格式这一课的学费,早交比晚交便宜得多。

读者留言

COMMENTS 暂无
仅本站原创文章开放留言 · 请勿留下手机号、邮箱等个人信息

还没有留言,来说第一句?