使用专用 (Private Service Connect) 端点的语义缓存

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

本页面介绍了如何配置和使用 Apigee 语义缓存政策，以根据语义相似度启用智能响应重用。在此示例中，政策会针对部署在私有 (Private Service Connect) 端点上的 Vector Search 索引运行相似度搜索。在 Apigee API 代理中使用这些政策可最大限度地减少冗余的后端 API 调用，缩短延迟时间，并降低运营成本。

本指南适用于 Apigee 和 Apigee Hybrid。两个平台上的政策配置完全相同，只有运行时访问专用端点的方式不同，如第 2 步：连接到服务连接中所述。 在 Apigee Hybrid 上，1.16.11 版及更高版本以及 1.17.0 版及更高版本支持通过专用 (Private Service Connect) 端点进行语义缓存。如需了解详情，请参阅在 Apigee Hybrid 上设置。

准备工作

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

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Compute Engine, AI Platform, and Cloud Storage APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  4. 在您的 Google Cloud 项目中启用并配置 Vertex AI 文本嵌入 API。
  5. 创建（或有权访问）部署在专用 (Private Service Connect) 端点上的 Vector Search 搜索索引。本教程不会重复 Vector Search 设置步骤；如需了解 SemanticCacheLookup 的特定要求和 Vector Search 文档的链接，请参阅 Vector Search 搜索索引前提条件。
  6. 确认您的 Apigee 实例中有中级或全面环境。语义缓存政策只能部署在中级或全面环境中。
  7. 确认您有一个环境组，其中包含可用于向 API 代理发送请求的运行时主机名。

所需的角色

如需获得创建和使用语义缓存政策所需的权限，请让管理员为您授予用于部署 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

Vector Search 索引前提条件

本教程假设您已在私有 (Private Service Connect) 端点上部署了 Vector Search 搜索索引（或将要创建该索引）。Vector Search 指南中介绍了如何创建、设置格式和部署 Vector Search 搜索索引，因此本教程不会重复这些步骤。按照 Vector Search 文档执行以下操作：

创建索引时，该索引必须满足以下 SemanticCacheLookup 专属要求：

  • 索引必须使用 STREAM_UPDATE ("indexUpdateMethod": "STREAM_UPDATE")，以便 SemanticCachePopulate 政策的 upsertDatapoints 调用可以近乎实时地进行查询。
  • 索引 dimensions 必须与您在 SemanticCacheLookup 政策中使用的嵌入模型的输出维度一致。本教程使用 gemini-embedding-001，默认情况下会生成 3072 维嵌入。如果您将输出截断为较低的维度（例如 768 或 1536），请将 dimensions 设置为相同的值。
  • 使用与政策的 <DistanceMeasureType> 匹配的距离衡量方式 (distanceMeasureType) 创建索引。SemanticCacheLookup 政策中的 <SimilaritySearch><VertexAI><DistanceMeasureType> 元素是可选的，默认值为 DOT_PRODUCT_DISTANCE；也支持 COSINE_DISTANCE。索引距离测量和政策 <DistanceMeasureType> 必须相同。

以下最简示例会创建一个兼容的索引。如需查看完整的请求正文和所有可用选项，请参阅创建和管理索引：

ACCESS_TOKEN=$(gcloud auth print-access-token) && curl -X POST \
  "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "semantic-cache-index",
    "metadata": {
      "config": {
        "dimensions": 3072,
        "distanceMeasureType": "DOT_PRODUCT_DISTANCE"
      }
    },
    "indexUpdateMethod": "STREAM_UPDATE"
  }'

请注意响应中返回的数字 INDEX_ID；您将在 SemanticCachePopulate 政策中使用它。创建索引后，创建 Private Service Connect 索引端点并将索引部署到该端点。

创建 Private Service Connect 索引端点时，该端点必须满足以下 SemanticCacheLookup 专属要求：

  • projectAllowlist 必须包含发起连接的 Apigee 项目：
    • Apigee：使用 Apigee 租户项目。从 Organizations API（apigeeProjectId 字段）获取租户项目 ID。
    索引端点创建后，projectAllowlist 无法修改。如果您将错误的项目列入许可清单，则必须删除并重新创建索引端点。

