このページは Apigee と Apigee ハイブリッドに適用されます。
Apigee Edge のドキュメントを表示する。
概要
SemanticCachePopulate ポリシーは、AI ワークロード（特に大規模言語モデル（LLM）を含むワークロード）のパフォーマンスを最適化するように設計された高度なキャッシュ ポリシーです。
このポリシーは、Vertex AI の Text embeddings API を使用してテキストのエンベディングを生成し、ベクトル検索を使用して、完全一致ではなくセマンティックな類似性に基づいて API レスポンスをキャッシュに保存します。
SemanticCachePopulate ポリシーを使用すると、LLM への呼び出し回数を減らして、繰り返しクエリのレスポンス時間を短縮し、費用を最適化できます。
このポリシーは、SemanticCacheLookup ポリシーと組み合わせて使用します。
このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。
始める前に
SemanticCachePopulate ポリシーを使用する前に、次のタスクを完了します。
- Vertex AI プロジェクトを作成する。
- ベクトル検索インデックスを作成する
- インデックスの Vertex AI エンドポイントを作成する。
- SemanticCachePopulate ポリシーを作成する。
これらのタスクの詳細については、セマンティック キャッシュ保存ポリシーを使ってみるをご覧ください。
ロールと権限
SemanticCachePopulate ポリシーを適用して使用するために必要な権限を取得するには、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.
<SemanticCachePopulate> 要素
SemanticCachePopulate ポリシーを定義します。
| デフォルト値 | 下記の [デフォルト ポリシー] タブをご覧ください。 |
| 必須かどうか | 必須 |
| 型 | 複合オブジェクト |
| 親要素 | なし |
| 子要素 |
<DisplayName><IgnoreUnresolvedVariables><SimilaritySearch><TTLInSeconds> |
<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>デフォルト ポリシー
次の例は、Apigee UI で API プロキシに 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 ポリシーを Apigee UI に挿入すると、テンプレートには使用可能なオペレーションすべてのスタブが含まれます。必須要素の詳細については、下記をご覧ください。
この要素には、すべてのポリシーに共通する次の属性があります。
| 属性 | デフォルト | 必須かどうか | 説明 |
|---|---|---|---|
name |
なし | 必須 |
ポリシーの内部名。 管理 UI プロキシ エディタで |
continueOnError |
false | 省略可 | ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報:
|
enabled |
true | 省略可 | ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。 |
async |
false | 非推奨 | この属性は非推奨となりました。 |
次の表は、<SemanticCachePopulate> の子要素の概要をまとめたものです。
| 子要素 | 必須かどうか | 説明 |
|---|---|---|
<DisplayName> |
省略可 | ポリシーの名前。 |
<IgnoreUnresolvedVariables> |
省略可 | プロパティ セットが解決されない場合に処理を停止するかどうかを決定します。 |
<SimilaritySearch> |
必須 | ベクトル インデックスの更新に必要な情報を含む要素。 詳細については、データポイントのアップサートをご覧ください。 データポイントの有効期限は、入力時から <TTLInSeconds> です。 |
<TTLInSeconds> |
省略可 | キャッシュに保存されたレスポンスを保持する有効期間（TTL）（秒単位）。 デフォルト値は |
例
このセクションでは、<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> を省略した場合、ポリシーの name 属性の値が使用されます。 |
| 型 | 文字列 |
| 親要素 | <PolicyElement> |
| 子要素 | なし |
<DisplayName> 要素の構文は次のとおりです。
構文
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
例
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
<DisplayName> 要素に属性や子要素はありません。
<IgnoreUnresolvedVariables>
変数が解決されない場合に処理を停止するかどうかを決定します。true を設定すると、未解決の変数を無視して処理を続行できます。
<DefaultValue> が指定されている場合、IgnoreUnresolvedVariables は適用されません。
| デフォルト値 | False |
| 必須かどうか | 省略可 |
| 型 | ブール値 |
| 親要素 |
<SemanticCachePopulate>
|
| 子要素 | なし |
<SimilaritySearch>
ベクトル インデックスの更新に必要な情報が含まれる要素。
詳細については、データポイントのアップサートをご覧ください。
データポイントの有効期限は、入力時から <TTLInSeconds> です。
| デフォルト値 | なし |
| 必須かどうか | 必須 |
| 型 | 文字列 |
| 親要素 |
<SemanticCachePopulate>
|
| 子要素 |
<VertexAI> |
<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> 要素が含まれています。
| デフォルト値 | なし |
| 必須かどうか | 必須 |
| 型 | 文字列 |
| 親要素 |
<SimilaritySearch>
|
| 子要素 |
<URL> |
VertexAI 要素の構文は次のとおりです。
<VertexAI>
<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI><URL>（<VertexAI> の子）
ベクトル インデックスにデータポイントをアップサートするために使用される URL。
| デフォルト値 | なし |
| 必須かどうか | 必須 |
| 型 | 文字列 |
| 親要素 |
<VertexAI>
|
| 子要素 | なし |
URL 要素の構文は次のとおりです。
<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>URL 要素は、URL テンプレートの使用をサポートしています。次の例を参照し、必要に応じて、この要素に URL の値を保持する変数を指定します。
<URL>https://{URL_VARIABLE}</URL><TTLInSeconds>
キャッシュに保存されたレスポンスを保持する有効期間（TTL）を秒単位で指定する要素。デフォルト値は 60 です。
詳細については、アクティブ インデックスの更新と再ビルドをご覧ください。
| デフォルト値 | なし |
| 必須かどうか | 省略可 |
| 型 | 文字列 |
| 親要素 |
<SemanticCachePopulate>
|
| 子要素 | なし |
フロー変数
フロー変数を使用すると、HTTP ヘッダー コンテンツ、メッセージ コンテンツ、またはフローのコンテキストに基づいて、ポリシーとフローが実行時に動的に動作するよう構成できます。フロー変数の詳細については、フロー変数のリファレンスをご覧ください。
このポリシーは、実行時に次の読み取り専用フロー変数のセットを提供します。これらのフロー変数と DataCapture ポリシーを使用して、カスタム分析レポートを作成できます。詳細については、DataCapture ポリシーを使用した顧客データの収集をご覧ください。
| 変数名 | 説明 |
|---|---|
response.content |
API レスポンスの完全な内容が含まれます。 |
semanticcache.populate.policy_name.upsert_index_request |
Vertex AI Vector Search API に送信され、新しいエンベディングとメタデータを使用してベクトル インデックスを更新するリクエスト ペイロードが含まれます。 |
semanticcache.populate.policy_name.upsert_index_response |
インデックス更新オペレーションの成功または失敗を示す Vertex AI Vector Search API からのレスポンスが含まれます。 |
エラー リファレンス
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードおよびエラー メッセージと、<SemanticCachePopulate> ポリシーに固有の Apigee によって設定される障害変数について説明します。これは、障害に対処するための障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
| 障害コード | HTTP ステータス | 原因 |
|---|---|---|
steps.semanticcachepopulate.VectorSearchUpsertServiceUnavailable
|
400 |
このエラーは、Vector Search Upsert Datapoints API が使用できない場合に発生します。 |
steps.semanticcache.populate.VectorSearchUpsertAPIFailed |
500 |
このエラーは、Vector Search Upsert Datapoints API サービスが失敗した場合に発生します。 |
steps.semanticcache.populate.AuthenticationFailure |
500 |
このエラーは、サービス アカウントに必要な権限がない場合に発生します。 |
steps.semanticcache.populate.CalloutError |
500 |
Vertex AI サービスの呼び出しに失敗しました。 |
steps.semanticcache.populate.InternalError |
500 |
このエラーは、 |
デプロイエラー
以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。
| エラー名 | 原因 |
|---|---|
The SimilaritySearch URL {url} is invalid. |
<SimilaritySearch> の <URL> 要素が空であるか無効な場合に発生します。 |
The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https. |
SimilaritySearch <URL> 要素の http スキームが無効な場合に発生する。 |
The TTLInSeconds element must be >= 0. |
値がゼロまたは負の数に設定されている場合、API プロキシのデプロイは失敗します。 |
障害変数
次の変数は、このポリシーでランタイム エラーが発生したときに設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。
| 変数 | 説明 | 例 |
|---|---|---|
fault.name="FAULT_NAME" |
FAULT_NAME は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 | fault.name Matches "UnresolvedVariable" |
semanticcachepopulate.POLICY_NAME.failed |
POLICY_NAME は、障害をスローしたポリシーのユーザー指定の名前です。 | semanticcachepopulate.SC-populate.failed = true |
エラー レスポンスの例
{ "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 から入手できます。