OpenAI 兼容 API 返回格式:字段结构与 response_format 支持对比
「response format」其实是两个问题
搜 openai compatible api response format 的人,通常想问的是两件事之一:
- 返回长什么样? OpenAI 兼容的
/v1/chat/completions接口返回的 JSON 对象结构,以及哪些字段可以放心读取。 response_format参数怎么用? 请求里要求纯文本、JSON 模式(json_object)或结构化输出(json_schema)的那个字段,以及各家兼容端点到底支不支持。
本文把两件事都讲清,再给出一套换供应商也不用改代码的写法。基础概念见 什么是 OpenAI 兼容 API,更全面的差异清单见 OpenAI 兼容性问题;这里只聚焦返回结构与 response_format。
以下事实均来自各家官方文档(2026 年 11 月 20 日查阅):OpenAI Structured Outputs 指南、Anthropic OpenAI SDK 兼容说明、Google Gemini OpenAI 兼容、DeepSeek JSON Output、vLLM structured outputs 与 Ollama OpenAI 兼容。各家支持情况变化快,如与文档不一致,以官方文档为准。
返回对象:哪些字段靠得住
OpenAI 兼容服务的非流式 chat completion 返回骨架基本一致:
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1763600000,
"model": "provider-model-name",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "...", "tool_calls": null },
"finish_reason": "stop"
}
],
"usage": { "prompt_tokens": 21, "completion_tokens": 48, "total_tokens": 69 }
}可以放心依赖的是 choices[0].message.content、choices[0].message.tool_calls、choices[0].finish_reason 和 usage 的三个计数,其余字段都属于「可能有」。Anthropic 的兼容对照表很能说明问题:id、choices[].message.content、tool_calls、model 和 usage 的 token 计数完全支持,而 usage.prompt_tokens_details、usage.completion_tokens_details、choices[].message.refusal、logprobs、service_tier、system_fingerprint 永远为空。
由此得出三条实操规则:
- 解析前先看
finish_reason。 值为length说明输出在 token 上限处被截断,JSON 多半不完整。 - 可选字段按可选处理。 不做空值判断就读
usage.prompt_tokens_details.cached_tokens,遇到返回空的供应商就会报错。 - 别指望
refusal处处可用。 OpenAI 的结构化输出会在refusal字段报告安全拒答;Anthropic 兼容层里这个字段永远为空。
流式返回把同样的字段拆到 chat.completion.chunk 事件的 choices[].delta 中,差异见 兼容性问题 一文。
response_format 参数的三种模式
在 Chat Completions 中,response_format 有三种取值:
|
模式 |
请求值 |
保证什么 |
|---|---|---|
|
文本 |
|
不做任何约束 |
|
JSON 模式 |
|
输出是合法 JSON,但结构不定 |
|
结构化输出 |
|
输出符合你给的 JSON Schema(限支持的子集) |
OpenAI 把结构化输出定位为 JSON 模式的升级版:两者都输出合法 JSON,只有结构化输出会强制遵循 Schema,官方建议能用就用。新版 Responses API 里同一设置放在 text.format 而不是 response_format,如果某家只实现了 Chat Completions,这一点要注意。
各家支持情况一览
|
供应商(OpenAI 兼容端点) |
|
|
备注 |
|---|---|---|---|
|
OpenAI |
支持 |
支持,配合 |
Schema 须在官方支持的子集内;官方示例把每个字段都列入 |
|
Anthropic( |
不支持,返回 400 |
支持,且只接受 |
传 |
|
Google Gemini( |
兼容页未说明 |
支持 |
官方示例通过 SDK 的 |
|
DeepSeek( |
支持 |
文档未提及 |
提示词须包含「json」字样并给出示例;无法解析的输出可能返回空白内容 |
|
vLLM(自部署) |
支持 |
支持 |
另有自有字段 |
|
Ollama( |
支持(JSON 模式) |
文档列明支持 |
本地服务不校验 API Key |
有两点很明显:其一,json_object 并不通用,写死 JSON 模式的客户端在 Anthropic 兼容层会直接报错;其二,json_schema 最接近「公约数」,前提是 Schema 落在每家目标供应商都支持的子集内。
容易踩坑的差异
DeepSeek 的空白内容。 DeepSeek 文档说明:模型输出若无法识别为 JSON,API 会把非 JSON 内容替换成空格,于是 finish_reason 为 stop 时 content 也可能看起来是空的。代码里要处理空白内容并重试;同时把 max_tokens 设够,避免 JSON 被截断。
Anthropic 的严格限制。 只接受 strict: true 的 json_schema,且受其结构化输出的 Schema 限制约束。另外,函数定义里的 strict 在兼容层会被忽略,工具调用参数不保证符合 Schema。
vLLM 的字段改名。 升级 vLLM 后,如果使用 guided_json、guided_regex、guided_choice 的请求失效,请改用 structured_outputs,例如 {"structured_outputs": {"json": ...}}。普通的 response_format + json_schema 不受影响。
中间的网关。 网关或 OpenAI API 代理 可能原样透传 response_format,也可能转换或丢弃。请用应用实际使用的 base URL 测试,而不是直连上游。
可移植的写法
想用一套代码对接多家供应商:
- 优先用
json_schema+strict: true,Schema 保持简单:根节点为 object,所有属性列入required,additionalProperties: false,不用冷门关键字。 - 提示词里仍写明「JSON」 并给一个简短示例。没有成本,而且 DeepSeek 要求这么做。
- 先查
finish_reason,再检查content是否空白或被截断。 - 解析后再校验。 OpenAI 官方也提醒要处理拒答、不完整响应和错误,并校验 Schema 表达不了的业务规则。
- 准备降级路径。 供应商对
json_schema返回 400 时,在支持的地方改用json_object,否则去掉response_format,靠提示词约束 + 校验。
import json
from openai import OpenAI
client = OpenAI(base_url="https://your-gateway.example/v1", api_key="...")
schema = {
"type": "object",
"properties": {"name": {"type": "string"}, "date": {"type": "string"}},
"required": ["name", "date"],
"additionalProperties": False,
}
resp = client.chat.completions.create(
model="your-model",
messages=[
{"role": "system", "content": "Extract the event. Reply in JSON like {\"name\": \"...\", \"date\": \"...\"}."},
{"role": "user", "content": "Alice and Bob meet at the science fair on Friday."},
],
response_format={"type": "json_schema",
"json_schema": {"name": "event", "schema": schema, "strict": True}},
max_tokens=300,
)
choice = resp.choices[0]
if choice.finish_reason != "stop" or not (choice.message.content or "").strip():
raise RuntimeError(f"incomplete or empty output: {choice.finish_reason}")
event = json.loads(choice.message.content)切换供应商前先验证
对新的 base URL 跑同样三个请求并对比:
- 普通请求,检查
choices[0].message.content和usage; - 加上
response_format: {"type": "json_object"},看是返回 400 还是合法 JSON; - 换成你真实的
json_schema,确认输出能解析且通过校验。
如果多个模型走同一个端点,ai.roibest 网关 用一个 OpenAI 兼容的 /v1 base URL 统一接入,但上表的逐模型差异依然存在,三请求检查建议写进发布清单。
常见问题
OpenAI 兼容 API 的返回格式是什么?
chat completion 返回的对象包含 id、object: "chat.completion"、created、model、choices 数组(每项含 message.content、可选的 message.tool_calls 和 finish_reason),以及包含输入、输出、总 token 数的 usage。其他字段是可选的,部分供应商返回为空。
json_object 和 json_schema 有什么区别?
json_object(JSON 模式)只保证输出合法 JSON;json_schema + strict: true(结构化输出)还保证输出符合你给的 Schema。OpenAI 建议能用结构化输出就用。
通过 OpenAI SDK 调 Claude 支持 response_format 吗?
部分支持。Anthropic 兼容层只接受 strict: true 的 json_schema,传 json_object 或 text 会返回 400。
DeepSeek 的 JSON 模式为什么返回空内容?
输出无法识别为 JSON 时,DeepSeek 会把非 JSON 内容替换为空格。提示词里写上「json」并给示例,max_tokens 设够,遇到空白内容就重试。
vLLM 还支持 guided_json 吗?
不支持了。guided_json、guided_regex、guided_choice 已在 vLLM v0.12.0 移除,请改用 response_format + json_schema,或 vLLM 的 structured_outputs 字段。
一句话总结
返回结构的核心(choices[0].message.content、finish_reason、usage)是稳定的,边缘字段不可靠。response_format 方面,简单的严格 json_schema 最通用,json_object 并非处处支持;无论接哪家,都要做 finish_reason 检查、空白内容检查和解析后校验。