본문으로 건너뛰기

AI 게이트웨이: LiteLLM, OpenRouter, Portkey, Vercel

중급

여러분의 제품이 두 개 이상의 모델과 대화하기 시작하면 직접-SDK 접근이 깨집니다. 각 프로바이더는 자체 키, 자체 rate limit, 자체 다운타임 일정, 자체 청구서를 갖습니다. AI 게이트웨이는 여러분의 코드와 모든 모델 — Claude, GPT, Gemini, Llama, Kimi, DeepSeek, 로컬 Ollama — 사이에 앉아 "N개의 취약한 통합"을 "여러분이 통제하는 하나의 엔드포인트"로 바꾸는 작은 인프라 조각입니다. 이 페이지는 2026년 프로덕션에 실제로 배포되는 네 개의 게이트웨이 — LiteLLM, OpenRouter, Portkey, Vercel AI Gateway — 를 비교하고, 킬러 워크플로를 보여줍니다: Claude Code를 자체 게이트웨이에 가리켜서 단일 프록시가 팀 전체의 라우팅, 예산, 로깅, fallback을 처리하게 하기.

What you'll learn
  • AI 게이트웨이가 무엇이고 다섯 가지 문제를 해결하는지 이해(여러 프로바이더, 하나의 API; fallback; 가상 키; 지출 상한; 관측성)
  • LiteLLM, OpenRouter, Portkey, Vercel AI Gateway를 지연 시간, 가격, 자체 호스팅 가능성, 각자의 강점에서 비교
  • ANTHROPIC_BASE_URL과 가상 키로 Claude Code를 자체 LiteLLM 프록시를 통해 배선하여 팀이 공유 한도와 로그를 얻게 하기
  • OpenRouter fallback을 구성하여 Claude 다운타임이 사용자에게 5xx를 보이는 대신 조용히 GPT나 Gemini로 승격되게 하기
  • 2026년 3월 LiteLLM 공급망 사건을 이해하고 프로덕션에서 버전을 안전하게 고정하는 법

문제: 프로바이더당 하나의 직접 SDK는 확장되지 않는다​

첫 Claude 통합은 두 줄 변경입니다: pip install anthropic, ANTHROPIC_API_KEY 설정, 끝. 두 번째 — Anthropic이 스로틀 걸 때 GPT-5.4로 fallback하고 싶다고 해봅시다 — 는 추상화가 깨지는 지점입니다. 이제 서로 다른 요청 형태의 두 SDK, 두 대시보드, 두 청구서, API 키 두 벌의 로테이션 주기, 두 세트의 재시도 로직이 있습니다. Gemini용 세 번째와 로컬 Ollama용 네 번째를 추가하면 모든 제품 결정("이 팀을 월 $500로 상한", "모든 프롬프트를 리뷰용으로 로그", "고객이 자체 키를 가져오게 하기")이 하나 대신 N개의 구현이 됩니다.

AI 게이트웨이는 그 배관을 한 곳에 집중시킵니다. 구체적으로 프로덕션 게이트웨이는 여러분에게 제공합니다:

  • 모든 프로바이더에 대한 하나의 요청 형태. 대부분 게이트웨이는 OpenAI Chat Completions API(또는 Anthropic Messages, 또는 둘 다)를 말하며 내부에서 실제 프로바이더로 번역합니다.
  • Fallback과 라우팅. 먼저 Claude를 시도; 429나 5xx에서 호출자 모르게 GPT나 Gemini로 재시도. 지연 상한과 컨텐츠 조정 거부에도 마찬가지.
  • 가상 키. 사용자별 또는 서비스별 키를 발행하여 모델 부분집합, 자체 예산, 자체 rate limit에 매핑 — 그러면 악성 스크립트가 전체 계정을 고갈시킬 수 없습니다.
  • 지출 상한과 로깅. 모든 요청이 태그되고, 가격 매겨지고, 저장됩니다. Anthropic이나 OpenAI를 건드리지 않고 키를 취소할 수 있고, 컴플라이언스에 무엇이 어디로 보내졌는지 증명할 수 있습니다.
  • 캐싱. 프롬프트 캐싱(정확 매치)과 semantic 캐싱(근사 매치)이 반복 트래픽을 무료 히트로 바꿉니다.

