SemanticCacheLookup 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

概览

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

该政策使用 Vertex AI 文本嵌入 API 为文本生成嵌入，并使用向量搜索根据语义相似性（而非完全匹配）查找类似的提示。

SemanticCacheLookup 政策可减少对 LLM 的调用量，从而缩短重复查询的响应时间并优化费用。

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

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

准备工作

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

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

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

所需的角色

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

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

启用 API

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

Enable the APIs

<SemanticCacheLookup> 元素

定义 SemanticCacheLookup 政策。

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

<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

<SemanticCacheLookup async="false" continueOnError="false"enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict
      </URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <Threshold>0.9</Threshold>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

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

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

{jsonPath($.contents[-1].parts[-1].text,request.content,true)}

子元素参考

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

<DisplayName>

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

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

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

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

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

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

<IgnoreUnresolvedVariables>

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

提供 <DefaultValue> 时，IgnoreUnresolvedVariables 不适用。

<UserPromptSource>

要提取的用户提示文本的载荷位置。仅支持字符串文本值。

此字段支持 Apigee 消息模板语法，包括使用变量或 JSON Path 函数。

例如：

{jsonPath($.contents[-1].parts[-1].text,request.content,true)}

<Embeddings>

此元素包含生成文本嵌入所需的信息。

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

<Embeddings>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
  </VertexAI>
</Embeddings>

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

包含适用于 Vertex AI 专用属性的 <网址> 元素。

VertexAI 元素使用以下语法：

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
</VertexAI>

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

用于生成文本嵌入的网址。如需查看可为 SemanticCacheLookup 政策提供文本嵌入的模型列表，请参阅 支持的模型。

URL 元素使用以下语法：

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>

<SimilaritySearch>

此元素包含执行相似度搜索所需的信息。

如需了解详情，请参阅查询公共索引以获取最近邻。

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

<SimilaritySearch>
  <VertexAI>
    <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors
    </URL>
    <Threshold>0.9</Threshold>
    <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
  </VertexAI>
</SimilaritySearch>

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

包含适用于 Vertex AI 专用属性的 <网址> 元素。

VertexAI 元素使用以下语法：

<VertexAI>
  <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
  <Threshold>0.9</Threshold>
  <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>

下表提供了 <VertexAI> 的子元素的简要说明。

流变量

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

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

错误参考信息

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

运行时错误

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

部署错误

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

故障变量

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

错误响应示例

{
  "fault": {
    "faultstring": "SemanticCacheLookup[SC-lookup]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.semanticcachelookup.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 提供了政策架构作为参考。