语义缓存政策使用入门

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

本页面介绍了如何配置和使用 Apigee 语义缓存政策，以便根据语义相似性实现智能响应重复利用。在 Apigee API 代理中使用这些政策可以最大限度地减少冗余的后端 API 调用，缩短延迟时间并降低运营成本。

准备工作

在开始之前，请务必完成以下任务：

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

Enable the APIs

在您的 Google Cloud 项目中设置和配置 Vertex AI Text embeddings API 和向量搜索。
确认您的 Apigee 实例中有一个全面环境。语义缓存政策只能部署在全面环境中。

所需的角色

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

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

设置环境变量

在包含 Apigee 实例的 Google Cloud 项目中，使用以下命令设置环境变量：

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

其中：

PROJECT_ID 是包含 Apigee 实例的项目的 ID。
REGION 是您的 Apigee 实例的 Google Cloud 区域。
RUNTIME_HOSTNAME 是 Apigee 运行时的主机名。

如需确认环境变量设置正确，请运行以下命令并查看输出：

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

设置项目

在开发环境中设置 Google Cloud 项目：

    gcloud auth login
    gcloud config set project $PROJECT_ID

概览

语义缓存政策旨在帮助使用 LLM 模型的 Apigee 用户高效地智能地提供相同或语义相似的提示，最大限度地减少后端 API 调用并降低资源消耗。

SemanticCacheLookup 和 SemanticCachePopulate 政策分别附加到 Apigee API 代理的请求流和响应流。当代理收到请求时，SemanticCacheLookup 政策会从请求中提取用户提示，并使用 Text embeddings API 将提示转换为数字表示法。使用 Vector Search 执行语义相似性搜索以查找相似的提示。如果找到类似的提示数据点，系统会执行缓存查找。如果找到缓存的数据，系统会将缓存的响应返回给客户端。

如果相似搜索未返回类似的之前提示，则 LLM 模型会根据用户提示生成内容，并使用该响应填充 Apigee 缓存。系统会创建一个反馈环，以更新 Vector Search 索引条目，为日后处理请求做好准备。

以下部分介绍了创建和配置语义缓存政策所需的步骤：

为 Vector Search 索引配置服务账号。
创建和部署 Vector Search 索引。
创建 API 代理以启用语义缓存。
配置语义缓存政策。
测试语义缓存政策。

为向量搜索索引配置服务账号

如需为向量搜索索引配置服务账号，请完成以下步骤：

使用以下命令创建服务账号：

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="SERVICE_ACCOUNT_DISPLAY_NAME"

其中：

SERVICE_ACCOUNT_NAME 是服务账号的名称。
DESCRIPTION 是服务账号的说明。
SERVICE_ACCOUNT_DISPLAY_NAME 是服务账号的显示名称。

例如：

gcloud iam service-accounts create ai-client \
  --description="semantic cache client" \
  --display-name="ai-client"

使用以下命令向服务账号授予 AI Platform User 角色：

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

其中 SERVICE_ACCOUNT_NAME 是您在上一步中创建的服务账号的名称。

使用以下命令向服务账号分配 IAM Service Account User 角色：

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"

其中 SERVICE_ACCOUNT_NAME 是您在上一步中创建的服务账号的名称。

创建和部署 Vector Search 索引

如需创建和部署 Vector Search 索引，请执行以下操作：

创建允许流式更新的 Vector Search 索引：

ACCESS_TOKEN=$(gcloud auth print-access-token) && curl --location --request POST \
  "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    --header 'Content-Type: application/json' \
    --data-raw \
    '{
      "displayName": "semantic-cache-index",
      "description": "semantic-cache-index",
      "metadata": {
        "config": {
          "dimensions": "768",
          "approximateNeighborsCount": 150,
          "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
          "featureNormType": "NONE",
          "algorithmConfig": {
            "treeAhConfig": {
              "leafNodeEmbeddingCount": "10000",
              "fractionLeafNodesToSearch": 0.05
              }
            },
          "shardSize": "SHARD_SIZE_MEDIUM"
          },
        },
      "indexUpdateMethod": "STREAM_UPDATE"
    }'

$REGION 用于定义部署 Vector Search 索引的区域。我们建议您使用与 Apigee 实例相同的区域。此环境变量已在前一个步骤中设置。

此操作完成后，您应该会看到类似于以下内容的响应：

{
  "name": "projects/976063410430/locations/us-west1/indexes/5695338290484346880/operations/9084564741162008576",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexOperationMetadata",
    "genericMetadata": {
      "createTime": "2025-04-25T18:45:27.996136Z",
      "updateTime": "2025-04-25T18:45:27.996136Z"
    }
  }
}

