Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

SemanticCachePopulate 政策

可擴充政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

SemanticCachePopulate 政策是進階快取政策，旨在最佳化 AI 工作負載的效能，尤其是涉及大型語言模型 (LLM) 的工作負載。

這項政策會使用 Vertex AI Text Embeddings API 生成文字嵌入，並透過向量搜尋根據語意相似度 (而非完全比對) 快取 API 回應。

SemanticCachePopulate 政策可減少重複查詢的回應時間，並減少對 LLM 的呼叫量，進而節省成本。

這項政策會與 SemanticCacheLookup 政策搭配使用。

這項政策屬於可擴充政策，使用這項政策可能會產生費用或影響使用率，具體取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

事前準備

使用 SemanticCachePopulate 政策前，請先完成下列工作：

建立 Vertex AI 專案。
建立向量搜尋索引。
為索引建立 Vertex AI 端點。
建立 SemanticCachePopulate 政策。

如要進一步瞭解如何完成這些工作，請參閱「開始使用語意快取政策」。

角色和權限

如要取得套用及使用 SemanticCachePopulate 政策所需的權限，請要求管理員在您用於部署 Apigee Proxy 的服務帳戶，授予 AI Platform 使用者 (roles/aiplatform.user) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

啟用 API

啟用 Compute Engine、Vertex AI 和 Cloud Storage API (如果尚未啟用)。

啟用 API 時所需的角色

如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

啟用 API

`<SemanticCachePopulate>` 元素

定義 SemanticCachePopulate 政策。

預設值	請參閱下方的「預設政策」分頁
必填與否	必填
類型	複雜物件
父項元素	不適用
子元素	`<DisplayName>` `<IgnoreUnresolvedVariables>` `<SimilaritySearch>` `<TTLInSeconds>`

<SemanticCachePopulate> 元素使用下列語法：

語法

<SemanticCachePopulate> 元素使用下列語法：

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

預設政策

以下範例顯示在 Apigee UI 中，將 SemanticCachePopulate 政策新增至 API Proxy 時的預設設定：

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

在 Apigee UI 中插入新的 SemanticCachePopulate 政策時，範本會包含所有可能作業的存根。請參閱下方資訊，瞭解必要元素。

這個元素包含下列所有政策都適用的屬性：

屬性	預設	是否必要？	說明
`name`	不適用	必要	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
`continueOnError`	false	選用	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
`enabled`	是	選用	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
`async`	false	已淘汰	此屬性已淘汰。

下表概略說明 <SemanticCachePopulate> 的子元素：

子元素	是否必要	說明
`<DisplayName>`	選用	政策名稱。
`<IgnoreUnresolvedVariables>`	選用	決定在屬性集未解決時是否停止處理。
`<SimilaritySearch>`	必填	包含更新向量索引所需資訊的元素。詳情請參閱「Upsert datapoints」。資料點的到期時間為輸入時間後的 <TTLInSeconds>。
`<TTLInSeconds>`	選用	快取回應的存留時間 (以秒為單位)。預設值為 `60`。

範例

本節提供使用 <SemanticCachePopulate> 的範例。

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

子元素參考資料

本節說明 <SemanticCachePopulate> 的子項元素。

`<DisplayName>`

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用其他更自然的名稱標記政策。

<DisplayName> 元素適用於所有政策。

預設值	不適用
是否必要？	(非必要) 如果省略 `<DisplayName>`，系統會使用政策的 `name` 屬性值。
類型	字串
上層元素	<`PolicyElement`>
子元素	無

<DisplayName> 元素使用以下語法：

語法

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

範例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 元素沒有屬性或子項元素。

`<IgnoreUnresolvedVariables>`

判斷變數無法解析時，是否要停止處理程序。設為 true，忽略未解析的變數並繼續處理。

提供 <DefaultValue> 時，不適用 IgnoreUnresolvedVariables。

預設值	否
必填與否	選用
類型	布林值
父項元素	`<SemanticCachePopulate>`
子元素	無

`<SimilaritySearch>`

這個元素包含更新向量索引所需的資訊。

詳情請參閱「Upsert datapoints」。

資料點的到期時間為輸入時間後的 <TTLInSeconds>。

預設值	不適用
必填與否	必填
類型	字串
父項元素	`<SemanticCachePopulate>`
子元素	`<VertexAI>`

<SimilaritySearch> 元素使用下列語法：

<SimilaritySearch>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
  </VertexAI>
</SimilaritySearch>

<VertexAI> (`<SimilaritySearch>` 的子項)

包含 Vertex AI 專屬屬性的 <URL> 元素。

預設值	不適用
必填與否	必填
類型	字串
父項元素	`<SimilaritySearch>`
子元素	`<URL>`

VertexAI 元素使用下列語法：

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

<URL> (`<VertexAI>` 的子項)

用於在向量索引中 upsert 資料點的網址。

預設值	不適用
必填與否	必填
類型	字串
父項元素	`<VertexAI>`
子元素	無

URL 元素使用下列語法：

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>

URL 元素支援使用網址範本。如要在此元素中提供變數來保留網址值，請參閱以下範例：

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

`<TTLInSeconds>`

