Halaman ini diterjemahkan oleh Cloud Translation API.

Mulai menggunakan kebijakan penyimpanan ke cache semantik

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan cara mengonfigurasi dan menggunakan kebijakan cache semantik Apigee untuk mengaktifkan penggunaan kembali respons cerdas berdasarkan kemiripan semantik. Penggunaan kebijakan ini di proxy API Apigee dapat meminimalkan panggilan API backend yang berlebihan, mengurangi latensi, dan menurunkan biaya operasional.

Sebelum memulai

Sebelum memulai, pastikan Anda menyelesaikan tugas berikut:

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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

Enable the APIs

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

Enable the APIs

Siapkan dan konfigurasikan Text embeddings API dan Vector Search Vertex AI dalam Google Cloud project Anda.
Pastikan Anda memiliki lingkungan Komprehensif yang tersedia di instance Apigee Anda. Kebijakan penyimpanan data dalam cache semantik hanya dapat di-deploy di lingkungan Komprehensif.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk membuat dan menggunakan kebijakan penyimpanan dalam cache semantik, minta administrator untuk memberi Anda AI Platform User (roles/aiplatform.user) peran IAM 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 Google Cloud region instance Apigee Anda.
RUNTIME_HOSTNAME adalah nama host runtime Apigee Anda.

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

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Menetapkan project

Tetapkan Google Cloud project di lingkungan pengembangan Anda:

    gcloud auth login
    gcloud config set project $PROJECT_ID

Ringkasan

Kebijakan penyimpanan dalam cache semantik dirancang untuk membantu pengguna Apigee dengan model LLM untuk secara cerdas menayangkan perintah yang identik atau mirip secara semantik secara efisien, meminimalkan panggilan API backend, dan mengurangi penggunaan resource.

Kebijakan SemanticCacheLookup dan SemanticCachePopulate masing-masing dilampirkan ke alur permintaan dan respons dari proxy Apigee API. Saat proxy menerima permintaan, kebijakan SemanticCacheLookup mengekstrak perintah pengguna dari permintaan dan mengonversi perintah tersebut menjadi representasi numerik menggunakan Text embeddings API. Penelusuran kemiripan semantik dilakukan menggunakan Vector Search untuk menemukan perintah yang 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 cache Apigee akan diisi dengan respons tersebut. Loop masukan dibuat untuk memperbarui entri indeks Vector Search sebagai persiapan untuk permintaan mendatang.

Bagian berikut menjelaskan langkah-langkah yang diperlukan untuk membuat dan mengonfigurasi kebijakan penyimpanan dalam cache semantik:

Konfigurasikan akun layanan untuk indeks Vector Search.
Membuat dan men-deploy indeks Vector Search.
Buat proxy API untuk mengaktifkan penyimpanan dalam cache semantik.
Konfigurasikan kebijakan penyimpanan ke cache semantik.
Uji kebijakan penyimpanan data dalam cache semantik.

Mengonfigurasi akun layanan untuk indeks Vector Search

Untuk mengonfigurasi akun layanan untuk indeks Penelusuran Vektor, selesaikan langkah-langkah berikut:

Buat akun layanan menggunakan perintah berikut:

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="SERVICE_ACCOUNT_DISPLAY_NAME"

Dengan:

SERVICE_ACCOUNT_NAME adalah nama akun layanan.
DESCRIPTION adalah deskripsi akun layanan.
SERVICE_ACCOUNT_DISPLAY_NAME adalah nama tampilan akun layanan.

Contoh:

gcloud iam service-accounts create ai-client \
  --description="semantic cache client" \
  --display-name="ai-client"

Berikan peran AI Platform User ke akun layanan menggunakan perintah berikut:

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

Dengan SERVICE_ACCOUNT_NAME adalah nama akun layanan yang dibuat di langkah sebelumnya.

Tetapkan peran IAM Service Account User ke akun layanan menggunakan perintah berikut:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"

Dengan SERVICE_ACCOUNT_NAME adalah nama akun layanan yang dibuat di langkah sebelumnya.

Membuat dan men-deploy indeks Vector Search

Untuk membuat dan men-deploy indeks Vector Search:

Buat indeks Vector Search yang memungkinkan update streaming:

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 menentukan region tempat indeks Penelusuran Vektor di-deploy. Sebaiknya gunakan region yang sama dengan instance Apigee Anda. Variabel lingkungan ini ditetapkan pada langkah sebelumnya.

Setelah operasi ini selesai, Anda akan melihat respons yang mirip dengan berikut ini:

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

Untuk informasi selengkapnya tentang cara membuat indeks Vector Search, lihat Membuat indeks.

Buat IndexEndpoint menggunakan perintah berikut:

gcloud ai index-endpoints create \
  --display-name=semantic-cache-index-endpoint \
  --public-endpoint-enabled \
  --region=$REGION \
  --project=$PROJECT_ID

Langkah ini mungkin memerlukan waktu beberapa menit hingga selesai. Setelah selesai, Anda akan melihat respons yang mirip dengan berikut:

Waiting for operation [8278420407862689792]...done.
  Created Vertex AI index endpoint: projects/976063410430/locations/us-west1/indexEndpoints/7953875911424606208.

Untuk informasi selengkapnya tentang cara membuat IndexEndpoint, lihat Membuat IndexEndpoint.

Deploy indeks ke endpoint menggunakan perintah berikut:

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

Catatan: Perintah untuk men-deploy indeks ke endpoint memerlukan jq. Jika utilitas pemrosesan JSON ini belum diinstal di lingkungan pengembangan, Anda dapat menginstalnya menggunakan perintah berikut: $ sudo apt install jq.

Deployment awal indeks ke endpoint dapat memerlukan waktu antara 20 hingga 30 menit. Untuk memeriksa status operasi, gunakan perintah berikut:

gcloud ai operations describe OPERATION_ID \
  --project=$PROJECT_ID \
  --region=$REGION

Pastikan indeks di-deploy:

gcloud ai operations describe OPERATION_ID \
  --index-endpoint=$INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID

Perintah akan menampilkan $ done: true.

Membuat proxy API untuk mengaktifkan penyimpanan dalam cache semantik

Pada langkah ini, Anda akan membuat proxy API baru menggunakan template Proxy with Semantic Cache, jika belum melakukannya.

Sebelum membuat proxy API, tetapkan variabel lingkungan berikut:

export PUBLIC_DOMAIN_NAME=$(gcloud ai index-endpoints describe $INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID | grep "publicEndpointDomainName" | awk '{print $2}')

Untuk membuat proxy yang akan digunakan dengan cache semantik:

Buka halaman API proxy di Google Cloud konsol.
Buka proxy API
Klik + Buat untuk membuka panel Buat proxy API.
Di kotak Proxy template, pilih Proxy with Semantic Cache.
Masukkan detail berikut:
- Nama proxy: Masukkan nama proxy.
- Deskripsi: (Opsional) Masukkan deskripsi proxy.
- Target (API yang Ada): Masukkan URL layanan backend yang dipanggil proxy. Ini adalah endpoint model LLM yang digunakan untuk membuat konten.
  Untuk tutorial ini, Target (API yang Ada) dapat ditetapkan ke:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent
```
Masukkan URL Cache Semantik berikut:
Catatan: URL ini juga dapat ditambahkan ke konfigurasi XML di Editor proxy pada tab Develop.
- Generate Embeddings URL: Layanan Vertex AI ini mengonversi input teks menjadi bentuk numerik untuk analisis semantik.
  Untuk tutorial ini, URL ini dapat ditetapkan ke URL berikut:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/text-embedding-004:predict
```
- Kueri URL Tetangga Terdekat: Layanan Vertex AI ini menelusuri input teks yang serupa dari permintaan sebelumnya di indeks Vector Search untuk menghindari pemrosesan ulang.
  Untuk tutorial ini, URL ini dapat ditetapkan ke URL berikut:
```
PUBLIC_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/REGION/indexEndpoints/INDEX_ENDPOINT_ID:findNeighbors
```
  Nilai PUBLIC_DOMAIN_NAME dan INDEX_ENDPOINT_ID ditetapkan di langkah sebelumnya. Untuk mendapatkan nilai ini, Anda dapat menggunakan perintah berikut:
```
  echo $PUBLIC_DOMAIN_NAME
  echo $INDEX_ENDPOINT_ID
```
- URL indeks upsert: Layanan Vertex AI ini memperbarui indeks dengan entri baru atau yang diubah.
  Untuk tutorial ini, URL ini dapat ditetapkan ke URL berikut:
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints
```
Klik Berikutnya.
Klik Buat.

Konfigurasi XML proxy API dapat dilihat di tab Develop. Kebijakan SemanticCacheLookup dan SemanticCachePopulate yang berisi nilai default sudah dilampirkan ke alur permintaan dan respons proxy.

Mengonfigurasi kebijakan penyimpanan data dalam cache semantik

Anda dapat melihat konfigurasi XML setiap kebijakan dengan mengklik nama kebijakan di tampilan Detail pada tab Develop proxy API. Pengeditan pada XML kebijakan dapat dilakukan langsung di Tampilan kode pada tab Develop.

Edit kebijakan:

Kebijakan SemanticCacheLookup:
- Hapus elemen <UserPromptSource> untuk menggunakan nilai default.
- Perbarui elemen <DeployedIndexId> untuk menggunakan nilai semantic_cache.
- Konfigurasikan nilai <Threshold> kemiripan semantik untuk menentukan kapan dua perintah dianggap cocok. Nilai defaultnya adalah 0,9, tetapi Anda dapat menyesuaikan nilai ini berdasarkan sensitivitas aplikasi. Makin besar angkanya, makin dekat perintah harus terkait agar dianggap sebagai hit cache. Untuk tutorial ini, sebaiknya tetapkan nilai ini ke 0,95.
- Klik Simpan.
Kebijakan SemanticCachePopulate:
- Tetapkan elemen <TTLInSeconds> untuk menentukan jumlah detik hingga masa berlaku cache berakhir, dalam detik. Nilai defaultnya adalah 60 detik. Perhatikan bahwa Apigee akan mengabaikan header kontrol cache yang diterima dari model LLM.
- Klik Simpan.

Menambahkan autentikasi Google ke proxy API

Anda juga harus menambahkan autentikasi Google ke endpoint target proxy API untuk mengaktifkan panggilan proxy ke target.

Untuk menambahkan token akses Google:

Di tab Develop, klik default di folder Target endpoints. Tampilan kode menampilkan konfigurasi XML elemen <TargetEndpoint>.

Edit XML untuk menambahkan konfigurasi berikut di bagian <HTTPTargetConnection>:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Klik Simpan.

Men-deploy proxy API

Untuk men-deploy proxy API:

Klik Deploy untuk membuka panel Deploy API proxy.
Kolom Revisi harus ditetapkan ke 1. Jika tidak, klik 1 untuk memilihnya.
Dalam daftar Environment, pilih lingkungan tempat Anda ingin men-deploy proxy. Lingkungan harus berupa lingkungan Komprehensif.
Masukkan Akun layanan yang Anda buat di langkah sebelumnya.
Klik Deploy.

Menguji kebijakan caching semantik

Untuk menguji kebijakan penyimpanan data dalam cache semantik:

Kirim permintaan ke proxy menggunakan perintah berikut:

curl https://$RUNTIME_HOSTNAME/PROXY_NAME -H 'Content-Type: application/json' --data '{
  "contents": [
      {
          "role": "user",
          "parts": [
              {
                  "text": "Why is the sky blue?"
              }
          ]
      }
  ]
}'

Dengan PROXY_NAME adalah jalur dasar proxy API yang Anda deploy di langkah sebelumnya.

Kenapa langit berwarna biru?
Apa yang membuat langit berwarna biru?
Mengapa langit berwarna biru?
Dapatkah Anda menjelaskan mengapa langit berwarna biru?
Langit berwarna biru, mengapa demikian?

Bandingkan waktu respons untuk setiap panggilan setelah perintah serupa di-cache.

Untuk memverifikasi bahwa panggilan Anda ditayangkan dari cache, periksa header respons. Harus ada header Cached-Content: true yang dilampirkan.

Praktik terbaik

Sebaiknya sertakan praktik terbaik berikut ke program pengelolaan API Anda saat menggunakan kebijakan caching semantik:

Mencegah penyimpanan dalam cache data sensitif dengan Model Armor.
Untuk mencegah penyimpanan dalam cache data sensitif, sebaiknya gunakan Model Armor untuk pemfilteran konten. Model Armor dapat menandai respons sebagai tidak dapat di-cache jika mendeteksi informasi sensitif. Untuk informasi selengkapnya, lihat Ringkasan Model Armor.
Mengelola keaktualan data dengan pembatalan validasi titik data dan Time-to-Live (TTL) Vertex AI.
Sebaiknya terapkan strategi pembatalan validasi titik data yang sesuai untuk memastikan respons yang di-cache selalu terbaru dan mencerminkan informasi terbaru dari sistem backend Anda. Untuk mempelajari lebih lanjut, lihat Mengupdate dan mem-build ulang indeks aktif.

Anda juga dapat menyesuaikan TTL untuk respons yang di-cache berdasarkan volatilitas data dan frekuensi pembaruan. Untuk mengetahui informasi selengkapnya tentang penggunaan TTL dalam kebijakan SemanticCachePopulate, lihat <TTLInSeconds>.
Gunakan strategi penyimpanan dalam cache yang telah ditentukan untuk memastikan data respons yang paling akurat.
Sebaiknya terapkan strategi penyimpanan dalam cache standar yang mirip dengan berikut:
- Respons AI generik: Konfigurasikan TTL yang lama (misalnya, satu jam) untuk respons yang tidak spesifik per pengguna.
- Respons khusus pengguna: Jangan terapkan penyimpanan dalam cache, atau tetapkan TTL singkat (misalnya, lima menit) untuk respons yang berisi informasi khusus pengguna.
- Respons yang sensitif terhadap waktu: Konfigurasikan TTL singkat (misalnya, lima menit) untuk respons yang memerlukan pembaruan real-time atau sering.

Batasan

Batasan berikut berlaku untuk kebijakan penyimpanan dalam cache semantik:

Ukuran teks maksimum yang dapat di-cache adalah 256 KB. Untuk mengetahui informasi selengkapnya, lihat Ukuran nilai cache di halaman Batas Apigee.
Apigee akan mengabaikan header kontrol cache yang diterima dari model LLM.
Jika cache tidak dibatalkan validasinya 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 hanya didukung di wilayah tertentu. 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 penyimpanan dalam cache semantik tidak didukung untuk digunakan dengan proxy API yang menggunakan EventFlows untuk streaming respons berkelanjutan dari peristiwa yang dikirim server (SSE).
Fungsi JsonPath dalam <UserPromptSource> tidak mendukung fungsi ignoreUnresolvedVariables. Secara default, nilai null atau kosong akan diabaikan selama penerapan template pesan.

Langkah berikutnya

Pelajari cara Memulai kebijakan Model Armor.