Configurer une extension pour appeler un service Google

Les extensions de service permettent aux équilibreurs de charge d'application compatibles de configurer des extensions à l'aide d'appels aux services Google. Cette page vous explique comment configurer ces extensions.

Pour obtenir une présentation, consultez Intégration aux services Google.

Configurer une extension de trafic pour appeler le service Model Armor

Vous pouvez configurer une extension de trafic pour appeler Model Armor afin d'appliquer de manière uniforme des règles de sécurité au trafic d'inférence d'IA générative vers les équilibreurs de charge d'application, y compris GKE Inference Gateway.

Une extension de trafic regroupe les services d'extension associés dans une ou plusieurs chaînes. Vous pouvez configurer des plug-ins et des encadrés dans la même chaîne d'extension. Chaque chaîne d'extension sélectionne le trafic sur lequel agir à l'aide de conditions de correspondance CEL (Common Expression Language). L'équilibreur de charge évalue une requête par rapport à la condition de correspondance de chaque chaîne de manière séquentielle. Lorsqu'une requête correspond aux conditions définies par une chaîne, toutes les extensions de la chaîne agissent sur la requête. Une seule chaîne correspond à une requête donnée.

Chaque extension d'une chaîne peut avoir son propre ensemble d'événements compatibles. Les modifications apportées par une extension au contenu des requêtes et des réponses sont visibles par les autres extensions de la chaîne. Pour les extensions configurées pour prendre en charge les événements de réponse, la séquence d'extensions est inversée sur le chemin de réponse.

L'extension de trafic est associée à une règle de transfert d'équilibreur de charge créée à l'aide de la passerelle d'inférence. Une fois la ressource configurée, les requêtes correspondantes sont envoyées au service Model Armor.

Avant de commencer

Identifiez un projet approprié dans lequel vous disposez d'un rôle de propriétaire ou d'éditeur, ou des rôles IAM Compute Engine suivants :
- Pour créer des instances : Administrateur d'instances Compute (v1) (roles/compute.instanceAdmin.v1)
- Pour créer des composants Cloud Load Balancing : Administrateur de réseaux Compute (roles/compute.networkAdmin)
Activez les API requises.
Console
1. Dans la console Google Cloud , accédez à la page Activer l'accès aux API.
  
  Accéder à "Activer l'accès aux API"
2. Suivez les instructions pour activer les API requises, y compris l'API Compute Engine, l'API Model Armor et l'API Network Services.
gcloud
Exécutez la commande gcloud services enable :
```
gcloud services enable compute.googleapis.com modelarmor.googleapis.com networkservices.googleapis.com
```
Créez les modèles Model Armor requis.
Configurez votre infrastructure Google Kubernetes Engine en déployant une passerelle d'inférence. Testez-le en envoyant une requête d'inférence.

Sous réserve de quelques limites, les points de terminaison de l'API OpenAI suivants sont compatibles : Assistants, Chat Completions, Completions (legacy), Messages et Threads.

Limites lors de la configuration d'un point de terminaison de l'API OpenAI

Lorsque vous configurez un point de terminaison de l'API OpenAI pour votre infrastructure GKE, tenez compte des limites suivantes concernant la désinfection des requêtes et des réponses :

Les réponses de l'API de streaming ne sont compatibles avec aucune API. Si vous utilisez un mélange d'API de diffusion et de non-diffusion en continu, lorsque vous configurez l'extension de trafic, définissez failOpen sur true. Model Armor nettoie les réponses sans streaming et ignore les réponses avec streaming.
Lors de la désinfection des requêtes et des réponses, seules les opérations suivantes sont acceptées :
- API Assistants : Create, Delete, List, Modify et Retrieve
- API Chat Completions : Create, Delete, Get Chat Completion, Get Chat Message, List et Update
- API Completions (ancienne) : Create
- API Messages : Create, Delete, List, Modify et Retrieve
- API Threads : Create, Delete, Modify et Retrieve
Pour les appels d'API qui renvoient plusieurs choix dans la réponse (comme POST https://api.openai.com/v1/chat/completions), seul le premier élément de la liste des choix est nettoyé.

