모델 라우팅 구성

이 페이지에서는 OpenAPI 3.x 사양을 사용하여 API Gateway에서 모델 라우팅을 구성, 배포, 테스트하는 방법을 설명합니다.

시작하기 전에

모델 라우팅을 구성하기 전에 환경이 다음 필수사항을 충족하는지 확인하세요.

  1. IAM 권한 확인: API Gateway 관리 영역 및 Vertex AI Model Garden에 액세스할 수 있는지 확인합니다. API 구성 및 게이트웨이를 만들려면 API Gateway 관리자 (roles/apigateway.admin) 역할이 있어야 합니다. 또한 API 게이트웨이에서 사용하는 서비스 계정(기본 Compute Engine 서비스 계정 또는 API 구성을 만들 때 지정된 사용자 관리 서비스 계정)에 대상 모델에 액세스할 수 있는 Vertex AI 사용자(roles/aiplatform.user) 역할이 부여되어야 합니다.
  2. 모델 가용성 및 엔드포인트 액세스 확인: 라우팅 가능한 모델이 Vertex AI Model Garden의 서비스형 모델 (MaaS)을 위한 사전 배포된 개방형 모델인지 확인합니다. 단일 라우터에서 참조하는 모든 모델은 정확히 동일한 호스트 이름을 공유해야 합니다. 해당 라우터 내에서 참조되는 모든 모델에 대해 전역 엔드포인트 (aiplatform.googleapis.com) 또는 단일 리전 엔드포인트 (예: us-central1-aiplatform.googleapis.com)를 선택합니다.
  3. 게이트웨이 배포 자격 확인: 모델 라우팅 없이 배포된 기존 게이트웨이를 업데이트하여 모델 라우팅을 사용 설정하거나 모델 라우팅으로 배포된 게이트웨이를 업데이트하여 모델 라우팅을 사용 중지하거나 삭제할 수 없습니다. 라우팅 모드를 전환하려면 새 API 구성 및 게이트웨이 인스턴스를 만들고 배포해야 합니다.
  4. VPC 서비스 제어 및 엔드포인트 호환성 확인: 모델 라우팅 게이트웨이는 VPC 서비스 제어 또는 Private Service Connect (PSC) 엔드포인트 구성을 지원하지 않습니다. 대상 프로젝트 및 API Gateway 인스턴스가 VPC 서비스 제어 경계에 의해 제한되지 않고 모델이 공개 리전 또는 전역 엔드포인트를 사용하는지 확인합니다.

구성 검증

API 구성을 배포하면 API Gateway 관리 영역이 OpenAPI 사양을 검증합니다. 관리 영역은 배포 중에 잘못된 구성을 정보 검증 오류와 함께 거부합니다. 검증 프로세스는 다음 규칙을 적용합니다.

구조 및 위치 확인

  • x-google-api-management 확장 프로그램 및 연결된 블록 (backends, ai.models.routing.routers, 개별 라우터, rules)은 형식이 올바르게 지정되어야 합니다. 키는 예상 데이터 유형 (맵, 목록 또는 문자열)과 일치해야 합니다. 관리 영역은 expected map/list/string 오류와 함께 유형 불일치를 거부합니다.
  • 모델 라우팅이 사용 설정된 경우 x-google-api-management 확장 프로그램에 유효한 backends 블록이 포함되어야 합니다.
  • x-google-model-router 확장 프로그램은 OpenAPI 3.x 사양에서만 지원됩니다 (OpenAPI 2.0 / Swagger에서는 지원되지 않음).
  • x-google-model-router 확장 프로그램은 작업 수준에서만 지정할 수 있습니다. 관리 영역은 경로 수준 또는 루트 (최상위) 수준에 배치된 x-google-model-router 정의를 명시적으로 거부합니다.
  • 작업이 x-google-model-router를 참조할 때마다 ai.models.routing.routers 블록이 x-google-api-management 내에 정의되어야 합니다.
  • 동일한 API 작업에서 x-google-model-router와 x-google-backend를 모두 지정할 수는 없습니다.
  • OpenAPI 사양에는 모델 라우팅 작업과 비모델 라우팅 작업을 혼합하여 포함할 수 없습니다. 동일한 API 사양 내에서 일부 작업에 표준 라우팅 확장 프로그램 (x-google-backend 등)을 지정하면서 다른 작업에 x-google-model-router를 사용할 수는 없습니다.

