> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/quickstart/openai-compatible · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 接入 OpenAI 上游

本章假设你已经把网关跑起来了（见 [Docker 单机跑通](/zh-CN/quickstart/docker-single-node.md)）。下面带你配一个 OpenAI 上游 + 一个 `gpt-4o` 模型，然后从 OpenAI SDK / curl 调用，并解释一些跨协议的小细节。

## 前置

- 网关已运行（`http://localhost:7890`），能登录控制台
- 已设 `ENCRYPTION_KEY`——下面要保存的上游 API key 与访问密钥都落库前加密，没设会在保存时报 `encryption_key not set in config`。见 [Docker 单机跑通 → 前置](/zh-CN/quickstart/docker-single-node.md#prereq)
- 一个 OpenAI API key（`sk-...`）

## 1. 建上游

控制台 → **上游服务** → **新建**，填：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `openai` | 上游唯一标识 |
| 协议 | `openai` | 决定执行器与请求 schema |
| 基础 URL | `https://api.openai.com/v1` | 上游真实地址，结尾不带 `/` |
| API Key | `sk-...` | 上游给你的密钥，点「添加」可加多把，按权重分布 |
| 启用 | ✓ | |

保存。上游列表出现 `openai`，状态为活跃。

## 2. 建模型

在上游 `openai` 行点 **展开** → 模型子表 → **新建模型**，填：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `gpt-4o` | 客户端调用时填的模型名 |
| 上游 | `openai` | 选刚建的上游 |
| 上游模型 ID | `gpt-4o` | 上游真实模型名 |
| 启用 | ✓ | |

保存。客户端用 `gpt-4o` 调用时，网关路由到上游 `openai` 的 `gpt-4o`。

> 「名称」对外暴露给客户端；「上游模型 ID」是发往上游的真实名字。两者不同就实现了模型别名/重命名。

## 3. 配密钥组放行

控制台 → **访问密钥** → **密钥组** 页签 → **新建**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `default` | 分组名 |
| 模型 | 选 `gpt-4o`，或 `*`（全部） | 决定该组密钥能调哪些模型 |
| 启用 | ✓ | |

## 4. 签发访问密钥

控制台 → **访问密钥** → **新建**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `my-app-key` | 标识 |
| API 密钥 | 点「生成」 | 自动生成一串，客户端实际带的凭证 |
| 分组 | `default` | 选刚建的组 |
| 启用 | ✓ | |

保存。点该行「复制」按钮可取完整密钥值。

> 客户端用的是**这把访问密钥**，不是上游的 `sk-...`。

## 5. 用 OpenAI SDK 调用

OpenAI Python / Node SDK：

```text
base_url = http://localhost:7890/v1
api_key  = <你的访问密钥>
```

Python 示例：

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:7890/v1",
    api_key="<你的访问密钥>",
)

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
```

## 6. 或用 curl

```bash
curl http://localhost:7890/v1/chat/completions \
  -H "Authorization: Bearer <你的访问密钥>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role":"user","content":"你好"}]
  }'
```

收到模型回复即跑通。

## 跨协议互译

OpenAI 上游 + OpenAI 客户端是「同协议 identity 路径」，网关不做翻译，直接转发。但你也可以用 Anthropic SDK / Gemini SDK 调这个 `gpt-4o` 模型——网关会把客户端协议翻译成上游协议（`openai`），再把响应翻译回客户端格式。

例如用 Anthropic SDK 调用：

```bash
curl http://localhost:7890/v1/messages \
  -H "x-api-key: <你的访问密钥>" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","max_tokens":1024,"messages":[{"role":"user","content":"hi"}]}'
```

请求体是 Anthropic 格式，网关翻译成 OpenAI 格式发给上游，响应再翻译回 Anthropic 格式。客户端无感。完整互通矩阵见 [协议互通矩阵](/zh-CN/reference/protocol-matrix.md)。

## 常见问题

**Q：客户端报 401？**
访问密钥没带对。检查 `Authorization: Bearer` 后面跟的是网关访问密钥（不是上游的 `sk-...`）。

**Q：客户端报 403 model_access_denied？**
密钥所在的密钥组「模型」列表没包含 `gpt-4o`。回到密钥组把该模型加进去，或改成 `*`。

**Q：客户端报 404 model_not_found？**
模型名拼错，或该模型被设了 `hide_name`（只能用别名访问）。检查控制台里模型的「名称」字段与客户端 `model` 参数是否一致。

**Q：客户端报 502 bad_gateway？**
上游不通。检查 OpenAI 的 `base_url`（必须 `https://api.openai.com/v1`，结尾不带 `/`）和 API key 是否正确、上游是否可访问。

**Q：怎么让多个上游（多把 OpenAI key）做故障转移？**
用负载均衡器，见 [多上游负载均衡](/zh-CN/quickstart/multi-upstream-load-balancing.md)。

**下一步**：[端点 · 认证 · 协议互通](/zh-CN/reference/endpoints.md) 看完整端点清单；[客户端接入与网关差异](/zh-CN/reference/clients-and-gateway-diffs.md) 看各 SDK 接法和网关特有行为；[Anthropic 跨协议](/zh-CN/quickstart/anthropic-interop.md) 看反向的跨协议例子。