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 preços de registros, consulte a página de preços do Cloud Logging. As taxas de uso do Model Armor também podem ser aplicadas com base no volume de dados processados. Consulte Preços do Model Armor para mais detalhes.

Antes de começar

Conclua estas tarefas antes de concluir as demais tarefas neste documento.

Receber as permissões necessárias

Para receber as permissões necessárias para configurar a geração de registros 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 personalizados papéis ou outros predefinidos papéis.

Ativar APIs

É necessário ativar a API Model Armor antes de usar o Model Armor.

Console

Ativar a API Model Armor.
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.
Ativar a API
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:

No Google Cloud console do, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do Google Cloud console do, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a Google Cloud CLI já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Defina a substituição do endpoint de API usando a CLI gcloud.

Definir a substituição do endpoint de API usando a CLI gcloud

Esta etapa só será necessária se você estiver usando a CLI gcloud para ativar a API Model Armor. É necessário definir manualmente a substituição do endpoint de API para garantir que a CLI gcloud encaminhe corretamente as solicitações ao serviço Model Armor.

Execute o comando a seguir para definir o endpoint de API para o 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 higienização do tráfego

Para servidores do Protocolo de Contexto de Modelo (MCP) gerenciados pelo Google, configure a higienização do tráfego pelas configurações mínimas. Para mais informações, consulte Configurar a proteção para servidores MCP remotos e do Google. 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 a geração de registros das operações de criação, atualização, leitura e exclusão de modelos.
log_sanitize_operations: um valor booleano que ativa a geração de registros das operações de higienização. Os registros incluem o comando e a resposta, os resultados da avaliação do Model Armor e outros campos de metadados.

Console

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

Acessar o Model Armor
Verifique se você está visualizando o projeto em que ativou o Model Armor.
Na página Model Armor, clique em Criar modelo. Para mais informações sobre como criar modelos, consulte Criar um modelo do Model Armor.
Na seção Configurar geração de registros, selecione as operações para as quais você quer configurar a geração de registros.
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 do Python e instale o SDK do Python do 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)

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 mínimas estabelecem filtros de segurança de linha de base em todos os modelos do Gemini na Vertex AI e servidores do Protocolo de Contexto de Modelo (MCP) gerenciados pelo Google (visualização) no seu projeto. Ao atualizar as configurações mínimas do Model Armor, é possível especificar se as operações de higienização do Model Armor são registradas.

É possível ativar a geração de registros de operações de higienização para servidores MCP gerenciados pelo Google e pela 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

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

Acessar o Model Armor
Verifique se você está visualizando o projeto em que ativou o Model Armor.
Acesse a guia Configurações mínimas.
Na seção Registros, selecione MCP gerenciado pelo Google.
Clique em Salvar.

gcloud

É possível usar uma das seguintes flags para gerenciar a geração de registros de operações de higienização nas configurações mínimas.

Para ativar a geração de registros, 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 a geração de registros, 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 a geração de registros de operações de higienização para servidores MCP gerenciados pelo Google e pela Vertex AI:

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

É possível usar o método UpdateFloorSetting para atualizar as configurações mínimas e ativar a geração de registros de operações de higienização. Ao usar esse método, defina o parâmetro apropriado como verdadeiro para ativar a geração de registros:

Para a 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 a geração de registros de operações de higienização para servidores MCP gerenciados pelo Google e pela Vertex AI:

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 do Python e instale o SDK do Python do 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}")

Substitua PROJECT_ID pelo ID do seu projeto.

Ver registros

Para visualizar os registros do Model Armor, use a Análise de registros no Logging. Siga estas etapas:

Acesse a Análise de registros no Google Cloud console. Para mais informações, consulte Ver registros usando a Análise de registros.
Filtre os registros pelo nome do serviço modelarmor.googleapis.com.
Procure entradas relacionadas às operações ativadas no modelo. Para uma lista de todos os nomes de serviço 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 para as operações de higienização e geração de registros de modelos. 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 higienização.

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

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

Usar um nome de cliente: quando o Model Armor é integrado a serviços como a Vertex AI ou o Gemini Enterprise, é possível usar o nome do cliente para filtrar registros de uma integração específica.
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
```

Usar um ID de correlação:

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

Substitua:

CLIENT_NAME: o nome do cliente, por exemplo, VERTEX_AI.
CORRELATION_ID: o identificador exclusivo gerado para uma solicitação específica.

Correlacionar registros e eventos relacionados

Para correlacionar registros e eventos de uma interação específica, é possível usar um ID de correlação do cliente. Esse ID é um identificador exclusivo gerado (por exemplo, um UUID) que rastreia uma solicitação específica no 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.

Confira o formato de exemplo:

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"

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.

Configurar a geração de registros Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Receber as permissões necessárias

Ativar APIs

Console

gcloud

Definir a substituição do endpoint de API usando a CLI gcloud

Configurar a higienização do tráfego

Configurar a geração de registros em modelos

Console

REST

Python

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

Console

gcloud

REST

Python

Ver registros

Filtrar registros do Model Armor

Correlacionar registros e eventos relacionados

Configurar a geração de registros