本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
SemanticCacheLookup 政策是進階快取政策,旨在最佳化 AI 工作負載的效能,尤其是涉及大型語言模型 (LLM) 的工作負載。
這項政策會使用 Vertex AI Text Embeddings API 生成文字嵌入,並透過向量搜尋,根據語意相似度 (而非完全比對) 找出類似提示詞。
SemanticCacheLookup 政策可減少對 LLM 的呼叫量,進而縮短重複查詢的回應時間,並降低成本。
這項政策會與 SemanticCachePopulate 政策搭配使用。
這項政策屬於可擴充政策,使用這項政策可能會產生費用或影響使用率,具體取決於您的 Apigee 授權。如要瞭解政策類型和使用影響,請參閱「政策類型」。
事前準備
使用 SemanticCacheLookup 政策前,請先完成下列工作:
- 建立 Vertex AI 專案。
- 建立向量搜尋索引。
- 為索引建立 Vertex AI 端點。
- 建立 SemanticCachePopulate 政策。
如要進一步瞭解如何完成這些工作,請參閱「開始使用語意快取政策」。
必要的角色
如要取得套用及使用 SemanticCacheLookup 政策所需的權限,請要求管理員針對您用於部署 Apigee Proxy 的服務帳戶,授予AI 平台使用者 (roles/aiplatform.user) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
啟用 API
啟用 Compute Engine、Vertex AI 和 Cloud Storage API (如果尚未啟用)。
啟用 API 時所需的角色
如要啟用 API,您必須具備 serviceusage.services.enable 權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
<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> <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType> </VertexAI> </SimilaritySearch> </SemanticCacheLookup>
預設政策
以下範例顯示在 Apigee UI 中,將 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> <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType> </VertexAI> </SimilaritySearch> </SemanticCacheLookup>
在 Apigee UI 中插入新的 SemanticCacheLookup 政策時,範本會包含所有可能作業的存根。請參閱下文,瞭解必要元素。
這個元素包含下列所有政策都適用的屬性:
| 屬性 | 預設 | 是否必要? | 說明 |
|---|---|---|---|
name |
不適用 | 必要 |
政策的內部名稱。 您可以選擇使用 |
continueOnError |
false | 選用 | 將其設為 false,即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true,即使政策失敗,流程執行作業仍會繼續進行。另請參閱:
|
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 Path 函式。
例如:
{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><網址> (<VertexAI> 的子項)
用於生成文字嵌入的網址。如要查看為 SemanticCacheLookup 政策提供文字嵌入的模型清單,請參閱「 支援的模型」。
| 預設值 | 不適用 |
| 必填與否 | 必填 |
| 類型 | 字串 |
| 父項元素 |
<VertexAI>
|
| 子元素 |
無 |
URL 元素使用下列語法:
<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>URL 元素支援使用網址範本。如有需要,請在這個元素中提供變數,用於保存網址的值,如以下範例所示:
<URL>https://{URL_VARIABLE}</URL><SimilaritySearch>
這個元素包含執行相似度搜尋所需的資訊。
相似度搜尋可針對部署在公開端點或私人 (Private Service Connect) 端點的向量搜尋索引執行。您必須在 <VertexAI> 元素中提供一個傳輸方式:
<URL>:如果是公開端點,則透過 REST (:findNeighbors)。<PrivateServiceConnect>:透過 gRPC 傳送至私人端點。私有 (Private Service Connect) 已部署的索引端點只接受 gRPC。
詳情請參閱「查詢公開索引以取得最鄰近項目」和「使用私人 (Private Service Connect) 端點進行語意快取」。
| 預設值 | 不適用 |
| 必填與否 | 必填 |
| 類型 | 字串 |
| 父項元素 |
<SemanticCacheLookup>
|
| 子元素 |
<VertexAI> |
<SimilaritySearch> 元素使用下列語法。
公開端點 (REST):
<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> <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType> </VertexAI> </SimilaritySearch>
私人端點 (Private Service Connect、gRPC):
<SimilaritySearch>
<VertexAI>
<PrivateServiceConnect>
<GrpcEndpoint>grpc://{TARGET_HOST}:10000</GrpcEndpoint>
</PrivateServiceConnect>
<Threshold>0.9</Threshold>
<DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>
</SimilaritySearch><VertexAI> (<SimilaritySearch> 的子項)
包含用於執行相似度搜尋的 Vertex AI 專屬屬性。請提供下列其中一種傳輸方式:<URL> 元素 (適用於透過 REST 的公開端點) 或 <PrivateServiceConnect> 元素 (適用於透過 gRPC 的私人端點)。
| 預設值 | 不適用 |
| 必填與否 | 必填 |
| 類型 | 字串 |
| 父項元素 |
<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> <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType> </VertexAI>
如果是私人 (Private Service Connect) 端點,VertexAI 元素會使用下列語法:
<VertexAI>
<PrivateServiceConnect>
<GrpcEndpoint>grpc://{TARGET_HOST}:10000</GrpcEndpoint>
</PrivateServiceConnect>
<Threshold>0.9</Threshold>
<DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>下表概略說明 <VertexAI> 的子元素。
| 子元素 | 是否必要 | 說明 |
|---|---|---|
<URL> |
必要 (提供 <URL> 或 <PrivateServiceConnect>) |
字串 用於對公開向量搜尋索引端點執行相似度搜尋的網址 (透過 REST (
<URL>https://{URL_VARIABLE}</URL> |
<PrivateServiceConnect> |
必要 (提供 <URL> 或 <PrivateServiceConnect>) |
複雜物件 包含連線資訊,用於對部署在 Private Service Connect 端點的私人向量搜尋索引執行相似度搜尋。私人已部署索引端點僅接受 gRPC。 這個元素包含單一子元素 <PrivateServiceConnect>
<GrpcEndpoint>grpc://{TARGET_HOST}:10000</GrpcEndpoint>
</PrivateServiceConnect>
|
<Threshold> |
選用 | 字串 最接近的鄰點必須達到的值,才能視為相符。
預設值為 0.9,適用於 請參閱「選擇距離測量門檻」。 |
<DeployedIndexID> |
必填 | 字串 部署在索引端點的索引 ID,用於語意快取。 |
<DistanceMeasureType> |
選用 | 字串 建立 Vertex AI 向量搜尋索引時使用的距離測量方式。這會設定 有效值為 預設值為 請參閱「選擇距離測量的門檻」。 |
選擇距離測量的門檻
建立索引時使用的指標會決定 <Threshold> 比較的方向:點積是相似度,因此值越大表示越接近,而其他三個是距離,值越小表示越接近。將 <DistanceMeasureType> 設為與索引相符,然後調整該指標的門檻。
| 距離度量 | 快取門檻 |
|---|---|
DOT_PRODUCT_DISTANCE (預設) |
value >= threshold |
COSINE_DISTANCE |
value <= threshold |
SQUARED_L2_DISTANCE |
value <= threshold |
L1_DISTANCE |
value <= threshold |
如要找出建立索引時使用的測量指標,請執行 gcloud ai indexes describe INDEX_ID --region=REGION 並查看 distanceMeasureType 欄位。如要確認政策是否已套用,請傳送相同要求兩次,並在偵錯工作階段中檢查 semanticcache.lookup.policy_name.measure_type 和 semanticcache.lookup.policy_name.nearest_neighbor_measure。
流程變數
流程變數會根據 HTTP 標頭或訊息內容,或流程中可用的內容,設定政策和流程的動態執行階段行為。如要進一步瞭解流程變數,請參閱「流程變數參考資料」。
這項政策會在執行期間提供下列一組唯讀流程變數。您可以搭配使用這些流程變數和 DataCapture 政策,建立自訂數據分析報表。詳情請參閱「透過『資料收集』政策收集顧客數位資料」。
| 變數名稱 | 說明 |
|---|---|
request.content |
包含傳入 API 要求的完整內容。 |
request.url |
包含傳入 API 要求的網址。 |
SemanticCacheLookup.policy_name.user_prompt |
包含從要求提示擷取的特定元件,用於產生嵌入或執行相似度搜尋。 |
SemanticCacheLookup.policy_name.embeddings_request |
包含傳送至 Vertex AI Embeddings API 的要求酬載,用於為輸入文字生成文字嵌入。 |
SemanticCacheLookup.policy_name.embeddings_response |
包含 Vertex AI Embeddings API 的回應,其中含有生成的文字嵌入。 |
SemanticCacheLookup.policy_name.dense_embeddings |
包含 Vertex AI Embeddings API 生成的實際數值嵌入值。 |
SemanticCacheLookup.policy_name.is_nearest_neighbor_hit |
指定是否在向量資料庫中找到指定要求的最鄰近項目,以及資料點是否符合類似程度門檻。 |
SemanticCacheLookup.policy_name.cache_hit |
指出是否在語意快取中找到回覆。 |
SemanticCacheLookup.policy_name.cached_llm_response |
包含從語意快取擷取的回應 (如果發生快取命中)。 |
semanticcache.lookup.policy_name.nearest_neighbor_measure |
包含 Vector Search 索引為最鄰近項目傳回的原始值。只要傳回鄰近項目,無論命中或未命中,都會設定這個值。 |
semanticcache.lookup.policy_name.measure_type |
包含政策套用的距離測量值,包括回復為預設值時。只要傳回鄰近項目,無論是否命中,都會設定這個值。 |
錯誤參考資料
本節說明 Apigee 傳回的錯誤代碼和錯誤訊息,以及 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 向量搜尋服務。 |
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> 元素為空白,就會發生這個錯誤。 |
Embeddings/VertexAI cannot have both URL and PrivateServiceConnect elements. |
如果同時指定 <Embeddings> 中的 <URL> 和 <PrivateServiceConnect> 元素,就會發生這個錯誤。 |
SimilaritySearch/VertexAI cannot have both URL and PrivateServiceConnect elements. |
如果指定 <SimilaritySearch> 中的 <URL> 和 <PrivateServiceConnect> 元素,就會發生這個錯誤。 |
Embeddings/VertexAI/URL or Embeddings/PrivateServiceConnect/GrpcEndpoint element is required. |
如果未指定 <Embeddings> 中的 <URL> 元素或 <GrpcEndpoint> 元素,就會發生這種情況。 |
SimilaritySearch/VertexAI/URL or SimilaritySearch/PrivateServiceConnect/GrpcEndpoint element is required. |
如果未指定 <SimilaritySearch> 中的 <URL> 元素或 <GrpcEndpoint> 元素,就會發生這種情況。 |
The Embeddings/VertexAI/PrivateServiceConnect element is not supported. Use URL instead. |
在 <Embeddings> 中使用 <PrivateServiceConnect> 元素時,會發生這個錯誤。 |
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 配置無效,就會發生這種情況。 |
The SimilaritySearch /VertexAI/PrivateServiceConnect/GrpcEndpoint {grpc-endpoint} must be in the format "grpc://TARGET_HOST:PORT". |
<SimilaritySearch> 中的 <GrpcEndpoint> 元素格式不符合 grpc://TARGET_HOST:PORT 時,就會發生這種情況。 |
The scheme {grpc-scheme} of SimilaritySearch /VertexAI/PrivateServiceConnect/GrpcEndpoint {grpc-endpoint} must be "grpc". |
如果 SimilaritySearch <GrpcEndpoint> 元素的 grpc 配置無效,就會發生這種情況。 |
SimilaritySearch/Threshold element must not be NaN. |
如果 <SimilaritySearch> 中的 <Threshold> 元素為 NaN,就會發生這種情況。可使用 Infinity 和 -Infinity。 |
Invalid DistanceMeasureType {value}. Supported values are DOT_PRODUCT_DISTANCE,
COSINE_DISTANCE, SQUARED_L2_DISTANCE and L1_DISTANCE |
如果 <SimilaritySearch> 中的 <DistanceMeasureType> 元素不是四個支援的值之一,就會發生這個錯誤。比對類型為完全比對。請參閱「索引設定參數」。 |
SimilaritySearch/DeployedIndexID element is required. |
<SimilaritySearch> 中的 <DeployedIndexID> 元素空白時,就會發生這種情況。 |
SimilaritySearch/DeployedIndexID element must not contain spaces. |
如果 <SimilaritySearch> 中的 <DeployedIndexID> 元素含有空格,就會發生這個錯誤。 |
故障變數
這項政策會在執行階段觸發錯誤時設定這些變數。詳情請參閱「政策錯誤須知」。
錯誤回應範例
{ "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 查看政策架構。