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:
- 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. - 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. - 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.
- 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-managemente os blocos associados (backends,ai.models.routing.routers, roteadores individuais erules) 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 erroexpected map/list/string. - A extensão
x-google-api-managementprecisa conter um blocobackendsvá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-routersó pode ser especificada no nível da operação. O plano de gerenciamento rejeita explicitamente as definições dex-google-model-routercolocadas no nível do caminho ou da raiz (superior). - O bloco
ai.models.routing.routersprecisa ser definido dentro dex-google-api-managementsempre que uma operação fizer referência ax-google-model-router. - Não é possível especificar
x-google-model-routerex-google-backendna 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 usax-google-model-routerem outras operações na mesma especificação de API.
Verificação do método HTTP
- A extensão
x-google-model-routersó pode ser aplicada a operações que usam o método HTTPPOST. O plano de gerenciamento rejeita o roteamento de modelos em qualquer outro método HTTP (comoGET,PUTouDELETE).
Validade do back-end
- Cada back-end definido em
x-google-api-management.backendsprecisa incluir um campoaddressnão vazio. - O back-end
addressprecisa ser um URL válido que use o esquemahttpouhttps. Para proteger payloads de comando e credenciais de autenticação em trânsito em endpoints públicos ou remotos, sempre especifique o esquemahttpsao definir o campoaddress. Os endpoints de API do Google precisam usarhttps. Consulte Hosts e esquemas de back-end. - Cada back-end definido em
x-google-api-management.backendse referenciado por um roteador de modelos precisa usarpathTranslation: CONSTANT_ADDRESS. O plano de gerenciamento rejeita configurações que usampathTranslation: APPEND_PATH_TO_ADDRESSpara 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
addressde 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-routerde uma operação precisa corresponder a uma chave de roteador válida definida emai.models.routing.routers. - O
backendreferenciado pelodefaultModelde um roteador precisa corresponder a um back-end válido definido emx-google-api-management.backends. - O
backendreferenciado por cada regra em um roteador precisa corresponder a um back-end válido definido emx-google-api-management.backends.
Conteúdo do roteador
- Cada roteador precisa definir um
defaultModel. - O
defaultModelprecisa incluir um campobackendválido. - O
defaultModelprecisa incluir um campotargetModelnão vazio. - Cada entrada em
rulesprecisa incluir um campomodelpreenchido. O valor de stringdefaulté reservado e não pode ser usado como o valormodelde uma regra. - Cada entrada em
rulesprecisa incluir um campotargetModelpreenchido. - Os valores de
modeldefinidos em todas as regras de um único roteador precisam ser exclusivos. O plano de gerenciamento rejeita valoresmodelduplicados 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 stringtargetModel(google,openaiouanthropic) 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 umtargetModelque não está formatado como<provider>/<model>ou cujo provedor não égoogle,openaiouanthropiccom um erroInvalidArgument: unsupported publisherdurante 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
backends: o objetobackendsemx-google-api-managementdefine 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 destinoaddress. O campobackendsé uma extensão atual da OpenAPI do Google.ai.models.routing: a configuração de roteamento de modelos fica emx-google-api-managementcomoai.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ênciamodel. Para rotas compatíveis com a OpenAI, quando uma solicitação volta paradefaultModel, o valor detargetModelé encaminhado como o atributomodelde 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.
- Propriedades da regra: cada entrada em
rules(e emdefaultModel) define as seguintes propriedades:model(somente regras): o valor da string que corresponde ao atributomodelno payload do comando JSON recebido do cliente. O roteador compara o valormodeldo payload recebido com essa string. Se nenhuma regra corresponder, o roteador vai selecionar odefaultModel. Para rotas compatíveis com a OpenAI (em que o back-end de destino é/openapi/chat/completions), essa string é encaminhada diretamente como o atributomodelde saída no corpo da solicitação enviado à Agent Platform. Portanto, para rotas compatíveis com a OpenAI, o seletormodelprecisa ser um identificador de modelo de editor válido (por exemplo,openai/gpt-oss-120b-maas). O uso de um alias comogpt-ossresulta em um erro400 Malformed publisher modelda Agent Platform.backend: o nome simbólico do back-end definido emx-google-api-management.backendspara 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 exatamentegoogle,openaiouanthropic. 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 campomodelda resposta retornada ao cliente. Exemplos de valores:google/gemini-3.5-flash-litegoogle/gemini-2.5-proopenai/gpt-oss-120b-maasanthropic/claude-opus-4-7
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 atributox-google-model-router. No exemplo anterior, uma solicitaçãoPOSTenviada para/v1/chat/gemini-claudeinvocagemini-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.latencyapi,apiConfig,apiMethodbackendRequest.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 de2xx,3xx,4xxou5xx.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
- Revise a arquitetura e os conceitos de roteamento de modelos.
- Conheça as extensões da OpenAPI 3.x