结构化输出实测:解析可靠但更耗 Token
作者用仓库中的 9 份真实差异,对比纯提示词与 Claude CLI JSON Schema 约束下的自动合并判断。文章报告 Schema 方案未出现解析失败,但 Token 消耗达到三倍;该小样本结果不能直接证明判断本身更准确。
AI 深度解读
让 AI 返回 JSON,提示词写得再严,也可能多出一层 Markdown 代码围栏,直接把解析器卡住。作者用同一模型、同一提示词,对 9 份真实 git diff 做了对照:仅靠提示词成功 8 次,启用 JSON Schema 的版本成功 9 次。
但格式稳定有多贵,这次实验没有算清。它记录到了结构化调用的费用,却没有普通调用的用量数据。对程序员来说,最值得看的是如何区分格式可靠性、判断正确性和调用成本,而不是照着标题接受「三倍 token」的结论。
9 份真实 diff,测的是输出能不能接住
作者原本在 my-git-manager 仓库里运行 git_commit.py,通过 claude -p 生成一行 Conventional Commit 消息,返回纯文本,没有使用 schema。这次他们另选了一个更接近 CI 机器人的任务:读完 diff,判断能否自动合并,还是需要人工审核。
样本来自仓库自身的 git 历史,通过 git show <commit> 提取,共 9 份,主要是文档日志提交,另有两份真实代码修复。每份 diff 最多 6,000 个字符。
两个版本使用同一提示词、同一模型,每份样本各跑一次。输出都要求包含三个字段:risk 只能取 low、medium、high;reason 是简短原因;requires_human 是布尔值。
普通版本通过 subprocess.run() 执行 ["claude", "-p", "--output-format", "text", prompt]。提示词明确要求只返回 JSON 对象,但 9 次里仍有一次加上了 Markdown 代码围栏。
这不是风险等级填错,而是整个字符串已经不符合 JSON 语法。json.loads() 读到开头的反引号,就抛出 Expecting value: line 1 column 1。
程序接收模型输出时,格式接近正确仍然可能等于调用失败。
Schema 把格式要求变成了可验证的约束
另一组调用使用 Claude CLI 的 --json-schema <schema>。原文给出的参数说明是:它用于结构化输出验证,且只支持 --print 模式;示例实际使用的是 -p。
下面这段代码约束了字段、类型和枚举,并在调用时传入 schema:
SCHEMA = {
"type": "object",
"properties": {
"risk": {"type": "string", "enum": ["low", "medium", "high"]},
"reason": {"type": "string"},
"requires_human": {"type": "boolean"}
},
"required": ["risk", "reason", "requires_human"],
"additionalProperties": False
}
r2 = subprocess.run(
["claude", "-p", "--output-format", "json", "--json-schema", json.dumps(SCHEMA), prompt],
capture_output=True, text=True,
)
要看的是 required 和 additionalProperties: False:前者要求三个字段全部存在,后者禁止额外字段;enum 则限制了 risk 的取值范围。
这组调用 9 次全部解析成功,字段齐全,风险值也都在枚举内。相比在提示词里反复叮嘱,schema 给程序提供了明确的输出契约。
不过,契约管的是结构。一个把危险修改判断为 low、同时返回 requires_human: false 的对象,依然可能完全符合这份 schema。原文没有给出风险分类的人工标准答案,也没有评估自动合并判断是否正确。
费用看到了,三倍 token 没有证实
作者真正意外的是调用元数据。--output-format json 会返回完整调用信息,其中一个示例的 total_cost_usd 为 0.132520,usage 包含 input_tokens: 2、cache_creation_input_tokens: 15409,以及 cache_read_input_tokens 等字段。
9 次结构化调用中,费用大致为每次 $0.13;首次调用在尚未建立缓存时达到 $0.36。作者还观察到,每次约有 15,400 个 token 被写入缓存。仅凭最多 6,000 字符的 diff,无法解释全部输入开销。
作者据此认为,schema 路径还有工具定义、schema 定义及结构化处理等准备成本。但这部分是作者对现象的解释,实验没有把各项开销拆开测量。
更关键的是,普通版本使用 --output-format text,没有暴露用量元数据,因此缺少同轮实验的成本基线。标题里的「三倍 token」,正文没有提供可复算的对照依据;约 15,400 个缓存写入 token,也不能全部算成 schema 新增的成本。
这次实验验证了结构化输出在这 9 个样本中的格式表现,没有验证成本增加了几倍。
我的判断
作者做对的一点,是拿自己的真实输入验证热门建议,并且没有因为一次小实验就改写 git_commit.py。相比只展示一个成功示例,这组对照更有参考价值。
但 8/9 约等于 89%,1/9 约等于 11%,都只是本轮观测比例。样本少、文档修改占多数、每份只运行一次,不能直接推算成日常调用的长期失败率;9/9 也不等于以后不会失败。原文还没有说明具体模型版本,以及如何从完整调用结果中提取业务对象,复现实验仍缺信息。
对于唯一出现的代码围栏问题,清理围栏后再解析确实是一个轻量替代方案。它是否比 schema 便宜,作者没有给出对照数据;而且清理围栏解决不了字段缺失、类型错误或错误的风险判断。
我的取舍是:由失败后果决定约束强度。单行提交消息可以接受有限清理;会驱动自动合并的结果,则需要结构校验和业务规则共同把关。
能拿来做什么
- 在 Node 或 Python 的 AI 输出消费端,把 JSON 解析、字段校验和业务判断分开处理,让日志能区分失败发生在哪一步。
- 为 CI 风险分类收集真实 diff,重复运行提示词版和 schema 版,并用人工标注检查分类结果,别只统计能否解析。
- 做成本比较时,让两组都留下可比较的费用和用量记录,分别观察输入、输出、缓存创建与缓存读取,再判断是否值得增加约束。
- 对提交消息等低风险文本,可以先清理已知的代码围栏;对自动合并结果,即使 schema 校验通过,也要检查
risk与requires_human是否符合团队规则。