Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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

如果尚未啟用 Model Armor API，請先啟用。

啟用 API 所需的角色

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

啟用 API

`<SanitizeUserPrompt>` 元素

定義 SanitizeUserPrompt 政策。

預設值	請參閱下方的「預設政策」分頁
必填與否	必填
類型	複雜物件
父項元素	不適用
子元素	`<DisplayName>` `<IgnoreUnresolvedVariables>` `<TemplateName>` `<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>
  <FunctionResponseSource>{jsonPath('$.contents[-1].parts[-1].functionResponse.response',request.content,true)}</FunctionResponseSource>
</SanitizeUserPrompt>

預設政策

以下範例顯示在 Apigee UI 中，將 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>
  <FunctionResponseSource>{jsonPath('$.contents[-1].parts[-1].functionResponse.response',request.content,true)}</FunctionResponseSource>
</SanitizeUserPrompt>

使用 Apigee UI 插入新的 SanitizeUserPrompt 政策時，範本會包含所有可能作業的存根。如要瞭解必要元素，請參閱下文。

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

屬性	預設	是否必要？	說明
`name`	不適用	必要	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
`continueOnError`	false	選用	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
`enabled`	是	選用	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
`async`	false	已淘汰	此屬性已淘汰。

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

子元素	是否必要	說明
`<DisplayName>`	選用	政策名稱。
`<IgnoreUnresolvedVariables>`	選用	指定如果用於範本名稱或 Model Armor 酬載的變數未解析，是否停止處理。
`<ModelArmor>`	必填	包含指定 Model Armor 範本所需的資訊。
`<UserPromptSource>`	選用	要擷取的使用者提示詞文字酬載位置。僅支援字串文字值。這個欄位支援 Apigee 訊息範本語法，包括使用變數或 JSON Path 函式。例如： {jsonpath('$.input.prompt.text',request.content,false)}
`<FunctionResponseSource>`	選用	要擷取函式/工具回應資料的位置。當函式呼叫回合的 `<UserPromptSource>` 傳回空白時，會做為備用選項。預設：`{jsonPath('$.contents[-1].parts[-1].functionResponse.response',request.content,true)}`

範例

本節提供使用 <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>`，系統會使用政策的 `name` 屬性值。
類型	字串
上層元素	<`PolicyElement`>
子元素	無

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

語法

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

範例

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

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

<IgnoreUnresolvedVariables>

判斷變數無法解析時，是否要停止處理程序。設為 true 即可忽略未解析的變數，並繼續處理。

預設值	否
必填與否	選用
類型	布林值
父項元素	`<SanitizeUserPrompt>`
子元素	無

`<ModelArmor>`

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

預設值	不適用
必填與否	必填
類型	字串
父項元素
子元素	`<TemplateName>`

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

語法

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

範例

這個範例會使用 Apigee 流程變數填入必要資訊。

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

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

子元素是否必要說明

子元素	是否必要	說明
`<TemplateName>`	必填	字串用來清理使用者提示詞的 Model Armor 範本。您可以使用下列 Apigee 流程變數，將這個值設為範本： projects/{organization.name}/locations/{system.region.name}/templates/{id}

<TemplateName>

必填

字串

用來清理使用者提示詞的 Model Armor 範本。

您可以使用下列 Apigee 流程變數，將這個值設為範本：

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

`<UserPromptSource>`

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

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

預設值	{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}
必填與否	選用
類型	字串
父項元素	`<SanitizeUserPrompt>`
子元素	無

<FunctionResponseSource>

要從要求中擷取的函式或工具回應資料位置。如果 <UserPromptSource> 傳回空白，系統會使用這個元素做為備用。當最後一個內容項目包含函式回應而非文字時，函式呼叫回合就會發生這種情況。函式回應資料必須經過清理，因為其中包含來自 API 和資料庫的不信任外部資料。

這個欄位支援訊息範本語法，包括 JSON Path 函式。

預設值	{jsonPath('$.contents[-1].parts[-1].functionResponse.response',request.content,true)}
必填與否	選用
類型	字串
父項元素	`<SanitizeUserPrompt>`
子元素	無

