開始使用語意快取政策

本頁內容適用於 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.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. 在 Google Cloud 專案中設定及設定 Vertex AI 文字嵌入 API 和 Vector Search。
2. 確認 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 使用者可透過語意快取政策，智慧地為相同或語意相似的提示提供服務，有效減少後端 API 呼叫次數，並降低資源耗用量。

SemanticCacheLookup 和 SemanticCachePopulate 政策會分別附加至 Apigee API 代理的要求和回應流程。Proxy 收到要求時，SemanticCacheLookup 政策會從要求中擷取使用者提示，並使用 Text Embeddings API 將提示轉換為數字表示法。語意相似度搜尋會使用 Vector Search 尋找類似提示。如果找到類似的提示資料點，系統會執行快取查閱作業。如果找到快取資料，快取回應就會傳回給用戶端。

如果相似度搜尋未傳回類似的先前提示，LLM 模型就會根據使用者提示生成內容，並在 Apigee 快取中填入回覆。建立意見回饋迴路，更新 Vector Search 索引項目，為日後的要求做準備。

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

1. 為 Vector Search 索引設定服務帳戶。
2. 建立及部署 Vector Search 索引。
3. 建立 API Proxy，啟用語意快取。
4. 設定語意快取政策。
5. 測試語意快取政策。

設定 Vector Search 索引的服務帳戶

如要為 Vector Search 索引設定服務帳戶，請完成下列步驟：

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

   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"

2. 使用下列指令將 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 替換為上一步建立的服務帳戶名稱。

3. 使用下列指令，將 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 索引，請按照下列步驟操作：

1. 建立允許串流更新的 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 索引，請參閱「建立索引」。

2. 使用下列指令建立 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」。

3. 使用下列指令將索引部署至端點：

   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，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「API proxies」(API 代理) 頁面。

   前往 API Proxy

2. 按一下「+ 建立」，開啟「建立 API Proxy」窗格。
3. 在「Proxy template」(Proxy 範本) 方塊中，選取「Proxy with Semantic Cache」(Proxy 與語意快取)。
4. 輸入下列詳細資料：
   • 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

5. 輸入下列語意快取網址：
   注意：您也可以在「開發」分頁的「Proxy editor」中，將這些網址新增至 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

6. 點選「下一步」。
7. 點選「建立」。

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

注意：SemanticCachePopulate 和 SemanticCacheLookup 政策支援對這些元素使用網址範本。 如要提供變數來保留網址值，請在這個元素中提供變數，如下列範例所示：

<URL>https://{URL_VARIABLE}</URL>

設定語意快取政策

在 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 存取權杖，請按照下列步驟操作：

1. 在「Develop」(開發) 分頁中，按一下「Target endpoints」(目標端點) 資料夾下方的「default」(預設)。「程式碼檢視畫面」會顯示 <TargetEndpoint> 元素的 XML 設定。
2. 編輯 XML，在 <HTTPTargetConnection> 下方新增下列設定：

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

3. 按一下 [儲存]。

部署 API Proxy

如要部署 API Proxy，請按照下列步驟操作：

1. 按一下「Deploy」(部署)，開啟「Deploy API proxy」(部署 API Proxy) 窗格。
2. 「修訂版本」欄位應設為「1」。如未選取，請按一下「1」選取。
3. 在「環境」清單中，選取要部署 Proxy 的環境。環境必須是綜合環境。
4. 輸入您在稍早步驟中建立的「服務帳戶」。
5. 按一下 [Deploy] (部署)。

測試語意快取政策

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

1. 使用下列指令向 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 代理項目基本路徑。

重複發出 API 呼叫，並將提示字串替換為下列語意相似的提示字串：
• 為什麼天空是藍色的？
• 為什麼天空是藍色的？
• 為什麼天空是藍色的？
• 你能解釋天空為什麼是藍色的嗎？
• 天空是藍色的，為什麼？
2. 類似提示快取完畢後，比較每次呼叫的回應時間。

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

最佳做法

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

• 使用 Model Armor 防止快取機密資料。

  為避免系統快取私密資料，建議使用 Model Armor 進行內容篩選。 如果偵測到私密資訊，Model Armor 會將回覆標示為不可快取。詳情請參閱 Model Armor 總覽。

• 使用 Vertex AI 資料點失效和存留時間 (TTL) 管理資料新鮮度。

  建議您實作適當的資料點失效策略，確保快取的回應是最新狀態，並反映後端系統的最新資訊。詳情請參閱「 更新及重建有效索引」。

  您也可以根據資料的波動程度和更新頻率，調整快取回應的 TTL。如要進一步瞭解如何在 SemanticCachePopulate 政策中使用 TTL，請參閱 <TTLInSeconds>。

• 使用預先定義的快取策略，確保回應資料最準確。

  建議您導入類似下列項目的預先定義快取策略：

  • 一般 AI 回覆：為非使用者專屬的回覆設定較長的存留時間 (例如一小時)。
  • 使用者專屬的回應：請勿為含有使用者專屬資訊的回應實作快取，或設定較短的 TTL (例如五分鐘)。
  • 需要即時回應：如要即時或頻繁更新回應，請設定較短的 TTL (例如五分鐘)。

提高相依服務的配額

如果每秒查詢次數 (QPS) 較高，導致效能瓶頸，您可能需要增加 Google Cloud 專案中相依服務的下列配額：

• 每個區域每分鐘的線上預測要求數 (按區域選取)
• 每個區域每分鐘的每個基礎模型區域線上預測要求數 (依區域和 textembedding-gecko 模型選取)
• 每個地區每分鐘的 Matching Engine 串流更新要求數 (依地區選取)

如要提高這些服務的配額：

1. 前往「配額與系統限制」頁面：

   前往「配額與系統限制」

2. 在篩選列中，輸入要增加的特定配額名稱，以及區域和模型名稱 (如適用)。

   舉例來說，您可以依「每個地區每分鐘每個基礎模型的區域線上預測要求數」、「textembedding-gecko」和「us-west1」進行篩選。

3. 按一下要增加配額的服務的 選單，然後選取「編輯配額」。
4. 輸入新的配額值 (必須大於目前值)。
5. 按一下 [完成]。
6. 按一下 [提交要求]。

提交要求後，系統會處理配額提高程序。您可以在「配額與系統限制」頁面中，使用「增加要求」分頁監控狀態。

限制

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

• 可快取的文字大小上限為 256 KB。詳情請參閱 Apigee 限制頁面的「快取值大小」。
• Apigee 會忽略從 LLM 模型收到的任何快取控制項標頭。
• 如果快取未正確失效，或語意相似度演算法不夠準確，無法區分意義非常相似的輸入內容，回覆就可能傳回過時或不正確的資訊。
  • 如要進一步瞭解如何設定 TTL 來管理資料更新間隔，請參閱「最佳做法」一節。
  • 如要進一步瞭解如何設定語意相似度門檻，請參閱「設定語意快取政策」一節。
  • 如要進一步瞭解如何調整語意相似度演算法，請參閱「篩選向量比對結果」。
• 向量搜尋功能僅支援部分地區。如需支援的地區清單，請參閱 Vertex AI 服務地區頁面的「 功能適用情形」一節。如果 Apigee 機構位於不支援的區域，您必須在 Apigee 機構以外的區域建立索引端點。
• 使用 EventFlows 的 API Proxy，不支援語意快取政策，這類 Proxy 會持續串流傳送伺服器傳送的事件 (SSE)。
• 語意快取政策會使用 LLM API，因此延遲時間可能會增加數百毫秒。

後續步驟

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