HTTP 메서드 확인

  • x-google-model-router 확장 프로그램은 POST HTTP 메서드를 사용하는 작업에만 적용할 수 있습니다. 관리 영역은 다른 HTTP 메서드 (GET, PUT, DELETE 등)의 모델 라우팅을 거부합니다.

백엔드 유효성

  • x-google-api-management.backends 아래에 정의된 모든 백엔드에는 비어 있지 않은 address 필드가 포함되어야 합니다.
  • 백엔드 address는 http 또는 https 스킴을 사용하는 유효한 URL이어야 합니다. 공개 또는 원격 엔드포인트 간에 전송되는 프롬프트 페이로드 및 인증 사용자 인증 정보를 보호하려면 address 필드를 정의할 때 항상 https 스킴을 지정하세요.
  • x-google-api-management.backends 아래에 정의되고 모델 라우터에서 참조하는 모든 백엔드는 pathTranslation: CONSTANT_ADDRESS를 사용해야 합니다. 관리 영역은 모델 라우터의 런타임 경로에서 경로 변환이 무시되므로 모델 라우팅 백엔드에 pathTranslation: APPEND_PATH_TO_ADDRESS를 사용하는 구성을 거부합니다.
  • 모델 라우팅 백엔드는 VPC 서비스 제어 또는 Private Service Connect (PSC) 엔드포인트 구성을 지원하지 않습니다. 모든 백엔드 address 필드는 공개 리전 또는 전역 MaaS 개방형 모델 엔드포인트를 가리켜야 합니다.

라우터 참조 확인

  • 작업의 x-google-model-router에서 참조하는 라우터 이름은 ai.models.routing.routers 아래에 정의된 유효한 라우터 키와 일치해야 합니다.
  • 라우터의 defaultModel에서 참조하는 backend는 x-google-api-management.backends 아래에 정의된 유효한 백엔드와 일치해야 합니다.
  • 라우터의 각 규칙에서 참조하는 backend는 x-google-api-management.backends 아래에 정의된 유효한 백엔드와 일치해야 합니다.

라우터 콘텐츠

  • 각 라우터는 defaultModel을 정의해야 합니다.
  • defaultModel에는 유효한 backend 필드가 포함되어야 합니다.
  • defaultModel에는 비어 있지 않은 targetModel 필드가 포함되어야 합니다.
  • rules 아래의 각 항목에는 비어 있지 않은 model 필드가 포함되어야 합니다. 문자열 값 default는 예약되어 있으며 규칙의 model 값으로 사용할 수 없습니다.
  • rules 아래의 각 항목에는 비어 있지 않은 targetModel 필드가 포함되어야 합니다.
  • 단일 라우터 내의 모든 규칙에서 정의된 model 값은 고유해야 합니다. 관리 영역은 동일한 라우터 내에서 중복된 model 값을 거부합니다.

백엔드 호스트 및 스킴 일관성

  • 단일 라우터에서 참조하는 모든 백엔드 (defaultModel.backend 및 모든 규칙의 backend 포함)는 동일한 호스트 이름과 URL 스키마를 공유해야 합니다. 관리 영역은 동일한 라우터 내에서 호스트 이름이 다르거나 스킴이 일관되지 않은 (http 대 https) 구성을 거부하여 라우터가 모든 요청을 일관된 업스트림 서비스 엔드포인트로 전달하도록 합니다.

대상 모델 검증

  • targetModel 문자열 (google, openai, 또는 anthropic)의 <provider> 부분과 <provider>/<model> 식별자 형식은 모두 구성 생성 (배포) 시에 검증됩니다. 관리 영역은 배포 중에 <provider>/<model> 형식으로 지정되지 않았거나 프로바이더가 google, openai, anthropic이 아닌 targetModel을 InvalidArgument: unsupported publisher 오류와 함께 거부합니다.

