OpenAI 兼容 API 规范与自建大模型服务要点**「OpenAI 格式」**通常指一套以HTTP JSON为主、路径与字段命名贴近OpenAI 官方 REST API的约定并非特指某一权重文件或某一家的闭源模型。许多推理服务云端或自建通过实现/v1/chat/completions等端点使客户端只需改base_url与 API Key即可切换后端。具体字段与新增接口以OpenAI 官方文档及你所对接的实现为准API 会持续演进。目录概念区分通用约定核心接口Chat Completions流式输出SSE其它常见端点一览与其它推理接口格式的差异自建兼容网关的结构分阶段实施清单参考链接概念区分说法含义OpenAI 兼容 API请求/响应形态与官方 API 相近的协议层约定路径、JSON 字段、鉴权头等。底层模型实际完成推理的权重与服务可由 OpenAI、其它云厂商或本地 vLLM / llama.cpp等承载与「是否叫 GPT」无必然一一对应。生态上大量 SDK 与编排框架如LangChain、LlamaIndex、Spring AI等默认按该约定对接因此「做兼容层」有利于复用现有客户端与示例代码。通用约定项目常见做法传输HTTPS生产环境Content-Type: application/json鉴权Authorization: Bearer api_key路径前缀多为/v1/...错误体常包含error对象message、type、code等HTTP 状态码与429 / 5xx重试策略需与客户端约定OpenAI 形态 JSON内部协议OpenAI 形态 JSON客户端(OpenAI SDK 等)兼容网关你的服务内部推理vLLM / 自研等核心接口Chat Completions路径POST /v1/chat/completions作用以messages数组表达多轮对话含system / user / assistant / tool等角色具体支持度依实现而定。请求体示例非流式POST /v1/chat/completions Content-Type: application/json Authorization: Bearer sk-xxxx{model:gpt-4o-mini,messages:[{role:system,content:你是一个有帮助的助手。},{role:user,content:你好}],temperature:0.7,stream:false}响应体示例结构示意{id:chatcmpl-xxx,object:chat.completion,created:1700000000,model:gpt-4o-mini,choices:[{index:0,message:{role:assistant,content:你好有什么可以帮你},finish_reason:stop}],usage:{prompt_tokens:10,completion_tokens:15,total_tokens:25}}常用请求字段节选字段作用model路由到具体模型名由服务端解释。messages对话消息列表。temperature采样温度影响随机性。max_tokens/max_completion_tokens生成长度上限名称以官方当前文档为准。stream是否流式返回。top_p、frequency_penalty等解码与重复惩罚相关可选。tools/tool_choice函数调用 / 工具调用若实现支持。流式输出SSE当stream: true时响应常为text/event-stream按行推送多个JSON 片段chunk增量内容多在choices[0].delta.content或等价字段客户端拼接delta即得完整回复最后常有finish_reason或[DONE]类标记依实现而定。服务端需将内部流式推理结果及时映射为该 chunk 格式并注意代理超时、心跳与断线重连策略。其它常见端点一览以下为 OpenAI 生态中常见能力分类自建服务可按需子集实现不必一次对齐全部。类别典型路径 / 说明旧式补全POST /v1/completionsprompt驱动非 messages向量POST /v1/embeddings模型列表GET /v1/models文生图POST /v1/images/generations等语音POST /v1/audio/transcriptions、/v1/audio/speech等审核POST /v1/moderations文件POST /v1/files等微调POST /v1/fine_tuning/jobs等助手 / AgentAssistants、Responses等较新能力字段与流程更复杂需对照官方最新版文档与其它推理接口格式的差异风格特点简述Hugging Face TGI常见POST /generate字段如inputs、parameters偏吞吐与自托管场景。Ollama本地常用POST /api/generate等部分发行版另提供OpenAI 兼容层。vLLM / LMDeploy 等常直接提供OpenAI 兼容的 Chat Completions同时可有私有扩展。选型时区分客户端要对接哪一种 URL 与 JSON必要时在网关做协议转换。自建兼容网关的结构对外实现或代理POST /v1/chat/completions、GET /v1/models等目标端点。对内校验model、参数将messages转为内部引擎所需格式如拼接 prompt、模板化 chat template。回包将内部输出填入choices[].message.content、生成id/created尽量填充usage或文档说明不支持。流式内部 token 流 →SSE chunk序列。横切鉴权、限流、超时、审计日志、统一错误体。完全兼容成本较高字段、错误码、流式细节与可选能力最小兼容可只保证团队使用的子集并在文档中声明差异。分阶段实施清单阶段一规划与环境任务说明范围必选chat/completions常用models按需embeddings、流式。技术栈任选成熟 Web 框架如 Spring Boot、FastAPI、NestJS 等。配置base_url、API Key 签发与校验、与内部推理地址。阶段二核心开发任务说明路由POST /v1/chat/completions解析 body按model映射后端。转换messages→ 内部输入支持temperature、stream等已承诺字段。响应组装choices、usage流式则按 SSE 推送 chunk。列表GET /v1/models返回可用id列表。向量可选POST /v1/embeddings对接嵌入模型并封装data[]。阶段三测试单测参数校验、错误路径、空消息等。集成curl/ Postman用官方风格 SDK将base_url指向自建服务做兼容性冒烟。流式验证 chunk 拼接与结束条件。阶段四部署与运维容器化与发布HTTPS、密钥与配置管理。监控QPS、延迟、5xx/429、上游推理耗时。限流与配额防止密钥泄露或滥用。参考链接OpenAI 官方 API 参考随版本更新https://platform.openai.com/docs/api-reference第三方「兼容服务」的字段与行为可能与官方存在差异集成前应以对方文档与实际抓包为准。