Configurar a geração de registros para o Model Armor

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 Visão geral do registro de auditoria do Model Armor.

Antes de começar

Conclua estas tarefas antes de concluir as restantes nesta página.

Receber as permissões necessárias

Para receber as permissões necessárias a fim de 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 as APIs do Model Armor antes de usar o Model Armor.

Console

  1. Enable the Model Armor API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  2. Selecione o projeto em que você quer ativar o Model Armor.

gcloud

Antes de começar, siga estas etapas usando a CLI do Google Cloud com a API Model Armor:

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Execute o comando a seguir para definir o endpoint da 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.

    3. Execute o comando a seguir para ativar o Model Armor.

      gcloud services enable modelarmor.googleapis.com --project=PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto.

    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 o registro em log das operações de criação, atualização, leitura e exclusão de modelos.

    • log_sanitize_operations: um valor booleano que ativa o registro das operações de limpeza. Os registros incluem o comando e a resposta, os resultados da avaliação do Model Armor e outros campos de metadados.

    Console

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

      Acessar o Model Armor

    2. Verifique se você está visualizando o projeto em que ativou o Model Armor.

    3. Na página Model Armor, clique em Criar modelo. Para mais informações sobre como criar modelos, consulte Criar um modelo do Model Armor.

    4. Na seção Configurar geração de registros, selecione as operações para as quais você quer configurar a geração de registros.

    5. 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.

    Ver registros

    Acessar os registros do Model Armor usando o Explorador de registros no Cloud Logging. Para mais informações, consulte Ver registros usando o Explorador de registros. Filtre pelo nome do serviço modelarmor.googleapis.com. Procure entradas relacionadas às operações que você ativou no modelo. Para conferir uma lista de todos os nomes de serviços e tipos de recursos monitorados, consulte Recursos e serviços monitorados.

    Filtrar registros do Model Armor

    Use rótulos de registro para filtrar os registros do Model Armor nas operações de limpeza e no registro de modelo.

    Execute a consulta a seguir no Explorador de registros para filtrar os registros de operações de limpeza.

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

    Para refinar ainda mais os registros de operações de limpeza, especifique um ID do projeto, um nome do cliente ou um ID de correlação na consulta.

    • Usando um ID do projeto:

      jsonPayload.@type="type.googleapis.com%2Fgoogle.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry";project=PROJECT_ID

    • Usar um nome de cliente:

      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:

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

    Substitua:

    • PROJECT_ID: o ID do projeto do Google Cloud .
    • CLIENT_NAME: o nome do cliente.
    • CORRELATION_ID: o identificador exclusivo que você gera para uma solicitação específica.

    Correlacionar registros e eventos relacionados

    Para correlacionar registros e eventos relacionados a essa interação específica, você precisa de um ID de correlação do cliente. É um identificador exclusivo gerado por você (por exemplo, um UUID) para rastrear uma solicitação específica no seu 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. Este é o formato de exemplo:

    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.