Configurare il routing dei modelli

Questa pagina descrive come configurare, eseguire il deployment e testare il routing dei modelli in API Gateway utilizzando le specifiche OpenAPI 3.x.

Prima di iniziare

Prima di configurare il routing dei modelli, verifica che il tuo ambiente soddisfi i seguenti prerequisiti:

  1. Controlla le autorizzazioni IAM: verifica di avere accesso al piano di gestione di API Gateway e a Model Garden di Vertex AI. Devi disporre del ruolo di amministratore di API Gateway (roles/apigateway.admin) per creare configurazioni API e gateway. Inoltre, al account di servizio utilizzato dal gateway API, ovvero il account di servizio Compute Engine predefinito o un account di servizio gestito dall'utente specificato durante la creazione della configurazione API, deve essere concesso il ruolo di utente di Vertex AI (roles/aiplatform.user) per accedere ai modelli di destinazione.
  2. Controlla la disponibilità dei modelli e l'accesso agli endpoint: verifica che i modelli instradabili siano modelli open pre-deployment per Model as a Service (MaaS) in Model Garden di Vertex AI. Tutti i modelli a cui fa riferimento un singolo router devono condividere esattamente lo stesso nome host. Scegli l'endpoint globale (aiplatform.googleapis.com) o un singolo endpoint regionale (ad esempio us-central1-aiplatform.googleapis.com) per ogni modello a cui fa riferimento il router.
  3. Controlla l'idoneità al deployment del gateway: non puoi aggiornare un gateway esistente di cui è stato eseguito il deployment senza il routing dei modelli per abilitare il routing dei modelli, né puoi aggiornare un gateway di cui è stato eseguito il deployment con il routing dei modelli per disabilitare o rimuovere il routing dei modelli. Per cambiare modalità di routing, devi creare ed eseguire il deployment di una nuova configurazione API e di un'istanza del gateway.
  4. Controlla i Controlli di servizio VPC e la compatibilità degli endpoint: i gateway di routing dei modelli non supportano le configurazioni degli endpoint dei Controlli di servizio VPC o di Private Service Connect (PSC). Verifica che il progetto di destinazione e le istanze di API Gateway non siano limitati dai perimetri dei Controlli di servizio VPC e che i modelli utilizzino endpoint regionali o globali pubblici.

Convalida della configurazione

Quando esegui il deployment di una configurazione API, il piano di gestione di API Gateway convalida la specifica OpenAPI. Il piano di gestione rifiuta le configurazioni non valide durante il deployment con un errore di convalida informativo. La procedura di convalida applica le seguenti regole:

Controlli strutturali e di posizione

  • L'estensione x-google-api-management e i relativi blocchi (backends, ai.models.routing.routers, singoli router e rules) devono essere ben formati. Le chiavi devono corrispondere ai tipi di dati previsti (mappa, elenco o stringa). Il piano di gestione rifiuta le mancate corrispondenze dei tipi con un errore expected map/list/string.
  • L'estensione x-google-api-management deve contenere un blocco backends valido quando il routing dei modelli è abilitato.
  • L'estensione x-google-model-router è supportata solo nelle specifiche OpenAPI 3.x (non è supportata in OpenAPI 2.0 / Swagger).
  • L'estensione x-google-model-router può essere specificata solo a livello di operazione. Il piano di gestione rifiuta esplicitamente le definizioni x-google-model-router inserite a livello di percorso o a livello di radice (superiore).
  • Il blocco ai.models.routing.routers deve essere definito all'interno di x-google-api-management ogni volta che un'operazione fa riferimento a x-google-model-router.
  • Non puoi specificare sia x-google-model-router che x-google-backend nella stessa operazione API.
  • Una specifica OpenAPI non può contenere un mix di operazioni di routing dei modelli e non di routing dei modelli. Non puoi specificare estensioni di routing standard (come x-google-backend) in alcune operazioni mentre utilizzi x-google-model-router in altre operazioni all'interno della stessa specifica API.

Controllo del metodo HTTP

  • L'estensione x-google-model-router può essere applicata solo alle operazioni che utilizzano il metodo HTTP POST. Il piano di gestione rifiuta il routing dei modelli su qualsiasi altro metodo HTTP (ad esempio GET, PUT o DELETE).