流程變數

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

這項政策會在執行期間提供下列一組唯讀流程變數。您可以搭配使用這些流程變數和 DataCapture 政策，建立自訂數據分析報表。詳情請參閱「透過『資料收集』政策收集顧客數位資料」。

變數名稱	說明
`SanitizeUserPrompt.POLICY_NAME.templateUsed`	指定使用的模型裝甲範本。例如： `projects/myproject/locations/us-west1/templates/mytemplate`
`SanitizeUserPrompt.POLICY_NAME.userPrompt`	指定呼叫 Model Armor 清理內容時使用的提示內容。
`SanitizeUserPrompt.POLICY_NAME.modelResponse`	指定呼叫 Model Armor 時使用的 LLM 回覆內容，以便清理內容。
`SanitizeUserPrompt.POLICY_NAME.responseFromModelArmor`	指定 Model Armor 的 JSON 回應。
`SanitizeUserPrompt.POLICY_NAME.filterMatchState`	指出篩選條件是否相符。有效值包括 `MATCH_FOUND` 和 `NO_MATCH_FOUND`。
`SanitizeUserPrompt.POLICY_NAME.invocationResult`	這個欄位會指出叫用結果，無論比對狀態為何。可能具有下列值：成功：所有篩選器均已成功執行。部分：部分篩選器已略過或無法執行。失敗：所有篩選器都略過或無法執行。
`SanitizeUserPrompt.POLICY_NAME.raiFilterResult.executionState`	RAI 篩選器執行結果。有效值包括 `EXECUTION_SUCCESS` 和 `EXECUTION_SKIPPED`。
`SanitizeUserPrompt.POLICY_NAME.raiFilterResult.matchState`	RAI 篩選器比對狀態。有效值包括 `MATCH_FOUND` 和 `NO_MATCH_FOUND`。
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.executionState`	Sdp filter inspect result execution state. 有效值包括 `EXECUTION_SUCCESS` 和 `EXECUTION_SKIPPED`。
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.matchState`	Sensitive Data Protection 篩選器檢查結果比對狀態。有效值包括 `MATCH_FOUND` 和 `NO_MATCH_FOUND`。
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState`	SDP 篩選器去識別化結果執行狀態。有效值包括 `EXECUTION_SUCCESS` 和 `EXECUTION_SKIPPED`。
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState`	SDP 篩選器去識別化結果比對狀態。有效值包括 `MATCH_FOUND` 和 `NO_MATCH_FOUND`。
`SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.executionState`	提示詞注入和越獄篩選器結果執行狀態。有效值包括 `EXECUTION_SUCCESS` 和 `EXECUTION_SKIPPED`。
`SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.matchState`	提示詞注入和越獄篩選器結果比對狀態。有效值包括 `MATCH_FOUND` 和 `NO_MATCH_FOUND`。
`SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.executionState`	兒少性虐待內容篩選器執行狀態。有效值包括 `EXECUTION_SUCCESS` 和 `EXECUTION_SKIPPED`。
`SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.matchState`	兒少性虐待內容篩選器比對狀態。有效值包括 `MATCH_FOUND` 和 `NO_MATCH_FOUND`。
`SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.executionState`	惡意 URI 篩選器執行狀態。有效值包括 `EXECUTION_SUCCESS` 和 `EXECUTION_SKIPPED`。
`SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.matchState`	惡意 URI 篩選器比對狀態。有效值包括 `MATCH_FOUND` 和 `NO_MATCH_FOUND`。
`SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorCode`	Model Armor 回應中自訂覆寫的錯誤代碼 (如有)。
`SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorMessage`	Model Armor 回應中自訂覆寫的錯誤代碼 (如有)。
`SanitizeUserPrompt.POLICY_NAME.csamFilterMatched`	布林值，指出是否符合兒少性虐待內容篩選器。
`SanitizeUserPrompt.POLICY_NAME.maliciousURIs`	惡意 URI 篩選器偵測到的惡意 URI 清單。
`SanitizeUserPrompt.POLICY_NAME.maliciousURIsDetected`	布林值，指出惡意 URI 篩選器是否相符。
`SanitizeUserPrompt.POLICY_NAME.matchesFound`	布林值，表示是否有任何篩選條件相符。
`SanitizeUserPrompt.POLICY_NAME.promptInjectionDetected`	布林值，指出提示詞注入篩選器是否相符。
`SanitizeUserPrompt.POLICY_NAME.promptInjectionConfidence`	提示詞注入偵測的信賴水準。
`SanitizeUserPrompt.POLICY_NAME.raiMatchesFound`	指出 RAI 篩選器是否相符的布林值。
`SanitizeUserPrompt.POLICY_NAME.requestSentToModelArmor`	布林值，指出是否已將要求傳送至 Model Armor。
`SanitizeUserPrompt.POLICY_NAME.sanitizeOperation`	指定政策執行的作業。有效值包括 `SANITIZE_USER_PROMPT` 和 `SANITIZE_MODEL_RESPONSE`。

