모델 라우팅 개요

API Gateway의 모델 라우팅은 OpenAI 호환 프롬프트 요청을 수락하고, 전송 중에 트랜스코딩하며, 특정 Gemini Enterprise Agent Platform 모델로 라우팅하는 관리형 트래픽 관리 레이어입니다. 모델 라우팅은 LiteLLM과 같은 클라이언트 측 프록시의 관리형 대안으로 작동하여 AI 에이전트의 수명 주기를 관리하는 중앙 집중식 인프라를 제공합니다.

모델 라우팅은 라우팅 로직을 네트워크 에지로 이동하고 동일 호스트 최적화를 위해 Agent Platform Model Garden과 통합됩니다. 이 아키텍처는 관리되지 않는 프록시 서버를 호스팅, 확장, 유지관리할 필요가 없으므로 운영 오버헤드와 인프라 비용이 절감됩니다.

범위 및 사용자 여정

모델 라우팅은 다음과 같은 핵심 사용자 여정을 지원합니다.

  • 모델 선택: AI 개발자가 Agent Platform Model Garden에서 서비스형 모델 (MaaS)의 개방형 모델을 사용합니다. Gemini, Anthropic Claude 또는 OpenAI GPT 제품군 모델입니다.
  • 사양 작성: AI 개발자가 OpenAPI 3.x 사양 내에서 모델 라우터 구성을 만들어 배포된 모델을 참조하거나 업데이트합니다.
  • 게이트웨이 배포: AI 개발자가 작성된 OpenAPI 사양을 사용하여 API 구성과 API Gateway 인스턴스를 배포합니다.
  • 프롬프트 라우팅: 클라이언트 애플리케이션은 OpenAI 호환 프롬프트 요청을 게이트웨이에 전송합니다. 게이트웨이는 JSON 페이로드에 지정된 모델 이름을 기반으로 요청을 라우팅하고 페이로드를 변환합니다.

향후 버전의 API Gateway에서는 추가 사용자 여정을 지원할 예정입니다.

모델 라우팅의 이점

API Gateway에서 모델 라우팅을 구현하면 다음과 같은 이점이 있습니다.

  • 중앙 집중식 관리: 단일 관리 게이트웨이 내에서 AI 트래픽 관리를 통합하여 분산된 클라이언트 측 라우팅 구성을 대체합니다.
  • 운영 오버헤드 감소: 독립형 프록시 서버 배포와 관련된 인프라 비용 및 유지보수 부담을 없앱니다.
  • 에지 최적화 성능: Agent Platform Model Garden 엔드포인트와의 직접 통합을 활용하여 네트워크 에지에서 프롬프트를 검사하고 트래픽을 라우팅합니다.
  • 표준화된 클라이언트 인터페이스: 클라이언트 애플리케이션이 다양한 기본 파운데이션 모델에 요청을 동적으로 디스패치하면서 균일한 OpenAI 호환 REST 인터페이스와 상호작용할 수 있도록 지원합니다.

페르소나 및 사용 사례

모델 라우팅은 다음 페르소나의 요구사항을 충족합니다.

  • 플랫폼 엔지니어: 엔터프라이즈 AI 배포 전반에서 클라이언트 측 라우팅 로직을 대체하는 관리형 인프라 솔루션을 프로비저닝합니다.
  • AI 개발자: 요청 페이로드 매개변수에 따라 다양한 파운데이션 모델 (예: Gemini Pro, Gemini Flash, Anthropic Claude) 간에 요청을 동적으로 라우팅하는 표준화된 API 엔드포인트를 노출합니다.
  • 거버넌스 관리자: 중앙 집중식 액세스 정책 (예: 인증 및 할당량)을 적용하고 조직 전체의 전반적인 AI 트래픽 양을 모니터링합니다.

지원되는 사용 사례

공개 프리뷰 기간 동안 모델 라우팅은 OpenAI 호환 클라이언트 요청의 JSON 페이로드 내에 지정된 모델 태그 또는 이름 (예: "model": "gemini-3.5-flash-lite")에만 기반한 라우팅을 지원합니다.

아키텍처 및 요청 흐름