모든 팀이 다섯 개 모두 필요하지는 않습니다. 하지만 로드맵에 둘이 올라오는 순간, 게이트웨이를 운영하는 것이 프로바이더별로 재발명하는 것보다 저렴합니다.

프로덕션에 배포되는 네 게이트웨이​

하나의 "승자"는 없습니다 — 네 리더는 설계 공간의 서로 다른 구석(자체 호스팅 vs. 호스팅, 오픈 소스 vs. 독점, 미니멀리스트 vs. 컨트롤 패널)을 차지합니다.

게이트웨이배포가격 모델최고 강점부적합
LiteLLM자체 호스팅(Docker) 또는 SDK무료(OSS); SSO/감사용 엔터프라이즈 티어가상 키·예산이 있는 팀 프록시, 토큰별 마크업 없음, 하나의 설정으로 100+ 프로바이더 작동Postgres + Redis를 운영할 DevOps가 없는 팀
OpenRouter호스팅 전용프로바이더 가격 + 약 5.5% 크레딧 구매 수수료, 요청별 마크업 없음하나의 키로 300+ 모델에 zero-ops 접근; 사용자가 모델을 고르는 제품에 이상적자체 호스팅이나 데이터 거주가 필요한 컴플라이언스 조직
PortkeyOSS 게이트웨이(npx) 또는 호스팅 클라우드OSS 무료; 클라우드는 사용량 티어밀리초 미만 게이트웨이 지연, semantic 캐싱, 가드레일, 카나리 테스트 — "컨트롤 패널" 각도가장 단순한 키 애그리게이터만 원하는 팀
Vercel AI Gateway호스팅 전용프로바이더 가격, 토큰 마크업 없음; Vercel 요금제로 무료AI SDK v5/v6 + Anthropic Messages + OpenAI Responses API 통합을 원하는 이미 Vercel에 있는 개발자비-Vercel 인프라 또는 air-gapped 배포

먼저 고를 중요한 축: 자체 호스팅 vs. 호스팅. 데이터가 VPC를 떠날 수 없다면(규제 산업, EU 거주, 엔터프라이즈 프라이버시 리뷰) 자체 호스팅 가능한 게이트웨이가 필요합니다 — LiteLLM 또는 Portkey OSS. 누군가에게 운영을 맡기고 싶다면 OpenRouter나 Vercel AI Gateway가 원-클릭 사안입니다.

두 번째 축: 실제로 얼마나 많은 컨트롤 플레인이 필요한가. Kimi K3, Claude, Grok을 세 번의 가입 없이 나란히 시도해 보고 싶은 1인 제품이라면 OpenRouter가 전부입니다. 재무가 팀별 월별 지출을, 보안이 로테이션 있는 가상 키를, 플랫폼이 Grafana 메트릭을 원하는 20인 조직이라면 LiteLLM이나 Portkey 위에 짓게 됩니다.

킬러 워크플로: Claude Code를 자체 LiteLLM 프록시에 가리키기​

Claude Code에 대한 가장 잘 알려지지 않은 비밀은 ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN을 존중한다는 것입니다. 이것을 게이트웨이로 설정하면 Claude Code는 api.anthropic.com에 직접 대화하기를 멈춥니다 — 여러분의 프록시에 대화하고, 프록시가 여러분이 통제하는 인증으로 Anthropic(또는 어디든)에 전달합니다. 팀에게 이것은 세 가지를 한꺼번에 바꿉니다:

  • 개발자당 하나의 공유 가상 키. 프록시 UI에서 키를 발행하고 취소합니다. .env 파일에 공유 루트 자격 증명 없음.
  • 개발자별 예산과 로그. 프록시가 모든 요청을 태그하므로 "어제 $300을 누가 썼는지"는 인시던트가 아니라 데이터베이스 쿼리입니다.
  • 모델 별칭. claude-sonnet-4-6을 프록시에 고정할 수 있으므로 모델 deprecation이 저장소 전체 grep이 아니라 한 줄짜리 설정 변경입니다.

