Caching semantik dengan endpoint pribadi (Private Service Connect)

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan cara mengonfigurasi dan menggunakan kebijakan caching semantik Apigee untuk memungkinkan 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 menerapkan kebijakan ini di proxy API Apigee, Anda dapat meminimalkan panggilan API backend yang tidak diperlukan, mengurangi latensi, dan menurunkan biaya operasional.

Panduan ini berlaku untuk Apigee dan Apigee Hybrid. Konfigurasi kebijakan sama di kedua platform—hanya cara runtime menjangkau endpoint pribadi yang berbeda, seperti yang dijelaskan dalam Langkah 2: Hubungkan ke lampiran layanan. Di Apigee Hybrid, caching semantik melalui endpoint pribadi (Private Service Connect) didukung di versi 1.16.11 dan yang lebih baru, serta versi 1.17.0 dan yang lebih baru. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan di Apigee Hybrid.

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

  4. Aktifkan dan konfigurasikan API embedding teks Vertex AI di project Google Cloud Anda.
  5. Membuat (atau memiliki 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 caching semantik hanya dapat di-deploy di lingkungan Menengah atau Komprehensif.
  7. Pastikan 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 untuk membuat dan menggunakan kebijakan cache semantik, minta administrator untuk memberi Anda peran IAM AI Platform User (roles/aiplatform.user) di 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

Dalam 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 region Google Cloud 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

Tetapkan project Google Cloud di lingkungan pengembangan Anda: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Prasyarat indeks Penelusuran Vektor

Tutorial ini mengasumsikan bahwa Anda sudah 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 menduplikasi 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") agar 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 memotong 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: Menggunakan project tenant Apigee. Dapatkan project ID tenant dari Organizations API (kolom apigeeProjectId).
    projectAllowlist tidak dapat diubah setelah endpoint indeks dibuat. Jika Anda mengizinkan project yang salah, Anda harus menghapus dan membuat ulang endpoint indeks.

Catat INDEX_ENDPOINT_ID numerik 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. Berikan peran AI Platform User (roles/aiplatform.user) ke akun layanan tersebut:

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

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

Prasyarat tambahan untuk deployment Apigee Hybrid

Untuk deployment Apigee Hybrid, konfirmasi persyaratan tambahan berikut:

  • Runtime hybrid pada versi 1.16.11 atau yang lebih baru, atau 1.17.0 atau yang lebih baru, yang diinstal di cluster Kubernetes Anda sendiri. Lihat dokumentasi penginstalan Apigee Hybrid. Fitur ini tidak menambahkan persyaratan cluster tersendiri—cluster hybrid yang didukung akan berfungsi.
  • Lingkungan Intermediate atau Comprehensive dan grup lingkungan dengan nama host runtime, sama seperti di Apigee. Kebijakan caching semantik hanya di-deploy ke lingkungan Menengah atau Komprehensif.
  • Keterjangkauan jaringan dari runtime ke endpoint pribadi. Pemroses pesan harus dapat membuka koneksi gRPC teks biasa ke endpoint Private Service Connect Penelusuran Vektor di TARGET_HOST:10000.
  • Egress untuk panggilan REST. Panggilan Embeddings, Populate, dan model-target mengarah ke platform REGION-aiplatform.googleapis.com publik, sehingga runtime juga memerlukan jalur ke Google API—secara langsung, atau melalui jalur pribadi jika cluster Anda tidak memiliki egress publik.

Menyiapkan di Apigee Hybrid

Caching semantik melalui endpoint pribadi (Private Service Connect) didukung di Apigee Hybrid versi 1.16.11 dan yang lebih baru, serta versi 1.17.0 dan yang lebih baru. Konfigurasi kebijakan dan langkah-langkah Penelusuran Vektor dalam tutorial ini sama dengan Apigee—perbedaannya adalah di hybrid, Anda menjalankan runtime dan menyediakan konektivitasnya sendiri. Karena deployment hybrid sangat bervariasi, bagian ini merupakan panduan umum, bukan perintah yang tepat. Satu-satunya persyaratan yang ditambahkan fitur ini adalah runtime harus dapat menjangkau endpoint pribadi melalui gRPC teks biasa.

Menyediakan keterjangkauan jaringan

Dalam deployment hybrid, Anda harus mengelola konektivitas secara manual karena tidak ada lampiran endpoint yang dikelola Apigee. Buat endpoint Private Service Connect di VPC konsumen Anda yang mengarah ke SERVICE_ATTACHMENT Penelusuran Vektor, dan gunakan alamat IP internalnya sebagai TARGET_HOST di proxy. Lihat Langkah 2: Hubungkan ke lampiran layanan untuk mengetahui informasi selengkapnya. Perutean spesifik (misalnya, VPC Bersama atau GKE native VPC) bergantung pada konfigurasi cluster Anda.

Jika cluster Anda tidak memiliki egress internet publik, pastikan runtime memiliki jalur pribadi ke Google API, seperti Akses Google Pribadi, untuk menangani komunikasi REST.

Setelah membuat konektivitas ke grpc://TARGET_HOST:10000, ikuti langkah-langkah berikutnya—membuat dan men-deploy indeks, membangun proxy, dan menguji—yang sama untuk Apigee dan Apigee Hybrid.

Ringkasan

Kebijakan caching semantik membantu pengguna Apigee dengan model LLM untuk menyajikan perintah yang identik atau mirip secara semantik dengan cerdas dan efisien, 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 tersebut menjadi representasi numerik menggunakan API embedding teks. Penelusuran kemiripan semantik dilakukan menggunakan Penelusuran Vektor untuk menemukan perintah serupa. Jika titik data perintah yang serupa ditemukan, pencarian cache akan dilakukan. Jika data yang di-cache ditemukan, respons yang di-cache akan ditampilkan ke klien.

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

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 Membuat kueri 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 diperlukan Apigee.
  2. Hubungkan ke lampiran layanan.
  3. Bangun paket proxy API.
  4. Mengimpor dan men-deploy proxy API.
  5. Menguji kebijakan caching semantik.

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

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

Pastikan indeks telah 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 deployment indeks sebelum 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 mengacu pada nilai tersebut sebagai DEPLOYED_INDEX_ID. Anda akan menggunakannya dalam kebijakan SemanticCacheLookup di Langkah 3: Buat paket proxy API.

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

Langkah 2: Hubungkan ke lampiran layanan

Langkah ini memberi Anda host pribadi yang dipanggil oleh <GrpcEndpoint> proxy. Cara membuatnya bergantung pada platform Anda. Konfigurasi proxy pada langkah selanjutnya akan sama, apa pun cara yang Anda pilih.

Apigee: Membuat lampiran endpoint

Di Apigee, buat lampiran endpoint Apigee. Lampiran endpoint adalah sisi konsumen Private Service Connect Apigee. Endpoint ini terhubung ke lampiran layanan Penelusuran Vektor dan memberi Anda host pribadi yang dipanggil oleh 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"

Lakukan polling hingga state lampiran menjadi ACTIVE dan connectionState-nya menjadi ACCEPTED, lalu catat host-nya: 

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 mengacu pada nilai tersebut sebagai TARGET_HOST.

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

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

Endpoint Private Service Connect untuk Apigee Hybrid

Di Apigee, Google menyediakan resource "lampiran endpoint" yang menangani koneksi Private Service Connect. Namun, di Apigee Hybrid, Anda mengelola runtime dan lingkungan jaringan. Di mana pun cluster Anda berjalan, cluster tersebut harus dapat menjangkau endpoint Private Service Connect Penelusuran Vektor melalui koneksi gRPC teks biasa ke host:10000.

Untuk Apigee Hybrid, buat endpoint Private Service Connect di Google Cloud VPC konsumen yang mengarah ke SERVICE_ATTACHMENT Penelusuran Vektor. Gunakan alamat IP internal endpoint sebagai TARGET_HOST dalam konfigurasi proxy Anda. Pastikan project Google Cloud yang menghosting endpoint ini disertakan dalam projectAllowlist endpoint indeks Penelusuran Vektor. Lihat Prasyarat indeks Penelusuran Vektor untuk mengetahui detail selengkapnya.

Langkah 3: Bangun paket proxy API

Membuat 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-nya 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 berupa teks biasa 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—menjalankan 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: Menguji kebijakan caching semantik

Mengirim 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 cache ditemukan: respons disajikan 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."}]}]}'

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

Anda juga dapat memverifikasi caching dengan sesi debug. Jika ditemukan, kebijakan SemanticCacheLookup akan menetapkan variabel flow 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 ditemukan, target model tidak akan dipanggil—alur akan langsung menampilkan respons yang di-cache.

Pemecahan masalah

Untuk referensi error selengkapnya, lihat kebijakan SemanticCacheLookup.

Batasan

Batasan berikut berlaku untuk kebijakan caching semantik:

  • Ukuran teks maksimum yang dapat di-cache adalah 256 KB. Untuk mengetahui informasi selengkapnya, lihat Ukuran nilai cache di halaman Batasan Apigee.
  • Apigee mengabaikan header cache-control yang diterimanya dari model LLM.
  • Jika cache tidak divalidasi dengan benar atau jika algoritma kesamaan semantik tidak cukup akurat untuk membedakan antara input dengan makna yang sangat mirip, respons dapat menampilkan informasi yang sudah tidak berlaku atau salah.
    • Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi TTL untuk mengelola keaktualan data, lihat bagian Praktik terbaik.
    • Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi nilai minimum kesamaan semantik, lihat bagian Mengonfigurasi kebijakan caching semantik.
    • Untuk mengetahui informasi selengkapnya tentang cara menyesuaikan algoritma kesamaan semantik, lihat Memfilter kecocokan vektor.
  • Fitur Penelusuran Vektor tidak didukung di semua region. Untuk mengetahui daftar wilayah yang didukung, lihat bagian Ketersediaan fitur di halaman Lokasi Vertex AI. Jika organisasi Apigee Anda berada di region yang tidak didukung, Anda harus membuat endpoint indeks di region yang berbeda dengan organisasi Apigee Anda.
  • Kebijakan caching semantik tidak didukung untuk digunakan dengan proxy API yang menggunakan EventFlow untuk streaming respons berkelanjutan dari peristiwa yang dikirim server (SSE).
  • Kebijakan caching semantik menggunakan LLM API, yang dapat menghasilkan latensi lebih tinggi dalam ratusan milidetik.
  • Dalam penginstalan Apigee hybrid, dukungan untuk kebijakan caching semantik terbatas pada penginstalan di Google Cloud Platform.
  • Jika kebijakan SemanticCacheLookup dikonfigurasi untuk menggunakan endpoint Penelusuran Vektor pribadi melalui Private Service Connect (PSC), panggilan penelusuran kesamaan akan dikirim melalui koneksi gRPC langsung ke endpoint pribadi dan tidak melalui proxy penerusan yang dikonfigurasi.

Langkah berikutnya