# 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/ko/integrations/

## SDK 및 프레임워크 통합
모든 SDK는 동일한 세 단계로 GateLLM에 연결됩니다. SDK를 찾고 base_url 규칙과 주의사항을 확인한 뒤 패턴을 복사하세요.
게이트웨이는 프로토콜 지향적입니다: 어떤 SDK를 쓰든 OpenAI / Anthropic / Gemini / DashScope / Realtime / MCP를 사용한다면, base_url을 게이트웨이로 지정하고 액세스 키를 교체하는 것만으로 구성된 모든 모델 — 다른 벤더 모델로의 프로토콜 교차 호출 포함 — 을 호출할 수 있습니다.
## 이미 쓰고 있는 SDK와 그대로 동작합니다
어떤 SDK나 프레임워크든 한 줄로 게이트웨이를 가리키게 하세요. OpenAI, Anthropic, Gemini, DashScope는 네이티브로 연결되고, LangChain, LlamaIndex, CrewAI, Vercel AI SDK 등 30개 이상은 동일한 base_url 교체로 연결됩니다.
### base_url을 게이트웨이로 지정
기본값은 https://your-gateway.gatellm.io 입니다 — /v1 포함 여부는 SDK마다 다릅니다(각 예시에 정확한 값을 표기).
### 게이트웨이 액세스 키로 교체
업스트림 sk-… 키가 아닙니다 — 같은 액세스 키가 SDK가 기대하는 헤더에 맞춰 들어갑니다.
### 게이트웨이 모델 이름 사용
콘솔에서 구성한 이름을 쓰세요 — 벤더의 공식 이름이 아닙니다.
```
# base_url convention differs by SDK — match the one you're using
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: root (appends /v1/messages)

# Vercel AI SDK createAnthropic: baseURL ".../v1" (appends /messages) — the reverse
# 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/en/sdk/vendor-sdks |
| Anthropic SDK | Python, Node.js | Anthropic | https://docs.gatellm.io/en/sdk/vendor-sdks |
| Google GenAI SDK | Python, JavaScript | Gemini | https://docs.gatellm.io/en/sdk/vendor-sdks |
| OpenAI-compatible third parties | Python, Node.js | OpenAI-compatible | https://docs.gatellm.io/en/sdk/vendor-sdks |

### DashScope 네이티브
텍스트, 이미지, 비동기 비디오, 임베딩 및 리랭크를 하나의 엔드포인트로
| SDK / 프레임워크 | 언어 | 프로토콜 | 문서 |
| --- | --- | --- | --- |
| DashScope SDK | Python | DashScope | https://docs.gatellm.io/en/quickstart/dashscope |

### 통합 SDK 및 게이트웨이
Vercel AI SDK, LiteLLM, Portkey, Semantic Kernel, Spring AI
| SDK / 프레임워크 | 언어 | 프로토콜 | 문서 |
| --- | --- | --- | --- |
| Vercel AI SDK | TypeScript | OpenAI / Anthropic | https://docs.gatellm.io/en/sdk/unified-sdks |
| LiteLLM | Python | OpenAI-compatible | https://docs.gatellm.io/en/sdk/unified-sdks |
| Portkey | Node.js, Python | OpenAI-compatible | https://docs.gatellm.io/en/sdk/unified-sdks |
| Braintrust / Langbase | TypeScript, Python | OpenAI-compatible | https://docs.gatellm.io/en/sdk/unified-sdks |
| Semantic Kernel | Python, .NET | OpenAI-compatible | https://docs.gatellm.io/en/sdk/unified-sdks |
| Spring AI | Java | OpenAI-compatible | https://docs.gatellm.io/en/sdk/unified-sdks |

### 오케스트레이션 프레임워크
LangChain, LlamaIndex, CrewAI, AutoGen, DSPy, Haystack
| SDK / 프레임워크 | 언어 | 프로토콜 | 문서 |
| --- | --- | --- | --- |
| LangChain | Python, TypeScript | OpenAI / Anthropic | https://docs.gatellm.io/en/sdk/orchestration-frameworks |
| LangGraph | Python, TypeScript | OpenAI / Anthropic | https://docs.gatellm.io/en/sdk/orchestration-frameworks |
| LlamaIndex | Python, TypeScript | OpenAI-compatible | https://docs.gatellm.io/en/sdk/orchestration-frameworks |
| CrewAI | Python | OpenAI-compatible (LiteLLM) | https://docs.gatellm.io/en/sdk/orchestration-frameworks |
| AutoGen / AG2 | Python | OpenAI-compatible | https://docs.gatellm.io/en/sdk/orchestration-frameworks |
| DSPy | Python | OpenAI-compatible | https://docs.gatellm.io/en/sdk/orchestration-frameworks |
| Haystack | Python | OpenAI-compatible | https://docs.gatellm.io/en/sdk/orchestration-frameworks |
| Llama Stack | Python | OpenAI-compatible | https://docs.gatellm.io/en/sdk/orchestration-frameworks |

### 에이전트 SDK
OpenAI Agents, Claude Agent, Pydantic AI, ADK, Mastra
| SDK / 프레임워크 | 언어 | 프로토콜 | 문서 |
| --- | --- | --- | --- |
| OpenAI Agents SDK | Python, TypeScript | OpenAI Responses | https://docs.gatellm.io/en/sdk/agent-sdks |
| Claude Agent SDK | Python, TypeScript | Anthropic | https://docs.gatellm.io/en/quickstart/anthropic-interop |
| Pydantic AI | Python | OpenAI-compatible | https://docs.gatellm.io/en/sdk/agent-sdks |
| Google ADK | Python | OpenAI-compatible (LiteLLM) | https://docs.gatellm.io/en/sdk/agent-sdks |
| Mastra | TypeScript | OpenAI-compatible | https://docs.gatellm.io/en/sdk/agent-sdks |
| Microsoft Agent Framework | .NET, Python | OpenAI-compatible | https://docs.gatellm.io/en/sdk/agent-sdks |
| MCP SDK | Python, TypeScript | MCP | https://docs.gatellm.io/en/reference/mcp-config |

### 실시간 및 오디오
Realtime WebSocket 음성 + openai_audio ASR / TTS
| SDK / 프레임워크 | 언어 | 프로토콜 | 문서 |
| --- | --- | --- | --- |
| Realtime WebSocket | Any WS client | OpenAI Realtime | https://docs.gatellm.io/en/sdk/realtime-and-audio |
| openai_audio (ASR / TTS) | Python, Node.js | OpenAI audio | https://docs.gatellm.io/en/sdk/realtime-and-audio |

### 로컬 / 자체 호스팅
Ollama, vLLM, llama.cpp를 업스트림으로 — 기존 클라이언트 SDK 유지
| SDK / 프레임워크 | 언어 | 프로토콜 | 문서 |
| --- | --- | --- | --- |
| Ollama | REST | OpenAI-compatible (upstream) | https://docs.gatellm.io/en/sdk/local-inference |
| vLLM | REST | OpenAI-compatible (upstream) | https://docs.gatellm.io/en/sdk/local-inference |
| llama.cpp server | REST | OpenAI-compatible (upstream) | https://docs.gatellm.io/en/sdk/local-inference |
| SGLang | REST | OpenAI-compatible (upstream) | https://docs.gatellm.io/en/sdk/local-inference |
| Text Generation Inference (TGI) | REST | OpenAI-compatible (upstream) | https://docs.gatellm.io/en/sdk/local-inference |
| LM Studio | REST | OpenAI-compatible (upstream) | https://docs.gatellm.io/en/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가 더 낮은 하한(예: ≥16)을 가진 max_output_tokens로 바뀔 수 있습니다 — 너무 작으면 400이 발생합니다.

### 사고(thinking) 블록은 게이트웨이가 감쌉니다
Claude / Gemini의 사고 콘텐츠와 서명은 그대로 전달되거나 제거됩니다 — content 배열에서 type == "text"인 요소를 취하고, content[0]이 텍스트라고 가정하지 마세요.

### OpenAI Agents SDK는 기본적으로 /v1/responses를 사용합니다
Chat Completions가 아니라 Responses API를 호출합니다. 업스트림이 openai(Chat)라면 OpenAIChatCompletionsModel로 명시적으로 전환하고, openai_response라면 문자열 모델 이름이 그대로 동작합니다.

### LlamaIndex는 모델 이름을 허용 목록으로 검증합니다
OpenAI 클래스는 인식하는 계열만 허용하고 사용자 정의 게이트웨이 이름을 거부합니다 — OpenAILike(Python)를 사용하거나 모델 정보를 명시적으로 선언하세요.

### CrewAI는 내부적으로 LiteLLM으로 구동됩니다
base_url은 프레임워크 파라미터가 아니라 OPENAI_API_BASE 환경 변수이며, 모델에는 openai/ 접두사가 필요합니다.

### AutoGen은 명시적인 model_info를 요구합니다
알 수 없는 모델 이름은 기본 목록에서 오류가 납니다 — model_info를 명시적으로 선언해 검사를 우회하세요.

### Google GenAI SDK는 루트를 가리킵니다
base_url은 http_options.base_url로 전달하며(/v1 없음), 키는 x-goog-api-key 헤더에 들어갑니다.

## FAQ
### GateLLM은 LangChain / LlamaIndex / CrewAI와 동작하나요?
예 — 각 프레임워크의 기반 채팅 모델을 게이트웨이의 OpenAI 호환 엔드포인트로 지정하세요. 각각 base_url을 바꾸는 진입점이 있습니다: LangChain은 ChatOpenAI(base_url=…), LlamaIndex는 OpenAILike, CrewAI는 OPENAI_API_BASE 환경 변수를 설정합니다(내부적으로 LiteLLM).
### Claude Agent SDK나 Claude Code를 GateLLM을 통해 사용할 수 있나요?
예. 이들은 ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN 환경 변수를 읽습니다 — 게이트웨이 루트를 가리키고 게이트웨이 액세스 키를 사용하세요. 게이트웨이 모델 이름을 에이전트가 요청하는 ID와 정확히 같게 지정하거나 ANTHROPIC_MODEL로 맞추세요.
### OpenAI Agents SDK는 어떻게 연결하나요?
OpenAI 클라이언트를 게이트웨이로 지정하고 모델을 설정하세요. 기본값이 /v1/responses라는 점에 유의하세요 — 업스트림이 Chat 프로토콜 모델이라면 OpenAIChatCompletionsModel로 명시적으로 전환하세요. 트레이스가 게이트웨이에 도달하지 않도록 추적을 비활성화하세요(set_tracing_disabled).
### GateLLM이 Ollama / vLLM / llama.cpp를 앞단에 둘 수 있나요?
예 — OpenAI 호환 업스트림으로 구성하고 기존 클라이언트 SDK를 유지하세요. 게이트웨이가 자체 호스팅 모델 위에 라우팅, 폴백, 거버넌스를 더합니다.
### base_url에 /v1이 포함되나요?
SDK에 따라 다릅니다: OpenAI SDK는 /v1을 사용하고, Anthropic SDK는 루트를 사용하며(내부에서 /v1/messages를 붙임), Vercel AI SDK의 createAnthropic은 /v1을 사용합니다(내부에서 /messages를 붙임). 문서에 SDK별 정확한 값이 있습니다.
### 게이트웨이 액세스 키와 업스트림 키의 차이는 무엇인가요?
게이트웨이 액세스 키는 클라이언트가 제시하는 것으로, SDK가 사용하는 헤더(Authorization, x-api-key, x-goog-api-key)에 들어갑니다. 업스트림 벤더 키는 게이트웨이에 남으며 클라이언트에 노출되지 않습니다.

## 관련 페이지
- [홈](https://www.gatellm.io/ko/index.md)
- [요금](https://www.gatellm.io/ko/pricing.md)
- [비용 계산기](https://www.gatellm.io/ko/calculator.md)
- [소개](https://www.gatellm.io/ko/about.md)
- [데모 예약](https://www.gatellm.io/ko/demo.md)
- [FAQ](https://www.gatellm.io/ko/faq.md)
- [AI 게이트웨이 비교](https://www.gatellm.io/ko/compare.md)
- [LiteLLM 비교](https://www.gatellm.io/ko/compare/litellm.md)
- [OpenRouter 비교](https://www.gatellm.io/ko/compare/openrouter.md)
- [Alibaba Cloud AI Gateway 비교](https://www.gatellm.io/ko/compare/alibaba-cloud.md)
- [Azure API Management 비교](https://www.gatellm.io/ko/compare/azure-apim.md)
- [Apigee 비교](https://www.gatellm.io/ko/compare/apigee.md)
- [Cloudflare AI Gateway 비교](https://www.gatellm.io/ko/compare/cloudflare.md)
- [Kong AI Gateway 비교](https://www.gatellm.io/ko/compare/kong.md)
- [Portkey 비교](https://www.gatellm.io/ko/compare/portkey.md)
- [LiteLLM vs Kong AI Gateway](https://www.gatellm.io/ko/compare/litellm-vs-kong.md)
- [LiteLLM vs OpenRouter](https://www.gatellm.io/ko/compare/litellm-vs-openrouter.md)
- [LiteLLM vs Portkey](https://www.gatellm.io/ko/compare/litellm-vs-portkey.md)
- [사용 사례](https://www.gatellm.io/ko/use-cases.md)
- [LLM 비용 절감](https://www.gatellm.io/ko/use-cases/reduce-cost.md)
- [고가용성](https://www.gatellm.io/ko/use-cases/high-availability.md)
- [멀티테넌트 격리](https://www.gatellm.io/ko/use-cases/multi-tenant.md)
- [컴플라이언스 및 감사](https://www.gatellm.io/ko/use-cases/compliance-audit.md)
- [증상별 트러블슈팅](https://www.gatellm.io/ko/use-cases/troubleshooting.md)
- [다중 벤더 혼합 모델 스택](https://www.gatellm.io/ko/use-cases/mixed-model-stack.md)
- [Office 내 AI 셀프 호스팅](https://www.gatellm.io/ko/use-cases/self-hosted-office-ai.md)
- [Token 사용량 가시성 및 귀속](https://www.gatellm.io/ko/use-cases/token-ops.md)
- [Token FinOps: AI 비용 배분 및 통제](https://www.gatellm.io/ko/use-cases/token-finops.md)
- [MCP 도구 거버넌스](https://www.gatellm.io/ko/use-cases/mcp-tool-governance.md)
- [모든 모델에 웹 검색 추가](https://www.gatellm.io/ko/use-cases/web-search-grounding.md)
- [다중 키 로테이션 및 대기](https://www.gatellm.io/ko/use-cases/multi-key-pooling.md)
- [연결 클라이언트 접근 제어](https://www.gatellm.io/ko/use-cases/client-admission-control.md)
- [모델 사용 정책 강제](https://www.gatellm.io/ko/use-cases/enforce-model-policy.md)
- [클라이언트에 모델 선택 비노출](https://www.gatellm.io/ko/use-cases/automatic-model-tiering.md)
- [하나의 프로토콜, 어떤 모델이든](https://www.gatellm.io/ko/use-cases/one-protocol-any-model.md)
- [Office / Microsoft 365 추가 기능](https://www.gatellm.io/ko/office-addin.md)
- [용어집](https://www.gatellm.io/ko/glossary.md)
- [모델 카탈로그](https://www.gatellm.io/ko/models.md)
- [AI 코딩 에이전트 및 하네스](https://www.gatellm.io/ko/coding-agents.md)
- [보안 및 컴플라이언스](https://www.gatellm.io/ko/security.md)