Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Configurer la journalisation

Ce document explique comment configurer Model Armor pour enregistrer 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 la section Journaux 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 de 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.
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.
Activer l'API
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 Google Cloud console, activez Cloud Shell.

Activer Cloud Shell

En bas de la Google Cloud console, une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement de shell dans lequel la Google Cloud CLI est déjà installée, 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 pour activer l'API Model Armor. 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 dans laquelle vous souhaitez utiliser Model Armor.

Configurer le nettoyage 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 des serveurs Google et Google 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 enregistre 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 d'enregistrer l'intégralité du contenu des prompts utilisateur et des réponses de modèle lors des opérations de nettoyage.

Console

Dans la Google Cloud console, accédez à la page Model Armor.

Accéder à 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 : l'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 installez le SDK Model Armor pour Python.

   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 : l'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 de 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 nettoyage. Lorsque vous mettez à jour les paramètres de plancher de 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 Google et Google Cloud les serveurs MCP 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 Agent Platform et Google et Google Cloud les serveurs MCP.

Console

Dans la Google Cloud console, accédez à la page Model Armor.

Accéder à Model Armor
Vérifiez que vous consultez le projet pour lequel vous avez activé Model Armor.
Accédez à l'onglet Paramètres de plancher.
Dans la section Journaux, cochez les cases Vertex AI et Serveur MCP géré par Google pour activer la journalisation de chaque service.
Cliquez sur Enregistrer.

gcloud

Utilisez l'indicateur --enable-vertex-ai-cloud-logging pour activer la journalisation pour Agent Platform, et l'indicateur --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 indicateurs --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 Google et Google Cloud les serveurs 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 Google et Google Cloud les serveurs 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 installez 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 Google Cloud console, accédez à la page Explorateur de journaux.

Accéder à l'explorateur de journaux

Pour en savoir plus, consultez la page Afficher les journaux à l'aide de l'explorateur de journaux.
Dans le volet 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 nettoyage :
```
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és, consultez la page Ressources surveillées et services.
- 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 nettoyage, 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 à Gemini Enterprise – Édition Business.
    - GOOGLE_MCP_SERVER : pour l'intégration aux serveurs Google et 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, 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.

Corréler les journaux et les événements associés

Pour corréler 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) 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 l'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 : l'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 des paramètres de plancher 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, quand) et surveillance de la conformité.	Surveillance opérationnelle, débogage et analyse détaillée des événements de nettoyage.
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 enregistré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 prompt utilisateur ni le texte de 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, l'horodatage et l'état.	Inclut la charge utile complète, telle que le texte du prompt ou de la réponse, les résultats du filtre et d'autres détails du nettoyage.
Mécanisme d'activation	Paramètres de journaux d'audit Standard Google Cloud 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 de modèle 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 liste sur les modèles et les paramètres de plancher.	Enregistre les données (prompts utilisateur et réponses de modèle) pour toutes les requêtes de plan de données, que Sensitive Data Protection soit activé ou qu'un paramètre de filtre ait été mis en correspondance.
Volume et coût des journaux	Généralement plus petits et plus prévisibles, entraînant une tarification standard de Cloud Logging.	Peut être très volumineux, ce qui peut entraîner des coûts importants pour Cloud Logging en raison de charges utiles volumineuses et d'une utilisation fréquente. 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 enregistré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 d'autorisations d'affichage des journaux (par exemple, `roles/logging.privateLogViewer`).
Recommandation	Activer pour la surveillance générale de la sécurité et de la conformité.	Non recommandé pour la production ou les données 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 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 un risque de dépassement des limites de volume de journaux, ce qui nécessite une gestion minutieuse.

Identité de l'appelant dans les journaux d'audit

Lorsque vous affichez des 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), principalEmail contient l'adresse e-mail de cet utilisateur ou de ce compte de service.
Appel via un service intégré Google Cloud : si Model Armor s'intègre à un autre Google Cloud service tel que Gemini Enterprise Agent Platform, alors principalEmail contient l'identité de ce service, qui est généralement un compte de service géré par Google. Le format des agents de service est service-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 Google Cloud services affichent les adresses e-mail des comptes de service gérés par Google.

Configurer la journalisation Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Avant de commencer

Obtenir les autorisations requises

Activer les API

Console

gcloud

Définir le remplacement du point de terminaison de l'API à l'aide de la gcloud CLI

Configurer le nettoyage du trafic

Configurer la journalisation dans les modèles

Console

REST

Python

Configurer la journalisation dans les paramètres de plancher

Console

gcloud

REST

Python

Afficher et filtrer les journaux Model Armor

Corréler les journaux et les événements associés

Journaux de plate-forme et Cloud Audit Logs

Identité de l'appelant dans les journaux d'audit

Configurer la journalisation