Ce document explique comment configurer Model Armor pour enregistrer les opérations suivantes :
- Opérations qui créent, modifient ou suppriment un modèle
- Opérations qui nettoient un prompt utilisateur ou une réponse du 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 les tarifs 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 les API, vous devez disposer de l'autorisation
serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au 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 :
Dans la console Google Cloud , activez Cloud Shell.
En bas de la console Google Cloud , une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.
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 avec Model Armor et que vous souhaitez utiliser une région ou une multirégion autre que la multirégion us par défaut. Vous devez définir manuellement 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 la région multiple dans laquelle vous souhaitez utiliser Model Armor.
Configurer l'assainissement du trafic
Pour les serveurs Google et Google Cloud MCP, configurez l'assainissement du trafic à l'aide des paramètres de plancher. Pour en savoir plus, consultez Configurer la protection pour les serveurs Google etGoogle Cloud 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 indicateurs suivants dans les métadonnées du modèle :
log_template_operations: valeur booléenne qui vous permet d'enregistrer 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 requêtes 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, ces paramètres définissent les filtres de sécurité pour les opérations de désinfection. Lorsque vous mettez à jour les paramètres de plancher Model Armor, vous pouvez spécifier si Model Armor enregistre 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. Lorsqu'elle est activée, les journaux incluent le prompt et la réponse (pour Agent Platform) ou les appels et 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 Agent Platform et les serveurs MCP 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 du 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 l'Agent Platform et l'option --enable-google-mcp-server-cloud-logging pour activer la journalisation pour les serveurs Google et Google Cloud MCP. 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 désinfection pour les serveurs Agent Platform et 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 les serveurs Agent Platform et Google et Google Cloud MCP :
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 d'opérations de désinfection :
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"Pour afficher uniquement les journaux d'audit Model Armor :
protoPayload.serviceName="modelarmor.googleapis.com"Pour obtenir la liste de tous les noms de service et types de ressources surveillées, consultez Ressources et services surveillés.
Pour afficher uniquement 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 d'opérations de désinfection, vous pouvez spécifier un nom de client ou un ID de corrélation 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 à l'édition Business de Gemini Enterprise.GOOGLE_MCP_SERVER: pour l'intégration aux serveurs MCP gérés par Google.AGENT_GATEWAY: Pour l'intégration à Agent Gateway.GEMINI_ENTERPRISE_NON_BUSINESSPour l'intégration avec les éditions Gemini Enterprise autres que Business (Standard, Plus, Frontline).SECURE_WEB_PROXYPour l'intégration à Secure Web Proxy.
CORRELATION_ID: identifiant unique que vous générez pour une demande spécifique.
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. Il s'agit d'un identifiant unique que vous générez (par exemple, un UUID) et qui permet de suivre 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: le prompt fourni au modèle.MODEL_RESPONSE: réponse reçue du modèle.
Journaux de plate-forme et journaux d'audit Cloud
Il est important de faire la distinction entre les journaux que vous pouvez activer dans un modèle ou des paramètres de plancher Model Armor et les journaux d'audit Cloud.
| Fonctionnalité | Cloud Audit Logs | Journaux de plate-forme |
|---|---|---|
| Objectif principal | Audit de sécurité des appels d'API (qui a fait quoi, quand) et surveillance de la conformité. | Surveillance opérationnelle, débogage et analyse détaillée des événements de désinfection. |
| Opérations d'API capturées | Opérations de création, de lecture, de mise à jour, de suppression et de liste sur les modèles et les paramètres de 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 du prompt de l'utilisateur ni 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 filtre et d'autres détails de la désinfection. |
| Mécanisme d'activation | Paramètres standards Google Cloud des journaux d'audit IAM pour l' API Model Armor. Les journaux d'accès aux données nécessitent souvent une activation explicite. Les journaux d'audit pour les opérations sur les modèles sont générés automatiquement. | Cette fonctionnalité est activée 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 liste sur les modèles et les paramètres de plancher. | Consigne les données de journaux (requêtes utilisateur et réponses du modèle) pour toutes les requêtes du plan de données, que Sensitive Data Protection soit activé ou qu'un paramètre de filtre ait été trouvé. |
| 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 y accéder (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 des 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 à accès contrôlé (par exemple, BigQuery avec un IAM strict). |
L'activation de la journalisation dans un modèle écrit les prompts et les réponses bruts dans la journalisation. Ces données peuvent inclure des données utilisateur sensibles, des informations permettant d'identifier personnellement l'utilisateur (PII) 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 potentiellement importants qui dépassent les limites et nécessitent une gestion minutieuse.
Identité de l'appelant dans les journaux d'audit
Lorsque vous consultez 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. - Invocation 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. Les agents de service sont au formatservice-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com. Par exemple, un appel provenant d'une fonctionnalité Gemini Enterprise Agent Platform utilise un agent de service Gemini Enterprise Agent Platform.
Pour faire la distinction entre 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 leur adresse 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.