세 단계로 최소 프록시를 시작:

Guided walkthrough1 of 3
  1. 새 venv에서 또는 uv를 통해: uv tool install 'litellm[proxy]'. 이것은 클라이언트 SDK와 함께 게이트웨이 서버(FastAPI + admin UI)를 가져옵니다.

이것을 작동시키는 설정 파일:

config.yaml — Claude Sonnet/Opus/Haiku behind LiteLLM

model_list:
- model_name: claude-opus-4-7
  litellm_params:
    model: anthropic/claude-opus-4-7
    api_key: os.environ/ANTHROPIC_API_KEY
- model_name: claude-sonnet-4-6
  litellm_params:
    model: anthropic/claude-sonnet-4-6
    api_key: os.environ/ANTHROPIC_API_KEY
- model_name: claude-haiku-4-5-20251001
  litellm_params:
    model: anthropic/claude-haiku-4-5-20251001
    api_key: os.environ/ANTHROPIC_API_KEY

litellm_settings:
master_key: os.environ/LITELLM_MASTER_KEY
# Optional: enable exact-match prompt caching
cache: true
cache_params:
  type: redis
  host: os.environ/REDIS_HOST

그런 다음 어떤 개발자의 셸에서든:

Point Claude Code at the proxy (per-developer .env)

export ANTHROPIC_BASE_URL="https://llm.internal.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-team-alice-9f4c..."   # a VIRTUAL key issued by the proxy

# now every Claude Code call goes through YOUR gateway
claude --model claude-sonnet-4-6

명백하지 않은 승리는 가상 키입니다. 마스터 키는 관리자 전용이며 절대 노트북에 배포되지 않습니다. 각 개발자는 허용된 모델만에 매핑되고 자체 월별 예산을 가지며 기저의 Anthropic 키를 로테이션하지 않고 몇 초 안에 취소할 수 있는 가상 키를 받습니다. 노트북을 잃어버리면 팀 전체의 접근이 아니라 Postgres에서 한 행만 죽입니다.

주의: 같은 env 변수가 Anthropic의 Bedrock과 Vertex 통합에서도 작동하지만 실험적 베타 기능에 엣지 케이스가 있습니다. Bedrock 배포에서 LiteLLM 문서는 헤더 호환성 이슈를 피하기 위해 ~/.claude/settings.json에 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정하기를 권장합니다.

킬러 워크플로 #2: OpenRouter로 조용한 fallback​

아무것도 호스팅하고 싶지 않다면 OpenRouter의 fallback 배열이 "Claude가 429일 때 다른 모델을 조용히 재시도"에 가장 짧은 경로입니다. 순서 있는 목록을 보내면 OpenRouter가 위에서 아래로 걷고 응답한 첫 모델을 반환합니다.

Claude → GPT → Gemini fallback in one request (OpenRouter)

import openai

client = openai.OpenAI(
  api_key="YOUR_OPENROUTER_KEY",
  base_url="https://openrouter.ai/api/v1",
)

response = client.chat.completions.create(
  model="anthropic/claude-sonnet-4.5",
  extra_body={
      # Ordered fallback. If the first model 429s, is down, or is
      # rejected by moderation, OpenRouter tries the next one.
      "models": [
          "anthropic/claude-sonnet-4.5",
          "openai/gpt-5.4",
          "google/gemini-2.5-pro",
      ],
  },
  messages=[{"role": "user", "content": "Explain B-trees in one paragraph."}],
)

# 'model' in the response tells you which one actually answered.
print(response.model, "->", response.choices[0].message.content)

