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

Configura el registro

En este documento, se describe cómo configurar Model Armor para registrar las operaciones siguientes:

Operaciones que crean, actualizan o borran una plantilla
Operaciones que limpian un prompt del usuario o una respuesta del modelo

Model Armor usa registros de auditoría para registrar las actividades de gestión y de administración de recursos. Para obtener más información, consulta Registro de auditoría de Model Armor.

Para obtener información sobre los precios de los registros, consulta los precios de Cloud Logging. También es posible que se apliquen cargos por uso de Model Armor según el volumen de datos procesados. Consulta los precios de Model Armor para obtener más información.

Antes de comenzar

Antes de comenzar, completa las siguientes tareas.

Obtén los permisos necesarios

Para obtener los permisos que necesitas a la hora de configurar el registro de Model Armor, pídele a tu administrador que te otorgue el rol de IAM de Administrador de Model Armor (roles/modelarmor.admin) en la plantilla de Model Armor. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Habilita las APIs

Debes habilitar la API de Model Armor para poder usar Model Armor.

Console

Habilita la API de Model Armor.
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.
Habilitar la API
Elige el proyecto en el que quieres activar Model Armor.

gcloud

Antes de empezar, sigue estos pasos a través de la Google Cloud CLI con la API de Model Armor:

En la consola de Google Cloud , activa Cloud Shell.

Activa Cloud Shell

En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell que muestra una ventana emergente con una línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.
Configura la anulación del extremo de API con la gcloud CLI.

Cómo configurar la anulación del extremo de API con la gcloud CLI

Este paso solo es necesario si usas gcloud CLI para habilitar la API de Model Armor. Debes configurar manualmente la anulación del extremo de API para garantizar que la gcloud CLI enrute correctamente las solicitudes al servicio de Model Armor.

Ejecuta el siguiente comando para configurar el extremo de API del servicio de Model Armor.

gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

Reemplaza LOCATION por la región en la que quieres usar Model Armor.

Configura la limpieza del tráfico

En el caso de los servidores de Google y Google Cloud MCP, configura la limpieza del tráfico a través de la configuración mínima. Para obtener más información, consulta Cómo configurar la protección para los servidores de Google y deGoogle Cloud MCP.

Configura el registro en plantillas

Las plantillas definen los filtros y umbrales para diferentes categorías de seguridad. Cuando creas o actualizas una plantilla de Model Armor, puedes especificar si este debe registrar ciertas operaciones. Usa las marcas siguientes en los metadatos de la plantilla:

log_template_operations: Es un valor booleano que te permite registrar las operaciones de creación, actualización, lectura y eliminación de plantillas.
log_sanitize_operations: Es un valor booleano que te permite registrar el contenido completo de las instrucciones del usuario y las respuestas del modelo durante las operaciones de limpieza.

Console

En la consola de Google Cloud , accede a la página de Model Armor.

Acceder a Model Armor
Verifica que estés viendo el proyecto en el que activaste Model Armor.
En la página de Model Armor, haz clic en Crear plantilla. Para obtener más información sobre cómo crear plantillas, consulta Crea una plantilla de Model Armor.
En la sección Configura el registro, elige las operaciones para las que quieres configurar el registro.
Haz clic en Crear.

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"

Reemplaza lo siguiente:

PROJECT_ID: Es el ID del proyecto al que pertenece la plantilla.
LOCATION: Es la ubicación de la plantilla.
TEMPLATE_ID: Es el ID de la plantilla.

Python

Para ejecutar este código, primero configura un entorno de desarrollo de Python y, luego, instala el SDK de Python para 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)

Reemplaza lo siguiente:

PROJECT_ID: Es el ID del proyecto al que pertenece la plantilla.
LOCATION: Es la ubicación de la plantilla.
TEMPLATE_ID: Es el ID de la plantilla.

Configura el registro en la configuración mínima

Cuando aplicas la configuración mínima en el tráfico de los modelos de Gemini en la plataforma de agentes de Gemini Enterprise y los servidores de Google y Google Cloud MCP dentro de tu proyecto, la configuración mínima define los filtros de seguridad para las operaciones de saneamiento. Cuando actualizas la configuración mínima de Model Armor, puedes especificar si Model Armor debe registrar las operaciones de limpieza.

Puedes habilitar el registro de las operaciones de limpieza para los servidores de Agent Platform y de Google y Google Cloud MCP de forma individual. Cuando se habilita, los registros incluyen el prompt y la respuesta (para la Plataforma de agentes) o las llamadas y respuestas de herramientas (para los servidores de MCP), los resultados de la evaluación de Model Armor y los campos de metadatos adicionales.

