API 中转站（API Relay / 代理网关）

1. 定义

API 中转站（API Relay） 是一个服务端程序：对外暴露一个 OpenAI 兼容（或 Anthropic 兼容）的端点，内部把请求转发 / 翻译给真实模型供应商（OpenAI、Anthropic、Gemini 等），并提供单一 key、统一计费、负载均衡等能力。

一句话总结：它就是部署在云端（或本地）的”OpenAI 兼容端点” + 一层翻译与调度。对照 openai_compatible_sdk.md：那篇讲客户端怎么换底座，这篇讲服务端怎么把自己做成那个”底座”。

类比：中转站像”代购/总代理”——你只跟它打交道（一个 key、一套接口），它背后帮你对接 N 家真供应商，还帮你比价、拼单、换货。

2. 它解决什么问题

痛点	直连各家时	走中转站后
多供应商管理	每家一个 key、一套 SDK、一套字段	一个 key、一套 OpenAI 形状
计费/对账	分散在多张账单	统一入口、统一计量
格式不统一	Claude 用 Anthropic 格式、OpenAI 用另一套	中转站做格式翻译，客户端只写 OpenAI 形状
稳定性	某家限流/宕机就挂	负载均衡 + 失败重试 + 多供应商 failover
成本/合规	难统一管控	可设预算上限、审计日志、私有化部署

3. 工作原理

中转站 = “兼容端点 + 翻译 + 调度”三层。客户端（SDK 或 CLI）唯一要做的，就是把 base_url 指过来。

你的客户端（openai SDK / Claude Code / Codex / cc-switch 改过的 CLI）
        │  base_url 改指中转站
        ▼
┌──────────────────────────────────────────────┐
│  中转站（API Relay）                            │
│  ┌────────────────────────────────────────┐  │
│  │ ① 兼容端点层                             │  │
│  │   POST /v1/chat/completions（OpenAI 形状）│  │
│  └───────────────┬────────────────────────┘  │
│  ┌───────────────▼────────────────────────┐  │
│  │ ② 翻译层（关键）                         │  │
│  │   OpenAI 形状 ⇄ Anthropic 形状 ⇄ Gemini │  │
│  │   （messages/tools/streaming 字段互转）   │  │
│  └───────────────┬────────────────────────┘  │
│  ┌───────────────▼────────────────────────┐  │
│  │ ③ 调度层                                 │  │
│  │   选供应商 / 负载均衡 / 失败重试 / failover│  │
│  │   计费计量 / 预算上限 / 审计日志           │  │
│  └───────────────┬────────────────────────┘  │
└──────────────────┼──────────────────────────┘
                   │  实际请求真实 API
       ┌───────────┼───────────────┐
       ▼           ▼               ▼
   OpenAI      Anthropic        Gemini
  （真供应商）  （真供应商）     （真供应商）

格式翻译是中转站区别于普通反向代理的核心：比如把 OpenAI 的 messages: [{role, content}] 翻成 Anthropic 的 system + messages，把 tools 翻成 Claude 的 tools 形状——这样Claude Code 也能被 OpenAI 兼容端点驱动（正是 cc-switch “让 Claude Code 用 OpenAI 格式 API” 的原理）。

4. 基本用法

客户端：只改 base_url

from openai import OpenAI
client = OpenAI(
    base_url="https://你的中转站/v1",   # 指向中转站，而非 api.openai.com
    api_key="中转站发的统一key",
)
# 之后 model 填中转站支持的任意供应商模型名即可
resp = client.chat.completions.create(
    model="claude-3-5-sonnet",          # 经翻译层转发给 Anthropic
    messages=[{"role": "user", "content": "hi"}],
)

Claude Code 类 CLI：靠环境变量重定向（cc-switch 帮你做这件事）

# 把 CLI 的流量从官方端点改指中转站（cc-switch 本质是自动写这些变量）
export ANTHROPIC_BASE_URL="https://你的中转站"   # 或 /v1 看中转站约定
export ANTHROPIC_AUTH_TOKEN="中转站统一key"
# 之后 Claude Code 的所有请求都先到中转站，再由它翻译/转发

自建中转站（以 LiteLLM 为例）

