Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Configurer la journalisation

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 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é. 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.
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 console Google Cloud , activez Cloud Shell.

Activer 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 de 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.
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.
```
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 avec Model Armor et que vous souhaitez utiliser une région ou un emplacement multirégional autre que l'emplacement multirégional par défaut us. 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 l'emplacement multirégional où vous souhaitez utiliser Model Armor.

Configurer la correction du trafic

Pour les serveurs MCP Google et Google Cloud , configurez la suppression des données sensibles 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 indicateurs suivants 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.

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 : 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 enregistre les opérations de nettoyage.

Vous pouvez activer la journalisation des opérations de nettoyage pour Agent Platform et les serveurs Google et Google Cloud MCP 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.

Accéder à 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 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 nettoyage pour Agent Platform et les serveurs MCP Google et Google Cloud :

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 Python Model Armor.

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 service 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'extension Load Balancer as a 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 MCP Google et 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 Règle d'exclusion (Aperçu) : lorsqu'une règle d'exclusion remplace le résultat d'un filtre ou lorsque Model Armor ignore l'évaluation d'une règle d'exclusion, Model Armor renseigne les champs labels facultatifs de premier niveau suivants dans les entrées de journal modelarmor.googleapis.com/SanitizeOperation :
    - modelarmor.googleapis.com/exclusion_rule_overridden_filters : liste de filtres séparés par une virgule dont les résultats MATCH_FOUND ou EXECUTION_SKIPPED ont été remplacés par NO_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 des règles 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 étiquettes de règle d'exclusion :
    - Pour trouver les demandes dont le résultat de filtre a été remplacé 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 trouver les requêtes pour lesquelles une détection d'injection de prompt et de jailbreaking 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 demandes 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_NAME par le nom du filtre (PROMPT_INJECTION_AND_JAILBREAK ou RESPONSIBLE_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. 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 Cloud Audit Logs

Il est important de faire la distinction entre les journaux que vous pouvez activer dans un modèle ou des paramètres de seuil 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 nettoyage des données.
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 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, comme 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 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 des 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é mis en correspondance.
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 cette option 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 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 informations 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 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), principalEmail contient 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. 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 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 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.

Étapes suivantes

Corréler les journaux Model Armor avec les journaux Gemini Enterprise

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 la correction 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

Étapes suivantes

Configurer la journalisation