En los siguientes ejemplos, se muestra cómo habilitar el registro de operaciones de limpieza para los servidores de la plataforma del agente y de Google y Google Cloud MCP.

Console

En la consola de Google Cloud , accede a la página de Model Armor.

Acceder a Model Armor
Verifica que estés viendo el proyecto en el que activaste Model Armor.
Navega a la pestaña Configuración de piso.
En la sección Registros, selecciona las casillas de verificación Vertex AI y MCP administrado por Google para habilitar el registro de cada servicio.
Haz clic en Guardar.

gcloud

Usa la marca --enable-vertex-ai-cloud-logging para habilitar el registro de Agent Platform y la marca --enable-google-mcp-server-cloud-logging para habilitar el registro de los servidores de Google y Google Cloud de MCP. Para inhabilitar el registro, usa las marcas --no-enable-vertex-ai-cloud-logging y --no-enable-google-mcp-server-cloud-logging.

El siguiente comando de ejemplo habilita el registro de operaciones de limpieza para los servidores de la plataforma del agente y de Google y 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

Reemplaza PROJECT_ID por el ID de tu proyecto.

REST

Para habilitar el registro, establece aiPlatformFloorSetting.enableCloudLogging en true para la Plataforma de agentes y googleMcpServerFloorSetting.enableCloudLogging en true para los servidores de Google y Google Cloud de MCP en el método UpdateFloorSetting.

El siguiente comando de ejemplo habilita el registro de operaciones de limpieza para los servidores de la plataforma del agente y de Google y 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"

Reemplaza PROJECT_ID por el ID de tu proyecto.

Python

Para ejecutar este código, primero configura un entorno de desarrollo de Python y, luego, instala el SDK de Python para 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}")

Reemplaza PROJECT_ID por el ID de tu proyecto.

Visualiza y filtra los registros de Model Armor

Para ver y filtrar los registros de Model Armor, usa el Explorador de registros en Logging:

En la consola de Google Cloud , accede a la página Explorador de registros.

Ve al Explorador de registros

Para obtener más información, consulta Visualiza registros con el Explorador de registros.
En el panel de consultas, ingresa una de las siguientes consultas para filtrar los registros de Model Armor:
- Para ver todos los registros de Model Armor, incluidos los registros de auditoría y los registros de operaciones de limpieza, haz lo siguiente:
```
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
- Sigue estos pasos para ver solo los registros de auditoría de Model Armor:
```
protoPayload.serviceName="modelarmor.googleapis.com"
```
  Para obtener una lista de todos los nombres de servicios y tipos de recurso supervisado, consulta Recursos y servicios supervisados.
- Para ver solo los registros de Model Armor de las operaciones de limpieza, haz lo siguiente:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
  Para definir mejor los registros de operaciones de limpieza, puedes especificar un nombre de cliente o un ID de correlación en la consulta.
  - Uso de un nombre de cliente: Cuando Model Armor se integra con servicios como Agent Platform de Gemini Enterprise o Gemini Enterprise, puedes usar el nombre del cliente para filtrar los registros de una integración específica.
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
```
  - Usa un ID de correlación:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
