Visão geral do roteamento de modelos

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

O roteamento de modelos move a lógica de roteamento para a borda da rede e se integra ao Vertex AI Model Garden para otimizações no mesmo host. Essa arquitetura remove o requisito de hospedar, escalonar e manter servidores proxy não gerenciados, reduzindo a sobrecarga operacional e os custos de infraestrutura.

Escopo e jornadas do usuário

O roteamento de modelos oferece suporte às seguintes jornadas principais do usuário:

  • Seleção de modelos: um desenvolvedor de IA usa modelos abertos do Model as a Service (MaaS) no Vertex AI Model Garden. Esses 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.
  • Roteamento de comandos: os aplicativos cliente enviam solicitações de comandos compatíveis com a OpenAI para o gateway, que encaminha as solicitações e traduz os 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 carga de manutenção associados à implantação de servidores proxy independentes.
  • Performance otimizada para a borda: inspecione comandos e encaminhe o tráfego na borda da rede, aproveitando a integração direta com os endpoints do Vertex AI Model Garden.
  • Interface de cliente padronizada: permita que os aplicativos cliente interajam com uma interface REST uniforme compatível com a OpenAI, enquanto enviam solicitações dinamicamente para diversos modelos de base.

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: expõem um endpoint de API padronizado que encaminha solicitações dinamicamente entre diferentes modelos de base (como Gemini Pro, Gemini Flash ou Anthropic Claude) com base nos parâmetros do 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 modelos oferece suporte ao roteamento com base exclusivamente na tag ou no nome do modelo (por exemplo, "model": "gemini-3.5-flash-lite") especificado no payload JSON de solicitações de cliente compatíveis com a OpenAI.

Arquitetura e fluxo de solicitações

O roteamento de modelos funciona 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 para o 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 recebido (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 selecionará o modelo padrão configurado.
  4. Transcodificação em tempo real: o gateway transcodifica a solicitação compatível com a OpenAI no esquema de previsão da Vertex AI de destino.
  5. Envio de back-end: o gateway envia a solicitação transcodificada para o endpoint do Vertex AI Model Garden designado e retorna a resposta do modelo ao cliente.

Performance 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 oferece suporte apenas ao roteamento para modelos MaaS pré-implantados hospedados no Vertex AI Model Garden em que todos os modelos referenciados por um único roteador compartilham o mesmo nome do 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 modelos 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 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.
  • Configurações mistas: uma especificação OpenAPI não pode conter uma combinação de operações de roteamento de modelos e não modelos. Todas as operações na especificação precisam usar o roteamento de modelos ou o roteamento de gateway padrão.
  • VPC Service Controls: os gateways de roteamento de modelos não oferecem suporte ao 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 oferece suporte ao streaming de respostas (eventos enviados pelo servidor), mas não oferece suporte ao streaming do lado da solicitação, gRPC, WebSockets ou Gemini Live.
  • Modalidades com suporte: durante a prévia pública, o roteamento de modelos assume solicitações de comandos baseadas em texto formatadas como payloads JSON compatíveis com a OpenAI e rotas com base exclusivamente na tag ou no nome model no payload.
  • Campos de payload obrigatórios: o payload da solicitação JSON recebida precisa incluir um atributo model. Durante a prévia pública, se o campo model estiver ausente do payload da solicitação do cliente, o gateway 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 do ambiente 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 modelos:
    • Tempo limite máximo: o gateway aplica 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 do gateway for escalonada para zero durante períodos de inatividade, a solicitação inicial poderá apresentar 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, como /eventlog, caminhos que começam com /_ah/ ou determinados caminhos que terminam em z (para evitar conflitos, evite usar nomes de caminho que terminam em z).
    • Decodificação de caracteres de URL: o gateway decodifica automaticamente determinados caracteres codificados em URLs de solicitação antes de processar a solicitação (por exemplo, %41 é decodificado como A).

A seguir