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

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, AI Platform, 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.

Enable the APIs

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, AI Platform, 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.

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
```
[Next] をクリックします。
[Create] をクリックします。

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

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

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

ポリシーを編集します。

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

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 分など）を構成します。

依存サービスの割り当てを増やす

秒間クエリ数（QPS）の増加によるパフォーマンスのボトルネックが発生した場合は、 Google Cloud プロジェクトの依存サービスの次の割り当てを増やす必要がある場合があります。

リージョンごとの 1 分あたりのオンライン予測リクエスト数（リージョンで選択）
リージョンごとのベースモデル単位のオンライン予測リクエスト数（1 分あたり）（リージョンと textembedding-gecko モデルで選択）
リージョンごとの Matching Engine ストリーム更新リクエスト数（1 分あたり）（リージョンで選択）

これらのサービスのいずれかの割り当てを増やすには、次の操作を行います。

[割り当てとシステム上限] ページに移動します。
[割り当てとシステム上限] に移動
フィルタバーに、増加する特定の割り当ての名前と、関連する場合はリージョンとモデルの名前を入力します。
たとえば、リージョンごとのベースモデル単位のオンライン予測リクエスト数（1 分あたり）、textembedding-gecko、us-west1 でフィルタします。
増やすサービスのメニューをクリックし、[割り当てを編集] を選択します。
新しい割り当て値を入力します。
[完了] をクリックします。
[リクエストを送信] をクリックします。

リクエストを送信すると、割り当ての増加処理が行われます。ステータスは、[割り当てとシステム上限] ページの [リクエストの増加] タブでモニタリングできます。

制限事項

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

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

次のステップ

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

セマンティック キャッシュ保存ポリシーを使ってみる コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

必要なロール

環境変数を設定する

プロジェクトを設定する

概要

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

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

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

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

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

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

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

ベスト プラクティス

依存サービスの割り当てを増やす

制限事項

次のステップ

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

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

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

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

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

ベストプラクティス