# SDK 与框架集成 - GateLLM

> 把任意 SDK 或框架接入 GateLLM:OpenAI、Anthropic、Gemini、DashScope、LangChain、LlamaIndex、CrewAI、Vercel AI SDK、OpenAI Agents SDK、Ollama 等 30+ —— 一行 base_url 切换,附各 SDK 的坑。

规范链接: https://www.gatellm.io/zh-CN/integrations/

## SDK 与框架集成
所有 SDK 都按同样的三步接入 GateLLM。找到你用的 SDK，看清它的 base_url 约定与坑，照着抄即可。
网关以协议为导向：不管你用哪个 SDK，只要它说 OpenAI / Anthropic / Gemini / DashScope / Realtime / MCP 其中一种协议，把它的 base_url 指向网关、换上 access key，就能调用任意已配置的模型 —— 包括跨协议调用其他厂商的模型。
## 兼容你正在用的 SDK
一行代码，把任意 SDK 或框架接到网关。OpenAI、Anthropic、Gemini、DashScope 原生接入；LangChain、LlamaIndex、CrewAI、Vercel AI SDK 等 30+ 框架同样只换 base_url。
### base_url 指向网关
默认 https://your-gateway.gatellm.io —— 是否含 /v1 因 SDK 而异（每个示例给出确切值）。
### 换成网关 access key
不是上游的 sk-… 密钥 —— 同一把 access key 装进你 SDK 期望的任意 header。
### 模型名用网关配置名
是你在控制台配置的名字 —— 不是厂商官方名。
```
# base_url 约定因 SDK 而异 —— 匹配你正在用的那个
from openai import OpenAI
OpenAI(base_url="https://your-gateway.gatellm.io/v1")        # OpenAI SDK：带 /v1

import anthropic
anthropic.Anthropic(base_url="https://your-gateway.gatellm.io")  # Anthropic SDK：根（自己拼 /v1/messages）

# Vercel AI SDK 的 createAnthropic：baseURL 要 ".../v1"（自己拼 /messages）—— 正好相反
# LangChain ChatOpenAI：base_url="https://your-gateway.gatellm.io/v1"
```
### `Authorization: Bearer <key>`
- SDK / 框架: OpenAI · DashScope · 通用
- Bearer 前缀大小写不敏感

### `x-api-key: <key>`
- SDK / 框架: Anthropic SDK
- 也接受 Authorization

### `x-goog-api-key: <key>`
- SDK / 框架: Gemini SDK
- 也接受 Authorization

## SDK 选型矩阵

### 官方厂商 SDK
OpenAI / Anthropic / Google SDK 原生接入 —— 只改 base_url
| SDK / 框架 | 语言 | 协议 | 文档 |
| --- | --- | --- | --- |
| OpenAI SDK | Python, Node.js | OpenAI | https://docs.gatellm.io/zh-CN/sdk/vendor-sdks |
| Anthropic SDK | Python, Node.js | Anthropic | https://docs.gatellm.io/zh-CN/sdk/vendor-sdks |
| Google GenAI SDK | Python, JavaScript | Gemini | https://docs.gatellm.io/zh-CN/sdk/vendor-sdks |
| OpenAI-compatible third parties | Python, Node.js | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/vendor-sdks |

### DashScope 原生
文本、图像、异步视频、embedding、rerank 走同一入口
| SDK / 框架 | 语言 | 协议 | 文档 |
| --- | --- | --- | --- |
| DashScope SDK | Python | DashScope | https://docs.gatellm.io/zh-CN/quickstart/dashscope |

### 统一 SDK / 网关层
Vercel AI SDK、LiteLLM、Portkey、Semantic Kernel、Spring AI
| SDK / 框架 | 语言 | 协议 | 文档 |
| --- | --- | --- | --- |
| Vercel AI SDK | TypeScript | OpenAI / Anthropic | https://docs.gatellm.io/zh-CN/sdk/unified-sdks |
| LiteLLM | Python | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/unified-sdks |
| Portkey | Node.js, Python | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/unified-sdks |
| Braintrust / Langbase | TypeScript, Python | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/unified-sdks |
| Semantic Kernel | Python, .NET | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/unified-sdks |
| Spring AI | Java | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/unified-sdks |

