Configurar el almacenamiento de registros

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

• Operaciones que crean, actualizan o eliminan una plantilla
• Operaciones que desinfectan una petición de un usuario o una respuesta de un modelo

Model Armor usa registros de auditoría para registrar las actividades de gestión de administradores y 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 la página de precios de Cloud Logging. También se pueden aplicar cargos por el uso de Model Armor en función del volumen de datos procesados. Consulta los precios de Model Armor para obtener más información.

Antes de empezar

Completa estas tareas antes de completar las tareas restantes de esta página.

Obtener los permisos necesarios

Para obtener los permisos que necesitas para configurar el registro de Model Armor, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Administrador de Model Armor (roles/modelarmor.admin) en la plantilla de Model Armor. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Habilitar APIs

Para usar Model Armor, primero debes habilitar sus APIs.

Consola

1. Enable the Model Armor API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

2. Selecciona el proyecto en el que quieras activar Model Armor.

gcloud

Antes de empezar, sigue estos pasos con la CLI de Google Cloud y la API Model Armor:

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Ejecuta el siguiente comando para definir el endpoint de la API del servicio Model Armor.

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

   Sustituye LOCATION por la región en la que quieras usar Model Armor.

Configurar la limpieza del tráfico

En los servidores Model Context Protocol (MCP) gestionados por Google, configura la limpieza del tráfico mediante los ajustes de suelo. Para obtener más información, consulta Configurar la protección de servidores MCP remotos y de Google Google Cloud . Vista previa

Configurar el registro en plantillas

Las plantillas definen los filtros y los umbrales de las diferentes categorías de protección y seguridad. Al crear o actualizar una plantilla de Model Armor, puedes especificar si Model Armor registra determinadas operaciones. Usa las siguientes marcas en los metadatos de la plantilla:

• log_template_operations: valor booleano que habilita el registro de las operaciones de creación, actualización, lectura y eliminación de plantillas.

• log_sanitize_operations: valor booleano que habilita el registro de las operaciones de saneamiento. Los registros incluyen la petición y la respuesta, los resultados de la evaluación de Model Armor y campos de metadatos adicionales.

Consola

1. En la Google Cloud consola, ve a la página Model Armor.

   Ir a Model Armor

2. Comprueba que estás viendo el proyecto en el que has activado Model Armor.

3. En la página Model Armor (Protección de modelos), haga clic en Create Template (Crear plantilla). Para obtener más información sobre cómo crear plantillas, consulta Crear una plantilla de Model Armor.

4. En la sección Configurar registro, selecciona las operaciones para las que quieras configurar el registro.

5. 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"

Haz los cambios siguientes:

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

Python

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de 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)
   

Haz los cambios siguientes:

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

Configurar el registro en los ajustes de planta

Los ajustes de nivel establecen filtros de seguridad básicos en todos los modelos de Gemini de Vertex AI y en los servidores del protocolo de contexto de modelo (MCP) gestionados por Google (vista previa) de tu proyecto. Al actualizar los ajustes de la protección mínima de Model Armor, puedes especificar si se registran las operaciones de saneamiento de Model Armor.

Nota: En la consola de Google Cloud , el registro de los ajustes de suelo para las operaciones de saneamiento está habilitado de forma predeterminada en Vertex AI, pero inhabilitado de forma predeterminada en los servidores de MCP.

Si tienes requisitos de residencia de datos, debes configurar un receptor de registro para enrutar los registros a una ubicación de almacenamiento que cumpla los requisitos antes de habilitar Cloud Logging en el siguiente procedimiento. Configurar un receptor de registros ayuda a asegurarse de que los registros de Model Armor se almacenan en los segmentos regionales adecuados. Para obtener más información, consulta Regionalizar los registros.

Puedes habilitar el registro de operaciones de saneamiento para Vertex AI y los servidores MCP gestionados por Google de forma individual. Si está habilitada, los registros incluyen la petición y la respuesta (en Vertex AI) o las llamadas y respuestas de herramientas (en servidores de MCP), los resultados de la evaluación de Model Armor y campos de metadatos adicionales.

Consola

1. En la Google Cloud consola, ve a la página Model Armor.

   Ir a Model Armor

2. Comprueba que estás viendo el proyecto en el que has activado Model Armor.

3. Ve a la pestaña Configuración de planta.

