セマンティックキャッシュ保存ポリシーを使ってみる

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する。

このページでは、セマンティック類似性に基づいてレスポンスをインテリジェントに再利用できるようにするための、Apigee セマンティックキャッシングポリシーの構成と使用方法について説明しています。これらのポリシーを Apigee の API プロキシで使用することで、バックエンドでの API 呼び出しの冗長性を最小限に抑え、レイテンシを減らし、運用コストを削減できます。

始める前に

次の作業を行ってから始めてください。

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Compute Engine, AI Platform, and Cloud Storage APIs.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Compute Engine, AI Platform, and Cloud Storage APIs.

Enable the APIs

Google Cloud プロジェクト内で Vertex AI の Text embeddings API と Vector Search を設定して構成します。
Apigee インスタンスで包括的な環境が利用可能であることを確認します。セマンティックキャッシュポリシーは、包括的な環境にのみデプロイできます。

必要なロール

セマンティックキャッシュポリシーの作成と使用に必要な権限を取得するには、Apigee プロキシのデプロイに使用するサービスアカウントに対する AI Platform ユーザー（roles/aiplatform.user）の IAM ロールを管理者に付与してもらってください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

環境変数を設定する

Apigee インスタンスを含む Google Cloud プロジェクトで、次のコマンドを使用して環境変数を設定します。

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

ここで

PROJECT_ID: Apigee インスタンスを含むプロジェクトの ID。
REGION は Apigee インスタンスの Google Cloud リージョンです。
RUNTIME_HOSTNAME は Apigee ランタイムのホスト名です。

環境変数が正しく設定されていることを確認するには、次のコマンドを実行して出力を確認します。

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

プロジェクトを設定する

開発環境で Google Cloud プロジェクトを設定します。

    gcloud auth login
    gcloud config set project $PROJECT_ID

概要

セマンティックキャッシュポリシーは、LLM モデルを使用する Apigee ユーザーが、同一または意味的に類似したプロンプトを効率的に提供し、バックエンド API 呼び出しを最小限に抑えてリソース消費を削減できるように設計されています。

SemanticCacheLookup ポリシーと SemanticCachePopulate ポリシーは、それぞれ Apigee API プロキシのリクエストフローとレスポンスフローにアタッチされています。プロキシがリクエストを受信すると、SemanticCacheLookup ポリシーはそのリクエストからユーザープロンプトを抽出し、Text embeddings API を使って数値表現に変換します。セマンティックな類似性検索は、ベクトル検索を使用して類似したプロンプトを見つけるために実行されます。類似したプロンプトデータポイントが見つかった場合は、キャッシュ検索が実行されます。キャッシュに保存されているデータが見つかった場合、キャッシュに保存されているレスポンスがクライアントに返されます。

類似性検索で過去の類似したプロンプトが返されなかった場合、LLM モデルはユーザープロンプトに対してコンテンツを生成し、Apigee キャッシュにレスポンスが入力されます。フィードバックループが作成され、今後のリクエストに備えてベクトル検索インデックスエントリが更新されます。

以降のセクションでは、セマンティックキャッシュポリシーを作成して構成するために必要な手順をご案内します。

ベクトル検索インデックス用のサービスアカウントを構成する。
ベクトル検索インデックスを作成してデプロイする。
API プロキシを作成してセマンティックキャッシュ保存を有効にする。
セマンティックキャッシュ保存ポリシーを構成する。
セマンティックキャッシュ保存ポリシーをテストする。

ベクトル検索インデックスのサービスアカウントを構成する

ベクトル検索インデックスのサービスアカウントを構成する手順は次のとおりです。

次のコマンドを使用してサービスアカウントを作成します。
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="SERVICE_ACCOUNT_DISPLAY_NAME"
```
ここで
- SERVICE_ACCOUNT_NAME はサービスアカウントの名前です。
- DESCRIPTION はサービスアカウントの説明です。
- SERVICE_ACCOUNT_DISPLAY_NAME はサービスアカウントの表示名です。
次に例を示します。
```
gcloud iam service-accounts create ai-client \
  --description="semantic cache client" \
  --display-name="ai-client"
