接入教程

OpenAI 兼容 API 返回格式:字段结构与 response_format 支持对比

ROIBest AI

「response format」其实是两个问题

搜 openai compatible api response format 的人,通常想问的是两件事之一:

  1. 返回长什么样? OpenAI 兼容的 /v1/chat/completions 接口返回的 JSON 对象结构,以及哪些字段可以放心读取。
  2. 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 有三种取值:

模式

请求值

保证什么

文本

{"type": "text"}(或不传)

不做任何约束

JSON 模式

{"type": "json_object"}

输出是合法 JSON,但结构不定

结构化输出

{"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}}

输出符合你给的 JSON Schema(限支持的子集)

OpenAI 把结构化输出定位为 JSON 模式的升级版:两者都输出合法 JSON,只有结构化输出会强制遵循 Schema,官方建议能用就用。新版 Responses API 里同一设置放在 text.format 而不是 response_format,如果某家只实现了 Chat Completions,这一点要注意。

各家支持情况一览

供应商(OpenAI 兼容端点)

json_object

json_schema

备注

OpenAI

支持

支持,配合 strict: true

Schema 须在官方支持的子集内;官方示例把每个字段都列入 required,并设 additionalProperties: false

Anthropic(api.anthropic.com/v1/)

不支持,返回 400

支持,且只接受 strict: true

传 text 也返回 400;官方把兼容层定位为测试和对比用途,而非长期生产方案

Google Gemini(.../v1beta/openai/)

兼容页未说明

支持

官方示例通过 SDK 的 parse 把 Pydantic 模型作为 response_format 传入

DeepSeek(api.deepseek.com)

支持

文档未提及

提示词须包含「json」字样并给出示例;无法解析的输出可能返回空白内容

vLLM(自部署)

支持

支持

另有自有字段 structured_outputs;旧的 guided_json 等字段已在 v0.12.0 移除

Ollama(localhost:11434/v1/)

支持(JSON 模式)

文档列明支持 response_format

本地服务不校验 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 测试,而不是直连上游。

可移植的写法

想用一套代码对接多家供应商:

  1. 优先用 json_schema + strict: true,Schema 保持简单:根节点为 object,所有属性列入 required,additionalProperties: false,不用冷门关键字。
  2. 提示词里仍写明「JSON」 并给一个简短示例。没有成本,而且 DeepSeek 要求这么做。
  3. 先查 finish_reason,再检查 content 是否空白或被截断。
  4. 解析后再校验。 OpenAI 官方也提醒要处理拒答、不完整响应和错误,并校验 Schema 表达不了的业务规则。
  5. 准备降级路径。 供应商对 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 检查、空白内容检查和解析后校验。