```
  Reemplaza lo siguiente:
  - CLIENT_NAME: Es el nombre de tu cliente, por ejemplo, VERTEX_AI.
  - CORRELATION_ID: Es el identificador único que generas para una solicitud específica.

Correlaciona registros y eventos relacionados

Para correlacionar los registros y eventos de una interacción específica, puedes usar un ID de correlación del cliente de Model Armor. Este ID es un identificador único que generas (por ejemplo, un UUID) y que hace un seguimiento de una solicitud específica en tu sistema. Para establecer un ID de correlación del cliente en un encabezado curl, usa la opción -H para incluir un encabezado personalizado MA-Client-Correlation-Id en tu solicitud.

Este es el formato de la muestra:

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"

Reemplaza los parámetros que se indican a continuación:

PROJECT_ID: Es el ID del proyecto al que pertenece la plantilla.
LOCATION: Es la ubicación de la plantilla.
TEMPLATE_ID: Es el ID de la plantilla.
USER_PROMPT: Es el prompt proporcionado al modelo.
MODEL_RESPONSE: Es la respuesta que se recibió del modelo.

Registros de la plataforma en comparación con los Registros de auditoría de Cloud

Es importante distinguir entre los registros que puedes habilitar en una plantilla o configuración mínima de Model Armor y los registros de auditoría de Cloud.

Función	Registros de auditoría de Cloud	Registros de plataforma
Propósito principal	Auditoría de seguridad de las llamadas a la API (quién hizo qué y cuándo) y supervisión del cumplimiento.	Supervisión operativa, depuración y análisis detallado de los eventos de saneamiento.
Operaciones de la API capturadas	Operaciones de creación, lectura, actualización, eliminación y enumeración en plantillas y parámetros de configuración de pisos. Las operaciones de limpieza (`SanitizeUserPrompt`, `SanitizeModelResponse`) se registran como metadatos.	Captura todas las solicitudes, como `SanitizeUserPrompt` y `SanitizeModelResponse`.
Contenido de la carga útil	No incluye el texto real del mensaje del usuario ni de la respuesta del modelo para las operaciones de limpieza. Contiene metadatos como el llamador, el método, el recurso, la marca de tiempo y el estado.	Incluye la carga útil completa, como el texto de la instrucción o la respuesta, los resultados del filtro y otros detalles de la sanitización.
Mecanismo de habilitación	Es la configuración estándar de los registros de auditoría de IAM para la API de Model Armor. Google Cloud Los registros de acceso a los datos suelen requerir una habilitación explícita. Los registros de auditoría de las operaciones de plantillas se generan automáticamente.	Se habilita configurando la marca booleana `log_sanitize_operations` en los metadatos de la plantilla o en la configuración mínima.
Condiciones de registro	Registra automáticamente las operaciones de creación, lectura, actualización, eliminación y enumeración en plantillas y configuración mínima.	Registra los datos (instrucciones del usuario y respuestas del modelo) de cualquier solicitud del plano de datos, independientemente de si Sensitive Data Protection está habilitado o si se encontró alguna configuración de filtro.
Volumen y costo de los registros	Por lo general, son más pequeños y predecibles, y se aplican los precios estándar de Cloud Logging.	Pueden ser muy grandes y voluminosos, lo que podría generar costos significativos de Cloud Logging debido a las cargas útiles grandes y al uso frecuente. Las cargas útiles grandes se pueden dividir en varias entradas de registro.
Consideraciones de seguridad	Es relativamente seguro, ya que no se registran los datos de la carga útil. Requiere permisos especiales de IAM para acceder (por ejemplo, roles específicos de IAM para ver los registros de auditoría).	Contiene datos del usuario potencialmente sensibles (PII, información confidencial). Cualquier persona con permisos para ver registros puede acceder a él (por ejemplo, `roles/logging.privateLogViewer`).
Recomendación	Habilita la supervisión general de la seguridad y el cumplimiento.	No se recomienda para datos sensibles o de producción, a menos que se enruten de forma segura a un receptor con control de acceso (por ejemplo, BigQuery con IAM estricta).

Si habilitas el registro en una plantilla, se escribirán las instrucciones y las respuestas sin procesar en Logging. Estos datos pueden incluir información sensible del usuario, información de identificación personal (PII) o información confidencial. El tráfico alto y las cargas útiles grandes pueden generar costos de registro considerables y la posibilidad de que los volúmenes de registros grandes superen los límites y requieran una administración cuidadosa.

Identidad del llamador en los registros de auditoría

Cuando ves los registros de auditoría, Registros de auditoría de Cloud captura la identidad del llamador en el campo protoPayload.authenticationInfo.principalEmail. La identidad registrada depende de cómo se llame a la API de Model Armor:

Invocación directa de la API: Si un usuario o una cuenta de servicio llama directamente a la API de Model Armor (por ejemplo, con gcloud, bibliotecas cliente o APIs de REST), principalEmail contiene la dirección de correo electrónico de ese usuario o cuenta de servicio.
Invocación a través de un servicio Google Cloud integrado: Si Model Armor se integra con otro servicioGoogle Cloud , como Agent Platform de Gemini Enterprise, principalEmailcontiene la identidad de ese servicio, que suele ser una cuenta de servicio administrada por Google. El formato de los agentes de servicio es service-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com. Por ejemplo, una llamada que se origina en una función de Gemini Enterprise Agent Platform usa un agente de servicio de Gemini Enterprise Agent Platform.

Para distinguir entre los llamadores, examina el campo principalEmail en la entrada de registro de auditoría. Las llamadas de los usuarios finales o las cuentas de servicio administradas por el usuario muestran sus direcciones de correo electrónico, mientras que las llamadas a través de otros servicios Google Cloud muestran las direcciones de correo electrónico de las cuentas de servicio administradas por Google.

Configura el registro Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Obtén los permisos necesarios

Habilita las APIs

Console

gcloud

Cómo configurar la anulación del extremo de API con la gcloud CLI

Configura la limpieza del tráfico

Configura el registro en plantillas

Console

REST

Python

Configura el registro en la configuración mínima

Console

gcloud

REST

Python

Visualiza y filtra los registros de Model Armor

Correlaciona registros y eventos relacionados

Registros de la plataforma en comparación con los Registros de auditoría de Cloud

Identidad del llamador en los registros de auditoría

Configura el registro