SemanticCacheLookup 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

總覽

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

這項政策會使用 Vertex AI 文字嵌入 API 為文字產生嵌入，並使用 Vector Search 根據語意相似性 (而非完全相符) 找出相似提示。

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

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

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

事前準備

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

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

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

必要的角色

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

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

啟用 API

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

Enable the APIs

<SemanticCacheLookup> 元素

定義 SemanticCacheLookup 政策。

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

<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

<SemanticCacheLookup async="false" continueOnError="false"enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict
      </URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <Threshold>0.9</Threshold>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

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

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

{jsonPath($.contents[-1].parts[-1].text,request.content,true)}

子元素參照

本節將說明 <SemanticCacheLookup> 的子元素。

<DisplayName>

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

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

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

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

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

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

<IgnoreUnresolvedVariables>

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

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

<UserPromptSource>

要擷取使用者提示文字的酬載位置。系統僅支援字串文字值。

這個欄位支援 Apigee 訊息範本語法，包括使用變數或 JSON 路徑函式。

例如：

{jsonPath($.contents[-1].parts[-1].text,request.content,true)}

<Embeddings>

這個元素包含產生文字嵌入資料所需的資訊。

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

<Embeddings>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
  </VertexAI>
</Embeddings>

<VertexAI> (<Embeddings> 的子項)

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

VertexAI 元素使用以下語法：

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
</VertexAI>

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

用於產生文字嵌入的網址。如需可為 SemanticCacheLookup 政策提供文字嵌入資料的模型清單，請參閱「 支援的模型」。

URL 元素使用以下語法：

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>

<SimilaritySearch>

這個元素包含執行相似搜尋所需的資訊。

詳情請參閱「查詢公開索引以取得最近鄰點」。

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

<SimilaritySearch>
  <VertexAI>
    <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors
    </URL>
    <Threshold>0.9</Threshold>
    <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
  </VertexAI>
</SimilaritySearch>

<VertexAI> (<SimilaritySearch> 的子項)

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

VertexAI 元素使用以下語法：

<VertexAI>
  <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
  <Threshold>0.9</Threshold>
  <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>

下表概略說明 <VertexAI> 的子元素。

流程變數

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

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

錯誤參考資料

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

執行階段錯誤

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

部署錯誤

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

錯誤變數

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

錯誤回應範例

{
  "fault": {
    "faultstring": "SemanticCacheLookup[SC-lookup]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.semanticcachelookup.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 查看政策架構。