本頁面由 Cloud Translation API 翻譯而成。

開始使用語意快取政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本頁面說明如何設定及使用 Apigee 語意快取政策，根據語意相似度啟用智慧回應重複使用功能。在 Apigee API Proxy 中使用這些政策，可盡量減少不必要的後端 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 文字嵌入 API 和向量搜尋。
確認 Apigee 執行個體中提供完整環境。語意快取政策只能在全方位環境中部署。

必要的角色

如要取得建立及使用語意快取政策所需的權限，請管理員在您用來部署 Apigee 快取代理的服務帳戶中，授予您 AI 平台使用者 (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 將提示轉換為數值表示法。使用向量搜尋執行語意相似度搜尋，找出相似提示。如果找到類似的提示資料點，系統就會執行快取查詢。如果找到快取資料，系統會將快取回應傳回給用戶端。

如果相似度搜尋未傳回類似的先前提示，LLM 模型會針對使用者提示產生內容，並在 Apigee 快取中填入回應。建立回饋循環，以便更新 Vector Search 索引項目，為日後的要求做好準備。

以下各節說明建立及設定語意快取政策所需的步驟：

為 Vector Search 索引設定服務帳戶。
建立及部署 Vector Search 索引。
建立 API Proxy 來啟用語意快取功能。
設定語意快取政策。
測試語意快取政策。

為 Vector Search 索引設定服務帳戶

如要為向量搜尋索引設定服務帳戶，請完成下列步驟：

使用下列指令建立服務帳戶：

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 是先前步驟中建立的服務帳戶名稱。

使用下列指令，將身分與存取權管理角色 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 Proxy 以啟用語意快取

在這個步驟中，您將使用「Proxy with Semantic Cache」範本建立新的 API Proxy (如果您尚未建立的話)。

在建立 API Proxy 之前，請設定下列環境變數：

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

如要建立 Proxy，以便搭配語意快取功能使用：

前往 Google Cloud 控制台的「API 代理」頁面。
前往 API Proxy
按一下「+ 建立」，開啟「建立 API Proxy」窗格。
在「Proxy template」方塊中，選取「Proxy with Semantic Cache」。
輸入下列詳細資料：
- Proxy name：輸入 Proxy 名稱。
- 說明：(選填) 輸入 Proxy 的說明。
- 目標 (現有 API)：輸入 Proxy 呼叫的後端服務網址。這是用於產生內容的 LLM 模型端點。
  在本教學課程中，您可以將「目標 (現有 API)」設為：
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent
```
輸入以下語意快取網址：
注意：您也可以在「Develop」分頁的 Proxy 編輯器中，將這些網址新增至 XML 設定。
- 產生嵌入網址：這項 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 index URL：這項 Vertex AI 服務會使用新項目或修改過的項目更新索引。
  在本教學課程中，您可以將此網址設為下列網址：
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints
```
點選「下一步」。
按一下 [建立]。

您可以在「Develop」分頁中查看 API Proxy 的 XML 設定。含有預設值的 SemanticCacheLookup 和 SemanticCachePopulate 政策已附加至 Proxy 要求和回應流程。

設定語意快取政策

如要查看各項政策的 XML 設定，請在 API Proxy 的「Develop」分頁中，按一下「Detail」檢視畫面中的政策名稱。您可以直接在「Develop」分頁的「Code」檢視畫面中編輯政策 XML。

編輯政策：

SemanticCacheLookup 政策：
- 移除 <UserPromptSource> 元素，即可使用預設值。
- 更新 <DeployedIndexId> 元素，使用 semantic_cache 值。
- 設定語意相似度 <Threshold> 值，以決定何時將兩個提示視為相符。預設值為 0.9，但您可以根據應用程式的敏感度調整這個值。這個數字越大，系統就必須越嚴格地判斷提示是否與快取命中。在本教學課程中，建議將這個值設為 0.95。
- 按一下 [儲存]。
SemanticCachePopulate 政策：
- 設定 <TTLInSeconds> 元素，以秒為單位指定快取到期前剩餘的秒數。預設值為 60 秒。請注意，Apigee 會忽略從 LLM 模型收到的任何快取控制項標頭。
- 按一下 [儲存]。

在 API Proxy 中新增 Google 驗證

您還必須在 API 代理程式的目標端點中新增 Google 驗證，才能啟用對目標的代理呼叫。

如要新增 Google 存取權憑證，請按照下列步驟操作：

在「Develop」分頁中，按一下「Target endpoints」資料夾下方的「default」。「Code」檢視畫面會顯示 <TargetEndpoint> 元素的 XML 設定。

編輯 XML，在 <HTTPTargetConnection> 下方新增下列設定：

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

按一下 [儲存]。

部署 API Proxy

如何部署 API Proxy：

按一下「Deploy」，開啟「Deploy API proxy」窗格。
Revision 欄位應設為 1。如果沒有，請按一下「1」選取。
在「環境」清單中，選取要部署 Proxy 的環境。環境必須是全面環境。
輸入先前步驟中建立的服務帳戶。
按一下 [Deploy] (部署)。

測試語意快取政策

如要測試語意快取政策，請按照下列步驟操作：

使用下列指令向 Proxy 傳送要求：

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 Proxy 的 basepath。

為什麼天空是藍色的？
為什麼天空是藍色的？
為什麼天空是藍色的？
你能解釋為什麼天空是藍色的嗎？
天空是藍色的，為什麼會這樣？

比較在快取類似提示後，每個呼叫的回應時間。

如要確認呼叫是否從快取中提供，請檢查回應標頭。應附加 Cached-Content: true 標頭。

最佳做法

建議您在使用語意快取政策時，將下列最佳做法納入 API 管理計畫：

使用 Model Armor 避免快取機密資料。
為避免機密資料快取，建議您使用 Model Armor 進行內容篩選。如果 Model Armor 偵測到私密資訊，就會將回應標示為不可快取。詳情請參閱「Model Armor 總覽」。
透過 Vertex AI 資料點無效化和存留時間 (TTL) 管理資料新鮮度。
建議您實施適當的資料點無效化策略，確保快取的回應為最新狀態，並反映後端系統的最新資訊。詳情請參閱「更新及重建有效索引」。

您也可以根據資料的變動性和更新頻率，調整快取回應的 TTL。如要進一步瞭解如何在 SemanticCachePopulate 政策中使用 TTL，請參閱 <TTLInSeconds>。
使用預先定義的快取策略，確保最準確的回應資料。
建議您導入預先定義的快取策略，類似於下列做法：
- 一般 AI 回應：針對非使用者專屬回應，設定較長的 TTL (例如一小時)。
- 使用者專屬回應：請勿為包含使用者專屬資訊的回應實作快取，或為其設定短 TTL (例如五分鐘)。
- 時間敏感型回應：針對需要即時或頻繁更新的回應，設定較短的 TTL (例如五分鐘)。

限制

以下限制適用於語意快取政策：

可快取的文字大小上限為 256 KB。詳情請參閱 Apigee 限制頁面中的「快取值大小」。
Apigee 會忽略從 LLM 模型收到的任何快取控制項標頭。
如果快取未正確失效，或是語意相似度演算法不夠準確，無法區分意義相近的輸入內容，回應可能會傳回過時或不正確的資訊。
並非所有地區都支援向量搜尋功能。如需支援的地區清單，請參閱 Vertex AI 位置頁面的「功能適用範圍」一節。如果 Apigee 機構位於不支援的區域，您必須在 Apigee 機構所在區域以外的區域建立索引端點。
語意快取政策不適用於使用 EventFlow 的 API Proxy，以便持續串流回應伺服器傳送的事件 (SSE)。
<UserPromptSource> 中的 JsonPath 函式不支援 ignoreUnresolvedVariables 功能。根據預設，系統會在套用訊息範本時忽略空值或空白值。

後續步驟

如要瞭解如何開始使用 Model Armor 政策，請參閱本文。