1단계: 대상 모델 식별

대상 기반 모델과 해당 Vertex AI 엔드포인트 URL을 식별합니다. 라우터 내의 모든 라우팅 가능한 모델은 단일 호스트 이름을 공유해야 합니다 (MaaS 개방형 모델의 경우 이 호스트 이름은 aiplatform.googleapis.com).

엔드포인트 URL 경로는 모델 제공업체에 따라 다릅니다.

  • Google Gemini: :generateContent 메서드를 사용합니다.
  • Anthropic Claude: :rawPredict 메서드를 사용합니다.
  • OpenAI: /endpoints/openapi/chat/completions 엔드포인트 경로를 사용합니다.

다음 표에는 이 섹션의 뒷부분에 나오는 OpenAPI 사양 예시에서 사용되는 MaaS 엔드포인트가 나와 있습니다.

모델 엔드포인트 URL
google/gemini-3.5-flash-lite https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash-lite:generateContent
anthropic/claude-opus-4-7 https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/publishers/anthropic/models/claude-opus-4-7:rawPredict
openai/gpt-oss-120b-maas https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/endpoints/openapi/chat/completions

YOUR_PROJECT_ID를 프로젝트 ID로 바꿉니다. Google Cloud

2단계: OpenAPI 3.x 사양 구성

OpenAPI 3.x 사양을 만들거나 업데이트하여 백엔드 엔드포인트 및 모델 라우팅 구성을 정의합니다.

다음 예시에서는 두 개의 고유한 모델 라우터를 정의하는 OpenAPI 3.0.3 사양을 보여줍니다. 가로 스크롤을 방지하기 위해 긴 백엔드 주소 URL은 YAML 큰따옴표로 묶인 여러 줄 문자열 연속 (``)을 사용합니다.

openapi: 3.0.3

info:
  title: OpenAPI 3.x spec using Model Routing
  description: Using Model Routing in an OAS 3.x spec
  version: 1.0.0

x-google-api-management:
  backends:
    gemini-35-flashlite:
      address: "https://aiplatform.googleapis.com/v1/projects/\
        YOUR_PROJECT_ID/locations/global/publishers/google/\
        models/gemini-3.5-flash-lite:generateContent"
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

    anthropic-claude-opus-47:
      address: "https://aiplatform.googleapis.com/v1/projects/\
        YOUR_PROJECT_ID/locations/global/publishers/anthropic/\
        models/claude-opus-4-7:rawPredict"
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

    openai-gpt-oss-120b:
      address: "https://aiplatform.googleapis.com/v1/projects/\
        YOUR_PROJECT_ID/locations/global/endpoints/openapi/\
        chat/completions"
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

  ai:
    models:
      routing:
        routers:
          # Router 1: route between Gemini (default) and Claude.
          gemini-claude-router:
            defaultModel:
              backend: gemini-35-flashlite
              targetModel: google/gemini-3.5-flash-lite
            rules:
              - model: "claude-opus-4-7"
                backend: anthropic-claude-opus-47
                targetModel: anthropic/claude-opus-4-7

          # Router 2: route between OpenAI GPT (default) and Gemini.
          openai-gemini-router:
            defaultModel:
              backend: openai-gpt-oss-120b
              targetModel: openai/gpt-oss-120b-maas
            rules:
              - model: "gemini-3.5-flash-lite"
                backend: gemini-35-flashlite
                targetModel: google/gemini-3.5-flash-lite

servers:
  - url: "https://my-gateway-url.com"

paths:
  /v1/chat/gemini-claude:
    post:
      summary: "Endpoint:defaults to Gemini & Claude as an option."
      operationId: "chatGeminiClaude"
      x-google-model-router: gemini-claude-router
      responses:
        '200':
          description: "OK"

  /v1/chat/openai-gemini:
    post:
      summary: "Endpoint:defaults to OpenAI & Gemini as an option."
      operationId: "chatOpenAIGemini"
      x-google-model-router: openai-gemini-router
      responses:
        '200':
          description: "OK"

