Configurar a geração de registros

Neste documento, descrevemos como configurar o Model Armor para registrar as seguintes operações:

• Operações que criam, atualizam ou excluem um modelo
• Operações que higienizam um comando do usuário ou uma resposta do modelo

O Model Armor usa registros de auditoria para registrar atividades administrativas e de gerenciamento de recursos. Para mais informações, consulte Registro de auditoria do Model Armor.

Para informações sobre como os registros são precificados, consulte a página de preços do Cloud Logging. Também podem ser aplicadas taxas de uso do Model Armor com base no volume de dados processados. Consulte os preços do Model Armor para mais detalhes.

Antes de começar

Conclua essas tarefas antes de concluir as restantes nesta página.

Receber as permissões necessárias

Para receber as permissões necessárias para configurar o registro em log do Model Armor, peça ao administrador para conceder a você o papel do IAM de Administrador do Model Armor (roles/modelarmor.admin) no modelo do Model Armor. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Ativar APIs

É necessário ativar as APIs do Model Armor antes de usar o Model Armor.

Console

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. Selecione o projeto em que você quer ativar o Model Armor.

gcloud

Antes de começar, siga estas etapas usando a Google Cloud CLI com a 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. Execute o comando a seguir para definir o endpoint de API do serviço Model Armor.

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

   Substitua LOCATION pela região em que você quer usar o Model Armor.

Configurar a limpeza de tráfego

Para servidores MCP gerenciados pelo Google, configure a limpeza do tráfego usando as configurações de limite mínimo. Para mais informações, consulte Configurar a proteção para servidores do Google e do MCP remoto Google Cloud . (Visualizar)

Configurar a geração de registros em modelos

Os modelos definem os filtros e limites para diferentes categorias de segurança. Ao criar ou atualizar um modelo do Model Armor, é possível especificar se o Model Armor registra determinadas operações. Use as seguintes flags nos metadados do modelo:

• log_template_operations: um valor booleano que ativa o registro em log das operações de criação, atualização, leitura e exclusão de modelos.

• log_sanitize_operations: um valor booleano que ativa o registro das operações de limpeza. Os registros incluem o comando e a resposta, os resultados da avaliação do Model Armor e outros campos de metadados.

Console

1. No console do Google Cloud , acesse a página Model Armor.

   Acessar o Model Armor

2. Verifique se você está visualizando o projeto em que ativou o Model Armor.

3. Na página Model Armor, clique em Criar modelo. Para mais informações sobre como criar modelos, consulte Criar um modelo do Model Armor.

4. Na seção Configurar geração de registros, selecione as operações para as quais você quer configurar a geração de registros.

5. Clique em Criar.

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"

Substitua:

• PROJECT_ID: o ID do projeto a que o modelo pertence.
• LOCATION: o local do modelo.
• TEMPLATE_ID: o ID do modelo.

Python

Para executar esse código, primeiro configure um ambiente de desenvolvimento Python e instale o SDK do Model Armor para 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)
   

Substitua:

• PROJECT_ID: o ID do projeto a que o modelo pertence.
• LOCATION: o local do modelo.
• TEMPLATE_ID: o ID do modelo.

Configurar a geração de registros nas configurações mínimas

As configurações de limite mínimo estabelecem filtros de segurança e proteção básicos em todos os modelos do Gemini na Vertex AI e nos servidores de Protocolo de Contexto de Modelo (MCP) gerenciados pelo Google (pré-lançamento) no seu projeto. Ao atualizar as configurações de limite mínimo do Model Armor, é possível especificar se as operações de higienização do Model Armor serão registradas.

Observação:no console Google Cloud , o registro de configurações de piso para operações de limpeza é ativado por padrão na Vertex AI, mas desativado por padrão nos servidores do MCP.

Se você tiver requisitos de residência de dados, configure um coletor de registros para rotear os registros a um local de armazenamento em conformidade antes de ativar o Cloud Logging no próximo procedimento. Configurar um coletor de registros ajuda a garantir que os registros do Model Armor sejam armazenados nos buckets regionais adequados. Para mais informações, consulte Regionalizar seus registros.

