疑難排解

本頁說明如何解決 Model Armor 的問題。

本節提供實用的疑難排解步驟,協助您解決使用 Model Armor 時遇到的問題。

所有對 Model Armor 的 API 呼叫都會傳回 404 找不到網頁錯誤

建立連至 Model Armor API 的 Private Service Connect。發生這項錯誤,通常是因為使用 Private Google Access,或在沒有 Private Service Connect 的情況下,存取 Model Armor 區域端點 (REP)。詳情請參閱「關於透過 Private Service Connect 端點存取區域端點」。

Sensitive Data Protection 篩選器發生錯誤或遭到略過

請確認下列事項:

  • Sensitive Data Protection 範本與所呼叫的 Model Armor 端點位於相同區域。
  • 提出 Model Armor 要求的服務代理,在含有 Sensitive Data Protection 範本的專案中,具備 dlp.User 和 dlp.Reader 角色。

這項錯誤是由 SanitizeUserPrompt 或 SanitizeModelResponse 要求中的用戶端錯誤,或 Sensitive Data Protection 範本問題所造成。

Model Armor 全球端點錯誤

請務必向適當的區域端點 (而非全域端點) 提出 API 要求。

Model Armor 僅支援在區域端點執行下列作業:

  • 建立、讀取、更新、刪除及列出範本。
  • SanitizeUserPrompt 和 SanitizeModelResponse API 要求。

如果您向全域端點發出這些作業的 API 要求,會看到下列錯誤:

{
  "error": {
    "code": 403,
    "message": "Write access to project '<PROJECT_ID>' was denied",
    "status": "PERMISSION_DENIED"
  }
}

存取 Model Armor 區域端點時發生憑證錯誤

這項錯誤通常發生在下列情況:使用 Private Google Access 或 VPC Service Controls,從虛擬私有雲網路存取 Model Armor 區域端點,但憑證驗證失敗。

例如,您可能會看到類似下列的錯誤訊息:

curl: (60) SSL: no alternative certificate subject name matches target host name 'modelarmor.europe-west4.rep.googleapis.com'

如要解決這個問題,請建立連至 Model Armor API 的 Private Service Connect 端點。詳情請參閱「關於透過 Private Service Connect 端點存取區域端點」。

區域不支援要求的功能

您可能會看到類似下列內容的錯誤訊息:

Region '<var>REGION</var>' does not support the requested capabilities: '<var>CAPABILITIES</var>'

如果您嘗試在有功能限制的區域建立或更新範本,且要求啟用了該區域不支援的功能,就會發生這項錯誤。

範本設定包含惡意網址和兒少性虐待內容 (CSAM) 等偵測工具,但部分區域不支援這些功能。

如何解決這個問題:

  1. 找出錯誤訊息中列出的不支援功能。
  2. 請查看各區域的功能可用性,確認指定區域不支援哪些功能。
  3. 從您建立或更新的範本中移除不支援的功能,或明確將其強制執行設為 DISABLED (例如 "csamFilterSettings": { "filterEnforcement": "DISABLED" })。

或者,如果資料落地規定允許,請使用支援這些功能的其他 Model Armor 區域。

必須遵守範本資料落地規定

您可能會看到類似下列的 400 (FAILED_PRECONDITION) 錯誤訊息:

Template data residency compliance is required. The 'Enforce data residency' field must not be set to false.

如果強制執行 Require Model Armor Template Data Residency Compliance (constraints/modelarmor.managed.requireTemplateDataResidencyCompliance) 代管組織政策服務限制,且您在建立或更新 Model Armor 範本時停用資料落地法規遵循,就會發生這項錯誤。如果將 data_residency_compliant 設為 false,或清除「Enforce data residency」(強制執行資料落地) 選項,系統就會停用資料落地法規遵循功能。這項限制預設為強制執行,因此如果現有範本的 data_residency_compliant 已設為 false,編輯任何設定 (例如篩選器) 也會觸發這項錯誤。除非您更新範本,否則現有範本和清理提示詞與回覆的要求不會受到影響。

如要解決這個問題,請按照下列其中一種做法進行:

  • 將 data_residency_compliant 設為 true,或選取「Enforce data residency」(強制執行資料落地) 選項,在範本上啟用資料落地法規遵循功能。
  • 如需為範本停用資料落地法規遵循功能,請按照「停用資料落地的組織政策限制」一節的步驟操作,讓組織政策管理員停用限制。

略過大型提示或酬載的政策控管或篩選器

篩選大型提示或回覆 (例如檢索增強生成 (RAG) 酬載或多步驟代理對話記錄) 時,個別篩選器可能不會執行,或者清理結果可能會傳回 EXECUTION_SKIPPED,並在 messageItems 欄位中顯示下列其中一則警告訊息:

Detection skipped as token limit exceeded.
Input size exceeded the limit of 4194304 bytes.

如果一元清理要求或緩衝串流要求超過篩選器的權杖系統限制或 4 MB 的輸入大小限制,就會發生這個問題。提示詞注入和越獄偵測、負責任的 AI 技術和兒少性虐待內容篩選器,一元要求的限制為 65,536 個詞元,緩衝串流要求則為 10,000 個詞元;Sensitive Data Protection 的限制為 130,000 個詞元。如果輸入內容超過篩選器的詞元限制,且未偵測到相符項目,篩選器會傳回 EXECUTION_SKIPPED 和 NO_MATCH_FOUND,允許要求在內嵌整合中繼續執行。

如要確認篩選器是否因權杖或輸入大小限制而略過,請在 Cloud Logging 中查詢 SanitizeOperation 記錄:

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

如何解決這個問題:

  1. 如果是串流工作負載或長時間執行的代理互動,請使用即時串流清理 (StreamSanitizeUserPrompt 和 StreamSanitizeModelResponse)。如果是使用 Agent Gateway 的 Agent Development Kit 代理,請使用 streamQuery,這類代理會分塊處理輸入內容,並支援無限數量的權杖。
  2. 對於一元要求,請先將大型 RAG 酬載分塊,或修剪多步驟代理對話記錄,再傳送至 Model Armor,確保每項要求都符合權杖系統限制和 4 MB 的輸入大小限制。