Configurar o roteamento de modelos

Nesta página, descrevemos como configurar, implantar e testar o roteamento de modelos no gateway de API usando as especificações da OpenAPI 3.x.

Antes de começar

Antes de configurar o roteamento de modelos, verifique se o ambiente atende aos seguintes pré-requisitos:

  1. Verifique as permissões do IAM: confira se você tem acesso ao plano de gerenciamento do gateway de API e ao Model Garden da Gemini Enterprise Agent Platform. Você precisa ter o papel de administrador do gateway de API (roles/apigateway.admin) para criar configurações e gateways de API. Além disso, a conta de serviço usada pelo gateway (a conta de serviço padrão do Compute Engine ou uma conta de serviço gerenciado pelo usuário especificada ao criar a configuração da API) precisa receber o papel de Usuário da Agent Platform (roles/aiplatform.user) em cada projeto que hospeda um modelo de destino. Portanto, um roteador com back-ends em outros projetos também precisa do papel nesses projetos.
  2. Verifique a disponibilidade do modelo e o acesso ao endpoint: confira se os modelos roteáveis são modelos abertos pré-implantados para o modelo como serviço (MaaS) no Model Garden da Agent Platform. Os modelos referenciados por um único roteador podem usar endpoints diferentes, como o endpoint global (aiplatform.googleapis.com) e endpoints regionais (por exemplo, us-central1-aiplatform.googleapis.com). Para as regras que se aplicam, consulte Hosts e esquemas de back-end.
  3. Verifique a qualificação para implantação do gateway: não é possível atualizar um gateway implantado sem o roteamento de modelos para ativá-lo, nem atualizar um gateway implantado com o roteamento de modelos para desativá-lo ou removê-lo. Para alternar os modos de roteamento, crie e implante uma nova configuração de API e uma instância de gateway.
  4. Verifique a compatibilidade do VPC Service Controls e do endpoint: os gateways de roteamento de modelos não são compatíveis com as configurações de endpoint do VPC Service Controls ou do Private Service Connect (PSC). Verifique se o projeto de destino e as instâncias do gateway de API não estão restritos por perímetros do VPC Service Controls e se os modelos usam endpoints públicos regionais ou globais.

Validação de configuração

Quando você implanta uma configuração de API, o plano de gerenciamento do gateway de API valida sua especificação OpenAPI. O plano de gerenciamento rejeita configurações inválidas durante a implantação com um erro de validação informativo. O processo de validação aplica as seguintes regras:

Verificações estruturais e de localização

  • A extensão x-google-api-management e os blocos associados (backends, ai.models.routing.routers, roteadores individuais e rules) precisam estar bem formados. As chaves precisam corresponder aos tipos de dados esperados (mapa, lista ou string). O plano de gerenciamento rejeita incompatibilidades de tipo com um erro expected map/list/string.
  • A extensão x-google-api-management precisa conter um bloco backends válido quando o roteamento de modelos está ativado.
  • A extensão x-google-model-router é compatível apenas com as especificações OpenAPI 3.x (não é compatível com OpenAPI 2.0 / Swagger).
  • A extensão x-google-model-router só pode ser especificada no nível da operação. O plano de gerenciamento rejeita explicitamente as definições de x-google-model-router colocadas no nível do caminho ou da raiz (superior).
  • O bloco ai.models.routing.routers precisa ser definido dentro de x-google-api-management sempre que uma operação fizer referência a x-google-model-router.
  • Não é possível especificar x-google-model-router e x-google-backend na mesma operação de API.
  • Uma especificação OpenAPI não pode conter uma combinação de operações de roteamento de modelos e operações que não são de roteamento de modelos. Não é possível especificar extensões de roteamento padrão (como x-google-backend) em algumas operações enquanto usa x-google-model-router em outras operações na mesma especificação de API.

Verificação do método HTTP

  • A extensão x-google-model-router só pode ser aplicada a operações que usam o método HTTP POST. O plano de gerenciamento rejeita o roteamento de modelos em qualquer outro método HTTP (como GET, PUT ou DELETE).