구성 속성

  1. backends: x-google-api-management 아래의 backends 객체는 모든 라우팅 가능한 모델 엔드포인트를 정의합니다. 각 백엔드 이름은 대상 address가 포함된 상징적 모델 이름 (예: gemini-35-flashlite)을 나타냅니다. backends 필드는 기존 Google OpenAPI 확장 프로그램입니다.
  2. ai.models.routing: 모델 라우팅 구성은 x-google-api-management 아래에 ai.models.routing으로 있으며, 이름이 지정된 라우터의 맵을 포함합니다. 각 맵 항목은 하나의 모델 라우터를 정의합니다. 여기서 키는 라우터의 이름 (예: gemini-claude-router)을 나타내고 값은 다음을 포함합니다.
    • defaultModel: 수신 요청 페이로드가 명시적 규칙과 일치하지 않을 때 사용되는 필수 대체 모델 대상입니다. 규칙 항목의 정확한 구조를 공유하지만 model 일치 필드는 생략합니다. OpenAI 호환 경로의 경우 요청이 defaultModel로 대체되면 targetModel의 값이 Vertex AI로 전송되는 요청 본문의 나가는 model 속성으로 전달됩니다.
    • rules: 각 요소가 클라이언트 페이로드 모델 문자열을 대상 백엔드 및 대상 모델에 매핑하는 선택적 배열입니다.
  3. 규칙 속성: rules (및 defaultModel) 내의 각 항목은 다음 속성을 정의합니다.
    • model (규칙만): 클라이언트의 수신 JSON 프롬프트 페이로드 내에서 model 속성과 일치하는 문자열 값입니다. 라우터는 수신 페이로드의 model 값을 이 문자열과 비교합니다. 일치하는 규칙이 없으면 라우터가 defaultModel을 선택합니다. OpenAI 호환 경로 (대상 백엔드가 /openapi/chat/completions인 경우)의 경우 이 문자열은 Vertex AI로 전송되는 요청 본문의 나가는 model 속성으로 직접 전달됩니다. 따라서 OpenAI 호환 경로의 경우 model 선택기 자체가 유효한 게시자 모델 식별자 (예: openai/gpt-oss-120b-maas)여야 합니다. gpt-oss와 같은 별칭을 사용하면 Vertex AI에서 400 Malformed publisher model 오류가 발생합니다.
    • backend: 게이트웨이가 프롬프트를 전송하는 x-google-api-management.backends 아래에 정의된 상징적 백엔드 이름입니다.
    • targetModel: <provider>/<model-id> 형식으로 지정된 대상 모델 식별자입니다. 모델 라우터는 이 문자열을 사용하여 대상 모델의 요청과 응답을 변환합니다. <provider> 프리픽스는 정확히 google, openai 또는 anthropic이어야 합니다. <model-id>는 유효한 Vertex AI Model Garden 게시자 모델 식별자여야 합니다. 게이트웨이는 클라이언트에 반환된 응답의 model 필드 내에서 이 문자열을 다시 에코합니다. 예시 값은 다음과 같습니다.
      • google/gemini-3.5-flash-lite
      • google/gemini-2.5-pro
      • openai/gpt-oss-120b-maas
      • anthropic/claude-opus-4-7
  4. x-google-model-router: 모델 라우터를 API 작업 경로에 연결하려면 x-google-model-router 속성을 사용하여 라우터 이름을 지정합니다. 이전 예시에서 /v1/chat/gemini-claude로 전송된 POST 요청은 JSON 페이로드에 지정된 모델 이름을 기반으로 프롬프트를 라우팅하는 gemini-claude-router를 호출합니다.

3단계: API 구성 만들기 및 배포

작성된 OpenAPI 3.x 사양을 사용하여 API 구성을 만들고 게이트웨이에 API 배포에 설명된 대로 API Gateway 인스턴스에 구성을 배포합니다.