Configurer l'extension de trafic

Vérifiez le comportement avant la configuration de l'extension en envoyant une requête d'inférence à l'équilibreur de charge et en spécifiant l'adresse IP exposée de l'équilibreur de charge :

curl -v http://${IP}/v1/chat/completions
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'

La requête génère un code d'état HTTP 200 OK, même si des données sensibles ont été envoyées au LLM.

Pour que Model Armor bloque les requêtes contenant des données sensibles, configurez une extension de trafic.
Console
1. Dans la console Google Cloud , accédez à la page Extensions de service.
  
  Accéder aux extensions de service
2. Cliquez sur Créer une extension. Un assistant s'ouvre pour vous guider à travers les premières étapes.
3. Pour le produit, sélectionnez Équilibrage de charge. Cliquez ensuite sur Continuer. Une liste des équilibreurs de charge d'application compatibles s'affiche.
4. Sélectionnez un type d'équilibreur de charge.
5. Spécifiez la région sous la forme us-central1. Cliquez sur Continuer.
6. Pour le type d'extension, sélectionnez Extensions de trafic, puis cliquez sur Continuer.
7. Pour ouvrir le formulaire Créer une extension, cliquez sur Continuer. Dans le formulaire Créer une extension, notez que les sélections précédentes ne sont pas modifiables.
8. Dans la section Informations de base, procédez comme suit :
  1. Spécifiez un nom unique pour l'extension.
    
    Le nom doit commencer par une lettre minuscule suivie d'un maximum de 62 caractères (lettres minuscules, chiffres ou traits d'union) et ne doit pas se terminer par un trait d'union.
  2. Facultatif : Saisissez une brève description de l'extension (1 024 caractères maximum).
  3. Facultatif : Dans la section Libellés, cliquez sur Ajouter un libellé. Ensuite, dans la ligne qui s'affiche, procédez comme suit :
    
    Dans le champ Clé, saisissez le nom d'une clé.
    
    Pour Valeur, saisissez une valeur pour la clé.
    
    Pour ajouter d'autres paires clé-valeur, cliquez sur Ajouter un libellé. Vous pouvez ajouter jusqu'à 64 paires clé/valeur.
    
    Pour en savoir plus sur les libellés, consultez Créer et mettre à jour des libellés pour les projets.
