Caching semantik dengan endpoint pribadi (Private Service Connect)

Halaman ini berlaku untuk Apigee, tetapi tidak untuk Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan cara mengonfigurasi dan menggunakan kebijakan caching semantik Apigee untuk mengaktifkan penggunaan kembali respons cerdas berdasarkan kemiripan semantik. Dalam contoh ini, kebijakan menjalankan penelusuran kemiripan terhadap indeks Penelusuran Vektor yang di-deploy di endpoint pribadi (Private Service Connect). Dengan menggunakan kebijakan ini di proxy API Apigee, Anda dapat meminimalkan panggilan API backend yang tidak diperlukan, mengurangi latensi, dan menurunkan biaya operasional.

Sebelum memulai

Sebelum memulai, selesaikan tugas berikut:

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

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

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

    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

  4. Aktifkan dan konfigurasi Vertex AI Text embeddings API di project Google Cloud Anda.
  5. Buat (atau miliki akses ke) indeks Penelusuran Vektor yang di-deploy di endpoint pribadi (Private Service Connect). Tutorial ini tidak menduplikasi langkah-langkah penyiapan Penelusuran Vektor; lihat Prasyarat indeks Penelusuran Vektor untuk persyaratan khusus SemanticCacheLookup dan link ke dokumentasi Penelusuran Vektor.
  6. Pastikan Anda memiliki lingkungan Menengah atau Komprehensif yang tersedia di instance Apigee Anda. Kebijakan penyimpanan data dalam cache semantik hanya dapat di-deploy di lingkungan Menengah atau Komprehensif.
  7. Konfirmasi bahwa Anda memiliki grup lingkungan dengan nama host runtime yang dapat Anda gunakan untuk mengirim permintaan ke proxy API.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna membuat dan menggunakan kebijakan caching semantik, minta administrator Anda untuk memberi Anda peran IAM Pengguna AI Platform (roles/aiplatform.user) pada akun layanan yang Anda gunakan untuk men-deploy proxy Apigee. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Menetapkan variabel lingkungan

Di project Google Cloud yang berisi instance Apigee Anda, gunakan perintah berikut untuk menetapkan variabel lingkungan: 

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

Dengan:

  • PROJECT_ID adalah ID project dengan instance Apigee Anda.
  • REGION adalah Google Cloud region instance Apigee Anda.
  • RUNTIME_HOSTNAME adalah nama host runtime Apigee Anda.

Untuk mengonfirmasi bahwa variabel lingkungan telah ditetapkan dengan benar, jalankan perintah berikut dan tinjau outputnya: 

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Menetapkan project

Siapkan Google Cloud project di lingkungan pengembangan Anda: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Prasyarat indeks Penelusuran Vektor

Tutorial ini mengasumsikan bahwa Anda telah memiliki (atau akan membuat) indeks Penelusuran Vektor yang di-deploy di endpoint pribadi (Private Service Connect). Pembuatan, pemformatan, dan deployment indeks Penelusuran Vektor didokumentasikan dalam panduan Penelusuran Vektor, sehingga tutorial ini tidak mengulangi langkah-langkah tersebut. Ikuti dokumentasi Penelusuran Vektor untuk:

Saat Anda membuat indeks, indeks tersebut harus memenuhi persyaratan khusus SemanticCacheLookup berikut:

  • Indeks harus menggunakan STREAM_UPDATE ("indexUpdateMethod": "STREAM_UPDATE") sehingga panggilan upsertDatapoints kebijakan SemanticCachePopulate dapat dikueri dalam waktu hampir real time.
  • Indeks dimensions harus cocok dengan dimensi output model embedding yang Anda gunakan dalam kebijakan SemanticCacheLookup. Tutorial ini menggunakan gemini-embedding-001, yang menghasilkan embedding 3072 dimensi secara default. Jika Anda memangkas output ke dimensi yang lebih rendah (misalnya, 768 atau 1536), tetapkan dimensions ke nilai yang sama.
  • Buat indeks dengan ukuran jarak (distanceMeasureType) yang cocok dengan <DistanceMeasureType> kebijakan Anda. Elemen <SimilaritySearch><VertexAI><DistanceMeasureType> dalam kebijakan SemanticCacheLookup bersifat opsional dan ditetapkan secara default ke DOT_PRODUCT_DISTANCE; COSINE_DISTANCE juga didukung. Ukuran jarak indeks dan kebijakan <DistanceMeasureType> harus sama.

Contoh minimal berikut membuat indeks yang kompatibel. Untuk isi permintaan lengkap dan semua opsi yang tersedia, lihat Membuat dan mengelola indeks:

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"
  }'

Catat INDEX_ID numerik yang ditampilkan dalam respons; Anda akan menggunakannya dalam kebijakan SemanticCachePopulate. Setelah membuat indeks, buat endpoint indeks Private Service Connect dan deploy indeks ke endpoint tersebut.

