此页面由 Cloud Translation API 翻译。

SemanticCachePopulate 政策

概览

SemanticCachePopulate 政策是一种高级缓存政策，旨在优化 AI 工作负载（尤其是涉及大语言模型 [LLM] 的工作负载）的性能。

该政策使用 Vertex AI 文本嵌入 API 为文本生成嵌入，并使用 Vector Search 根据语义相似度（而非完全匹配）缓存 API 响应。

SemanticCachePopulate 政策可通过减少对 LLM 的调用量来缩短重复查询的响应时间并优化费用。

此政策与 SemanticCacheLookup 政策结合使用。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

准备工作

在使用 SemanticCachePopulate 政策之前，您必须完成以下任务：

创建 Vertex AI 项目。
创建 Vector Search 索引。
为索引创建 Vertex AI 端点。
创建 SemanticCachePopulate 政策。

如需详细了解如何完成这些任务，请参阅语义缓存政策使用入门。

角色与权限

如需获得应用和使用 SemanticCachePopulate 政策所需的权限，请让管理员为您授予用于部署 Apigee 代理的服务账号的 AI Platform User (roles/aiplatform.user) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

启用 API

Enable the Compute Engine, Vertex AI, and Cloud Storage APIs.

Enable the APIs

`<SemanticCachePopulate>` 元素

定义 SemanticCachePopulate 政策。

默认值	请参阅下面的默认政策标签页
是否必需？	必需
类型	复杂对象
父元素	不适用
子元素	`<DisplayName>` `<IgnoreUnresolvedVariables>` `<SimilaritySearch>` `<TTLInSeconds>`

<SemanticCachePopulate> 元素使用以下语法：

语法

<SemanticCachePopulate> 元素使用以下语法：

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>{EXPIRATION_TIME_IN_SECONDS}</TTLInSeconds>
</SemanticCachePopulate>

默认政策

以下示例显示了在 Apigee 界面中将 SemanticCachePopulate 政策添加到 API 代理时的默认设置：

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>60</TTLInSeconds>
</SemanticCachePopulate>

当您在 Apigee 界面中插入新的 SemanticCachePopulate 政策时，该模板将包含所有可能操作的存根。如需了解所需的元素，请参阅下文。

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

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

下表简要介绍了 <SemanticCachePopulate> 的子元素：

子元素	是否必需？	说明
`<DisplayName>`	可选	政策的名称。
`<IgnoreUnresolvedVariables>`	可选	确定在属性集无法解析时是否停止处理。
`<SimilaritySearch>`	必需	包含更新矢量索引所需信息的元素。如需了解详情，请参阅更新或插入数据点。数据点的过期时间为自输入时间起算的 <TTLInSeconds>。
`<TTLInSeconds>`	可选	缓存响应的存留时间 (TTL)，以秒为单位。默认值为 `60`。

示例

本部分提供了一个使用 <SemanticCachePopulate> 的示例。

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>60</TTLInSeconds>
</SemanticCachePopulate>

子元素参考

本部分介绍 <SemanticCachePopulate> 的子元素。

`<DisplayName>`

除了用于 name 属性之外，还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<DisplayName> 元素适用于所有政策。

默认值	不适用
是否必需？	可选。如果省略 `<DisplayName>`，则会使用政策的 `name` 属性的值
类型	字符串
父元素	<`PolicyElement`>
子元素	无

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

语法

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

示例

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

<DisplayName> 元素没有属性或子元素。

`<IgnoreUnresolvedVariables>`

确定在变量无法解析时处理是否停止。设置为 true 可忽略无法解析的变量并继续处理。

如果提供了 <DefaultValue>，则 IgnoreUnresolvedVariables 不适用。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<SemanticCachePopulate>`
子元素	无

`<SimilaritySearch>`

包含更新矢量索引所需信息的元素。

如需了解详情，请参阅更新或插入数据点。

数据点的过期时间为自输入时间起 <TTLInSeconds>。

默认值	不适用
是否必需？	必需
类型	字符串
父元素	`<SemanticCachePopulate>`
子元素	`<VertexAI>`

<SimilaritySearch> 元素使用以下语法：

<SimilaritySearch>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
  </VertexAI>
</SimilaritySearch>

<VertexAI>（`<SimilaritySearch>` 的子元素）

包含 Vertex AI 特有属性的 <网址> 元素。

默认值	不适用
是否必需？	必需
类型	字符串
父元素	`<SimilaritySearch>`
子元素	`<URL>`

VertexAI 元素使用以下语法：

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

<网址>（`<VertexAI>` 的子元素）

用于在矢量索引中更新/插入数据点的网址。

默认值	不适用
是否必需？	必需
类型	字符串
父元素	`<VertexAI>`
子元素	无

URL 元素使用以下语法：

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>

`<TTLInSeconds>`

用于指定缓存响应的存留时间 (TTL)（以秒为单位）的元素。默认值为 60。

如需了解详情，请参阅更新和重建有效索引。

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<SemanticCachePopulate>`
子元素	无