API 게이트웨이 관리 영역은 모델 라우팅 구성을 처리하고 라우팅 레이어를 활성화합니다. 게이트웨이 배포가 완료되면 게이트웨이는 OpenAI 호환 JSON 페이로드 형식으로 지정된 프롬프트 요청을 수신할 준비가 됩니다.

4단계: 라우팅 동작 테스트

게이트웨이를 테스트하기 전에 게이트웨이가 ACTIVE 상태에 도달할 때까지 기다린 후 URL을 검색합니다.

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GATEWAY_LOCATION \
  --project=PROJECT_ID \
  --format='value(defaultHostname)'

공개 미리보기 중에 모델 라우팅 게이트웨이는 *.run.app 호스트 이름을 반환합니다. 게이트웨이가 ACTIVE된 후에만 호스트 이름을 검색합니다. 게이트웨이가 아직 생성 중일 때 보고된 값은 최종 URL이 아닙니다.

curl을 사용하여 게이트웨이 URL (https://GATEWAY_URL)에 OpenAI 호환 프롬프트 요청을 전송하여 게이트웨이의 라우팅 동작을 테스트합니다. 다음 예시에서 $TOKEN는 인증 방법 선택에 설명된 방법 중 하나를 사용하여 가져온 유효한 인증 토큰을 나타냅니다.

명시적 규칙 라우팅 테스트

Claude 모델 anthropic/claude-opus-4-7을 요청하는 프롬프트를 전송합니다.

curl https://GATEWAY_URL/v1/chat/gemini-claude \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "claude-opus-4-7",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Explain the concept of recursion in one sentence."
      }
    ]
  }'

/v1/chat/gemini-claude로 요청을 전송하면 gemini-claude-router가 호출됩니다. JSON 페이로드 내의 속성 "model": "claude-opus-4-7"은 gemini-claude-router의 명시적 규칙과 일치하여 게이트웨이가 요청을 anthropic-claude-opus-47 백엔드로 라우팅하도록 지시합니다.

기본 모델 대체 테스트

일치하지 않는 모델 이름을 지정하는 프롬프트를 전송하여 대체 라우팅을 테스트합니다.

curl https://GATEWAY_URL/v1/chat/gemini-claude \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "unrecognized-model",
    "messages": [
      {
        "role": "user",
        "content": "Write a short poem about the ocean."
      }
    ],
    "stream": true
  }'

/v1/chat/gemini-claude로 요청을 전송하면 gemini-claude-router가 호출됩니다. 속성 "model": "unrecognized-model"이 명시적 규칙과 일치하지 않으므로 게이트웨이는 요청을 라우터의 구성된 defaultModel(즉, gemini-35-flashlite 백엔드)로 전달합니다.

대체 라우터 경로 테스트

보조 라우터 엔드포인트를 통해 Gemini를 요청하는 프롬프트를 전송합니다.

curl https://GATEWAY_URL/v1/chat/openai-gemini \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "gemini-3.5-flash-lite",
    "messages": [
      {
        "role": "user",
        "content": "List the three largest cities in the world."
      }
    ]
  }'

/v1/chat/openai-gemini로 요청을 전송하면 openai-gemini-router가 호출됩니다. 속성 "model": "gemini-3.5-flash-lite"은 해당 라우터의 명시적 규칙과 일치하여 게이트웨이가 요청을 gemini-35-flashlite 백엔드로 라우팅하도록 지시합니다. 단일 백엔드는 여러 라우터에서 참조할 수 있습니다. 이 구성에서 gemini-35-flashlite는 openai-gemini-router의 명시적 규칙 타겟으로, gemini-claude-router의 대체 defaultModel로 사용됩니다.

모니터링 가능성

게이트웨이가 트래픽을 제공하는지 확인하고, Cloud Logging을 사용하여 요청별 메타데이터를 검사하고, Cloud Monitoring을 사용하여 오류를 진단할 수 있도록 모델 라우터가 계측됩니다.

Cloud Logging

