Visão geral do roteamento de modelos

O roteamento de modelos para o gateway de API é uma camada gerenciada de gerenciamento de tráfego que aceita solicitações de comandos compatíveis com a OpenAI, as transcodifica em trânsito e as encaminha para modelos específicos da Gemini Enterprise Agent Platform. O roteamento de modelos funciona como uma alternativa gerenciada a proxies do lado do cliente, como o LiteLLM, fornecendo infraestrutura centralizada para gerenciar o ciclo de vida dos agentes de IA.

O roteamento de modelo move a lógica de roteamento para a borda da rede e se integra ao Model Garden da Agent Platform para otimizações no mesmo host. Essa arquitetura elimina a necessidade de hospedar, escalonar e manter servidores proxy não gerenciados, reduzindo o overhead operacional e os custos de infraestrutura.

Escopo e jornadas do usuário

O encaminhamento de modelo é compatível com as seguintes jornadas principais do usuário:

  • Seleção de modelos: um desenvolvedor de IA usa modelos abertos do Model as a Service (MaaS) no Model Garden da Agent Platform. São modelos das famílias Gemini, Anthropic Claude ou OpenAI GPT.
  • Criação de especificações: um desenvolvedor de IA cria ou atualiza uma configuração de roteador de modelo em uma especificação OpenAPI 3.x para referenciar os modelos implantados.
  • Implantação do gateway: um desenvolvedor de IA implanta uma configuração de API e uma instância do gateway de API usando a especificação OpenAPI criada.
  • Encaminhamento de comandos: os aplicativos cliente enviam solicitações de comandos compatíveis com a OpenAI para o gateway, que encaminha solicitações e traduz payloads com base no nome do modelo especificado no payload JSON.

As versões futuras do gateway de API vão oferecer suporte a mais jornadas do usuário.

Benefícios do roteamento de modelos

A implementação do roteamento de modelos no gateway de API oferece as seguintes vantagens:

  • Gerenciamento centralizado: consolide o gerenciamento de tráfego de IA em um único gateway gerenciado, substituindo as configurações de roteamento fragmentadas do lado do cliente.
  • Redução da sobrecarga operacional: elimine os custos de infraestrutura e a sobrecarga de manutenção associados à implantação de servidores proxy autônomos.
  • Performance otimizada para a borda: inspecione comandos e direcione o tráfego na borda da rede, aproveitando a integração direta com os endpoints do Model Garden da Agent Platform.
  • Interface de cliente padronizada: permite que aplicativos cliente interajam com uma interface REST uniforme compatível com a OpenAI enquanto enviam solicitações dinamicamente para diversos modelos de fundação subjacentes.

Personas e casos de uso

O roteamento de modelos atende aos requisitos das seguintes personas:

  • Engenheiros de plataforma: provisionam uma solução de infraestrutura gerenciada para substituir a lógica de roteamento do lado do cliente em implantações de IA corporativa.
  • Desenvolvedores de IA: exponha um endpoint de API padronizado que roteia dinamicamente solicitações entre diferentes modelos de fundação (como Gemini Pro, Gemini Flash ou Anthropic Claude) com base nos parâmetros de payload da solicitação.
  • Administradores de governança: aplicam políticas de acesso centralizadas (como autenticação e cotas) e monitoram o volume geral de tráfego de IA em uma organização.

Casos de uso

Durante a prévia pública, o roteamento de modelo é compatível com o roteamento baseado exclusivamente na tag ou no nome do modelo (por exemplo, "model": "gemini-3.5-flash-lite") especificado no payload JSON de solicitações de clientes compatíveis com a OpenAI.

Arquitetura e fluxo de solicitação

