Configura el enrutamiento de modelos

En esta página, se describe cómo configurar, implementar y probar el enrutamiento de modelos en API Gateway con las especificaciones de OpenAPI 3.x.

Antes de comenzar

Antes de configurar el enrutamiento de modelos, verifica que tu entorno cumpla con los siguientes requisitos previos:

1. Verifica los permisos de IAM: Verifica que tengas acceso al plano de administración de API Gateway y a Vertex AI Model Garden. Debes tener el rol de administrador de API Gateway (roles/apigateway.admin) para crear configuraciones de API y puertas de enlace. Además, la cuenta de servicio que usa tu puerta de enlace de API (ya sea la cuenta de servicio predeterminada de Compute Engine o una cuenta de servicio administrada por el usuario especificada cuando se crea la configuración de la API) debe tener el rol de usuario de Vertex AI (roles/aiplatform.user) para acceder a los modelos de destino.
2. Verifica la disponibilidad del modelo y el acceso al extremo: Verifica que tus modelos enrutables sean modelos abiertos implementados previamente para el modelo como servicio (MaaS) en Vertex AI Model Garden. Todos los modelos a los que hace referencia un solo router deben compartir exactamente el mismo nombre de host. Elige el extremo global (aiplatform.googleapis.com) o un solo extremo regional (por ejemplo, us-central1-aiplatform.googleapis.com) para cada modelo al que se hace referencia dentro de ese router.
3. Verifica la elegibilidad de la implementación de la puerta de enlace: No puedes actualizar una puerta de enlace existente implementada sin enrutamiento de modelos para habilitar el enrutamiento de modelos, ni puedes actualizar una puerta de enlace implementada con enrutamiento de modelos para inhabilitar o quitar el enrutamiento de modelos. 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 los Controles del servicio de VPC y la compatibilidad de extremos: Las puertas de enlace de enrutamiento de 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 regionales o globales públicos.

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 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 estar bien formados. Las claves deben coincidir con sus 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 se habilita el enrutamiento de modelos.
• 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 explícitamente las definiciones de x-google-model-router colocadas 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 API.
• Una especificación de OpenAPI no puede contener una combinación de operaciones de enrutamiento de modelos y de no enrutamiento de 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 API.

Verificación del método HTTP

• La extensión x-google-model-router solo se puede aplicar a las operaciones que usan el método HTTP POST. El plano de administración rechaza el enrutamiento de 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.
• La address del backend debe ser una URL válida que use el esquema http o https. Para proteger las cargas útiles de instrucciones y las credenciales de autenticación en tránsito a través de extremos públicos o remotos, siempre especifica el esquema https cuando definas el campo address.
• Cada backend definido en x-google-api-management.backends y al que hace referencia un router 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 de modelos porque la traducción de ruta de acceso se ignora en la ruta de acceso del entorno de ejecución del router de modelos.
• Los backends de enrutamiento de 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 referencias 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 no vacío.
• Cada entrada en rules debe incluir un campo model no vacío. El valor de cadena default está reservado y no se puede usar como valor model de una regla.
• Cada entrada en rules debe incluir un campo targetModel no vacío.
• Los valores model definidos en todas las reglas dentro de un solo router deben ser únicos. El plano de administración rechaza los valores model duplicados dentro del mismo router.

Coherencia del host y el esquema del backend

• Todos los backends a los que hace referencia un solo router (incluidos defaultModel.backend y el backend de cada regla) deben compartir el mismo nombre de host y esquema de URL. El plano de administración rechaza las configuraciones con nombres de host diferentes o esquemas incoherentes (http en comparación con https) dentro del mismo router, lo que garantiza que el router envíe todas las solicitudes a un extremo de servicio ascendente coherente.

Validación del modelo de destino

• 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 base de destino y sus URLs de extremos de Vertex AI correspondientes. Todos los modelos enrutables dentro de un router deben compartir un solo nombre de host (para los modelos abiertos de MaaS, este nombre de host es aiplatform.googleapis.com).

Las rutas de acceso de la URL del extremo 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 más adelante en esta sección:

Reemplaza YOUR_PROJECT_ID por el ID del Google Cloud proyecto de.

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 de modelos.

En el siguiente ejemplo, se muestra una especificación de OpenAPI 3.0.3 que define dos routers de 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 la address de destino. El campo backends es una extensión de OpenAPI de Google existente.
2. ai.models.routing: La configuración de enrutamiento de 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 router de modelos, en el que la clave representa el nombre del router (por ejemplo, gemini-claude-router) y el valor contiene lo siguiente:
   • defaultModel: 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. Para 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 Vertex AI.
   • 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 un modelo de destino.
3. Propiedades de la regla: Cada entrada dentro de rules (y el 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 con 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 Vertex AI. 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 Vertex AI.
   • backend: Es el nombre simbólico del backend definido en x-google-api-management.backends en el 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 router de modelos usa esta cadena para traducir solicitudes y respuestas para el 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 Vertex AI Model Garden válido. La puerta de enlace repite esta cadena en el campo model de la respuesta que se muestra al cliente. Los valores de ejemplo incluyen lo siguiente:
     • 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 router de modelos a una ruta de acceso de operación de API, especifica el nombre del router con el atributo x-google-model-router. En el ejemplo anterior, una solicitud POST enviada a /v1/chat/gemini-claude invoca 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 tu especificación de OpenAPI 3.x creada y, luego, implementa la configuración 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 la configuración de enrutamiento de modelos y activa la capa de enrutamiento. Cuando se completa la implementación de la puerta de enlace, esta está lista para recibir solicitudes de instrucciones con el formato de cargas útiles de JSON compatibles con OpenAI.

Paso 4: Prueba el comportamiento de enrutamiento

Antes de probar tu 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)'

Durante la vista previa pública, las puertas de enlace de enrutamiento de modelos muestran un nombre de host *.run.app. Recupera el nombre de host solo después de que la puerta de enlace esté ACTIVE; el valor informado mientras se crea la puerta de enlace no es la URL final.

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 que solicite el modelo de 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."
      }
    ]
  }'

Si envías 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 no coincidente 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
  }'

Si envías 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 de acceso alternativa del router

Envía una instrucción que solicite 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."
      }
    ]
  }'

Si envías 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. Se puede hacer referencia a un solo backend en varios routers; 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 router de 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 Google Cloud proyecto 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 Vertex AI al que se envió la solicitud por proxy.
• responseDetails: Se propaga con una categoría de error de marca en las fallas del router de modelos (consulta Soluciona problemas de fallas del router de modelos justo debajo).

Para encontrar 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: Uno de 2xx, 3xx, 4xx o 5xx.
• api_config: 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. Se agregarán métricas específicas del router de modelos (como desgloses por router o por modelo de destino) en una versión futura.

Para hacer un seguimiento de la latencia agregada de las solicitudes, puedes crear una métrica basada en registros a partir del campo httpRequest.latency en el registro de solicitudes.

Soluciona problemas de fallas del router de modelos

Cuando falla una solicitud enrutada a través del router de modelos, el campo responseDetails en la entrada de registro de solicitudes correspondiente indica si la falla ocurrió dentro de la capa del router de modelos. El router de modelos muestra cuatro categorías de marca:

¿Qué sigue?

• Revisa la arquitectura y los conceptos de enrutamiento de modelos.
• Explora las extensiones de OpenAPI 3.x.