记下索引端点的数字 INDEX_ENDPOINT_ID。

为 Apigee 代理配置服务账号

Apigee 代理使用服务账号进行 Vertex AI REST 调用：SemanticCacheLookup 政策中的 Embeddings API、SemanticCachePopulate 政策中的 upsertDatapoints 以及模型目标。向该服务账号授予 AI Platform User (roles/aiplatform.user) 角色：

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

其中，SERVICE_ACCOUNT 是代理使用的服务账号的邮箱。在第 4 步：导入和部署 API 代理中部署代理时，您需要引用此服务账号。

Apigee Hybrid 部署的其他前提条件

对于 Apigee Hybrid 部署，请确认以下额外要求：

  • 1.16.11 或更高版本，或者 1.17.0 或更高版本的 Hybrid 运行时，安装在您自己的 Kubernetes 集群中。请参阅 Apigee Hybrid 安装文档。此功能本身不会增加任何集群要求，任何受支持的混合集群都可以使用。
  • 一个中级或全面环境，以及一个具有运行时主机名的环境组（与 Apigee 上的环境组相同）。语义缓存政策只能部署到中级环境或全面环境。
  • 从运行时到专用端点的网络可达性。消息处理器必须能够通过 TARGET_HOST:10000 打开与 Vector Search Private Service Connect 端点的明文 gRPC 连接。
  • REST 调用的出站流量。Embeddings、Populate 和 model-target 调用会发送到公共 REGION-aiplatform.googleapis.com 接口，因此运行时还需要一条通往 Google API 的路径，可以是直接路径，也可以是私有路径（如果您的集群没有公共出站流量）。

在 Apigee Hybrid 上设置

Apigee Hybrid 1.16.11 版及更高版本以及 1.17.0 版及更高版本支持通过专用 (Private Service Connect) 端点进行语义缓存。本教程中的政策配置和 Vector Search 步骤与 Apigee 相同，不同之处在于，在 Hybrid 上，您需要自行运行运行时并提供其连接性。由于混合部署差异很大，因此本部分提供的是一般性指导，而不是确切的命令。此功能增加的唯一要求是，运行时必须能够通过明文 gRPC 访问专用端点。

提供网络可达性

在混合部署中，您必须手动管理连接，因为没有 Apigee 管理的端点连接。在您的使用方 VPC 中创建一个指向 Vector Search SERVICE_ATTACHMENT 的 Private Service Connect 端点，并将其内部 IP 地址用作代理中的 TARGET_HOST。如需了解详情，请参阅第 2 步：连接到服务连接。具体路由（例如共享 VPC 或 VPC 原生 GKE）取决于集群的配置。

如果您的集群缺少公共互联网出站流量，请确保运行时具有通往 Google API 的专用路径（例如专用 Google 访问通道），以处理 REST 通信。

与 grpc://TARGET_HOST:10000 建立连接后，请按照后续步骤（创建和部署索引、构建代理以及测试）操作，这些步骤对于 Apigee 和 Apigee Hybrid 都是相同的。

概览

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

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

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

在此场景中，Vector Search 搜索索引通过 gRPC 部署在专用 (Private Service Connect) 端点上。如需详细了解 Vector Search Private Service Connect 支持，请参阅查询专用服务访问通道或 Private Service Connect 索引。

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

  1. 验证资源并获取 Apigee 所需的值。
  2. 连接到服务连接。
  3. 构建 API 代理软件包。
  4. 导入和部署 API 代理。
  5. 测试语义缓存政策。

第 1 步：验证您的资源并获取 Apigee 所需的值

在配置 Apigee 之前，请确认您的 Vector Search 搜索索引端点已启用 Private Service Connect，并且您的索引已部署。然后，读取 Apigee 代理使用的两个值：服务连接和 DEPLOYED_INDEX_ID。

