OpenAI API/OpenAI 结构化输出与采样参数

OpenAI 结构化输出 text.format 与 response_format 规范、采样参数约束、对数概率与服务档位控制。

OpenAI 结构化输出与采样参数

本文档详细说明通过 UniGateway 调用 OpenAI 规范端点时的结构化输出配置(text.format 与 response_format)、采样参数约束与剥离规则(temperature 与 top_p)、对数概率(logprobs)、惩罚参数以及服务档位(service_tier)等控制选项。


章节导引

本篇为 OpenAI API 参考文档的第 4 章节:

  1. Responses 概述与快速开始
  2. 请求参数与输入格式
  3. 扩展推理与会话状态
  4. 结构化输出与采样参数(当前章节)
  5. 工具调用与内置工具
  6. 响应、流式与错误处理

结构化输出(Structured Outputs)

OpenAI 支持将模型输出严格约束为合法的 JSON 对象或符合指定 JSON Schema 的数据格式。

1. text.format 与 response_format 跨代迁移

参数 / 场景OpenAI 官方规范与 Migration GuideUniGateway 处理规则
text.format 与 response_format 跨代迁移Migration Guide:在 /v1/chat/completions 中,结构化输出通过 response_format 配置(如 {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}});在 /v1/responses 中,该配置已迁移至 text.format(扁平化为 {"type": "json_schema", "name": "...", "schema": {...}, "strict": true})。双向无损转换与 strict 默认补齐:当客户端在 /v1/responses 端点仍传入旧版 response_format(或嵌套的 text.format.json_schema)时,网关自动将其展平迁移至标准 text.format 结构;在 Chat Completions 与 Responses 协议互转时自动完成 response_format ⇄ text.format 映射;若客户端使用 json_schema 但未显式指定 strict 布尔值,默认补齐 "strict": true。
json_object 模式的 "json" 关键词校验OpenAI 官方要求:当请求指定 type: "json_object" 时,输入提示词(instructions、input 或 messages)中必须包含 "json" 字样(不区分大小写),否则上游返回 400 'messages' must contain the word 'json'。自动注入关键词保障:在 /v1/responses(text.format.type == "json_object")与 /v1/chat/completions(response_format.type == "json_object")转发路径中,若网关检测到实际消息文本与 instructions 中均未出现 "json" 字样,会自动补充 "Respond in json."(并在响应头记录 sanitize_chat_completions 等修正标签),防止因缺少提示词关键字而报错。
text.verbosity 与顶层 verbosityGPT-5 / GPT-6 系列新增输出详细度控制参数(可选值:"low"、"medium"、"high")。在 /v1/responses 中位于 text.verbosity。位置归一化:若客户端在 /v1/responses 请求体顶层直接传入了 "verbosity": "low",网关自动将其归并至 text.verbosity 并移除顶层冗余字段。

采样参数与输出分布控制

在引入推理能力的现代大语言模型中,OpenAI 官方规范对采样参数实施了严格的互斥约束。

参数 / 场景OpenAI 官方规范与 Migration GuideUniGateway 处理规则
开启推理时的 temperature 与 top_pMigration Guide:在 OpenAI 推理模型(o1 / o3 / o4-mini、GPT-5、GPT-6.1 Sol、GPT-6 Astra,以及 effort != "none" 时的 GPT-5.1~5.6 / GPT-6 Sol & Luna / GPT-6.1 Terra)上,采样参数不受支持,传入非默认值会导致上游返回 400 Unsupported parameter。推理状态下主动剥离:在主动规范化处理中,只要目标模型开启推理且有效 effort 不为 "none",网关自动剥离 temperature 与 top_p;若未知新模型在推理状态下因采样参数返回 400,网关在自适应重试中自动剥离并重试。在响应头中输出 x-gateway-modified: temperature=0.7=>@absent。
非推理模式(或 effort: "none")时的 temperature 与 top_p在非推理模型(如 gpt-4.1、gpt-4o)或支持 effort: "none" 且当前处于 "none" 档位的模型上,允许使用 temperature 与 top_p。按需保留与通道固定值适配:当模型支持无推理模式且当前有效档位为 effort == "none"(例如 gpt-5.4、gpt-5.6、gpt-6-sol 默认或显式指定 none)时,网关保留 temperature 与 top_p;在配置了固定采样默认值的特定通道上,网关自动将采样参数对齐为通道预设值。
logprobs、top_logprobs 与 include 中的 logprobs推理模型在激活推理(effort != "none")时同样不支持返回对数概率(包括 Chat Completions 的 logprobs / top_logprobs 以及 Responses API include 数组中的 "message.output_text.logprobs")。联动清理:当推理激活(effort != "none")时,网关自动移除顶层 logprobs、top_logprobs,并从 /v1/responses 的 include 数组中过滤掉 "message.output_text.logprobs"(若过滤后 include 为空则一并移除该字段)。
presence_penalty、frequency_penalty 与 logit_bias仅适用于传统非推理 Chat Completions 模型;在推理模型及 /v1/responses 端点上不受支持。推理模式自动清理:在推理模型(effort != "none")或转换至 /v1/responses 时,网关自动剥离 presence_penalty、frequency_penalty 与 logit_bias。

服务处理档位、安全标识与路由元数据

参数 / 场景OpenAI 官方规范与 Migration GuideUniGateway 处理规则
service_tier(服务处理档位)可选值为 "auto"、"default"、"flex"、"priority"(或旧版 "scale")。归一化与权限适配:若客户端传入 "priority"(常见于客户端 Fast Mode 开关),网关将其规范化为标准 "priority" 档位,并在上游因权限不足返回 400 时自动回退为 "default" 重试;响应体与流式 Chunk 中的 service_tier 如实反映上游实际执行的档位。
safety_identifier 与 metadataMigration Guide:OpenAI 官方推荐使用 safety_identifier(字符串,最大 64 字符)替代旧版 user 字段,用于传递哈希脱敏后的终端用户标识;metadata 用于传递最多 16 组自定义键值对。长度截断与通道过滤:网关自动将超出 64 字符的 safety_identifier 截断至 64 字符(兼容严格校验 64 字符上限的上游);在不支持 safety_identifier 与 metadata 的通道上,网关在转发前自动剥离这两个字段。
provider(OpenRouter 兼容路由策略)OpenAI 官方协议不包含顶层 provider 字段;OpenRouter 兼容网关支持通过 provider 对象指定提供商筛选(only / order / ignore)、量化精度(quantizations)与零数据保留(zdr)。账号级路由策略收敛合并:当目标通道启用了提供商路由策略时,网关将账号级配置的路由约束与客户端传入的 provider 对象取交集收敛合并后写入出口请求体;在标准 OpenAI 通道上不注入该字段。