這個元素會指定快取回應的存留時間 (以秒為單位)。預設值為 60。

詳情請參閱「更新及重建有效索引」。

預設值	不適用
必填與否	選用
類型	字串
父項元素	`<SemanticCachePopulate>`
子元素	無

流程變數

流程變數會根據 HTTP 標頭、訊息內容或流程中的可用內容，為政策和流程設定動態執行階段行為。如要進一步瞭解流程變數，請參閱「流程變數參考資料」。

這項政策會在執行期間提供下列唯讀流程變數集。您可以搭配 DataCapture 政策使用這些流程變數，建立自訂的 Analytics 報表。詳情請參閱「依據資料擷取政策收集顧客數位資料」。

變數名稱	說明
`response.content`	包含 API 回應的完整內容。
`SemanticCachePopulate.policy_name.upsert_index_request`	包含傳送至 Vertex AI 向量搜尋 API 的要求酬載，用於以新的嵌入和中繼資料更新向量索引。
`SemanticCachePopulate.policy_name.upsert_index_response`	包含 Vertex AI 向量搜尋 API 的回應，指出索引更新作業成功或失敗。

錯誤參考資料

本節說明 Apigee 針對 <SemanticCachePopulate> 政策傳回的錯誤代碼和錯誤訊息，以及設定的錯誤變數。如果您要開發錯誤規則來處理錯誤，請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

執行政策時可能會發生這些錯誤。

故障代碼	HTTP 狀態	原因
`steps.semanticcachepopulate.VectorSearchUpsertServiceUnavailable`	`400`	如果 Vector Search Upsert Datapoints API 無法使用，就會發生這項錯誤。
`steps.semanticcache.populate.VectorSearchUpsertAPIFailed`	`500`	如果向量搜尋 Upsert Datapoints API 服務失敗，就會發生這項錯誤。
`steps.semanticcache.populate.AuthenticationFailure`	`500`	如果服務帳戶沒有必要權限，就會發生這項錯誤。
`steps.semanticcache.populate.CalloutError`	`500`	Vertex AI 服務呼叫失敗。
`steps.semanticcache.populate.InternalError`	`500`	如果 `<SemanticCachePopulate>` 政策發生未預期的錯誤，就會出現這個錯誤。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱	原因
`The SimilaritySearch/VertexAI/PrivateServiceConnect element is not supported in SemanticCachePopulate.`	在 <SemanticCachePopulate> 中使用 <PrivateServiceConnect> 元素時，就會發生這種情況。
`The SimilaritySearch/VertexAI/URL element is required.`	<SimilaritySearch> 中的 <URL> 元素空白時，就會發生這種情況。
`The SimilaritySearch URL {url} is invalid.`	<SimilaritySearch> 中的 <URL> 元素空白或無效時，就會發生這種情況。
`The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https.`	如果 SimilaritySearch <URL> 元素的 `http` 配置無效，就會發生這種情況。
`The TTLInSeconds element must be >= 0.`	如果值設為零或負數，API Proxy 就無法部署。

故障變數

這項政策在執行階段觸發錯誤時，系統會設定這些變數。詳情請參閱「政策錯誤須知」。

變數	地點	範例
`fault.name="FAULT_NAME"`	`FAULT_NAME` 是錯誤名稱，如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤代碼的最後一部分。	`fault.name Matches "UnresolvedVariable"`
`semanticcachepopulate.POLICY_NAME.failed`	`POLICY_NAME` 是使用者指定的政策名稱，該政策擲回了錯誤。	`semanticcachepopulate.SC-populate.failed = true`

錯誤回應範例

注意：處理錯誤時，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為文字可能會變更。

{
"fault": {
  "faultstring": "SemanticCacheLookup[SC-populate]: unable to resolve variable [variable_name]",
  "detail": {
    "errorcode": "steps.semanticcachepopulate.UnresolvedVariable"
  }
}
}

錯誤規則範例

<FaultRule name="SemanticCacheLookup Faults">
  <Step>
      <Name>SCL-CustomSetVariableErrorResponse</Name>
      <Condition>(fault.name = "SetVariableFailed")</Condition>
  </Step>
  <Condition>(semanticcachelookup.failed = true)</Condition>
</FaultRule>

結構定義

每種政策類型都是由 XML 結構定義 (.xsd) 定義。如需參考資料，請前往 GitHub 查看政策結構定義。

SemanticCachePopulate 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

角色和權限

啟用 API

<SemanticCachePopulate> 元素

語法

預設政策

範例

子元素參考資料

<DisplayName>

語法

範例

<IgnoreUnresolvedVariables>

<SimilaritySearch>

<VertexAI> (<SimilaritySearch> 的子項)

<URL> (<VertexAI> 的子項)

<TTLInSeconds>

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

故障變數

錯誤回應範例

錯誤規則範例

結構定義

SemanticCachePopulate 政策

`<SemanticCachePopulate>` 元素

`<DisplayName>`

`<IgnoreUnresolvedVariables>`

`<SimilaritySearch>`

<VertexAI> (`<SimilaritySearch>` 的子項)

<URL> (`<VertexAI>` 的子項)

`<TTLInSeconds>`