모델 라우팅은 API Gateway 데이터 영역 내에서 관리형 라우팅 레이어로 작동합니다. 클라이언트 애플리케이션이 OpenAI 호환 프롬프트 요청을 게이트웨이에 전송하면 다음 순서가 발생합니다.

  1. 요청 가로채기: 게이트웨이가 수신되는 POST 요청 (예: POST /chat/completions)을 가로챕니다.
  2. 페이로드 검사: 모델 라우터는 수신되는 JSON 페이로드 내의 model 속성을 검사합니다 (예: {"model": "claude-opus-4-7", "messages": [...]}).
  3. 규칙 평가: 라우터는 model 문자열을 OpenAPI 사양에 정의된 라우팅 규칙과 일치시킵니다. 일치하는 규칙이 없으면 라우터는 구성된 기본 모델을 선택합니다.
  4. 전송 중 트랜스코딩: 게이트웨이가 OpenAI 호환 요청을 대상 Agent Platform 예측 스키마로 트랜스코딩합니다.
  5. 백엔드 디스패치: 게이트웨이는 트랜스코딩된 요청을 지정된 Agent Platform Model Garden 엔드포인트로 디스패치하고 모델 응답을 클라이언트에 반환합니다.

성능 및 제한사항

모델 라우팅을 구현하기 전에 다음 기술적 제약사항을 검토하세요.

  • 호스트 제약 조건: 모델 라우팅은 단일 라우터에서 참조하는 모든 모델이 동일한 호스트 이름(예: 전역 엔드포인트 aiplatform.googleapis.com 또는 단일 리전 엔드포인트(예: us-central1-aiplatform.googleapis.com))을 공유하는 Agent Platform Model Garden에 호스팅된 사전 배포된 MaaS 모델로만 라우팅을 지원합니다.
  • 사양 요구사항: 모델 라우팅에는 OpenAPI 3.x 사양과 해당 API Gateway OpenAPI 3.x 확장 프로그램이 필요합니다. OpenAPI 2.0 (Swagger) 사양은 지원되지 않습니다.
  • 게이트웨이 업데이트: 모델 라우팅 없이 배포된 기존 게이트웨이를 업데이트하여 모델 라우팅을 사용 설정할 수 없으며, 모델 라우팅으로 배포된 게이트웨이를 업데이트하여 모델 라우팅을 사용 중지하거나 삭제할 수도 없습니다. 라우팅 모드를 전환하려면 새 API 구성과 게이트웨이 인스턴스를 만들고 배포해야 합니다.
  • 혼합 구성: OpenAPI 사양에는 모델 라우팅 작업과 비모델 라우팅 작업이 혼합되어 있을 수 없습니다. 사양의 모든 작업은 모델 라우팅을 사용하거나 표준 게이트웨이 라우팅을 사용해야 합니다.
  • VPC 서비스 제어: 모델 라우팅 게이트웨이는 VPC 서비스 제어를 지원하지 않습니다. 모델 라우팅을 사용 설정하는 API Gateway 인스턴스에는 VPC 서비스 제어 경계를 사용할 수 없습니다.
  • 스트리밍 및 지원되지 않는 프로토콜: 모델 라우팅은 응답 스트리밍 (서버 전송 이벤트)을 지원하지만 요청 측 스트리밍, gRPC, WebSocket 또는 Gemini Live는 지원하지 않습니다.
  • 지원되는 모달리티: 공개 미리보기 기간 동안 모델 라우팅은 OpenAI 호환 JSON 페이로드로 형식이 지정된 텍스트 기반 프롬프트 요청을 가정하고 페이로드의 model 태그 또는 이름에만 기반하여 라우팅합니다.
  • 필수 페이로드 필드: 수신되는 JSON 요청 페이로드에는 model 속성이 포함되어야 합니다. 공개 미리보기 중에 클라이언트 요청 페이로드에서 model 필드가 누락되면 게이트웨이는 오류와 함께 요청을 거부하는 대신 요청을 잘못 처리합니다. 클라이언트 요청이 JSON 페이로드에 model 필드를 지정하는지 항상 확인하세요.
  • 런타임 제한사항: 표준 게이트웨이 호스팅 인프라 서비스 제한사항 및 동작이 모델 라우팅 엔드포인트에 적용됩니다.
    • 최대 제한 시간: 게이트웨이는 장기 실행 스트리밍 요청에 적용되는 최대 요청 제한 시간 3,600초 (1시간)를 적용합니다.
    • 콜드 스타트 지연 시간: 비활성 기간에 게이트웨이 인스턴스가 0으로 확장되면 초기 요청에 콜드 스타트 지연 시간이 발생할 수 있으며, 이는 지연 시간에 민감한 AI 추론 경로에 영향을 미칠 수 있습니다.
    • 예약된 URL 경로: /_ah/로 시작하는 예약된 URL 경로 또는 z로 끝나는 특정 경로를 사용할 수 없습니다 (충돌을 방지하려면 z로 끝나는 경로 이름을 사용하지 마세요).
    • URL 문자 디코딩: 게이트웨이는 요청을 처리하기 전에 요청 URL에서 인코딩된 특정 문자를 자동으로 디코딩합니다 (예: %41가 A로 디코딩됨).

다음 단계