Validade do back-end

  • Cada back-end definido em x-google-api-management.backends precisa incluir um campo address não vazio.
  • O back-end address precisa ser um URL válido que use o esquema http ou https. Para proteger payloads de comando e credenciais de autenticação em trânsito em endpoints públicos ou remotos, sempre especifique o esquema https ao definir o campo address. Os endpoints de API do Google precisam usar https. Consulte Hosts e esquemas de back-end.
  • Cada back-end definido em x-google-api-management.backends e referenciado por um roteador de modelos precisa usar pathTranslation: CONSTANT_ADDRESS. O plano de gerenciamento rejeita configurações que usam pathTranslation: APPEND_PATH_TO_ADDRESS para back-ends de roteamento de modelos porque a tradução de caminho é ignorada no caminho de execução do roteador de modelos.
  • Os back-ends de roteamento de modelos não são compatíveis com as configurações de endpoint do VPC Service Controls ou do Private Service Connect (PSC). Todos os campos address de back-end precisam apontar para endpoints públicos regionais ou globais de modelos abertos de MaaS.

Resolução de referência do roteador

  • O nome do roteador referenciado pelo x-google-model-router de uma operação precisa corresponder a uma chave de roteador válida definida em ai.models.routing.routers.
  • O backend referenciado pelo defaultModel de um roteador precisa corresponder a um back-end válido definido em x-google-api-management.backends.
  • O backend referenciado por cada regra em um roteador precisa corresponder a um back-end válido definido em x-google-api-management.backends.

Conteúdo do roteador

  • Cada roteador precisa definir um defaultModel.
  • O defaultModel precisa incluir um campo backend válido.
  • O defaultModel precisa incluir um campo targetModel não vazio.
  • Cada entrada em rules precisa incluir um campo model preenchido. O valor de string default é reservado e não pode ser usado como o valor model de uma regra.
  • Cada entrada em rules precisa incluir um campo targetModel preenchido.
  • Os valores de model definidos em todas as regras de um único roteador precisam ser exclusivos. O plano de gerenciamento rejeita valores model duplicados no mesmo roteador.

Hosts e esquemas de back-end

O roteamento de modelos aceita apenas endpoints de API do Google como back-ends: nomes de host que terminam em .googleapis.com ou .vertexai.goog. O gateway se autentica em todos os back-ends referenciados por um único roteador (incluindo defaultModel.backend e o backend de cada regra) com um token de acesso do OAuth 2.0, que é válido em qualquer host de API do Google (consulte Outras Google Cloud APIs). O plano de gerenciamento rejeita configurações que violam as seguintes regras:

  • Cada back-end referenciado por um roteador precisa usar o esquema https.
  • Um roteador não pode misturar endpoints de API do Google com outros endpoints.

Os back-ends referenciados por um roteador podem estar em hosts diferentes (por exemplo, o endpoint global aiplatform.googleapis.com, endpoints regionais como us-central1-aiplatform.googleapis.com ou endpoints .vertexai.goog) e em projetos diferentes.

Validação do modelo de destino

  • A parte <provider> da string targetModel (google, openai ou anthropic) e o formato do identificador <provider>/<model> são validados no momento da criação da configuração (implantação). O plano de gerenciamento rejeita um targetModel que não está formatado como <provider>/<model> ou cujo provedor não é google, openai ou anthropic com um erro InvalidArgument: unsupported publisher durante a implantação.

Etapa 1: identificar os modelos de destino

Identifique os modelos de fundação de destino e os URLs de endpoint correspondentes da Agent Platform. Os modelos em um roteador podem usar diferentes endpoints da Agent Platform, por exemplo, o endpoint global (aiplatform.googleapis.com) e um endpoint regional (us-central1-aiplatform.googleapis.com).

Os caminhos de URL do endpoint variam de acordo com o provedor do modelo:

  • Google Gemini: usa o método :generateContent.
  • Anthropic Claude: usa o método :rawPredict.
  • OpenAI: usa o caminho do endpoint /endpoints/openapi/chat/completions.

A tabela a seguir lista os endpoints de MaaS usados no exemplo de especificação OpenAPI mais adiante nesta seção:

Modelo URL do endpoint
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

Substitua YOUR_PROJECT_ID pelo ID do projeto Google Cloud .

Etapa 2: configurar a especificação OpenAPI 3.x

Crie ou atualize sua especificação OpenAPI 3.x para definir os endpoints de back-end e as configurações de roteamento de modelos.

O exemplo a seguir demonstra uma especificação OpenAPI 3.0.3 que define dois roteadores de modelos distintos. Para evitar a rolagem horizontal, URLs de endereço de back-end longos usam a continuação de string de várias linhas entre aspas duplas do 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"

