Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

プライベート（Private Service Connect）エンドポイントを使用したセマンティックキャッシュ保存

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

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

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

このガイドは、Apigee と Apigee ハイブリッドの両方に適用されます。ポリシー構成は両方のプラットフォームで同じです。ステップ 2: サービスアタッチメントに接続するで説明されているように、ランタイムがプライベートエンドポイントに到達する方法のみが異なります。Apigee ハイブリッドでは、プライベート（Private Service Connect）エンドポイントを介したセマンティックキャッシュは、バージョン 1.16.11 以降とバージョン 1.17.0 以降でサポートされています。詳細については、Apigee ハイブリッドで設定するをご覧ください。

始める前に

始める前に、次のタスクを完了します。

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Compute Engine, AI Platform, and Cloud Storage APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
Enable the APIs

Google Cloud プロジェクトで Vertex AI のテキストエンベディング API を有効にして構成します。
プライベート（Private Service Connect）エンドポイントにデプロイされたベクトル検索インデックスを作成する（またはアクセス権がある）。このチュートリアルでは、ベクトル検索の設定手順を繰り返しません。SemanticCacheLookup 固有の要件とベクトル検索のドキュメントへのリンクについては、ベクトル検索インデックスの前提条件をご覧ください。
Apigee インスタンスで中間環境または包括的な環境が使用可能であることを確認します。セマンティックキャッシュポリシーは、中間環境または包括的な環境にのみデプロイできます。
API プロキシにリクエストを送信するために使用できるランタイムホスト名を持つ環境グループがあることを確認します。

必要なロール

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

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

注: プロキシをデプロイする ID には、SERVICE_ACCOUNT（またはプロジェクトレベル）に対する roles/iam.serviceAccountUser（サービスアカウントユーザー）ロールが必要です。ステップ 4: API プロキシをインポートしてデプロイするをご覧ください。

環境変数を設定する

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

ベクトル検索インデックスの前提条件

このチュートリアルでは、プライベート（Private Service Connect）エンドポイントにデプロイされたベクトル検索インデックスがすでに存在している（または作成する）ことを前提としています。ベクトル検索インデックスの作成、フォーマット、デプロイについては、ベクトル検索ガイドに記載されているため、このチュートリアルではこれらの手順を繰り返しません。ベクトル検索のドキュメントに沿って、次の操作を行います。

インデックスを作成するときは、次の SemanticCacheLookup 固有の要件を満たす必要があります。

SemanticCachePopulate ポリシーの upsertDatapoints 呼び出しがほぼリアルタイムでクエリ可能になるように、インデックスは STREAM_UPDATE（"indexUpdateMethod": "STREAM_UPDATE"）を使用する必要があります。
インデックス dimensions は、SemanticCacheLookup ポリシーで使用するエンベディングモデルの出力次元数と一致する必要があります。このチュートリアルでは、デフォルトで 3, 072 次元のエンベディングを生成する gemini-embedding-001 を使用します。出力をより低い次元（768 や 1536 など）に切り捨てる場合は、dimensions を同じ値に設定します。
ポリシーの <DistanceMeasureType> と一致する距離測定（distanceMeasureType）を使用してインデックスを作成します。SemanticCacheLookup ポリシーの <SimilaritySearch><VertexAI><DistanceMeasureType> 要素は省略可能で、デフォルトは DOT_PRODUCT_DISTANCE です。COSINE_DISTANCE もサポートされています。インデックス距離の測定値とポリシー <DistanceMeasureType> は同じである必要があります。

次の最小限の例では、互換性のあるインデックスを作成します。リクエスト本文全体と使用可能なすべてのオプションについては、インデックスを作成して管理するをご覧ください。

ACCESS_TOKEN=$(gcloud auth print-access-token) && curl -X POST \
  "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "semantic-cache-index",
    "metadata": {
      "config": {
        "dimensions": 3072,
        "distanceMeasureType": "DOT_PRODUCT_DISTANCE"
      }
    },
    "indexUpdateMethod": "STREAM_UPDATE"
  }'

レスポンスで返された数値 INDEX_ID をメモします。これは SemanticCachePopulate ポリシーで使用します。インデックスを作成したら、Private Service Connect インデックスエンドポイントを作成し、そこにインデックスをデプロイします。

Private Service Connect インデックスエンドポイントを作成するときは、次の SemanticCacheLookup 固有の要件を満たす必要があります。

