Vercel AI Gateway Virtual Models 출시: 모델 교체·요금·설정 방법

모델 이름 하나 바꾸려는데 서비스 여러 개를 다시 배포한다면

고객 문의 분류에는 빠르고 저렴한 모델을 쓰고, 복잡한 코드 수정에는 더 강한 모델을 쓰는 서비스를 생각해 보자. 처음에는 각 앱의 환경 변수나 소스 코드에 공급자별 모델 이름을 직접 넣기 쉽다. 그런데 모델을 교체할 때마다 웹 서버, 백그라운드 작업, 코딩 에이전트 설정을 따로 바꾸고 배포해야 한다면 운영 비용이 늘어난다.

2026년 10월 28일 Vercel이 공개한 AI Gateway Virtual Models는 이 지점을 바꾼다. 앱이 실제 모델 이름 대신 vmc/coding-agent처럼 사람이 정한 고정 식별자를 호출하고, 그 이름이 어떤 모델과 설정을 가리키는지는 AI Gateway에서 관리한다. 서비스 코드는 그대로 두고 모델과 우선순위를 바꿀 수 있다는 뜻이다.

가령 문서 검토용 API와 사내 개발 도구가 모두 vmc/contract-review를 사용한다고 하자. 운영자가 가상 모델의 실제 대상을 다른 공급자 모델로 변경하면 새 요청에는 변경된 설정이 적용된다. 공식 문서는 변경 전파에 몇 분이 걸릴 수 있다고 설명하므로 모든 진행 중 요청이 동시에 새 모델로 바뀐다고 이해하면 안 된다.

기존 AI Gateway에도 통합 API와 공급자 장애 시 재시도·대체 경로 기능은 있었다. Virtual Models의 차이는 이 옵션을 호출하는 코드마다 넣지 않고 재사용 가능한 이름에 묶어 둔다는 데 있다. 하나의 설정을 여러 앱과 에이전트에서 공유하고 변경 기록을 운영하는 팀에 특히 실용적이다.

다만 Vercel 계정과 AI Gateway를 거쳐 요청하는 구조는 그대로 필요하다. 가상 모델은 무료 추론 엔진도, 자체 호스팅 모델도 아니다. 이미 모델 선택과 정책을 중앙 설정으로 완전히 관리하는 작은 프로젝트라면 새 추상화가 꼭 필요한 것은 아니다.

근거 [1] [2] [3]

vmc/ 식별자 뒤에는 실제 모델과 운영 정책이 있다

가상 모델을 만들 때 먼저 slug와 실제 모델을 고른다. 예를 들어 coding-agent라는 slug를 만들면 앱에서 부르는 이름은 vmc/coding-agent가 된다. 이 이름 아래에는 기본 모델뿐 아니라 공급자 선택 순서, 대체 모델, 데이터 보존 요구, 속도 등급, 프롬프트 캐싱, 요청 분류 태그를 저장할 수 있다.

요청이 들어오면 AI Gateway는 vmc/ 식별자를 실제 모델 설정으로 해석한 뒤 허용된 공급자에 전달한다. 앱은 같은 식별자를 계속 보내지만 관리자가 모델을 바꾸면 다음 요청부터 새 경로를 사용할 수 있다. 여러 개발자가 각자의 코딩 도구 설정을 고칠 필요가 줄어든다.

공급자 순서와 공급자 제한은 다르다. Provider Order는 우선 시도할 공급자를 정렬하는 기능이어서 목록에 없는 공급자가 후순위로 쓰일 수 있다. 반면 Provider Only는 허용 공급자를 해당 목록으로 제한하며 모두 실패하면 요청도 실패한다. 개인정보 처리나 지역 제한이 중요하다면 두 옵션을 같은 것으로 취급하면 안 된다.

가상 모델에 저장한 설정과 요청이 보낸 설정이 충돌할 때는 항목별 우선순위가 적용된다. 공식 문서에 따르면 가상 모델의 라우팅·대체 경로·서비스 등급 같은 명시적 설정은 요청에서 지정한 값보다 우선한다. Zero Data Retention과 학습 금지 설정도 호출자가 false로 보내 느슨하게 만들 수 없도록 강제할 수 있다.

그렇다고 가상 모델이 조직 전체의 보안 정책을 무시하는 것은 아니다. 팀이 허용하지 않은 모델이나 공급자는 가상 모델에 적어도 차단된다. 이 구조는 중앙에서 예외를 허용하는 도구가 아니라, 팀 정책 아래에 업무별 제한을 더하는 방식에 가깝다.

근거 [1] [3] [4]

대시보드에서 만들고 CLI로 교체하는 실제 순서

처음 시작한다면 Vercel 대시보드의 AI Gateway Virtual Models 페이지를 열어 Create Virtual Model을 누른다. 이름으로 쓸 slug를 입력하고 카탈로그에서 실제 모델을 선택한 뒤 필요한 라우팅과 보안 설정을 저장한다. 공식 문서는 slug를 생성 후 변경할 수 없다고 안내하므로 팀에서 계속 사용할 업무 이름으로 정하는 편이 낫다.

