Panoramica del routing dei modelli

Il routing dei modelli per API Gateway è un livello di gestione del traffico gestito che accetta richieste di prompt compatibili con OpenAI, le transcodifica durante il trasferimento e le indirizza a modelli Gemini Enterprise Agent Platform specifici. Il routing dei modelli funge da alternativa gestita ai proxy lato client come LiteLLM, fornendo un'infrastruttura centralizzata per gestire il ciclo di vita degli agenti AI.

Il routing dei modelli sposta la logica di routing all'edge della rete e si integra con Model Garden di Agent Platform per le ottimizzazioni dello stesso host. Questa architettura elimina il requisito di ospitare, scalare e gestire server proxy non gestiti, riducendo i costi operativi e dell'infrastruttura.

Ambito e percorsi degli utenti

Il routing dei modelli supporta i seguenti percorsi utente principali:

  • Selezione del modello: uno sviluppatore di AI utilizza modelli aperti di Model as a Service (MaaS) in Agent Platform Model Garden. Si tratta dei modelli delle famiglie Gemini, Anthropic Claude o OpenAI GPT.
  • Creazione delle specifiche: uno sviluppatore di AI crea o aggiorna una configurazione del router di modelli all'interno di una specifica OpenAPI 3.x per fare riferimento ai modelli di cui è stato eseguito il deployment.
  • Deployment del gateway: uno sviluppatore di AI esegue il deployment di una configurazione API e di un'istanza API Gateway utilizzando la specifica OpenAPI creata.
  • Routing dei prompt: le applicazioni client inviano richieste di prompt compatibili con OpenAI al gateway, che esegue il routing delle richieste e traduce i payload in base al nome del modello specificato nel payload JSON.

Le versioni future di API Gateway prevedono di supportare ulteriori percorsi utente.

Vantaggi del routing dei modelli

L'implementazione del routing dei modelli in API Gateway offre i seguenti vantaggi:

  • Gestione centralizzata: consolida la gestione del traffico AI in un unico gateway gestito, sostituendo le configurazioni di routing lato client frammentate.
  • Overhead operativo ridotto: elimina i costi dell'infrastruttura e l'onere di manutenzione associati al deployment di server proxy autonomi.
  • Rendimento ottimizzato per l'edge: ispeziona i prompt e indirizza il traffico all'edge della rete, sfruttando l'integrazione diretta con gli endpoint di Agent Platform Model Garden.
  • Interfaccia client standardizzata: consente alle applicazioni client di interagire con un'interfaccia REST uniforme compatibile con OpenAI, inviando dinamicamente le richieste a diversi modelli di base sottostanti.

Buyer persona e casi d'uso

Il routing dei modelli soddisfa i requisiti delle seguenti buyer persona:

  • Platform Engineer: fornisci una soluzione di infrastruttura gestita per sostituire la logica di routing lato client in tutte le implementazioni di AI aziendale.
  • Sviluppatori di AI: espongono un endpoint API standardizzato che instrada dinamicamente le richieste tra diversi modelli di base (come Gemini Pro, Gemini Flash o Anthropic Claude) in base ai parametri del payload della richiesta.
  • Amministratori della governance: applicano criteri di accesso centralizzati (come autenticazione e quote) e monitorano il volume complessivo del traffico AI in un'organizzazione.

Casi d'uso supportati

Durante l'anteprima pubblica, il routing dei modelli supporta il routing basato esclusivamente sul tag o sul nome del modello (ad esempio "model": "gemini-3.5-flash-lite") specificato nel payload JSON delle richieste client compatibili con OpenAI.

Architettura e flusso delle richieste