O roteamento de modelos opera como uma camada de roteamento gerenciada no plano de dados do gateway de API. Quando um aplicativo cliente envia uma solicitação de comando compatível com a OpenAI ao gateway, ocorre a seguinte sequência:

  1. Interceptação de solicitações: o gateway intercepta a solicitação POST recebida (por exemplo, POST /chat/completions).
  2. Inspeção de payload: o roteador de modelo inspeciona o atributo model no payload JSON de entrada (por exemplo, {"model": "claude-opus-4-7", "messages": [...]}).
  3. Avaliação de regras: o roteador compara a string model com as regras de roteamento definidas na especificação OpenAPI. Se nenhuma regra corresponder, o roteador vai selecionar o modelo padrão configurado.
  4. Transcodificação em trânsito: o gateway transcodifica a solicitação compatível com a OpenAI no esquema de previsão da Agent Platform de destino.
  5. Envio de back-end: o gateway envia a solicitação transcodificada ao endpoint designado do Model Garden da Agent Platform e retorna a resposta do modelo ao cliente.

Desempenho e limitações

Antes de implementar o roteamento de modelos, revise as seguintes restrições técnicas:

  • Restrições de host: o roteamento de modelos só é compatível com o roteamento para modelos MaaS pré-implantados hospedados no Model Garden da Agent Platform, em que todos os modelos referenciados por um único roteador compartilham o mesmo nome de host (por exemplo, o endpoint global aiplatform.googleapis.com ou um único endpoint regional, como us-central1-aiplatform.googleapis.com).
  • Requisitos de especificação: o roteamento de modelo exige uma especificação OpenAPI 3.x e as extensões correspondentes do gateway de API OpenAPI 3.x. As especificações OpenAPI 2.0 (Swagger) não são compatíveis.
  • Atualizações de gateway: não é possível atualizar um gateway implantado sem o roteamento de modelo para ativar esse recurso. Também não é possível atualizar um gateway implantado com o roteamento de modelo 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.
  • Configurações mistas: uma especificação OpenAPI não pode conter uma combinação de operações de roteamento de modelo e não modelo. Todas as operações na especificação precisam usar o roteamento do modelo ou o roteamento padrão do gateway.
  • VPC Service Controls: os gateways de roteamento de modelos não são compatíveis com o VPC Service Controls. Não é possível usar perímetros do VPC Service Controls com instâncias do gateway de API que ativam o roteamento de modelos.
  • Streaming e protocolos não compatíveis: o roteamento de modelos é compatível com o streaming de respostas (eventos enviados pelo servidor), mas não com o streaming do lado da solicitação, gRPC, WebSockets ou Gemini Live.
  • Modalidades compatíveis: durante a prévia pública, o roteamento de modelos pressupõe solicitações de comandos baseadas em texto formatadas como payloads JSON compatíveis com a OpenAI e roteia com base exclusivamente na tag ou no nome model no payload.
  • Campos obrigatórios do payload: o payload da solicitação JSON recebida precisa incluir um atributo model. Durante a prévia pública, se o campo model estiver faltando no payload da solicitação do cliente, o gateway vai processar a solicitação incorretamente em vez de rejeitá-la com um erro. Sempre verifique se as solicitações do cliente especificam um campo model no payload JSON.
  • Limitações de tempo de execução: os limites e comportamentos padrão do serviço de infraestrutura de hospedagem de gateway se aplicam aos endpoints de roteamento de modelo:
    • Tempo limite máximo: o gateway impõe um tempo limite máximo de solicitação de 3.600 segundos (1 hora), que se aplica a solicitações de streaming de longa duração.
    • Latência de inicialização a frio: se a instância de gateway for escalonada para zero durante períodos de inatividade, a solicitação inicial poderá sofrer latência de inicialização a frio, o que pode afetar caminhos de inferência de IA sensíveis à latência.
    • Caminhos de URL reservados: não é possível usar caminhos de URL reservados que começam com /_ah/ ou terminam com z. Para evitar conflitos, não use nomes de caminhos que terminem com z.
    • Decodificação de caracteres de URL: o gateway decodifica automaticamente alguns caracteres codificados em URLs de solicitação antes de processar a solicitação (por exemplo, %41 é decodificado para A).

A seguir