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 limpam 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 Registros de auditoria do Model Armor.
Para informações sobre preços de registros, consulte os preços do Cloud Logging. As cobranças de uso do Model Armor também podem ser aplicadas com base no volume de tratamento de dados. Consulte os preços do Model Armor para mais detalhes.
Antes de começar
Antes de começar, conclua as tarefas a seguir.
Conseguir 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 papéis personalizados ou outros papéis predefinidos.
Ativar APIs
É necessário ativar a API Model Armor antes de usar o Model Armor.
Console
Ative a API Model Armor, se ainda não estiver ativada.
Funções necessárias para ativar APIs
Para ativar APIs, você precisa da permissão
serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.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:
Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada. Depois de fazer login, inicialize a Google Cloud CLI executando o seguinte comando:
gcloud initAtive a API Model Armor, se ainda não estiver ativada:
Funções necessárias para ativar APIs
Para ativar APIs, você precisa da permissão
serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.gcloud services enable modelarmor.googleapis.com
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. Defina a substituição do endpoint de API para garantir que a CLI gcloud encaminhe corretamente as solicitações para o serviço Model Armor.
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 ou multirregião em que
você quer usar o Model Armor.
Configurar a sanitização de tráfego
Para servidores do Google e do Google Cloud , configure a sanitização de tráfego usando as configurações de limite mínimo. Para mais informações, consulte Configurar a proteção para servidores do Google e doGoogle Cloud MCP.
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 permite registrar as operações de criação, atualização, leitura e exclusão de modelos.log_sanitize_operations: um valor booleano que permite registrar o conteúdo completo dos comandos do usuário e das respostas do modelo durante as operações de limpeza.
Console
No console do Google Cloud , acesse a página Model Armor.
Verifique se você está visualizando o projeto em que o Model Armor foi ativado.
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 ao qual 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 em 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 ao qual 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
Quando você aplica as configurações mínimas ao tráfego de modelos do Gemini na Gemini Enterprise Agent Platform e nos servidores do Google e do Google Cloud servidor MCP no seu projeto, essas configurações definem os filtros de segurança para operações de sanitização. Ao atualizar as configurações mínimas do Model Armor, é possível especificar se o Model Armor registra as operações de higienização.
É possível ativar a geração de registros de operações de limpeza para a Plataforma de Agentes e os servidores MCP do Google e do Google Cloud individualmente. Quando ativados, os registros incluem o comando e a resposta (para a Agent Platform) ou as chamadas de ferramenta e respostas de ferramentas (para servidores MCP), os resultados da avaliação do Model Armor e outros campos de metadados.
Os exemplos a seguir mostram como ativar a geração de registros de operações de limpeza para a Plataforma de Agentes e os servidores MCP do Google e do Google Cloud .
Console
No console do Google Cloud , acesse a página Model Armor.
Verifique se você está visualizando o projeto em que o Model Armor foi ativado.
Acesse a guia Configurações de piso.
Na seção Registros, marque as caixas de seleção Vertex AI e MCP gerenciado pelo Google para ativar a geração de registros em cada serviço.
Clique em Salvar.
gcloud
Use a flag --enable-vertex-ai-cloud-logging para ativar a geração de registros para a
plataforma de agentes e a flag --enable-google-mcp-server-cloud-logging
para ativar a geração de registros para os servidores do Google e do MCP do Google Cloud . Para desativar
a geração de registros, use as flags --no-enable-vertex-ai-cloud-logging e
--no-enable-google-mcp-server-cloud-logging.
O comando de exemplo a seguir ativa a geração de registros de operações de limpeza para a Agent Platform e os servidores MCP do Google e do Google Cloud :
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
Para ativar a geração de registros, defina aiPlatformFloorSetting.enableCloudLogging como true
para a Agent Platform e googleMcpServerFloorSetting.enableCloudLogging
como true para os servidores do Google e do Google Cloud servidor MCP no método
UpdateFloorSetting.
O comando de exemplo a seguir ativa a geração de registros de operações de limpeza para a Agent Platform e os servidores MCP do Google e do Google Cloud :
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 em 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.
Ver e filtrar registros do Model Armor
Para visualizar e filtrar os registros do Model Armor, use a Análise de Registros no Logging:
No console do Google Cloud , acesse a página Análise de registros.
Acessar a Análise de registros
Para mais informações, consulte Ver registros usando a Análise de registros.
No painel de consulta, insira uma das seguintes consultas para filtrar os registros do Model Armor:
Para conferir todos os registros do Model Armor, incluindo registros de auditoria e de operações de sanitização:
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"Para ver apenas os registros de auditoria do Model Armor:
protoPayload.serviceName="modelarmor.googleapis.com"Para ver uma lista de todos os nomes de serviço e tipos de recursos monitorados, consulte Recursos e serviços monitorados.
Para ver apenas os registros do Model Armor para operações de sanitização:
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"Para refinar ainda mais os registros de operação de sanitização, especifique um nome de cliente, ID de correlação ou rótulo de avaliação de regra de exclusão (pré-lançamento) na consulta:
Usar um nome de cliente: quando o Model Armor se integra a serviços como a Gemini Enterprise Agent Platform 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"Usando um ID de correlação:
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"Substitua:
CLIENT_NAME: o nome do cliente. Use um dos seguintes valores:CLIENT_NAME_UNSPECIFIED: valor padrão, usado quando o nome do cliente não é especificado.VERTEX_AI: para integração com a Gemini Enterprise Agent Platform.LOAD_BALANCER: para integração usando o balanceador de carga como uma extensão de serviço.LANGCHAIN: para integração com o LangChain.GEMINI_ENTERPRISE_BUSINESS: para integração com o Gemini Enterprise – edição Business.GOOGLE_MCP_SERVER: para integração com o Google e servidores MCP gerenciados pelo Google.AGENT_GATEWAY: para integração com o Gateway de Agente.GEMINI_ENTERPRISE_NON_BUSINESS: para integração com edições do Gemini Enterprise que não sejam Business (Standard, Plus e Frontline).SECURE_WEB_PROXY: para integração com o Secure Web Proxy.
CORRELATION_ID: o identificador exclusivo que você gera para uma solicitação específica.
Usando rótulos de regra de exclusão (pré-lançamento): quando uma regra de exclusão substitui um resultado de filtro ou quando o Model Armor ignora a avaliação da regra de exclusão, ele preenche os seguintes campos opcionais de nível superior
labelsnas entradas de registromodelarmor.googleapis.com/SanitizeOperation:modelarmor.googleapis.com/exclusion_rule_overridden_filters: uma lista separada por vírgulas de filtros com resultadosMATCH_FOUNDouEXECUTION_SKIPPEDque foram substituídos porNO_MATCH_FOUNDporque uma regra de exclusão foi correspondida.modelarmor.googleapis.com/exclusion_rule_skipped_filters: uma lista separada por vírgulas de filtros em que a avaliação da regra de exclusão foi pulada (por exemplo, quando uma entrada excede o limite de payload de exclusão de 130.000 tokens (0,5 MB)).
Use as seguintes consultas de amostra para filtrar os registros de sanitização por rótulos de regra de exclusão:
- Para encontrar solicitações em que um resultado de filtro foi substituído por uma regra de exclusão:
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters":"FILTER_NAME"- Para encontrar solicitações em que uma detecção de injeção de comando e jailbreak foi substituída por uma regra de exclusão:
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 solicitações em que a avaliação da regra de exclusão foi ignorada:
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/exclusion_rule_skipped_filters"="FILTER_NAME"Substitua
FILTER_NAMEpelo nome do filtro (PROMPT_INJECTION_AND_JAILBREAKouRESPONSIBLE_AI).
Correlacionar registros e eventos relacionados
Para correlacionar registros e eventos de uma interação específica, use um
ID de correlação do cliente do Model Armor. Esse ID é um identificador exclusivo
gerado por você (por exemplo, um UUID) que rastreia uma solicitação específica em
todo o sistema. Para definir um ID de correlação de cliente em um cabeçalho curl, use a opção -H
para incluir um cabeçalho personalizado MA-Client-Correlation-Id na solicitação.
Veja 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 ao qual 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.
Registros da plataforma x Registros de auditoria do Cloud
É importante distinguir entre os registros que podem ser ativados em um modelo do Model Armor ou nas configurações de piso e os Registros de Auditoria do Cloud.
| Recurso | Registros de auditoria do Cloud | Registros de plataforma |
|---|---|---|
| Finalidade principal | Auditoria de segurança de chamadas de API (quem fez o quê, quando) e monitoramento de conformidade. | Monitoramento operacional, depuração e análise detalhada de eventos de sanitização. |
| Operações de API capturadas | Criar, ler, atualizar, excluir e listar operações em modelos e configurações de
piso. As operações de limpeza (SanitizeUserPrompt,
SanitizeModelResponse) são registradas como metadados. |
Captura todas as solicitações, como SanitizeUserPrompt e
SanitizeModelResponse. |
| Conteúdo do payload | Não inclui o texto real do comando do usuário ou da resposta do modelo para operações de limpeza. Contém metadados como o autor da chamada, o método, o recurso, o carimbo de data/hora e o status. | Inclui o payload completo, como o texto do comando ou da resposta, os resultados do filtro e outros detalhes da sanitização. |
| Mecanismo de ativação | Configurações padrão Google Cloud dos registros de auditoria do IAM para a API Model Armor. Os registros de acesso a dados geralmente exigem ativação explícita. Os registros de auditoria para operações de modelo são gerados automaticamente. | Ativado ao definir a flag booleana log_sanitize_operations nos
metadados do modelo ou nas configurações mínimas. |
| Condições de registro | Registra automaticamente as operações de criação, leitura, atualização, exclusão e listagem em modelos e configurações de piso. | Registra dados (comandos do usuário e respostas do modelo) para todas as solicitações do plano de dados, independentemente de a Proteção de Dados Sensíveis estar ativada ou de alguma configuração de filtro ter sido correspondida. |
| Volume e custo de registros | Geralmente menores e mais previsíveis, incorrendo em preços padrão do Cloud Logging. | Podem ser muito grandes e volumosos, o que pode gerar custos significativos do Cloud Logging devido a payloads grandes e uso frequente. Payloads grandes podem ser divididos em várias entradas de registro. |
| Considerações sobre segurança | Relativamente seguro, já que os dados do payload não são registrados. Requer permissões especiais do IAM para acesso (por exemplo, papéis específicos do IAM para visualizar registros de auditoria). | Contém dados de usuários potencialmente sensíveis (PII, informações
confidenciais). Acessível a qualquer pessoa com permissões de visualização de registros (por exemplo,
roles/logging.privateLogViewer). |
| Recomendação | Ative para monitoramento geral de segurança e conformidade. | Não recomendado para produção ou dados sensíveis, a menos que seja roteado com segurança para um coletor com controle de acesso (por exemplo, BigQuery com IAM estrito). |
Ativar a geração de registros em um modelo grava comandos e respostas brutos no Logging. Esses dados podem incluir dados sensíveis do usuário, informações de identificação pessoal (PII) ou informações confidenciais. Tráfego intenso e payloads grandes podem gerar custos de geração de registros substanciais e volumes de registros grandes que excedem os limites, exigindo um gerenciamento cuidadoso.
Identidade do autor da chamada em registros de auditoria
Quando você visualiza os registros de auditoria, os Registros de Auditoria do Cloud capturam a identidade do
autor da chamada no campo protoPayload.authenticationInfo.principalEmail. A identidade registrada depende de como a API Model Armor é chamada:
- Invocação direta da API: se um usuário ou uma conta de serviço chamar a
API Model Armor diretamente (por exemplo, usando
gcloud, bibliotecas de cliente ou APIs REST),principalEmailvai conter o endereço de e-mail desse usuário ou dessa conta de serviço. - Invocação por um serviço integrado Google Cloud : se o
Model Armor se integrar a outro
Google Cloud serviço, como a Gemini Enterprise Agent Platform,
principalEmailvai conter a identidade desse serviço, que normalmente é uma conta serviço gerenciado pelo Google. O formato dos agentes de serviço éservice-PROJECT_NUMBER@SERVICE_NAME.. Por exemplo, uma chamada que se origina de um recurso da Gemini Enterprise Agent Platform usa um agente de serviço da Gemini Enterprise Agent Platform.
Para distinguir os autores das chamadas, examine o campo principalEmail na entrada de registro de auditoria. As chamadas de usuários finais ou contas de serviço gerenciado pelo usuário mostram os
endereços de e-mail, enquanto as chamadas por outros serviços do Google Cloud mostram
endereços de e-mail de conta de serviço gerenciadas pelo Google.