Saat Anda membuat endpoint indeks Private Service Connect, endpoint tersebut harus memenuhi persyaratan khusus SemanticCacheLookup berikut:

  • projectAllowlist harus menyertakan project Apigee yang memulai koneksi:
    • Apigee: Gunakan project tenant Apigee. Dapatkan project ID tenant dari Organizations API (kolom apigeeProjectId).
    projectAllowlist tidak dapat diubah setelah endpoint indeks dibuat. Jika Anda memasukkan project yang salah ke daftar yang diizinkan, Anda harus menghapus dan membuat ulang endpoint indeks.

Perhatikan INDEX_ENDPOINT_ID numerik dari endpoint indeks.

Mengonfigurasi akun layanan untuk proxy Apigee

Proxy Apigee menggunakan akun layanan untuk panggilan REST Vertex AI-nya: Embeddings API dalam kebijakan SemanticCacheLookup, upsertDatapoints dalam kebijakan SemanticCachePopulate, dan target model. Beri akun layanan tersebut peran AI Platform User (roles/aiplatform.user):

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

Dengan SERVICE_ACCOUNT adalah alamat email akun layanan yang digunakan proxy. Anda mereferensikan akun layanan ini saat men-deploy proxy di Langkah 4: Impor dan deploy proxy API.

Ringkasan

Kebijakan caching semantik membantu pengguna Apigee dengan model LLM untuk menyajikan perintah yang identik atau mirip secara semantik secara efisien dan cerdas, sehingga meminimalkan panggilan API backend dan mengurangi konsumsi resource.

Kebijakan SemanticCacheLookup dan SemanticCachePopulate masing-masing dilampirkan ke alur permintaan dan respons proxy API Apigee. Saat proxy menerima permintaan, kebijakan SemanticCacheLookup mengekstrak perintah pengguna dari permintaan dan mengonversi perintah menjadi representasi numerik menggunakan Text embeddings API. Penelusuran kemiripan semantik dilakukan menggunakan Vector Search untuk menemukan perintah serupa. Jika ditemukan perintah sebelumnya yang serupa, pencarian cache akan dilakukan. Jika data yang di-cache ditemukan, respons yang di-cache akan ditampilkan kepada klien.

Jika penelusuran kemiripan tidak menampilkan perintah sebelumnya yang serupa, model LLM akan membuat konten sebagai respons terhadap perintah pengguna dan mengisi cache Apigee dengan respons tersebut. Loop masukan dibuat untuk memperbarui entri indeks Penelusuran Vektor sebagai persiapan untuk permintaan mendatang.

Dalam skenario ini, indeks Penelusuran Vektor di-deploy di endpoint pribadi (Private Service Connect), melalui gRPC. Lihat detail selengkapnya tentang dukungan Private Service Connect Penelusuran Vektor di Mengueri indeks akses layanan pribadi atau Private Service Connect.

Bagian berikut menjelaskan langkah-langkah untuk membuat dan mengonfigurasi kebijakan caching semantik:

  1. Verifikasi resource Anda dan dapatkan nilai yang dibutuhkan Apigee.
  2. Hubungkan ke lampiran layanan.
  3. Bangun paket proxy API.
  4. Impor dan deploy proxy API.
  5. Uji kebijakan penyimpanan data dalam cache semantik.

Langkah 1: Verifikasi resource Anda dan dapatkan nilai yang dibutuhkan Apigee

Sebelum mengonfigurasi Apigee, pastikan endpoint indeks Penelusuran Vektor Anda kompatibel dengan Private Service Connect dan indeks Anda telah di-deploy. Kemudian, baca dua nilai yang digunakan oleh proxy Apigee: lampiran layanan dan DEPLOYED_INDEX_ID.

Konfirmasi bahwa indeks di-deploy dan endpoint mengekspos lampiran layanan Private Service Connect:

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

Perintah ini menampilkan nama resource lampiran layanan dalam bentuk projects/TENANT_PROJECT/regions/REGION/serviceAttachments/SERVICE_ATTACHMENT_NAME. Panduan ini menyebut nilai tersebut sebagai SERVICE_ATTACHMENT. Jika perintah menampilkan nilai kosong, indeks belum di-deploy di endpoint Private Service Connect. Kembali ke Prasyarat indeks Penelusuran Vektor dan selesaikan men-deploy indeks sebelum Anda melanjutkan.

Baca DEPLOYED_INDEX_ID indeks yang di-deploy di endpoint:

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

Panduan ini menyebut nilai tersebut sebagai DEPLOYED_INDEX_ID. Anda menggunakannya dalam kebijakan SemanticCacheLookup di Langkah 3: Buat paket proxy API.

Untuk mengetahui informasi selengkapnya tentang cara men-deploy dan membuat kueri endpoint indeks pribadi, lihat Men-deploy indeks ke endpoint Private Service Connect dan Membuat kueri indeks Private Service Connect atau Akses Layanan Pribadi.

Langkah 2: Hubungkan ke lampiran layanan

