Halaman ini diterjemahkan oleh Cloud Translation API.

Kebijakan SemanticCacheLookup

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Ringkasan

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

Kebijakan ini menggunakan Text Embeddings API Vertex AI untuk membuat embedding teks dan Vector Search untuk menemukan perintah serupa berdasarkan kemiripan semantik, bukan kecocokan persis.

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

Kebijakan ini digunakan bersama dengan SemanticCachePopulate 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 SemanticCacheLookup, 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 yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk menerapkan dan menggunakan kebijakan SemanticCacheLookup, minta administrator 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 `<SemanticCacheLookup>`

Menentukan kebijakan SemanticCacheLookup.

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

Elemen <SemanticCacheLookup> menggunakan sintaksis berikut:

Sintaks

Elemen <SemanticCacheLookup> menggunakan sintaksis berikut:

<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

Kebijakan Default

Contoh berikut menunjukkan setelan default saat Anda menambahkan kebijakan SemanticCacheLookup ke alur di UI Apigee:

<SemanticCacheLookup async="false" continueOnError="false"enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict
      </URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <Threshold>0.9</Threshold>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

Saat Anda menyisipkan kebijakan SemanticCacheLookup baru di UI Apigee, template akan 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: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani error dalam alur saat ini
`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 <SemanticCacheLookup>:

Elemen Turunan	Wajib?	Deskripsi
`<DisplayName>`	Opsional	Nama kebijakan.
`<IgnoreUnresolvedVariables>`	Opsional	Menentukan apakah pemrosesan berhenti saat variabel tidak terselesaikan. Setel ke `true` untuk mengabaikan variabel yang belum terselesaikan dan melanjutkan pemrosesan.
`<UserPromptSource>`	Opsional	Lokasi payload untuk teks perintah pengguna yang akan diekstrak. Hanya nilai teks string yang didukung. Kolom ini mendukung sintaksis template pesan Apigee, termasuk penggunaan variabel atau fungsi JSON Path. Contoh: {jsonPath($.contents[-1].parts[-1].text,request.content,true)}
`<Embeddings>`	Wajib	Elemen yang berisi informasi yang diperlukan untuk membuat penyematan.
`<SimilaritySearch>`	Wajib	Elemen yang berisi informasi yang diperlukan untuk melakukan penelusuran kemiripan. Untuk mengetahui informasi selengkapnya, lihat Membuat kueri indeks publik untuk mendapatkan tetangga terdekat.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <SemanticCacheLookup>.

`<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	`<SemanticCacheLookup>`
Elemen Turunan	Tidak ada

`<UserPromptSource>`

Lokasi payload untuk teks perintah pengguna yang akan diekstrak. Hanya nilai teks string yang didukung.

Kolom ini mendukung sintaksis template pesan Apigee, termasuk penggunaan variabel atau fungsi JSON Path.

Contoh:

{jsonPath($.contents[-1].parts[-1].text,request.content,true)}

Nilai Default	{jsonPath($.contents[-1].parts[-1].text,request.content,true)}
Wajib?	Opsional
Jenis	String
Elemen Induk	`<SemanticCacheLookup>`
Elemen Turunan	Tidak ada

`<Embeddings>`

Elemen ini berisi informasi yang diperlukan untuk membuat embedding teks.

Nilai Default	T/A
Wajib?	Opsional
Jenis	String
Elemen Induk	`<SemanticCacheLookup>`
Elemen Turunan	`<VertexAI>`

Elemen <Embeddings> menggunakan sintaksis berikut:

<Embeddings>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
  </VertexAI>
</Embeddings>

<VertexAI> (turunan dari `<Embeddings>`)

Berisi elemen <URL> untuk atribut khusus Vertex AI.

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

Elemen VertexAI menggunakan sintaksis berikut:

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
</VertexAI>

<URL> (turunan `<VertexAI>`)