게이트웨이를 통해 라우팅되는 모든 요청은 your Google Cloud project의 다음 위치에 있는 표준 API Gateway 요청 로그에 항목을 생성합니다.

projects/YOUR_PROJECT_ID/logs/apigateway.googleapis.com%2Frequests

각 로그 항목에는 다음 필드가 포함됩니다.

  • httpRequest.requestUrl, httpRequest.status, httpRequest.latency
  • api, apiConfig, apiMethod
  • backendRequest.hostname: 요청이 프록시된 Vertex AI 백엔드의 호스트 이름입니다.
  • responseDetails: 모델 라우터 오류 시 브랜드 오류 카테고리로 채워집니다 (바로 아래의 모델 라우터 오류 문제 해결 참고).

특정 게이트웨이로 전송된 최근 요청을 찾으려면 다음 Cloud Logging 쿼리 필터를 사용하세요.

(resource.type="apigateway.googleapis.com/Gateway" OR resource.type="api")
logName="projects/YOUR_PROJECT_ID/logs/apigateway.googleapis.com%2Frequests"

Cloud Monitoring

표준 API 게이트웨이 측정항목 apigateway.googleapis.com/proxy/request_count (베타)는 다음과 같이 분류된 게이트웨이 트래픽 볼륨을 보고합니다.

  • response_code_class: 2xx, 3xx, 4xx 또는 5xx 중 하나입니다.
  • api_config: 게이트웨이가 사용하는 API 구성 이름입니다.

이 측정항목을 사용하면 전반적인 트래픽 볼륨과 오류율을 확인할 수 있습니다. 라우터별 또는 대상 모델별 분류와 같은 모델 라우터별 측정항목은 향후 출시 버전에 추가될 예정입니다.

집계된 요청 지연 시간을 추적하려면 요청 로그의 httpRequest.latency 필드에서 로그 기반 측정항목을 만들면 됩니다.

모델 라우터 오류 문제 해결

모델 라우터를 통해 라우팅된 요청이 실패하면 해당 요청 로그 항목의 responseDetails 필드는 모델 라우터 레이어 내에서 오류가 발생했는지 여부를 나타냅니다. 모델 라우터는 다음과 같은 4가지 브랜드 카테고리를 표시합니다.

responseDetails 값 의미 일반적인 수정사항
model_router_application_error 요청을 라우팅할 수 없습니다. 이는 일반적으로 규칙이 누락되었거나, 구성된 defaultModel 없이 규칙과 일치하지 않는 model 값이 포함된 페이로드이거나, 형식이 잘못된 요청 페이로드를 나타냅니다. 고객 측: 페이로드의 model 매개변수가 라우터 구성의 rule.model 문자열 중 하나와 일치하거나 defaultModel 대체가 정의되어 있는지 확인합니다. 요청 본문이 유효한 OpenAI 호환 JSON이고 model 속성을 명시적으로 포함하는지 확인합니다 (공개 미리보기 중에 요청 페이로드의 누락된 model 속성은 거부되는 대신 잘못 처리됨).
model_router_timeout 모델 라우터가 요청별 제한 시간을 초과했습니다. 요청이 비정상적으로 크거나 복잡하거나 용량 병목 현상이 있을 수 있습니다. 백엔드 전반에서 요청 복잡성과 제한 시간 설정을 확인합니다. 일반 페이로드에서 문제가 계속되면 Google Cloud 지원팀에 요청 타임스탬프와 로그 샘플을 포함하여 문의하세요.
model_router_upstream_error 업스트림 대상 모델이 게이트웨이에 HTTP 오류를 반환했습니다. 업스트림 서비스 측: 대상 Vertex AI 서비스 엔드포인트의 상태 코드와 페이로드를 확인합니다. 유효한 요청에 대해 예상치 못한 경우 지원 케이스를 엽니다.
model_router_unavailable 전송 또는 연결 오류로 인해 게이트웨이에서 모델 라우터에 연결할 수 없습니다. 플랫폼 측: Google Cloud 지원팀에 지원 케이스를 엽니다.

다음 단계