Configurer le routage de modèle

Cette page explique comment configurer, déployer et tester le routage de modèle dans API Gateway à l'aide des spécifications OpenAPI 3.x.

Avant de commencer

Avant de configurer le routage de modèle, vérifiez que votre environnement répond aux prérequis suivants :

1. Vérifier les autorisations IAM : vérifiez que vous avez accès au plan de gestion API Gateway et à Vertex AI Model Garden. Vous devez disposer du rôle Administrateur API Gateway (roles/apigateway.admin) pour créer des configurations d'API et des passerelles. De plus, le compte de service utilisé par votre passerelle d'API (le compte de service Compute Engine par défaut ou un compte de service géré par l'utilisateur spécifié lors de la création de la configuration d'API) doit disposer du rôle Utilisateur Vertex AI (roles/aiplatform.user) pour accéder aux modèles cibles.
2. Vérifier la disponibilité du modèle et l'accès au point de terminaison : vérifiez que vos modèles routables sont des modèles ouverts pré-déployés pour le modèle en tant que service (MaaS) dans Vertex AI Model Garden. Tous les modèles référencés par un seul routeur doivent partager exactement le même nom d'hôte. Choisissez le point de terminaison mondial (aiplatform.googleapis.com) ou un seul point de terminaison régional (par exemple, us-central1-aiplatform.googleapis.com) pour chaque modèle référencé dans ce routeur.
3. Vérifier l'éligibilité au déploiement de la passerelle : vous ne pouvez pas mettre à jour une passerelle existante déployée sans routage de modèle pour activer le routage de modèle, ni mettre à jour une passerelle déployée avec le routage de modèle pour désactiver ou supprimer le routage de modèle. Pour changer de mode de routage, vous devez créer et déployer une nouvelle configuration d'API et une nouvelle instance de passerelle.
4. Vérifier la compatibilité de VPC Service Controls et des points de terminaison : les passerelles de routage de modèle ne sont pas compatibles avec les configurations de point de terminaison VPC Service Controls ni Private Service Connect (PSC). Vérifiez que votre projet cible et vos instances API Gateway ne sont pas limités par les périmètres VPC Service Controls et que vos modèles utilisent des points de terminaison régionaux ou mondiaux publics.

Validation de la configuration

Lorsque vous déployez une configuration d'API, le plan de gestion API Gateway valide votre spécification OpenAPI. Le plan de gestion rejette les configurations non valides lors du déploiement avec une erreur de validation informative. Le processus de validation applique les règles suivantes :

Vérifications structurelles et d'emplacement

• L'extension x-google-api-management et ses blocs associés (backends, ai.models.routing.routers, les routeurs individuels et rules) doivent être bien formés. Les clés doivent correspondre aux types de données attendus (mappage, liste ou chaîne). Le plan de gestion rejette les incompatibilités de type avec une erreur expected map/list/string.
• L'extension x-google-api-management doit contenir un bloc backends valide lorsque le routage de modèle est activé.
• L'extension x-google-model-router n'est compatible qu'avec les spécifications OpenAPI 3.x (elle n'est pas compatible avec OpenAPI 2.0 / Swagger).
• L'extension x-google-model-router ne peut être spécifiée qu'au niveau de l'opération. Le plan de gestion rejette explicitement les définitions x-google-model-router placées au niveau du chemin d'accès ou au niveau racine (supérieur).
• Le bloc ai.models.routing.routers doit être défini dans x-google-api-management chaque fois qu'une opération fait référence à x-google-model-router.
• Vous ne pouvez pas spécifier à la fois x-google-model-router et x-google-backend sur la même opération d'API.
• Une spécification OpenAPI ne peut pas contenir un mélange d'opérations de routage de modèle et d'opérations sans routage de modèle. Vous ne pouvez pas spécifier d'extensions de routage standards (telles que x-google-backend) sur certaines opérations tout en utilisant x-google-model-router sur d'autres opérations dans la même spécification d'API.

Vérification de la méthode HTTP

• L'extension x-google-model-router ne peut être appliquée qu'aux opérations utilisant la méthode HTTP POST. Le plan de gestion rejette le routage de modèle sur toute autre méthode HTTP (telle que GET, PUT ou DELETE).