URL yang digunakan untuk membuat embedding teks. Lihat Model yang didukung untuk mengetahui daftar model yang dapat memberikan embedding teks untuk kebijakan SemanticCacheLookup.

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}/publishers/google/models/{MODEL_ID}:predict</URL>

`<SimilaritySearch>`

Elemen ini berisi informasi yang diperlukan untuk melakukan penelusuran kemiripan.

Untuk mengetahui informasi selengkapnya, lihat Membuat kueri indeks publik untuk mendapatkan tetangga terdekat.

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

Elemen <SimilaritySearch> menggunakan sintaksis berikut:

<SimilaritySearch>
  <VertexAI>
    <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors
    </URL>
    <Threshold>0.9</Threshold>
    <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
  </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://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
  <Threshold>0.9</Threshold>
  <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>

Tabel berikut memberikan deskripsi umum elemen turunan <VertexAI>.

Elemen Turunan Wajib? Deskripsi

Elemen Turunan	Wajib?	Deskripsi
`<URL>`	Wajib	String URL yang digunakan untuk melakukan penelusuran kemiripan. Titik data yang paling cocok, berdasarkan nilai minimum kemiripan, akan menjadi satu-satunya titik data yang digunakan.
`<Threshold>`	Opsional	String Skor kemiripan yang digunakan untuk menentukan apakah dua perintah dianggap cocok. Nilai antara 0 dan 1. Nilai defaultnya adalah 0,9.
`<DeployedIndexID>`	Wajib	String ID indeks yang di-deploy di endpoint indeks yang digunakan untuk penyimpanan semantik.

<URL>

Wajib

String

URL yang digunakan untuk melakukan penelusuran kemiripan. Titik data yang paling cocok, berdasarkan nilai minimum kemiripan, akan menjadi satu-satunya titik data yang digunakan.

<Threshold>

Opsional

String

Skor kemiripan yang digunakan untuk menentukan apakah dua perintah dianggap cocok. Nilai antara 0 dan 1.

Nilai defaultnya adalah 0,9.

<DeployedIndexID>

Wajib

String