如需详细了解如何创建 Vector Search 索引，请参阅创建索引。

使用以下命令创建 IndexEndpoint：

gcloud ai index-endpoints create \
  --display-name=semantic-cache-index-endpoint \
  --public-endpoint-enabled \
  --region=$REGION \
  --project=$PROJECT_ID

此步骤可能需要几分钟才能完成。完成后，您应该会看到类似于下面这样的响应：

Waiting for operation [8278420407862689792]...done.
  Created Vertex AI index endpoint: projects/976063410430/locations/us-west1/indexEndpoints/7953875911424606208.

如需详细了解如何创建 IndexEndpoint，请参阅创建 IndexEndpoint。

使用以下命令将索引部署到端点：

INDEX_ENDPOINT_ID=$(gcloud ai index-endpoints list \
  --project=$PROJECT_ID \
  --region=$REGION \
  --format="json" | jq -c -r \
  '.[] | select(.displayName=="semantic-cache-index-endpoint") | .name | split("/") | .[5]' \
  ) && INDEX_ID=$(gcloud ai indexes list \
  --project=$PROJECT_ID \
  --region=$REGION \
  --format="json" | jq -c -r \
  '.[] | select(.displayName=="semantic-cache-index") | .name | split("/") | .[5]' \
  ) && gcloud ai index-endpoints deploy-index \
  $INDEX_ENDPOINT_ID \
  --deployed-index-id=semantic_cache \
  --display-name=semantic-cache \
  --index=$INDEX_ID \
  --region=$REGION \
  --project=$PROJECT_ID

注意：将索引部署到端点的命令需要 jq。如果您的开发环境中尚未安装此 JSON 处理实用程序，您可以使用以下命令进行安装： $ sudo apt install jq。

初次将索引部署到端点可能需要 20 到 30 分钟才能完成。如需检查操作状态，请使用以下命令：

gcloud ai operations describe OPERATION_ID \
  --project=$PROJECT_ID \
  --region=$REGION

确认已部署索引：

gcloud ai operations describe OPERATION_ID \
  --index-endpoint=$INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID

该命令应返回 $ done: true。

创建 API 代理以启用语义缓存

在此步骤中，您将使用带语义缓存的代理模板创建新的 API 代理（如果您尚未创建）。

在创建 API 代理之前，请设置以下环境变量：

export PUBLIC_DOMAIN_NAME=$(gcloud ai index-endpoints describe $INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID | grep "publicEndpointDomainName" | awk '{print $2}')

如需创建用于语义缓存的代理，请执行以下操作：

在 Google Cloud 控制台中，前往 API 代理页面。
前往 API 代理
点击 + 创建，打开创建 API 代理窗格。
在代理模板框中，选择带有语义缓存的代理。
输入以下详细信息：
- 代理名称：输入代理的名称。
- 说明：（可选）输入代理的说明。
- 目标（现有 API）：输入代理调用的后端服务的网址。这是用于生成内容的 LLM 模型端点。
  在本教程中，目标（现有 API）可设置为：
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent
```
输入以下语义缓存网址：
注意：这些网址也可以添加到代理编辑器的开发标签页中的 XML 配置中。
- Generate Embeddings 网址：此 Vertex AI 服务会将文本输入转换为数值形式，以进行语义分析。
  在本教程中，此网址可设置为以下内容：
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/text-embedding-004:predict
```
- Query Nearest Neighbor 网址：此 Vertex AI 服务会在 Vector Search 索引中搜索之前请求中的类似文本输入，以避免重新处理。
  在本教程中，此网址可设置为以下内容：
```
PUBLIC_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/REGION/indexEndpoints/INDEX_ENDPOINT_ID:findNeighbors
```
  PUBLIC_DOMAIN_NAME 和 INDEX_ENDPOINT_ID 值在之前的步骤中已设置。如需获取这些值，您可以使用以下命令：