Il routing dei modelli funziona come un livello di routing gestito all'interno del data plane di API Gateway. Quando un'applicazione client invia una richiesta di prompt compatibile con OpenAI al gateway, si verifica la seguente sequenza:

  1. Intercettazione delle richieste: il gateway intercetta la richiesta POST in entrata (ad esempio, POST /chat/completions).
  2. Ispezione del payload: il router dei modelli esamina l'attributo model all'interno del payload JSON in entrata (ad esempio, {"model": "claude-opus-4-7", "messages": [...]}).
  3. Valutazione delle regole: il router confronta la stringa model con le regole di routing definite nella specifica OpenAPI. Se nessuna regola corrisponde, il router seleziona il modello predefinito configurato.
  4. Transcodifica in volo: il gateway transcodifica la richiesta compatibile con OpenAI nello schema di previsione di Agent Platform di destinazione.
  5. Invio backend: il gateway invia la richiesta transcodificata all'endpoint Agent Platform Model Garden designato e restituisce la risposta del modello al client.

Prestazioni e limitazioni

Prima di implementare il routing dei modelli, esamina i seguenti vincoli tecnici:

  • Vincoli host: il routing dei modelli supporta il routing solo verso modelli MaaS pre-deployment ospitati in Agent Platform Model Garden, dove tutti i modelli a cui fa riferimento un singolo router condividono lo stesso nome host (ad esempio, l'endpoint globale aiplatform.googleapis.com o un singolo endpoint regionale come us-central1-aiplatform.googleapis.com).
  • Requisiti delle specifiche: il routing dei modelli richiede una specifica OpenAPI 3.x e le estensioni OpenAPI 3.x di API Gateway corrispondenti. Le specifiche OpenAPI 2.0 (Swagger) non sono supportate.
  • Aggiornamenti del gateway: non puoi aggiornare un gateway esistente di cui è stato eseguito il deployment senza il routing dei modelli per attivarlo, né puoi aggiornare un gateway di cui è stato eseguito il deployment con il routing dei modelli per disattivarlo o rimuoverlo. Per cambiare modalità di routing, devi creare ed eseguire il deployment di una nuova configurazione API e di una nuova istanza del gateway.
  • Configurazioni miste: una specifica OpenAPI non può contenere un mix di operazioni di routing del modello e non del modello. Tutte le operazioni nella specifica devono utilizzare il routing del modello o il routing del gateway standard.
  • Controlli di servizio VPC: i gateway di routing dei modelli non supportano i Controlli di servizio VPC. Non puoi utilizzare i perimetri dei Controlli di servizio VPC con le istanze API Gateway che abilitano il routing dei modelli.
  • Streaming e protocolli non supportati: il routing dei modelli supporta lo streaming delle risposte (eventi inviati dal server), ma non supporta lo streaming lato richiesta, gRPC, WebSocket o Gemini Live.
  • Modalità supportate: durante l'anteprima pubblica, il routing dei modelli presuppone richieste di prompt basate su testo formattate come payload JSON compatibili con OpenAI e il routing si basa esclusivamente sul tag o sul nome model nel payload.
  • Campi del payload obbligatori: il payload della richiesta JSON in entrata deve includere un attributo model. Durante l'anteprima pubblica, se il campo model non è presente nel payload della richiesta del client, il gateway elabora la richiesta in modo errato anziché rifiutarla con un errore. Assicurati sempre che le richieste client specifichino un campo model nel payload JSON.
  • Limitazioni di runtime: i limiti e i comportamenti standard del servizio di hosting dell'infrastruttura del gateway si applicano agli endpoint di routing del modello:
    • Timeout massimo: il gateway applica un timeout massimo della richiesta di 3600 secondi (1 ora), che si applica alle richieste di streaming a lunga esecuzione.
    • Latenza di avvio a freddo: se la tua istanza del gateway viene scalata a zero durante i periodi di inattività, la richiesta iniziale potrebbe subire una latenza di avvio a freddo, che può influire sui percorsi di inferenza dell'AI sensibili alla latenza.
    • Percorsi URL riservati: non puoi utilizzare percorsi URL riservati che iniziano con /_ah/ o determinati percorsi che terminano con z (per evitare conflitti, evita di utilizzare nomi di percorso che terminano con z).
    • Decodifica dei caratteri URL: il gateway decodifica automaticamente alcuni caratteri codificati negli URL delle richieste prima di elaborare la richiesta (ad esempio, %41 viene decodificato in A).

Passaggi successivi