确认索引已部署，并且端点公开了 Private Service Connect 服务连接：

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.privateEndpoints.serviceAttachment)"

该命令会返回格式为 projects/TENANT_PROJECT/regions/REGION/serviceAttachments/SERVICE_ATTACHMENT_NAME 的服务连接资源名称。 本指南将该值称为 SERVICE_ATTACHMENT。如果该命令返回空值，则表示索引尚未部署到 Private Service Connect 端点。返回到 Vector Search 索引前提条件，并完成索引部署，然后再继续。

读取部署在端点上的索引的 DEPLOYED_INDEX_ID：

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.id)"

本指南将该值称为 DEPLOYED_INDEX_ID。您将在第 3 步：构建 API 代理包中的 SemanticCacheLookup 政策中使用它。

如需详细了解如何部署和查询专用索引端点，请参阅将索引部署到 Private Service Connect 端点和查询专用服务访问通道或 Private Service Connect 索引。

第 2 步：连接到服务连接

此步骤为您提供代理的 <GrpcEndpoint> 调用的专用主机。创建方式取决于您所用的平台。无论采用哪种方式，后续步骤中的代理配置都是相同的。

Apigee：创建端点连接

在 Apigee 上，创建 Apigee 端点连接。端点连接是 Apigee 的 Private Service Connect 使用方端。它会连接到 Vector Search 服务连接，并为您提供代理调用的专用主机。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
        "location": "'"$REGION"'",
        "serviceAttachment": "SERVICE_ATTACHMENT"
      }' \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments?endpointAttachmentId=ENDPOINT_ATTACHMENT"

轮询，直到连接的 state 为 ACTIVE 且其 connectionState 为 ACCEPTED，然后记下主机：

curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments/ENDPOINT_ATTACHMENT"

响应在 host 字段中包含主机。本指南将该值称为 TARGET_HOST。

如需从代理连接到 Vector Search 服务连接，您可以使用以下任一方法：

  • IP 地址：直接将 host 字段中返回的 IP 地址用作 TARGET_HOST（例如 7.0.3.4）。
  • 专用 DNS 记录：如果您在 Google Cloud 项目中配置了专用 Cloud DNS 区域，并与 Apigee 建立了 DNS 对等互连，则可以在专用区域中创建指向端点连接 IP 地址的 A 记录，并将该域名（例如 vectorsearch.example.com）用作 TARGET_HOST。如需了解详情，请参阅使用 DNS 记录和通过专用 DNS 对等互连区域进行连接。

适用于 Apigee Hybrid 的 Private Service Connect 端点

在 Apigee 中，Google 提供了一个“端点连接”资源，用于处理 Private Service Connect 连接。不过，在 Apigee Hybrid 中，您需要管理运行时和网络环境。无论集群在何处运行，都必须能够通过与 host:10000 的明文 gRPC 连接访问 Vector Search Private Service Connect 端点。

对于 Apigee Hybrid，请在 Google Cloud 指向 Vector Search SERVICE_ATTACHMENT的使用方 VPC 中创建 Private Service Connect 端点。在代理配置中，将端点的内部 IP 地址用作 TARGET_HOST。确保托管此端点的 Google Cloud 项目包含在 Vector Search 搜索索引端点的projectAllowlist中。如需了解详情，请参阅 Vector Search 搜索索引前提条件。

第 3 步：构建 API 代理软件包

创建代理包

创建以下目录布局： 

apiproxy/
├── PROXY_NAME.xml
├── proxies/default.xml
├── targets/default.xml
└── policies/
    ├── SCL-1.xml
    └── SCP-1.xml

policies/SCL-1.xml - SemanticCacheLookup 政策。<SimilaritySearch> 块使用 <PrivateServiceConnect><GrpcEndpoint>（无 <URL>）。

