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 caching semantik Apigee untuk mengaktifkan penggunaan ulang respons cerdas berdasarkan kemiripan semantik. Menggunakan kebijakan ini di proxy API Apigee dapat meminimalkan panggilan API backend yang berlebihan, mengurangi latensi, dan menurunkan biaya operasional.

Sebelum memulai

Sebelum memulai, pastikan untuk menyelesaikan tugas berikut:

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

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

    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.

    Enable the APIs

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

    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.

    Enable the APIs

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

    10. Peran yang diperlukan

    Untuk mendapatkan izin yang diperlukan untuk membuat dan menggunakan kebijakan caching semantik, minta administrator Anda untuk memberi Anda peran IAM Pengguna AI Platform (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

    Di project Google Cloud yang berisi instance Apigee, 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

    Tetapkan Google Cloud project di lingkungan pengembangan Anda: 

        gcloud auth login
    gcloud config set project $PROJECT_ID

    Ringkasan

    Kebijakan caching semantik dirancang untuk membantu pengguna Apigee dengan model LLM agar dapat secara cerdas menayangkan perintah yang identik atau serupa secara semantik secara efisien, 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 akan mengekstrak perintah pengguna dari permintaan dan mengonversi perintah menjadi representasi numerik menggunakan Text embeddings API. Penelusuran kesamaan 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 ke klien.

    Jika penelusuran kemiripan tidak menampilkan perintah sebelumnya yang serupa, model LLM akan membuat 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 semantik:

    1. Konfigurasi akun layanan untuk indeks Vector Search.
    2. Buat dan deploy indeks Vector Search.
    3. Buat proxy API untuk mengaktifkan caching semantik.
    4. Konfigurasi kebijakan caching semantik.
    5. Uji kebijakan penyimpanan data dalam cache semantik.

    Mengonfigurasi akun layanan untuk indeks Vector Search

    Untuk mengonfigurasi akun layanan untuk indeks Vector Search, selesaikan langkah-langkah berikut:

    1. 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"
    2. Berikan peran AI Platform User kepada 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 pada langkah sebelumnya.

    3. 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 pada langkah sebelumnya.

    Membuat dan men-deploy indeks Vector Search

    Untuk membuat dan men-deploy indeks Vector Search:

    1. 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 Anda menggunakan 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: 

      {
  "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 mengetahui informasi selengkapnya tentang cara membuat indeks Vector Search, lihat Membuat indeks.

    2. 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 untuk diselesaikan. 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 mengetahui informasi selengkapnya tentang cara membuat IndexEndpoint, lihat Membuat IndexEndpoint.

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

    Deployment awal indeks ke endpoint dapat memerlukan waktu antara 20 hingga 30 menit hingga selesai. 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 caching semantik

    Pada langkah ini, Anda akan membuat proxy API baru menggunakan template Proxy dengan Cache Semantik, jika Anda 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 penyimpanan semantik:

    1. Buka halaman API proxies di konsol Google Cloud .

      Buka proxy API

    2. Klik + Create untuk membuka panel Create API proxy.
    3. Di kotak Proxy template, pilih Proxy with Semantic Cache.
    4. 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
    5. Masukkan URL Cache Semantik berikut:
      • URL Pembuatan Embedding: Layanan Vertex AI ini mengonversi input teks menjadi bentuk numerik untuk analisis semantik.

        Untuk tutorial ini, URL ini dapat disetel ke berikut ini: 

        REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/text-embedding-004:predict
      • URL Kueri Elemen Terdekat: Layanan Vertex AI ini menelusuri input teks serupa dari permintaan sebelumnya dalam indeks Vector Search untuk menghindari pemrosesan ulang.

        Untuk tutorial ini, URL ini dapat disetel ke berikut ini: 

        PUBLIC_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/REGION/indexEndpoints/INDEX_ENDPOINT_ID:findNeighbors

        Nilai PUBLIC_DOMAIN_NAME dan INDEX_ENDPOINT_ID ditetapkan pada 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 disetel ke berikut ini: 

        REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints
    6. Klik Berikutnya.
    7. 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.
      • Konfigurasi nilai kemiripan semantik <Threshold> untuk menentukan kapan dua perintah dianggap cocok. Nilai defaultnya adalah 0,9, tetapi Anda dapat menyesuaikan nilai ini berdasarkan sensitivitas aplikasi Anda. Makin besar angkanya, makin erat hubungan antara perintah yang harus ada agar dianggap sebagai cache ditemukan. Untuk tutorial ini, sebaiknya setel 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 cache-control yang diterimanya 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:

    1. Di tab Develop, klik default di folder Target endpoints. Tampilan kode menampilkan konfigurasi XML elemen <TargetEndpoint>.
    2. Edit XML untuk menambahkan konfigurasi berikut di bagian <HTTPTargetConnection>: 
      <Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>
    3. Klik Simpan.

    Men-deploy proxy API

    Untuk men-deploy proxy API:

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

    Menguji kebijakan caching semantik

    Untuk menguji kebijakan penyimpanan data dalam cache semantik:

    1. 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 basepath proxy API yang Anda deploy pada langkah sebelumnya.

      2. Ulangi panggilan API, dengan mengganti string perintah dengan string perintah yang serupa secara semantik berikut:
      • Kenapa langit warnanya biru?
      • Apa yang membuat langit berwarna biru?
      • Mengapa langit berwarna biru?
      • Dapatkah Anda menjelaskan mengapa langit berwarna biru?
      • Langit berwarna biru, mengapa demikian?
    2. Bandingkan waktu respons untuk setiap panggilan setelah perintah serupa di-cache.

    Untuk memverifikasi bahwa panggilan Anda ditayangkan dari cache, periksa header respons. Header Cached-Content: true harus dilampirkan.

    Praktik terbaik

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

    • Mencegah penyimpanan data sensitif dalam cache dengan Model Armor.

      Untuk mencegah penyimpanan data sensitif dalam cache, sebaiknya gunakan Model Armor untuk pemfilteran konten. Model Armor dapat menandai respons sebagai tidak dapat di-cache jika mendeteksi informasi sensitif. Untuk mengetahui informasi selengkapnya, lihat Ringkasan Model Armor.

    • Mengelola keaktualan data dengan pembatalan validitas titik data Vertex AI dan Time-to-Live (TTL).

      Sebaiknya terapkan strategi pembatalan 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 membangun 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 caching yang telah ditentukan sebelumnya yang mirip dengan berikut ini:

      • Respons AI generik: Konfigurasi TTL yang panjang (misalnya, satu jam) untuk respons yang tidak spesifik per pengguna.
      • Respons khusus pengguna: Jangan menerapkan caching, atau tetapkan TTL singkat (misalnya, lima menit) untuk respons yang berisi informasi khusus pengguna.
      • Respons yang sensitif terhadap waktu: Konfigurasi TTL singkat (misalnya, lima menit) untuk respons yang memerlukan update real-time atau sering.

    Batasan

    Batasan berikut berlaku untuk kebijakan penyimpanan 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 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).
    • Fungsi JsonPath dalam <UserPromptSource> tidak mendukung fungsi ignoreUnresolvedVariables. Secara default, nilai null atau kosong diabaikan selama penerapan template pesan.