É possível ativar o registro em log de operações de limpeza para servidores MCP gerenciados pelo Google e da Vertex AI individualmente. Quando ativados, os registros incluem o comando e a resposta (para a Vertex AI) ou chamadas e respostas de ferramentas (para servidores MCP), os resultados da avaliação do Model Armor e outros campos de metadados.

Console

1. No console do Google Cloud , acesse a página Model Armor.

   Acessar o Model Armor

2. Verifique se você está visualizando o projeto em que ativou o Model Armor.

3. Acesse a guia Configurações do piso.

4. Na seção Registros, selecione MCP gerenciado pelo Google.

5. Clique em Salvar.

gcloud

Você pode usar uma das seguintes flags para gerenciar a geração de registros de operações de limpeza nas configurações de piso.

Para ativar o Logging, use uma das seguintes flags:

• Para a Vertex AI, use a flag --enable-vertex-ai-cloud-logging.
• Para servidores MCP gerenciados pelo Google, use a flag --enable-google-mcp-server-cloud-logging.

Para desativar o Logging, use uma das seguintes flags:

• Para a Vertex AI, use a flag --no-enable-vertex-ai-cloud-logging.

• Para servidores MCP gerenciados pelo Google, use a flag --no-enable-google-mcp-server-cloud-logging.

  Observação: é possível ativar ou desativar a geração de registros para um ou ambos os serviços usando um único comando.

O comando de exemplo a seguir ativa o registro em registros de operações de limpeza para servidores da Vertex AI e do MCP gerenciados pelo 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

Substitua PROJECT_ID pelo ID do seu projeto.

REST

Use o método UpdateFloorSetting para atualizar as configurações do piso e ativar o registro de operações de higienização. Ao usar esse método, defina o parâmetro apropriado como "true" para ativar o registro em log:

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

• Para servidores MCP gerenciados pelo Google, defina googleMcpServerFloorSetting.enableCloudLogging como true.

O comando de exemplo a seguir ativa o registro em registros de operações de limpeza para servidores da Vertex AI e do MCP gerenciados pelo 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"

Substitua PROJECT_ID pelo ID do seu projeto.

Python

Para executar esse código, primeiro configure um ambiente de desenvolvimento Python e instale o SDK do Model Armor para 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}")

Substitua PROJECT_ID pelo ID do seu projeto.

Como visualizar registros

Para ver os registros do Model Armor usando o Explorador de registros no Logging, siga estas etapas:

1. Navegue até o Explorador de registros no console do Google Cloud . Para mais informações, consulte Ver registros usando o Explorador de registros.
2. Filtre os registros pelo nome do serviço modelarmor.googleapis.com.
3. Procure entradas relacionadas às operações que você ativou no modelo. Para conferir uma lista de todos os nomes de serviços e tipos de recursos monitorados, consulte Recursos e serviços monitorados.

Filtrar registros do Model Armor

É possível usar rótulos de registro para filtrar os registros do Model Armor nas operações de limpeza e no registro de modelo. Para fazer isso, siga estas instruções:

Execute a consulta a seguir na Análise de registros para filtrar os registros de operações de limpeza.

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

Para refinar ainda mais os registros de operação de limpeza, especifique um ID do projeto, um nome do cliente ou um ID de correlação na consulta.

• Usando um ID do projeto:

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

• Usando um nome de cliente:

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

• Usando um ID de correlação:

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

Substitua:

• PROJECT_ID: o ID do projeto do Google Cloud .
• CLIENT_NAME: o nome do cliente.
• CORRELATION_ID: o identificador exclusivo que você gera para uma solicitação específica.

Correlacionar registros e eventos relacionados

Para correlacionar registros e eventos de uma interação específica, use um ID de correlação do cliente. Esse ID é um identificador exclusivo gerado por você (por exemplo, um UUID) que rastreia uma solicitação específica no seu sistema. Para definir um ID de correlação do cliente em um cabeçalho curl, use a opção -H para incluir um cabeçalho personalizado na solicitação.

Este é o formato de exemplo:

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"

Substitua:

• PROJECT_ID: o ID do projeto a que o modelo pertence.
• LOCATION: o local do modelo.
• TEMPLATE_ID: o ID do modelo.
• USER_PROMPT: o comando fornecido ao modelo.
• MODEL_RESPONSE: a resposta recebida do modelo.

Envie comentários