Validité du backend

• Chaque backend défini sous x-google-api-management.backends doit inclure un champ address non vide.
• Le backend address doit être une URL valide utilisant le schéma http ou https. Pour protéger les charges utiles de prompt et les identifiants d'authentification en transit sur des points de terminaison publics ou distants, spécifiez toujours le schéma https lorsque vous définissez le champ address.
• Chaque backend défini sous x-google-api-management.backends et référencé par un routeur de modèle doit utiliser pathTranslation: CONSTANT_ADDRESS. Le plan de gestion rejette les configurations utilisant pathTranslation: APPEND_PATH_TO_ADDRESS pour les backends de routage de modèle, car la traduction de chemin d'accès est ignorée dans le chemin d'exécution du routeur de modèle.
• Les backends de routage de modèle ne sont pas compatibles avec les configurations de point de terminaison VPC Service Controls ni Private Service Connect (PSC). Tous les champs address du backend doivent pointer vers des points de terminaison de modèle ouvert MaaS régionaux ou mondiaux publics.

Résolution des références de routeur

• Le nom du routeur référencé par le x-google-model-router d'une opération doit correspondre à une clé de routeur valide définie sous ai.models.routing.routers.
• Le backend référencé par le defaultModel d'un routeur doit correspondre à un backend valide défini sous x-google-api-management.backends.
• Le backend référencé par chaque règle d'un routeur doit correspondre à un backend valide défini sous x-google-api-management.backends.

Contenu du routeur

• Chaque routeur doit définir un defaultModel.
• Le defaultModel doit inclure un champ backend valide.
• Le defaultModel doit inclure un champ targetModel non vide.
• Chaque entrée sous rules doit inclure un champ model non vide. La valeur de chaîne default est réservée et ne peut pas être utilisée comme valeur model d'une règle.
• Chaque entrée sous rules doit inclure un champ targetModel non vide.
• Les valeurs model définies dans toutes les règles d'un même routeur doivent être uniques. Le plan de gestion rejette les valeurs model en double dans le même routeur.

Cohérence de l'hôte et du schéma du backend

• Tous les backends référencés par un seul routeur (y compris defaultModel.backend et le backend de chaque règle) doivent partager le même nom d’hôte et le même schéma d’URL. Le plan de gestion rejette les configurations avec des noms d'hôte différents ou des schémas incohérents (http par rapport à https) dans le même routeur, ce qui garantit que le routeur distribue toutes les requêtes à un point de terminaison de service en amont cohérent.

Validation du modèle cible

• La partie <provider> de la chaîne targetModel (google, openai, ou anthropic) et le format d'identifiant <provider>/<model> sont tous deux validés au moment de la création (déploiement) de la configuration. Le plan de gestion rejette un targetModel qui n'est pas au format <provider>/<model> ou dont le fournisseur n'est pas google, openai, ou anthropic avec une erreur InvalidArgument: unsupported publisher lors du déploiement.

Étape 1 : Identifier les modèles cibles

