Integrar o Model Armor à Gemini Enterprise Agent Platform

Este documento descreve como configurar o Model Armor para proteger modelos do Gemini na Gemini Enterprise Agent Platform, examinando comandos e respostas. Quando integrado à Gemini Enterprise Agent Platform, o Model Armor intercepta comandos antes que eles cheguem aos modelos do Gemini e intercepta respostas antes que seu aplicativo as receba. Com base na sua configuração, a Gemini Enterprise Agent Platform chama o serviço Model Armor, que inspeciona ou bloqueia o tráfego que viola as políticas definidas, aplicando medidas de segurança como injeção de comando e detecção de jailbreak, filtros de IA responsável e Proteção de Dados Sensíveis. É possível configurar essa integração usando as configurações mínimas para proteção para envolvidos no projeto ou usando modelos para proteção por solicitação.

O Model Armor oferece proteção de comandos e respostas na API Gemini na Vertex AI para o método generateContent. É necessário ativar o Cloud Logging para visualizar os resultados da higienização de comandos e respostas.

Além de proteger chamadas REST diretas para o serviço da Gemini Enterprise Agent Platform, também é possível usar o Model Armor para proteger outras interfaces que fornecem acesso à API Gemini na Vertex AI, como os SDKs de IA generativa do Google ou os SDKs do Firebase AI Logic.

Limitações

Considere as seguintes limitações ao integrar o Model Armor à Gemini Enterprise Agent Platform:

  • Quando o Model Armor usa um modelo da Proteção de Dados Sensíveis para verificar comandos ou respostas, ele verifica se o conteúdo corresponde aos critérios de filtro definidos no modelo. Se encontrar uma correspondência, o Model Armor vai sinalizar que o conteúdo acionou o filtro da Proteção de Dados Sensíveis. Embora a Proteção de Dados Sensíveis desidentifique os dados com base na configuração do modelo, o Model Armor não transmite os dados desidentificados, como conteúdo mascarado, encobridor ou com hash, de volta à Gemini Enterprise Agent Platform para processamento adicional. Em vez disso, se o tipo de aplicação for INSPECT_AND_BLOCK, o Model Armor vai emitir um veredito de bloqueio para garantir que os dados sensíveis não sejam processados.
  • A higienização de comandos e respostas que contêm documentos ou uploads de arquivos (como PDFs) não é compatível com essa integração. Para verificar documentos, chame a API REST do Model Armor diretamente.
  • Se a Gemini Enterprise Agent Platform encaminhar uma solicitação para uma região em que o modelo do Model Armor especificado não existe, a solicitação vai falhar com um erro Template not found.

  • A Gemini Enterprise Agent Platform ignora a etapa de higienização do Model Armor e continua processando a solicitação nas seguintes condições:

    • O Model Armor não está disponível em uma região em que a Gemini Enterprise Agent Platform está presente.
    • O Model Armor está temporariamente inacessível.
    • Ocorreu um erro no Model Armor.

    Todas essas instâncias podem expor comandos ou respostas não verificados ocasionalmente porque a solicitação continua sem higienização de comandos e respostas.

    Embora a integração seja criada para alta disponibilidade durante falhas de conexão, o modo INSPECT_AND_BLOCK ainda vai informar erros de configuração, como problemas de permissão ou cota.

Antes de começar

  • Conceda o papel de usuário do Model Armor à conta de serviço da Gemini Enterprise Agent Platform.

    gcloud projects add-iam-policy-binding PROJECT_ID --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com' --role='roles/modelarmor.user'

    Substitua:

    • PROJECT_ID: o ID do Google Cloud projeto.
    • PROJECT_NUMBER: o número do seu Google Cloud projeto.

  • Ative a API Model Armor.

  • Defina a substituição do endpoint de API usando a CLI gcloud.

Configurar como o Model Armor ajuda a proteger a Gemini Enterprise Agent Platform

É possível configurar como o Model Armor protege a Gemini Enterprise Agent Platform de duas maneiras:

  • Usar modelos para proteção por solicitação: essa abordagem oferece controle granular , permitindo que você aplique um modelo específico a cada generateContent chamada de API para modelos do Gemini na Gemini Enterprise Agent Platform.
  • Usar configurações mínimas para proteção no nível do projeto: essa abordagem aplica uma proteção de linha de base, aplicando configurações mínimas a todas as generateContent chamadas de API para modelos do Gemini na Gemini Enterprise Agent Platform no seu projeto.

Defina o tipo de aplicação para determinar se as violações são apenas inspecionadas ou também bloqueadas.

Configuração por solicitação usando modelos

Os modelos permitem configurar como o Model Armor verifica comandos e respostas e definir configurações de filtro de segurança. Primeiro, é necessário criar modelos e, em seguida, usá-los com o método generateContent do Gemini. Para mais informações sobre modelos, consulte Criar e gerenciar modelos do Model Armor.

Depois de configurar o modelo do Model Armor, transmita o ID do modelo como um parâmetro ao fazer uma chamada para a API Gemini usando o método generateContent. A Gemini Enterprise Agent Platform encaminha a solicitação para o Model Armor para processamento.

