在閘道上設定 Model Armor

Model Armor 可確保 AI 代理遵循您的安全性和管理標準，您不必直接在代理中實作篩選邏輯。使用 Agent Gateway 設定 Model Armor 時，Model Armor 會檢查通過閘道的所有提示詞和回覆，套用貴組織的內容安全防護機制。這項功能可讓您在閘道控管的所有代理中，一致強制執行內容安全防護措施。Model Armor 可協助您降低提示詞注入、越獄、機密資訊外洩和生成有害內容等風險。詳情請參閱「Model Armor 篩選器」。

Model Armor 範本

如要在閘道設定 Model Armor，請建立範本，指定如何篩選 AI 代理收到的提示詞和傳回的回覆。範本提供自訂的篩選條件和門檻，適用於多種安全類別。詳情請參閱「Model Armor 範本」。

Model Armor 會將篩選功能直接嵌入 Agent Gateway 管理的通訊路徑。內容通過 Model Armor 時，閘道會強制執行內容安全範本。您可以在範本中設定 Model Armor，遮蓋或封鎖違反範本的內容。

輸入和輸出流量

Model Armor 可透過 Agent Gateway 保護下列流量。

用戶端至代理 (代理輸入)

您定義的範本會由 Model Armor 用於評估用戶端與代理之間流量的要求和回覆。您可以將單一範本套用至兩個方向，也可以為每個方向設定不同的範本。

Model Armor 會依據範本篩選下列內容：

• 用戶端 (使用者或呼叫應用程式) 傳送至 AI 代理的要求
• AI 代理傳回用戶端的回應

用戶端傳送提示詞給代理時，Agent Gateway 會攔截流量，並將酬載傳送至 Model Armor 進行清理。如果 Model Armor 發出 ALLOW 判定結果，Agent Gateway 會將提示傳送至 AI 代理。如果 Model Armor 發出 BLOCK 判定，用戶端會收到錯誤訊息，流程也會在到達 AI 代理前結束。

AI 代理處理要求並生成回覆後，Agent Gateway 會在傳出串流到達用戶端前攔截。Model Armor 會評估回覆並做出裁決。Agent Gateway 會根據判定結果，允許或完全封鎖回覆。

代理至任意目的地 (代理輸出)

您定義的範本會由 Model Armor 用於評估 Agent-to-Anywhere 流量中的要求和回覆。您可以將單一範本套用至兩個方向，也可以為每個方向設定不同的範本。

Model Armor 會依據範本，篩選 AI 代理與外部系統之間的通訊內容，包括：

• 外部大型語言模型 (LLM)
• 第三方 AI 代理
• Model Context Protocol (MCP) 伺服器

AI 代理與外部系統通訊時，Agent Gateway 會攔截輸出流量並呼叫 Model Armor。Model Armor 會根據您設定的輸出範本評估酬載。

如果輸出資料違反安全政策，Model Armor 會做出 BLOCK 判定。接著，Agent Gateway 會終止連線，防止有害或機密資料傳送至 LLM、工具或外部 AI 代理。

事前準備

啟用 Model Armor API (如果尚未啟用)。

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

啟用 API

必要的角色

