Imagens de tela

O Model Armor analisa imagens independentes e incorporadas em documentos de rich text compatíveis em comandos e respostas para ajudar a proteger seus aplicativos de IA generativa contra riscos incorporados em imagens.

O Model Armor analisa imagens usando os seguintes métodos:

Especificações e limitações

Considere as seguintes especificações e limitações ao usar o Model Armor para filtrar imagens:

  • Formatos de imagem compatíveis: o Model Armor analisa imagens independentes nos formatos JPEG, PNG e BMP. Ele também extrai e analisa imagens incorporadas de arquivos de rich text compatíveis.
  • Limites de tamanho: cada imagem independente precisa ter no máximo 4 MB. Os arquivos de rich text precisam ter até 4 MB e conter no máximo 5 imagens incorporadas. Exceder qualquer um desses limites faz com que o Model Armor pule a verificação do arquivo inteiro. Para mais informações, consulte Limite do sistema de tamanho de arquivo e Filtrar imagens incorporadas em documentos.
  • Comandos independentes: quando você chama os métodos SanitizeUserPrompt e SanitizeModelResponse com imagens independentes, o Model Armor analisa uma única imagem por solicitação. Não é possível fazer a triagem de várias imagens independentes em uma única solicitação. Além disso, o Model Armor não é compatível com comandos independentes que combinam texto e imagens em uma única solicitação. No entanto, é possível analisar documentos de rich text que contêm texto e imagens ativando as modalidades de texto e imagem.
  • Desidentificação: quando você configura um modelo de desidentificação da Proteção de Dados Sensíveis, o Model Armor encobre texto ou imagens independentes, não ambos. A desidentificação não é compatível com documentos de rich text quando a modalidade de imagem (MODALITY_IMAGE) está selecionada. Para mais informações, consulte Encobrir dados sensíveis em imagens independentes e Analisar imagens incorporadas em documentos.
  • Streaming: os métodos de streaming do Model Armor aceitam apenas entrada textual e não aceitam imagens ou arquivos.
  • Integrações compatíveis: é possível analisar imagens chamando a API REST do Model Armor diretamente ou pela integração do Gemini Enterprise. Todas as outras integrações do Model Armor verificam e limpam apenas texto. Para mais informações, consulte Modalidades compatíveis.
  • Disponibilidade regional: a verificação de imagens só está disponível em algumas multirregiões. Se você enviar um comando com uma imagem para um endpoint em que o Model Armor não oferece suporte à verificação de imagens, o campo invocationResult na resposta vai indicar FAILURE. Para uma lista de locais que oferecem suporte à triagem de imagens, consulte Recursos compatíveis por região.

Cálculo de tokens e preços para imagens

O Model Armor usa um modelo de preços unificado baseado em tokens, em que os tokens de imagem são cobrados na mesma taxa que os tokens de texto.

Você não recebe cobranças quando o Model Armor rejeita ou ignora uma entrada antes do processamento do filtro, como entradas vazias ou arquivos e imagens que excedem os limites de tamanho de arquivo ou de imagem incorporada. No entanto, se uma entrada passar na validação inicial, você vai receber uma cobrança pelos tokens calculados, mesmo nos seguintes casos:

  • Todos os detectores são ignorados: alguns ou todos os filtros (detectores) configurados são ignorados e retornam EXECUTION_SKIPPED (por exemplo, quando um payload de imagem dentro do limite de 4 MB não pode ser analisado por detectores ou quando um filtro é ignorado para uma modalidade).
  • Arquivos que não são de imagem encapsulados com o tipo de dados de byte IMAGE: um arquivo que não é de imagem (como um documento ZIP, CSV ou Microsoft Word) é enviado com byteDataType definido como IMAGE (até 4 MB). O Model Armor cobra a solicitação usando o cálculo de token de imagem independente, mesmo que os filtros retornem EXECUTION_SKIPPED.

O Model Armor calcula tokens para imagens e documentos com base no tipo de entrada e nas modalidades configuradas:

  • Imagens independentes: o Model Armor converte cada imagem processada (até 4 MB) em tokens usando uma contagem base de 5.000 tokens por imagem, mais 1.000 tokens por megabyte (MB) de tamanho de imagem. Ao calcular tokens com base no tamanho, o Model Armor arredonda o tamanho da imagem para o próximo MB inteiro:

    Tokens por imagem = 5.000 + (1.000 × tamanho da imagem em MB, arredondado para o próximo MB inteiro)

    O texto extraído de uma imagem por OCR é incluído no cálculo do token de imagem e não gera cobranças separadas de token de texto.

  • Documentos de rich text: o cálculo de tokens depende das modalidades configuradas no seu modelo:

    • Modalidade de texto (MODALITY_TEXT): o Model Armor calcula os tokens do texto extraído do documento (cerca de 4 caracteres por token). As imagens incorporadas não são extraídas nem faturadas.
    • Modalidade de imagem (MODALITY_IMAGE): o Model Armor calcula os tokens individualmente para cada imagem incorporada processada usando a fórmula de token de imagem. O texto do documento não é faturado.
    • Modalidades de texto e imagem (MODALITY_TEXT e MODALITY_IMAGE): o Model Armor calcula a contagem total de tokens como a soma dos tokens do texto do documento extraído e dos tokens de cada imagem incorporada processada.

