Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 os 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 dados processados. Consulte os preços do Model Armor para mais detalhes.

Antes de começar

Antes de começar, conclua as seguintes tarefas:

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.
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 com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o 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.
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ê 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 roteie 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 em que você quer usar o Model Armor.

Configurar a limpeza de tráfego

Para servidores MCP do Google e da Google Cloud , configure a limpeza do tráfego usando as configurações mínimas. Para mais informações, consulte Configurar a proteção para servidores do Google e Google 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 todo o conteúdo de comandos do usuário e 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 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

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, as configurações mínimas definem os filtros de segurança para operações de limpeza. Ao atualizar as configurações mínimas do Model Armor, você pode especificar se os registros do Model Armor higienizam as operações.

É possível ativar a geração de registros de operações de limpeza para a Agent Platform e servidores MCP do Google e Google Cloud individualmente. Quando ativados, os registros incluem o comando e a resposta (para a Agent Platform) 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 a geração de registros de operações de limpeza para a Agent Platform 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 ativou o Model Armor.
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 Agent Platform e a flag --enable-google-mcp-server-cloud-logging para ativar a geração de registros para servidores do Google e do Google Cloud 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 comando de exemplo a seguir ativa a geração de registros de operações de limpeza para servidores da Agent Platform, 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 do Google e Google Cloud MCP no método UpdateFloorSetting.

O exemplo de comando 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 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.

Acessar 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 o Explorador 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ços e tipos de recursos monitorados, consulte Recursos e serviços monitorados.
- Para ver apenas os registros do Model Armor para operações de higienização:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
  Para refinar ainda mais os registros de operações de limpeza, especifique um nome de cliente ou ID de correlação na consulta.
  - Usar um nome de cliente: quando o Model Armor se integra a serviços como o 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, 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.

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 que você gera (por exemplo, um UUID) e 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 MA-Client-Correlation-Id na sua solicitação.

Este é 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ê, quando) e monitoramento de compliance.	Monitoramento operacional, depuração e análise detalhada de eventos de limpeza.
Operações de API capturadas	Criar, ler, atualizar, excluir e listar operações em modelos e configurações de planta. 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 comando do usuário ou o texto da resposta do modelo para operações de limpeza. Contém metadados como autor da chamada, método, recurso, carimbo de data/hora e 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 de registros de auditoria do IAM Google Cloud para a API Model Armor. Muitas vezes, os registros de acesso aos dados precisam ser ativados explicitamente. Os registros de auditoria para operações de modelo são gerados automaticamente.	Ativada 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 de payload não são registrados. Requer permissões especiais do IAM para acesso (por exemplo, funções específicas do IAM para visualizar registros de auditoria).	Contém dados do usuário 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 compliance.	Não recomendado para produção ou dados sensíveis, a menos que sejam encaminhados com segurança para um gravador controlado por acesso (por exemplo, BigQuery com IAM estrito).

Ao ativar a geração de registros em um modelo, os comandos e as respostas brutos são gravados no Cloud Logging. Esses dados podem incluir informações sensíveis do usuário, informações de identificação pessoal (PII) ou informações confidenciais. Alto tráfego e payloads grandes podem gerar custos de registro substanciais e a possibilidade de grandes volumes de registros excederem os limites e exigirem 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 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), principalEmail vai conter o endereço de e-mail desse usuário ou conta de serviço.
Invocação por um Google Cloud serviço integrado: 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 entre chamadores, 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 deles, enquanto as chamadas por outros serviços Google Cloud mostram os endereços de e-mail conta de serviço gerenciadas pelo Google.

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 limpeza 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

Acessar 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

Configurar a geração de registros