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 se pueden aplicar cargos por el uso de Model Armor según el volumen de datos procesados. Consulta los precios de Model Armor para obtener más detalles.
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
Para poder usar Model Armor, debes habilitar su API.
Console
Habilita la API de Model Armor si aún no está habilitada.
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el permiso
serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.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:
Instala Google Cloud CLI y, luego, accede a gcloud CLI con tu identidad federada. Después de acceder, inicializa Google Cloud CLI con el siguiente comando:
gcloud initHabilita la API de Model Armor si aún no está habilitada:
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el permiso
serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.gcloud services enable modelarmor.googleapis.com
Configura la anulación del extremo de API con la gcloud CLI.
Configura la anulación del extremo de API con gcloud CLI
Este paso solo es necesario si usas gcloud CLI. Establece la anulación del extremo de API para asegurarte de que gcloud CLI enrute correctamente las solicitudes al servicio de Model Armor.
Ejecuta el comando siguiente 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 o multirregión en la que
quieres usar Model Armor.
Configura la limpieza del tráfico
Para 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 Configura la protección para los servidores de Google y Google Cloud servidores de 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.
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 de precios mínimos
Cuando aplicas de manera forzosa la configuración mínima al tráfico de los modelos de Gemini en Gemini Enterprise Agent Platform y los servidores de MCP de Google y Google Cloud dentro de tu proyecto, la configuración mínima define los filtros de seguridad para las operaciones de limpieza. Cuando actualizas la configuración mínima de Model Armor, puedes especificar si este debe registrar las operaciones de limpieza.
Puedes habilitar el registro de las operaciones de limpieza para Agent Platform y los servidores de MCP de Google y Google Cloud de forma individual. Cuando se habilita, los registros incluyen la instrucción y la respuesta (para Agent Platform) o las llamadas a la herramienta y las respuestas a herramientas (para 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 la plataforma de agentes y los servidores de Google y Google Cloud MCP.
Console
En la consola de Google Cloud , accede a la página de Model Armor.
Verifica que estés viendo el proyecto en el que activaste Model Armor.
Navega a la pestaña Configuración de pisos.
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 servidores de MCP. Para inhabilitar
el registro, usa las marcas --no-enable-vertex-ai-cloud-logging y
--no-enable-google-mcp-server-cloud-logging.
En el siguiente comando de ejemplo, se habilita el registro de operaciones de limpieza para los servidores de Agent Platform 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 Agent Platform y googleMcpServerFloorSetting.enableCloudLogging
en true para los servidores de Google y Google Cloud servidores de MCP en el método UpdateFloorSetting.
En el siguiente comando de ejemplo, se habilita el registro de operaciones de limpieza para Agent Platform y los servidores 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.
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"Para ver solo los registros de auditoría de Model Armor, haz lo siguiente:
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, un ID de correlación o una etiqueta de evaluación de regla de exclusión (versión preliminar) en la consulta:
Usa un nombre de cliente: Cuando Model Armor se integra en servicios como Gemini Enterprise Agent Platform 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. Usa uno de los siguientes valores:CLIENT_NAME_UNSPECIFIED: Es el valor predeterminado que se usa cuando no se especifica el nombre del cliente.VERTEX_AI: Para la integración con Gemini Enterprise Agent Platform.LOAD_BALANCER: Para la integración con el balanceador de cargas como una extensión de servicio.LANGCHAIN: Para la integración en LangChain.GEMINI_ENTERPRISE_BUSINESS: Para la integración con Gemini Enterprise - edición Business.GOOGLE_MCP_SERVER: Para la integración con Google y los servidores de MCP administrados por Google.AGENT_GATEWAY: Para la integración con Agent Gateway.GEMINI_ENTERPRISE_NON_BUSINESS: Para la integración con ediciones de Gemini Enterprise que no sean Business (Standard, Plus y Frontline).SECURE_WEB_PROXY: Para la integración en Secure Web Proxy.
CORRELATION_ID: Es el identificador único que generas para una solicitud específica.
Usa etiquetas de regla de exclusión (versión preliminar): Cuando una regla de exclusión anula un resultado de filtro o cuando Model Armor omite la evaluación de la regla de exclusión, Model Armor completa los siguientes campos opcionales de nivel superior de
labelsen las entradas de registro demodelarmor.googleapis.com/SanitizeOperation:modelarmor.googleapis.com/exclusion_rule_overridden_filters: Es una lista separada por comas de filtros cuyos resultadosMATCH_FOUNDoEXECUTION_SKIPPEDse anularon aNO_MATCH_FOUNDporque coincidieron con una regla de exclusión.modelarmor.googleapis.com/exclusion_rule_skipped_filters: Es una lista separada por comas de los filtros cuya evaluación de la regla de exclusión se omitió (por ejemplo, cuando una entrada supera el límite de carga útil de exclusión de 130,000 tokens [0.5 MB]).
Usa las siguientes consultas de ejemplo para filtrar los registros de limpieza por etiquetas de reglas de exclusión:
- Para encontrar solicitudes en las que una regla de exclusión anuló el resultado de un filtro, haz lo siguiente:
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters":"FILTER_NAME"- Para encontrar solicitudes en las que una regla de exclusión anuló una detección de inyección de instrucciones y jailbreak, haz lo siguiente:
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters"="PROMPT_INJECTION_AND_JAILBREAK"- Para encontrar solicitudes en las que se omitió la evaluación de la regla de exclusión, sigue estos pasos:
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/exclusion_rule_skipped_filters"="FILTER_NAME"Reemplaza
FILTER_NAMEpor el nombre del filtro (PROMPT_INJECTION_AND_JAILBREAKoRESPONSIBLE_AI).
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) 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
con el objetivo de incluir un encabezado personalizado MA-Client-Correlation-Id en la 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 plataforma frente a Registros de auditoría de Cloud
Es importante distinguir entre los registros que puedes habilitar en una plantilla de Model Armor o en la configuración de piso 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 limpieza. |
| 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 precios mínimos. 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 de la instrucción del usuario ni de la respuesta del modelo para las operaciones de limpieza. Contiene metadatos, como el emisor, 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 limpieza. |
| Mecanismo de habilitación | Configuración estándar Google Cloud de los registros de auditoría de IAM para la API de Model Armor. Los registros de acceso a los datos suelen requerir una habilitación explícita. Los registros de auditoría de las operaciones de plantilla 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 parámetros de configuración de precios mínimos. | Registra datos (instrucciones del usuario y respuestas del modelo) para cualquier solicitud del plano de datos, independientemente de si Sensitive Data Protection está habilitado o si se encontró alguna coincidencia con la configuración del filtro. |
| Volumen y costo de los registros | Por lo general, son más pequeños y predecibles, lo que genera precios estándar de Cloud Logging. | Pueden ser muy grandes y voluminosos, lo que puede generar costos significativos de Cloud Logging debido a las cargas útiles grandes y el 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 de IAM especiales para acceder (por ejemplo, roles de IAM específicos para ver los registros de auditoría). | Contiene datos del usuario potencialmente sensibles (IIP, información confidencial). Cualquier persona con permisos de visualización de registros puede acceder a ellos (por ejemplo,
roles/logging.privateLogViewer). |
| Recomendación | Habilítalo para la supervisión general de la seguridad y el cumplimiento. | No se recomienda para datos de producción o sensibles, a menos que se enruten de forma segura a un receptor con control de acceso (por ejemplo, BigQuery con IAM estricta). |
Cuando habilitas el registro en una plantilla, se escriben las instrucciones y respuestas sin procesar en Logging. Estos datos pueden incluir datos sensibles del usuario, información de identificación personal (IIP) o información confidencial. El tráfico alto y las cargas útiles grandes pueden generar costos de registro significativos y la posibilidad de que los volúmenes de registros grandes superen los límites y requieran una administración cuidadosa.
Identidad del emisor en los registros de auditoría
Cuando ves los registros de auditoría, los Registros de auditoría de Cloud capturan la identidad del
emisor en el campo protoPayload.authenticationInfo.principalEmail. La
identidad registrada depende de cómo se llama a la API de Model Armor:
- Invocación directa de la API: Si un usuario o una cuenta de servicio llama a la
API de Model Armor directamente (por ejemplo, con
gcloud, bibliotecas cliente o APIs de REST),principalEmailcontiene la dirección de correo electrónico de ese usuario o cuenta de servicio. - Invocación a través de un servicio de Google Cloud integrado: Si
Model Armor se integra en otro
servicio deGoogle Cloud , como Gemini Enterprise Agent Platform,
principalEmailcontiene la identidad de ese servicio, que suele ser una cuenta de servicio administrada por Google. El formato de los agentes de servicio esservice-PROJECT_NUMBER@SERVICE_NAME.. 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 emisores, examina el campo principalEmail en la entrada de registro de auditoría. Las llamadas de usuarios finales o cuentas de servicio administradas por el usuario muestran sus
direcciones de correo electrónico, mientras que las llamadas a través de otros servicios de Google Cloud muestran
direcciones de correo electrónico de cuentas de servicio administradas por Google.