SanitizeUserPrompt 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

總覽

「SanitizeUserPrompt」政策會對傳送至生成式 AI 模型的使用者提示進行清理，保護 AI 應用程式免於遭受有害內容的侵害。這項政策會使用 Model Armor 評估使用者有害內容提示，讓使用者可透過 Apigee 為 AI 工作負載提供原生保護。Model Armor 是 Google Cloud 一項提供 AI 安全性和安全措施的服務，可降低大型語言模型 (LLM) 相關風險。

這項政策會與 SanitizeModelResponse 政策搭配使用。

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

事前準備

使用「SanitizeUserPrompt」政策前，您必須完成下列工作：

• 建立 Model Armor 範本。您必須先完成這個步驟，才能建立「SanitizeUserPrompt」政策。
• 設定 Model Armor 服務的 API 端點。
• 建立 SanitizeModelResponse 政策。您必須先完成這項工作，才能部署「SanitizeUserPrompt」政策。

必要的角色

如要取得適用 SanitizeUserPrompt 政策所需的權限，請要求管理員在您用來部署 Apigee Proxy 的服務帳戶上，授予下列 IAM 角色：

• Model Armor 使用者 (roles/modelarmor.user)
• Model Armor 檢視器 (roles/modelarmor.viewer)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

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

啟用 API

Enable the Model Armor API.

Enable the API

<SanitizeUserPrompt> 元素

定義 SanitizeUserPrompt 政策。

<SanitizeUserPrompt> 元素使用以下語法：

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</SanitizeUserPrompt>

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</SanitizeUserPrompt>

這個元素包含下列所有政策都適用的屬性：

下表概略說明 <SanitizeUserPrompt> 的子元素：

{jsonpath('$.input.prompt.text',request.content,false)}

範例

本節提供使用 <SanitizeUserPrompt> 的範例。

本範例會使用所有預設值來偵測模型和擷取提示：

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
</SanitizeUserPrompt>

子元素參照

本節將說明 <SanitizeUserPrompt> 的子元素。

<DisplayName>

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用其他更自然的名稱標記政策。

<DisplayName> 元素適用於所有政策。

<DisplayName> 元素使用以下語法：

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 元素沒有屬性或子項元素。

<IgnoreUnresolvedVariables>

判斷在變數未解析時是否停止處理。將其設為 true 可忽略未解析的變數，並繼續處理。

<ModelArmor>

包含指定 Model Armor 範本所需的資訊。

<ModelArmor> 元素使用以下語法：

<ModelArmor>
  <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
</ModelArmor>

<ModelArmor>
  <TemplateName>projects/{organization.name}/locations/{system.region.name}/templates/{id}</TemplateName>
</ModelArmor>

下表概略說明 <ModelArmor> 的子元素。

projects/{organization.name}/locations/{system.region.name}/templates/{id}

<UserPromptSource>

要擷取使用者提示文字的酬載位置。這個欄位支援 Apigee 訊息範本語法，包括使用 變數或 JSON 路徑函式。例如：

{jsonpath('$.input.prompt.text',request.content,false)}

流程變數

您可以使用流程變數，根據 HTTP 標頭或訊息內容，或是流程中可用的內容，設定政策和流程的動態執行階段行為。如要進一步瞭解流程變數，請參閱「流程變數參考資料」。

政策可以在執行期間設定這些唯讀變數。

錯誤參考資料

本節說明傳回的錯誤代碼和錯誤訊息，以及 Apigee 針對 SanitizeUserPrompt 政策設定的錯誤變數。如果您要開發錯誤規則來處理錯誤，就必須瞭解這項資訊。詳情請參閱「政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤變數

當這項政策在執行階段觸發錯誤時，系統就會設定這些變數。詳情請參閱「關於政策錯誤的相關資訊」。

錯誤回應範例

{
  "fault": {
    "faultstring": "SanitizeUserPrompt[sanitize-prompt]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.sanitizeuserprompt.UnresolvedVariable"
    }
  }
}

錯誤規則範例

<FaultRule name="SanitizeUserPrompt Faults">
    <Step>
        <Name>SUP-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(sanitizeuserprompt.failed = true)</Condition>
</FaultRule>

Model Armor 範本錯誤代碼和錯誤訊息

Model Armor 範本可覆寫 SanitizeUserPrompt 政策 API 要求所擲回的錯誤代碼和錯誤訊息。如果使用者設定覆寫值，則 Model Armor 錯誤代碼和錯誤訊息會填入流程變數。

舉例來說，回應中含有 Model Armor 錯誤代碼和訊息，可能會如下所示：

{
  "sanitizationResult": {
    "filterMatchState": "MATCH_FOUND",
    "filterResults": {...},
    "sanitizationMetadata": {
      "errorCode": "890",
      "errorMessage": "get out"
      },
    "invocationResult": "SUCCESS"
  }
}

結構定義

每個政策類型都由 XML 架構 (.xsd) 定義。如需參考，請前往 GitHub 查看政策架構。