结构化输出失败怎么配置或排查

结构化输出失败时，先别急着改提示词。多数问题发生在三层之一：当前 provider 或模型不支持 schema 约束，response_format 的嵌套结构不符合接口要求，或者服务端已经返回文本但本地解析方式不对。把模型、provider 和最小 JSON Schema 固定下来，通常比反复重试更快。

官方地址：https://huggingface.co/docs/inference-providers/en/guides/structured-output

结构化输出失败，先确定是哪一层不兼容

Hugging Face 文档把 JSON mode 和 Structured Outputs 分开：前者主要保证结果是合法 JSON，后者还要求结果符合预先给出的 schema。因此仅把提示词改成“请返回 JSON”，不能替代 type=json_schema。

如果错误发生在请求发送前，先看参数形状；如果请求成功但结果不稳定，再看模型和 provider 的支持列表；只有拿到正文后才进入 JSON 解析排查。三类错误不要混在同一个重试循环里。

先用最小 JSON Schema 把配置跑通

调试时建议先只保留字符串和字符串数组，去掉默认值、复杂联合类型和过多格式限制。下面的例子让模型抽取书名和作者，schema 由 Pydantic 生成，再按 Hugging Face 文档要求放进 json_schema。

import json
import os
from pydantic import BaseModel
from huggingface_hub import InferenceClient

class BookInfo(BaseModel):
    # 先用简单字段，确认 provider 能处理基本 JSON Schema
    name: str
    authors: list[str]

client = InferenceClient(
    # 调试阶段固定 provider，避免自动路由更换能力边界
    provider="cerebras",
    api_key=os.environ["HF_TOKEN"],
)

schema = {
    "name": "book",
    "schema": BookInfo.model_json_schema(),
    # 让服务端按 schema 约束输出，而不只是返回合法 JSON
    "strict": True,
}

completion = client.chat.completions.create(
    # 模型与 provider 要使用当前文档列出的兼容组合
    model="Qwen/Qwen3-32B",
    messages=[
        {"role": "system", "content": "Extract the book information."},
        {"role": "user", "content": "我读过《了不起的盖茨比》，作者是 F. Scott Fitzgerald。"},
    ],
    response_format={
        "type": "json_schema",
        "json_schema": schema,
    },
)

# 只解析消息正文，保留完整 completion 便于记录错误上下文
raw_content = completion.choices[0].message.content
book = json.loads(raw_content)
print(book["name"], book["authors"])

这里有两个容易写错的层级：type 是 response_format 的字段，name、schema、strict 则放在 json_schema 内。若服务端提示字段未知，不要继续加参数，先对照 provider 的接口文档确认它支持的 OpenAI 兼容子集。

把排查结果固定成发布前检查清单

最小例子成功后，再一次只增加一个变化：先加整数或枚举，再加嵌套对象，最后才加入业务字段。每次都记录这组组合，便于区分“模型不支持”与“Schema 变复杂后不兼容”。

• 能力：provider 和 model 是否明确，文档是否说明支持 Structured Outputs，而不只是 JSON mode。
• 形状：properties 里的字段名、类型与 required 是否一致；数组是否声明了 items。
• 响应：保存原始响应、HTTP 错误和请求组合，只对 message.content 调用 json.loads。
• 降级：如果业务只需要合法 JSON，可以明确退回 JSON mode；如果依赖字段完整性，就不能把它当成等价方案。

自托管 vLLM 时还要单独核对服务端版本与 structured outputs backend。当前 vLLM 文档中的 backend 默认是 auto，不同 backend 对 schema 特性的支持并不完全相同；不要把 Hugging Face provider 的请求体原样复制到本地服务后就认为能力一致。

相关问题

为什么提示词要求 JSON 仍然会失败？

提示词只是在表达意图，不能替代 provider 的结构化解码或 schema 校验；需要字段契约时应使用 json_schema。

结构化输出一定不需要重试吗？

它能减少格式错误，但网络超时、provider 限流和业务语义错误仍需处理。格式稳定不等于业务结果正确。

复杂 Schema 一上来就报错怎么办？

退回字符串和字符串数组的最小版本，固定 provider 与 model，再逐层增加字段；每次只改一处，错误边界最清楚。