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

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

原文: https://fdetimes.net/zh/guides/structured-outputs-strict-schema-refusals-truncation/

响应返回 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 同时遵守这两条规则，两家服务商都能用。

```python
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 位于响应的文本内容块中。简化版如下：

```python
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 可能不完整。

```python
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` 字段，读取解析后的内容之前必须先检查它。

```python
# 简化版：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` 字段 |

**要点:** 200 状态码只说明请求跑完了，不说明数据可用。

## 第 4 步：截断的输出可以重试，但要设上限

Anthropic 建议调高 `max_tokens` 后重新发送，以拿到完整的 JSON。其余的由你来设计。一种合理的做法是每次翻倍，1024、2048、4096，试三次就停，免得一封异常邮件无休止地烧 token。

```python
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 里删掉的约束，在这里用你自己掌控的代码重写。

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

**本周动手试试:**

- 找到一处直接对模型输出调用 json.loads 的地方，在那一行之前加上 stop_reason 或 status 检查
- 检查现有的 Schema，找出 minimum、maxLength 之类的约束，从 Schema 中删掉，改写成一个 validate 函数
- 故意用很低的 max_tokens 发一个请求，确认截断输出的分支运行正确

## 信源

- [Structured outputs - Claude API Docs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

- [Structured Outputs - OpenAI API docs](https://developers.openai.com/api/docs/guides/structured-outputs)

- [OpenAI: Introducing Structured Outputs (Simon Willison)](https://simonwillison.net/2024/Aug/6/openai-structured-outputs)

- [Structured output - Gemini API docs](https://aistudio.google.com/docs/structured-output)
