將 Model Armor 與 Gemini Enterprise Agent Platform 整合

本文說明如何設定 Model Armor，篩選提示詞和回覆，保護 Gemini Enterprise Agent Platform 上的 Gemini 模型。與 Gemini Enterprise Agent Platform 整合後，Model Armor 會在提示詞傳送至 Gemini 模型前攔截，並在回覆傳送至應用程式前攔截。根據您的設定，Gemini Enterprise Agent Platform 會呼叫 Model Armor 服務，檢查或封鎖違反您定義政策的流量，並強制執行安全措施，例如提示詞注入和越獄偵測、負責任的 AI 技術過濾器，以及 Sensitive Data Protection。您可以透過專案層級保護的底價設定，或透過要求層級保護的範本，設定這項整合功能。

Model Armor 可在 Vertex AI 的 Gemini API 中，為 generateContent 方法提供提示詞和回覆防護。您必須啟用 Cloud Logging，才能查看提示和回覆的清除結果。

除了保護對 Gemini Enterprise Agent Platform 服務的直接 REST 呼叫，您也可以使用 Model Armor 保護其他介面，例如 Google 生成式 AI SDK 或 Firebase AI Logic SDK，這些介面可存取 Vertex AI 中的 Gemini API。

限制

將 Model Armor 與 Gemini Enterprise Agent Platform 整合時，請注意下列限制：

• 當 Model Armor 使用 Sensitive Data Protection 範本掃描提示詞或回覆時，會檢查內容是否符合範本中定義的篩選條件。如果找到相符內容，Model Armor 會標記該內容觸發了 Sensitive Data Protection 篩選器。雖然 Sensitive Data Protection 功能會根據範本設定將資料去識別化，但 Model Armor 不會將去識別化資料 (例如遮蓋、刪除或雜湊處理的內容) 傳回 Gemini Enterprise Agent Platform，以供後續處理。如果強制執行類型為 INSPECT_AND_BLOCK，Model Armor 會發出封鎖判決，確保私密資料不會繼續處理。
• 系統不支援清除含有文件的提示和回覆。
• 如果 Gemini Enterprise Agent Platform 將要求傳送至指定 Model Armor 範本不存在的區域，要求就會失敗並顯示 Template not found 錯誤。

• 在下列情況下，Gemini Enterprise Agent Platform 會略過 Model Armor 清理步驟，繼續處理要求：

  • 如果 Gemini Enterprise Agent Platform 所在的區域不支援 Model Armor，
  • 暫時無法連線至 Model Armor。
  • Model Armor 發生錯誤。

  在這些情況下，由於要求會繼續執行，但不會進行提示和回覆內容的清理作業，因此有時可能會顯示未經篩選的提示或回覆。

  雖然這項整合功能可在連線失敗時維持高可用性，但 INSPECT_AND_BLOCK 模式仍會回報設定錯誤，例如權限或配額問題。

事前準備

• 將「Model Armor 使用者」角色授予 Gemini Enterprise Agent Platform 服務帳戶。

  gcloud projects add-iam-policy-binding PROJECT_ID --member='serviceAccount:[e-mail]' --role='roles/modelarmor.user'

  更改下列內容：

  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • PROJECT_NUMBER：您的 Google Cloud 專案編號。

• 啟用 Model Armor API。

• 使用 gcloud CLI 設定 API 端點覆寫。

設定 Model Armor 如何保護 Gemini Enterprise Agent Platform

您可以透過下列兩種方式，設定 Model Armor 如何保護 Gemini Enterprise Agent Platform：

• 使用範本為每個要求提供保護：這個方法可讓您為 Gemini Enterprise Agent Platform 上對 Gemini 模型的每個 generateContent API 呼叫套用特定範本，提供精細的控制權。
• 使用底限設定，在專案層級提供保護：這個方法會對專案中 Gemini Enterprise Agent Platform 上所有 Gemini 模型的 generateContent API 呼叫套用底限設定，強制執行基本保護措施。

定義強制執行類型，決定要檢查違規事項，還是連帶封鎖。

使用範本設定每個要求

您可以透過範本設定 Model Armor 過濾提示詞和回覆的方式，並定義安全篩選器設定。您必須先建立範本，然後透過 Gemini 的 generateContent 方法使用這些範本。如要進一步瞭解範本，請參閱「建立及管理 Model Armor 範本」。

設定 Model Armor 範本後，請使用 generateContent 方法呼叫 Gemini API 時，將範本 ID 做為參數傳遞。Gemini Enterprise Agent Platform 會將要求傳送至 Model Armor 進行處理。

如要將特定範本套用至個別 generateContent 呼叫，請在要求中加入 modelArmorConfig 物件。

• promptTemplateName：Model Armor 範本的資源名稱，用於清除提示。
• responseTemplateName：Model Armor 範本的資源名稱，用於清理回覆內容。

下列程式碼範例顯示對 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"
        }
}'

更改下列內容：

