本頁面由 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 Text embeddings API 和 Vector Search。
確認 Apigee 執行個體中是否有可用的完整環境。語意快取政策只能部署在「全方位」環境中。

必要的角色

如要取得建立及使用語意快取政策所需的權限，請要求管理員在您用來部署 Apigee Proxy 的服務帳戶中，授予您 AI Platform 使用者 (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 代理的要求和回應流程。Proxy 收到要求時，SemanticCacheLookup 政策會從要求中擷取使用者提示，並使用 Text Embeddings API 將提示轉換為數字表示法。系統會使用 Vector Search 執行語意相似度搜尋，找出類似的提示。如果找到類似的提示資料點，系統就會執行快取查詢。如果找到快取資料，系統會將快取的回應傳回給用戶端。

如果相似度搜尋未傳回類似的先前提示，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 是在上一個步驟中建立的服務帳戶名稱。

使用下列指令，將 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 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 proxies」(API 代理) 頁面。
前往 API Proxy
按一下「+ 建立」，開啟「建立 API Proxy」窗格。
在「Proxy template」(Proxy 範本) 方塊中，選取「Proxy with Semantic Cache」(Proxy 與語意快取)。
輸入下列詳細資料：
- Proxy 名稱：輸入 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
```
輸入下列語意快取網址：
注意：這些網址也可以在「開發」分頁的「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
```
點選「下一步」。
點選「建立」。

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

設定語意快取政策

在 API 代理的「開發」分頁中，按一下「詳細資料」檢視畫面中的政策名稱，即可查看各項政策的 XML 設定。您可以在「開發」分頁的「程式碼檢視畫面」中，直接編輯政策 XML。

編輯政策：

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

在 API Proxy 中新增 Google 驗證

您也必須在 API Proxy 的目標端點中新增 Google 驗證，才能對目標進行 Proxy 呼叫。

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

在「Develop」(開發) 分頁中，按一下「Target endpoints」(目標端點) 資料夾下方的「default」(預設)。「程式碼檢視畫面」會顯示 <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」(部署 API Proxy) 窗格。
「修訂版本」欄位應設為「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 基礎路徑。

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

類似提示快取完畢後，比較每次呼叫的回應時間。

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

最佳做法

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

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

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

限制

語意快取政策有以下限制：

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

後續步驟

瞭解如何開始使用 Model Armor 政策。