Validità del backend

  • Ogni backend definito in x-google-api-management.backends deve includere un campo address non vuoto.
  • L' address del backend deve essere un URL valido che utilizza lo schema http o https. Per proteggere i payload dei prompt e le credenziali di autenticazione in transito su endpoint pubblici o remoti, specifica sempre lo schema https quando definisci il campo address.
  • Ogni backend definito in x-google-api-management.backends e a cui fa riferimento un router di modelli deve utilizzare pathTranslation: CONSTANT_ADDRESS. Il piano di gestione rifiuta le configurazioni che utilizzano pathTranslation: APPEND_PATH_TO_ADDRESS per i backend di routing dei modelli perché la traduzione del percorso viene ignorata nel percorso di runtime del router di modelli.
  • I backend di routing dei modelli non supportano le configurazioni degli endpoint dei Controlli di servizio VPC o di Private Service Connect (PSC). Tutti i campi address del backend devono rimandare a endpoint di modelli open MaaS regionali o globali pubblici.

Risoluzione dei riferimenti del router

  • Il nome del router a cui fa riferimento x-google-model-router di un'operazione deve corrispondere a una chiave del router valida definita in ai.models.routing.routers.
  • Il backend a cui fa riferimento defaultModel di un router deve corrispondere a un backend valido definito in x-google-api-management.backends.
  • Il backend a cui fa riferimento ogni regola in un router deve corrispondere a un backend valido definito in x-google-api-management.backends.

Contenuti del router

  • Ogni router deve definire un defaultModel.
  • defaultModel deve includere un campo backend valido.
  • defaultModel deve includere un campo targetModel non vuoto.
  • Ogni voce in rules deve includere un campo model non vuoto. Il valore della stringa default è riservato e non può essere utilizzato come valore model di una regola.
  • Ogni voce in rules deve includere un campo targetModel non vuoto.
  • I valori model definiti in tutte le regole all'interno di un singolo router devono essere univoci. Il piano di gestione rifiuta i valori model duplicati all'interno dello stesso router.

Coerenza di host e schema del backend

  • Tutti i backend a cui fa riferimento un singolo router (inclusi defaultModel.backend e backend di ogni regola) devono condividere lo stesso nome host e lo stesso schema URL. Il piano di gestione rifiuta le configurazioni con nomi host diversi o schemi incoerenti (http rispetto a https) all'interno dello stesso router, assicurandosi che il router invii tutte le richieste a un endpoint di servizio upstream coerente.

Convalida del modello di destinazione

  • La parte <provider> della stringa targetModel (google, openai o anthropic) e il formato dell'identificatore <provider>/<model> vengono convalidati al momento della creazione della configurazione (deployment). Il piano di gestione rifiuta un targetModel non formattato come <provider>/<model> o il cui provider non è google, openai o anthropic con un errore InvalidArgument: unsupported publisher durante il deployment.

Passaggio 1: identifica i modelli di destinazione

Identifica i modelli di base di destinazione e i relativi URL degli endpoint di Vertex AI. Tutti i modelli instradabili all'interno di un router devono condividere un singolo nome host (per i modelli open MaaS, questo nome host è aiplatform.googleapis.com).

I percorsi degli URL degli endpoint variano in base al provider del modello:

  • Google Gemini: utilizza il metodo :generateContent.
  • Anthropic Claude: utilizza il metodo :rawPredict.
  • OpenAI: utilizza il percorso dell'endpoint /endpoints/openapi/chat/completions.

La tabella seguente elenca gli endpoint MaaS utilizzati nell'esempio di specifica OpenAPI più avanti in questa sezione:

Modello URL 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

Sostituisci YOUR_PROJECT_ID con l' Google Cloud ID progetto.

Passaggio 2: configura la specifica OpenAPI 3.x

Crea o aggiorna la specifica OpenAPI 3.x per definire gli endpoint di backend e le configurazioni di routing dei modelli.

L'esempio seguente mostra una specifica OpenAPI 3.0.3 che definisce due router di modelli distinti. Per evitare lo scorrimento orizzontale, gli URL degli indirizzi di backend lunghi utilizzano la continuazione di stringhe multilinea con virgolette doppie 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"