注意：<GrpcEndpoint> 规则：

  • 格式为 grpc://TARGET_HOST:PORT；架构必须为 grpc://。此版本不支持 grpcs:// (TLS)。
  • 对于 Vector Search，端口为 10000。Private Service Connect 数据平面端点在端口 10000 上提供 gRPC 服务，因此端点始终为 grpc://TARGET_HOST:10000。
  • TARGET_HOST 可以是端点连接 IP 地址（来自第 2 步），也可以是在专用 DNS 区域中创建的自定义 DNS 记录。
  • gRPC 跃点是明文且未经身份验证（通过网络隔离进行保护）。
<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-1">
  <DisplayName>SCL-1</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-embedding-001:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <PrivateServiceConnect>
        <GrpcEndpoint>grpc://TARGET_HOST:10000</GrpcEndpoint>
      </PrivateServiceConnect>
      <DeployedIndexID>DEPLOYED_INDEX_ID</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

policies/SCP-1.xml - SemanticCachePopulate 政策。Populate 仅支持 REST，并且必须使用 <URL>（它会在部署时拒绝 <PrivateServiceConnect>）： 

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

targets/default.xml - 模型目标。目标会调用 Google API，因此需要令牌；<GoogleAccessToken> 使用部署的服务账号： 

<TargetEndpoint name="default">
  <PreFlow name="PreFlow"><Request/><Response/></PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

proxies/default.xml - 对请求运行 SemanticCacheLookup 政策，对响应运行 SemanticCachePopulate 政策： 

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request><Step><Name>SCL-1</Name></Step></Request>
    <Response><Step><Name>SCP-1</Name></Step></Response>
  </PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPProxyConnection>
    <BasePath>/PROXY_NAME</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

PROXY_NAME.xml - 软件包描述符： 

<APIProxy name="PROXY_NAME">
  <BasePaths>/PROXY_NAME</BasePaths>
  <Policies><Policy>SCL-1</Policy><Policy>SCP-1</Policy></Policies>
  <ProxyEndpoints><ProxyEndpoint>default</ProxyEndpoint></ProxyEndpoints>
  <TargetEndpoints><TargetEndpoint>default</TargetEndpoint></TargetEndpoints>
</APIProxy>

第 4 步：导入和部署 API 代理

压缩该软件包，将其导入以创建新修订版本，然后使用您的服务账号部署该修订版本： 

TOKEN=$(gcloud auth print-access-token)
(cd BUNDLE_DIR && zip -r ../PROXY_NAME.zip apiproxy)
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -F "file=@PROXY_NAME.zip" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/apis?action=import&name=PROXY_NAME"
curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments?override=true&serviceAccount=SERVICE_ACCOUNT"

其中：

  • BUNDLE_DIR 是包含 apiproxy/ 文件夹的目录。归档文件的根目录中必须包含 apiproxy/ 文件夹。
  • ENV 是您在其中部署代理的 Apigee 环境。环境必须是中间或综合环境。
  • REVISION 是导入调用返回的修订版本号。
  • SERVICE_ACCOUNT 是您用于部署代理的服务账号的邮箱。

等待部署报告 READY： 

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments" | jq .state

第 5 步：测试语义缓存政策

发送新提示。这是缓存未命中：系统调用了模型，并缓存了回答。 

curl -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

再次发送相同的提示。这是缓存命中：响应由缓存提供，不会调用模型。 

curl -i -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

命中时，响应包含 Cached-content: true 标头、相同的答案和明显更低的延迟时间。

您还可以通过调试会话验证缓存。命中时，SemanticCacheLookup 政策会设置以下流变量：

变量 命中值
SemanticCacheLookup.SCL-1.dense_embeddings 提示的嵌入向量。
SemanticCacheLookup.SCL-1.is_nearest_neighbor_hit true
SemanticCacheLookup.SCL-1.cache_hit true
SemanticCacheLookup.SCL-1.cached_llm_response 缓存的回答。

如果命中，则不会调用模型目标，而是直接返回缓存的回答。

问题排查

如需查看完整的错误参考文档，请参阅 SemanticCacheLookup 政策。

限制

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

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

后续步骤