Langkah ini memberi Anda host pribadi yang dipanggil oleh <GrpcEndpoint> proxy. Di Apigee, buat lampiran endpoint Apigee. Lampiran endpoint adalah sisi konsumen Private Service Connect Apigee: lampiran ini terhubung ke lampiran layanan Penelusuran Vektor dan memberi Anda host pribadi yang dipanggil proxy.

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"

Polling hingga state lampiran adalah ACTIVE dan connectionState-nya adalah ACCEPTED, lalu catat host: 

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

Respons berisi host di kolom host. Panduan ini menyebut nilai tersebut sebagai TARGET_HOST.

Untuk terhubung ke lampiran layanan Penelusuran Vektor dari proxy, Anda dapat menggunakan salah satu dari:

  • Alamat IP: Gunakan alamat IP yang ditampilkan di kolom host secara langsung sebagai TARGET_HOST (misalnya, 7.0.3.4).
  • Data DNS pribadi: Jika Anda mengonfigurasi zona Cloud DNS pribadi di project Google Cloud dengan peering DNS ke Apigee, Anda dapat membuat data A di zona pribadi yang mengarah ke alamat IP lampiran endpoint dan menggunakan nama domain tersebut (seperti vectorsearch.example.com) sebagai TARGET_HOST. Untuk mengetahui informasi selengkapnya, lihat Menggunakan data DNS dan Menghubungkan dengan zona peering DNS pribadi.

Langkah 3: Bangun paket proxy API

Buat paket proxy

Buat tata letak direktori berikut: 

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

policies/SCL-1.xml—kebijakan SemanticCacheLookup. Blok <SimilaritySearch> menggunakan <PrivateServiceConnect><GrpcEndpoint> (tanpa <URL>).

Catatan: Aturan <GrpcEndpoint>:

  • Formatnya adalah grpc://TARGET_HOST:PORT; skemanya harus grpc://. grpcs:// (TLS) tidak didukung dalam versi ini.
  • Port-nya adalah 10000 untuk Penelusuran Vektor. Endpoint data plane Private Service Connect menyajikan gRPC di port 10000, sehingga endpoint selalu grpc://TARGET_HOST:10000.
  • TARGET_HOST dapat berupa alamat IP lampiran endpoint (dari Langkah 2) atau data DNS kustom yang dibuat di zona DNS pribadi Anda.
  • Hop gRPC adalah plaintext dan tidak diautentikasi (diamankan oleh isolasi jaringan).
<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—kebijakan SemanticCachePopulate. Populate hanya REST dan harus menggunakan <URL> (menolak <PrivateServiceConnect> pada waktu deployment): 

<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—target model. Target memanggil Google API, sehingga memerlukan token; <GoogleAccessToken> menggunakan akun layanan deployment: 

<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—jalankan kebijakan SemanticCacheLookup pada permintaan dan kebijakan SemanticCachePopulate pada respons: 

<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—deskripsi paket: 

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

Langkah 4: Impor dan deploy proxy API

Zip paket, impor untuk membuat revisi baru, dan deploy revisi dengan akun layanan Anda: 

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"

Dengan:

  • BUNDLE_DIR adalah direktori yang berisi folder apiproxy/. Arsip harus berisi folder apiproxy/ di root-nya.
  • ENV adalah lingkungan Apigee tempat Anda men-deploy proxy. Lingkungan harus berupa lingkungan Menengah atau Komprehensif.
  • REVISION adalah nomor revisi yang ditampilkan oleh panggilan impor.
  • SERVICE_ACCOUNT adalah alamat email akun layanan yang Anda gunakan untuk men-deploy proxy.

Tunggu hingga deployment melaporkan 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

Langkah 5: Uji kebijakan caching semantik

Kirim perintah baru. Ini adalah cache tidak ditemukan: model dipanggil dan jawabannya di-cache. 

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."}]}]}'

Kirim perintah yang sama lagi. Ini adalah hit cache: respons ditayangkan dari cache dan model tidak dipanggil. 

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."}]}]}'

Pada hit, respons mencakup header Cached-content: true, jawaban yang sama, dan latensi yang jauh lebih rendah.

Anda juga dapat memverifikasi penyimpanan dalam cache dengan sesi proses debug. Jika ada kecocokan, kebijakan SemanticCacheLookup akan menetapkan variabel alur berikut:

Variabel Nilai pada hit
SemanticCacheLookup.SCL-1.dense_embeddings Vektor embedding perintah.
SemanticCacheLookup.SCL-1.is_nearest_neighbor_hit true
SemanticCacheLookup.SCL-1.cache_hit true
SemanticCacheLookup.SCL-1.cached_llm_response Jawaban yang di-cache.

Jika ada hit, target model tidak dipanggil—alur akan diringkas dan menampilkan respons yang di-cache.

Pemecahan masalah

Untuk referensi error lengkap, lihat kebijakan SemanticCacheLookup.

Langkah berikutnya