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


# SDK 集成总览

网关是**协议导向**的入口：不管你在客户端用哪个 SDK，只要能说网关支持的协议（OpenAI / Anthropic / Gemini / DashScope / Realtime / MCP / 透传），把 base_url 指到网关、API key 换成网关签发的访问密钥，就能调网关里配好的任何模型——包括**跨协议调别家模型**。这一组页面按「你手上已有哪个 SDK」组织，每页给可直接复制的最小示例。

## 通用三步 {#three-steps}

所有 SDK 都遵循同一条接线规则：

1. **`base_url` 指向网关**（默认 `http://localhost:7890`）。注意各 SDK 对 base_url 是否带 `/v1` 的约定不同，见各页示例。
2. **API key 填网关签发的访问密钥**，不是上游的 `sk-...`。访问密钥在控制台「访问密钥」页签发。
3. **`model` 填网关里配置的模型名**。网关不按模型名限制调用——控制台里配什么名，客户端就填什么名。

示例里出现的模型名（`gpt-5.4-mini`、`claude-haiku-4-5`、`gemini-3.5-flash`、`qwen3.8-max` 等）只是「某套网关配置下的真实名字」，实际以你的控制台配置为准。

## 认证头对照 {#auth-headers}

数据面端点按顺序尝试以下认证方式，命中即用（详见 [端点 · 认证](/zh-CN/reference/endpoints.md#auth)）：

| 请求头 | 对应 SDK | 备注 |
|--------|---------|------|
| `Authorization: Bearer <访问密钥>` | OpenAI、DashScope、通用 | `Bearer` 前缀大小写不敏感 |
| `x-api-key: <访问密钥>` | Anthropic SDK | 也接受 `Authorization` |
| `x-goog-api-key: <访问密钥>` | Gemini SDK | 也接受 `Authorization` |
| （无以上头） | — | 匿名兜底，仅当配了 `anonymous=true` 的密钥时 |

> 三把头其实是同一个「网关访问密钥」的不同挂载位——你在控制台签一把，按 SDK 的习惯放到对应头即可。

## SDK 选型矩阵 {#selection-matrix}

「我已经在用 X，怎么接到网关？」按行找：

| SDK / 框架 | 语言 | 落点协议 / 端点 | 语言 | 图像 | 视频 | 实时 | 向量/重排 | 页面 |
|-----------|------|----------------|------|------|------|------|-----------|------|
| OpenAI SDK | Py / Node | `openai` 系（`/v1/chat/completions`、`/v1/responses`…） | ✅ | ✅ | — | ✅¹ | ✅ | [官方厂商 SDK](/zh-CN/sdk/vendor-sdks.md) |
| Anthropic SDK | Py / Node | `anthropic`（`/v1/messages`） | ✅ | 输入理解 | — | — | — | [官方厂商 SDK](/zh-CN/sdk/vendor-sdks.md) |
| Google GenAI SDK | Py / JS | `google`（`/v1beta/models/*`） | ✅ | ✅ | — | — | — | [官方厂商 SDK](/zh-CN/sdk/vendor-sdks.md) |
| DashScope SDK / HTTP | Py | `dashscope`（`/v1/services/*`） | ✅ | ✅ | ✅ 异步 | ✅¹ | ✅ | [DashScope 原生与异步任务](/zh-CN/sdk/dashscope-native.md) |
| OpenAI 兼容第三方（DeepSeek/GLM/Kimi/Grok…） | Py / Node | `openai` 兼容 | ✅ | 视供应商 | — | — | 视供应商 | [官方厂商 SDK](/zh-CN/sdk/vendor-sdks.md) |
| Vercel AI SDK | TS | `openai` / `anthropic`（provider 层） | ✅ | 视 provider | — | — | 视 provider | [统一 SDK 与网关层](/zh-CN/sdk/unified-sdks.md) |
| LiteLLM | Py | `openai` 兼容 | ✅ | 视模型 | — | — | ✅ | [统一 SDK 与网关层](/zh-CN/sdk/unified-sdks.md) |
| LangChain / LangGraph | Py / TS | 其底层 chat model（OpenAI/Anthropic…） | ✅ | 视模型 | — | — | ✅ | [编排框架](/zh-CN/sdk/orchestration-frameworks.md) |
| LlamaIndex | Py / TS | `OpenAILike` / chat model | ✅ | 视模型 | — | — | ✅ | [编排框架](/zh-CN/sdk/orchestration-frameworks.md) |
| CrewAI | Py | 底层 LiteLLM | ✅ | 视模型 | — | — | — | [编排框架](/zh-CN/sdk/orchestration-frameworks.md) |
| AutoGen / AG2 | Py | `openai` 兼容 | ✅ | 视模型 | — | — | — | [编排框架](/zh-CN/sdk/orchestration-frameworks.md) |
| OpenAI Agents SDK | Py / TS | `openai_response`（默认） | ✅ | 视模型 | — | — | — | [Agent SDK](/zh-CN/sdk/agent-sdks.md) |
| Claude Agent SDK | Py / TS | `anthropic` | ✅ | 输入理解 | — | — | — | [Agent SDK](/zh-CN/sdk/agent-sdks.md) |
| Pydantic AI | Py | `openai` 兼容 | ✅ | 视模型 | — | — | — | [Agent SDK](/zh-CN/sdk/agent-sdks.md) |
| Realtime（WebSocket） | 任意 WS 客户端 | `openai_realtime`（`/v1/realtime`） | — | — | — | ✅ | — | [实时会话与语音](/zh-CN/sdk/realtime-and-audio.md) |

> ¹ 实时（Realtime）经网关的 OpenAI Realtime 客户端协议（`/v1/realtime`）通过原生 WebSocket 接入——无需厂商 SDK；`model` 填实时模型在网关里的配置名（OpenAI 或 DashScope）。

## 跨 SDK 通用坑 {#common-pitfalls}

不管用哪个 SDK，经网关后都要注意这几点（各页会重复提醒，这里集中列出）：

- **模型名必须与网关配置一致**。客户端填的 `model` 是「网关里配的名字」，不是厂商官网名，也不是上游真实模型 ID。填错了直接 404 `model_not_found`。
- **base_url 带不带 `/v1` 因 SDK 而异**。OpenAI SDK 填到 `/v1`，Anthropic SDK 填到根（它自动拼 `/v1/messages`），Google GenAI 填到根（走 `http_options.base_url`）。填错会多出或丢掉一段路径。
- **跨协议时字段会被翻译、并受目标协议约束**。例如网关里某模型的 `gpt-5.6-sol` 若上游是 Responses 协议，客户端传的 `max_tokens` 会被译成 `max_output_tokens`，且上游可能要求下限（如 ≥16），传太小会 400。
- **思考块 / 签名经网关封装**。Claude 与 Gemini 的思考内容（thinking / thoughtSignature）会经网关透传或剥离，取文本时要按 `content` 数组里 `type == "text"` 的元素取，别假设 `content[0]` 一定是文本。
- **第三方 SDK 的模型名白名单**。部分框架（LlamaIndex、AutoGen 等）会校验模型名是否符合它认识的家族，遇到未知网关名会拒绝——用它的「任意模型」入口或显式声明模型信息（见各页）。

## 下一步 {#next}

- 只想跑通最小调用：先看 [官方厂商 SDK](/zh-CN/sdk/vendor-sdks.md)。
- 前端 / Next.js：看 [统一 SDK 与网关层](/zh-CN/sdk/unified-sdks.md)。
- 已经用 LangChain / LlamaIndex / CrewAI：看 [编排框架](/zh-CN/sdk/orchestration-frameworks.md)。
- 要接语音 / 视频等偏僻能力：看 [实时会话与语音](/zh-CN/sdk/realtime-and-audio.md) 与 [DashScope 原生与异步任务](/zh-CN/sdk/dashscope-native.md)。
- 供应商与模型全清单（不含 SDK 示例）：看 [支持的供应商与模型](/zh-CN/reference/supported-models-and-sdks.md)。