OpenAI API 请求格式详解

请求 (Request) — POST /v1/chat/completions

HTTP Header → Request Body (JSON) → 网关转发到后端 → Response

HTTP Headers — 网关从中提取认证和路由信息

网关读取 → 认证: 提取 API Key "Authorization": "Bearer test-key"

网关读取 → 路由: Session-ID → Consistent Hash "X-Session-ID": "user-alice-001"

标准 → "Content-Type": "application/json"

Request Body (JSON) — 每个字段的用途

{
  "model": "qwen2.5-7b",         // ① 指定模型 — Semantic Router 用此选模型组
  "messages": [                       // ② 对话历史 — 网关不解析，透传给后端
    {
      "role": "system",                 // system prompt — Prefix Cache 的 hash 来源!
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",                   // 用户输入 — Prefill 的计算量取决于这个
      "content": "你好，请介绍一下你自己"
    }
  ],
  "max_tokens": 256,                 // ③ 最多生成 token 数 — 限流器据此预扣配额
  "temperature": 0.7,               // ④ 随机性 — 0=确定性, 1=更随机
  "stream": true,                     // ⑤ 是否流式返回 — true → SSE 逐 token 推送
  "stop": ["\n\n"],                  // ⑥ 停止条件 — 遇到此字符串停止生成
  "top_p": 0.95                      // ⑦ nucleus sampling — 只考虑累积概率前 95% 的 token
}

非流式响应 (Response)

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1720000000,
  "model": "qwen2.5-7b",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "你好！我是..."
    },
    "finish_reason": "stop"      // "stop"=正常结束 "length"=达到max_tokens
  }],
  "usage": {
    "prompt_tokens": 15,          // 输入 token 数 — 计费用
    "completion_tokens": 42,     // 输出 token 数 — 计费用 (通常更贵)
    "total_tokens": 57           // 总 token 消耗
  }
}

流式响应 (SSE — Server-Sent Events)

当 stream: true 时，后端逐 token 推送，每个 token 一个 SSE 事件：

data: {"choices":[{"delta":{"role":"assistant"},"index":0}]}

data: {"choices":[{"delta":{"content":"你好"},"index":0}]}

data: {"choices":[{"delta":{"content":"！"},"index":0}]}

data: {"choices":[{"delta":{},"finish_reason":"stop"}]}

data: [DONE]

网关如何处理这些字段

① model → Semantic Router 选模型组

② messages[0].content → system prompt hash → Consistent Hash → 固定 Worker

③ max_tokens → Token Bucket 预扣配额 (input×1 + output×2)

⑤ stream → 网关用 stream=True 转发，逐 chunk 返回

usage → 计费系统读取，写审计日志

AI 网关的协议转换角色

对外: 标准 OpenAI API (/v1/chat/completions)
对内: 可转发到不同的后端协议 (vLLM/gRPC/其他)
用户用 openai Python SDK → 零修改 → 享受 vLLM 高性能
«用户无感知 — OpenAI SDK 直接可用，后端换什么都行»