Propriedades de configuração

  1. backends: o objeto backends em x-google-api-management define todos os endpoints de modelo roteáveis. Cada nome de back-end representa um nome de modelo simbólico (por exemplo, gemini-35-flashlite) que contém o destino address. O campo backends é uma extensão atual da OpenAPI do Google.
  2. ai.models.routing: a configuração de roteamento de modelos fica em x-google-api-management como ai.models.routing, contendo um mapa de roteadores nomeados. Cada entrada de mapa define um roteador de roteamento de modelos, em que a chave representa o nome do roteador (por exemplo, gemini-claude-router) e o valor contém:
    • defaultModel: o destino do modelo de substituição obrigatório usado quando um payload de solicitação recebido não corresponde a nenhuma regra explícita. Ele compartilha a estrutura exata de uma entrada de regra, mas omite o campo de correspondência model. Para rotas compatíveis com a OpenAI, quando uma solicitação volta para defaultModel, o valor de targetModel é encaminhado como o atributo model de saída no corpo da solicitação enviado à plataforma de agentes.
    • rules: uma matriz opcional em que cada elemento mapeia uma string de modelo de payload do cliente para um back-end de destino e um modelo de destino.
  3. Propriedades da regra: cada entrada em rules (e em defaultModel) define as seguintes propriedades:
    • model (somente regras): o valor da string que corresponde ao atributo model no payload do comando JSON recebido do cliente. O roteador compara o valor model do payload recebido com essa string. Se nenhuma regra corresponder, o roteador vai selecionar o defaultModel. Para rotas compatíveis com a OpenAI (em que o back-end de destino é /openapi/chat/completions), essa string é encaminhada diretamente como o atributo model de saída no corpo da solicitação enviado à Agent Platform. Portanto, para rotas compatíveis com a OpenAI, o seletor model precisa ser um identificador de modelo de editor válido (por exemplo, openai/gpt-oss-120b-maas). O uso de um alias como gpt-oss resulta em um erro 400 Malformed publisher model da Agent Platform.
    • backend: o nome simbólico do back-end definido em x-google-api-management.backends para onde o gateway envia o comando.
    • targetModel: o identificador do modelo de destino formatado como <provider>/<model-id>. O roteador de modelos usa essa string para traduzir solicitações e respostas para o modelo de destino. O prefixo <provider> precisa ser exatamente google, openai ou anthropic. O <model-id> precisa ser um identificador válido de modelo de editor do Model Garden da Agent Platform. O gateway repete essa string no campo model da resposta retornada ao cliente. Exemplos de valores:
      • 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: para anexar um roteador de modelos a um caminho de operação de API, especifique o nome do roteador usando o atributo x-google-model-router. No exemplo anterior, uma solicitação POST enviada para /v1/chat/gemini-claude invoca gemini-claude-router, que encaminha o comando com base no nome do modelo especificado no payload JSON.

Etapa 3: criar e implantar a configuração da API

Crie uma configuração de API usando a especificação OpenAPI 3.x que você criou e implante a configuração na instância do gateway de API, conforme descrito em Como implantar uma API em um gateway.

O plano de gerenciamento do gateway de API processa a configuração de roteamento de modelos e ativa a camada de roteamento. Quando a implantação do gateway for concluída, ele estará pronto para receber solicitações de comando formatadas como payloads JSON compatíveis com a OpenAI.

Etapa 4: testar o comportamento de roteamento

Antes de testar o gateway, aguarde até que ele alcance o estado ACTIVE e recupere o URL dele:

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

No início do Acesso Antecipado do roteamento de modelos, os gateways de roteamento de modelos usavam um nome de host run.app. A partir de 3 de setembro de 2026, os novos gateways de roteamento de modelos poderão usar um nome de host padrão gateway.dev no formato https://GATEWAY_ID-PROJECT_NUMBER.REGION.gateway.dev, por exemplo, https://my-gateway-123456789012.us-central1.gateway.dev. O nome do host padrão é imutável e atribuído na criação. Seja qual for o formato atribuído (um nome de host run.app ou gateway.dev), o gateway vai manter esse formato permanentemente.

Teste o comportamento de roteamento do gateway usando curl para enviar solicitações de comando compatíveis com a OpenAI para o URL do gateway (https://GATEWAY_URL). Nos exemplos a seguir, $TOKEN representa um token de autenticação válido obtido usando qualquer um dos métodos descritos em Como escolher um método de autenticação.

Testar o roteamento de regras explícitas

Envie um comando solicitando o modelo 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."
      }
    ]
  }'

O envio da solicitação para /v1/chat/gemini-claude invoca gemini-claude-router. O atributo "model": "claude-opus-4-7" no payload JSON corresponde à regra explícita em gemini-claude-router, direcionando o gateway para rotear a solicitação para o back-end anthropic-claude-opus-47.

