헤드라인: Vercel AI Gateway는 단순한 "provider/model" 문자열을 통해 AI SDK 호출을 어떤 모델 제공자(provider)로든 라우팅하는 단일 엔드포인트입니다. 저는 @ai-sdk/anthropic, @ai-sdk/openai 및 세 개의 별도 제공자 API 키를 제거했으며, 이제 SDK 패키지를 교체하는 대신 문자열 하나를 편집함으로써 모델을 전환합니다.

핵심 요약 (Key takeaways)

• Vercel AI Gateway는 앱과 여러 LLM 제공자 사이에 위치하는 통합 API로, 2025년 8월부터 GA(General Availability)되었으며, 하나의 자격 증명(credential)과 하나의 코드 경로로 모든 모델에 접근할 수 있게 합니다.
• AI SDK를 사용하면 @ai-sdk/anthropic과 같은 특정 제공자 전용 패키지를 임포트(import)하는 대신, "provider/model" 문자열(예: 'anthropic/claude-sonnet-5', 'openai/gpt-5')을 통해 모델을 선택합니다.
• 모델 폴백 (Model fallbacks) 기능을 통해 모델의 순서 목록을 선언할 수 있습니다. 기본 모델이 속도 제한(rate-limited)에 걸리거나 오류가 발생하면, 게이트웨이는 코드의 분기 처리 없이 동일한 요청 내에서 다음 모델로 재시도합니다.
• 게이트웨이는 관측 가능성 (observability) (요청당 비용, 지연 시간(latency), 토큰 수)을 추가하며 **데이터 보존 제로 (zero data retention)**를 지원하므로, 제공자를 전환하더라도 로깅(logging) 설정을 다시 할 필요가 없습니다.
• 게이트웨이는 제공자별 SDK 연결 및 키 관리를 대체하는 것이지, AI SDK 자체를 대체하는 것이 아닙니다. 여전히 generateText, streamText 및 동일한 도구 호출(tool-calling) API를 사용합니다.

Vercel AI Gateway란 무엇이며 어떤 문제를 해결하는가?

Vercel AI Gateway는 단일 OpenAI 호환 엔드포인트를 노출하고 모델 문자열이 지정하는 제공자에게 요청을 전달하는 호스팅된 프록시(proxy)입니다. Anthropic 키, OpenAI 키, Google 키를 각각의 SDK 및 속도 제한 동작과 함께 보유하는 대신, 하나의 게이트웨이 자격 증명을 보유하고 인라인(inline)으로 모델을 지정하면 됩니다. 이 서비스가 해결하는 문제는 코드 수준에서의 제공자 종속성(provider lock-in)입니다. 호출이 anthropic('claude-sonnet-5')인 경우, 다른 제공자를 시도하려면 새로운 임포트, 새로운 클라이언트, 그리고 종종 새로운 로깅 형식이 필요합니다. 하지만 호출이 'anthropic/claude-sonnet-5'라는 문자열인 경우, 'openai/gpt-5'를 시도하는 것은 단 한 줄의 차이(diff)일 뿐입니다.

제공자 SDK에서 게이트웨이(Gateway)로 어떻게 전환하나요?

제공자(provider) 임포트를 제거하고 AI SDK의 model 필드에 "provider/model" 문자열을 전달하세요. AI SDK는 기본적으로 모든 일반 문자열을 게이트웨이를 통해 해결(resolve)합니다.