명령줄이 익숙하면 Vercel CLI에서도 생성할 수 있다. 공식 발표의 예시는 coding-agent라는 가상 모델을 Claude Opus 5.5에 연결하고 fast mode와 Zero Data Retention을 설정한다. 아래 명령은 문서에 실린 인터페이스를 설명하기 위한 예시이며, 이번 기사 작성 과정에서 계정에 로그인하거나 유료 API를 호출해 실행한 결과는 아니다.

생성한 뒤 앱의 모델 문자열을 실제 공급자 모델 이름에서 vmc/coding-agent로 바꾼다. TypeScript AI SDK의 generateText나 streamText에 이 식별자를 전달하면 된다. AI Gateway 연결과 인증은 별도로 준비해야 하며, 모델 이름만 바꾼다고 기존 공급자 API 키가 자동으로 AI Gateway 인증으로 전환되지는 않는다.

이후 실제 모델을 바꿀 때는 vercel ai-gateway virtual-models edit 명령을 사용한다. 예를 들어 coding-agent가 가리키는 모델을 다른 공급자로 옮기더라도 앱에는 같은 vmc/coding-agent를 남겨 둘 수 있다. 운영자가 설정을 바꾸는 순간 새 배포 없이 변경이 퍼지지만, 공식 문서대로 몇 분의 전파 지연을 고려해야 한다.

실무에서는 운영용 식별자와 후보용 식별자를 분리하는 게 안전하다. vmc/coding-agent-candidate로 새 모델을 시험하고 실제 업무의 품질·지연·비용을 확인한 뒤 운영용 대상을 교체하면 된다. Vercel도 정식 서비스에 모델을 바꾸기 전에 별도 가상 모델에서 평가를 실행하라고 권한다.

vercel ai-gateway virtual-models create coding-agent \
  --model anthropic/claude-opus-5.5 \
  --config '{"speed":"fast","zeroDataRetention":true}'

# 실제 모델 교체 예시 (문서 기반, 미실행)
vercel ai-gateway virtual-models edit coding-agent --model openai/gpt-6.1-sol

근거 [1] [2] [3]

Claude Code·Codex와 기존 앱에서 사용하는 방법

코딩 에이전트에서도 같은 구조를 쓸 수 있다. 공식 문서는 vercel ai-gateway setup으로 Claude Code나 Codex를 AI Gateway에 연결한 뒤 모델 선택 메뉴에서 가상 모델을 고르는 방법을 안내한다. 연결 과정에서 기존 도구의 인증·모델 설정이 바뀔 수 있으니 실제 업무 환경에 적용하기 전에 현재 설정을 확인해야 한다.

Codex는 모델 선택 메뉴 외에 codex --model vmc/coding-agent처럼 실행하거나 ~/.codex/config.toml에 model 값을 지정할 수 있다. Claude Code의 모델 선택 메뉴에는 연결 상태에 따라 claude-code/vmc/ 형태로 표시될 수 있다. 다만 가상 모델이 언어 모델을 가리킬 때만 코딩 에이전트의 모델 목록에 나타난다.

앱 코드에서도 특별한 새 API를 학습할 필요는 적다. 기존에 AI Gateway를 사용했다면 모델 문자열만 vmc/ 식별자로 교체하는 방식이다. AI SDK뿐 아니라 AI Gateway가 제공하는 OpenAI·Anthropic 호환 API에서도 가상 모델을 호출할 수 있다고 공식 발표는 설명한다.

텍스트 모델만 지원하는 기능도 아니다. 이미지 생성, 음성, 임베딩 등 AI Gateway 카탈로그의 다른 모델 유형에도 가상 모델을 만들 수 있다. 하지만 모델 유형은 유지해야 한다. 이미지 생성용 가상 모델을 텍스트 채팅 엔드포인트에 보내면 지원되지 않는 요청으로 오류가 난다.

또한 공급자마다 받는 옵션이 다르다. Anthropic 전용 추론 설정을 붙여 놓고 가상 모델의 실제 대상을 OpenAI로 바꾸면 그 옵션이 새 공급자에 자동 번역되는 것은 아니다. 모델을 교체할 때는 기능 지원과 파라미터, 응답 형식을 함께 확인해야 한다.

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'vmc/coding-agent',
  prompt: '이 변경 사항의 위험 요소를 요약해 줘.',
});
console.log(text);

근거 [1] [3]

무료로 쓸 수 있나: 월 5달러 크레딧과 추가 과금

Vercel의 AI Gateway 요금 문서에는 팀 계정별 무료 등급에 월 5달러 크레딧이 포함된다고 적혀 있다. 그러나 무료 크레딧으로 모든 모델을 호출할 수 있다는 뜻은 아니다. 무료 등급은 별도로 지정된 모델만 이용할 수 있고 모델별 요청 제한도 낮다. 원하는 모델이 무료 대상인지 먼저 카탈로그에서 확인해야 한다.

