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 ポリシーを定義します。

デフォルト値	下記の [デフォルトポリシー] タブをご覧ください。
必須かどうか	必須
型	複合オブジェクト
親要素	なし
子要素	`<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 に挿入すると、テンプレートには使用可能なオペレーションすべてのスタブが含まれます。必須要素の詳細については、下記をご覧ください。

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
`name`	N/A	Required	The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name.
`continueOnError`	false	Optional	Set to `false` to return an error when a policy fails. This is expected behavior for most policies. Set to `true` to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
`enabled`	true	Optional	Set to `true` to enforce the policy. Set to `false` to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
`async`	false	Deprecated	This attribute is deprecated.

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

子要素	必須かどうか	説明
`<DisplayName>`	省略可	ポリシーの名前。
`<IgnoreUnresolvedVariables>`	省略可	プロパティセットが解決されない場合に処理を停止するかどうかを決定します。
`<SimilaritySearch>`	必須	ベクトルインデックスの更新に必要な情報を含む要素。詳細については、データポイントのアップサートをご覧ください。データポイントの有効期限は、入力時から <TTLInSeconds> です。
`<TTLInSeconds>`	省略可	キャッシュに保存されたレスポンスを保持する有効期間（TTL）（秒単位）。デフォルト値は `60` です。

例

このセクションでは、<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>

`<TTLInSeconds>`

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

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

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	`<SemanticCachePopulate>`
子要素	なし

フロー変数

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

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

変数名	説明
`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`	このエラーは、`<SemanticCachePopulate>` ポリシー内で予期しないエラーが発生した場合に発生します。

デプロイエラー

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

エラー名	原因
`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`

エラーレスポンスの例

注: ベストプラクティスとして、エラー処理でエラーレスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。

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

SemanticCachePopulate ポリシー コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要

始める前に

ロールと権限

API を有効にする

<SemanticCachePopulate> 要素

構文

デフォルト ポリシー

例

子要素のリファレンス

<DisplayName>

構文

例

<IgnoreUnresolvedVariables>

<SimilaritySearch>

<VertexAI>（<SimilaritySearch> の子）

<URL>（<VertexAI> の子）

<TTLInSeconds>

フロー変数

エラー リファレンス

ランタイム エラー

デプロイエラー

障害変数

エラー レスポンスの例

障害ルールの例

スキーマ

SemanticCachePopulate ポリシー

`<SemanticCachePopulate>` 要素

デフォルトポリシー

`<DisplayName>`

`<IgnoreUnresolvedVariables>`

`<SimilaritySearch>`

<VertexAI>（`<SimilaritySearch>` の子）

<URL>（`<VertexAI>` の子）

`<TTLInSeconds>`

エラーリファレンス

ランタイムエラー

エラーレスポンスの例