// 이전: 제공자 SDK + 제공자 전용 키
import { anthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';
...

// 이후: 게이트웨이 문자열 라우팅, 하나의 AI_GATEWAY_API_KEY 사용
import { generateText } from 'ai';

...

streamText, generateObject, 도구 호출(tool calling) 등 하위의 모든 기능은 동일하게 유지됩니다. 모델은 코드가 아닌 설정(configuration)의 영역이 됩니다.

모델 폴백(model fallbacks)은 언제 사용해야 하나요?

선호하는 제공자가 속도 제한(rate-limited)에 걸리거나 다운되었을 때도 요청이 반드시 성공해야 하는 경우에 폴백(fallback)을 사용하세요. 게이트웨이는 기본 모델을 시도하며, 제공자 오류가 발생하면 동일한 호출 내에서 투명하게(transparently) 다음 모델로 재시도합니다.

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

...

저는 결정론적 동작(deterministic behavior)이 필요한 백그라운드 작업에서는 폴백을 사용하지 않습니다. 야간 배치 작업은 명확하게 실패하고 동일한 모델로 재시도해야 하며, 제가 검증하지 않은 다른 모델이 조용히 답변하게 해서는 안 됩니다. 폴백은 일관성(consistency)을 가용성(availability)과 맞바꾸는 것입니다. 가용성이 더 중요한 곳에만 이 트레이드오프를 사용하세요.

게이트웨이가 대체하는 것은 무엇이며, 무엇이 유지되나요?

비용, 데이터 보존(data retention), 그리고 관찰 가능성(observability)은 어떤가요?

게이트웨이는 요청당 비용(cost), 지연 시간(latency), 토큰 수(token counts)를 한 곳에서 보고하므로, 동일한 프롬프트로 두 모델을 비교할 때 더 이상 두 공급자의 청구 페이지를 연결할 필요가 없습니다. 또한 제로 데이터 보존(zero data retention) 모드를 지원하여 요청 및 응답 본문이 게이트웨이에 저장되지 않습니다. 이는 프롬프트에 고객 데이터가 포함되어 있고 보안 검토를 위해 깨끗한 데이터 흐름 답변이 필요한 경우 중요합니다. 실질적인 이점은 측정입니다. 모델 선택이 문자열이고 메트릭이 통합되면, 실제 비교(동일 프롬프트, 세 가지 모델, 비용 및 지연 시간 확인)는 엔지니어링 프로젝트가 아니라 설정 변경과 대시보드 읽기로 충분합니다.

전면 도입 전에 고려할 점

요청 경로에 추가되는 간접 계층(indirection layer)은 의존성을 하나 더 만듭니다. 게이트웨이가 다운되면 모든 모델 호출이 중단되므로, 여전히 폴백 목록과 합리적인 타임아웃을 유지합니다. 그리고 단순 문자열은 공급자별 기능(도구 형식, 캐시-컨트롤 헤더 등)에 의존할 때까지는 공급자에 구애받지 않지만, 그 순간 다시 공급자 옵션으로 돌아가게 되며 이는 게이트웨이를 통해 전달될 뿐입니다. 둘 다 치명적인 결함은 아니지만, 제가 했던 것처럼 공급자 패키지를 삭제하기 전에 알아둘 가치가 있습니다.

FAQ

질문: Vercel AI Gateway를 사용하면 여전히 AI SDK가 필요한가요?
답변: 네. 게이트웨이는 모델 요청을 라우팅하며, AI SDK는 코드에서 호출하는 부분(generateText, streamText, generateObject)은 여전히 동일합니다. 이는 @ai-sdk/anthropic과 같은 공급자별 패키지를 대체할 뿐, 핵심 ai 패키지는 아닙니다.

질문: 게이트웨이를 통해 모델을 선택하려면 어떻게 해야 하나요?
답변: model 필드에 `

질문: 게이트웨이가 제 프롬프트(prompt)를 저장하나요?
답변: 요청(request) 및 응답(response) 본문을 유지하지 않는 제로 데이터 보유(zero data retention) 모드를 지원합니다. 민감한 데이터를 보내기 전에 귀하의 계정 설정을 확인하십시오.

질문: 2026년에도 프로바이더(provider)별 SDK를 사용해야 할까요?
답변: 이식성(portability)을 위해 게이트웨이 문자열 라우팅(gateway string routing)을 기본으로 사용하십시오. 게이트웨이가 노출하지 않는 프로바이더 전용 기능이 필요한 경우에만 직접적인 프로바이더 SDK를 사용하십시오.

원문은 devya.dev에 처음 게시되었습니다. 또한 eng-ahmed.com에서도 확인하실 수 있습니다. Devya Solutions에서 제작하였습니다.