projectAllowlist には、接続を開始する Apigee プロジェクトを含める必要があります。
- Apigee: Apigee テナントプロジェクトを使用します。Organizations API（apigeeProjectId フィールド）からテナントプロジェクト ID を取得します。
インデックスエンドポイントの作成後に projectAllowlist を変更することはできません。間違ったプロジェクトを許可リストに登録した場合は、インデックスエンドポイントを削除して再作成する必要があります。

インデックスエンドポイントの数値 INDEX_ENDPOINT_ID をメモします。

Apigee プロキシのサービスアカウントを構成する

Apigee プロキシは、Vertex AI REST 呼び出し（SemanticCacheLookup ポリシーの Embeddings API、SemanticCachePopulate ポリシーの upsertDatapoints、モデルターゲット）にサービスアカウントを使用します。そのサービスアカウントに AI Platform User（roles/aiplatform.user）ロールを付与します。

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

ここで、SERVICE_ACCOUNT はプロキシが使用するサービスアカウントのメールアドレスです。このサービスアカウントは、ステップ 4: API プロキシをインポートしてデプロイするでプロキシをデプロイするときに参照します。

注: プロキシをデプロイする ID には、SERVICE_ACCOUNT（またはプロジェクトレベル）に対する roles/iam.serviceAccountUser（サービスアカウントユーザー）ロールが必要です。これにより、そのサービスアカウントが接続されたプロキシをデプロイできます。ステップ 4: API プロキシをインポートしてデプロイするをご覧ください。

Apigee ハイブリッドデプロイの追加の前提条件

Apigee ハイブリッドデプロイの場合は、次の追加要件を確認します。

独自の Kubernetes クラスタにインストールされたバージョン 1.16.11 以降または 1.17.0 以降のハイブリッドランタイム。Apigee ハイブリッドのインストールドキュメントをご覧ください。この機能には、独自のクラスタ要件はありません。サポートされているハイブリッドクラスタであれば、どれでも機能します。
Intermediate または Comprehensive 環境と、Apigee と同じランタイムホスト名を持つ環境グループ。セマンティックキャッシュポリシーは、中間環境または包括的な環境にのみデプロイされます。
ランタイムからプライベートエンドポイントへのネットワーク到達性。Message Processor は、TARGET_HOST:10000 のベクトル検索 Private Service Connect エンドポイントへの平文の gRPC 接続を開くことができる必要があります。
REST 呼び出しの下り（外向き）。Embeddings、Populate、model-target の呼び出しは、公開 REGION-aiplatform.googleapis.com サーフェスに送信されるため、ランタイムには Google API へのパスも必要です。クラスタに公開下り（外向き）がない場合は、直接またはプライベートパス経由で送信されます。

Apigee ハイブリッドで設定する

プライベート（Private Service Connect）エンドポイントを介したセマンティックキャッシュは、Apigee ハイブリッドバージョン 1.16.11 以降とバージョン 1.17.0 以降でサポートされています。このチュートリアルのポリシー構成とベクトル検索の手順は Apigee と同じです。違いは、ハイブリッドではランタイムを実行し、接続を自分で提供することです。ハイブリッドデプロイは多岐にわたるため、このセクションでは、正確なコマンドではなく、一般的なガイダンスについて説明します。この機能で追加される唯一の要件は、ランタイムが平文の gRPC 経由でプライベートエンドポイントに到達できることです。

Network Reachability を提供する

ハイブリッドデプロイでは、Apigee が管理するエンドポイントアタッチメントがないため、接続を手動で管理する必要があります。ベクトル検索 SERVICE_ATTACHMENT を指すPrivate Service Connect エンドポイントをコンシューマー VPC に作成し、その内部 IP アドレスをプロキシの TARGET_HOST として使用します。詳細については、ステップ 2: サービスアタッチメントに接続するをご覧ください。具体的なルーティング（共有 VPC や VPC ネイティブ GKE など）は、クラスタの構成によって異なります。

クラスタにパブリックインターネットの下り（外向き）がない場合は、ランタイムに Google API へのプライベートパス（限定公開の Google アクセスなど）があり、REST 通信を処理できることを確認します。

grpc://TARGET_HOST:10000 への接続を確立したら、後続の手順（インデックスの作成とデプロイ、プロキシの構築、テスト）を行います。これらの手順は、Apigee と Apigee ハイブリッドの両方で同じです。

概要

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

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

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

このシナリオでは、ベクトル検索インデックスは gRPC 経由でプライベート（Private Service Connect）エンドポイントにデプロイされます。ベクトル検索の Private Service Connect のサポートの詳細については、プライベートサービスアクセスまたは Private Service Connect インデックスをクエリするをご覧ください。

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