```
次のコマンドを使用して、サービスアカウントに AI Platform User ロールを付与します。
```
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
```
ここで、SERVICE_ACCOUNT_NAME は前の手順で作成したサービスアカウントの名前です。
次のコマンドを使用して、IAM Service Account User ロールをサービスアカウントに割り当てます。
```
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"
```
ここで、SERVICE_ACCOUNT_NAME は前の手順で作成したサービスアカウントの名前です。

ベクトル検索インデックスを作成してデプロイする

ベクトル検索インデックスを作成してデプロイするには:

ストリーミングアップデートを許可するベクトル検索インデックスを作成します。

ACCESS_TOKEN=$(gcloud auth print-access-token) && curl --location --request POST \
  "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    --header 'Content-Type: application/json' \
    --data-raw \
    '{
      "displayName": "semantic-cache-index",
      "description": "semantic-cache-index",
      "metadata": {
        "config": {
          "dimensions": "768",
          "approximateNeighborsCount": 150,
          "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
          "featureNormType": "NONE",
          "algorithmConfig": {
            "treeAhConfig": {
              "leafNodeEmbeddingCount": "10000",
              "fractionLeafNodesToSearch": 0.05
              }
            },
          "shardSize": "SHARD_SIZE_MEDIUM"
          },
        },
      "indexUpdateMethod": "STREAM_UPDATE"
    }'

$REGION は、ベクトル検索インデックスがデプロイされるリージョンを定義します。Apigee インスタンスと同じリージョンを使用することをおすすめします。この環境変数は前の手順で設定したものです。

このオペレーションが完了すると、次のようなレスポンスが表示されます。

{
  "name": "projects/976063410430/locations/us-west1/indexes/5695338290484346880/operations/9084564741162008576",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexOperationMetadata",
    "genericMetadata": {
      "createTime": "2025-04-25T18:45:27.996136Z",
      "updateTime": "2025-04-25T18:45:27.996136Z"
    }
  }
}

ベクトル検索インデックスの作成の詳細については、インデックスを作成するをご覧ください。

次のコマンドを使用して IndexEndpoint を作成します。

gcloud ai index-endpoints create \
  --display-name=semantic-cache-index-endpoint \
  --public-endpoint-enabled \
  --region=$REGION \
  --project=$PROJECT_ID

このステップの完了までには数分かかることがあります。完了すると、次のようなレスポンスが表示されます。

Waiting for operation [8278420407862689792]...done.
  Created Vertex AI index endpoint: projects/976063410430/locations/us-west1/indexEndpoints/7953875911424606208.

IndexEndpoint の作成の詳細については、IndexEndpoint を作成するをご覧ください。

次のコマンドを使用して、エンドポイントにインデックスをデプロイします。

INDEX_ENDPOINT_ID=$(gcloud ai index-endpoints list \
  --project=$PROJECT_ID \
  --region=$REGION \
  --format="json" | jq -c -r \
  '.[] | select(.displayName=="semantic-cache-index-endpoint") | .name | split("/") | .[5]' \
  ) && INDEX_ID=$(gcloud ai indexes list \
  --project=$PROJECT_ID \
  --region=$REGION \
  --format="json" | jq -c -r \
  '.[] | select(.displayName=="semantic-cache-index") | .name | split("/") | .[5]' \
  ) && gcloud ai index-endpoints deploy-index \
  $INDEX_ENDPOINT_ID \
  --deployed-index-id=semantic_cache \
  --display-name=semantic-cache \
  --index=$INDEX_ID \
  --region=$REGION \
  --project=$PROJECT_ID

注: インデックスをエンドポイントにデプロイするコマンドには jq が必要です。この JSON 処理ユーティリティが開発環境にまだインストールされていない場合は、コマンド $ sudo apt install jq を使用してインストールできます。

インデックスを初めてエンドポイントにデプロイする際は、完了までに 20～30 分かかることがあります。オペレーションのステータスを確認するには、次のコマンドを使用します。

gcloud ai operations describe OPERATION_ID \
  --project=$PROJECT_ID \
  --region=$REGION

インデックスがデプロイされていることを確認します。

gcloud ai operations describe OPERATION_ID \
  --index-endpoint=$INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID

このコマンドは $ done: true を返すはずです。

API プロキシを作成してセマンティックキャッシュを有効にする

この手順では、Proxy with Semantic Cache テンプレートを使用して新しい API プロキシを作成します（まだ作成していない場合）。

API プロキシを作成する前に、次の環境変数を設定します。

export PUBLIC_DOMAIN_NAME=$(gcloud ai index-endpoints describe $INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID | grep "publicEndpointDomainName" | awk '{print $2}')

セマンティックキャッシュで使用するプロキシを作成するには:

Google Cloud コンソールの [API プロキシ] ページに移動します。
[API プロキシ] に移動
[+ 作成] をクリックして、[Create API proxy] ペインを開きます。
[Proxy template] ボックスで、[Proxy with Semantic Cache] を選択します。
次の詳細情報を入力します。
- Proxy name: プロキシの名前を入力します。
- Description: （省略可）プロキシの簡単な説明を入力します。
- Target (Existing API): プロキシが呼び出すバックエンドサービスの URL を入力します。これは、コンテンツの生成に使用される LLM モデルのエンドポイントです。
  このチュートリアルでは、[Target (Existing API)] を次のように設定できます。
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent
```
次の [Semantic Cache URLs] を入力します。
注: これらの URL は、[Develop] タブの [Proxy editor] で XML 構成に追加することもできます。
- Generate Embeddings URL: この Vertex AI サービスは、テキスト入力を数値形式に変換してセマンティック分析を行います。
  このチュートリアルでは、この URL を次のように設定できます。
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/text-embedding-004:predict
```
- Query Nearest Neighbor URL: この Vertex AI サービスは、再処理を回避するために、ベクトル検索インデックスで過去のリクエストの類似したテキスト入力を検索します。
  このチュートリアルでは、この URL を次のように設定できます。
```
PUBLIC_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/REGION/indexEndpoints/INDEX_ENDPOINT_ID:findNeighbors
```
  PUBLIC_DOMAIN_NAME と INDEX_ENDPOINT_ID の値は、前の手順で設定したものです。それらの値を取得するには、次のコマンドを使用します。
```
  echo $PUBLIC_DOMAIN_NAME
  echo $INDEX_ENDPOINT_ID