Identifiez les modèles de fondation cibles et leurs URL de point de terminaison Vertex AI correspondantes. Tous les modèles routables d'un routeur doivent partager un seul nom d'hôte (pour les modèles ouverts MaaS, ce nom d'hôte est aiplatform.googleapis.com).

Les chemins d'accès aux URL de point de terminaison varient en fonction du fournisseur de modèle :

• Google Gemini : utilise la méthode :generateContent.
• Anthropic Claude : utilise la méthode :rawPredict.
• OpenAI : utilise le chemin d'accès au point de terminaison /endpoints/openapi/chat/completions.

Le tableau suivant répertorie les points de terminaison MaaS utilisés dans l'exemple de spécification OpenAPI plus loin dans cette section :

Remplacez YOUR_PROJECT_ID par l'ID du Google Cloud projet.

Étape 2 : Configurer la spécification OpenAPI 3.x

Créez ou mettez à jour votre spécification OpenAPI 3.x pour définir vos points de terminaison de backend et vos configurations de routage de modèle.

L'exemple suivant illustre une spécification OpenAPI 3.0.3 définissant deux routeurs de modèle distincts. Pour éviter le défilement horizontal, les longues URL d'adresse de backend utilisent la continuation de chaîne multiligne entre guillemets doubles 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"

Propriétés de configuration

1. backends: l'objet backends sous x-google-api-management définit tous les points de terminaison de modèle routables. Chaque nom de backend représente un nom de modèle symbolique (par exemple, gemini-35-flashlite) contenant l'address de destination. Le champ backends est une extension Google OpenAPI existante.
2. ai.models.routing: la configuration de routage de modèle se trouve sous x-google-api-management en tant que ai.models.routing, contenant un mappage des routeurs nommés. Chaque entrée de mappage définit un routeur de modèle, où la clé représente le nom du routeur (par exemple, gemini-claude-router) et la valeur contient :
   • defaultModel: destination de modèle de remplacement obligatoire utilisée lorsqu'une charge utile de requête entrante ne correspond à aucune règle explicite. Elle partage la structure exacte d'une entrée de règle, mais omet le champ de correspondance model. Pour les routes compatibles avec OpenAI, lorsqu'une requête revient à defaultModel, la valeur de targetModel est transmise en tant qu'attribut model sortant dans le corps de la requête envoyée à Vertex AI.
   • rules: tableau facultatif dans lequel chaque élément mappe une chaîne de modèle de charge utile client à un backend de destination et à un modèle cible.
3. Propriétés de la règle : chaque entrée dans rules (et le defaultModel) définit les propriétés suivantes :
   • model (règles uniquement) : valeur de chaîne correspondant à l'attribut model dans la charge utile de prompt JSON entrante du client. Le routeur compare la valeur model de la charge utile entrante à cette chaîne. Si aucune règle ne correspond, le routeur sélectionne le defaultModel. Pour les routes compatibles avec OpenAI (où le backend de destination est /openapi/chat/completions), cette chaîne est transmise directement en tant qu'attribut model sortant dans le corps de la requête envoyée à Vertex AI. Par conséquent, pour les routes compatibles avec OpenAI, le sélecteur model doit lui-même être un identifiant de modèle d'éditeur valide (par exemple, openai/gpt-oss-120b-maas) ; l'utilisation d'un alias tel que gpt-oss génère une erreur 400 Malformed publisher model de Vertex AI.
   • backend: nom de backend symbolique défini sous x-google-api-management.backends où la passerelle envoie le prompt.
   • targetModel : identifiant de modèle cible au format <provider>/<model-id>. Le routeur de modèle utilise cette chaîne pour traduire les requêtes et les réponses du modèle de destination. Le <provider> préfixe doit être exactement google, openai, ou anthropic. Le <model-id> doit être un identifiant de modèle d'éditeur Vertex AI Model Garden valide. La passerelle renvoie cette chaîne dans le champ model de la réponse renvoyée au client. Voici quelques exemples de valeurs :
     • 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: pour associer un routeur de modèle à un chemin d'opération d'API, spécifiez le nom du routeur à l'aide de l'attribut x-google-model-router. Dans l'exemple précédent, une requête POST envoyée à /v1/chat/gemini-claude appelle gemini-claude-router, qui achemine le prompt en fonction du nom de modèle spécifié dans la charge utile JSON.

Étape 3 : Créer et déployer la configuration d'API

Créez une configuration d'API à l'aide de la spécification OpenAPI 3.x que vous avez créée, puis déployez-la sur votre instance API Gateway, comme décrit dans Déployer une API sur une passerelle.

Le plan de gestion API Gateway traite votre configuration de routage de modèle et active la couche de routage. Une fois le déploiement de votre passerelle terminé, elle est prête à recevoir des requêtes de prompt au format de charges utiles JSON compatibles avec OpenAI.

Étape 4 : Tester le comportement de routage

Avant de tester votre passerelle, attendez qu'elle atteigne l'état ACTIVE, puis récupérez son URL :

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

Pendant la préversion publique, les passerelles de routage de modèle renvoient un nom d'hôte *.run.app. Récupérez le nom d'hôte uniquement une fois que la passerelle est ACTIVE. La valeur signalée pendant la création de la passerelle n'est pas l'URL finale.

Testez le comportement de routage de votre passerelle à l'aide de curl pour envoyer des requêtes de prompt compatibles avec OpenAI à l'URL de votre passerelle (https://GATEWAY_URL). Dans les exemples suivants, $TOKEN représente un jeton d'authentification valide obtenu à l'aide de l'une des méthodes décrites dans Choisir une méthode d'authentification.

Tester le routage de règle explicite

Envoyez un prompt demandant le modèle 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'envoi de la requête à /v1/chat/gemini-claude appelle gemini-claude-router. L'attribut "model": "claude-opus-4-7" dans la charge utile JSON correspond à la règle explicite dans gemini-claude-router, ce qui indique à la passerelle d'acheminer la requête vers le backend anthropic-claude-opus-47.

Tester le remplacement du modèle par défaut

Envoyez un prompt spécifiant un nom de modèle sans correspondance pour tester le routage de remplacement :

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'envoi de la requête à /v1/chat/gemini-claude appelle gemini-claude-router. Étant donné que l'attribut "model": "unrecognized-model" ne correspond à aucune règle explicite, la passerelle envoie la requête au defaultModel configuré du routeur, à savoir le backend gemini-35-flashlite.

Tester un autre chemin d'accès au routeur

Envoyez un prompt demandant Gemini via le point de terminaison du routeur secondaire :

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'envoi de la requête à /v1/chat/openai-gemini appelle openai-gemini-router. L'attribut "model": "gemini-3.5-flash-lite" correspond à la règle explicite de ce routeur, ce qui indique à la passerelle d'acheminer la requête vers le backend gemini-35-flashlite. Un seul backend peut être référencé par plusieurs routeurs. Dans cette configuration, gemini-35-flashlite sert de cible de règle explicite dans openai-gemini-router et de defaultModel de remplacement dans gemini-claude-router.

Observabilité

Le routeur de modèle est instrumenté pour vous permettre de vérifier que votre passerelle diffuse du trafic, d'inspecter les métadonnées par requête à l'aide de Cloud Logging et de diagnostiquer les échecs à l'aide de Cloud Monitoring.

Cloud Logging

Chaque requête acheminée via la passerelle génère une entrée dans le journal de requêtes API Gateway standard situé dans votre Google Cloud projet à l'adresse suivante :

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

Chaque entrée de journal inclut les champs suivants :

• httpRequest.requestUrl, httpRequest.status, httpRequest.latency
• api, apiConfig, apiMethod
• backendRequest.hostname : nom d'hôte du backend Vertex AI vers lequel la requête a été envoyée par proxy.
• responseDetails : rempli avec une catégorie d'erreur de marque en cas d'échec du routeur de modèle (voir Résoudre les problèmes d'échec du routeur de modèle ci-dessous).

Pour trouver les requêtes récentes envoyées à une passerelle spécifique, utilisez le filtre de requête Cloud Logging suivant :

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

Cloud Monitoring

La métrique API Gateway standard apigateway.googleapis.com/proxy/request_count (BÊTA) indique le volume de trafic de la passerelle ventilé par :

• response_code_class : 2xx, 3xx, 4xx ou 5xx.
• api_config : nom de la configuration d'API utilisée par la passerelle.

Cette métrique vous permet de vérifier le volume de trafic global et les taux d'erreur. Des métriques spécifiques au routeur de modèle (telles que les répartitions par routeur ou par modèle cible) seront ajoutées dans une prochaine version.

Pour suivre la latence agrégée des requêtes, vous pouvez créer une métrique basée sur les journaux à partir du champ httpRequest.latency dans le journal des requêtes.

Résoudre les problèmes d'échec du routeur de modèle

Lorsqu'une requête acheminée via le routeur de modèle échoue, le champ responseDetails de l'entrée de journal de requête correspondante indique si l'échec s'est produit dans la couche du routeur de modèle. Le routeur de modèle présente quatre catégories de marque :

Étape suivante

• Consultez l'architecture et les concepts de routage de modèle.
• Découvrez les extensions OpenAPI 3.x.