本頁面由 Cloud Translation API 翻譯而成。

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 Proxy 的服務帳戶中，授予您 AI Platform 使用者 (roles/aiplatform.user) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

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

啟用 API

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

Enable the APIs

`<SemanticCacheLookup>` 元素

定義 SemanticCacheLookup 政策。

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

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

預設政策

以下範例顯示在 Apigee 使用者介面中，將 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>

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

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

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

下表提供 <SemanticCacheLookup> 子元素的高階說明：

子元素	是否必要	說明
`<DisplayName>`	選用	政策名稱。
`<IgnoreUnresolvedVariables>`	選用	決定變數無法解析時是否停止處理。設為 `true` 可忽略未解析的變數，並繼續處理。
`<UserPromptSource>`	選用	要擷取使用者提示文字的酬載位置。系統僅支援字串文字值。這個欄位支援 Apigee 訊息範本語法，包括使用變數或 JSON 路徑函式。例如： {jsonPath($.contents[-1].parts[-1].text,request.content,true)}
`<Embeddings>`	必填	包含產生嵌入內容所需資訊的元素。
`<SimilaritySearch>`	必填	包含執行相似性搜尋所需資訊的元素。詳情請參閱「查詢公開索引以取得最相近鄰點」。

子元素參照

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

`<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。

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

`<UserPromptSource>`

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

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

例如：

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

預設值	{jsonPath($.contents[-1].parts[-1].text,request.content,true)}
必填與否	選用
類型	字串
父項元素	`<SemanticCacheLookup>`
子元素	無

`<Embeddings>`

這個元素包含生成文字嵌入內容所需的資訊。

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

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

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

VertexAI 元素使用下列語法：

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

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

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

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

URL 元素使用下列語法：

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

`<SimilaritySearch>`

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

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

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

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

預設值	不適用
必填與否	必填
類型	字串
父項元素	`<SimilaritySearch>`
子元素	`<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> 子元素的高階說明。

子元素是否必要說明

子元素	是否必要	說明
`<URL>`	必填	字串用於執行相似度搜尋的網址。系統只會使用與相似度門檻最相符的資料點。
`<Threshold>`	選用	字串相似度分數，用於判斷兩個提示是否視為相符。介於 0 到 1 的值。預設值為 0.9。
`<DeployedIndexID>`	必填	字串部署在索引端點的索引 ID，用於語意快取。

<URL>

必填

字串

用於執行相似度搜尋的網址。系統只會使用與相似度門檻最相符的資料點。

<Threshold>

選用

字串

相似度分數，用於判斷兩個提示是否視為相符。介於 0 到 1 的值。

預設值為 0.9。

<DeployedIndexID>

必填

字串

部署在索引端點的索引 ID，用於語意快取。

流程變數

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

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

變數名稱	說明
`request.content`	包含傳入 API 要求的完整內容。
`request.url`	包含傳入 API 要求的網址。
`semanticcache.lookup.policy_name.user_prompt`	包含從要求提示擷取的特定元件，用於產生嵌入或執行相似度搜尋。
`semanticcache.lookup.policy_name.embeddings_request`	包含傳送至 Vertex AI Embeddings API 的要求酬載，用於為輸入文字生成文字嵌入。
`semanticcache.lookup.policy_name.embeddings_response`	包含 Vertex AI Embeddings API 的回應，包括生成的文字嵌入。
`semanticcache.lookup.policy_name.dense_embeddings`	包含 Vertex AI Embeddings API 產生的實際數值嵌入值。
`semanticcache.lookup.policy_name.is_nearest_neighbor_hit`	指定是否在向量資料庫中找到指定要求的最鄰近項目，以及資料點是否符合相似度門檻。
`semanticcache.lookup.policy_name.cache_hit`	指定是否在語意快取中找到回應。
`semanticcache.lookup.policy_name.cached_llm_response`	包含從語意快取擷取的回應 (如果發生快取命中)。

錯誤參考資料

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

執行階段錯誤

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

錯誤碼	HTTP 狀態	原因
`steps.semanticcache.lookup.MessageTemplateExtractionFailed`	`400`	無法使用 JSON 路徑運算式從要求中擷取資料。
`steps.semanticcache.lookup.FailedToExtractUserPrompt`	`500`	無法從 API 要求中擷取使用者提示。
`steps.semanticcache.lookup.EmbeddingsServiceUnavailable`	`400`	目前無法使用 Vertex AI Embeddings 服務。
`steps.semanticcache.lookup.EmbeddingsAPIFailed`	`400`	Vertex AI Embeddings 服務失敗。
`steps.semanticcache.lookup.VectorSearchServiceUnavailable`	`400`	Vertex AI Vector Search 服務目前無法使用。
`steps.semanticcache.lookup.VectorSearchAPIFailed`	`400`	Vertex AI Vector Search 服務失敗。
`steps.semanticcache.lookup.AuthenticationFailure`	`500`	服務帳戶沒有必要權限。
`steps.semanticcache.lookup.InternalError`	`500`	SemanticCacheLookup 政策發生未預期的錯誤。
`steps.semanticcache.lookup.CalloutError`	`500`	Vertex AI 服務呼叫失敗。

部署錯誤

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

錯誤名稱	原因
`The Embeddings/VertexAI element is required.`	如果 <Embeddings> 中的 <VertexAI> 元素為空，就會發生這種情況。
`The SimilaritySearch/VertexAI element is required.`	如果 <SimilaritySearch> 中的 <VertexAI> 元素為空白，就會發生這種情況。
`The Embeddings/URL element is required.`	如果 <Embeddings> 中的 <URL> 元素為空，就會發生這種情況。
`The SimilaritySearch/URL element is required.`	如果 <SimilaritySearch> 中的 <URL> 元素為空白，就會發生這個錯誤。
`Embeddings URL {url} is invalid.`	如果 <Embeddings> 中的 <URL> 元素為空或無效，就會發生這個錯誤。
`The SimilaritySearch URL {url} is invalid.`	如果 <SimilaritySearch> 中的 <URL> 元素空白或無效，就會發生這個錯誤。
`The scheme {http-scheme} of Embeddings URL {url} must be one of http, https.`	如果 Embeddings <URL> 元素的 `http` 配置無效，就會發生這種情況。
`The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https.`	如果 SimilaritySearch <URL> 元素的 `http` 配置無效，就會發生這種情況。
`SimilaritySearch/Threshold element must be >= 0 and <= 1.`	如果屬性不在 0 到 1 之間，API Proxy 的部署作業就會失敗。
`SimilaritySearch/DeployedIndexID element is required.`	如果 <SimilaritySearch> 中的 <DeployedIndexID> 元素為空白，就會發生這種情況。
`SimilaritySearch/DeployedIndexID element must not contain spaces.`	如果 <SimilaritySearch> 中的 <DeployedIndexID> 元素含有空格，就會發生這個錯誤。

錯誤變數

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

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

錯誤回應範例

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

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

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

總覽

事前準備

必要的角色

啟用 API

<SemanticCacheLookup> 元素

語法

預設政策

子元素參照

<DisplayName>

語法

範例

<IgnoreUnresolvedVariables>

<UserPromptSource>

<Embeddings>

<VertexAI> (<Embeddings> 的子項)

<URL> (<VertexAI> 的子項)

<SimilaritySearch>

<VertexAI> (<SimilaritySearch> 的子項)

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

SemanticCacheLookup 政策

`<SemanticCacheLookup>` 元素

`<DisplayName>`

`<UserPromptSource>`

`<Embeddings>`

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

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

`<SimilaritySearch>`

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