A tabela a seguir mostra exemplos de como o Model Armor calcula tokens para imagens processadas:

Tamanho da imagem Tamanho arredondado para cálculo Cálculo de tokens Total de tokens
500 KB 1 MB 5.000 + (1 × 1.000) 6.000 tokens
1,9 MB 2 MB 5.000 + (2 × 1.000) 7.000 tokens
4 MB 4 MB 5.000 + (4 × 1.000) 9.000 tokens

Antes de começar

Antes de filtrar imagens, conclua os seguintes pré-requisitos:

Criar ou atualizar um modelo com a modalidade de imagem ativada

Ao criar ou atualizar um modelo, selecione a modalidade para incluir MODALITY_IMAGE (Imagem ou Todas no console do Google Cloud , ou "modalities": ["MODALITY_IMAGE", "MODALITY_TEXT"] em templateMetadata ao usar a API REST). Se você não especificar uma modalidade, deixar o campo modalities vazio ou especificar apenas MODALITY_TEXT, o Model Armor vai verificar apenas o texto e retornar EXECUTION_SKIPPED para filtros que verificam a modalidade ignorada.

Conseguir as permissões necessárias

Verifique se você tem os papéis necessários do Identity and Access Management para limpar solicitações e respostas (como roles/modelarmor.user) e, se você usar o modo avançado da Proteção de Dados Sensíveis em vários projetos, conceda os papéis de DLP necessários ao agente de serviço do Model Armor. Para instruções, consulte Receber as permissões necessárias.

Limpar imagens independentes

Para analisar uma imagem independente em um comando do usuário ou em uma resposta do modelo, defina o campo byteDataType como IMAGE e forneça a imagem codificada em Base64 em um formato compatível (JPEG, PNG ou BMP) no campo byteData.

Use o comando a seguir para limpar um comando que contém uma imagem:

curl -X POST \
    -d "$(jq -n \
    --arg data "$(base64 -w 0 -i IMAGE)" \
    '{userPromptData: {byteItem: {byteDataType: "IMAGE", byteData: $data}}}')" \
    -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:sanitizeUserPrompt"

Substitua:

  • PROJECT_ID: o ID do projeto que contém o modelo.
  • LOCATION: o local do modelo.
  • TEMPLATE_ID: o ID de um modelo configurado para verificar imagens (MODALITY_IMAGE).
  • IMAGE: o caminho para o arquivo de imagem em um formato compatível.

O resultado parecido com este:

{
  "sanitizationResult": {
    "filterMatchState": "MATCH_FOUND",
    "invocationResult": "SUCCESS",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "pi_and_jailbreak": {
        "piAndJailbreakFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "MATCH_FOUND",
          "confidenceLevel": "HIGH"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "inspectResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "MATCH_FOUND"
          }
        }
      }
    }
  }
}

Encobrir dados sensíveis em imagens independentes

Quando você usa o modo avançado da Proteção de Dados Sensíveis, o Model Armor encobre as descobertas sensíveis em imagens independentes se você configurar o modelo do Model Armor com um modelo de inspeção e um modelo de desidentificação da Proteção de Dados Sensíveis. Configure a remoção de imagem no modelo de desidentificação. Para mais informações sobre como configurar a Proteção de Dados Sensíveis no Model Armor, consulte Definir configurações da Proteção de Dados Sensíveis. Para informações sobre as limitações de desidentificação, consulte Especificações e limitações e Imagens incorporadas à tela em documentos.

O exemplo a seguir mostra a configuração do filtro com a encobertura da Proteção de Dados Sensíveis ativada:

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate": "projects/PROJECT_ID/locations/LOCATION/inspectTemplates/INSPECT_TEMPLATE_ID",
        "deidentifyTemplate": "projects/PROJECT_ID/locations/LOCATION/deidentifyTemplates/DEIDENTIFY_TEMPLATE_ID"
      }
    }
  }
}

Substitua:

  • PROJECT_ID: o ID do projeto que contém os modelos da Proteção de Dados Sensíveis.
  • LOCATION: o local dos modelos.
  • INSPECT_TEMPLATE_ID: o ID do modelo de inspeção.
  • DEIDENTIFY_TEMPLATE_ID: o ID do modelo de desidentificação.

Quando você limpa uma imagem independente usando um modelo com a edição de imagem ativada, a resposta inclui a imagem editada e as coordenadas da caixa delimitadora para cada descoberta:

{
  "sanitizationResult": {
    "filterMatchState": "MATCH_FOUND",
    "invocationResult": "SUCCESS",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "redactResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "MATCH_FOUND",
            "redactedImage": "[REDACTED_IMAGE]",
            "findings": [
              {
                "infoType": "EMAIL_ADDRESS",
                "likelihood": "LIKELY",
                "location": {
                  "contentLocations": [
                    {
                      "imageFindingLocation": {
                        "boundingBoxes": {
                          "top": 16,
                          "left": 121,
                          "width": 620,
                          "height": 90
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    }
  }
}

Analisar imagens incorporadas em documentos

Quando você ativa a modalidade de imagem (MODALITY_IMAGE) no seu modelo e limpa um documento de rich text (PDF, WORD_DOCUMENT, EXCEL_DOCUMENT ou POWERPOINT_DOCUMENT), o Model Armor extrai e analisa automaticamente até cinco imagens incorporadas no documento. Se você ativar MODALITY_TEXT e MODALITY_IMAGE, o Model Armor vai verificar o texto do documento e as imagens incorporadas.

Se você ativar apenas MODALITY_IMAGE ou ambos MODALITY_IMAGE e MODALITY_TEXT, o Model Armor vai pular a verificação de todo o documento, incluindo texto e imagens incorporadas, sem verificação parcial. Ele retorna EXECUTION_SKIPPED para todos os filtros configurados, incluindo inspeção, e um filterMatchState geral de NO_MATCH_FOUND nos seguintes casos:

  • O documento excede o limite de tamanho de arquivo de 4 MB ou o limite de cinco imagens.
  • Um modelo de desidentificação da Proteção de Dados Sensíveis está configurado. Para inspecionar documentos de rich text quando a modalidade de imagem estiver ativada, configure apenas um modelo de inspeção sem um modelo de desidentificação.

Para exemplos de código que mostram como enviar comandos baseados em arquivos usando REST e bibliotecas de cliente, consulte Comandos baseados em arquivos.

Inspeção parcial de arquivos

O Model Armor retorna um resultado parcial (invocationResult: PARTIAL) apenas no nível do filtro (detector) em todo o arquivo, em vez de por imagem:

  • Falha por imagem (arquivo inteiro ignorado): se algumas imagens incorporadas em um arquivo forem verificadas, mas uma ou mais imagens no arquivo não forem extraídas ou verificadas, o Model Armor vai ignorar o arquivo inteiro. Ele retorna executionState: EXECUTION_SKIPPED para todos os filtros configurados e um filterMatchState geral de NO_MATCH_FOUND.
  • Falha no nível do detector (resultado parcial): se alguns filtros configurados forem bem-sucedidos no arquivo, mas um ou mais filtros forem ignorados para o arquivo inteiro (por exemplo, devido a um tempo limite do detector), o Model Armor vai retornar um resultado parcial com os seguintes campos:
    • Resultado da invocação: o campo invocationResult é definido como PARTIAL (em vez de SUCCESS), indicando que um ou mais filtros configurados foram ignorados para o arquivo enquanto outros filtros concluíram a inspeção.
    • Estado de execução do filtro: filtros que foram ignorados no relatório de arquivos executionState: EXECUTION_SKIPPED. Filtros que concluíram a inspeção no relatório de arquivos executionState: EXECUTION_SUCCESS.
    • Estado de correspondência: o campo filterMatchState reflete as descobertas dos filtros que concluíram a inspeção. Se algum filtro concluído detectar uma violação, filterMatchState será definido como MATCH_FOUND. Se nenhuma violação for detectada pelos filtros concluídos, filterMatchState será definido como NO_MATCH_FOUND.

Considerações de segurança com inspeção parcial

Do ponto de vista da segurança, um valor invocationResult de PARTIAL indica que um ou mais filtros configurados não conseguiram avaliar o arquivo. Possíveis ameaças à segurança ou violações da política visadas pelos filtros ignorados ainda podem estar presentes no arquivo.

Por padrão, se os filtros que concluíram a inspeção não detectarem violações de política, filterMatchState será NO_MATCH_FOUND. Se o aplicativo exigir que todos os filtros configurados concluam a inspeção antes de permitir que os comandos cheguem a um modelo de IA, inspecione o campo invocationResult na resposta. Se o valor for PARTIAL, configure a lógica do aplicativo para processar a solicitação de acordo com a tolerância ao risco da sua organização, como rejeitar o comando ou encaminhá-lo para uma análise secundária.

Exemplo de resposta de inspeção parcial

O exemplo a seguir mostra uma resposta em que o filtro de material de abuso sexual infantil (CSAM, na sigla em inglês) foi ignorado para o arquivo, enquanto outros filtros configurados concluíram a inspeção. O Model Armor retorna um invocationResult de PARTIAL, um status EXECUTION_SKIPPED para o filtro de CSAM e EXECUTION_SUCCESS para os filtros restantes:

{
  "sanitizationResult": {
    "filterMatchState": "NO_MATCH_FOUND",
    "invocationResult": "PARTIAL",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SKIPPED",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "pi_and_jailbreak": {
        "piAndJailbreakFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "inspectResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "NO_MATCH_FOUND"
          }
        }
      }
    }
  }
}

A seguir