Proprietà di configurazione

  1. backends: l'oggetto backends in x-google-api-management definisce tutti gli endpoint dei modelli instradabili. Ogni nome di backend rappresenta un nome di modello simbolico (ad esempio gemini-35-flashlite) contenente l'address di destinazione. Il campo backends è un'estensione OpenAPI di Google esistente.
  2. ai.models.routing: la configurazione di routing dei modelli si trova in x-google-api-management come ai.models.routing e contiene una mappa di router denominati. Ogni voce della mappa definisce un router di modelli, dove la chiave rappresenta il nome del router (ad esempio gemini-claude-router) e il valore contiene:
    • defaultModel: la destinazione del modello di fallback obbligatoria utilizzata quando un payload di richiesta in entrata non corrisponde a nessuna regola esplicita. Condivide la struttura esatta di una voce di regola, ma omette il campo di corrispondenza model. Per le route compatibili con OpenAI, quando una richiesta esegue il fallback a defaultModel, il valore di targetModel viene inoltrato come attributo model in uscita nel corpo della richiesta inviata a Vertex AI.
    • rules: un array facoltativo in cui ogni elemento mappa una stringa del modello del payload del client a un backend di destinazione e a un modello di destinazione.
  3. Proprietà delle regole: ogni voce in rules (e defaultModel) definisce le seguenti proprietà:
    • model (solo regole): il valore della stringa corrispondente all'attributo model all'interno del payload del prompt JSON in entrata del client. Il router confronta il valore model del payload in entrata con questa stringa. Se nessuna regola corrisponde, il router seleziona defaultModel. Per le route compatibili con OpenAI (dove il backend di destinazione è /openapi/chat/completions), questa stringa viene inoltrata direttamente come attributo model in uscita nel corpo della richiesta inviata a Vertex AI. Pertanto, per le route compatibili con OpenAI, il selettore model deve essere un identificatore di modello del publisher valido (ad esempio openai/gpt-oss-120b-maas); l'utilizzo di un alias come gpt-oss genera un errore 400 Malformed publisher model da Vertex AI.
    • backend: il nome del backend simbolico definito in x-google-api-management.backends in cui il gateway invia il prompt.
    • targetModel: l'identificatore del modello di destinazione formattato come <provider>/<model-id>. Il router di modelli utilizza questa stringa per tradurre le richieste e le risposte per il modello di destinazione. Il prefisso <provider> deve essere esattamente google, openai, o anthropic. Il <model-id> deve essere un identificatore di modello del publisher di Model Garden di Vertex AI valido. Il gateway ripete questa stringa nel campo model della risposta restituita al client. I valori di esempio includono:
      • 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: per collegare un router di modelli a un percorso di operazione API, specifica il nome del router utilizzando l'attributo x-google-model-router. Nell'esempio precedente, una richiesta POST inviata a /v1/chat/gemini-claude richiama gemini-claude-router, che instrada il prompt in base al nome del modello specificato nel payload JSON.

Passaggio 3: crea ed esegui il deployment della configurazione API

Crea una configurazione API utilizzando la specifica OpenAPI 3.x creata ed esegui il deployment della configurazione nell'istanza di API Gateway come descritto in Eseguire il deployment di un'API in un gateway.

Il piano di gestione di API Gateway elabora la configurazione di routing dei modelli e attiva il livello di routing. Al termine del deployment del gateway, il gateway è pronto a ricevere richieste di prompt formattate come payload JSON compatibili con OpenAI.

Passaggio 4: testa il comportamento di routing

Prima di testare il gateway, attendi che raggiunga lo stato ACTIVE, quindi recupera il relativo URL:

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

Durante l'anteprima pubblica, i gateway di routing dei modelli restituiscono un nome host *.run.app. Recupera il nome host solo dopo che il gateway è ACTIVE; il valore segnalato durante la creazione del gateway non è l'URL finale.

Testa il comportamento di routing del gateway utilizzando curl per inviare richieste di prompt compatibili con OpenAI all'URL del gateway (https://GATEWAY_URL). Negli esempi seguenti, $TOKEN rappresenta un token di autenticazione valido ottenuto utilizzando uno dei metodi descritti in Scegliere un metodo di autenticazione.

Testa il routing delle regole esplicite

Invia un prompt che richiede il modello 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."
      }
    ]
  }'

L'invio della richiesta a /v1/chat/gemini-claude richiama gemini-claude-router. L'attributo "model": "claude-opus-4-7" all'interno del payload JSON corrisponde alla regola esplicita in gemini-claude-router, che indica al gateway di instradare la richiesta al backend anthropic-claude-opus-47.

Testa il fallback del modello predefinito

Invia un prompt specificando un nome di modello non corrispondente per testare il routing di 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
  }'

L'invio della richiesta a /v1/chat/gemini-claude richiama gemini-claude-router. Poiché l'attributo "model": "unrecognized-model" non corrisponde a nessuna regola esplicita, il gateway invia la richiesta a defaultModel configurato del router, ovvero il backend gemini-35-flashlite.

