FDE Times 数据在招 FDE 职位 881▼8 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 55在招公司 185支持远程 25%美国薪资中位数 $201k招聘最多 Databricks 98
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

严格 Schema 也挡不住拒答和截断的 JSON

Claude 拒答时照样返回 200、全额计费,解析之前先看停止信号。

分享微博

要点速览

  • 使用 Claude 时,拒答照样返回 200 状态码,照样按 token 计费,JSON 也可能不符合 Schema
  • JSON 因 max_tokens 被截断时,响应会带有专门的信号;Anthropic 建议调高 max_tokens 后重新发送
  • 符合 Schema 的 JSON 不一定取值正确:务必在应用中校验取值
决策树:解析 JSON 之前先检查 stop_reason。若为 refusal,把响应送进人工审核队列,不盲目重试;若为 max_tokens,依次用 1024、2048、4096 个 token 重试,3 次后停止;其他情况调用 json.loads 后再做校验,因为取值仍可能出错。
使用 Claude 时,拒答照样返回 200 状态码,照样按 token 计费。每种 stop_reason 取值都要单独处理,之后才能信任 JSON。来源:文中引用的 Anthropic 结构化输出文档。

响应返回 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 的输出,是结构化输出里最容易的部分。输出不合法时知道该怎么办,才是你值得被录用的地方。

这篇文章对你有帮助吗?

4 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力电力公司里,GIS 和 SCADA 对不上往往不是 bugGIS 记录电网按设计如何运行,SCADA 记录电网此刻如何运行,分清两者能少白忙几周。