リソースを確認し、Apigee に必要な値を取得します。
サービスアタッチメントに接続する。
API プロキシバンドルをビルドします。
API プロキシをインポートしてデプロイする。
セマンティックキャッシュ保存ポリシーをテストする。

ステップ 1: リソースを確認し、Apigee に必要な値を取得する

Apigee を構成する前に、ベクトル検索インデックスエンドポイントが Private Service Connect 対応であり、インデックスがデプロイされていることを確認します。次に、Apigee プロキシが使用する 2 つの値（サービスアタッチメントと DEPLOYED_INDEX_ID）を読み取ります。

インデックスがデプロイされ、エンドポイントが Private Service Connect サービスアタッチメントを公開していることを確認します。

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.privateEndpoints.serviceAttachment)"

このコマンドは、projects/TENANT_PROJECT/regions/REGION/serviceAttachments/SERVICE_ATTACHMENT_NAME 形式のサービスアタッチメントリソース名を返します。このガイドでは、この値を SERVICE_ATTACHMENT と呼びます。コマンドが空の値を返した場合、インデックスは Private Service Connect エンドポイントにまだデプロイされていません。ベクトル検索インデックスの前提条件に戻り、インデックスのデプロイを完了してから続行してください。

エンドポイントにデプロイされたインデックスの DEPLOYED_INDEX_ID を読み取ります。

gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --project=$PROJECT_ID --region=$REGION \
  --format="value(deployedIndexes.id)"

このガイドでは、この値を DEPLOYED_INDEX_ID と呼びます。これは、ステップ 3: API プロキシバンドルをビルドするの SemanticCacheLookup ポリシーで使用します。

プライベートインデックスエンドポイントのデプロイとクエリの詳細については、Private Service Connect エンドポイントにインデックスをデプロイするとプライベートサービスアクセスまたは Private Service Connect インデックスをクエリするをご覧ください。

ステップ 2: サービスアタッチメントに接続する

このステップでは、プロキシの <GrpcEndpoint> が呼び出すプライベートホストを取得します。作成方法はプラットフォームによって異なります。どちらの方法でも、以降の手順のプロキシ構成は同じです。

Apigee: エンドポイントアタッチメントを作成する

Apigee で、Apigee エンドポイントアタッチメントを作成します。エンドポイントアタッチメントは、Apigee の Private Service Connect コンシューマー側です。ベクトル検索サービスアタッチメントに接続し、プロキシが呼び出すプライベートホストを提供します。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
        "location": "'"$REGION"'",
        "serviceAttachment": "SERVICE_ATTACHMENT"
      }' \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments?endpointAttachmentId=ENDPOINT_ATTACHMENT"

アタッチメントの state が ACTIVE になり、connectionState が ACCEPTED になるまでポーリングし、ホストをメモします。

curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/endpointAttachments/ENDPOINT_ATTACHMENT"

レスポンスの host フィールドにホストが含まれています。このガイドでは、この値を TARGET_HOST と呼びます。

プロキシからベクトル検索サービスアタッチメントに接続するには、次のいずれかを使用します。

IP アドレス: host フィールドで返された IP アドレスを TARGET_HOST として直接使用します（例: 7.0.3.4）。
プライベート DNS レコード: Apigee への DNS ピアリングを使用して Google Cloud プロジェクトにプライベート Cloud DNS ゾーンを構成した場合は、エンドポイントアタッチメントの IP アドレスを参照する A レコードをプライベートゾーンに作成し、そのドメイン名（vectorsearch.example.com など）を TARGET_HOST として使用できます。詳細については、DNS レコードを使用するとプライベート DNS ピアリングゾーンとの接続をご覧ください。

注: connectionState が PENDING のままの場合、ベクトル検索サービスアタッチメントは接続を受け入れていません。通常、これはテナントプロジェクトが許可リストに登録されていないことが原因です。インデックスエンドポイントの projectAllowlist は作成後に変更できないため、ベクトル検索インデックスの前提条件に戻り、正しい privateServiceConnectConfig.projectAllowlist 値でインデックスエンドポイントを再作成します。

Apigee ハイブリッド用の Private Service Connect エンドポイント

Apigee では、Private Service Connect 接続を処理する「エンドポイントアタッチメント」リソースが提供されます。ただし、Apigee ハイブリッドでは、ランタイムとネットワーク環境を管理します。クラスタがどこで実行されているかにかかわらず、host:10000 への平文の gRPC 接続を介してベクトル検索の Private Service Connect エンドポイントに到達できる必要があります。