```
- Upsert index URL: この Vertex AI サービスは、新しいエントリまたは変更されたエントリでインデックスを更新します。
  このチュートリアルでは、この URL を次のように設定できます。
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints
```
[次へ] をクリックします。
[作成] をクリックします。

API プロキシの XML 構成は、[Develop] タブで確認できます。デフォルト値を含む SemanticCacheLookup ポリシーと SemanticCachePopulate ポリシーは、プロキシのリクエストおよびレスポンスのフローにすでにアタッチされています。

セマンティックキャッシュポリシーを構成する

各ポリシーの XML 構成を表示するには、API プロキシの [Develop] タブの [Detail] ビューでポリシー名をクリックします。ポリシー XML の編集は、[Develop] タブのコードビューで直接行えます。

ポリシーを編集します

SemanticCacheLookup ポリシー:
- デフォルト値を使用するには、<UserPromptSource> 要素を削除します。
- 値 semantic_cache を使用するように <DeployedIndexId> 要素を更新します。
- 2 つのプロンプトが一致と見なされるタイミングを決定するために、セマンティック類似性の <Threshold> 値を設定します。デフォルトは 0.9 ですが、アプリケーションの感度に応じてこの値を調整できます。数値が大きいほど、キャッシュヒットと見なされるためには、プロンプト同士がより密接に関連している必要があります。このチュートリアルでは、この値を 0.95 に設定することをおすすめします。
- [保存] をクリックします。
SemanticCachePopulate ポリシー:
- <TTLInSeconds> 要素を設定して、キャッシュの有効期限が切れるまでの秒数を秒単位で指定します。デフォルト値は 60 秒です。Apigee では、LLM モデルから受信したキャッシュ制御ヘッダーはすべて無視されることに注意してください。
- [保存] をクリックします。

API プロキシに Google 認証を追加する

ターゲットへのプロキシ呼び出しを有効にするには、API プロキシのターゲットエンドポイントに Google 認証を追加することも必要です。

Google アクセストークンを追加するには:

[Develop] タブで、[Target endpoints] フォルダの [default] をクリックします。コードビューには、<TargetEndpoint> 要素の XML 構成が表示されます。

XML を編集して、<HTTPTargetConnection> の下に次の構成を追加します。

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

[保存] をクリックします。

API プロキシをデプロイする

API プロキシをデプロイするには:

[Deploy] をクリックして、[Deploy API proxy] ペインを開きます。
[Revision] フィールドは [1] に設定します。選択されていない場合は、[1] をクリックして選択します。
[Environment] リストで、プロキシをデプロイする環境を選択します。環境は包括的環境である必要があります。
前の手順で作成したサービスアカウントを入力します。
[Deploy] をクリックします。

セマンティックキャッシュポリシーをテストする

セマンティックキャッシュポリシーをテストするには:

次のコマンドを使用して、プロキシにリクエストを送信します。

curl https://$RUNTIME_HOSTNAME/PROXY_NAME -H 'Content-Type: application/json' --data '{
  "contents": [
      {
          "role": "user",
          "parts": [
              {
                  "text": "Why is the sky blue?"
              }
          ]
      }
  ]
}'

ここで、PROXY_NAME は前の手順でデプロイした API プロキシのベースパスです。

空はなぜ青いのですか？
空が青いのはなぜですか？
空が青色なのはなぜですか？
空が青い理由を教えてもらえますか？
空は青いですが、それはなぜですか？

類似するプロンプトがキャッシュに保存された後、各呼び出しのレスポンス時間を比較します。

呼び出しがキャッシュから提供されていることを確認するには、レスポンスヘッダーを確認します。Cached-Content: true ヘッダーが付いている必要があります。

ベストプラクティス

セマンティックキャッシュポリシーを使用する場合は、次のベストプラクティスを API 管理プログラムに組み込むことをおすすめします。

Model Armor を使用して機密データのキャッシュ保存を防止します。
機密データのキャッシュ保存を防ぐため、コンテンツフィルタリングに Model Armor を使用することをおすすめします。Model Armor は、機密情報を検出すると、レスポンスがキャッシュに保存できないものとしてフラグを立てます。詳細については、Model Armor の概要をご覧ください。
Vertex AI データポイントの無効化と有効期間（TTL）を使用して、データの更新頻度を管理します。
キャッシュに保存されたレスポンスが最新の状態になり、バックエンドシステムの最新情報が反映されるように、適切なデータポイントの無効化戦略を実装することをおすすめします。詳細については、アクティブインデックスの更新と再構築をご覧ください。

また、データの変化率と更新頻度に基づいて、キャッシュに保存されたレスポンスの TTL を調整することもできます。SemanticCachePopulate ポリシーで TTL を使用する方法については、<TTLInSeconds> をご覧ください。
事前定義されたキャッシュ保存戦略を使用して、最も正確なレスポンスデータを確保します。
次のような事前定義されたキャッシュ戦略を実装することをおすすめします。
- 汎用 AI レスポンス: ユーザー固有ではないレスポンスには、長い TTL（1 時間など）を構成します。
- ユーザー固有のレスポンス: キャッシュを実装しないか、ユーザー固有の情報を含むレスポンスに短い TTL（5 分など）を設定します。
- 時間に敏感なレスポンス: リアルタイムまたは頻繁な更新が必要なレスポンスには、短い TTL（5 分など）を構成します。

制限事項

セマンティックキャッシュポリシーには次の制限が適用されます。

キャッシュに保存できるテキストの最大サイズは 256 KB です。詳細については、Apigee の上限ページのキャッシュ値のサイズをご覧ください。
Apigee では、LLM モデルから受信したキャッシュ制御ヘッダーはすべて無視されます。
キャッシュが適切に無効化されない場合、またはセマンティック類似性アルゴリズムが非常に似た意味の入力を十分に区別できない場合、古い情報や不正確な情報が返される可能性があります。
ベクトル検索機能は一部の地域ではサポートされていません。サポートされているリージョンの一覧については、Vertex AI のロケーションページの利用できる機能セクションをご覧ください。Apigee 組織がサポートされていないリージョンにある場合は、Apigee 組織とは異なるリージョンにインデックスエンドポイントを作成する必要があります。
セマンティックキャッシュポリシーは、サーバー送信イベント（SSE）の連続レスポンスストリーミングに EventFlows を使用する API プロキシでは使用できません。
<UserPromptSource> 内の JsonPath 関数は、ignoreUnresolvedVariables 機能をサポートしていません。デフォルトでは、メッセージテンプレートの適用時に null 値または空の値は無視されます。

次のステップ

Model Armor ポリシーの使い方を学習する。