Testar o fallback do modelo padrão

Envie um comando especificando um nome de modelo sem correspondência para testar o roteamento de fallback:

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
  }'

O envio da solicitação para /v1/chat/gemini-claude invoca gemini-claude-router. Como o atributo "model": "unrecognized-model" não corresponde a nenhuma regra explícita, o gateway envia a solicitação para o defaultModel configurado do roteador, o back-end gemini-35-flashlite.

Testar caminho alternativo do roteador

Envie um comando solicitando o Gemini pelo endpoint do roteador secundário:

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."
      }
    ]
  }'

O envio da solicitação para /v1/chat/openai-gemini invoca openai-gemini-router. O atributo "model": "gemini-3.5-flash-lite" corresponde à regra explícita nesse roteador, direcionando o gateway para rotear a solicitação para o back-end gemini-35-flashlite. Um único back-end pode ser referenciado por vários roteadores. Nessa configuração, gemini-35-flashlite serve como um destino de regra explícito em openai-gemini-router e como o substituto defaultModel em gemini-claude-router.

Observabilidade

O roteador de modelos é instrumentado para que você possa verificar se o gateway está veiculando tráfego, inspecionar metadados por solicitação usando o Cloud Logging e diagnosticar falhas usando o Cloud Monitoring.

Cloud Logging

Cada solicitação roteada pelo gateway gera uma entrada no registro de solicitações padrão do gateway de API localizado no projeto do Google Cloud em:

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

Cada entrada de registro inclui os seguintes campos:

  • httpRequest.requestUrl, httpRequest.status, httpRequest.latency
  • api, apiConfig, apiMethod
  • backendRequest.hostname: o nome do host do back-end da plataforma de agente para o qual a solicitação foi enviada por proxy.
  • responseDetails: preenchido com uma categoria de erro de marca em falhas de roteamento de modelos (consulte Solução de problemas de falhas de roteamento de modelos).

Para encontrar solicitações recentes enviadas a um gateway específico, use o seguinte filtro de consulta do Cloud Logging:

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

Cloud Monitoring

A métrica padrão do gateway de API apigateway.googleapis.com/proxy/request_count (BETA) informa o volume de tráfego do gateway dividido por:

  • response_code_class: um de 2xx, 3xx, 4xx ou 5xx.
  • api_config: o nome da configuração da API que o gateway está usando.

Essa métrica permite verificar o volume geral de tráfego e as taxas de erro. As métricas específicas do roteador de modelos (como detalhamentos por roteador ou por modelo de destino) serão adicionadas em uma versão futura.

Para acompanhar a latência agregada de solicitações, crie uma métrica com base em registros usando o campo httpRequest.latency no registro de solicitações.

Solução de problemas de falhas no roteamento de modelos

Quando uma solicitação roteada pelo roteador de modelos falha, o campo responseDetails na entrada de registro de solicitação correspondente indica se a falha ocorreu na camada do roteador de modelos. O roteador de modelos mostra quatro categorias de marca:

Valor de responseDetails Significado Correção típica
model_router_application_error Não foi possível rotear a solicitação. Isso geralmente indica uma regra ausente, um payload com um valor model que não corresponde a nenhuma regra (sem um defaultModel configurado) ou um payload de solicitação inválido. Lado do cliente: verifique se o parâmetro model do payload corresponde a uma das strings rule.model na configuração do roteador ou se um substituto defaultModel está definido. Verifique se o corpo da solicitação é um JSON válido compatível com a OpenAI e se inclui explicitamente um atributo model. Durante o pré-lançamento público, um atributo model ausente no payload da solicitação é processado incorretamente em vez de ser rejeitado.
model_router_timeout O roteamento de modelos excedeu o tempo limite por solicitação. A solicitação pode ser muito grande ou complexa, ou pode haver um gargalo de capacidade. Verifique a complexidade da solicitação e as configurações de tempo limite em todos os back-ends. Se o problema persistir em payloads normais, entre em contato com o suporte doGoogle Cloud com o carimbo de data/hora da solicitação e uma amostra de registro.
model_router_upstream_error O modelo de destino upstream retornou um erro de HTTP para o gateway. Lado do serviço upstream: verifique o código de status e o payload do endpoint de serviço de destino da Agent Platform. Se isso for inesperado para solicitações válidas, abra um caso de suporte.
model_router_unavailable O roteamento de modelos não estava acessível pelo gateway devido a uma falha de transporte ou conectividade. Plataforma: abra um caso de suporte com o suporte doGoogle Cloud .

A seguir