9. Pour Règles de transfert, sélectionnez une ou plusieurs règles de transfert à associer à l'extension. Choisissez une règle de transfert générée lors du déploiement de la passerelle d'inférence. Vous ne pouvez pas sélectionner les règles de transfert déjà associées à une autre extension. Elles apparaissent comme indisponibles.
10. Pour les chaînes d'extensions, ajoutez une ou plusieurs chaînes d'extensions à exécuter pour une requête correspondante.
  
  Pour ajouter une chaîne d'extension, procédez comme suit, puis cliquez sur OK :
  - Dans le champ Nom de la nouvelle chaîne d'extension, spécifiez un nom unique.
    
    Le nom doit être conforme à la norme RFC-1034, ne doit comporter que des lettres minuscules, des chiffres et des traits d'union, et ne doit pas dépasser 63 caractères. De plus, le premier caractère doit être une lettre et le dernier doit être une lettre ou un chiffre.
  - Pour faire correspondre les requêtes pour lesquelles la chaîne d'extension est exécutée, spécifiez une expression CEL (Common Expression Language) dans Condition de correspondance, par exemple request.path == "/v1/chat/completions".
    
    Pour en savoir plus sur les expressions CEL, cliquez sur Obtenir de l'aide sur la syntaxe ou consultez la documentation de référence sur le langage de correspondance CEL.
  - Ajoutez une ou plusieurs extensions à exécuter pour une requête correspondante.
    
    Pour chaque extension, sous Extensions, procédez comme suit, puis cliquez sur OK :
    
    Dans le champ Nom de l'extension, spécifiez un nom unique.
    
    Le nom doit être conforme à la norme RFC-1034, ne doit comporter que des lettres minuscules, des chiffres et des traits d'union, et ne doit pas dépasser 63 caractères. De plus, le premier caractère doit être une lettre et le dernier doit être une lettre ou un chiffre.
    
    Pour Type de programmabilité, sélectionnez Services Google, puis sélectionnez un point de terminaison du service Model Armor, par exemple modelarmor.us-central1.rep.googleapis.com.
    
    Pour Délai avant expiration, spécifiez une valeur comprise entre 10 et 1 000 millisecondes, au-delà de laquelle un message sur le flux expire. Sachez que Model Armor a une latence d'environ 250 millisecondes.
    
    Pour Événements, sélectionnez tous les types d'événements HTTP.
    
    Pour Transférer les en-têtes, cliquez sur Ajouter un en-tête, puis ajoutez les en-têtes HTTP à transférer à l'extension (depuis le client ou le backend). Si aucun en-tête n'est spécifié, tous les en-têtes sont envoyés.
    
    Facultatif : si l'extension expire ou échoue et que vous souhaitez que le traitement des requêtes ou des réponses se poursuive, sélectionnez Activé pour Échec ouvert. Les extensions suivantes de la chaîne sont également exécutées.
    
    Par défaut, l'option Échec ouvert n'est pas sélectionnée. Dans ce cas, lorsqu'une erreur se produit, le traitement des requêtes ou des réponses s'arrête. Si les en-têtes de réponse n'ont pas été transmis au client en aval, un code d'état HTTP 500 générique lui est renvoyé. Si des en-têtes de réponse ont été fournis, le flux HTTP vers le client est réinitialisé.
    
    L'option par défaut Échec ouvert est préférable lorsque la sécurité ou l'intégrité sont prioritaires. L'activation de l'option Échec ouvert, en particulier pour les opérations non critiques, est utile lorsque la disponibilité est une priorité.
    
    Pour Métadonnées, cliquez sur Ajouter des métadonnées pour spécifier les modèles Model Armor à utiliser pour filtrer les requêtes et les réponses correspondant à des modèles spécifiques.
    
    Pour Clé, spécifiez model_armor_settings. Pour Valeur, spécifiez les modèles sous forme de chaîne JSON, comme suit :
    
    [{ "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" }]
    
    Remplacez les éléments suivants :
    
    MODEL_NAME : nom du modèle tel qu'il est configuré avec la ressource InferenceModel (par exemple, meta-llama/Llama-3.1-8B-Instruct)
    
    TEMPLATE_PROJECT_ID : ID de projet des modèles Model Armor
    
    LOCATION : emplacement du modèle Model Armor (par exemple, us-central1)
    
    RESPONSE_TEMPLATE : modèle de réponse à utiliser par le modèle
    
    PROMPT_TEMPLATE : modèle de requête à utiliser par le modèle
    
    Un modèle par défaut peut également être spécifié pour être utilisé lorsqu'une requête ne correspond pas exactement à un modèle. Pour configurer un modèle par défaut, spécifiez MODEL_NAME comme default.
    
    Si vous ne souhaitez pas filtrer le trafic des invites ou des réponses, créez et incluez un modèle de filtre vide.
    
    La taille totale de metadata doit être inférieure à 1 Kio. Le nombre total de clés dans les métadonnées doit être inférieur à 20. La longueur de chaque clé doit être inférieure à 64 caractères. La longueur de chaque valeur doit être inférieure à 1 024 caractères. Toutes les valeurs doivent être des chaînes.
    
    Lorsqu'une requête est bloquée, Model Armor renvoie un code d'état 403 Forbidden standard. Vous pouvez remplacer l'état en définissant des paramètres de réponse personnalisés (y compris un code d'état et un message personnalisés) dans la stratégie de sécurité du modèle Model Armor. Pour en savoir plus, consultez TemplateMetadata.
