AI JSON Schema 约束输出 怎样处理

AI JSON Schema 约束输出，关键不是在提示词里补一句“请返回 JSON”，而是把字段结构作为接口参数交给支持结构化输出的模型服务。Schema 负责字段、类型和必填关系；模型或 Provider 负责生成；应用层仍要检查业务含义。这样既能减少无法解析的文本，也不会把“格式正确”误当成“内容正确”。

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

云端调用优先使用 response_format 搭配 JSON Schema；自托管 TGI 可以在 /generate 使用 grammar。先选与模型、Provider 兼容的约束入口，再在应用层做语义校验。

先分清 JSON Schema 约束的是哪一层

只在自然语言中要求“输出 JSON”，模型仍可能加解释文字、漏字段或改变字段类型。结构化输出把 Schema 放进请求协议，约束的是可生成的结构；它并不替你判断事实是否真实、分类是否符合业务规则。

可以把一次请求拆成三层：输入文本提出任务，Schema 描述结果形状，模型和 Provider 生成结构化 JSON，最后由业务代码检查枚举值、数值范围和领域规则。字段写进 required 只能表达“必须存在”，不能表达“字符串必须有业务意义”。

因此，排查时先问三个问题：请求是否真的传入 Schema；当前模型和 Provider 是否支持该接口；解析成功后是否还有业务校验。只改提示词，通常解决不了接口层的字段漂移。

用 response_format 定义云端 JSON 结构

Hugging Face Inference Providers 的官方示例使用 Pydantic 定义结果，再通过 model_json_schema() 交给 response_format。下面的例子让模型从一段文本里抽取工单主题、优先级和标签，重点是展示字段约束的组织方式。

# 安装 Hugging Face Hub 客户端，令 Python 可以调用 Inference Providers
python -m pip install huggingface_hub pydantic

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


class Ticket(BaseModel):
    # required 字段由模型字段声明表达，结果必须包含这三个键
    subject: str
    priority: str
    labels: list[str]


response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "Ticket",
        # 把 Pydantic 模型转换为服务端可理解的 JSON Schema
        "schema": Ticket.model_json_schema(),
        "strict": True,
    },
}

client = InferenceClient(
    provider="cerebras",  # 也可以按官方支持情况改用 auto
    api_key=os.environ["HF_TOKEN"],  # 凭据从环境变量读取，不写进代码
)

response = client.chat_completion(
    model="Qwen/Qwen3-32B",
    response_format=response_format,
    messages=[
        {"role": "system", "content": "提取工单主题、优先级和标签，只返回结构化结果。"},
        {"role": "user", "content": "用户反馈：导出任务连续两次超时，影响今天的报表。"},
    ],
)

# 客户端返回的 content 仍按字符串读取，再转成 Python 对象
data = json.loads(response.choices[0].message.content)
if data["priority"] not in {"low", "medium", "high"}:
    # Schema 能保证字段形状，但业务枚举仍应由应用自己把关
    raise ValueError("priority 不在业务允许范围内")
print(data["subject"], data["labels"])

这里的重点有三处：Schema 名称让响应格式更容易追踪；strict 表达严格结构意图；json.loads() 之后才进入业务对象。模型与 Provider 的组合如果不支持该结构化能力，应该先更换兼容组合，而不是把完整 Schema 反复塞进提示词。

自托管 TGI 用 grammar 约束生成

如果使用 Text Generation Inference，可以把 JSON Schema 放在 grammar 参数的 value 中，通过 /generate 约束生成文本。TGI 官方文档同时支持 Pydantic、JSON Schema 和正则语法；grammar 首次需要编译成中间表示，后续相同结构通常可以复用缓存。

import json
from huggingface_hub import InferenceClient

schema = {
    "type": "object",
    "properties": {
        "answer": {"type": "string"},
        "confidence": {"type": "number", "minimum": 0, "maximum": 1},
    },
    "required": ["answer", "confidence"],
}

client = InferenceClient("http://localhost:3000")

# grammar 约束生成形状；提示词只补充任务语义，不承担协议约束
text = client.text_generation(
    "从输入材料提取一句答案，并给出 0 到 1 的置信度。请使用给定 JSON 结构。",
    max_new_tokens=120,  # 给结构化结果预留足够的输出空间
    grammar={"type": "json", "value": schema},
)

# 语法约束后仍要解析，并检查应用能接受的数值范围
result = json.loads(text)
if not 0 

这条路径适合已经维护 TGI 服务、希望在服务端控制 grammar 的团队。若只通过云端兼容 API 调用模型，优先使用 response_format；若是本地 TGI，则使用 grammar。两者都要求先确认模型、服务版本和约束能力的兼容关系。

按数据生命周期处理返回值

把约束输出放进业务代码时，可以沿着“请求定义—生成—解析—业务校验—落库”处理。不要直接把模型返回的字符串写进数据库或消息队列；先确认 JSON 可解析，再检查必填字段的业务含义、枚举值、长度和敏感字段。

如果出现“字段有了但值不对”，先看业务校验；如果出现“返回无法解析”，先看是否真的使用结构化入口；如果首次请求明显变慢，检查 grammar 编译开销，而不是马上把 max_new_tokens 调得更大。

常见问题

JSON Schema 能保证答案真实吗？ 不能。它约束数据形状和部分类型边界，事实正确性、分类准确性和权限规则仍需应用或人工流程判断。

为什么已经写了 JSON Schema 还会不兼容？ 结构化输出能力依赖模型、Provider 和接口实现的组合；先查看当前服务的支持列表，再选择 response_format 或 grammar。

response_format 和 grammar 是否二选一？ 通常按服务入口选择：Inference Providers 走 response_format，自托管 TGI 的 /generate 走 grammar。不要把一套参数原样混到另一条接口。

小结

AI JSON Schema 约束输出的正确做法是把 Schema 作为协议参数传入支持的结构化入口：云端优先看 response_format，TGI 本地生成使用 grammar。生成后仍按“解析、业务校验、下游处理”的生命周期推进，格式稳定只是可靠 AI 应用的第一层。