# 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-TW/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-TW/index.md)
- [定價](https://www.gatellm.io/zh-TW/pricing.md)
- [成本計算器](https://www.gatellm.io/zh-TW/calculator.md)
- [關於](https://www.gatellm.io/zh-TW/about.md)
- [預約示範](https://www.gatellm.io/zh-TW/demo.md)
- [常見問題](https://www.gatellm.io/zh-TW/faq.md)
- [比較 AI 閘道](https://www.gatellm.io/zh-TW/compare.md)
- [比較 LiteLLM](https://www.gatellm.io/zh-TW/compare/litellm.md)
- [比較 OpenRouter](https://www.gatellm.io/zh-TW/compare/openrouter.md)
- [比較 Alibaba Cloud AI Gateway](https://www.gatellm.io/zh-TW/compare/alibaba-cloud.md)
- [比較 Azure API Management](https://www.gatellm.io/zh-TW/compare/azure-apim.md)
- [比較 Apigee](https://www.gatellm.io/zh-TW/compare/apigee.md)
- [比較 Cloudflare AI Gateway](https://www.gatellm.io/zh-TW/compare/cloudflare.md)
- [比較 Kong AI Gateway](https://www.gatellm.io/zh-TW/compare/kong.md)
- [比較 Portkey](https://www.gatellm.io/zh-TW/compare/portkey.md)
- [LiteLLM vs Kong AI Gateway 比較](https://www.gatellm.io/zh-TW/compare/litellm-vs-kong.md)
- [LiteLLM vs OpenRouter 比較](https://www.gatellm.io/zh-TW/compare/litellm-vs-openrouter.md)
- [LiteLLM vs Portkey 比較](https://www.gatellm.io/zh-TW/compare/litellm-vs-portkey.md)
- [場景方案](https://www.gatellm.io/zh-TW/use-cases.md)
- [降低呼叫成本](https://www.gatellm.io/zh-TW/use-cases/reduce-cost.md)
- [達成高可用](https://www.gatellm.io/zh-TW/use-cases/high-availability.md)
- [多租戶隔離](https://www.gatellm.io/zh-TW/use-cases/multi-tenant.md)
- [合規與稽核](https://www.gatellm.io/zh-TW/use-cases/compliance-audit.md)
- [從症狀排障](https://www.gatellm.io/zh-TW/use-cases/troubleshooting.md)
- [混合多供應商模型堆疊](https://www.gatellm.io/zh-TW/use-cases/mixed-model-stack.md)
- [在 Office 內自架 AI](https://www.gatellm.io/zh-TW/use-cases/self-hosted-office-ai.md)
- [Token 用量可見性與歸因](https://www.gatellm.io/zh-TW/use-cases/token-ops.md)
- [Token FinOps: AI 支出分攤與管控](https://www.gatellm.io/zh-TW/use-cases/token-finops.md)
- [MCP 工具治理](https://www.gatellm.io/zh-TW/use-cases/mcp-tool-governance.md)
- [為所有模型統一加入網路搜尋](https://www.gatellm.io/zh-TW/use-cases/web-search-grounding.md)
- [多 Key 輪替與備援](https://www.gatellm.io/zh-TW/use-cases/multi-key-pooling.md)
- [限制接入的用戶端](https://www.gatellm.io/zh-TW/use-cases/client-admission-control.md)
- [強制模型使用政策](https://www.gatellm.io/zh-TW/use-cases/enforce-model-policy.md)
- [用戶端不暴露模型選擇](https://www.gatellm.io/zh-TW/use-cases/automatic-model-tiering.md)
- [一種協定,任何模型](https://www.gatellm.io/zh-TW/use-cases/one-protocol-any-model.md)
- [Office / Microsoft 365 增益集](https://www.gatellm.io/zh-TW/office-addin.md)
- [術語表](https://www.gatellm.io/zh-TW/glossary.md)
- [模型目錄](https://www.gatellm.io/zh-TW/models.md)
- [AI Coding Agent 與 Harness](https://www.gatellm.io/zh-TW/coding-agents.md)
- [安全性與合規](https://www.gatellm.io/zh-TW/security.md)