錯誤參考資料

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

執行階段錯誤

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

錯誤代碼	HTTP 狀態	原因
`steps.sanitize.user.prompt.response.FilterMatched`	`400`	如果使用者提示詞未通過 Model Armor 範本檢查，就會發生這項錯誤。
`steps.sanitize.user.prompt.SanitizationResponseParsingFailed`	`500`	如果無法剖析 Model Armor 回應，就會發生這項錯誤。
`steps.sanitize.user.prompt.FailedToExtractUserPrompt`	`500`	如果系統無法自動擷取預設值的使用者提示，就會發生這項錯誤。
`steps.sanitize.user.prompt.InternalError`	`500`	如果發生內部伺服器錯誤，就會出現這個錯誤。
`steps.sanitize.modelarmor.ModelArmorTemplateNameExtractionFailed`	`500`	如果無法解析範本名稱，就會發生這個錯誤。
`steps.sanitize.modelarmor.AuthenticationFailure`	`500`	如果服務帳戶沒有呼叫 Model Armor API 的權限，就會發生這個錯誤。
`steps.sanitize.modelarmor.ModelArmorAPIFailed`	`500`	如果 Model Armor API 擲回錯誤，就會發生這個錯誤。
`steps.sanitize.modelarmor.ModelArmorCalloutError`	`500`	如果 Model Armor API 呼叫失敗，就會發生這項錯誤。
`steps.sanitize.modelarmor.ServiceUnavailable`	`500`	如果 Model Armor 服務無法使用，就會發生這項錯誤。

部署錯誤

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

錯誤名稱	原因
`The ModelArmor/TemplateName element is required.`	如果 <ModelArmor> 中沒有 <TemplateName> 元素，就會發生這種情況。
`The TemplateName element value is required.`	如果 <TemplateName> 值空白，就會發生這個錯誤。

故障變數

這項政策會在執行階段觸發錯誤時設定這些變數。詳情請參閱「政策錯誤須知」。

變數	地點	範例
`fault.name="FAULT_NAME"`	`FAULT_NAME` 是錯誤名稱，如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤代碼的最後一部分。	`fault.name Matches "UnresolvedVariable"`
`SanitizeUserPrompt.POLICY_NAME.failed`	`POLICY_NAME` 是使用者指定的政策名稱，該政策會擲回錯誤。	`SanitizeUserPrompt.sanitize-prompt.failed = true`

錯誤回應範例

注意：如要進行錯誤處理，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為這些文字可能會變更。

{
  "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 查看政策架構。

SanitizeUserPrompt 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

啟用 API

<SanitizeUserPrompt> 元素

語法

預設政策

範例

子元素參考資料

<DisplayName>

語法

範例

<IgnoreUnresolvedVariables>

<ModelArmor>

語法

範例

<UserPromptSource>

<FunctionResponseSource>

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

故障變數

錯誤回應範例

錯誤規則範例

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

結構定義

SanitizeUserPrompt 政策

`<SanitizeUserPrompt>` 元素

`<DisplayName>`

`<ModelArmor>`

`<UserPromptSource>`