OpenAI API 怎样限制输出内容使用指定文本格式

我第一次把模型接进工单分类接口时，提示词明明写了“只能返回固定字段”，结果仍会偶尔多出解释文字，或者把枚举值写成近义词。问题不在于提示词不够强，而在于它没有成为 API 层面的格式约束。

官方地址：https://developers.openai.com/api/docs/guides/structured-outputs

要限制 OpenAI API 的输出使用指定文本格式，优先使用 Structured Outputs：在 Responses API 中通过 text.format 声明 json_schema，并设置 strict: true。如果只需要合法 JSON 而不要求字段完全匹配，才考虑 json_object。

从输出漂移症状定位根因

现场通常有三个症状：字段偶尔缺失、枚举值超出约定范围、JSON 前后夹着说明文字。我的排查顺序是先记录原始输出，再看请求到底用了哪一种格式配置。只在提示词里写“请严格输出 JSON”，属于约定；使用 json_object，最多把结果收敛为可解析的 JSON，仍不能保证业务字段齐全。

真正需要固定数据契约时，应把目标从“输出看起来像某种文本”改成“输出匹配一份 schema”。这也是 Structured Outputs 和普通 JSON mode 的根本区别：前者约束结构，后者只约束外形。

把指定文本格式写成 JSON Schema

先定义业务对象，不要一上来堆复杂规则。下面的工单示例只保留标题、优先级和处理建议三个字段；priority 用枚举限制取值，additionalProperties: false 则阻止模型悄悄添加未约定字段。

严格 schema 还要把必填字段写进 required，对象节点写明 type。如果字段确实可以为空，应把空值作为 schema 的一部分设计，而不是等输出后再猜测。

在 Responses API 中配置 text.format

Responses API 的结构化输出配置放在 text.format。下面代码使用手写 schema，适合先看清请求形状；生产项目也可以用 SDK 的类型辅助工具减少模型类型与 schema 分离的问题。

from openai import OpenAI

client = OpenAI()

schema = {
    "type": "object",
    "properties": {
        "title": {"type": "string"},
        "priority": {"type": "string", "enum": ["low", "medium", "high"]},
        "suggestion": {"type": "string"},
    },
    "required": ["title", "priority", "suggestion"],
    "additionalProperties": False,
}

response = client.responses.create(
    model="gpt-6-astra",
    input="把这条工单归纳成标题、优先级和处理建议。",
    text={
        "format": {
            # 用 json_schema 固定字段、类型和枚举值。
            "type": "json_schema",
            "name": "support_ticket",
            "strict": True,
            "schema": schema,
        }
    },
)

# output_text 是结构化 JSON 文本；业务侧再解析并处理异常。
if not response.output_text:
    raise RuntimeError("没有拿到结构化输出，请检查拒答或截断状态")
print(response.output_text)

这里的关键不是把模型换成某个固定名称，而是请求使用了支持 Structured Outputs 的模型，并把 schema 放进正确的参数层级。模型名称应由你的账号和项目可用模型决定；如果模型不支持这项能力，参数写对也不会得到预期约束。

复查拒答、截断和解析边界

格式约束成功不等于每次都有业务结果。安全拒答可能没有可解析的对象，输出被长度限制截断时也可能只得到半段 JSON。调用方至少要记录响应状态、是否存在文本输出，以及解析失败的原始摘要；不要把一次解析异常直接当成 schema 失效。

如果 API 返回了 JSON，却缺少必填字段，优先检查请求是否退回了 JSON mode 或普通文本；如果字段完整但业务值不对，再检查枚举和描述是否足够清楚。需要模型调用应用函数时，则应评估 function calling，而不是把函数参数 schema 和面向用户的文本 schema 混成一个配置。

旧写法迁移时，先查三处边界

迁移时最容易犯的错是只改参数名、不重新确认接口形状：Responses API 把结构化输出放到 text.format，而旧代码常见的 response_format 不能机械照搬。先用一条固定输入做契约回归，再接回真实流量，排查会比盯着提示词省时间。

相关问题

json_object 和 json_schema 应该怎么选

需要固定字段、类型或枚举时选 json_schema；只要求返回合法 JSON、结构由后续逻辑自行处理时才选 json_object。

为什么设置了 strict 仍然没有结果

strict 约束的是结构，不会消除安全拒答、长度截断或模型能力不匹配。先看响应状态和原始输出，再判断是否需要调整 schema。

函数调用也能使用 schema 吗

可以，但函数参数的 schema 服务于工具调用；面向用户的结构化回复则使用文本格式配置。两者目标不同，按数据流的位置选择。

最后的判断标准很简单：把格式要求写进 schema，把接口入口写对，把拒答和截断当成正常分支处理。这样输出格式才是可维护的接口契约，而不是一次碰巧成功的提示词效果。