OpenAI 兼容接入
遵循 OpenAI 规范的第三方上游接入——以 openai-compatible 协议类型登记、请求与响应字段映射、模型清单与路由配置示例
OpenAI 兼容接入用于纳管遵循 OpenAI 规范的第三方上游。由于平台的数据平面统一查询入口本身即 OpenAI 兼容，这类上游的协议映射最为直接——请求与响应几乎一一对应，平台只需做归属与计量的补充处理。本页只写 OpenAI 兼容接入相对通用接入规则的差异。
接入要点
登记时 source 取 third_party、type 取 openai-compatible。平台据此把发往该上游的请求按 OpenAI 规范组织，并把上游返回的 chat.completion 结构对齐到统一响应。
curl https://your-platform/api/v1/providers \
-H "Content-Type: application/json" \
-H "Cookie: <控制台会话凭证>" \
-d '{
"name": "OpenAI 兼容上游",
"source": "third_party",
"type": "openai-compatible",
"models": ["<模型中性名>"],
"group": "default",
"priority": 2,
"weight": 1
}'| 字段 | OpenAI 兼容取值 | 说明 |
|---|---|---|
source | third_party | 标记为第三方兼容接入，「模型接入」页归入第三方分区 |
type | openai-compatible | 平台按 OpenAI 规范翻译请求与响应 |
models | 中性名数组 | 上游实际模型名映射为对外中性名（见下） |
请求与响应映射
OpenAI 兼容上游的对接点是 /v1/chat/completions 形态。客户应用发往平台统一入口的请求字段，绝大多数可原样透传给上游：
| 平台统一入口字段 | OpenAI 兼容上游字段 | 映射 |
|---|---|---|
model（中性名） | model（上游实际模型名） | 平台按 models 登记把中性名解析为上游实际模型 |
messages | messages | 原样透传 |
stream | stream | 原样透传，流式逐 chunk 经护栏中间件处理 |
max_tokens / temperature 等 | 同名标准字段 | 原样透传 |
响应方向，上游返回的 chat.completion 结构对齐到统一响应，平台在 usage 上补充 6 档计量信息：
{
"object": "chat.completion",
"model": "<实际路由的上游模型中性名>",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "<生成内容>" },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 0,
"completion_tokens": 0,
"total_tokens": 0,
"cached_input_tokens": 0,
"price_tier": "<适用单价档（6 档之一）>",
"thinking": false
}
}
usage扩展由平台补全。 上游原生usage仅含基础词元字段；cached_input_tokens/price_tier/thinking等 6 档计量扩展由平台依统一计价词元口径补全，是逐条调用记录与计费的来源。客户应用无需感知这一补全过程。
模型清单拉取
接入后可在「模型接入」页对该上游做接入探测，确认连通后其登记的中性名即进入模型池准入判定：
curl https://your-platform/api/v1/providers/<上游标识>/probe \
-X POST \
-H "Cookie: <控制台会话凭证>"OpenAI 兼容上游往往与自有供应模型供给同一中性名，作为自有供应的备份层（较低优先级）。当自有供应不可用时，路由中间件按优先级降级到该上游，对客户应用透明。
OpenAI 兼容接入完成后，其模型与自有供应、其它规范的第三方上游在同一模型池中统一调度。其它第三方规范见 Anthropic 兼容接入、Gemini 兼容接入；逐条调用与计量字段的完整契约见 API 参考。