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 pré-requisitos a seguir:

  1. Verificar as permissões do IAM: confira se você tem acesso ao plano de gerenciamento do gateway de API e ao Model Garden da Vertex AI. É necessário 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 de API, seja 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 de API, precisa receber o papel de usuário da Vertex AI (roles/aiplatform.user) para acessar os modelos de destino.
  2. Verificar 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, na sigla em inglês) no Model Garden da Vertex AI. Todos os modelos referenciados por um único roteador precisam compartilhar o mesmo nome de host. Escolha o endpoint global (aiplatform.googleapis.com) ou um único endpoint regional (por exemplo, us-central1-aiplatform.googleapis.com) para cada modelo referenciado nesse roteador.
  3. Verificar a qualificação para implantação do gateway: não é possível atualizar um gateway implantado sem o roteamento de modelos para ativar o roteamento de modelos, nem atualizar um gateway implantado com o roteamento de modelos para desativar ou remover o roteamento de modelos. Para mudar os modos de roteamento, é necessário criar e implantar uma nova configuração de API e uma instância de gateway.
  4. Verificar o VPC Service Controls e a compatibilidade de endpoints: os gateways de roteamento de modelos não oferecem suporte a configurações de endpoints 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 pelos perímetros do VPC Service Controls e se os modelos usam endpoints regionais ou globais públicos.

Validação de configuração

Ao implantar uma configuração de API, o plano de gerenciamento do gateway de API valida a especificação da 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 local

  • A extensão x-google-api-management e os blocos associados a ela (backends, ai.models.routing.routers, roteadores individuais e rules) precisam ser 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 especificações da OpenAPI 3.x (não é compatível com a 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 na raiz (superior).
  • O bloco ai.models.routing.routers precisa ser definido dentro de x-google-api-management sempre que uma operação referenciar 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 da OpenAPI não pode conter uma combinação de operações de roteamento de modelos e não modelos. Não é possível especificar extensões de roteamento padrão (como x-google-backend) em algumas operações ao usar 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 address do back-end precisa ser um URL válido usando o esquema http ou https. Para proteger payloads de comandos e credenciais de autenticação em trânsito em endpoints públicos ou remotos, sempre especifique o esquema https ao definir o campo address.
  • 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 oferecem suporte a configurações de endpoints do VPC Service Controls ou do Private Service Connect (PSC). Todos os campos address de back-end precisam apontar para endpoints de modelos abertos de MaaS regionais ou globais públicos.

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 não vazio. O valor de string default está reservado e não pode ser usado como um valor model de regra.
  • Cada entrada em rules precisa incluir um campo targetModel não vazio.
  • Os valores model definidos em todas as regras em um único roteador precisam ser exclusivos. O plano de gerenciamento rejeita valores model duplicados no mesmo roteador.

Consistência do host e do esquema de back-end

  • Todos os back-ends referenciados por um único roteador (incluindo defaultModel.backend e o backend de cada regra) precisam compartilhar o mesmo nome de host e esquema de URL. O plano de gerenciamento rejeita configurações com nomes de host diferentes ou esquemas inconsistentes (http versus https) no mesmo roteador, garantindo que o roteador envie todas as solicitações para um endpoint de serviço upstream consistente.

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 modelos de destino

Identifique os modelos de base de destino e os URLs de endpoints da Vertex AI correspondentes. Todos os modelos roteáveis em um roteador precisam compartilhar um único nome de host (para modelos abertos de MaaS, esse nome de host é 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 da 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 Google Cloud projeto.

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

Crie ou atualize a especificação da 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 da OpenAPI 3.0.3 que define dois roteadores de modelos distintos. Para evitar a rolagem horizontal, os URLs de endereço de back-end longos usam a continuação de string de várias linhas com aspas duplas 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 modelos roteáveis. Cada nome de back-end representa um nome de modelo simbólico (por exemplo, gemini-35-flashlite) que contém o address de destino. O campo backends é uma extensão da OpenAPI do Google.
  2. ai.models.routing: a configuração de roteamento de modelos reside em x-google-api-management como ai.models.routing, contendo um mapa de roteadores nomeados. Cada item no mapa define um roteador 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 necessário usado quando um payload de solicitação recebida 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 à Vertex AI.
    • 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 de regra: cada entrada em rules (e o defaultModel) define as seguintes propriedades:
    • model (somente regras): o valor de string correspondente ao atributo model no payload de comando JSON recebido do cliente. O roteador compara o valor model do payload recebido a essa string. Se nenhuma regra corresponder, o roteador 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 à Vertex AI. Portanto, para rotas compatíveis com a OpenAI, o 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 Vertex AI.
    • backend: o nome simbólico do back-end definido em x-google-api-management.backends em que 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 de modelo de editor do Model Garden da Vertex AI válido. O gateway ecoa essa string de volta no campo model da resposta retornada ao cliente. Os valores de exemplo incluem:
      • 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 roteia o comando com base no nome do modelo especificado no payload JSON.

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

Crie uma configuração de API usando a especificação da OpenAPI 3.x criada 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 comandos 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 atinja o estado ACTIVE e recupere o URL:

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

Durante o pré-lançamento público, os gateways de roteamento de modelos retornam um nome de host *.run.app. Recupere o nome do host somente depois que o gateway estiver ACTIVE. O valor informado enquanto o gateway ainda está sendo criado não é o URL final.

Teste o comportamento de roteamento do gateway usando curl para enviar solicitações de comandos 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 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 não correspondente 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 o caminho do roteador alternativo

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 defaultModel de fallback em gemini-claude-router.

Observabilidade

O roteador de modelos é instrumentado para que você possa verificar se o gateway está disponibilizando tráfego, inspecionar metadados por solicitação usando Cloud Logging e diagnosticar falhas usando 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 em your Google Cloud project 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 Vertex AI para o qual a solicitação foi encaminhada por proxy.
  • responseDetails: preenchido com uma categoria de erro de marca em falhas do roteador de modelos (consulte Solução de problemas de falhas do roteador de modelos logo abaixo).

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 de API que o gateway está usando.

Essa métrica permite verificar o volume geral de tráfego e as taxas de erro. 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 da solicitação, é possível criar uma métrica com base em registros do campo httpRequest.latency no registro de solicitações.

Solução de problemas de falhas do roteador 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 apresenta 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 que contém um valor model que não corresponde a nenhuma regra (sem um defaultModel configurado) ou um payload de solicitação malformado. 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 fallback defaultModel está definido. Verifique se o corpo da solicitação é um JSON válido compatível com a OpenAI e 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 roteador 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 Google Cloud suporte com o carimbo de data/hora da solicitação e um exemplo de registro.
model_router_upstream_error O modelo de destino upstream retornou um erro 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 Vertex AI. Se isso for inesperado para solicitações válidas, abra um caso de suporte.
model_router_unavailable Não foi possível acessar o roteador de modelos do gateway devido a uma falha de transporte ou conectividade. Lado da plataforma: abra um caso de suporte com o Google Cloud suporte.

A seguir