このページは Apigee と Apigee ハイブリッドに適用されます。
Apigee Edge のドキュメントを表示する。
概要
SemanticCacheLookup ポリシーは、AI ワークロード（特に大規模言語モデル（LLM）を含むワークロード）のパフォーマンスを最適化するように設計された高度なキャッシュ ポリシーです。
このポリシーは、テキストのエンベディングを生成するために Vertex AI の Text Embeddings API を使用し、文字の完全一致ではなく意味的な類似性に基づいてプロンプトを見つけるためにベクトル検索を使用します。
SemanticCacheLookup ポリシーを使用すると、LLM への呼び出し回数を減らして、繰り返しクエリのレスポンス時間を短縮し、費用を最適化できます。
このポリシーは、SemanticCachePopulate ポリシーと組み合わせて使用します。
このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。
始める前に
SemanticCacheLookup ポリシーを使用する前に、次のタスクを完了します。
- Vertex AI プロジェクトを作成する。
- ベクトル検索インデックスを作成する
- インデックスの Vertex AI エンドポイントを作成する。
- SemanticCachePopulate ポリシーを作成する。
これらのタスクの詳細については、セマンティック キャッシュ保存ポリシーを使ってみるをご覧ください。
必要なロール
SemanticCacheLookup ポリシーを適用して使用するために必要な権限を取得するには、Apigee プロキシのデプロイに使用するサービス アカウントに対する AI Platform ユーザー（roles/aiplatform.user）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。
必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
API を有効にする
Enable the Compute Engine, Vertex AI, and Cloud Storage APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM
role (roles/serviceusage.serviceUsageAdmin), which
contains the serviceusage.services.enable permission. Learn how to grant
roles.
<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 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> </VertexAI> </SimilaritySearch> </SemanticCacheLookup>
Apigee UI を使って新しい SemanticCacheLookup ポリシーを挿入すると、テンプレートには使用可能なすべてのオペレーションに対応するスタブが組み込まれます。必須要素の詳細については、下記をご覧ください。
この要素には、すべてのポリシーに共通する次の属性があります。
| 属性 | デフォルト | 必須かどうか | 説明 |
|---|---|---|---|
name |
なし | 必須 |
ポリシーの内部名。 管理 UI プロキシ エディタで |
continueOnError |
false | 省略可 | ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報:
|
enabled |
true | 省略可 | ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。 |
async |
false | 非推奨 | この属性は非推奨となりました。 |
次の表は、<SemanticCacheLookup> の子要素の概要をまとめたものです。
| 子要素 | 必須かどうか | 説明 |
|---|---|---|
<DisplayName> |
省略可 | ポリシーの名前。 |
<IgnoreUnresolvedVariables> |
省略可 | 変数が解決されない場合に処理を停止するかどうかを決定します。
true を設定すると、未解決の変数を無視して処理を続行できます。 |
<UserPromptSource> |
省略可 | ユーザー プロンプト テキストを抽出するペイロードの場所。文字列テキスト値のみがサポートされています。
このフィールドは、変数や JSON Path 関数の使用など、Apigee メッセージ テンプレートの構文をサポートしています。 次に例を示します。 {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 は適用されません。
| デフォルト値 | False |
| 必須かどうか | 省略可 |
| 型 | ブール値 |
| 親要素 |
<SemanticCacheLookup>
|
| 子要素 | なし |
<UserPromptSource>
ユーザー プロンプト テキストを抽出するペイロードの場所。文字列テキスト値のみがサポートされています。
このフィールドは、変数や JSON Path 関数の使用など、Apigee メッセージ テンプレートの構文をサポートしています。
次に例を示します。
{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> の子）
テキスト エンベディングの生成に使用される URL。SemanticCacheLookup ポリシーのテキスト エンベディングを提供できるモデルの一覧については、サポートされているモデルをご覧ください。
| デフォルト値 | なし |
| 必須かどうか | 必須 |
| 型 | 文字列 |
| 親要素 |
<VertexAI>
|
| 子要素 | なし |
URL 要素の構文は次のとおりです。
<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>URL 要素は、URL テンプレートの使用をサポートしています。必要に応じて、次の例に示すように、この要素に URL の値を保持する変数を指定します。
<URL>https://{URL_VARIABLE}</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> |
必須 | 文字列 類似検索の実行に使用される URL。類似性しきい値に基づいて、最も一致率の高いデータポイントのみが使用されます。
<URL>https://{URL_VARIABLE}</URL> |
<Threshold> |
省略可 | 文字列 2 つのプロンプトが一致と見なされるかどうかを判断するために使用される類似性スコア。0～1 の値。 デフォルト値は 0.9 です。 詳しくは、 |
<DeployedIndexID> |
必須 | 文字列 セマンティック キャッシュに使用されるインデックス エンドポイントにデプロイされたインデックスの ID。 |
フロー変数
フロー変数を使用すると、HTTP ヘッダー コンテンツ、メッセージ コンテンツ、またはフローのコンテキストに基づいて、ポリシーとフローが実行時に動的に動作するよう構成できます。フロー変数の詳細については、フロー変数のリファレンスをご覧ください。
このポリシーは、実行時に次の読み取り専用フロー変数のセットを提供します。これらのフロー変数と DataCapture ポリシーを使用して、カスタム分析レポートを作成できます。詳細については、DataCapture ポリシーを使用した顧客データの収集をご覧ください。
| 変数名 | 説明 |
|---|---|
request.content |
受信した API リクエストの完全な内容が含まれます。 |
request.url |
受信した API リクエストの URL が含まれます。 |
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 |
セマンティック キャッシュから取得されたレスポンス（キャッシュ ヒットが発生した場合）が含まれます。 |
エラー リファレンス
このセクションでは、<SemanticCacheLookup> ポリシーに固有の Apigee によって返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処するための障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
| 障害コード | HTTP ステータス | 原因 |
|---|---|---|
steps.semanticcache.lookup.MessageTemplateExtractionFailed |
400 |
JSON Path 式を使ってリクエストからデータを抽出することができなかった。 |
steps.semanticcache.lookup.FailedToExtractUserPrompt |
500 |
API リクエストからユーザー プロンプトを抽出できなかった。 |
steps.semanticcache.lookup.EmbeddingsServiceUnavailable |
400 |
Vertex AI Embeddings サービスが現在利用できない。 |
steps.semanticcache.lookup.EmbeddingsAPIFailed |
400 |
Vertex AI エンベディング サービスでエラーが発生した。 |
steps.semanticcache.lookup.VectorSearchServiceUnavailable |
400 |
Vertex AI Vector Search サービスが現在利用できない。 |
steps.semanticcache.lookup.VectorSearchAPIFailed |
400 |
Vertex AI ベクトル検索サービスで障害が発生した。 |
steps.semanticcache.lookup.AuthenticationFailure |
500 |
サービス アカウントに必要な権限がない。 |
steps.semanticcache.lookup.InternalError |
500 |
SemanticCacheLookup ポリシー内で予期しないエラーが発生した。 |
steps.semanticcache.lookup.CalloutError |
500 |
Vertex AI サービスの呼び出しに失敗した。 |
デプロイエラー
以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。
| エラー名 | 原因 |
|---|---|
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. |
エンベディング <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 プロキシのデプロイは失敗する。 |
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 |
エラー レスポンスの例
{ "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 から入手できます。