Configura el enrutamiento a modelos
En esta página, se describe cómo configurar, implementar y probar el enrutamiento a modelos en API Gateway con las especificaciones de OpenAPI 3.x.
Antes de comenzar
Antes de configurar el enrutamiento a modelos, verifica que tu entorno cumpla con los siguientes requisitos previos:
- Verifica los permisos de IAM: Comprueba que tengas acceso al plano de administración de API Gateway y a Model Garden de Gemini Enterprise Agent Platform. Debes tener el rol de administrador de API Gateway (
roles/apigateway.admin) para crear parámetros de configuración y puertas de enlace de APIs. Además, a la cuenta de servicio que usa tu puerta de enlace, ya sea la cuenta de servicio predeterminada de Compute Engine o una cuenta de servicio administrada por el usuario que se especifica cuando se crea la configuración de la API, se le debe otorgar el rol de usuario de Agent Platform (roles/aiplatform.user) en cada proyecto que aloja un modelo de destino, por lo que un router cuyos backends están en otros proyectos también necesita el rol en esos proyectos. - Verifica la disponibilidad del modelo y el acceso al extremo: Comprueba que tus modelos enrutables sean modelos abiertos para Model as a Service (MaaS) implementados previamente en Model Garden de Agent Platform. Los modelos a los que hace referencia un solo router pueden usar diferentes extremos, como el extremo global (
aiplatform.googleapis.com) y los extremos regionales (por ejemplo,us-central1-aiplatform.googleapis.com). Para conocer las reglas que se aplican, consulta Hosts y esquemas de backend. - Verifica la elegibilidad de la implementación de la puerta de enlace: No puedes actualizar una puerta de enlace existente implementada sin enrutamiento a modelos para habilitarlo, ni puedes actualizar una puerta de enlace implementada con enrutamiento a modelos para inhabilitarlo o quitarlo. Para cambiar los modos de enrutamiento, debes crear e implementar una nueva configuración de API y una instancia de puerta de enlace.
- Verifica la compatibilidad de los Controles del servicio de VPC y los extremos: Las puertas de enlace de enrutamiento a modelos no admiten los Controles del servicio de VPC ni las configuraciones de extremos de Private Service Connect (PSC). Verifica que tu proyecto de destino y las instancias de API Gateway no estén restringidos por los perímetros de los Controles del servicio de VPC y que tus modelos usen extremos públicos regionales o globales.
Validación de la configuración
Cuando implementas una configuración de API, el plano de administración de API Gateway valida tu especificación de OpenAPI. El plano de administración rechaza las configuraciones no válidas durante la implementación con un error de validación informativo. El proceso de validación aplica de manera forzosa las siguientes reglas:
Verificaciones estructurales y de ubicación
- La extensión
x-google-api-managementy sus bloques asociados (backends,ai.models.routing.routers, routers individuales yrules) deben tener el formato correcto. Las claves deben coincidir con los tipos de datos esperados (mapa, lista o cadena). El plano de administración rechaza las discrepancias de tipo con un errorexpected map/list/string. - La extensión
x-google-api-managementdebe contener un bloquebackendsválido cuando el enrutamiento a modelos está habilitado. - La extensión
x-google-model-routersolo se admite en las especificaciones de OpenAPI 3.x (no se admite en OpenAPI 2.0/Swagger). - La extensión
x-google-model-routersolo se puede especificar a nivel de la operación. El plano de administración rechaza de forma explícita las definiciones dex-google-model-routerque se colocan en el nivel de ruta de acceso o en el nivel raíz (superior). - El bloque
ai.models.routing.routersdebe definirse dentro dex-google-api-managementcada vez que una operación haga referencia ax-google-model-router. - No puedes especificar
x-google-model-routeryx-google-backenden la misma operación de la API. - Una especificación de OpenAPI no puede contener una combinación de operaciones de enrutamiento a modelos y de enrutamiento que no sea a modelos. No puedes especificar extensiones de enrutamiento estándar (como
x-google-backend) en algunas operaciones mientras usasx-google-model-routeren otras operaciones dentro de la misma especificación de la API.
Verificación del método HTTP
- La extensión
x-google-model-routersolo se puede aplicar a operaciones que usen el método HTTPPOST. El plano de administración rechaza el enrutamiento a modelos en cualquier otro método HTTP (comoGET,PUToDELETE).
Validez del backend
- Cada backend definido en
x-google-api-management.backendsdebe incluir un campoaddressno vacío. - El backend
addressdebe ser una URL válida que use el esquemahttpohttps. Para proteger las cargas útiles de los mensajes y las credenciales de autenticación en tránsito en extremos públicos o remotos, especifica siempre el esquemahttpscuando definas el campoaddress. Los endpoints de API de Google deben usarhttps; consulta Hosts y esquemas de backend. - Cada backend definido en
x-google-api-management.backendsy al que hace referencia un enrutador de modelos debe usarpathTranslation: CONSTANT_ADDRESS. El plano de administración rechaza las configuraciones que usanpathTranslation: APPEND_PATH_TO_ADDRESSpara los backends de enrutamiento a modelos porque se ignora la traducción de rutas de acceso en la ruta de acceso del entorno de ejecución del enrutador de modelos. - Los backends de enrutamiento a modelos no admiten los Controles del servicio de VPC ni las configuraciones de extremos de Private Service Connect (PSC). Todos los campos
addressdel backend deben apuntar a extremos de modelos abiertos de MaaS regionales o globales públicos.
Resolución de referencia del router
- El nombre del router al que hace referencia el
x-google-model-routerde una operación debe coincidir con una clave de router válida definida enai.models.routing.routers. - El
backendal que hace referencia eldefaultModelde un router debe coincidir con un backend válido definido enx-google-api-management.backends. - El
backendal que hace referencia cada regla de un router debe coincidir con un backend válido definido enx-google-api-management.backends.
Contenido del router
- Cada router debe definir un
defaultModel. - El
defaultModeldebe incluir un campobackendválido. - El
defaultModeldebe incluir un campotargetModelque no esté vacío. - Cada entrada en
rulesdebe incluir un campomodelque no esté vacío. El valor de cadenadefaultestá reservado y no se puede usar como el valormodelde una regla. - Cada entrada en
rulesdebe incluir un campotargetModelque no esté vacío. - Los valores de
modeldefinidos en todas las reglas de un solo router deben ser únicos. El plano de administración rechaza los valoresmodelduplicados dentro del mismo router.
Hosts y esquemas de backend
El enrutamiento a modelos solo admite extremos de la API de Google como backends: nombres de host que terminan en .googleapis.com o .vertexai.goog. La puerta de enlace se autentica en cada backend al que hace referencia un solo router (incluidos defaultModel.backend y backend de cada regla) con un token de acceso de OAuth 2.0, que es válido en cualquier host de la API de Google (consulta Otras APIs de Google Cloud ). El plano de administración rechaza las configuraciones que incumplen las siguientes reglas:
- Cada backend al que hace referencia un router debe usar el esquema
https. - Un router no puede mezclar endpoints de la API de Google con otros endpoints.
Los backends a los que hace referencia un router pueden estar en diferentes hosts (por ejemplo, el extremo global aiplatform.googleapis.com, los extremos regionales como us-central1-aiplatform.googleapis.com o los extremos .vertexai.goog) y en diferentes proyectos.
Validación del modelo objetivo
- La parte
<provider>de la cadenatargetModel(google,openaioanthropic) y el formato del identificador<provider>/<model>se validan en el momento de la creación de la configuración (implementación). El plano de administración rechaza untargetModelque no tiene el formato<provider>/<model>o cuyo proveedor no esgoogle,openaioanthropiccon un errorInvalidArgument: unsupported publisherdurante la implementación.
Paso 1: Identifica los modelos de destino
Identifica los modelos de base de destino y sus URLs de extremos de Agent Platform correspondientes. Los modelos dentro de un router pueden usar diferentes extremos de Agent Platform, por ejemplo, el extremo global (aiplatform.googleapis.com) y un extremo regional (us-central1-aiplatform.googleapis.com).
Las rutas de URL de extremos varían según el proveedor del modelo:
- Google Gemini: Usa el método
:generateContent. - Anthropic Claude: Usa el método
:rawPredict. - OpenAI: Usa la ruta de acceso del extremo
/endpoints/openapi/chat/completions.
En la siguiente tabla, se enumeran los extremos de MaaS que se usan en el ejemplo de especificación de OpenAPI que se incluye más adelante en esta sección:
| Modelo | URL del extremo |
|---|---|
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 |
Reemplaza YOUR_PROJECT_ID por el ID del proyecto de Google Cloud .
Paso 2: Configura la especificación de OpenAPI 3.x
Crea o actualiza tu especificación de OpenAPI 3.x para definir tus extremos de backend y las configuraciones de enrutamiento a modelos.
En el siguiente ejemplo, se muestra una especificación de OpenAPI 3.0.3 que define dos enrutadores a modelos distintos. Para evitar el desplazamiento horizontal, las URLs largas de direcciones de backend usan la continuación de cadenas de varias líneas entre comillas dobles de 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"
Propiedades de configuración
backends: El objetobackendsenx-google-api-managementdefine todos los extremos de modelos enrutables. Cada nombre de backend representa un nombre de modelo simbólico (por ejemplo,gemini-35-flashlite) que contiene el destinoaddress. El campobackendses una extensión de OpenAPI de Google existente.ai.models.routing: La configuración del enrutamiento a modelos reside enx-google-api-managementcomoai.models.routing, que contiene un mapa de routers con nombre. Cada entrada de mapa define un enrutador de modelos, en el que la clave representa el nombre del enrutador (por ejemplo,gemini-claude-router) y el valor contiene lo siguiente:defaultModel: Es el destino del modelo de resguardo obligatorio que se usa cuando una carga útil de solicitud entrante no coincide con ninguna regla explícita. Comparte la estructura exacta de una entrada de regla, pero omite el campo de coincidenciamodel. En el caso de las rutas compatibles con OpenAI, cuando una solicitud recurre adefaultModel, el valor detargetModelse reenvía como el atributomodelsaliente en el cuerpo de la solicitud que se envía a Agent Platform.rules: Es un array opcional en el que cada elemento asigna una cadena de modelo de carga útil del cliente a un backend de destino y a un modelo de destino.
- Propiedades de las reglas: Cada entrada dentro de
rules(ydefaultModel) define las siguientes propiedades:model(solo reglas): Es el valor de cadena que coincide con el atributomodeldentro de la carga útil de la instrucción JSON entrante del cliente. El router compara el valormodelde la carga útil entrante con esta cadena. Si no coincide ninguna regla, el router selecciona eldefaultModel. Para las rutas compatibles con OpenAI (en las que el backend de destino es/openapi/chat/completions), esta cadena se reenvía directamente como el atributomodelsaliente en el cuerpo de la solicitud que se envía a Agent Platform. Por lo tanto, para las rutas compatibles con OpenAI, el selectormodeldebe ser un identificador de modelo de publicador válido (por ejemplo,openai/gpt-oss-120b-maas). El uso de un alias comogpt-ossgenera un error400 Malformed publisher modelde Agent Platform.backend: Es el nombre simbólico del backend definido enx-google-api-management.backendsal que la puerta de enlace envía la instrucción.targetModel: Es el identificador del modelo de destino con el formato<provider>/<model-id>. El enrutador de modelos usa esta cadena para traducir las solicitudes y respuestas del modelo de destino. El prefijo<provider>debe ser exactamentegoogle,openaioanthropic. El<model-id>debe ser un identificador de modelo de publicador de Model Garden de Agent Platform válido. La puerta de enlace repite esta cadena en el campomodelde la respuesta que se devuelve al cliente. Estos son algunos ejemplos de valores:google/gemini-3.5-flash-litegoogle/gemini-2.5-proopenai/gpt-oss-120b-maasanthropic/claude-opus-4-7
x-google-model-router: Para adjuntar un enrutador de modelos a una ruta de operación de la API, especifica el nombre del enrutador con el atributox-google-model-router. En el ejemplo anterior, una solicitudPOSTenviada a/v1/chat/gemini-claudeinvoca agemini-claude-router, que enruta la instrucción según el nombre del modelo especificado en la carga útil de JSON.
Paso 3: Crea e implementa la configuración de la API
Crea una configuración de API con la especificación de OpenAPI 3.x que creaste y, luego, impleméntala en tu instancia de API Gateway como se describe en Implementa una API en una puerta de enlace.
El plano de administración de API Gateway procesa tu configuración de enrutamiento a modelos y activa la capa de enrutamiento. Cuando se complete la implementación de la puerta de enlace, esta estará lista para recibir solicitudes de instrucciones con formato de cargas útiles JSON compatibles con OpenAI.
Paso 4: Prueba el comportamiento del enrutamiento
Antes de probar la puerta de enlace, espera a que alcance el estado ACTIVE y, luego, recupera su URL:
gcloud api-gateway gateways describe GATEWAY_ID \
--location=GATEWAY_LOCATION \
--project=PROJECT_ID \
--format='value(defaultHostname)'
Al comienzo de la versión preliminar pública de Model Routing, las puertas de enlace de enrutamiento a modelos usaban un nombre de host run.app. A partir del 3 de septiembre de 2026, las nuevas puertas de enlace de enrutamiento a modelos podrían usar un nombre de host predeterminado de gateway.dev con el formato https://GATEWAY_ID-PROJECT_NUMBER.REGION.gateway.dev, por ejemplo, https://my-gateway-123456789012.us-central1.gateway.dev. El nombre de host predeterminado es inmutable y se asigna en el momento de la creación. Independientemente del formato que se asigne, ya sea un nombre de host run.app o gateway.dev, la puerta de enlace conserva ese formato de forma permanente.
Prueba el comportamiento de enrutamiento de tu puerta de enlace con curl para enviar solicitudes de instrucciones compatibles con OpenAI a la URL de tu puerta de enlace (https://GATEWAY_URL). En los siguientes ejemplos, $TOKEN representa un token de autenticación válido obtenido con cualquiera de los métodos descritos en Elige un método de autenticación.
Prueba el enrutamiento de reglas explícitas
Envía una instrucción para solicitar el modelo anthropic/claude-opus-4-7 de Claude:
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."
}
]
}'
Cuando se envía la solicitud a /v1/chat/gemini-claude, se invoca gemini-claude-router. El atributo "model": "claude-opus-4-7" dentro de la carga útil de JSON coincide con la regla explícita en gemini-claude-router, lo que indica a la puerta de enlace que enrute la solicitud al backend anthropic-claude-opus-47.
Prueba el resguardo del modelo predeterminado
Envía una instrucción que especifique un nombre de modelo que no coincida para probar el enrutamiento de resguardo:
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
}'
Cuando se envía la solicitud a /v1/chat/gemini-claude, se invoca gemini-claude-router. Debido a que el atributo "model": "unrecognized-model" no coincide con ninguna regla explícita, la puerta de enlace envía la solicitud al defaultModel configurado del router, el backend gemini-35-flashlite.
Prueba la ruta alternativa del router
Envía una instrucción para solicitar Gemini a través del extremo del router secundario:
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."
}
]
}'
Cuando se envía la solicitud a /v1/chat/openai-gemini, se invoca openai-gemini-router. El atributo "model": "gemini-3.5-flash-lite" coincide con la regla explícita en ese router, lo que indica a la puerta de enlace que enrute la solicitud al backend gemini-35-flashlite. Varios routers pueden hacer referencia a un solo backend. En esta configuración, gemini-35-flashlite funciona como un destino de regla explícito en openai-gemini-router y como el defaultModel de resguardo en gemini-claude-router.
Observabilidad
El enrutamiento a modelos está instrumentado para que puedas verificar que tu puerta de enlace esté entregando tráfico, inspeccionar los metadatos por solicitud con Cloud Logging y diagnosticar fallas con Cloud Monitoring.
Cloud Logging
Cada solicitud enrutada a través de la puerta de enlace genera una entrada en el registro de solicitudes estándar de API Gateway ubicado en tu proyecto de Google Cloud en:
projects/YOUR_PROJECT_ID/logs/apigateway.googleapis.com%2Frequests
En cada entrada de registro, se incluyen los siguientes campos:
httpRequest.requestUrl,httpRequest.status,httpRequest.latencyapi,apiConfig,apiMethodbackendRequest.hostname: Es el nombre de host del backend de la plataforma de agentes al que se envió la solicitud mediante proxy.responseDetails: Se completa con una categoría de error de marca en las fallas del enrutamiento a modelos (consulta Soluciona problemas de fallas del enrutamiento a modelos).
Para encontrar las solicitudes recientes enviadas a una puerta de enlace específica, usa el siguiente filtro de consulta de 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 métrica estándar de API Gateway apigateway.googleapis.com/proxy/request_count (BETA) informa el volumen de tráfico de la puerta de enlace desglosado de la siguiente manera:
response_code_class: Es uno de los siguientes:2xx,3xx,4xxo5xx.api_config: Es el nombre de la configuración de la API que usa la puerta de enlace.
Esta métrica te permite verificar el volumen de tráfico general y las tasas de error. Las métricas específicas del enrutador de modelos (como los desgloses por enrutador o por modelo de destino) se agregarán en una versión futura.
Para hacer un seguimiento de la latencia de las solicitudes agregadas, puedes crear una métrica basada en registros a partir del campo httpRequest.latency en el registro de solicitudes.
Soluciona problemas de fallas del enrutador de modelos
Cuando falla una solicitud enrutada a través del enrutador de modelos, el campo responseDetails de la entrada de registro de la solicitud correspondiente indica si la falla se produjo dentro de la capa del enrutador de modelos. El enrutador de modelos muestra cuatro categorías de marca:
Valor responseDetails |
Significado | Solución típica |
|---|---|---|
model_router_application_error |
No se pudo enrutar la solicitud. Por lo general, esto indica que falta una regla, que una carga útil contiene un valor model que no coincide con ninguna regla (sin un defaultModel configurado) o que la carga útil de la solicitud tiene un formato incorrecto. |
Lado del cliente: Verifica que el parámetro model de tu carga útil coincida con una de las cadenas rule.model de la configuración de tu router o que se haya definido un resguardo defaultModel. Verifica que el cuerpo de la solicitud sea un JSON válido compatible con OpenAI y que incluya de forma explícita un atributo model (durante la versión preliminar pública, un atributo model faltante en la carga útil de la solicitud se procesa de forma incorrecta en lugar de rechazarse). |
model_router_timeout |
El enrutador de modelos superó el tiempo de espera por solicitud. Es posible que la solicitud sea inusualmente grande o compleja, o que haya un cuello de botella de capacidad. | Verifica la complejidad de las solicitudes y la configuración de tiempo de espera en los backends. Si el problema persiste en las cargas útiles normales, comunícate con el equipo de asistencia deGoogle Cloud con la marca de tiempo de la solicitud y una muestra de registro. |
model_router_upstream_error |
El modelo de destino upstream devolvió un error de HTTP a la puerta de enlace. | Lado del servicio upstream: Verifica el código de estado y la carga útil del extremo del servicio de Agent Platform de destino. Si esto es inesperado para las solicitudes válidas, abre un caso de asistencia. |
model_router_unavailable |
No se pudo acceder al enrutador de modelos desde la puerta de enlace debido a una falla de transporte o conectividad. | Lado de la plataforma: Abre un caso de asistencia con el equipo de asistencia deGoogle Cloud . |
¿Qué sigue?
- Revisa la arquitectura y los conceptos del enrutamiento a modelos
- Explora las extensiones de OpenAPI 3.x