公告AI接口网提供各类可接入的人工智能接口
AI接口网AI 接口选型与接入工程手册
首页/接入实战/OpenAI 兼容协议逐字段拆解:一次搞懂所有厂商的「通用语言」

OpenAI 兼容协议逐字段拆解:一次搞懂所有厂商的「通用语言」

2026-11-22约 9 分钟读完协议接入OpenAI

OpenAI 的 /v1/chat/completions 事实上已经成为行业通用协议。理解它的字段语义,等于拿到了所有厂商的通用说明书。

最小请求

http
POST /v1/chat/completions
Authorization: Bearer <KEY>
Content-Type: application/json

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "system", "content": "你是一名严谨的技术编辑。"},
    {"role": "user", "content": "用三句话解释什么是向量检索。"}
  ],
  "temperature": 0.3,
  "max_tokens": 800,
  "stream": false
}

字段语义

字段作用常见坑
model模型标识各厂命名规则不同,且会下线旧名;不要写死在业务代码
messages对话数组,含 role 与 contentsystem 只能有一条且通常需在首位;部分厂商把 system 提到顶层
rolesystem / user / assistant / tooltool 消息必须与 tool_call_id 对应,否则 400
temperature随机性,0~2推理模型常忽略此参数;设为 0 也不保证完全确定
top_p核采样与 temperature 同时调会互相干扰,一般只调一个
max_tokens输出上限不设会用默认值,长文任务容易被截断
stream是否流式开启后返回 SSE,不再是单个 JSON
stop停止词部分厂商对 stop 的支持不完整
tools工具定义数组schema 写错不会报错,只会「模型不用工具」
response_format输出格式约束要求 json_object 时,prompt 里必须出现 json 字样

返回结构

json
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1763800000,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "……"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 42, "completion_tokens": 118, "total_tokens": 160}
}

finish_reason 是最容易被忽略但最该处理的一个字段:

值含义处置
stop正常结束直接用
length达到 max_tokens 被截断内容不完整,需要续写或提高上限
tool_calls模型要求调用工具执行工具并回填结果,继续对话
content_filter被内容安全策略拦截提示用户改写,不要重试

兼容的边界在哪

「兼容」通常只覆盖 chat/completions 的基础字段。以下能力各家实现差异较大,迁移时逐个验证:

  • 工具调用:返回结构、并行调用支持、流式下的增量 tool_calls 拼接方式
  • 结构化输出:json_schema 的严格模式是否支持
  • 多模态消息:图片是 URL 还是 base64、字段名是 image_url 还是别的
  • 计费明细:usage 里是否包含缓存命中、思考 token 的细项
  • 错误响应:是否也遵循 OpenAI 的 error.message / error.type 结构(很多厂商不遵循)
错误体不兼容
实践建议:把「响应错误」也做一层归一化。OpenAI 的错误体是 error.message / error.type / error.code,很多国产厂商返回的是完全不同的结构,直接取 resp[error][message] 会二次崩溃。

一个可复用的适配层骨架

python
def chat(role_cfg, messages, **kw):
    payload = {
        "model": role_cfg["model"],
        "messages": messages,
        "max_tokens": kw.get("max_tokens", 1200),
        "temperature": kw.get("temperature", 0.3),
    }
    if kw.get("tools"):
        payload["tools"] = kw["tools"]
        payload["tool_choice"] = "auto"
    r = session.post(role_cfg["base_url"] + "/chat/completions",
                     json=payload, timeout=(5, role_cfg["timeout"]))
    if r.status_code != 200:
        raise ApiError(normalize_error(r))
    d = r.json()
    ch = d["choices"][0]
    return {
        "text": ch["message"].get("content") or "",
        "tool_calls": ch["message"].get("tool_calls", []),
        "finish": ch.get("finish_reason"),
        "usage": d.get("usage", {}),
    }

这 20 行就是「不锁定」的核心:业务层只认 text / tool_calls / finish / usage 四个键,换供应商时改配置即可。

说明
文中价格、配额、限额均为撰写时的公开口径,会随厂商调整变化;用于估算量级,不构成报价。具体以各厂商官方文档与合同为准。