SemanticCachePopulate ポリシー

概要

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.

Enable the APIs

<SemanticCachePopulate> 要素

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>

<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> の子要素の概要をまとめたものです。

例

このセクションでは、<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> 要素の構文は次のとおりです。

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

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

<DisplayName> 要素に属性や子要素はありません。

<IgnoreUnresolvedVariables>

変数が解決されない場合に処理を停止するかどうかを決定します。true を設定すると、未解決の変数を無視して処理を続行できます。

<DefaultValue> が指定されている場合、IgnoreUnresolvedVariables は適用されません。

<SimilaritySearch>

ベクトル インデックスの更新に必要な情報が含まれる要素。

詳細については、データポイントのアップサートをご覧ください。

データポイントの有効期限は、入力時から <TTLInSeconds> です。

<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> 要素が含まれています。

VertexAI 要素の構文は次のとおりです。

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

<URL>（<VertexAI> の子）

ベクトル インデックスにデータポイントをアップサートするために使用される URL。

URL 要素の構文は次のとおりです。

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>

<TTLInSeconds>

キャッシュに保存されたレスポンスを保持する有効期間（TTL）を秒単位で指定する要素。デフォルト値は 60 です。

詳細については、アクティブ インデックスの更新と再ビルドをご覧ください。

フロー変数

フロー変数を使用すると、HTTP ヘッダー コンテンツ、メッセージ コンテンツ、またはフローのコンテキストに基づいて、ポリシーとフローが実行時に動的に動作するよう構成できます。フロー変数の詳細については、フロー変数のリファレンスをご覧ください。

ポリシーは実行時にこれらの読み取り専用変数を設定できます。

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードおよびエラー メッセージと、<SemanticCachePopulate> ポリシーに固有の Apigee によって設定される障害変数について説明します。これは、障害に対処するための障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

障害変数

次の変数は、このポリシーでランタイム エラーが発生したときに設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

エラー レスポンスの例

{
"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 から入手できます。