如要取得建立 Model Armor 範本所需的權限，請要求管理員授予您專案的 Model Armor 管理員 (roles/modelarmor.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

如要瞭解使用 Agent Gateway 所需的角色，請參閱 Agent Gateway 說明文件中的「必要角色」。

如要瞭解通過閘道的支援和不支援酬載，請參閱本文件中的「支援和不支援的酬載」一節。

在閘道設定 Model Armor

如要在閘道上設定 Model Armor，請按照下列步驟操作：

1. 在要建立 Model Armor 範本的專案中，啟用 Model Armor API。

2. 在您打算新增閘道的區域，建立一或多個 Model Armor 範本。您可以將同一個範本用於輸入和輸出流量。

   記下範本名稱。如要在Google Cloud 控制台複製範本名稱，請查看範本詳細資料，然後按一下範本名稱旁的content_copy「Copy to clipboard」(複製到剪貼簿)。

   如果您在不同專案中建立 Model Armor 範本，而該專案包含 AI 代理或 Agent Gateway，且您使用 VPC Service Controls，則這兩個專案必須位於相同的 VPC Service Controls 服務範圍。

3. 在儲存 Model Armor 範本的區域設定 Agent Gateway。在「Client-to-Agent (ingress) gateway」(用戶端至代理 (輸入) 閘道) 部分，指定您為輸入流量建立的 Model Armor 範本。在「Agent-to-Anywhere (egress) gateway」(代理至任何位置 (輸出) 閘道) 部分，指定您為輸出流量建立的 Model Armor 範本。兩個流量方向可使用相同範本。

4. 將必要的 IAM 角色授予適當的服務代理：

   • 用戶端至代理 (輸入)：將下列角色授予 AI 平台推論引擎服務代理：

     • 在含有 AI 代理的專案中，具備 Model Armor 呼叫使用者 (roles/modelarmor.calloutUser) 角色。

     • 在含有 Model Armor 範本的專案中，具備 Model Armor 使用者 (roles/modelarmor.user) 角色。

     gcloud projects add-iam-policy-binding AGENT_RUNTIME_PROJECT_ID \
         --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
         --role=roles/modelarmor.calloutUser
     gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
         --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
         --role=roles/modelarmor.user
     

     更改下列內容：

     • AGENT_RUNTIME_PROJECT_ID：您建立代理的專案 ID。
     • AGENT_RUNTIME_PROJECT_NUMBER：您建立代理的專案編號。
     • MODEL_ARMOR_PROJECT_ID：Model Armor 範本所在專案的專案 ID。

   • 代理至任意目的地 (輸出)：將下列角色授予 Service Extensions 服務代理：

     • 在含有閘道的專案中，具備 Model Armor 呼叫使用者 (roles/modelarmor.calloutUser) 和服務使用情形消費者 (roles/serviceusage.serviceUsageConsumer) 角色。
     • 在含有 Model Armor 範本的專案中，具備 Model Armor 使用者 (roles/modelarmor.user) 角色。

     gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
         --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
         --role=roles/modelarmor.calloutUser
     gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
         --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
         --role=roles/serviceusage.serviceUsageConsumer
     gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
         --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
         --role=roles/modelarmor.user
     

     更改下列內容：

     • GATEWAY_PROJECT_ID：您建立閘道的 專案 ID。
     • GATEWAY_PROJECT_NUMBER：您建立閘道的專案編號。
     • MODEL_ARMOR_PROJECT_ID：Model Armor 範本所在專案的專案 ID。

     如需操作說明，請參閱「將授權委派給 Model Armor」。

   如要瞭解如何授予角色，請參閱「授予單一 IAM 角色」。

選用：預先部署範本驗證檢查

將範本部署至閘道前，您可以執行部署前檢查，確認範本設定是否正確強制執行安全性政策。

您可以使用一組測試提示，直接查詢 sanitizeUserPrompt 方法，驗證範本。如要進一步瞭解如何執行這項部署前檢查，以及查看已驗證的測試提示清單，請參閱「測試 Model Armor 範本」。

遮蓋要求和回應中的機密資料

您可以指示 Model Armor 遮蓋酬載中的敏感資料，例如身分證字號和電話號碼。如要使用這項功能，請按照下列步驟操作：

• 在 Model Armor 範本中設定進階 Sensitive Data Protection 設定，並加入去識別化範本。

• 將 Model Armor 範本的強制執行類型設為 INSPECT_AND_BLOCK。

如果使用 INSPECT_AND_BLOCK 強制執行類型，會發生下列其中一種情況：

• 如果酬載僅違反 Sensitive Data Protection 偵測工具，Model Armor 會根據您的進階 Sensitive Data Protection 設定和去識別化範本，遮蓋酬載。

• 如果酬載違反多個偵測工具，Model Armor 不會執行遮蓋，而是封鎖整個酬載。

如果使用 INSPECT_ONLY 強制執行類型，而非 INSPECT_AND_BLOCK，Model Armor 不會遮蓋酬載。

無論強制執行類型為何 (INSPECT_ONLY 或 INSPECT_AND_BLOCK)，Model Armor 記錄都會根據進階 Sensitive Data Protection 設定和去識別化範本進行遮蓋。

如需 Model Armor 偵測工具 (也稱為篩選器) 的完整清單，請參閱「Model Armor 篩選器」。

支援和不支援的酬載

本節列出 Model Armor 清理的酬載類型。

用戶端至代理 (輸入) 流量

對於使用 ADK 通訊協定的用戶端對代理 (輸入) 流量，Model Armor 只會清理 reasoningEngines.streamQuery 要求和回應，這些要求和回應是針對使用 Agent Development Kit (ADK) 建構，且在 Vertex AI Agent Engine 上執行的代理。

所有其他 ReasoningEngine 酬載和 ReasoningEngine 錯誤回應都不會傳送至 Model Armor。非 ADK 酬載 (例如 Langchain 酬載) 也不會傳送至 Model Armor。

代理至任意目的地 (輸出) 流量

代理程式對任何位置 (輸出) 的流量支援下列酬載。

A2A 酬載

Model Armor 只會清理 A2A v1 通訊協定的下列酬載：

• 傳送訊息作業
• 代理資訊卡
• Get Extended Agent Card 作業
• JSON-RPC 通訊協定繫結
• HTTP+JSON/REST 通訊協定繫結

Model Armor 允許下列 A2A 酬載，不需經過清理：

• 來自 A2A 1.0 版以前版本的酬載
• SendStreamingMessage
• GetTask
• ListTasks
• CancelTask
• SubscribeToTask
• CRUD methods on TaskPushNotificationConfig
• 使用 A2A gRPC 通訊協定繫結 (透過網路傳輸的 protobuf) 的酬載
• A2A 錯誤酬載

MCP 酬載

Model Armor 只會清理下列 MCP 酬載：

• tools/call 要求和回應
• prompts/get 要求和回應
• MCP 工具執行錯誤 (惡意 MCP 工具作者的提示詞注入目標)

Model Armor 允許下列酬載，不需經過清理：

• tools/list
• resources/*
• notifications/*
• MCP 適用的可串流 HTTP/SSE
• MCP 通訊協定錯誤 (例如工具執行錯誤以外的所有錯誤)

外部 LLM 酬載

Model Armor 只會清理 OpenAI API 通訊協定 (輸出) 的下列酬載，包括 openai.com 上的 GPT 模型，以及透過 OpenAI API 相容 LLM 伺服器 (例如 vLLM) 提供的任何其他模型。未列於此處的酬載則不需經過清理。

• Chat completions： 建立、刪除、取得、列出及更新 (僅限非串流變體)
• 取得即時通訊訊息
• Responses：建立、取得和刪除 (僅限非串流變體)
• OpenAI API 錯誤 (包括 vLLM 的變體)
• Legacy Completions
• 舊版助理：建立、刪除、列出、修改及擷取
• 舊版訊息：建立、刪除、列出、修改及擷取
• 舊版討論串：建立、刪除、修改及擷取
• 嵌入：建立

文件篩選

這項整合功能不支援清理含有文件或上傳檔案 (例如 PDF) 的提示和回覆。如要篩選文件，請直接呼叫 Model Armor REST API。詳情請參閱 Model Armor 說明文件的「文件篩選」一節。

配額與系統限制

配額會在 Model Armor 範本所在的專案中消耗。如果閘道位於其他專案，則閘道專案也會耗用 ExternalProcessor 配額。

一元清理要求和緩衝串流要求受限於各篩選器的權杖系統限制 (提示詞注入和越獄偵測、負責任的 AI 技術和兒少性虐待內容 (CSAM) 篩選器為 65,536 個權杖，Sensitive Data Protection 為 130,000 個權杖)，以及 4 MB 的輸入大小限制。如果提示或回覆 (例如大型檢索增強生成 (RAG) 酬載或多步驟代理對話記錄) 超過篩選器的權杖限制，且未偵測到違規行為，篩選器就會略過評估，並在 SanitizeOperation 記錄項目中傳回 EXECUTION_SKIPPED 和 Detection skipped as token limit exceeded.。要求會繼續執行，不會觸發該篩選器的封鎖動作。如要篩選大型酬載，且不超過權杖限制，請使用即時串流清理。

舉例來說，如果代理是以 Agent Development Kit 建構，請使用 streamQuery，因為該模型支援不限數量的詞元。或者，您也可以將大型 RAG 酬載和代理歷史記錄分塊，確保每個一元要求都在權杖限制內。

如要進一步瞭解將 Model Armor 與其他服務整合時適用的配額，請參閱「管理配額」。如要瞭解 Model Armor 配額和系統限制 (包括輸入大小和權杖限制) 的一般資訊，請參閱 Model Armor 說明文件中的「配額和系統限制」。

後續步驟

• 設定 Agent Gateway

• 監控內容安全性