• PROJECT_ID： Google Cloud 專案 ID。
• LOCATION：Gemini 端點的位置。 Google Cloud 支援的位置包括 europe-west1、europe-west2、europe-west3、asia-southeast1 和 asia-south1。
• TEMPLATE_ID：Model Armor 範本 ID。

下列程式碼範例顯示 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"
}

定義範本的強制執行類型

如要設定 Model Armor 處理偵測結果的方式，請設定強制執行類型。

以下範例顯示 Model Armor 範本設定，並採用 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"

更改下列內容：

• PROJECT_ID：範本所屬的專案 ID。
• TEMPLATE_ID：要建立的範本 ID。
• LOCATION：範本的位置。

使用底限設定進行專案層級設定

底限設定會定義最低保護基準，即使 API 要求中省略 modelArmorConfig 參數，專案內的所有 Gemini Enterprise Agent Platform generateContent 呼叫都會套用這項基準。如要瞭解如何設定底限，請參閱「指定底限設定」。

如要啟用 Model Armor 和 Gemini Enterprise Agent Platform 整合功能，請使用 API 或 Google Cloud 控制台，僅在專案層級設定底限設定。

如要透過 Gemini Enterprise Agent Platform 整合功能設定樓層，請執行下列指令：

gcloud

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

這個指令預設會啟用 INSPECT_ONLY 強制執行模式。如要將模式變更為 INSPECT_AND_BLOCK，請執行下列指令：

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

如要從整合式服務中移除 Gemini Enterprise Agent Platform，請執行下列指令：

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

如要從底限設定中移除所有已設定的整合式服務，請執行下列指令：

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

將 PROJECT_ID 替換為底限設定的專案 ID。

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"

將 PROJECT_ID 替換為包含底限設定的專案 ID。

設定底限設定以啟用 Gemini Enterprise Agent Platform 淨化功能後，Model Armor 會使用指定的篩選器設定，淨化所有對專案 Gemini 端點的 generateContent API 呼叫。

以下程式碼範例說明如何使用 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
}
}'

更改下列內容：

• PROJECT_ID：您的 Google Cloud 專案 ID。
• LOCATION：Gemini 端點的 Google Cloud 位置。如要查看支援的位置，請參閱「Model Armor API 支援的位置」。

下列程式碼範例顯示 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"
}

定義底限設定的強制執行類型

如要設定 Model Armor 處理偵測結果的方式，請將強制執行類型設為 INSPECT 或 INSPECT_AND_BLOCK。以下範例顯示採用 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"

更改下列內容：

• PROJECT_ID：樓層設定的專案 ID。
• LOCATION：底限設定的位置。

透過 API 呼叫測試內嵌強制執行

測試整合功能，呼叫 Gemini Enterprise Agent Platform API 的 generateContent 方法。使用設計為違反已設定底限設定的提示。

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
}
}'

如果整合功能運作正常，當 Model Armor 判定提示違規時，API 會傳回 blockReason 欄位設為 MODEL_ARMOR 的回應。

回應範例如下：

    {
    "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"
    }

互動和優先順序規則

搭配 Gemini Enterprise Agent Platform 使用 Model Armor 時，您可以在多個層級定義安全設定。在這種情況下，Model Armor 和 Gemini Enterprise Agent Platform 會依特定優先順序運作：

1. Model Armor 範本：API 要求設定中明確提供的任何設定，優先順序最高。這些設定會覆寫該特定要求的任何其他衝突設定。

2. Model Armor 底限設定：如果 API 要求中未提供任何覆寫設定，系統會套用 Model Armor 底限設定。

3. Gemini Enterprise Agent Platform 安全性篩選器：Gemini Enterprise Agent Platform 內建的預設安全性篩選器優先順序最低。只有在您未定義特定 Model Armor 範本或底限設定時，系統才會套用這些設定。

這種階層式做法結合了廣泛的全機構最低標準 (使用底限設定) 和個別要求控制 (使用範本)，同時仍以 Gemini Enterprise Agent Platform 的固有安全功能做為基準。

Model Armor 和 Gemini Enterprise Agent Platform 安全性功能的運作方式，取決於您提供的設定。

是否已設定範本？	是否已設定 Gemini Enterprise Agent Platform 安全篩選器？	是否已設定底限設定？	行為
是	是	不限	系統會顯示錯誤訊息。您無法在同一個要求中同時指定範本設定和 Gemini Enterprise Agent Platform 安全篩選機制。
是	否	不限	Model Armor 會使用 modelArmorConfig 中指定的範本執行。系統會忽略 Gemini Enterprise Agent Platform 安全篩選器。要求範本覆寫底限設定。
否	是	是	兩者都會執行。Model Armor 會使用底限設定政策掃描， Gemini Enterprise Agent Platform 則會評估安全篩選器。系統會套用最嚴格的結果。
否	否	是	Model Armor 會使用有效的底限設定政策執行。
否	是	否	系統只會評估 Gemini Enterprise Agent Platform 安全性篩選器。 未呼叫 Model Armor。
否	否	否	系統不會套用單次請求的 Model Armor，也不會套用 Gemini Enterprise Agent Platform 安全性篩選器。只有基準模型行為會生效。