### 编排框架
LangChain、LlamaIndex、CrewAI、AutoGen、DSPy、Haystack
| SDK / 框架 | 语言 | 协议 | 文档 |
| --- | --- | --- | --- |
| LangChain | Python, TypeScript | OpenAI / Anthropic | https://docs.gatellm.io/zh-CN/sdk/orchestration-frameworks |
| LangGraph | Python, TypeScript | OpenAI / Anthropic | https://docs.gatellm.io/zh-CN/sdk/orchestration-frameworks |
| LlamaIndex | Python, TypeScript | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/orchestration-frameworks |
| CrewAI | Python | OpenAI-compatible (LiteLLM) | https://docs.gatellm.io/zh-CN/sdk/orchestration-frameworks |
| AutoGen / AG2 | Python | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/orchestration-frameworks |
| DSPy | Python | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/orchestration-frameworks |
| Haystack | Python | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/orchestration-frameworks |
| Llama Stack | Python | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/orchestration-frameworks |

### Agent SDK
OpenAI Agents、Claude Agent、Pydantic AI、ADK、Mastra
| SDK / 框架 | 语言 | 协议 | 文档 |
| --- | --- | --- | --- |
| OpenAI Agents SDK | Python, TypeScript | OpenAI Responses | https://docs.gatellm.io/zh-CN/sdk/agent-sdks |
| Claude Agent SDK | Python, TypeScript | Anthropic | https://docs.gatellm.io/zh-CN/quickstart/anthropic-interop |
| Pydantic AI | Python | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/agent-sdks |
| Google ADK | Python | OpenAI-compatible (LiteLLM) | https://docs.gatellm.io/zh-CN/sdk/agent-sdks |
| Mastra | TypeScript | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/agent-sdks |
| Microsoft Agent Framework | .NET, Python | OpenAI-compatible | https://docs.gatellm.io/zh-CN/sdk/agent-sdks |
| MCP SDK | Python, TypeScript | MCP | https://docs.gatellm.io/zh-CN/reference/mcp-config |

### 实时语音
Realtime WebSocket 语音 + openai_audio 转写 / 合成
| SDK / 框架 | 语言 | 协议 | 文档 |
| --- | --- | --- | --- |
| Realtime WebSocket | Any WS client | OpenAI Realtime | https://docs.gatellm.io/zh-CN/sdk/realtime-and-audio |
| openai_audio (ASR / TTS) | Python, Node.js | OpenAI audio | https://docs.gatellm.io/zh-CN/sdk/realtime-and-audio |

### 本地 / 自托管
Ollama、vLLM、llama.cpp 作上游 —— 客户端 SDK 不变
| SDK / 框架 | 语言 | 协议 | 文档 |
| --- | --- | --- | --- |
| Ollama | REST | OpenAI-compatible (upstream) | https://docs.gatellm.io/zh-CN/sdk/local-inference |
| vLLM | REST | OpenAI-compatible (upstream) | https://docs.gatellm.io/zh-CN/sdk/local-inference |
| llama.cpp server | REST | OpenAI-compatible (upstream) | https://docs.gatellm.io/zh-CN/sdk/local-inference |
| SGLang | REST | OpenAI-compatible (upstream) | https://docs.gatellm.io/zh-CN/sdk/local-inference |
| Text Generation Inference (TGI) | REST | OpenAI-compatible (upstream) | https://docs.gatellm.io/zh-CN/sdk/local-inference |
| LM Studio | REST | OpenAI-compatible (upstream) | https://docs.gatellm.io/zh-CN/sdk/local-inference |

## 接入坑
### 模型名必须等于网关配置名
不是厂商官方名，也不是上游真实模型 ID —— 是你在控制台起的名字。名字不对 → 404 model_not_found。

### base_url 是否带 /v1 因 SDK 而异
OpenAI SDK 带 /v1；Anthropic SDK 指网关根（它自己拼 /v1/messages）；Vercel AI SDK 的 createAnthropic 要带 /v1（它自己拼 /messages）。拼错会多一段或少一段路径。

### 跨协议字段会被翻译并受约束
当上游是 Responses 协议模型时，max_tokens 会被翻译成 max_output_tokens，且上游可能设下界（如 ≥16）—— 太小 → 400。

### 思考块被网关包裹
Claude / Gemini 的思考内容与签名会被透传或剥除 —— 取 content 数组里 type == "text" 的元素，别假设 content[0] 是文本。

