Kebijakan SemanticCachePopulate

Ringkasan

Kebijakan SemanticCachePopulate adalah kebijakan caching lanjutan yang dirancang untuk mengoptimalkan performa beban kerja AI, terutama yang melibatkan Model Bahasa Besar (LLM).

Kebijakan ini menggunakan Text embeddings API Vertex AI untuk membuat embedding untuk teks dan Vector Search untuk meng-cache respons API berdasarkan kemiripan semantik, bukan kecocokan persis.

Kebijakan SemanticCachePopulate dapat mengurangi waktu respons untuk kueri berulang dan mengoptimalkan biaya dengan mengurangi volume panggilan ke LLM.

Kebijakan ini digunakan bersama dengan SemanticCacheLookup policy.

Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Sebelum memulai

Sebelum menggunakan kebijakan SemanticCachePopulate, Anda harus menyelesaikan tugas berikut:

  • Buat project Vertex AI.
  • Buat indeks Vector Search.
  • Buat endpoint Vertex AI untuk indeks.
  • Buat kebijakan SemanticCachePopulate.

Untuk mengetahui informasi selengkapnya tentang cara menyelesaikan tugas ini, lihat Mulai menggunakan kebijakan Semantic Caching.

Peran dan izin

Untuk mendapatkan izin yang diperlukan untuk menerapkan dan menggunakan kebijakan SemanticCachePopulate, 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.

Mengaktifkan API

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

Enable the APIs

Elemen <SemanticCachePopulate>

Menentukan kebijakan SemanticCachePopulate.

Nilai Default Lihat tab Kebijakan Default di bawah
Wajib? Wajib
Jenis Objek kompleks
Elemen Induk T/A
Elemen Turunan <DisplayName>
<IgnoreUnresolvedVariables>
<SimilaritySearch>
<TTLInSeconds>

Elemen <SemanticCachePopulate> menggunakan sintaksis berikut:

Sintaks

Elemen <SemanticCachePopulate> menggunakan sintaksis berikut:

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>{EXPIRATION_TIME_IN_SECONDS}</TTLInSeconds>
</SemanticCachePopulate>

Kebijakan Default

Contoh berikut menunjukkan setelan default saat Anda menambahkan kebijakan SemanticCachePopulate ke proxy API di UI Apigee:

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>60</TTLInSeconds>
</SemanticCachePopulate>

Saat Anda menyisipkan kebijakan SemanticCachePopulate baru di UI Apigee, template berisi stub untuk semua kemungkinan operasi. Lihat di bawah untuk mengetahui informasi tentang elemen yang diperlukan.

Elemen ini memiliki atribut berikut yang umum untuk semua kebijakan:

Atribut Default Wajib? Deskripsi
name T/A Wajib

Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter.

Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.
continueOnError false Opsional Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga:
enabled benar Opsional Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.
async   false Tidak digunakan lagi Atribut ini tidak digunakan lagi.

Tabel berikut memberikan deskripsi umum elemen turunan <SemanticCachePopulate>:

Elemen Turunan Wajib? Deskripsi
<DisplayName> Opsional Nama kebijakan.
<IgnoreUnresolvedVariables> Opsional Menentukan apakah pemrosesan berhenti saat set properti tidak terselesaikan.
<SimilaritySearch> Wajib Elemen yang berisi informasi yang diperlukan untuk memperbarui indeks vektor.

Untuk mengetahui informasi selengkapnya, lihat Memasukkan/Memperbarui titik data.

Waktu habis masa berlaku untuk titik data adalah <TTLInSeconds> sejak waktu entri.

<TTLInSeconds> Opsional Time to live (TTL) untuk respons yang di-cache, dalam hitungan detik.

Nilai defaultnya adalah 60.

Contoh

Bagian ini memberikan contoh penggunaan <SemanticCachePopulate>.

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>60</TTLInSeconds>
</SemanticCachePopulate>

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <SemanticCachePopulate>.

<DisplayName>

Gunakan selain atribut name untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama yang berbeda dan lebih terdengar alami.

Elemen <DisplayName> umum untuk semua kebijakan.

Nilai Default T/A
Wajib? Opsional. Jika Anda menghilangkan <DisplayName>, nilai atribut name kebijakan akan digunakan.
Jenis String
Elemen Induk <PolicyElement>
Elemen Turunan Tidak ada

Elemen <DisplayName> menggunakan sintaksis berikut:

Sintaks

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Contoh

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Elemen <DisplayName> tidak memiliki atribut atau elemen turunan.

<IgnoreUnresolvedVariables>

Menentukan apakah pemrosesan berhenti saat variabel tidak terselesaikan. Setel ke true untuk mengabaikan variabel yang belum terselesaikan dan melanjutkan pemrosesan.

IgnoreUnresolvedVariables tidak berlaku jika <DefaultValue> disediakan.

Nilai Default Salah
Wajib? Opsional
Jenis Boolean
Elemen Induk <SemanticCachePopulate>
Elemen Turunan Tidak ada

<SimilaritySearch>

Elemen yang berisi informasi yang diperlukan untuk memperbarui indeks vektor.