```
  echo $PUBLIC_DOMAIN_NAME
  echo $INDEX_ENDPOINT_ID
```
- Upsert 索引网址：此 Vertex AI 服务会使用新条目或修改后的条目更新索引。
  在本教程中，此网址可设置为以下内容：
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints
```
点击下一步。
点击创建。

您可以在开发标签页中查看 API 代理的 XML 配置。包含默认值的 SemanticCacheLookup 和 SemanticCachePopulate 政策已附加到代理请求和响应流。

配置语义缓存政策

您可以点击 API 代理的开发标签页的详细信息视图中的政策名称，查看每项政策的 XML 配置。您可以直接在开发标签页的代码视图中修改政策 XML。

修改政策：

SemanticCacheLookup 政策：
- 移除 <UserPromptSource> 元素以使用默认值。
- 更新 <DeployedIndexId> 元素以使用值 semantic_cache。
- 配置语义相似性 <Threshold> 值，以确定两条提示何时被视为匹配。默认值为 0.9，但您可以根据应用的敏感度调整此值。该数字越大，提示与缓存命中的相关性就越高。在本教程中，我们建议将此值设置为 0.95。
- 点击保存。
SemanticCachePopulate 政策：
- 设置 <TTLInSeconds> 元素以指定缓存到期前的秒数（以秒为单位）。默认值为 60 秒。请注意，Apigee 会忽略从 LLM 模型接收的所有缓存控制标头。
- 点击保存。

向 API 代理添加 Google 身份验证

您还必须向 API 代理的目标端点添加 Google 身份验证，以启用对目标的代理调用。

如需添加 Google 访问令牌，请执行以下操作：

在开发标签页中，点击目标端点文件夹下的默认。代码视图显示 <TargetEndpoint> 元素的 XML 配置。

修改 XML 以在 <HTTPTargetConnection> 下添加以下配置：

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

点击保存。

部署 API 代理

如需部署 API 代理，请执行以下操作：

点击部署以打开部署 API 代理窗格。
修订版本字段应设置为 1。否则，请点击 1 以将其选中。
在环境列表中，选择要部署代理的环境。环境必须是全面环境。
输入您在前面步骤中创建的服务账号。
点击部署。

测试语义缓存政策

如需测试语义缓存政策，请执行以下操作：

使用以下命令向代理发送请求：

curl https://$RUNTIME_HOSTNAME/PROXY_NAME -H 'Content-Type: application/json' --data '{
  "contents": [
      {
          "role": "user",
          "parts": [
              {
                  "text": "Why is the sky blue?"
              }
          ]
      }
  ]
}'

其中，PROXY_NAME 是您在上一步中部署的 API 代理的基路径。

Why is the sky blue?
What makes the sky blue?
Why is the sky blue colored?
Can you explain why the sky is blue?
The sky is blue, why is that?

Compare the response time for each call once a similar prompt has been cached.

如需验证您的调用是否从缓存中提供，请检查响应标头。应附加 Cached-Content: true 标头。

最佳做法

我们建议您在使用语义缓存政策时，将以下最佳实践纳入您的 API 管理计划：

使用 Model Armor 防止缓存敏感数据。
为防止缓存敏感数据，我们建议您使用 Model Armor 进行内容过滤。如果检测到敏感信息，Model Armor 可以将响应标记为不可缓存。如需了解详情，请参阅 Model Armor 概览。
使用 Vertex AI 数据点失效和存留时间 (TTL) 管理数据的新鲜度。
我们建议您实施适当的数据点无效化策略，以确保缓存的响应是最新的，并反映后端系统中的最新信息。如需了解详情，请参阅更新和重建活跃索引。

您还可以根据数据的波动性和更新频率调整缓存响应的 TTL。如需详细了解如何在 SemanticCachePopulate 政策中使用 TTL，请参阅 <TTLInSeconds>。
使用预定义的缓存策略，确保获得最准确的响应数据。
我们建议您实现类似于以下内容的预定义缓存策略：
- 通用 AI 响应：为非针对特定用户的响应配置较长的 TTL（例如，一小时）。
- 特定于用户的响应：对于包含特定于用户的信息的响应，请勿实现缓存，或为其设置较短的 TTL（例如 5 分钟）。
- 时间敏感响应：对于需要实时或频繁更新的响应，请配置较短的 TTL（例如 5 分钟）。

限制

语义缓存政策存在以下限制：

可缓存的文本大小上限为 256 KB。如需了解详情，请参阅 Apigee 限制页面上的缓存值大小。
Apigee 会忽略从 LLM 模型接收的任何缓存控制标头。
如果缓存未正确失效，或者语义相似性算法不够准确，无法区分含义非常相似的输入，响应可能会返回过时或错误的信息。
并非所有区域都支持向量搜索功能。如需查看受支持区域的列表，请参阅“Vertex AI 位置”页面中的功能可用性部分。如果您的 Apigee 组织位于不受支持的区域，则必须在与 Apigee 组织不同的区域创建索引端点。
语义缓存政策不支持与使用 Eventflow 对服务器发送事件 (SSE) 进行连续响应流式传输的 API 代理搭配使用。
<UserPromptSource> 中的 JsonPath 函数不支持 ignoreUnresolvedVariables 功能。默认情况下，在应用消息模板期间，系统会忽略 null 值或空值。

后续步骤

了解如何开始使用 Model Armor 政策。