### OpenAI Agents SDK 默认打 /v1/responses
它调的是 Responses API，不是 Chat Completions。上游是 openai（Chat）协议时，用 OpenAIChatCompletionsModel 显式切到 Chat；上游本身是 openai_response 时，字符串模型名直接用。

### LlamaIndex 按白名单校验模型名
OpenAI 类只认它认识的一系列名称，会拒绝自定义网关名 —— 用 OpenAILike（Python）或显式声明模型信息绕过。

### CrewAI 底层是 LiteLLM
base_url 不是框架参数 —— 是 OPENAI_API_BASE 环境变量，而且 model 要带 openai/ 前缀。

### AutoGen 对未知模型名要显式 model_info
不在默认清单的模型名会报错 —— 显式声明 model_info 绕过校验。

### Google GenAI SDK 指向网关根
base_url 经 http_options.base_url 传入（不带 /v1），key 装在 x-goog-api-key header。

## 常见问题
### GateLLM 能接 LangChain / LlamaIndex / CrewAI 吗？
能 —— 把各框架底层的 chat model 指向网关的 OpenAI 兼容端点即可。各自的「改 base_url」入口不同:LangChain 用 ChatOpenAI(base_url=…),LlamaIndex 用 OpenAILike(它的 OpenAI 类会拒绝自定义模型名),CrewAI 设 OPENAI_API_BASE 环境变量(它底层是 LiteLLM)。
### 能经 GateLLM 用 Claude Agent SDK 或 Claude Code 吗？
能。它们读 ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN 环境变量 —— 指向网关根、用网关 access key。把网关模型名起成 agent 请求的 ID(或用 ANTHROPIC_MODEL 对齐)最省事。
### 怎么接 OpenAI Agents SDK？
把它的 OpenAI client 指向网关、设好模型名。注意它默认打 /v1/responses —— 上游是 Chat 协议模型时,用 OpenAIChatCompletionsModel 显式切换。用 set_tracing_disabled 关掉 tracing,免得 trace 也打到网关。
### GateLLM 能前置 Ollama / vLLM / llama.cpp 吗？
能 —— 把它们配成 OpenAI 兼容上游,客户端 SDK 保持不动。网关在自托管模型之上叠加路由、fallback 与治理。
### base_url 到底带不带 /v1？
因 SDK 而异:OpenAI SDK 带 /v1;Anthropic SDK 指根(它自己拼 /v1/messages);Vercel AI SDK 的 createAnthropic 带 /v1(它自己拼 /messages)。文档给出每个 SDK 的确切值。
### 网关 access key 和上游密钥有什么区别？
网关 access key 是客户端出示的凭证,装进你 SDK 用的任意 header(Authorization、x-api-key 或 x-goog-api-key)。上游厂商密钥留在网关里,永不暴露给客户端。

