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:

  1. 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.
  2. 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.
  3. 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.
  4. 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-management y sus bloques asociados (backends, ai.models.routing.routers, routers individuales y rules) 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 error expected map/list/string.
  • La extensión x-google-api-management debe contener un bloque backends válido cuando el enrutamiento a modelos está habilitado.
  • La extensión x-google-model-router solo se admite en las especificaciones de OpenAPI 3.x (no se admite en OpenAPI 2.0/Swagger).
  • La extensión x-google-model-router solo se puede especificar a nivel de la operación. El plano de administración rechaza de forma explícita las definiciones de x-google-model-router que se colocan en el nivel de ruta de acceso o en el nivel raíz (superior).
  • El bloque ai.models.routing.routers debe definirse dentro de x-google-api-management cada vez que una operación haga referencia a x-google-model-router.
  • No puedes especificar x-google-model-router y x-google-backend en 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 usas x-google-model-router en otras operaciones dentro de la misma especificación de la API.

Verificación del método HTTP

  • La extensión x-google-model-router solo se puede aplicar a operaciones que usen el método HTTP POST. El plano de administración rechaza el enrutamiento a modelos en cualquier otro método HTTP (como GET, PUT o DELETE).

Validez del backend

  • Cada backend definido en x-google-api-management.backends debe incluir un campo address no vacío.
  • El backend address debe ser una URL válida que use el esquema http o https. 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 esquema https cuando definas el campo address. Los endpoints de API de Google deben usar https; consulta Hosts y esquemas de backend.
  • Cada backend definido en x-google-api-management.backends y al que hace referencia un enrutador de modelos debe usar pathTranslation: CONSTANT_ADDRESS. El plano de administración rechaza las configuraciones que usan pathTranslation: APPEND_PATH_TO_ADDRESS para 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 address del 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-router de una operación debe coincidir con una clave de router válida definida en ai.models.routing.routers.
  • El backend al que hace referencia el defaultModel de un router debe coincidir con un backend válido definido en x-google-api-management.backends.
  • El backend al que hace referencia cada regla de un router debe coincidir con un backend válido definido en x-google-api-management.backends.

Contenido del router

  • Cada router debe definir un defaultModel.
  • El defaultModel debe incluir un campo backend válido.
  • El defaultModel debe incluir un campo targetModel que no esté vacío.
  • Cada entrada en rules debe incluir un campo model que no esté vacío. El valor de cadena default está reservado y no se puede usar como el valor model de una regla.
  • Cada entrada en rules debe incluir un campo targetModel que no esté vacío.
  • Los valores de model definidos en todas las reglas de un solo router deben ser únicos. El plano de administración rechaza los valores model duplicados 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 cadena targetModel (google, openai o anthropic) 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 un targetModel que no tiene el formato <provider>/<model> o cuyo proveedor no es google, openai o anthropic con un error InvalidArgument: unsupported publisher durante 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

  1. backends: El objeto backends en x-google-api-management define 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 destino address. El campo backends es una extensión de OpenAPI de Google existente.
  2. ai.models.routing: La configuración del enrutamiento a modelos reside en x-google-api-management como ai.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 coincidencia model. En el caso de las rutas compatibles con OpenAI, cuando una solicitud recurre a defaultModel, el valor de targetModel se reenvía como el atributo model saliente 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.
  3. Propiedades de las reglas: Cada entrada dentro de rules (y defaultModel) define las siguientes propiedades:
    • model (solo reglas): Es el valor de cadena que coincide con el atributo model dentro de la carga útil de la instrucción JSON entrante del cliente. El router compara el valor model de la carga útil entrante con esta cadena. Si no coincide ninguna regla, el router selecciona el defaultModel. 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 atributo model saliente en el cuerpo de la solicitud que se envía a Agent Platform. Por lo tanto, para las rutas compatibles con OpenAI, el selector model debe ser un identificador de modelo de publicador válido (por ejemplo, openai/gpt-oss-120b-maas). El uso de un alias como gpt-oss genera un error 400 Malformed publisher model de Agent Platform.
    • backend: Es el nombre simbólico del backend definido en x-google-api-management.backends al 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 exactamente google, openai o anthropic. 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 campo model de la respuesta que se devuelve al cliente. Estos son algunos ejemplos de valores:
      • 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: Para adjuntar un enrutador de modelos a una ruta de operación de la API, especifica el nombre del enrutador con el atributo x-google-model-router. En el ejemplo anterior, una solicitud POST enviada a /v1/chat/gemini-claude invoca a gemini-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.latency
  • api, apiConfig, apiMethod
  • backendRequest.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, 4xx o 5xx.
  • 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?