11. Cliquez sur Créer une extension.
gcloud
1. Définissez l'encadré dans un fichier YAML et associez-le à la règle de transfert générée lors du déploiement de l'Inference Gateway. Utilisez les exemples de valeurs fournis.
  cat >traffic_callout_service.yaml <<EOF name: traffic-ext forwardingRules: - https://www.googleapis.com/compute/v1/projects/LB_PROJECT_ID/regions/us-central1/forwardingRules/FORWARDING_RULE loadBalancingScheme: INTERNAL_MANAGED extensionChains: - name: "chain1-model-armor" matchCondition: celExpression: 'request.path == "/v1/chat/completions"' extensions: - name: extension-chain-1-model-armor service: modelarmor.us-central1.rep.googleapis.com failOpen: true supportedEvents: - REQUEST_HEADERS - REQUEST_BODY - REQUEST_TRAILERS - RESPONSE_HEADERS - RESPONSE_BODY - RESPONSE_TRAILERS timeout: 1s metadata: model_armor_settings: '[ { "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" } ]' EOF
  Remplacez les éléments suivants :
  - TEMPLATE_PROJECT_ID : ID de projet des modèles Model Armor
  - LB_PROJECT_ID : ID du projet de la règle de transfert de l'équilibreur de charge
  - FORWARDING_RULE : une ou plusieurs règles de transfert à associer à l'extension. Choisissez une règle de transfert générée lors du déploiement de la passerelle d'inférence.
    
    Vous ne pouvez pas sélectionner les règles de transfert déjà associées à une autre extension. Elles apparaissent comme indisponibles.
  - MODEL_NAME : nom du modèle tel qu'il est configuré avec la ressource InferenceModel (par exemple, meta-llama/Llama-3.1-8B-Instruct)
  - LOCATION : emplacement du modèle Model Armor (par exemple, us-central1)
  - RESPONSE_TEMPLATE : modèle de réponse à utiliser par le modèle
  - PROMPT_TEMPLATE : modèle de requête à utiliser par le modèle
  Dans le champ metadata, spécifiez les paramètres et les modèles Model Armor à utiliser lors de l'examen des requêtes et des réponses correspondant à des modèles spécifiques.
  
  Un modèle par défaut peut également être spécifié pour être utilisé lorsqu'une requête ne correspond pas exactement à un modèle. Pour configurer un modèle par défaut, spécifiez MODEL_NAME comme default.
  
  Si vous ne souhaitez pas filtrer le trafic des invites ou des réponses, créez et incluez un modèle de filtre vide.
  
  La taille totale de metadata doit être inférieure à 1 Kio. Le nombre total de clés dans les métadonnées doit être inférieur à 16. La longueur de chaque clé doit être inférieure à 64 caractères. La longueur de chaque valeur doit être inférieure à 1 024 caractères. Toutes les valeurs doivent être des chaînes.
  
  Lorsqu'une requête est bloquée, Model Armor renvoie un code d'état 403 Forbidden standard. Vous pouvez remplacer l'état en définissant des paramètres de réponse personnalisés (y compris un code d'état et un message personnalisés) dans la stratégie de sécurité du modèle Model Armor. Pour en savoir plus, consultez TemplateMetadata.
2. Importez l'extension de trafic. Utilisez la commande gcloud service-extensions lb-traffic-extensions import avec les exemples de valeurs suivants.
  gcloud service-extensions lb-traffic-extensions import traffic-ext \ --source=traffic_callout_service.yaml \ --location=us-central1
kubectl
1. Si vous utilisez une version de GKE antérieure à la version v1.32.2-gke.1182001, installez le CRD de l'extension de trafic :
  kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml
2. Définissez l'extension dans un fichier YAML. Cette ressource personnalisée associe votre Inference Gateway au service Model Armor. Utilisez les exemples de valeurs fournis.
  cat >traffic_callout_service.yaml <<EOF apiVersion: networking.gke.io/v1 kind: GCPTrafficExtension metadata: name: traffic-ext spec: targetRefs: - group: "gateway.networking.k8s.io" kind: Gateway name: inference-gateway extensionChains: - name: "chain1-model-armor" matchCondition: celExpressions: - celMatcher: 'request.path == "/v1/chat/completions"' extensions: - name: extension-chain-1-model-armor googleAPIServiceName: modelarmor.us-central1.rep.googleapis.com failOpen: true supportedEvents: - RequestHeaders - RequestBody - RequestTrailers - ResponseHeaders - ResponseBody - ResponseTrailers timeout: 1s metadata: model_armor_settings: '[ { "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" } ]' EOF
  Remplacez les éléments suivants :
  - MODEL_NAME : nom du modèle tel qu'il est configuré avec la ressource InferenceModel (par exemple, meta-llama/Llama-3.1-8B-Instruct)
  - TEMPLATE_PROJECT_ID : ID de projet des modèles Model Armor
  - LOCATION : emplacement du modèle Model Armor (par exemple, us-central1)
  - RESPONSE_TEMPLATE : modèle de réponse à utiliser par le modèle
  - PROMPT_TEMPLATE : modèle de requête à utiliser par le modèle
  Dans le champ metadata, spécifiez les paramètres et les modèles Model Armor à utiliser lors de l'examen des requêtes et des réponses correspondant à des modèles spécifiques.
  
  Un modèle par défaut peut également être spécifié pour être utilisé lorsqu'une requête ne correspond pas exactement à un modèle. Pour configurer un modèle par défaut, spécifiez MODEL_NAME comme default.
  
  Si vous ne souhaitez pas filtrer le trafic des invites ou des réponses, créez et incluez un modèle de filtre vide.
  
  La taille totale de metadata doit être inférieure à 1 Kio. Le nombre total de clés dans les métadonnées doit être inférieur à 16. La longueur de chaque clé doit être inférieure à 64 caractères. La longueur de chaque valeur doit être inférieure à 1 024 caractères. Toutes les valeurs doivent être des chaînes.
  
  Lorsqu'une requête est bloquée, Model Armor renvoie un code d'état 403 Forbidden standard. Vous pouvez remplacer l'état en définissant des paramètres de réponse personnalisés (y compris un code d'état et un message personnalisés) dans la stratégie de sécurité du modèle Model Armor. Pour en savoir plus, consultez TemplateMetadata.
3. Appliquez la configuration définie dans le fichier traffic_callout_service.yaml à votre cluster GKE. Cette commande crée la ressource GCPTrafficExtension, qui associe votre passerelle d'inférence au service Model Armor.
  kubectl apply -f traffic_callout_service.yaml

Attribuez les rôles requis au compte de service des extensions de service. Exécutez la commande gcloud projects add-iam-policy-binding :

gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/container.admin
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

Remplacez les éléments suivants :

TEMPLATE_PROJECT_ID : ID du projet des modèles Model Armor
LB_PROJECT_NUMBER : numéro de projet de l'équilibreur de charge

Ces valeurs sont listées dans le panneau Informations sur le projet de la consoleGoogle Cloud pour votre projet.

Pour vérifier que l'extension de trafic fonctionne comme prévu, exécutez la même commande curl :

curl -v http://${IP}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'
  ```

Une fois l'extension de service configurée, une requête contenant des données sensibles génère un code d'état HTTP 403 Forbidden, consigne un message d'erreur tel qu'il est configuré dans le modèle et ferme la connexion.

Lorsque la requête est sûre, il génère un code d'état HTTP 200 OK et renvoie la réponse du LLM à l'utilisateur.

Pour surveiller le comportement de l'extension, utilisez l'explorateur de journaux. Dans le volet de requête, en fonction de la configuration de votre Inference Gateway, filtrez par le type de ressource d'équilibreur de charge approprié.

Les entrées de journal de l'équilibreur de charge d'application contiennent des informations qui vous aident à déboguer votre trafic HTTP ou HTTPS.

Pour effectuer une analyse plus détaillée des évaluations de sécurité, activez la journalisation des audits Model Armor.

Étapes suivantes

Gérer les extensions

Configurer une extension pour appeler un service Google Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.