## 相关页面
- [首页](https://www.gatellm.io/zh-CN/index.md)
- [定价](https://www.gatellm.io/zh-CN/pricing.md)
- [成本计算器](https://www.gatellm.io/zh-CN/calculator.md)
- [关于](https://www.gatellm.io/zh-CN/about.md)
- [预约演示](https://www.gatellm.io/zh-CN/demo.md)
- [常见问题](https://www.gatellm.io/zh-CN/faq.md)
- [对比 AI 网关](https://www.gatellm.io/zh-CN/compare.md)
- [对比 LiteLLM](https://www.gatellm.io/zh-CN/compare/litellm.md)
- [对比 OpenRouter](https://www.gatellm.io/zh-CN/compare/openrouter.md)
- [对比 Alibaba Cloud AI Gateway](https://www.gatellm.io/zh-CN/compare/alibaba-cloud.md)
- [对比 Azure API Management](https://www.gatellm.io/zh-CN/compare/azure-apim.md)
- [对比 Apigee](https://www.gatellm.io/zh-CN/compare/apigee.md)
- [对比 Cloudflare AI Gateway](https://www.gatellm.io/zh-CN/compare/cloudflare.md)
- [对比 Kong AI Gateway](https://www.gatellm.io/zh-CN/compare/kong.md)
- [对比 Portkey](https://www.gatellm.io/zh-CN/compare/portkey.md)
- [LiteLLM vs Kong AI Gateway 对比](https://www.gatellm.io/zh-CN/compare/litellm-vs-kong.md)
- [LiteLLM vs OpenRouter 对比](https://www.gatellm.io/zh-CN/compare/litellm-vs-openrouter.md)
- [LiteLLM vs Portkey 对比](https://www.gatellm.io/zh-CN/compare/litellm-vs-portkey.md)
- [场景方案](https://www.gatellm.io/zh-CN/use-cases.md)
- [降低调用成本](https://www.gatellm.io/zh-CN/use-cases/reduce-cost.md)
- [做到高可用](https://www.gatellm.io/zh-CN/use-cases/high-availability.md)
- [多租户隔离](https://www.gatellm.io/zh-CN/use-cases/multi-tenant.md)
- [合规与审计](https://www.gatellm.io/zh-CN/use-cases/compliance-audit.md)
- [从症状排障](https://www.gatellm.io/zh-CN/use-cases/troubleshooting.md)
- [混合多供应商模型栈](https://www.gatellm.io/zh-CN/use-cases/mixed-model-stack.md)
- [在 Office 里自托管用 AI](https://www.gatellm.io/zh-CN/use-cases/self-hosted-office-ai.md)
- [Token 用量可见与归因](https://www.gatellm.io/zh-CN/use-cases/token-ops.md)
- [Token FinOps: AI 支出分摊与管控](https://www.gatellm.io/zh-CN/use-cases/token-finops.md)
- [MCP 工具治理](https://www.gatellm.io/zh-CN/use-cases/mcp-tool-governance.md)
- [给模型统一加联网搜索](https://www.gatellm.io/zh-CN/use-cases/web-search-grounding.md)
- [多 Key 轮询与备用](https://www.gatellm.io/zh-CN/use-cases/multi-key-pooling.md)
- [限制接入的客户端](https://www.gatellm.io/zh-CN/use-cases/client-admission-control.md)
- [强制模型使用策略](https://www.gatellm.io/zh-CN/use-cases/enforce-model-policy.md)
- [客户端不暴露模型选择](https://www.gatellm.io/zh-CN/use-cases/automatic-model-tiering.md)
- [一套协议接任意模型](https://www.gatellm.io/zh-CN/use-cases/one-protocol-any-model.md)
- [Office / Microsoft 365 加载项](https://www.gatellm.io/zh-CN/office-addin.md)
- [术语表](https://www.gatellm.io/zh-CN/glossary.md)
- [模型目录](https://www.gatellm.io/zh-CN/models.md)
- [AI Coding Agent 与 Harness](https://www.gatellm.io/zh-CN/coding-agents.md)
- [安全与合规](https://www.gatellm.io/zh-CN/security.md)
- [隐私政策](https://www.gatellm.io/zh-CN/privacy-policy.md)
- [服务条款](https://www.gatellm.io/zh-CN/terms.md)
- [Cookie 政策](https://www.gatellm.io/zh-CN/cookies.md)
- [数据处理协议 (DPA)](https://www.gatellm.io/zh-CN/dpa.md)
- [子处理方清单](https://www.gatellm.io/zh-CN/subprocessors.md)
- [安全问卷预答库 (CAIQ/SIG/VSA)](https://www.gatellm.io/zh-CN/trust.md)
- [事故响应与支持服务](https://www.gatellm.io/zh-CN/sla.md)
- [漏洞披露政策](https://www.gatellm.io/zh-CN/vulnerability-disclosure.md)
- [开源许可声明](https://www.gatellm.io/zh-CN/open-source-licenses.md)
- [版本支持与生命周期 (EOL)](https://www.gatellm.io/zh-CN/lifecycle.md)
- [技术博客](https://www.gatellm.io/zh-CN/blog.md)
- [你的 Agent 权限比员工还大:在网关层治理 MCP 工具](https://www.gatellm.io/zh-CN/blog/mcp-tool-governance.md)
- [一张一万美元的账单:五种降低 LLM 成本又不让应用变笨的做法](https://www.gatellm.io/zh-CN/blog/reduce-cost.md)
- [厂商的目录价不是你的成本:把真正的 FinOps 用到 Token 支出上](https://www.gatellm.io/zh-CN/blog/token-finops.md)
- [llms.txt](https://www.gatellm.io/zh-CN/llms.txt)