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

Panduan ini berlaku untuk Apigee dan Apigee Hybrid. Konfigurasi kebijakan identik di kedua platform—hanya cara runtime mencapai endpoint pribadi yang berbeda, seperti dijelaskan dalam Langkah 2: Hubungkan ke lampiran layanan. Di Apigee Hybrid, semantik caching melalui endpoint pribadi (Private Service Connect) didukung di 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. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

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

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

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

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

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

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

    8.
  8. Aktifkan dan konfigurasi Vertex AI Text embeddings API di project Google Cloud Anda.
  9. 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.
  10. 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.
  11. 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.

Prasyarat tambahan untuk deployment Apigee Hybrid

Untuk deployment Apigee Hybrid, konfirmasi persyaratan tambahan berikut:

  • Runtime hybrid di 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 sendiri—cluster hybrid yang didukung berfungsi.
  • Lingkungan Menengah atau Komprehensif dan grup lingkungan dengan nama host runtime, yang sama seperti di Apigee. Kebijakan penyimpanan data dalam cache 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 akan masuk ke permukaan REGION-aiplatform.googleapis.com publik, sehingga runtime juga memerlukan jalur ke Google API—secara langsung, atau melalui jalur pribadi jika cluster Anda tidak memiliki keluar publik.

Menyiapkan di Apigee Hybrid

Caching semantik melalui endpoint pribadi (Private Service Connect) didukung di Apigee Hybrid 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 berisi panduan umum, bukan perintah yang tepat. Satu-satunya persyaratan yang ditambahkan fitur ini adalah bahwa runtime harus dapat menjangkau endpoint pribadi melalui gRPC teks biasa.

Menyediakan aksesibilitas 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 yang mengarah ke Penelusuran Vektor SERVICE_ATTACHMENT, dan gunakan alamat IP internalnya sebagai TARGET_HOST di proxy. Lihat Langkah 2: Hubungkan ke lampiran layanan untuk mengetahui informasi selengkapnya. Perutean tertentu (misalnya, GKE native VPC atau VPC Bersama) bergantung pada konfigurasi cluster Anda.

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

Setelah konektivitas ke grpc://TARGET_HOST:10000 dibuat, ikuti langkah-langkah berikutnya—membuat dan men-deploy indeks, membuat proxy, dan melakukan pengujian—yang identik untuk Apigee dan Apigee Hybrid.

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 titik data perintah serupa ditemukan, 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. Cara membuatnya bergantung pada platform Anda. Konfigurasi proxy pada langkah-langkah selanjutnya sama saja.

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

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 Penelusuran Vektor SERVICE_ATTACHMENT. 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

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.

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 Batas Apigee.
  • Apigee mengabaikan header cache-control apa pun yang diterimanya dari model LLM.
  • Jika cache tidak dibatalkan dengan benar atau jika algoritma kemiripan semantik tidak cukup akurat untuk membedakan antara input dengan makna yang sangat mirip, respons dapat menampilkan informasi yang sudah tidak berlaku atau salah.
  • Fitur Penelusuran Vektor tidak didukung di semua wilayah. Untuk mengetahui daftar region 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 EventFlows untuk streaming respons berkelanjutan dari peristiwa yang dikirim server (SSE).
  • Kebijakan penyimpanan dalam cache semantik menggunakan LLM API, yang dapat menghasilkan latensi yang 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 similarity-search akan dikirim melalui koneksi gRPC langsung ke endpoint pribadi dan tidak melalui proxy penerusan yang dikonfigurasi.

Langkah berikutnya