Untuk mengetahui informasi selengkapnya, lihat Memasukkan/Memperbarui titik data.

Waktu habis masa berlaku untuk titik data adalah <TTLInSeconds> sejak waktu entri.

Nilai Default T/A
Wajib? Wajib
Jenis String
Elemen Induk <SemanticCachePopulate>
Elemen Turunan <VertexAI>

Elemen <SimilaritySearch> menggunakan sintaksis berikut:

<SimilaritySearch>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
  </VertexAI>
</SimilaritySearch>

<VertexAI> (turunan dari <SimilaritySearch>)

Berisi elemen <URL> untuk atribut khusus Vertex AI.

Nilai Default T/A
Wajib? Wajib
Jenis String
Elemen Induk <SimilaritySearch>
Elemen Turunan <URL>

Elemen VertexAI menggunakan sintaksis berikut:

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

<URL> (turunan <VertexAI>)

URL yang digunakan untuk meng-upsert titik data dalam indeks vektor.

Nilai Default T/A
Wajib? Wajib
Jenis String
Elemen Induk <VertexAI>
Elemen Turunan Tidak ada

Elemen URL menggunakan sintaksis berikut:

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>

<TTLInSeconds>

Elemen yang menentukan time to live (TTL) untuk respons yang di-cache, dalam hitungan detik. Nilai defaultnya adalah 60.

Untuk mengetahui informasi selengkapnya, lihat Mengupdate dan membangun ulang indeks aktif.

Nilai Default T/A
Wajib? Opsional
Jenis String
Elemen Induk <SemanticCachePopulate>
Elemen Turunan Tidak ada

Variabel alur

Variabel alur dapat digunakan untuk mengonfigurasi perilaku runtime dinamis untuk kebijakan dan alur, berdasarkan header HTTP atau konten pesan, atau konteks yang tersedia di Alur. Untuk mengetahui informasi selengkapnya tentang variabel alur, lihat Referensi variabel alur.

Kebijakan dapat menetapkan variabel hanya baca ini selama eksekusi.

Nama variabel Deskripsi
response.content Berisi konten lengkap respons API.
semanticcache.populate.policy_name.upsert_index_request Berisi payload permintaan yang dikirim ke Vertex AI Vector Search API untuk memperbarui indeks vektor dengan embedding dan metadata baru.
semanticcache.populate.policy_name.upsert_index_response Berisi respons dari Vertex AI Vector Search API, yang menunjukkan keberhasilan atau kegagalan operasi update indeks.

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan serta variabel kesalahan yang ditetapkan oleh Apigee khusus untuk kebijakan <SemanticCachePopulate>. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

Kode kesalahan Status HTTP Penyebab
steps.semanticcachepopulate.VectorSearchUpsertServiceUnavailable 400

Error ini terjadi jika Vector Search Upsert Datapoints API tidak tersedia.
steps.semanticcache.populate.VectorSearchUpsertAPIFailed 500

Error ini terjadi jika layanan Vector Search Upsert Datapoints API gagal.
steps.semanticcache.populate.AuthenticationFailure 500

Error ini terjadi jika akun layanan tidak memiliki izin yang diperlukan.
steps.semanticcache.populate.CalloutError 500 Panggilan layanan Vertex AI gagal.
steps.semanticcache.populate.InternalError 500

Error ini terjadi jika ada error yang tidak terduga dalam kebijakan <SemanticCachePopulate>.

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Nama error Penyebab
The SimilaritySearch URL {url} is invalid. Terjadi jika elemen <URL> di <SimilaritySearch> kosong atau tidak valid.
The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https. Terjadi jika skema http elemen <URL> SimilaritySearch tidak valid.
The TTLInSeconds element must be >= 0. Jika nilai disetel ke nol atau angka negatif, deployment proxy API akan gagal.

Variabel kesalahan

Variabel ini ditetapkan saat kebijakan ini memicu error saat runtime. Untuk mengetahui informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

Variabel Di mana Contoh
fault.name="FAULT_NAME" FAULT_NAME adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. fault.name Matches "UnresolvedVariable"
semanticcachepopulate.POLICY_NAME.failed POLICY_NAME adalah nama kebijakan yang ditentukan pengguna yang menyebabkan kesalahan. semanticcachepopulate.SC-populate.failed = true

Contoh respons error

{
"fault": {
  "faultstring": "SemanticCacheLookup[SC-populate]: unable to resolve variable [variable_name]",
  "detail": {
    "errorcode": "steps.semanticcachepopulate.UnresolvedVariable"
  }
}
}

Contoh aturan kesalahan

<FaultRule name="SemanticCacheLookup Faults">
  <Step>
      <Name>SCL-CustomSetVariableErrorResponse</Name>
      <Condition>(fault.name = "SetVariableFailed")</Condition>
  </Step>
  <Condition>(semanticcachelookup.failed = true)</Condition>
</FaultRule>

Skema

Setiap jenis kebijakan ditentukan oleh skema XML (.xsd). Sebagai referensi, skema kebijakan tersedia di GitHub.