Apigee ハイブリッドの場合は、ベクトル検索 SERVICE_ATTACHMENT を指す Google Cloud コンシューマ VPC に Private Service Connect エンドポイントを作成します。エンドポイントの内部 IP アドレスを、プロキシ構成の TARGET_HOST として使用します。このエンドポイントをホストする Google Cloud プロジェクトが、ベクトル検索インデックスエンドポイントの projectAllowlist に含まれていることを確認します。詳細については、ベクトル検索インデックスの前提条件をご覧ください。

ステップ 3: API プロキシバンドルをビルドする

プロキシバンドルを作成する

次のディレクトリレイアウトを作成します。

apiproxy/
├── PROXY_NAME.xml
├── proxies/default.xml
├── targets/default.xml
└── policies/
    ├── SCL-1.xml
    └── SCP-1.xml

policies/SCL-1.xml - SemanticCacheLookup ポリシー。<SimilaritySearch> ブロックは <PrivateServiceConnect><GrpcEndpoint> を使用します（<URL> は使用しません）。

注: <PrivateServiceConnect> トランスポートは、Apigee、Apigee ハイブリッドバージョン 1.16.11 以降、バージョン 1.17.0 以降でサポートされています。

注: <GrpcEndpoint> ルール:

形式は grpc://TARGET_HOST:PORT です。スキームは grpc:// にする必要があります。grpcs://（TLS）は、このバージョンではサポートされていません。
ベクトル検索のポートは 10000 です。Private Service Connect データプレーンエンドポイントはポート 10000 で gRPC を提供するため、エンドポイントは常に grpc://TARGET_HOST:10000 です。
TARGET_HOST には、エンドポイントアタッチメントの IP アドレス（ステップ 2）またはプライベート DNS ゾーンに作成されたカスタム DNS レコードを指定できます。
gRPC ホップは、平文で認証されていません（ネットワーク分離によって保護されています）。

<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-1">
  <DisplayName>SCL-1</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-embedding-001:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <PrivateServiceConnect>
        <GrpcEndpoint>grpc://TARGET_HOST:10000</GrpcEndpoint>
      </PrivateServiceConnect>
      <DeployedIndexID>DEPLOYED_INDEX_ID</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

policies/SCP-1.xml - SemanticCachePopulate ポリシー。populate は REST 専用であり、<URL> を使用する必要があります（デプロイ時に <PrivateServiceConnect> を拒否します）。

<SemanticCachePopulate async="false" continueOnError="true" enabled="true" name="SCP-1">
  <DisplayName>SCP-1</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>3600</TTLInSeconds>
</SemanticCachePopulate>

targets/default.xml - モデルターゲット。ターゲットは Google API を呼び出すため、トークンが必要です。<GoogleAccessToken> はデプロイのサービスアカウントを使用します。

<TargetEndpoint name="default">
  <PreFlow name="PreFlow"><Request/><Response/></PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

proxies/default.xml - リクエストで SemanticCacheLookup ポリシーを実行し、レスポンスで SemanticCachePopulate ポリシーを実行します。

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request><Step><Name>SCL-1</Name></Step></Request>
    <Response><Step><Name>SCP-1</Name></Step></Response>
  </PreFlow>
  <PostFlow name="PostFlow"><Request/><Response/></PostFlow>
  <HTTPProxyConnection>
    <BasePath>/PROXY_NAME</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

PROXY_NAME.xml - バンドル記述子:

<APIProxy name="PROXY_NAME">
  <BasePaths>/PROXY_NAME</BasePaths>
  <Policies><Policy>SCL-1</Policy><Policy>SCP-1</Policy></Policies>
  <ProxyEndpoints><ProxyEndpoint>default</ProxyEndpoint></ProxyEndpoints>
  <TargetEndpoints><TargetEndpoint>default</TargetEndpoint></TargetEndpoints>
</APIProxy>

ステップ 4: API プロキシをインポートしてデプロイする

バンドルを ZIP 形式で圧縮し、インポートして新しいリビジョンを作成し、サービスアカウントを使用してリビジョンをデプロイします。

TOKEN=$(gcloud auth print-access-token)
(cd BUNDLE_DIR && zip -r ../PROXY_NAME.zip apiproxy)
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -F "file=@PROXY_NAME.zip" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/apis?action=import&name=PROXY_NAME"
curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments?override=true&serviceAccount=SERVICE_ACCOUNT"

