SemanticCacheLookup ポリシー

このページは 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.

Enable the APIs

<SemanticCacheLookup> 要素

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>

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

この要素には、すべてのポリシーに共通する次の属性があります。

次の表は、<SemanticCacheLookup> の子要素の概要をまとめたものです。

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

子要素のリファレンス

このセクションでは、<SemanticCacheLookup> の子要素について説明します。

<DisplayName>

name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の、より自然な響きの名前でラベル付けするために使います。

<DisplayName> 要素はすべてのポリシーに共通です。

<DisplayName> 要素の構文は次のとおりです。

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

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

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

<IgnoreUnresolvedVariables>

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

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

<UserPromptSource>

ユーザー プロンプト テキストを抽出するペイロードの場所。文字列テキスト値のみがサポートされています。

このフィールドは、変数や JSON Path 関数の使用など、Apigee メッセージ テンプレートの構文をサポートしています。

次に例を示します。

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

<Embeddings>

この要素には、テキスト エンベディングの生成に必要な情報が含まれています。

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

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 ポリシーのテキスト エンベディングを提供できるモデルの一覧については、サポートされているモデルをご覧ください。

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

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

<SimilaritySearch>

この要素には、類似検索の実行に必要な情報が含まれます。

詳細については、パブリック インデックスをクエリして最近傍を取得するをご覧ください。

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

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

フロー変数

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

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

エラー リファレンス

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

ランタイム エラー

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

デプロイエラー

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

障害変数

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

エラー レスポンスの例

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