模型接口怎样约束输出为可解析结构

模型接口要返回可解析结构，不能只在提示词里写一句“请输出 JSON”。更稳的做法是把下游真正需要的字段写成 JSON Schema，再通过接口提供的 response_format 或 grammar 参数交给生成端约束，收到结果后立即解析，并单独检查业务值。

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

结构化输出解决的是“形状能否被程序读取”，不是“模型填入的事实一定正确”。先定义最小 Schema，再选择支持它的模型和提供方，最后把结构错误、接口错误与业务校验错误分开处理。

Hugging Face 的 Inference Providers 文档给出了 JSON Schema 结构化输出示例：可以用 Pydantic 生成 Schema，也可以通过兼容接口传递 response_format；其 Transformers 文档还说明了原始 token 流需要经过解析层才能变成结构化消息。下面用一个“从文本抽取工单摘要”的小例子说明实现边界。

先把下游字段写成最小 Schema

Schema 的第一要务是描述下游代码真的会读取什么。字段越多，模型越容易在无关字段上产生歧义；字段越松，解析虽然成功，业务却可能拿到空标题或超范围优先级。下面的模型只保留工单标题、优先级和摘要三个字段。

from pydantic import BaseModel, Field

class TicketSummary(BaseModel):
    # 标题用于列表展示，限制长度可以避免下游布局被异常长文本撑开
    title: str = Field(min_length=1, max_length=80)
    # 优先级只允许下游已经约定的三个枚举值
    priority: str = Field(pattern="^(low|medium|high)$")
    # 摘要保留问题现象，不要求模型输出额外推理过程
    summary: str = Field(min_length=1, max_length=240)

schema = TicketSummary.model_json_schema()

如果不使用 Pydantic，也可以直接写 JSON Schema。严格 JSON 块不能混入注释，因此把字段说明放在代码块前后；required 决定缺字段时不能当作完整结果接受。

{
  "type": "object",
  "properties": {
    "title": {"type": "string"},
    "priority": {"type": "string", "enum": ["low", "medium", "high"]},
    "summary": {"type": "string"}
  },
  "required": ["title", "priority", "summary"],
  "additionalProperties": false
}

设计时先问一句：下游是要一个对象、数组，还是带错误状态的联合结构？如果接口只支持 JSON Schema 的子集，就不要把不兼容的关键字硬塞进去，而应把 Schema 缩到该模型和提供方共同支持的范围。

把 Schema 放进模型接口的约束参数

使用 Hugging Face Inference Providers 的聊天接口时，可以把 Schema 放进 response_format，并设置严格模式。下面的请求示例只展示调用边界；令牌从环境变量读取，不写入文章或代码仓库。

import os
import json
from huggingface_hub import InferenceClient

client = InferenceClient(
    provider="auto",
    api_key=os.environ["HF_TOKEN"],
)

response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "TicketSummary",
        "schema": schema,
        "strict": True,
    },
}

completion = client.chat_completion(
    model="Qwen/Qwen3-32B",
    messages=[
        {"role": "system", "content": "从工单文本提取标题、优先级和摘要。"},
        {"role": "user", "content": "支付页面在高峰期偶尔超时，影响部分用户。"},
    ],
    response_format=response_format,
)

# 先把接口返回的字符串转成对象，再交给业务模型继续处理
payload = json.loads(completion.choices[0].message.content)
summary = TicketSummary.model_validate(payload)

文档同时展示了 OpenAI 兼容客户端的解析方式，但参数是否可用仍取决于具体模型和 provider。不要只看客户端方法名就假定所有后端都支持同一套 Schema；结构化输出场景应固定经过验证的模型、提供方和 Schema 组合。

如果使用文本生成接口而不是聊天接口，Hugging Face 的 cookbook 展示了 grammar={"type": "json", "value": schema} 这种约束方式。它的思路是让生成过程只选择符合语法的 token，和“提示词要求返回 JSON”不是同一层能力。

# 文本生成接口的兼容写法，具体参数以所选 provider 文档为准
answer = client.text_generation(
    prompt="从下面工单抽取结构化摘要：支付页面在高峰期偶尔超时。",
    grammar={"type": "json", "value": schema},
    max_new_tokens=180,
    return_full_text=False,
)

# 约束生成仍然返回文本，需要在应用边界完成 JSON 解析
summary = TicketSummary.model_validate_json(answer)

收到结果后立即解析，分开三类错误

“接口返回 200”不等于业务结果可用。建议把处理边界分成三层：网络或 provider 错误属于调用失败；无法被 json.loads 读取属于格式失败；JSON 能读取但字段值不满足 Schema 属于结构校验失败。即使三层都通过，还要检查业务语义，例如工单摘要是否真的包含问题现象。

import json
from pydantic import ValidationError

def parse_ticket(raw: str) -> TicketSummary:
    # 先捕获 JSON 语法错误，避免把格式问题误报成业务空值
    try:
        data = json.loads(raw)
    except json.JSONDecodeError as exc:
        raise ValueError("模型返回的内容不是合法 JSON") from exc

    # 再执行字段类型、必填项、枚举和长度约束
    try:
        result = TicketSummary.model_validate(data)
    except ValidationError as exc:
        raise ValueError("JSON 形状不符合 TicketSummary") from exc

    # 最后只做与业务有关的轻量判断，不把主观质量伪装成格式检查
    if "超时" not in result.summary and "支付" not in result.summary:
        raise ValueError("摘要没有覆盖工单的关键现象")
    return result

处理失败时，日志至少记录模型名、provider、Schema 名称、请求追踪 ID 和失败层次；不要把包含用户隐私的原始输入无条件写入日志。对于可以安全重试的 provider 暂时错误，可以重试调用；对于 Schema 不支持或模型不兼容，不要无限重试同一请求。

不支持严格约束时，降级方案要写清边界

有些模型接口只接受普通提示词，或仅支持 JSON MIME 类型而不支持完整 Schema。此时可以要求输出 JSON、限制示例和增加一次解析修复，但这只是降低出错概率，不能宣称“接口保证了结构”。更稳妥的降级顺序是：先尝试换到支持 JSON Schema/grammar 的模型或 provider；确实不能更换时，再使用提示词加有限重试，并把最终结果送入本地 Schema 校验。

• 结构约束只保证字段形状和允许值范围，不能保证模型抽取的事实正确。
• Schema 关键字、数组嵌套、可选字段和并行工具调用可能存在 provider 差异，要以当前接口文档为准。
• 不要把完整 URL、密钥或内部路径要求模型原样回传；敏感字段应由服务端映射或补全。
• 下游存储前仍保留原始响应的必要追踪信息，但按隐私和留存策略脱敏。

因此，最小可用方案可以概括为：定义最小 Schema，选择明确支持它的模型接口，把 Schema 放入约束参数，收到响应后先解析再做业务检查。这样“可解析”有了技术边界，模型质量问题也不会被一层 JSON 外壳掩盖。

常见问题

只在提示词里写“返回 JSON”为什么不够？

提示词是在描述期望，模型仍可能输出解释文字、漏字段或使用错误类型。结构化参数或 grammar 才能把约束放到生成接口层，之后仍应在本地解析和校验。

JSON Schema 校验通过就代表答案正确吗？

不代表。校验通过只能说明字段、类型和部分取值满足约定；摘要是否忠实、分类是否合理、是否遗漏关键信息，仍需要业务规则或人工/模型评估。

应该优先用 response_format 还是 grammar？

按接口能力选择：聊天式 provider 支持 JSON Schema 时优先使用 response_format；文本生成接口暴露 grammar 时使用 grammar。不要为了统一代码而忽略具体 provider 的支持范围。