O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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 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 Geração de registros de auditoria do Model Armor.

Para informações sobre preços de registros, consulte os preços do Cloud Logging. Também podem ser aplicadas taxas de uso do Model Armor 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.

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 a API Model Armor antes de usar o Model Armor.

Console

Ative a API Model Armor, se ela 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 receber essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). 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 console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Ative a API Model Armor, se ela 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 receber 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ó é necessária se você usar a CLI gcloud com o Model Armor e quiser usar uma região ou multirregião diferente da multirregião padrão us. É necessário definir manualmente 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 mínimas. Para mais informações, consulte Configurar a proteção para servidores do Google e do Google Cloud servidor MCP.

Configurar a geração de registros em modelos

Os modelos definem os filtros e limites para diferentes categorias de proteção e 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.

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 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 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 MCP no seu projeto, essas configurações definem os filtros de segurança para operações de limpeza. 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 o registro em registros de operações de limpeza para a Plataforma de Agentes e servidores MCP do Google e Google Cloud individualmente. Quando ativados, os registros incluem o comando e a resposta (para a plataforma do agente) ou chamadas 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 o registro em registros de operações de limpeza para a plataforma do agente e os servidores do Google e do Google Cloud MCP.

Console

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

Acessar o Model Armor
Verifique se você está visualizando o projeto em que o Model Armor foi ativado.
Acesse a guia Configurações do 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 Agent Platform e a flag --enable-google-mcp-server-cloud-logging para ativar a geração de registros para servidores do Google e Google Cloud servidores MCP. Para desativar o registro em log, use as flags --no-enable-vertex-ai-cloud-logging e --no-enable-google-mcp-server-cloud-logging.

O exemplo de comando a seguir ativa o registro em registros de operações de limpeza para servidores da plataforma do agente, do Google e do 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

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 servidores MCP do Google e Google Cloud 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 do Google e do 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"

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 acessar e filtrar 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ção de limpeza:
```
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 da operação de limpeza, especifique um nome de cliente, um ID de correlação ou um rótulo de avaliação de regra de exclusão (prévia) 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 (Visualização): 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, o Model Armor preenche os seguintes campos labels opcionais de nível superior nas entradas de registro modelarmor.googleapis.com/SanitizeOperation:
    - modelarmor.googleapis.com/exclusion_rule_overridden_filters: uma lista separada por vírgulas de filtros cujos resultados de MATCH_FOUND ou EXECUTION_SKIPPED foram substituídos por NO_MATCH_FOUND porque uma regra de exclusão foi correspondente.
    - modelarmor.googleapis.com/exclusion_rule_skipped_filters: uma lista separada por vírgulas de filtros cuja avaliação da regra de exclusão foi ignorada (por exemplo, quando uma entrada excede o limite de payload de exclusão de 130.000 tokens (0,5 MB)).
    Use as consultas de exemplo a seguir 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_NAME pelo nome do filtro (PROMPT_INJECTION_AND_JAILBREAK ou RESPONSIBLE_AI).

Correlacionar registros e eventos relacionados

Para correlacionar registros e eventos de uma interação específica, use um ID de correlação de 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 do cliente em um cabeçalho curl, use a opção -H para incluir um cabeçalho personalizado MA-Client-Correlation-Id na sua 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 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.

Registros da plataforma x Registros de auditoria do Cloud

É importante distinguir entre os registros que podem ser ativados em um modelo ou configurações mínimas do Model Armor 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ê e quando) e monitoramento de compliance.	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 da carga útil	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 caller, 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. Muitas vezes, os registros de acesso a dados precisam ser ativados explicitamente. 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 mínimas.	Registra dados (comandos do usuário e respostas do modelo) para todas as solicitações do plano de dados, independente 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 nos 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 potencialmente sensíveis do usuário (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 compliance.	Não é recomendado para produção ou dados sensíveis, a menos que sejam encaminhados 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 informações sensíveis do usuário, informações de identificação pessoal (PII) ou informações confidenciais. Tráfego alto e payloads grandes podem gerar custos de registro substanciais e a possibilidade de grandes volumes de registros excederem os limites, exigindo gerenciamento cuidadoso.

Identidade do autor da chamada em registros de auditoria

Quando você visualiza registros de auditoria, os Registros de auditoria do Cloud capturam a identidade do chamador 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), principalEmail vai conter o endereço de e-mail desse usuário ou conta de serviço.
Invocação por um serviço integrado Google Cloud : se o Model Armor se integrar a outroGoogle Cloud serviço, como a Gemini Enterprise Agent Platform, principalEmail vai 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.iam.gserviceaccount.com. Por exemplo, uma chamada originada de um recurso da Gemini Enterprise Agent Platform usa um agente de serviço da Gemini Enterprise Agent Platform.

Para distinguir os autores da chamada, 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.

A seguir

Correlacionar registros do Model Armor com registros do Gemini Enterprise

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 sanitização de 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 e filtrar registros do Model Armor

Correlacionar registros e eventos relacionados

Registros da plataforma x Registros de auditoria do Cloud

Identidade do autor da chamada em registros de auditoria

A seguir

Configurar a geração de registros