Testa il percorso del router alternativo

Invia un prompt che richiede Gemini tramite l'endpoint del router secondario:

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."
      }
    ]
  }'

L'invio della richiesta a /v1/chat/openai-gemini richiama openai-gemini-router. L'attributo "model": "gemini-3.5-flash-lite" corrisponde alla regola esplicita in quel router, che indica al gateway di instradare la richiesta al backend gemini-35-flashlite. Un singolo backend può essere referenziato da più router; in questa configurazione, gemini-35-flashlite funge da target di regole esplicite in openai-gemini-router e da defaultModel di fallback in gemini-claude-router.

Osservabilità

Il router di modelli è instrumentato in modo che tu possa verificare che il gateway stia gestendo il traffico, ispezionare i metadati per richiesta utilizzando Cloud Logging e diagnosticare gli errori utilizzando Cloud Monitoring.

Cloud Logging

Ogni richiesta instradata tramite il gateway genera una voce nel log delle richieste di API Gateway standard che si trova in your Google Cloud project all'indirizzo:

projects/YOUR_PROJECT_ID/logs/apigateway.googleapis.com%2Frequests

Ogni voce di log include i seguenti campi:

  • httpRequest.requestUrl, httpRequest.status, httpRequest.latency
  • api, apiConfig, apiMethod
  • backendRequest.hostname: il nome host del backend Vertex AI a cui è stato eseguito il proxy della richiesta.
  • responseDetails: compilato con una categoria di errore con brand in caso di errori del router di modelli (vedi Risolvere i problemi del router di modelli subito sotto).

Per trovare le richieste recenti inviate a un gateway specifico, utilizza il seguente filtro di query di Cloud Logging:

(resource.type="apigateway.googleapis.com/Gateway" OR resource.type="api")
logName="projects/YOUR_PROJECT_ID/logs/apigateway.googleapis.com%2Frequests"

Cloud Monitoring

La metrica standard di API Gateway apigateway.googleapis.com/proxy/request_count (BETA) segnala il volume di traffico del gateway suddiviso per:

  • response_code_class: uno tra 2xx, 3xx, 4xx o 5xx.
  • api_config: il nome della configurazione API utilizzata dal gateway.

Questa metrica ti consente di verificare il volume di traffico complessivo e le percentuali di errore. Le metriche specifiche del router di modelli (ad esempio le suddivisioni per router o per modello di destinazione) verranno aggiunte in una release futura.

Per monitorare la latenza delle richieste aggregate, puoi creare una metrica basata sui log dal campo httpRequest.latency nel log delle richieste.

Risolvere i problemi del router di modelli

Quando una richiesta instradata tramite il router di modelli non va a buon fine, il campo responseDetails nella voce di log delle richieste corrispondente indica se l'errore si è verificato all'interno del livello del router di modelli. Il router di modelli mostra quattro categorie con brand:

Valore responseDetails Significato Correzione tipica
model_router_application_error Impossibile instradare la richiesta. In genere indica una regola mancante, un payload contenente un valore model che non corrisponde a nessuna regola (senza un defaultModel configurato) o un payload di richiesta non valido. Lato cliente: verifica che il parametro model del payload corrisponda a una delle stringhe rule.model nella configurazione del router o che sia definito un fallback defaultModel. Verifica che il corpo della richiesta sia un JSON valido compatibile con OpenAI e includa esplicitamente un attributo model (durante l'anteprima pubblica, un attributo model mancante nel payload della richiesta viene elaborato in modo errato anziché essere rifiutato).
model_router_timeout Il router di modelli ha superato il timeout per richiesta. La richiesta potrebbe essere insolitamente grande o complessa oppure potrebbe esserci un collo di bottiglia della capacità. Controlla la complessità della richiesta e le impostazioni di timeout nei backend. Se il problema persiste nei payload normali, contatta Google Cloud l'assistenza indicando il timestamp della richiesta e un esempio di log.
model_router_upstream_error Il modello di destinazione upstream ha restituito un errore HTTP al gateway. Lato servizio upstream: controlla il codice di stato e il payload dell'endpoint del servizio Vertex AI di destinazione. Se questo comportamento non è previsto per le richieste valide, apri una richiesta di assistenza.
model_router_unavailable Il router di modelli non è raggiungibile dal gateway a causa di un errore di trasporto o di connettività. Lato piattaforma: apri una richiesta di assistenza con Google Cloud l'assistenza.

Passaggi successivi