SemanticCachePopulate 政策

總覽

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

這項政策會使用 Vertex AI 文字嵌入 API 為文字產生嵌入，並使用 Vector Search 根據語意相似度 (而非完全比對) 快取 API 回應。

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

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

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

事前準備

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

• 建立 Vertex AI 專案。
• 建立 Vector Search 索引。
• 為索引建立 Vertex AI 端點。
• 建立 SemanticCachePopulate 政策。

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

角色和權限

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

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

啟用 API

Enable the Compute Engine, Vertex AI, and Cloud Storage APIs.

Enable the APIs

<SemanticCachePopulate> 元素

定義 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>

<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> 的子元素：

範例

本節提供使用 <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> 元素使用以下語法：

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

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

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

<IgnoreUnresolvedVariables>

判斷在變數未解析時是否停止處理。將其設為 true 可忽略未解析的變數，並繼續處理。

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

<SimilaritySearch>

元素，其中包含更新向量索引所需的資訊。

詳情請參閱「更新/插入資料點」。

資料點的到期時間是自輸入時間起算的 <TTLInSeconds>。

<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> 元素。

VertexAI 元素使用以下語法：

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

<網址> (<VertexAI> 的子項)

用於在向量索引中新增或更新資料點的網址。

URL 元素使用以下語法：

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

<TTLInSeconds>

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

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

流程變數

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

政策可以在執行期間設定這些唯讀變數。

錯誤參考資料

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

執行階段錯誤

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

部署錯誤

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

錯誤變數

當這項政策在執行階段觸發錯誤時，系統就會設定這些變數。詳情請參閱「關於政策錯誤的相關資訊」。

錯誤回應範例

{
"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 查看政策架構。