4. En la sección Registros, selecciona MCP gestionado por Google.

5. Haz clic en Guardar.

gcloud

Puedes usar una de las siguientes marcas para gestionar el registro de operaciones de saneamiento en los ajustes de planta.

Para habilitar el registro, usa una de las siguientes marcas:

• En Vertex AI, usa la marca --enable-vertex-ai-cloud-logging.
• En el caso de los servidores MCP gestionados por Google, usa la marca --enable-google-mcp-server-cloud-logging.

Para inhabilitar el registro, usa una de las siguientes marcas:

• En Vertex AI, usa la marca --no-enable-vertex-ai-cloud-logging.

• En el caso de los servidores MCP gestionados por Google, usa la marca --no-enable-google-mcp-server-cloud-logging.

  Nota: Puedes habilitar o inhabilitar el registro de uno o ambos servicios con un solo comando.

El siguiente comando de ejemplo habilita el registro de operaciones de saneamiento para los servidores de Vertex AI y MCP gestionados por Google:

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-vertex-ai-cloud-logging \
--enable-google-mcp-server-cloud-logging

Sustituye PROJECT_ID por el ID de tu proyecto.

REST

Puedes usar el método UpdateFloorSetting para actualizar los ajustes de planta y habilitar el registro de operaciones de saneamiento. Cuando utilices este método, asegúrate de asignar el valor "true" al parámetro correspondiente para habilitar el registro:

• En Vertex AI, defina aiPlatformFloorSetting.enableCloudLogging como true.

• En los servidores de MCP gestionados por Google, define googleMcpServerFloorSetting.enableCloudLogging como true.

El siguiente comando de ejemplo habilita el registro de operaciones de saneamiento para los servidores de Vertex AI y MCP gestionados por Google:

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"

Sustituye PROJECT_ID por el ID de tu proyecto.

Python

Para ejecutar este código, primero debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de 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}")

Sustituye PROJECT_ID por el ID de tu proyecto.

Ver registros

Para ver los registros de Model Armor, puedes usar el Explorador de registros de Logging. Sigue estos pasos:

1. Ve a Explorador de registros en la Google Cloud consola. Para obtener más información, consulta el artículo sobre cómo ver registros con el Explorador de registros.
2. Filtra los registros por el nombre del servicio modelarmor.googleapis.com.
3. Busca las entradas relacionadas con las operaciones que hayas habilitado en tu plantilla. Para ver una lista de todos los nombres de servicio y tipos de recursos monitorizados, consulta Recursos y servicios monitorizados.

Filtrar registros de Model Armor

Puedes usar etiquetas de registro para filtrar los registros de Model Armor por operaciones de anonimización y registro de plantillas. Para ello, sigue estas instrucciones:

Ejecuta la siguiente consulta en el explorador de registros para filtrar los registros de operaciones de anonimización.

jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"

Para acotar aún más los registros de operaciones de anonimización, puede especificar un ID de proyecto, un nombre de cliente o un ID de correlación en la consulta.

• Usar un ID de proyecto:

  jsonPayload.@type="type.googleapis.com%2Fgoogle.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry";project=PROJECT_ID
  

• Usar un nombre de cliente:

  jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
  labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
  

• Usar un ID de correlación:

  labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
  

Haz los cambios siguientes:

• PROJECT_ID: el ID del proyecto. Google Cloud
• CLIENT_NAME: el nombre de tu cliente.
• CORRELATION_ID: identificador único que genera para una solicitud específica.

Correlacionar registros y eventos relacionados

Para correlacionar registros y eventos de una interacción específica, puede usar un ID de correlación de cliente. Este ID es un identificador único que genera (por ejemplo, un UUID) que hace un seguimiento de una solicitud específica en su sistema. Para definir un ID de correlación de cliente en un encabezado de curl, usa la opción -H para incluir un encabezado personalizado en tu solicitud.

Este es el formato de ejemplo:

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"

Haz los cambios siguientes:

• PROJECT_ID: el ID del proyecto al que pertenece la plantilla.
• LOCATION: la ubicación de la plantilla.
• TEMPLATE_ID: el ID de la plantilla.
• USER_PROMPT: la petición proporcionada al modelo.
• MODEL_RESPONSE: la respuesta recibida del modelo.

Enviar comentarios