ID indeks yang di-deploy di endpoint indeks yang digunakan untuk penyimpanan semantik.

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
`request.content`	Berisi konten lengkap permintaan API masuk.
`request.url`	Berisi URL permintaan API masuk.
`semanticcache.lookup.policy_name.user_prompt`	Berisi komponen spesifik yang diekstrak dari perintah permintaan, yang digunakan untuk membuat embedding atau melakukan penelusuran kemiripan.
`semanticcache.lookup.policy_name.embeddings_request`	Berisi payload permintaan yang dikirim ke Vertex AI Embeddings API untuk membuat embedding teks untuk teks input.
`semanticcache.lookup.policy_name.embeddings_response`	Berisi respons dari Vertex AI Embeddings API, yang mencakup embedding teks yang dihasilkan.
`semanticcache.lookup.policy_name.dense_embeddings`	Berisi nilai embedding numerik aktual yang dihasilkan oleh Vertex AI Embeddings API.
`semanticcache.lookup.policy_name.is_nearest_neighbor_hit`	Menentukan apakah tetangga terdekat ditemukan di database vektor untuk permintaan tertentu dan titik data memenuhi nilai minimum kemiripan.
`semanticcache.lookup.policy_name.cache_hit`	Menentukan apakah respons ditemukan di cache semantik.
`semanticcache.lookup.policy_name.cached_llm_response`	Berisi respons yang diambil dari cache semantik (jika terjadi hit cache).

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan serta variabel kesalahan yang ditetapkan oleh Apigee khusus untuk kebijakan <SemanticCacheLookup>. 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.semanticcache.lookup.MessageTemplateExtractionFailed`	`400`	Gagal mengekstrak data dari permintaan menggunakan ekspresi JSON Path.
`steps.semanticcache.lookup.FailedToExtractUserPrompt`	`500`	Tidak dapat mengekstrak perintah pengguna dari permintaan API.
`steps.semanticcache.lookup.EmbeddingsServiceUnavailable`	`400`	Layanan Vertex AI Embeddings saat ini tidak tersedia.
`steps.semanticcache.lookup.EmbeddingsAPIFailed`	`400`	Layanan Vertex AI Embeddings gagal.
`steps.semanticcache.lookup.VectorSearchServiceUnavailable`	`400`	Layanan Vertex AI Vector Search saat ini tidak tersedia.
`steps.semanticcache.lookup.VectorSearchAPIFailed`	`400`	Layanan Vertex AI Vector Search gagal.
`steps.semanticcache.lookup.AuthenticationFailure`	`500`	Akun layanan tidak memiliki izin yang diperlukan.
`steps.semanticcache.lookup.InternalError`	`500`	Terjadi error yang tidak terduga dalam kebijakan SemanticCacheLookup.
`steps.semanticcache.lookup.CalloutError`	`500`	Panggilan layanan Vertex AI gagal.

Error saat deployment

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

Nama error	Penyebab
`The Embeddings/VertexAI element is required.`	Terjadi jika elemen <VertexAI> di <Embeddings> kosong.
`The SimilaritySearch/VertexAI element is required.`	Terjadi jika elemen <VertexAI> di <SimilaritySearch> kosong.
`The Embeddings/URL element is required.`	Terjadi jika elemen <URL> di <Embeddings> kosong.
`The SimilaritySearch/URL element is required.`	Terjadi jika elemen <URL> di <SimilaritySearch> kosong.
`Embeddings URL {url} is invalid.`	Terjadi jika elemen <URL> di <Embeddings> kosong atau tidak valid.
`The SimilaritySearch URL {url} is invalid.`	Terjadi jika elemen <URL> di <SimilaritySearch> kosong atau tidak valid.
`The scheme {http-scheme} of Embeddings URL {url} must be one of http, https.`	Terjadi jika skema `http` elemen Embeddings <URL> 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.
`SimilaritySearch/Threshold element must be >= 0 and <= 1.`	Jika atribut tidak berada di antara 0 dan 1, deployment proxy API akan gagal.
`SimilaritySearch/DeployedIndexID element is required.`	Terjadi jika elemen <DeployedIndexID> di <SimilaritySearch> kosong.
`SimilaritySearch/DeployedIndexID element must not contain spaces.`	Terjadi jika elemen <DeployedIndexID> dalam <SimilaritySearch> berisi spasi.

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"`
`semanticcachelookup.POLICY_NAME.failed`	`POLICY_NAME` adalah nama kebijakan yang ditentukan pengguna yang menyebabkan kesalahan.	`semanticcachelookup.SC-lookup.failed = true`

Contoh respons error

Catatan: Untuk penanganan error, praktik terbaiknya adalah menangkap bagian errorcode dari respons error. Jangan mengandalkan teks di faultstring, karena dapat berubah.

{
  "fault": {
    "faultstring": "SemanticCacheLookup[SC-lookup]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.semanticcachelookup.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.

Kebijakan SemanticCacheLookup Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Ringkasan

Sebelum memulai

Peran yang diperlukan

Mengaktifkan API

Elemen <SemanticCacheLookup>

Sintaks

Kebijakan Default

Referensi elemen turunan

<DisplayName>

Sintaks

Contoh

<IgnoreUnresolvedVariables>

<UserPromptSource>

<Embeddings>

<VertexAI> (turunan dari <Embeddings>)

<URL> (turunan <VertexAI>)

<SimilaritySearch>

<VertexAI> (turunan dari <SimilaritySearch>)

Variabel alur

Referensi error

Error runtime

Error saat deployment

Variabel kesalahan

Contoh respons error

Contoh aturan kesalahan

Skema

Kebijakan SemanticCacheLookup

Elemen `<SemanticCacheLookup>`

`<DisplayName>`

`<UserPromptSource>`

`<Embeddings>`

<VertexAI> (turunan dari `<Embeddings>`)

<URL> (turunan `<VertexAI>`)

`<SimilaritySearch>`

<VertexAI> (turunan dari `<SimilaritySearch>`)