첫 시도에서 사람들이 놓치는 세 가지:

  • 청구는 여러분이 요청한 것이 아니라 응답한 모델을 따릅니다. Claude가 실패하고 GPT-5.4가 응답하면 그 요청에 대해 OpenRouter의 GPT-5.4 요율을 지불합니다.
  • fallback은 5xx 이상에서 트리거됩니다. Rate limiting, 프로바이더 다운타임, 컨텍스트 길이 검증 에러, 컨텐츠 조정 거부 모두 다음 모델로 승격됩니다. 그 마지막이 가장 날카로운 엣지입니다 — 한 프로바이더의 "조정" 거부가 더 허용적인 것으로 조용히 라우팅될 수 있고, 그것이 여러분이 원하는 것일 수도 아닐 수도 있습니다. ACL과 같은 주의로 fallback 목록을 리뷰하세요.
  • models를 fallbacks와 혼용할 수 없습니다. Anthropic 형식 Messages 엔드포인트는 다른 fallbacks 배열을 사용합니다. 같은 요청에 두 키를 보내면 400을 반환합니다. 클라이언트가 말하는 형식을 골라 고수하세요.

2026년 3월 LiteLLM 공급망 사건: 실제로 무엇을 해야 하나​

2026년 3월 24일 10:39 UTC에 LiteLLM의 두 악성 PyPI 릴리스 — v1.82.7과 v1.82.8 — 가 공격자에 의해 게시되었습니다. LiteLLM CI/CD 파이프라인에서 실행되는 보안 스캐너 Trivy의 사전 침해를 통해 관리자의 PyPI 자격 증명을 훔친 후였습니다. PyPI는 13:38 UTC에 패키지를 격리했습니다(약 3시간 후). 노출 창 동안 수만 건의 다운로드가 발생했습니다. 페이로드는 지속성 메커니즘(모든 Python 호출에서 실행되고 자격 증명을 수확하며 systemd 백도어를 설치하는 litellm_init.pth 파일)이 있는 infostealer였습니다. 귀속은 TeamPCP로 추적되는 그룹으로, Trivy와 Checkmarx KICS도 침해했습니다.

어떤 환경에서든 LiteLLM을 실행한다면 이것을 한 번 적용하고 플랫폼 플레이북에 유지하세요:

Guided walkthrough1 of 5
  1. v1.82.6과 이전은 깨끗합니다. v1.83.0과 이후(LiteLLM의 재구축된 CI/CD v2 파이프라인을 통해 게시)는 깨끗합니다. 그 사이의 어떤 것도 제거해야 하고 환경은 오염된 것으로 간주해야 합니다. 공식 Docker 이미지(ghcr.io/berriai/litellm)는 침해되지 않았습니다 — 사건은 PyPI 전용이었습니다.

더 넓은 교훈은 "LiteLLM을 쓰지 말라"가 아니라 "보안 스캐너를 포함해 AI 스택의 모든 의존성이 전달 벡터일 수 있다고 가정하라"입니다. 버전을 고정하고, 이미지에 서명하고, 게이트웨이를 모델 프로바이더에만 도달하는 네트워크 세그먼트에 두세요.

상황에 맞는 게이트웨이 선택​

Guided walkthrough1 of 5
  1. 작은 팀에 프로바이더 하나 또는 둘 → 게이트웨이 건너뛰기; 직접 SDK로 충분. 3개 이상 프로바이더 OR '누가 키를 갖고 있나'가 중요한 팀 → 게이트웨이. DevOps와 프라이버시 요구 사항이 있다면 LiteLLM 또는 Portkey OSS를 자체 호스팅. 누가 운영하기를 원한다면 OpenRouter(호스팅 전용) 또는 Vercel AI Gateway(이미 그곳에 배포한다면 훌륭).

프로덕션에 배포되는 흔한 조합:

  • 1인 개발자 / 프로토타입: OpenRouter 직접. 하나의 키, 300+ 모델, 끝.
  • 작은 팀, Claude 우선: LiteLLM 프록시에 Anthropic + fallback 프로바이더 하나, 엔지니어별 가상 키, Redis 프롬프트 캐싱.
  • Vercel 네이티브 제품: AI SDK와 함께 Vercel AI Gateway; 이색 모델용 provider-options fallback으로 OpenRouter 추가.
  • 규제 / EU: VPC 안에 자체 호스팅 LiteLLM 또는 Portkey OSS, 앞에 Presidio PII 마스킹(리덕션 패턴은 Claude + Local Models 참조).
  • 반복 트래픽 많은 AI 제품: Portkey(semantic 캐싱은 채팅 스타일 워크로드에서 흔히 30-50% 비용 감소를 이끈다고 Portkey 자체 사례 연구가 주장 — 헤드라인 숫자를 믿기 전에 여러분 트래픽에서 검증).

