Vercel AI Gateway로 여러 모델 한 번에 다루기 — API 키 하나로 폴백까지

프로젝트에서 모델을 여러 개 섞어 쓰다 보니 관리가 슬슬 귀찮아졌다. Claude, GPT, Gemini를 상황에 따라 갈아 끼우는데 그때마다 프로바이더 SDK를 따로 깔고, API 키를 각각 발급받아 환경변수에 넣고, 청구서도 세 군데서 날아왔다.

Vercel AI SDK의 provider registry로 모델 교체 자체는 정리했었는데, 여전히 키 관리와 폴백은 내 몫이었다. Anthropic이 잠깐 500을 뱉으면 요청이 그냥 실패했다. AI Gateway를 붙이고 나서 이 두 개가 한 번에 해결됐다.

키 하나로 여러 프로바이더

AI Gateway는 Vercel이 앞단에 두는 라우팅 레이어다. 프로바이더 SDK를 각각 설치할 필요 없이, provider/model 형식의 문자열만 넘기면 된다.

import { streamText } from 'ai';

const result = streamText({
  // 프로바이더 SDK import 없이 문자열로 지정
  model: 'anthropic/claude-sonnet-4.5',
  prompt: '이 커밋 메시지를 한 줄로 요약해줘',
});

Vercel에 배포하면 OIDC 토큰으로 인증이 자동으로 붙어서 키를 따로 안 넣어도 된다. 로컬에서는 AI_GATEWAY_API_KEY 하나만 .env에 넣으면 끝이다. 프로바이더별 키를 각각 관리하던 걸 생각하면 훨씬 깔끔하다.

죽으면 다음 모델로 넘기기

가장 마음에 든 건 폴백이다. 배열로 모델을 나열하면 앞에서부터 시도하다가 실패하면 다음으로 자동으로 넘어간다.

import { streamText } from 'ai';
import { gateway } from '@ai-sdk/gateway';

const result = streamText({
  model: gateway([
    'anthropic/claude-sonnet-4.5',
    'openai/gpt-5',
    'google/gemini-2.5-flash',
  ]),
  prompt: '...',
});

Anthropic이 잠깐 흔들려도 사용자는 아무 일 없이 GPT 응답을 받는다. 예전엔 이걸 try/catch로 직접 짰는데, 재시도 로직에서 스트리밍이 꼬여서 골치 아팠다. 그걸 게이트웨이가 알아서 처리해준다.

사용량이 한눈에

Vercel 대시보드의 AI Gateway 탭에 들어가면 모델별 요청 수, 토큰, 비용이 다 모여서 나온다. 어떤 기능이 토큰을 잡아먹는지 프로바이더 세 군데를 뒤질 필요 없이 여기서 바로 보인다. 요청마다 providerOptions로 예산이나 라우팅 우선순위를 조정할 수도 있다.

정리하면, 모델을 두 개 이상 쓰는 프로젝트라면 게이트웨이를 거치는 게 거의 무조건 이득이다. 키 관리가 하나로 줄고, 폴백이 공짜로 생기고, 비용 추적까지 딸려온다. 프로바이더 락인이 걱정된다면 문자열만 바꾸면 되니 갈아타기도 쉽다. 나는 붙이는 데 10분 걸렸고, 그날 밤 Anthropic 장애 때 폴백 덕을 바로 봤다.