Claude 结构化输出报 400:Schema 与引用冲突怎么排查
Claude JSON 输出和 strict 工具调用约束不同。本文给出最小请求、Schema 复杂度与 citations 冲突的排查步骤。
Claude Messages API 的结构化输出有两种:output_config.format 约束最终 JSON 回答,工具定义中的 strict: true 约束工具名和输入参数。若请求直接报 400,应先检查字段、Schema 和组合功能,而不是反复改提示词。直接依据 Anthropic 结构化输出指南。
先用最小请求确认字段
JSON 输出应在顶层提供 output_config.format,格式类型为 json_schema,并附上对象 Schema。旧 output_format 字段已弃用;官方说明未加对应 beta header 时会返回 400。下面只展示请求体形状,模型 ID 须以账号实际权限为准,密钥从环境变量读取,不写入脚本或日志。
{"model":"claude-sonnet-5-5","max_tokens":256,"messages":[{"role":"user","content":"提取示例标题"}],"output_config":{"format":{"type":"json_schema","schema":{"type":"object","properties":{"title":{"type":"string"}},"required":["title"],"additionalProperties":false}}}}三个容易忽略的限制
第一,Schema 过于复杂:官方列出每请求至多 20 个 strict 工具、24 个可选参数和 16 个联合类型参数,深层嵌套还可能触发语法编译错误。第二,文档 citations 与严格 JSON 输出不能同用,因引用块需要和文字交错,组合请求会返回 400。第三,严格模式只保证格式,不能保证提取出的事实正确;应用仍要做业务校验。
排查与修复顺序
- 保留 HTTP 状态、错误类型和请求 ID;脱敏后缩到单条消息、一个对象字段,确认账号与模型支持该功能。
- 若最小请求成功,逐项加回字段、可选参数、联合类型及 strict 工具,找出首次失败的 Schema 变化;必要时拆分请求。
- 若启用 citations,先移除 JSON 格式约束做对照。需要每个字段附出处时,按官方建议生成可解析的逐行文本,再由应用解析。
- 对成功响应检查 JSON 可解析性、必填字段、枚举大小写和业务规则;对失败响应避免无限重试。
时延、缓存与中转边界
Anthropic 说明首次 Schema 编译增加时延,编译产物可缓存 24 小时;改变 Schema 结构或工具集合会使其失效。格式约束还会增加部分输入 token,并可能影响提示词缓存。经 LondAI 中转时,需另行验证字段透传、模型权限和真实费用;本文未修改网关,也未用本站 Key 做调用。
上线验收
准备合法 Schema、过度复杂 Schema、citations 冲突、无权限及流式请求样本。正常结果须满足 Schema 和业务规则;错误须可诊断,且不会造成重复处理。通用接口说明见 LondAI API 文档。