严格 Schema 也挡不住拒答和截断的 JSON
Claude 拒答时照样返回 200、全额计费,解析之前先看停止信号。
要点速览
- 使用 Claude 时,拒答照样返回 200 状态码,照样按 token 计费,JSON 也可能不符合 Schema
- JSON 因 max_tokens 被截断时,响应会带有专门的信号;Anthropic 建议调高 max_tokens 后重新发送
- 符合 Schema 的 JSON 不一定取值正确:务必在应用中校验取值
响应返回 200 状态码,每个 token 都照常计费,可里面的 JSON 却不符合你发送的 Schema。在 Claude 上,这不是系统故障,而是模型拒答了。Anthropic 的文档写得很明确:模型拒答时,拒答消息优先于 Schema 约束。
很多人以为打开 strict 就够了。实际上,strict 只在模型完整作答时保证 JSON 结构。还剩两种情况:模型拒答,或者输出触及 token 上限、中途被截断。Claude 的拒答看起来和成功响应一模一样。截断的输出确实带有自己的停止信号,但只有读了这个信号的人才会发现。
如果你是前线部署工程师(FDE),要把数据抽取管道接入客户系统,演示版和生产版恰恰在这三个分支上分道扬镳。下面按检查顺序,逐个搭建这三个分支。
要做什么,需要准备什么?
贯穿全文的是一个假设的例子。函数 extract_invoice(text) 读取客户的发票邮件,返回一个 dict,包含供应商、发票号、总额和币种。拿不到可用结果时,函数抛出命名清晰的错误,而不是任由各种异常往外冒。
你需要 Python、一个 Claude 或 OpenAI 的 API key,以及几封示例邮件。下面的代码块做了简化,方便看清逻辑。具体字段名和 SDK 调用请对照服务商当前的文档。
第 1 步:API 接受什么样的 Schema?
先从 Schema 入手,因为很多 400 错误在这里就已经埋下了。Anthropic 只允许把 additionalProperties 设为 false,不支持递归 Schema、外部 $ref 引用,也不支持数值和字符串约束。
Simon Willison 在介绍 OpenAI 严格模式时补充:在那里,对象的每个键都必须出现在 required 中。下面的 Schema 同时遵守这两条规则,两家服务商都能用。
INVOICE_SCHEMA = {
"type": "object",
"properties": {
"vendor": {"type": "string"},
"invoice_number": {"type": "string"},
"total": {"type": "number"},
"currency": {"type": "string"},
},
"required": ["vendor", "invoice_number", "total", "currency"],
"additionalProperties": False,
}
注意这里有意省掉的内容:total 没有 minimum,currency 没有长度限制。在 Anthropic 上使用不支持的特性,会返回带详细信息的 400 错误。Gemini 那边,Google 也提醒,过大或嵌套过深的 Schema 可能被拒绝,返回 400 INVALID_ARGUMENT。
**检查:**发一个测试请求。如果收到 400,先读错误详情、改好 Schema,再写下一行代码。
第 2 步:带上 Schema 发送请求
在 Claude 上,Schema 放在 output_config.format 里,type: "json_schema",合法的 JSON 位于响应的文本内容块中。简化版如下:
request = {
"model": MODEL,
"max_tokens": 1024,
"messages": [{"role": "user", "content": prompt}],
"output_config": {
"format": {"type": "json_schema", "schema": INVOICE_SCHEMA}
},
}
如果用 OpenAI,不要把 JSON mode 和 Structured Outputs 混为一谈。OpenAI 说得很直白:两者都能产出合法 JSON,但只有 Structured Outputs 保证符合 Schema,并建议始终使用 Structured Outputs。Willison 的看法是,99% 的情况下你都会想打开 "strict": true。
**检查:**从第二个请求开始测延迟。Willison 指出,每个 Schema 的第一个请求都比较慢,因为 Schema 需要预处理。拿第一个请求做基准测试,只会白白吓到自己。
第 3 步:解析之前先读停止信号
这是最常被跳过的一步。不要直接调用 json.loads。在 Claude 上,拒答时 stop_reason 为 refusal;输出被截断时 stop_reason 为 max_tokens,此时 JSON 可能不完整。
class Refused(Exception): pass
class Truncated(Exception): pass
def read_claude(response):
if response.stop_reason == "refusal":
raise Refused(response)
if response.stop_reason == "max_tokens":
raise Truncated(response)
text = next(b.text for b in response.content if b.type == "text")
return json.loads(text)
OpenAI 的信号在别处。输出被截断时,response.status 为 incomplete,incomplete_details.reason 为 max_output_tokens。Willison 介绍,模型拒答时,你拿到的是一条单独的拒答消息,而不是遵循 Schema 的 JSON。由于拒答可能不遵循 Schema,API 额外提供了一个 refusal 字段,读取解析后的内容之前必须先检查它。
# 简化版:refusal 字段和内容的具体位置
# 取决于你使用的端点,请查阅 OpenAI 文档
def read_openai(response, output):
if response.status == "incomplete" and \
response.incomplete_details.reason == "max_output_tokens":
raise Truncated(response)
if getattr(output, "refusal", None):
raise Refused(output.refusal)
return json.loads(output.text)
| 情况 | Claude | OpenAI |
|---|---|---|
| 模型拒答 | stop_reason 为 refusal,状态码 200,照样计费 |
单独的 refusal 字段,不遵循 Schema |
| 触及 token 上限被截断 | stop_reason 为 max_tokens |
status 为 incomplete,原因为 max_output_tokens |
| 解析前要做什么 | 读 stop_reason |
先读 status,再读 refusal 字段 |
第 4 步:截断的输出可以重试,但要设上限
Anthropic 建议调高 max_tokens 后重新发送,以拿到完整的 JSON。其余的由你来设计。一种合理的做法是每次翻倍,1024、2048、4096,试三次就停,免得一封异常邮件无休止地烧 token。
def extract_invoice(text, budgets=(1024, 2048, 4096)):
for max_tokens in budgets:
try:
return read_claude(call(text, max_tokens))
except Truncated:
continue
raise Truncated("token 预算已用完")
拒答需要完全不同的处理:不要盲目重试。每次拒答照样计费,同样的输入再发一遍,没有理由指望结果会变。把这类情况推进队列,交给人工审核。
**检查:**用一封长邮件调用 call(text, 50)。必须走到 Truncated 分支,json.loads 不能抛出解析错误。
第 5 步:Schema 合法不等于取值合法
Google 在 Gemini 文档里说得很直接:语法正确的 JSON,仍需在应用中校验取值。第 1 步从 Schema 里删掉的约束,在这里用你自己掌控的代码重写。
def validate(inv):
errors = []
if inv["total"] < 0:
errors.append("总额为负数")
if len(inv["currency"]) != 3:
errors.append("币种不是 3 位字母代码")
if not inv["invoice_number"].strip():
errors.append("缺少发票号")
return errors
设想一封邮件只写了“总额按上周报价”。由于所有键都在 required 中,Schema 强制每个键都要有,你很可能拿回一个空的 invoice_number。Schema 依然完全匹配,但客户的财务系统不会接受这一行。
哪些错误容易犯?
一个常见错误是先解析、后检查:拒答会被误当成 JSON 错误,记到错误的分类下。另一个是在 OpenAI 严格模式下把可选键漏出 required。还有,别把业务规则硬塞进 Schema,否则可能要花一整个下午排查 400 错误。
如果你用的是严格工具调用(strict tool use)而不是输出格式,记住 Anthropic 限制每个请求最多 20 个严格工具。工具列表不断变长的 Agent,会比你预想的更早撞上这个上限。
这项技能在客户现场怎么体现?
设想第一次用真实数据做评审,客户问管道有多大比例能正常工作。上面三个命名异常就能给出答案:分别统计拒答、截断和校验不通过的记录。在第一周就把这三个数字放上看板,别等人来问。
从职业发展看,简历里写一句“基于严格 Schema 搭建抽取管道,分别处理拒答和截断输出,并按类别统计错误指标”,就能让招聘方看到你真正把东西交付到了生产环境。职位描述里提到“生产环境中的 LLM”时,需要的很可能正是这项技能。
拿到符合 Schema 的输出,是结构化输出里最容易的部分。输出不合法时知道该怎么办,才是你值得被录用的地方。
这篇文章对你有帮助吗?
感谢你的反馈!