语义缓存政策使用入门

本页面适用于 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

Verify 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

Verify 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

概览

借助语义缓存政策，Apigee 用户可以利用 LLM 模型智能高效地处理相同或语义相似的提示，从而最大限度地减少后端 API 调用并减少资源消耗。

SemanticCacheLookup 和 SemanticCachePopulate 政策分别附加到 Apigee API 代理的请求流和响应流。当代理收到请求时，SemanticCacheLookup 政策会从请求中提取用户提示，并使用文本嵌入 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
```
- 查询最近邻网址：此 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 模型收到的任何 cache-control 标头。
- 点击保存。

向 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 分钟）。

增加依赖服务的配额

如果您因每秒查询次数 (QPS) 较多而遇到性能瓶颈，可能需要增加 Google Cloud 项目中的依赖服务的以下配额：

每分钟每个区域的在线预测请求数（按区域选择）
每个基本模型每分钟每个区域的区域级在线预测请求数（按区域和 textembedding-gecko 模型选择）
每分钟每个区域的 Matching Engine 流式更新请求数（按区域选择）

如需增加上述某个服务的配额，请执行以下操作：

前往配额和系统限制页面：
前往“配额和系统限制”
在过滤条件栏中，输入您要增加的特定配额的名称，以及区域和模型名称（如果相关）。
例如，按每个基本模型每分钟每个区域的区域级在线预测请求数、textembedding-gecko 和 us-west1 进行过滤。
点击要增加的服务对应的菜单，然后选择修改配额。
输入新的更高配额值。
点击完成。
点击提交请求。

提交申请后，系统会处理配额增加。您可以使用配额和系统限制页面上的增加配额申请标签页监控状态。

限制

以下限制适用于语义缓存政策：

可缓存的文本大小上限为 256 KB。如需了解详情，请参阅 Apigee 限制页面上的缓存值大小。
Apigee 会忽略从 LLM 模型收到的任何 cache-control 标头。
如果缓存未正确失效，或者语义相似度算法不够准确，无法区分含义非常相似的输入，则回答可能会返回过时或不正确的信息。
- 如需详细了解如何配置 TTL 以管理数据新鲜度，请参阅最佳实践部分。
- 如需详细了解如何配置语义相似度阈值，请参阅配置语义缓存政策部分。
- 如需详细了解如何调优语义相似度算法，请参阅过滤向量匹配项。
并非所有区域都支持向量搜索功能。如需查看受支持的区域列表，请参阅“Vertex AI 位置”页面的功能可用性部分。如果 Apigee 组织位于不受支持的区域，则您必须在与 Apigee 组织不同的区域中创建索引端点。
语义缓存政策不支持与使用 Eventflow 对服务器发送事件 (SSE) 进行连续响应流式传输的 API 代理搭配使用。
语义缓存政策使用 LLM API，这可能会导致延迟时间增加到数百毫秒。

后续步骤

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

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

准备工作

所需的角色

设置环境变量

设置项目

概览

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

创建和部署 Vector Search 索引

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

配置语义缓存政策

向 API 代理添加 Google 身份验证

部署 API 代理

测试语义缓存政策

最佳做法

增加依赖服务的配额

限制

后续步骤

语义缓存政策使用入门