게이트웨이가 해결하지 않는 것​

게이트웨이는 미들웨어입니다 — 여러분이 모델에 어떻게 도달하는지 바꾸지, 어떤 모델이 맞는지는 바꾸지 않습니다. 두 가지는 여전히 실제 작업이 필요합니다:

  • 프롬프트 이식성. Claude, GPT, Gemini는 같은 프롬프트에 다르게 답하며 시스템 프롬프트 관습이 다양합니다. 게이트웨이는 fallback 프로바이더를 위해 여러분의 프롬프트를 다시 쓰지 않습니다 — 그것이 Porting prompts across models와 Cross-AI translation의 역할입니다.
  • 평가. 게이트웨이는 같은 요청에서 두 모델의 A/B를 쉽게 만듭니다. 어느 것이 실제로 여러분 작업에 더 나았는지는 말할 수 없습니다. 기본을 바꾸기 전에 실제 평가(Evals 참조)를 실행하세요.

흔한 실수는 게이트웨이를 설치하고 "멀티 모델"이 끝났다고 여기는 것입니다. 게이트웨이는 전송 레이어입니다; 이식성과 평가는 제품 레이어입니다.

Check yourself

0/5
  1. 두 개 이상 쓰기 시작하면 앱과 모델 프로바이더 사이에 AI 게이트웨이를 두는 주된 이유는?
  2. ANTHROPIC_BASE_URL로 Claude Code를 LiteLLM 프록시에 가리킵니다. ANTHROPIC_AUTH_TOKEN은 무엇이어야 하나?
  3. OpenRouter의 fallback 배열은 첫 번째가 실패할 때 다음 모델로 승격됩니다. 다음 중 트리거되는 것은?
  4. 프로덕션에 LiteLLM을 설치해야 합니다. 2026년 3월 사건 이후 어떤 버전이 안전한가?
  5. Vercel에 있는 1인 개발자로 오후에 Claude, GPT, Gemini를 시도하고 싶습니다. 가장 잘 맞는 것은?
AI gateways at a glance
Enter 또는 스페이스 키를 눌러 카드를 뒤집습니다. 좌우 화살표 키로 카드를 이동할 수 있습니다.용어가 표시되었습니다.
1 / 9
Key takeaways
  • AI 게이트웨이는 앱과 모든 모델 사이의 잃어버린 라우터 — 가상 키, 예산, fallback, 로깅, 캐싱을 프로바이더당 N개가 아니라 단일 구현으로 만들기 위해 존재
  • 먼저 두 축으로 선택: 자체 호스팅 vs. 호스팅(LiteLLM/Portkey OSS vs. OpenRouter/Vercel), 미니멀리스트 vs. 컨트롤 패널(OpenRouter/Vercel vs. LiteLLM/Portkey)
  • Claude Code 킬러 워크플로: ANTHROPIC_BASE_URL을 자체 LiteLLM 프록시에 가리키고 개발자별 가상 키 발행 — 팀이 루트 Anthropic 키를 건드리지 않고 공유 한도, 로그, 원-클릭 취소를 얻음
  • OpenRouter의 models[] 배열은 조용한 Claude → GPT → Gemini fallback에 가장 짧은 경로지만, 조정 거부도 fallback 트리거임 — ACL처럼 목록을 리뷰
  • 2026년 3월 LiteLLM 공급망 공격 이후 v1.82.6이나 이전, 또는 v1.83.0+로 고정; pip보다 서명된 Docker 이미지 선호; 프록시에 egress 허용 목록
  • 게이트웨이는 전송이지 제품이 아님 — 프롬프트 이식성과 평가는 이제 얼마나 많은 모델에 도달할 수 있든 실제 작업이 필요

Sources & further reading​

관련 페이지: Claude + Local Models: Hybrid Patterns · Porting prompts across models · Cross-AI translation · Evals · What AI costs across providers