此页面由 Cloud Translation API 翻译。

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 代理的服务账号的以下 IAM 角色：

Model Armor User (roles/modelarmor.user)
Model Armor Viewer (roles/modelarmor.viewer)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

启用 API

Enable the Model Armor API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the 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>
</SanitizeUserPrompt>

默认政策

以下示例展示了在 Apigee 界面中将 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>

当您使用 Apigee 界面插入新的 SanitizeUserPrompt 政策时，模板包含所有可能操作的桩。如需了解所需的元素，请参阅下文。

此元素具有所有政策中常见的以下属性：

属性	默认	是否必需？	说明
`name`	无	必需	政策的内部名称。`name` 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。（可选）使用 `<DisplayName>` 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
`continueOnError`	false	可选	设置为 `false` 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 `true`，即使在政策失败后，仍可以继续执行流。另请参阅：故障规则仅在错误状态下触发（关于 continueOnError）处理当前流中的故障
`enabled`	true	可选	设置为 `true` 可实施政策。设为 `false` 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。
`async`	false	已弃用	此属性已弃用。

下表提供了 <SanitizeUserPrompt> 的子元素的简要说明：

子元素	是否必需？	说明
`<DisplayName>`	可选	政策的名称。
`<IgnoreUnresolvedVariables>`	可选	指定在用于模板名称或 Model Armor 载荷的变量未解析时是否停止处理。
`<ModelArmor>`	需要	包含指定 Model Armor 模板所需的信息。
`<UserPromptSource>`	可选	要提取的用户提示文本的载荷位置。仅支持字符串文本值。此字段支持 Apigee 消息模板语法，包括使用变量或 JSON Path 函数。例如： {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 属性之外，还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<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 路径函数。例如：

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

默认值	{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}
是否必需？	可选
类型	字符串
父元素	`<SanitizeUserPrompt>`
子元素	无

流变量

流变量可基于 HTTP 标头或消息内容或者流中提供的上下文，为政策和流配置动态运行时行为。如需详细了解流变量，请参阅流变量参考。

此政策在执行期间提供以下只读流变量集。您可以将这些流变量与 DataCapture 政策搭配使用，以创建自定义分析报告。如需了解详情，请参阅使用 Data Capture 政策收集客户数据。

变量名称	说明
`SanitizeUserPrompt.POLICY_NAME.templateUsed`	指定要使用的 Model Armor 模板。例如：`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`	一个字段，用于指示调用的结果，无论匹配状态如何。它可以具有以下值： SUCCESS：所有过滤条件都已成功执行。 PARTIAL：部分过滤条件已跳过或执行失败。 FAILURE：所有过滤条件都已跳过或执行失败。
`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 过滤条件检查结果执行状态。有效值包括 `EXECUTION_SUCCESS` 和 `EXECUTION_SKIPPED`。
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.matchState`	SDP 过滤条件检查结果匹配状态。有效值包括 `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`	CSAM 过滤条件执行状态。有效值包括 `EXECUTION_SUCCESS` 和 `EXECUTION_SKIPPED`。
`SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.matchState`	CSAM 过滤条件匹配状态。有效值包括 `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/code>`	布尔值，指示 CSAM 过滤条件是否匹配。
`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 针对 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 服务不可用，就会发生此错误。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称	原因
`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>

流变量

错误参考信息

运行时错误

部署错误

故障变量

错误响应示例

故障规则示例

Model Armor 模板错误代码和错误消息

架构

`<SanitizeUserPrompt>` 元素

`<DisplayName>`

`<ModelArmor>`

`<UserPromptSource>`