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.

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 属性之外，还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<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 政策返回的故障代码和错误消息以及设置的故障变量。 在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

部署错误

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

故障变量

当此政策在运行时触发错误时，将设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

错误响应示例

{
  "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 提供了政策架构作为参考。