ここで

BUNDLE_DIR は、apiproxy/ フォルダを含むディレクトリです。アーカイブのルートに apiproxy/ フォルダが含まれている必要があります。
ENV は、プロキシをデプロイする Apigee 環境です。環境は中間環境または包括的環境である必要があります。
REVISION は、インポート呼び出しによって返されたリビジョン番号です。
SERVICE_ACCOUNT は、プロキシのデプロイに使用するサービスアカウントのメールアドレスです。

注: プロキシをデプロイする ID には、そのサービスアカウントが接続されたプロキシをデプロイするために、SERVICE_ACCOUNT（またはプロジェクトレベル）に対する roles/iam.serviceAccountUser（サービスアカウントユーザー）ロールが必要です。プロジェクトオーナーと編集者には、デフォルトでこの権限が含まれています。デプロイする ID がオーナーまたは編集者でない場合は、次のコマンドを使用してサービスアカウントにロールを付与します。

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT \
  --member="user:DEPLOYER_EMAIL" \
  --role="roles/iam.serviceAccountUser"

デプロイが READY を報告するまで待ちます。

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV/apis/PROXY_NAME/revisions/REVISION/deployments" | jq .state

ステップ 5: セマンティックキャッシュ保存ポリシーをテストする

新しいプロンプトを送信します。これはキャッシュミスです。モデルが呼び出され、回答がキャッシュに保存されます。

curl -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

同じプロンプトをもう一度送信します。これはキャッシュヒットです。レスポンスはキャッシュから提供され、モデルは呼び出されません。

curl -i -X POST "https://$RUNTIME_HOSTNAME/PROXY_NAME" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain in one sentence why the sky appears blue."}]}]}'

ヒットすると、レスポンスには Cached-content: true ヘッダー、同じ回答、著しく低いレイテンシが含まれます。

デバッグセッションでキャッシュを確認することもできます。ヒットすると、SemanticCacheLookup ポリシーは次のフロー変数を設定します。

変数	ヒットの値
`SemanticCacheLookup.SCL-1.dense_embeddings`	プロンプトのエンベディングベクトル。
`SemanticCacheLookup.SCL-1.is_nearest_neighbor_hit`	`true`
`SemanticCacheLookup.SCL-1.cache_hit`	`true`
`SemanticCacheLookup.SCL-1.cached_llm_response`	キャッシュに保存された回答。

ヒットすると、モデルターゲットは呼び出されません。フローはショートカットされ、キャッシュに保存されたレスポンスを返します。

トラブルシューティング

エラーリファレンスの詳細については、SemanticCacheLookup ポリシーをご覧ください。

制限事項

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

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

次のステップ

ベクトル検索でプライベートサービスアクセスまたは Private Service Connect インデックスをクエリする方法を学習する。
セマンティックキャッシュ保存ポリシーを使ってみるで、パブリックエンドポイントに対してセマンティックキャッシュを構成する方法を確認する。
Model Armor ポリシーの使い方を学習する。

プライベート（Private Service Connect）エンドポイントを使用したセマンティック キャッシュ保存 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

必要なロール

環境変数を設定する

プロジェクトを設定する

ベクトル検索インデックスの前提条件

Apigee プロキシのサービス アカウントを構成する

Apigee ハイブリッド デプロイの追加の前提条件

Apigee ハイブリッドで設定する

Network Reachability を提供する

概要

ステップ 1: リソースを確認し、Apigee に必要な値を取得する

ステップ 2: サービス アタッチメントに接続する

Apigee: エンドポイント アタッチメントを作成する

Apigee ハイブリッド用の Private Service Connect エンドポイント

ステップ 3: API プロキシ バンドルをビルドする

プロキシ バンドルを作成する

ステップ 4: API プロキシをインポートしてデプロイする

ステップ 5: セマンティック キャッシュ保存ポリシーをテストする

トラブルシューティング

制限事項

次のステップ

プライベート（Private Service Connect）エンドポイントを使用したセマンティックキャッシュ保存

Apigee プロキシのサービスアカウントを構成する

Apigee ハイブリッドデプロイの追加の前提条件

ステップ 2: サービスアタッチメントに接続する

Apigee: エンドポイントアタッチメントを作成する

ステップ 3: API プロキシバンドルをビルドする

プロキシバンドルを作成する

ステップ 5: セマンティックキャッシュ保存ポリシーをテストする