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

Configurar a geração de registros

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

Para informações sobre os 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 dados processados. Consulte Preços do Model Armor para mais detalhes.

Antes de começar

Antes de começar, faça o seguinte:

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 para o serviço Model Armor.

Execute o seguinte comando 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 Google e Google Cloud MCP, configure a higienização 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 dos comandos do usuário e das respostas do modelo durante as operações de higienização.

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

Ao aplicar configurações mínimas ao tráfego de modelos do Gemini na Gemini Enterprise Agent Platform e nos servidores do Google e Google Cloud MCP no seu projeto, as configurações mínimas definem os filtros de segurança para operações de higienização. Ao atualizar as configurações mínimas do Model Armor, é possível especificar se o Model Armor registra operações de higienização.

É possível ativar a geração de registros de operações de higienização para a Agent Platform e os servidores do Google e Google Cloud MCP 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 higienização para a Agent Platform e os servidores do Google e Google Cloud MCP.

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 as caixas de seleção Vertex AI e MCP gerenciado pelo Google para ativar a geração de registros de cada serviço.
Clique em Salvar.

gcloud

Use a flag --enable-vertex-ai-cloud-logging para ativar a geração de registros da Agent Platform, e a --enable-google-mcp-server-cloud-logging flag para ativar a geração de registros de servidores do Google e Google Cloud MCP. 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 higienização para a Agent Platform e os servidores do Google e 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 comando de exemplo a seguir ativa a geração de registros de operações de higienização para a Agent Platform e os servidores do Google e MCP: 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 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.

Visualizar e filtrar registros do Model Armor

Para visualizar e filtrar registros do Model Armor, use a Análise de registros no Logging:

No Google Cloud console do, 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 registros do Model Armor:
- Para visualizar todos os registros do Model Armor, incluindo registros de auditoria e registros de operações de higienização:
```
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
- Para visualizar apenas os registros de auditoria do Model Armor:
```
protoPayload.serviceName="modelarmor.googleapis.com"
```
  Para uma lista de todos os nomes de serviço e tipos de recursos monitorados, consulte Recursos e serviços monitorados.
- Para visualizar 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 higienização, é possível especificar um nome de cliente ou ID de correlação na consulta.
  - Usando um nome de cliente: quando o Model Armor é integrado 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 seu 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 servidores MCP do Google e gerenciados pelo Google.
    - AGENT_GATEWAY: para integração com o gateway de agentes.
    - 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, é possível usar um ID de correlação de cliente do Model Armor. Esse ID é um identificador exclusivo que você gera (por exemplo, um UUID) que rastreia uma solicitação específica no seu 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 sua 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.

Registros de plataforma x registros de auditoria do Cloud

É importante distinguir entre os registros que podem ser ativados em um modelo do Model Armor ou configurações mínimas 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 higienização.
Operações de API capturadas	Criar, ler, atualizar, excluir e listar operações em modelos e configurações mínimas. As operações de higienização (`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 real do usuário ou o texto de resposta do modelo para operações de higienização. 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 higienização.
Mecanismo de ativação	Configurações de registros de auditoria do Google Cloud IAM padrão para a API Model Armor. Os registros de acesso aos dados geralmente exigem ativação explícita. Os registros de auditoria para operações de modelo são gerados automaticamente.	Ativado definindo a flag booleana `log_sanitize_operations` nos metadados do modelo ou nas configurações mínimas.
Condições de geração de registros	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, independentemente de a Proteção de Dados Sensíveis estar ativada ou se alguma configuração de filtro foi correspondida.
Volume e custo de registros	Geralmente menor e mais previsível, incorrendo no preço padrão do Cloud Logging.	Pode ser muito grande e volumoso, o que pode levar a 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. Exige permissões especiais do IAM para acesso (por exemplo, papéis específicos 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 conformidade.	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, o BigQuery com IAM estrito).

A ativação da 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. O tráfego alto e payloads grandes podem levar a custos substanciais de geração de registros e potencial para grandes volumes de registros que excedem os limites e exigem gerenciamento cuidadoso.

Identidade do autor da chamada em registros de auditoria

Ao visualizar 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 serviço integrado Google Cloud : se o Model Armor for integrado 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 autores de 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 da conta, enquanto as chamadas por outros Google Cloud serviços mostram endereços de e-mail de 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 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

Visualizar e filtrar registros do Model Armor

Correlacionar registros e eventos relacionados

Registros de plataforma x registros de auditoria do Cloud

Identidade do autor da chamada em registros de auditoria

Configurar a geração de registros