流变量

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

该政策可以在执行期间设置这些只读变量。

变量名称	说明
`response.content`	包含 API 响应的完整内容。
`semanticcache.populate.policy_name.upsert_index_request`	包含发送到 Vertex AI Vector Search API 的请求载荷，用于使用新的嵌入和元数据更新向量索引。
`semanticcache.populate.policy_name.upsert_index_response`	包含来自 Vertex AI Vector Search API 的响应，指示索引更新操作是成功还是失败。

错误参考信息

本部分介绍了 Apigee 针对 <SemanticCachePopulate> 政策返回的故障代码和错误消息以及设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

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

故障代码	HTTP 状态	原因
`steps.semanticcachepopulate.VectorSearchUpsertServiceUnavailable`	`400`	如果 Vector Search Upsert Datapoints API 不可用，就会发生此错误。
`steps.semanticcache.populate.VectorSearchUpsertAPIFailed`	`500`	如果 Vector Search Upsert Datapoints API 服务失败，就会发生此错误。
`steps.semanticcache.populate.AuthenticationFailure`	`500`	如果服务账号没有所需的权限，则会发生此错误。
`steps.semanticcache.populate.CalloutError`	`500`	Vertex AI 服务调用失败。
`steps.semanticcache.populate.InternalError`	`500`	如果 `<SemanticCachePopulate>` 政策中出现意外错误，则会发生此错误。

部署错误

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

错误名称	原因
`The SimilaritySearch URL {url} is invalid.`	如果 <SimilaritySearch> 中的 <网址> 元素为空或无效，就会发生此错误。
`The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https.`	如果 SimilaritySearch <网址> 元素的 `http` 方案无效，则会发生此错误。
`The TTLInSeconds element must be >= 0.`	如果该值设置为零或负数，则 API 代理的部署将失败。

故障变量

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

变量	其中	示例
`fault.name="FAULT_NAME"`	`FAULT_NAME` 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。	`fault.name Matches "UnresolvedVariable"`
`semanticcachepopulate.POLICY_NAME.failed`	`POLICY_NAME` 是抛出故障的政策的用户指定名称。	`semanticcachepopulate.SC-populate.failed = true`

错误响应示例

注意：处理错误时，最佳做法是捕获错误响应的 errorcode 部分。请勿依赖 faultstring 中的文本，因为它可能会发生变化。

{
"fault": {
  "faultstring": "SemanticCacheLookup[SC-populate]: unable to resolve variable [variable_name]",
  "detail": {
    "errorcode": "steps.semanticcachepopulate.UnresolvedVariable"
  }
}
}

故障规则示例

<FaultRule name="SemanticCacheLookup Faults">
  <Step>
      <Name>SCL-CustomSetVariableErrorResponse</Name>
      <Condition>(fault.name = "SetVariableFailed")</Condition>
  </Step>
  <Condition>(semanticcachelookup.failed = true)</Condition>
</FaultRule>

架构

每种政策类型均由 XML 架构 (.xsd) 定义。GitHub 提供了政策架构作为参考。

SemanticCachePopulate 政策 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

概览

准备工作

角色与权限

启用 API

<SemanticCachePopulate> 元素

语法

默认政策

示例

子元素参考

<DisplayName>

语法

示例

<IgnoreUnresolvedVariables>

<SimilaritySearch>

<VertexAI>（<SimilaritySearch> 的子元素）

<网址>（<VertexAI> 的子元素）

<TTLInSeconds>

流变量

错误参考信息

运行时错误

部署错误

故障变量

错误响应示例

故障规则示例

架构

SemanticCachePopulate 政策

`<SemanticCachePopulate>` 元素

`<DisplayName>`

`<IgnoreUnresolvedVariables>`

`<SimilaritySearch>`

<VertexAI>（`<SimilaritySearch>` 的子元素）

<网址>（`<VertexAI>` 的子元素）

`<TTLInSeconds>`