Para aplicar modelos específicos a uma chamada generateContent individual, inclua o objeto modelArmorConfig na solicitação.

  • promptTemplateName: o nome do recurso do modelo do Model Armor para higienizar o comando.
  • responseTemplateName: o nome do recurso do modelo do Model Armor para higienizar a resposta.

O exemplo de código a seguir mostra a solicitação para o método generateContent.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.0-flash-001:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": "[YOUR PROMPT HERE]"
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
},
 "model_armor_config": {
        "prompt_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "response_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
        }
}'

Substitua:

  • PROJECT_ID: o Google Cloud ID do projeto.
  • LOCATION: a Google Cloud localização do endpoint do Gemini. Os locais compatíveis são europe-west1, europe-west2, europe-west3, asia-southeast1 e asia-south1.
  • TEMPLATE_ID: ID do modelo do Model Armor.

O exemplo de código a seguir mostra a resposta do método generateContent.

{
  "promptFeedback": {
    "blockReason": "MODEL_ARMOR",
    "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection and Jailbreak filters."
  },
  "usageMetadata": {
    "trafficType": "ON_DEMAND"
  },
  "modelVersion": "gemini-2.0-flash-001",
  "createTime": "2025-03-26T13:14:36.961184Z",
  "responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Definir o tipo de aplicação para modelos

Para configurar como o Model Armor processa detecções, defina o tipo de aplicação.

O exemplo a seguir mostra a configuração do modelo do Model Armor com o tipo de aplicação Inspect only.

export TEMPLATE_CONFIG='{
   "filter_config": {
    "rai_settings": {
     "rai_filters": [{
       "filter_type": "HATE_SPEECH",
       "confidence_level": "MEDIUM_AND_ABOVE"
      }, {
      "filter_type": "HARASSMENT",
      "confidence_level": "MEDIUM_AND_ABOVE"
    }, {
      "filter_type": "DANGEROUS",
      "confidence_level": "MEDIUM_AND_ABOVE"
    },{
      "filter_type": "SEXUALLY_EXPLICIT",
      "confidence_level": "MEDIUM_AND_ABOVE"
    }]
  },
  "pi_and_jailbreak_filter_settings": {
    "filter_enforcement": "ENABLED",
    "confidence_level": "LOW_AND_ABOVE"
  },
  "malicious_uri_filter_settings": {
    "filter_enforcement": "ENABLED"
  }
 },
 "template_metadata": {
    "enforcement_type": "INSPECT_ONLY",
    "multi_language_detection": {
      "enable_multi_language_detection": true
    }
  }
}'

curl -X POST \
    -d "$TEMPLATE_CONFIG"  \
    -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.
  • TEMPLATE_ID: o ID do modelo a ser criado.
  • LOCATION: o local do modelo.

Configuração para envolvidos no projeto usando configurações mínimas

As configurações mínimas definem uma linha de base mínima de proteção que se aplica a todas as chamadas generateContent da Gemini Enterprise Agent Platform em um projeto, mesmo que o parâmetro modelArmorConfig seja omitido da solicitação de API. Consulte Definir configurações mínimas para saber como configurar as configurações mínimas.

Para ativar a integração do Model Armor e da Gemini Enterprise Agent Platform, defina as configurações mínimas apenas no nível do projeto usando a API ou o Google Cloud console.

Para configurar as configurações mínimas com a integração da Gemini Enterprise Agent Platform, execute o seguinte comando:

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --add-integrated-services=VERTEX_AI

Esse comando ativa o modo de aplicação INSPECT_ONLY por padrão. Para mudar o modo para INSPECT_AND_BLOCK, execute o seguinte comando:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

Para remover a Gemini Enterprise Agent Platform dos serviços integrados, execute o seguinte comando:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --remove-integrated-services=VERTEX_AI

Para remover todos os serviços integrados configurados das configurações mínimas, execute o seguinte comando:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --clear-integrated-services

Substitua PROJECT_ID pelo ID do projeto para as configurações mínimas.

REST

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{"filterConfig" : {"piAndJailbreakFilterSettings": { "filterEnforcement": "ENABLED"}}, "integratedServices": ["AI_PLATFORM"], "aiPlatformFloorSetting":{"inspectOnly":true, "enableCloudLogging":true}, "enableFloorSettingEnforcement":true}' \
  "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

Substitua PROJECT_ID pelo ID do projeto que contém as configurações mínimas.

Depois de configurar as configurações mínimas para ativar a higienização da Gemini Enterprise Agent Platform, o Model Armor higieniza todas as chamadas de API generateContent para os endpoints do Gemini do projeto usando as configurações de filtro especificadas.

O exemplo de código a seguir mostra como usar o método generateContent.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
  {
      "role": "user",
      "parts": [
          {
              "text": ""
          }
      ]
  }
]
, "generationConfig": {
  "responseModalities": ["TEXT"]
  ,"temperature": 0.2
  ,"maxOutputTokens": 1024
  ,"topP": 0.8
}
}'

Substitua:

  • PROJECT_ID: o ID do Google Cloud projeto.
  • LOCATION: a Google Cloud localização do endpoint do Gemini. Para locais compatíveis, consulte Locais da API Model Armor.

