Ce document explique comment configurer Model Armor pour consigner les opérations suivantes :
- Opérations qui créent, mettent à jour ou suppriment un modèle
- Opérations qui nettoient un prompt utilisateur ou une réponse de modèle
Model Armor utilise des journaux d'audit pour enregistrer les activités d'administration et de gestion des ressources. Pour en savoir plus, consultez Journalisation d'audit Model Armor.
Pour en savoir plus sur la tarification des journaux, consultez la page Tarifs de Cloud Logging. Des frais d'utilisation de Model Armor peuvent également s'appliquer en fonction du volume de données traitées. Pour en savoir plus, consultez la page Tarifs de Model Armor.
Avant de commencer
Avant de commencer, effectuez les tâches suivantes.
Obtenir les autorisations requises
Pour obtenir les autorisations nécessaires pour configurer la journalisation pour Model Armor, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Model Armor (roles/modelarmor.admin) sur le modèle Model Armor.
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.
Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.
Activer les API
Vous devez activer l'API Model Armor avant de pouvoir utiliser Model Armor.
Console
Activez l'API Model Armor, si ce n'est pas déjà fait.
Rôles requis pour activer les API
Pour activer des API, vous devez disposer de l'autorisation
serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.Sélectionnez le projet dans lequel vous souhaitez activer Model Armor.
gcloud
Avant de commencer, suivez ces étapes à l'aide de la Google Cloud CLI avec l'API Model Armor :
Installez la Google Cloud CLI, puis connectez-vous à la gcloud CLI avec votre identité fédérée. Après vous être connecté, initialisez la Google Cloud CLI en exécutant la commande suivante :
gcloud initActivez l'API Model Armor si ce n'est pas déjà fait :
Rôles requis pour activer les API
Pour activer des API, vous devez disposer de l'autorisation
serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.gcloud services enable modelarmor.googleapis.com
Définissez le remplacement du point de terminaison de l'API à l'aide de la gcloud CLI.
Définir le remplacement du point de terminaison de l'API à l'aide de la gcloud CLI
Cette étape n'est requise que si vous utilisez la gcloud CLI. Définissez le remplacement du point de terminaison de l'API pour vous assurer que la gcloud CLI achemine correctement les requêtes vers le service Model Armor.
Exécutez la commande suivante pour définir le point de terminaison de l'API pour le service Model Armor.
gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"
Remplacez LOCATION par la région ou l'emplacement multirégional où vous souhaitez utiliser Model Armor.
Configurer la correction du trafic
Pour les serveurs Google et Google Cloud MCP, configurez le nettoyage du trafic via les paramètres de plancher. Pour en savoir plus, consultez Configurer la protection pour les serveurs Google etGoogle Cloud serveurs MCP.
Configurer la journalisation dans les modèles
Les modèles définissent les filtres et les seuils pour différentes catégories de sécurité. Lorsque vous créez ou mettez à jour un modèle Model Armor, vous pouvez spécifier si Model Armor doit consigner certaines opérations. Utilisez les options suivantes dans les métadonnées du modèle :
log_template_operations: valeur booléenne qui vous permet de consigner les opérations de création, de mise à jour, de lecture et de suppression de modèles.log_sanitize_operations: valeur booléenne qui vous permet de consigner l'intégralité du contenu des prompts utilisateur et des réponses du modèle lors des opérations de nettoyage.
Console
Dans la console Google Cloud , accédez à la page Model Armor.
Vérifiez que vous consultez le projet pour lequel vous avez activé Model Armor.
Sur la page Model Armor, cliquez sur Créer un modèle. Pour en savoir plus sur la création de modèles, consultez Créer un modèle Model Armor.
Dans la section Configurer la journalisation, sélectionnez les opérations pour lesquelles vous souhaitez configurer la journalisation.
Cliquez sur Créer.
REST
curl -X POST \
-d '{ "filterConfig": {}, "templateMetadata": { "logTemplateOperations": true, "logSanitizeOperations": true } }' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"
Remplacez les éléments suivants :
PROJECT_ID: ID du projet auquel appartient le modèle.LOCATION: emplacement du modèle.TEMPLATE_ID: ID du modèle.
Python
Pour exécuter ce code, commencez par configurer un environnement de développement Python et installer le SDK Python Model Armor.
request = modelarmor_v1.CreateTemplateRequest( parent="projects/PROJECT_ID/locations/LOCATION", template_id="TEMPLATE_ID", template={ "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID", "filter_config": {}, "template_metadata": { "log_template_operations": True, "log_sanitize_operations": True } } ) response = client.create_template(request=request)
Remplacez les éléments suivants :
PROJECT_ID: ID du projet auquel appartient le modèle.LOCATION: emplacement du modèle.TEMPLATE_ID: ID du modèle.
Configurer la journalisation dans les paramètres de plancher
Lorsque vous appliquez des paramètres de plancher au trafic provenant des modèles Gemini dans Gemini Enterprise Agent Platform et des serveurs Google et Google Cloud MCP de votre projet, les paramètres de plancher définissent les filtres de sécurité pour les opérations de nettoyage. Lorsque vous mettez à jour les paramètres de plancher Model Armor, vous pouvez spécifier si Model Armor doit consigner les opérations de nettoyage.
Vous pouvez activer la journalisation des opérations de nettoyage pour Agent Platform et les serveurs MCP Google et Google Cloud individuellement. Lorsque la journalisation est activée, les journaux incluent le prompt et la réponse (pour Agent Platform) ou les appels d'outils et les réponses d'outils (pour les serveurs MCP), les résultats d'évaluation de Model Armor et d'autres champs de métadonnées.
Les exemples suivants montrent comment activer la journalisation des opérations de nettoyage pour les serveurs MCP Agent Platform et Google et Google Cloud .
Console
Dans la console Google Cloud , accédez à la page Model Armor.
Vérifiez que vous consultez le projet pour lequel vous avez activé Model Armor.
Accédez à l'onglet Paramètres de prix plancher.
Dans la section Journaux, cochez les cases Vertex AI et MCP géré par Google pour activer la journalisation pour chaque service.
Cliquez sur Enregistrer.
gcloud
Utilisez l'option --enable-vertex-ai-cloud-logging pour activer la journalisation pour Agent Platform et l'option --enable-google-mcp-server-cloud-logging pour activer la journalisation pour Google et les serveurs MCP Google Cloud . Pour désactiver la journalisation, utilisez les options --no-enable-vertex-ai-cloud-logging et --no-enable-google-mcp-server-cloud-logging.
L'exemple de commande suivant active la journalisation des opérations de nettoyage pour Agent Platform et les serveurs Google et Google Cloud MCP :
gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-vertex-ai-cloud-logging \
--enable-google-mcp-server-cloud-logging
Remplacez PROJECT_ID par l'ID de votre projet.
REST
Pour activer la journalisation, définissez aiPlatformFloorSetting.enableCloudLogging sur true pour Agent Platform et googleMcpServerFloorSetting.enableCloudLogging sur true pour les serveurs Google et Google Cloud MCP dans la méthode UpdateFloorSetting.
L'exemple de commande suivant active la journalisation des opérations de nettoyage pour Agent Platform et les serveurs MCP Google et Google Cloud :
curl -X PATCH \
-d '{ "aiPlatformFloorSetting":{ "enableCloudLogging": true}, "googleMcpServerFloorSetting":{ "enableCloudLogging": true}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting?updateMask=aiPlatformFloorSetting.enableCloudLogging,googleMcpServerFloorSetting.enableCloudLogging"
Remplacez PROJECT_ID par l'ID de votre projet.
Python
Pour exécuter ce code, commencez par configurer un environnement de développement Python et installer le SDK Model Armor pour Python.
from google.cloud.modelarmor import v1 as modelarmor_v1
from google.protobuf import field_mask_pb2
# TODO: Initialize the ModelArmorClient, "client"
# client = modelarmor_v1.ModelArmorClient()
project_id = "PROJECT_ID"
location = "global"
floor_setting_name = f"projects/{project_id}/locations/{location}/floorSetting"
request = modelarmor_v1.UpdateFloorSettingRequest(
floor_setting=modelarmor_v1.FloorSetting(
name=floor_setting_name,
ai_platform_floor_setting=modelarmor_v1.FloorSetting.AiPlatformFloorSetting(
enable_cloud_logging=True
),
google_mcp_server_floor_setting=modelarmor_v1.FloorSetting.GoogleMcpServerFloorSetting(
enable_cloud_logging=True
),
),
update_mask=field_mask_pb2.FieldMask(
paths=["ai_platform_floor_setting.enable_cloud_logging", "google_mcp_server_floor_setting.enable_cloud_logging"]
)
)
try:
response = client.update_floor_setting(request=request)
print("Successfully updated floor settings logging.")
print(response)
except Exception as e:
print(f"An error occurred: {e}")
Remplacez PROJECT_ID par l'ID de votre projet.
Afficher et filtrer les journaux Model Armor
Pour afficher et filtrer les journaux Model Armor, utilisez l'explorateur de journaux dans Logging :
Dans la console Google Cloud , accédez à la page Explorateur de journaux.
Accéder à l'explorateur de journaux
Pour en savoir plus, consultez Afficher les journaux à l'aide de l'explorateur de journaux.
Dans le volet de requête, saisissez l'une des requêtes suivantes pour filtrer les journaux Model Armor :
Pour afficher tous les journaux Model Armor, y compris les journaux d'audit et les journaux des opérations de nettoyage :
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"Pour n'afficher que les journaux d'audit Model Armor :
protoPayload.serviceName="modelarmor.googleapis.com"Pour obtenir la liste de tous les noms de services et types de ressources surveillées, consultez Ressources et services surveillés.
Pour n'afficher que les journaux Model Armor pour les opérations de nettoyage :
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"Pour affiner davantage les journaux des opérations de nettoyage, vous pouvez spécifier un nom de client, un ID de corrélation ou un libellé d'évaluation de règle d'exclusion (preview) dans la requête :
Utiliser un nom de client : lorsque Model Armor s'intègre à des services tels que Gemini Enterprise Agent Platform ou Gemini Enterprise, vous pouvez utiliser le nom du client pour filtrer les journaux d'une intégration spécifique.
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"Utiliser un ID de corrélation :
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"Remplacez les éléments suivants :
CLIENT_NAME: nom de votre client. Utilisez l'une des valeurs suivantes :CLIENT_NAME_UNSPECIFIED: valeur par défaut, utilisée lorsque le nom du client n'est pas spécifié.VERTEX_AI: pour l'intégration à Gemini Enterprise Agent Platform.LOAD_BALANCER: pour l'intégration à l'aide de l'équilibreur de charge en tant qu'extension de service.LANGCHAIN: pour l'intégration à LangChain.GEMINI_ENTERPRISE_BUSINESS: pour l'intégration à Gemini Enterprise – édition Business.GOOGLE_MCP_SERVER: pour l'intégration avec Google et les serveurs MCP gérés par Google.AGENT_GATEWAY: pour l'intégration à Agent Gateway.GEMINI_ENTERPRISE_NON_BUSINESS: pour l'intégration aux éditions Gemini Enterprise autres que Business (Standard, Plus et Frontline).SECURE_WEB_PROXY: pour l'intégration à Secure Web Proxy.
CORRELATION_ID: identifiant unique que vous générez pour une requête spécifique.
Utilisation des libellés de règle d'exclusion (bêta) : lorsqu'une règle d'exclusion remplace un résultat de filtre ou lorsque Model Armor ignore l'évaluation de la règle d'exclusion, Model Armor renseigne les champs
labelsde premier niveau facultatifs suivants sur les entrées de journalmodelarmor.googleapis.com/SanitizeOperation:modelarmor.googleapis.com/exclusion_rule_overridden_filters: liste de filtres séparés par une virgule dont les résultatsMATCH_FOUNDouEXECUTION_SKIPPEDont été remplacés parNO_MATCH_FOUND, car une règle d'exclusion correspondait.modelarmor.googleapis.com/exclusion_rule_skipped_filters: liste de filtres séparés par une virgule dont l'évaluation de la règle d'exclusion a été ignorée (par exemple, lorsqu'une entrée dépasse la limite de charge utile d'exclusion de 130 000 jetons (0,5 Mo)).
Utilisez les exemples de requêtes suivants pour filtrer les journaux de nettoyage par libellés de règle d'exclusion :
- Pour trouver les requêtes pour lesquelles un résultat de filtre a été ignoré par une règle d'exclusion :
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters":"FILTER_NAME"- Pour rechercher les requêtes pour lesquelles une détection d'injection de prompt et de jailbreak a été ignorée par une règle d'exclusion :
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters"="PROMPT_INJECTION_AND_JAILBREAK"- Pour trouver les requêtes pour lesquelles l'évaluation des règles d'exclusion a été ignorée :
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/exclusion_rule_skipped_filters"="FILTER_NAME"Remplacez
FILTER_NAMEpar le nom du filtre (PROMPT_INJECTION_AND_JAILBREAKouRESPONSIBLE_AI).
Corréler les journaux et les événements associés
Pour mettre en corrélation les journaux et les événements d'une interaction spécifique, vous pouvez utiliser un ID de corrélation client Model Armor. Cet ID est un identifiant unique que vous générez (par exemple, un UUID) et qui suit une requête spécifique dans votre système. Pour définir un ID de corrélation client dans un en-tête curl, utilisez l'option -H pour inclure un en-tête personnalisé MA-Client-Correlation-Id dans votre requête.
Voici un exemple de format :
uuid=$(uuidgen) \
curl -X POST -d '{"userPromptData": { "text": "USER_PROMPT" } }' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "MA-Client-Correlation-Id:${uuid}" \
"https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeUserPrompt"
curl -X POST \
-d '{"modelResponseData": { "text": "MODEL_RESPONSE" }, "userPrompt": "USER_PROMPT" }' \
-H "Content-Type: application/json" \
-H "MA-Client-Correlation-Id:${uuid}" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeModelResponse"
Remplacez les éléments suivants :
PROJECT_ID: ID du projet auquel appartient le modèle.LOCATION: emplacement du modèle.TEMPLATE_ID: ID du modèle.USER_PROMPT: prompt fourni au modèle.MODEL_RESPONSE: réponse reçue du modèle.
Journaux de plate-forme et Cloud Audit Logs
Il est important de faire la distinction entre les journaux que vous pouvez activer dans un modèle Model Armor ou dans les paramètres de base, et Cloud Audit Logs.
| Fonctionnalité | Cloud Audit Logs | Journaux de plate-forme |
|---|---|---|
| Objectif principal | Audit de sécurité des appels d'API (qui a fait quoi et quand) et surveillance de la conformité. | Surveillance opérationnelle, débogage et analyse détaillée des événements de nettoyage des données. |
| Opérations d'API capturées | Opérations de création, de lecture, de mise à jour, de suppression et de listage sur les modèles et les paramètres de prix plancher. Les opérations de nettoyage (SanitizeUserPrompt, SanitizeModelResponse) sont consignées en tant que métadonnées. |
Capture toutes les requêtes telles que SanitizeUserPrompt et SanitizeModelResponse. |
| Contenu de la charge utile | N'inclut pas le texte réel du prompt utilisateur ou de la réponse du modèle pour les opérations de nettoyage. Contient des métadonnées telles que l'appelant, la méthode, la ressource, le code temporel et l'état. | Inclut la charge utile complète, telle que le texte de la requête ou de la réponse, les résultats du filtrage et d'autres détails de l'assainissement. |
| Mécanisme d'activation | Paramètres standards des journaux d'audit IAM Google Cloud pour l'API Model Armor. Les journaux d'accès aux données doivent souvent être activés explicitement. Les journaux d'audit des opérations sur les modèles sont générés automatiquement. | Activé en définissant l'indicateur booléen log_sanitize_operations dans les métadonnées du modèle ou les paramètres de plancher. |
| Conditions de journalisation | Enregistre automatiquement les opérations de création, de lecture, de mise à jour, de suppression et de listage sur les modèles et les paramètres de prix plancher. | Enregistre les données (prompts utilisateur et réponses du modèle) pour toutes les requêtes du plan de données, que la protection des données sensibles soit activée ou non, ou qu'un paramètre de filtre ait été mis en correspondance ou non. |
| Volume et coût des journaux | Généralement plus petits et plus prévisibles, ils sont soumis à la tarification standard de Cloud Logging. | Ils peuvent être très volumineux et entraîner des coûts Cloud Logging importants en raison de la taille des charges utiles et de la fréquence d'utilisation. Les charges utiles volumineuses peuvent être divisées en plusieurs entrées de journal. |
| Points à noter concernant la sécurité | Relativement sûr, car les données de charge utile ne sont pas journalisées. Nécessite des autorisations IAM spéciales pour l'accès (par exemple, des rôles IAM spécifiques pour afficher les journaux d'audit). | Contient des données utilisateur potentiellement sensibles (informations permettant d'identifier personnellement l'utilisateur, informations confidentielles). Accessible à toute personne disposant d'autorisations d'affichage des journaux (par exemple, roles/logging.privateLogViewer). |
| Recommandation | Activez-le pour la surveillance générale de la sécurité et de la conformité. | Non recommandé pour les données de production ou sensibles, sauf si elles sont acheminées de manière sécurisée vers un récepteur avec contrôle des accès (par exemple, BigQuery avec IAM strict). |
L'activation de la journalisation dans un modèle écrit les prompts et les réponses bruts dans Logging. Ces données peuvent inclure des données utilisateur sensibles, des informations permettant d'identifier personnellement l'utilisateur ou des informations confidentielles. Un trafic élevé et des charges utiles volumineuses peuvent entraîner des coûts de journalisation importants et des volumes de journaux élevés susceptibles de dépasser les limites et de nécessiter une gestion minutieuse.
Identité de l'appelant dans les journaux d'audit
Lorsque vous affichez les journaux d'audit, Cloud Audit Logs capture l'identité de l'appelant dans le champ protoPayload.authenticationInfo.principalEmail. L'identité enregistrée dépend de la manière dont l'API Model Armor est appelée :
- Appel direct de l'API : si un utilisateur ou un compte de service appelle directement l'API Model Armor (par exemple, à l'aide de
gcloud, de bibliothèques clientes ou d'API REST),principalEmailcontient l'adresse e-mail de cet utilisateur ou de ce compte de service. - Appel via un service Google Cloud intégré : si Model Armor s'intègre à un autre serviceGoogle Cloud , tel que Gemini Enterprise Agent Platform,
principalEmailcontient l'identité de ce service, qui est généralement un compte de service géré par Google. Le format des agents de service estservice-PROJECT_NUMBER@SERVICE_NAME.. Par exemple, un appel provenant d'une fonctionnalité de Gemini Enterprise Agent Platform utilise un agent de service Gemini Enterprise Agent Platform.
Pour distinguer les appelants, examinez le champ principalEmail dans l'entrée de journal d'audit. Les appels provenant d'utilisateurs finaux ou de comptes de service gérés par l'utilisateur affichent leurs adresses e-mail, tandis que les appels via d'autres services Google Cloud affichent les adresses e-mail des comptes de service gérés par Google.