유료 등급에서는 사용한 모델의 입력·출력 토큰과 공급자별 요금에 따라 비용이 청구된다. Vercel은 토큰 추론 요금에 자체 가산금이나 플랫폼 수수료를 붙이지 않는다고 안내한다. 그렇지만 이 문구를 전체 기능이 무료라는 뜻으로 받아들이면 곤란하다. 별도로 켜는 일부 부가 기능에는 추가 요금이 있고 결제 처리 수수료가 적용될 수도 있다.

예를 들어 가상 모델에 요청 분류 태그를 붙여 팀별 비용을 나누고 싶다면 Custom Reporting의 태그 기록·조회 과금도 확인해야 한다. 공식 요금표에는 태그 등 기록 1,000회당 0.075달러, 보고 API 조회 1,000회당 5달러가 제시돼 있다. 이 비용은 모델 토큰 요금과 구분되는 항목이다.

직접 가져온 공급자 API 키를 쓰는 BYOK도 무조건 무료 등급에서 가능한 것은 아니다. 공식 요금 문서는 BYOK를 유료 등급에서 제공한다고 설명한다. 또한 자체 키 요청이 실패했을 때 AI Gateway 시스템 자격 증명으로 재시도하면 그 사용량은 Gateway 크레딧 잔액에서 차감될 수 있다.

모델 교체 자체가 자동 비용 최적화를 보장하지는 않는다. 예를 들어 저렴한 분류 모델을 비싼 추론 모델로 바꾸면 코드 수정은 줄어도 호출 비용은 올라갈 수 있다. 업무별 식별자를 나누고 월 예산, 호출 수, 평균 토큰 사용량을 같이 보는 편이 낫다.

2026년 10월 29일 확인한 Vercel AI Gateway 공식 요금 안내. 가상 모델 사용에 별도 고정 요금이 있다는 주장은 확인되지 않았으며 실제 모델·부가 기능별 과금은 대시보드에서 다시 확인해야 한다.

근거 [1] [3] [5]

운영에 넣기 전에 확인할 네 가지 경계

첫째, 같은 이름을 사용하는 모든 호출자가 변경의 영향을 받는다. 가상 모델을 바꾸면 웹 앱과 에이전트가 함께 새 설정을 받기 때문에 편하지만, 잘못 바꾸면 장애 범위도 넓어진다. 운영·테스트 식별자를 분리하고 되돌릴 이전 모델 이름을 기록해 두는 편이 안전하다.

둘째, 보안 설정은 공급자 지원 범위까지 확인해야 한다. Zero Data Retention을 필수로 지정하면 그 조건을 충족하지 못하는 공급자는 사용할 수 없을 수 있다. 보안 요구를 체크박스로 표시했다고 실제 공급자의 데이터 처리 정책을 검토할 필요가 없어지는 것은 아니다.

셋째, 설정의 우선순위를 알아야 한다. 가상 모델의 제한이 요청별 옵션보다 우선하는 항목이 있지만, 팀 전체의 허용 목록은 여전히 상위 정책이다. 특정 공급자만 사용해야 하는 서비스라면 Provider Order가 아니라 Provider Only를 검토해야 하고, 허용 공급자가 모두 장애일 때 실패하는 상황도 받아들여야 한다.

넷째, 모델 교체는 응답 품질과 API 호환성을 따로 검증해야 한다. 동일한 프롬프트를 보내도 모델마다 출력 형식, 함수 호출, 도구 사용, 응답 지연이 다르다. 재배포를 생략할 수 있다는 장점이 평가와 모니터링까지 생략해도 된다는 뜻은 아니다.

가상 모델은 작은 개인 프로젝트에서도 사용할 수 있지만, 여러 애플리케이션이 같은 설정을 참조하거나 모델 정책을 자주 바꾸는 팀에서 효과가 크다. 반대로 모델 하나를 고정해 쓰는 앱이라면 추가 관리 화면과 외부 게이트웨이를 도입할 가치가 있는지 먼저 비교하는 게 합리적이다.

근거 [1] [3] [4] [5]

자주 묻는 질문

현재 발표 기준으로 Virtual Models는 AI Gateway에서 사용할 수 있다. 하지만 특정 팀의 계정 상태나 원하는 모델의 무료 이용 가능 여부는 별도 확인이 필요하다. 아래는 공식 발표와 제품 문서에서 확인할 수 있는 범위만 정리했다.

이 기능의 핵심은 호출자가 보는 이름과 실제 모델을 분리하는 것이다. 여러 앱에서 같은 식별자를 쓰는 경우에만 중앙 변경의 이점이 크게 드러난다. 실제 운영에 적용할 때는 변경 전후 요청을 비교하고 오류·지연·비용을 기록하는 절차를 권한다.

근거 [1] [3] [5]