# litellm 配置：把多家供应商收成一个 OpenAI 兼容端点
model_list:
  - model_name: gpt-4o
    litellm_params: { model: openai/gpt-4o, api_key: os.environ[OPENAI_KEY] }
  - model_name: claude-3-5-sonnet
    litellm_params: { model: anthropic/claude-3-5-sonnet, api_key: os.environ[ANTHROPIC_KEY] }

启动后监听 :4000，对外就是标准 OpenAI 兼容端点。

5. 对比辨析表

中转站 vs 直连原生 SDK vs 本地兼容服务

维度	API 中转站	直连各家原生 SDK	本地兼容服务（Ollama/vLLM）
位置	远端（云）或自建	各家云端	本机
接口	OpenAI（+ 翻译）	各家独有	OpenAI 形状
key 管理	单一中转 key	多家 key	无需 key
翻译能力	有（核心卖点）	无（本家格式）	通常无（本家格式）
计费/审计	统一	分散	免费（本地算力）
典型代表	One API、LiteLLM 部署、商业 relay	openai / anthropic SDK	Ollama、vLLM

开源自建 vs 商业 relay 服务

维度	自建（LiteLLM / One API）	商业 relay 服务
掌控力	完全自控、可私有化	依赖第三方
密钥安全	key 在自己手里	key 经第三方中转（需信任）
上手成本	要部署运维	注册即用
成本	只付真实 API 费 + 服务器	通常加价（服务费）
适用	企业/隐私敏感/需审计	个人快速体验多模型

6. 典型工作流

个人：cc-switch + 中转站多模型体验

cc-switch 配置多个中转 key（Claude / GPT / Gemini 统一入口）
   │ 一键切换 ANTHROPIC_BASE_URL / api_key
   ▼
Claude Code / openai SDK  ←→  中转站  ←→  真实供应商
（只写一套 OpenAI 形状代码，背后换供应商）

团队：自建统一网关

多个业务服务（各自只认 openai SDK）
        │  base_url 全指到团队中转站 :4000
        ▼
   自建 LiteLLM 中转站
        ├─ 统一 key 与配额
        ├─ 审计日志（谁调了啥、花多少）
        └─ failover：某供应商挂了自动切另一家

接手已有项目：识别中转层

1. 找 base_url / ANTHROPIC_BASE_URL 实际指向哪（是不是中转站域名）
2. 确认翻译覆盖度：tools/streaming/图像 是否都支持
3. 计费口径：从哪看用量与账单

7. 常见误区

❌ “中转站就是模型供应商，能自己生成回答” 正确：中转站不持有模型，只是转发 + 翻译。回答质量、知识截止、能力边界仍由背后的真实供应商决定。

❌ “用了中转站，所有模型能力完全一致” 正确：翻译层是子集映射。某些独有特性（Claude 的 extended thinking、OpenAI 的图像生成）中转站未必实现，或映射有损——换底座后务必重测行为（见 openai_compatible_sdk.md 第 7 节）。

❌ “中转站 = 免费” 正确：商业 relay 通常在真实 API 费上加服务费；自建也要付真实 API 费 + 服务器成本。省的是”管理成本”，不是”推理成本”。

❌ “中转站能绕过供应商的合规/限速” 正确：最终请求还是打到真实供应商，对方的内容策略、速率限制、区域限制依然生效。中转站只解决”接口统一”，不解决”供应商政策”。

❌ “把 key 交给中转站没风险” 正确：第三方中转会经手你的请求内容和 key，有数据泄露/审计风险。敏感场景优先自建私有中转（LiteLLM），而非盲信商业 relay。

8. 延伸阅读 / 关联概念

openai_compatible_sdk.md — 客户端侧：同一份代码改 base_url 调不同模型（本文的”服务端对应物”）
agent_dev.md — 代码级开发中”调哪个模型”的统一客户端层
tool_calling.md / hermes.md — 工具调用字段如何在翻译层里保持对齐
mcp.md — MCP 是”接工具”的协议层，与”调模型 API”是不同层面（中转站管后者）
../networking/http_methods_fetch.md — 中转站收到的正是这些 POST 请求；怎么用 Fetch/curl 发出去
openclaw.md — 开源 Agent 框架底层也常经兼容客户端/中转调模型

第二大脑 / Knowledge Bank

探索

api_relay