모델 라우팅 개요
API 게이트웨이의 모델 라우팅은 OpenAI 호환 프롬프트 요청을 수락하고, 전송 중에 트랜스코딩하며, 특정 Vertex AI 모델로 라우팅하는 관리형 트래픽 관리 레이어입니다. 모델 라우팅은 LiteLLM과 같은 클라이언트 측 프록시의 관리형 대안 역할을 하며, AI 에이전트의 수명 주기를 관리하는 중앙 집중식 인프라를 제공합니다.
모델 라우팅은 라우팅 로직을 네트워크 에지로 이동하고 동일한 호스트 최적화를 위해 Vertex AI Model Garden과 통합됩니다. 이 아키텍처는 관리되지 않는 프록시 서버를 호스팅, 확장, 유지관리할 필요성을 없애 운영 오버헤드와 인프라 비용을 줄여줍니다.
범위 및 사용자 여정
모델 라우팅은 다음과 같은 핵심 사용자 여정을 지원합니다.
- 모델 선택: AI 개발자는 Vertex AI Model Garden에서 MaaS (Model as a Service)의 개방형 모델을 사용합니다. 이러한 모델은 Gemini, Anthropic Claude 또는 OpenAI GPT 제품군 모델입니다.
- 사양 작성: AI 개발자는 배포된 모델을 참조하기 위해 OpenAPI 3.x 사양 내에서 모델 라우터 구성을 만들거나 업데이트합니다.
- API Gateway 배포: AI 개발자는 작성된 OpenAPI 사양을 사용하여 API 구성 및 API Gateway 인스턴스를 배포합니다.
- 프롬프트 라우팅: 클라이언트 애플리케이션은 OpenAI 호환 프롬프트 요청을 게이트웨이에 전송합니다. 게이트웨이는 JSON 페이로드에 지정된 모델 이름을 기반으로 요청을 라우팅하고 페이로드를 변환합니다.
향후 API 게이트웨이 버전에서는 추가 사용자 여정을 지원할 계획입니다.
모델 라우팅의 이점
API Gateway에서 모델 라우팅을 구현하면 다음과 같은 이점이 있습니다.
- 중앙 집중식 관리: 단일 관리형 게이트웨이 내에서 AI 트래픽 관리를 통합하여 분산된 클라이언트 측 라우팅 구성을 대체합니다.
- 운영 오버헤드 감소: 독립형 프록시 서버 배포와 관련된 인프라 비용 및 유지관리 부담을 없앱니다.
- 에지 최적화 성능: Vertex AI Model Garden 엔드포인트와의 직접 통합을 활용하여 네트워크 에지에서 프롬프트를 검사하고 트래픽을 라우팅합니다.
- 표준화된 클라이언트 인터페이스: 클라이언트 애플리케이션이 다양한 기본 기반 모델에 요청을 동적으로 디스패치하는 동시에 균일한 OpenAI 호환 REST 인터페이스와 상호작용할 수 있도록 합니다.
페르소나 및 사용 사례
모델 라우팅은 다음 페르소나의 요구사항을 해결합니다.
- 플랫폼 엔지니어: 엔터프라이즈 AI 배포 전반에서 클라이언트 측 라우팅 로직을 대체하는 관리형 인프라 솔루션을 프로비저닝합니다.
- AI 개발자: 요청 페이로드 매개변수를 기반으로 다양한 기반 모델 (예: Gemini Pro, Gemini Flash 또는 Anthropic Claude) 간에 요청을 동적으로 라우팅하는 표준화된 API 엔드포인트를 노출합니다.
- 거버넌스 관리자: 중앙 집중식 액세스 정책 (예: 인증 및 할당량)을 적용하고 조직 전반의 전반적인 AI 트래픽 볼륨을 모니터링합니다.
지원되는 사용 사례
공개 미리 보기 중에 모델 라우팅은 OpenAI 호환 클라이언트 요청의 JSON 페이로드 내에 지정된 모델 태그 또는 이름 (예: "model": "gemini-3.5-flash-lite")을 기반으로 하는 라우팅만 지원합니다.
아키텍처 및 요청 흐름
모델 라우팅은 API 게이트웨이 데이터 영역 내에서 관리형 라우팅 레이어로 작동합니다. 클라이언트 애플리케이션이 OpenAI 호환 프롬프트 요청을 게이트웨이에 전송하면 다음 순서가 발생합니다.
- 요청 가로채기: 게이트웨이가 수신
POST요청 (예:POST /chat/completions)을 가로챕니다. - 페이로드 검사: 모델 라우터가 수신 JSON 페이로드 내의
model속성 (예:{"model": "claude-opus-4-7", "messages": [...]})을 검사합니다. - 규칙 평가: 라우터가
model문자열을 OpenAPI 사양에 정의된 라우팅 규칙과 일치시킵니다. 일치하는 규칙이 없으면 라우터가 구성된 기본 모델을 선택합니다. - 전송 중 트랜스코딩: 게이트웨이가 OpenAI 호환 요청을 대상 Vertex AI 예측 스키마로 트랜스코딩합니다.
- 백엔드 디스패치: 게이트웨이가 트랜스코딩된 요청을 지정된 Vertex AI Model Garden 엔드포인트로 디스패치하고 모델 응답을 클라이언트에 반환합니다.
성능 및 제한사항
모델 라우팅을 구현하기 전에 다음 기술 제약조건을 검토하세요.
- 호스트 제약조건: 모델 라우팅은 단일 라우터에서 참조하는 모든 모델이 동일한 호스트 이름(예: 전역 엔드포인트
aiplatform.googleapis.com또는 단일 리전 엔드포인트(예:us-central1-aiplatform.googleapis.com))을 공유하는 Vertex AI Model Garden에서 호스팅되는 사전 배포된 MaaS 모델로의 라우팅만 지원합니다. - 사양 요구사항: 모델 라우팅에는 OpenAPI 3.x 사양과 해당 API Gateway OpenAPI 3.x 확장 프로그램이 필요합니다. OpenAPI 2.0 (Swagger) 사양은 지원되지 않습니다.
- 게이트웨이 업데이트: 모델 라우팅 없이 배포된 기존 게이트웨이를 업데이트하여 모델 라우팅을 사용 설정하거나 모델 라우팅으로 배포된 게이트웨이를 업데이트하여 모델 라우팅을 사용 중지하거나 삭제할 수 없습니다. 라우팅 모드를 전환하려면 새 API 구성 및 게이트웨이 인스턴스를 만들고 배포해야 합니다.
- 혼합 구성: OpenAPI 사양에는 모델 라우팅 및 비모델 라우팅 작업이 혼합되어 있을 수 없습니다. 사양의 모든 작업은 모델 라우팅을 사용하거나 표준 게이트웨이 라우팅을 사용해야 합니다.
- VPC 서비스 제어: 모델 라우팅 게이트웨이는 VPC 서비스 제어를 지원하지 않습니다. 모델 라우팅을 사용 설정하는 API Gateway 인스턴스에는 VPC 서비스 제어 경계를 사용할 수 없습니다.
- 스트리밍 및 지원되지 않는 프로토콜: 모델 라우팅은 응답 스트리밍 (서버 전송 이벤트)을 지원하지만 요청 측 스트리밍, gRPC, WebSockets 또는 Gemini Live는 지원하지 않습니다.
- 지원되는 모달리티: 공개 미리보기 중에 모델 라우팅은 OpenAI 호환 JSON 페이로드로 형식이 지정된 텍스트 기반 프롬프트 요청을 가정하고 페이로드의
model태그 또는 이름만을 기반으로 라우팅합니다. - 필수 페이로드 필드: 수신 JSON 요청 페이로드에는
model속성이 포함되어야 합니다. 공개 미리보기 중에 클라이언트 요청 페이로드에model필드가 없으면 게이트웨이가 오류와 함께 요청을 거부하는 대신 요청을 잘못 처리합니다. 클라이언트 요청이 JSON 페이로드에model필드를 지정하는지 항상 확인하세요. - 런타임 제한사항: 표준 게이트웨이 호스팅 인프라 서비스 제한사항 및 동작이 모델 라우팅 엔드포인트에 적용됩니다.
- 최대 제한 시간: 게이트웨이는 최대 요청 제한 시간 3,600초 (1시간)를 적용하며, 이는 장기 실행 스트리밍 요청에 적용됩니다.
- 콜드 스타트 지연 시간: 비활성 기간 동안 게이트웨이 인스턴스가 0으로 확장되면 초기 요청에 콜드 스타트 지연 시간이 발생할 수 있으며, 이는 지연 시간에 민감한 AI 추론 경로에 영향을 미칠 수 있습니다.
- 예약된 URL 경로:
/eventlog,/_ah/로 시작하는 경로 또는z로 끝나는 특정 경로와 같은 예약된 URL 경로는 사용할 수 없습니다 (충돌을 방지하려면z로 끝나는 경로 이름을 사용하지 마세요). - URL 문자 디코딩: 게이트웨이는 요청을 처리하기 전에 요청 URL에서 특정 인코딩된 문자를 자동으로 디코딩합니다 (예:
%41은A로 디코딩됨).