O exemplo de código a seguir mostra a resposta do método generateContent.

{
"promptFeedback": {
  "blockReason": "MODEL_ARMOR",
  "blockReasonMessage": "Blocked by Floor Setting. The prompt violated
  Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection
  and Jailbreak filters."
},
"usageMetadata": {
  "trafficType": "ON_DEMAND"
},
"modelVersion": "gemini-2.5-flash",
"createTime": "2025-03-26T13:14:36.961184Z",
"responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Definir o tipo de aplicação para configurações mínimas

Para configurar como o Model Armor processa detecções, defina o tipo de aplicação como INSPECT ou INSPECT_AND_BLOCK. O exemplo a seguir mostra a configuração das configurações mínimas com o tipo de aplicação INSPECT_AND_BLOCK.

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/modelarmor-api-test/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

REST

export FLOOR_SETTING='{
  "filterConfig": {
    "raiSettings": {
      "raiFilters": [
        { "filterType": "HATE_SPEECH", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "DANGEROUS", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "HARASSMENT", "confidenceLevel": "LOW_AND_ABOVE" }
      ]
    },
    "sdpSettings": {
      "basicConfig": { "filterEnforcement": "ENABLED" }
    },
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED",
      "confidenceLevel": "LOW_AND_ABOVE"
    },
    "maliciousUriFilterSettings": { "filterEnforcement": "ENABLED" }
  },
  "integratedServices": ["AI_PLATFORM"],
  "aiPlatformFloorSetting": {
    "inspectAndBlock": true,
    "enableCloudLogging": true
  },
  "enableFloorSettingEnforcement": true
}'

curl -X PATCH \
    -d "$FLOOR_SETTING" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

Substitua:

  • PROJECT_ID: o ID do projeto para as configurações mínimas.
  • LOCATION: o local das configurações mínimas.

Testar a aplicação in-line com uma chamada de API

Teste a integração para chamar o método generateContent da API Gemini Enterprise Agent Platform. Use um comando projetado para violar as configurações mínimas configuradas.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://${VERTEX_AI_LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${VERTEX_AI_LOCATION}/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": ""
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
}
}'

Se a integração estiver funcionando conforme o esperado, a API vai retornar uma resposta com o campo blockReason definido como MODEL_ARMOR quando o Model Armor identificar o comando como uma violação.

Confira um exemplo de resposta:

    {
    "promptFeedback": {
      "blockReason": "MODEL_ARMOR",
      "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings..."
    },
    "usageMetadata": { "trafficType": "ON_DEMAND" },
    "modelVersion": "gemini-2.5-flash"
    }

Regras de interação e precedência

Ao usar o Model Armor com a Gemini Enterprise Agent Platform, é possível definir configurações de segurança em vários níveis. Nesses casos, o Model Armor e a Gemini Enterprise Agent Platform seguem uma ordem de precedência específica:

  1. Modelos do Model Armor: qualquer configuração fornecida explicitamente na configuração da solicitação de API tem a maior precedência. Essas configurações substituem qualquer outra configuração conflitante para essa solicitação específica.

  2. Configurações mínimas do Model Armor: se nenhuma configuração de substituição for fornecida na solicitação de API, as configurações mínimas do Model Armor serão aplicadas.

  3. Filtros de segurança da Gemini Enterprise Agent Platform: os filtros de segurança padrão integrados à Gemini Enterprise Agent Platform têm a menor precedência. Eles só serão aplicados se você não definir modelos ou configurações mínimas específicos do Model Armor.

Essa abordagem hierárquica oferece uma combinação de padrões mínimos amplos em toda a organização (usando configurações mínimas) e controle por solicitação (usando modelos), enquanto ainda usa os recursos de segurança inerentes da Gemini Enterprise Agent Platform como uma linha de base.

O comportamento do Model Armor e dos recursos de segurança da Gemini Enterprise Agent Platform depende de como você fornece a configuração.

Modelo configurado? Filtros de segurança da Gemini Enterprise Agent Platform configurados? Configurações mínimas configuradas? Comportamento
Sim Sim Qualquer Você recebe um erro. Não é possível especificar a configuração do modelo e os filtros de segurança da Gemini Enterprise Agent Platform na mesma solicitação.
Sim Não Qualquer O Model Armor é executado usando os modelos especificados em modelArmorConfig. Os filtros de segurança da Gemini Enterprise Agent Platform são ignorados. Os modelos de solicitação substituem as configurações mínimas.
Não Sim Sim Ambos são executados. O Model Armor verifica usando a política de configuração mínima, e a Gemini Enterprise Agent Platform avalia os filtros de segurança. O resultado mais restritivo é aplicado.
Não Não Sim O Model Armor é executado usando a política de configuração mínima ativa.
Não Sim Não Somente os filtros de segurança da Gemini Enterprise Agent Platform são avaliados. O Model Armor não é chamado.
Não Não Não Nem o Model Armor por solicitação nem os filtros de segurança da Gemini Enterprise Agent Platform são aplicados. Somente os comportamentos do modelo de linha de base estão ativos.