Kebijakan PromptTokenLimit

Halaman ini berlaku untuk Apigee, tetapi tidak untuk Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Ringkasan

Kebijakan PromptTokenLimit melindungi backend Model Bahasa Besar (LLM) dari lonjakan traffic dengan membatasi jumlah token dalam perintah pengguna.

Kebijakan PromptTokenLimit mirip dengan kebijakan SpikeArrest; namun; kebijakan SpikeArrest membatasi jumlah permintaan, sedangkan kebijakan PromptTokenLimit membatasi jumlah token dalam permintaan tersebut. Kebijakan ini secara khusus disesuaikan untuk aplikasi LLM yang biaya dan performa terkait langsung dengan jumlah token yang diproses.

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.

Perbedaan antara PromptTokenLimit dan LLMTokenQuota

Kebijakan PromptTokenLimit digunakan untuk pengelolaan traffic operasional guna mencegah lonjakan penggunaan token secara tiba-tiba. Sebaliknya, kebijakan LLMTokenQuota digunakan untuk menerapkan batas penggunaan pada aplikasi klien selama jangka waktu yang lebih lama (seperti jam, hari, atau bulan) untuk mengelola biaya dan menerapkan perjanjian bisnis.

Elemen PromptTokenLimit

Menentukan kebijakan PromptTokenLimit.

Nilai Default Lihat tab Kebijakan Default di bawah
Wajib? Opsional
Jenis Objek kompleks
Elemen Induk T/A
Elemen Turunan <Identifier>
<Rate> (Wajib)
<UseEffectiveCount>
<UserPromptSource>
<IgnoreUnresolvedVariables>

Sintaksis

Elemen PromptTokenLimit menggunakan sintaksis berikut:

<PromptTokenLimit continueOnError="false" enabled="true" name="POLICY_NAME">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref=""/>
  <Rate ref="">[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</PromptTokenLimit>

Kebijakan Default

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

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref=""/>
  <Rate ref="">[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</PromptTokenLimit>

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.

Contoh

Contoh berikut menunjukkan beberapa cara Anda dapat menggunakan kebijakan PromptTokenLimit:

Contoh 1

Pembatasan Token Prompt dalam satu replika.

Dalam contoh ini, pembatasan token perintah terjadi dalam satu replika dan tidak didistribusikan di beberapa pemroses pesan dalam suatu region. 

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref="request.url"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Contoh 2

Pembatasan Token yang didistribusikan.

Dalam contoh ini, pembatasan token perintah didistribusikan di beberapa replika dalam suatu region, dan algoritma pembatasan frekuensi "sliding window" diterapkan.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref="request.url"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

Contoh 3

Pembatasan token ukuran jendela konteks per permintaan.

Dalam contoh ini, pembatasan token perintah terjadi dalam satu replika dan tidak didistribusikan di beberapa pemroses pesan dalam satu region. Konfigurasi khusus ini digunakan untuk ukuran jendela konteks pembatasan token per permintaan.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.messages',request.content,true)}</UserPromptSource>
  <Identifier ref="messageid"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Contoh 4

Pembatasan Token yang Didistribusikan dengan nilai default.

Dalam contoh ini, pembatasan token perintah terjadi dalam satu replika dan tidak didistribusikan di beberapa pemroses pesan dalam satu region. Nilai default sumber perintah pengguna digunakan: {jsonPath('$.messages',request.content,true)} 

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <Identifier ref="messageid"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <PromptTokenLimit>.

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

<Identifier>

Memungkinkan Anda memilih cara mengelompokkan permintaan sehingga kebijakan PromptTokenLimit dapat diterapkan berdasarkan klien. Misalnya, Anda dapat mengelompokkan permintaan berdasarkan ID developer, yang dalam hal ini setiap permintaan developer akan dihitung dalam batas PromptTokenLimit mereka sendiri, bukan semua permintaan ke proxy.

Jika Anda mengosongkan elemen <Identifier>, satu batas frekuensi akan diterapkan untuk semua permintaan ke proxy API tersebut.

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

Sintaksis

<PromptTokenLimit
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="POLICY_NAME"
>
  <Identifier ref="FLOW_VARIABLE"/>
</PromptTokenLimit>

Contoh 1

Contoh berikut menerapkan kebijakan PromptTokenLimit per ID developer:

<PromptTokenLimit name="PTL-limitTokens-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

Tabel berikut menjelaskan atribut <Identifier>:

Atribut Deskripsi Default Kehadiran
ref Mengidentifikasi variabel yang digunakan PromptTokenLimit untuk mengelompokkan permintaan masuk. Anda dapat menggunakan variabel alur apa pun untuk menunjukkan klien yang unik, seperti yang tersedia dengan kebijakan VerifyAPIKey. Anda juga dapat menetapkan variabel kustom menggunakan kebijakan JavaScript atau kebijakan AssignMessage. T/A Wajib

<Rate>

Menentukan kecepatan untuk membatasi lonjakan (atau burst) token dengan menetapkan jumlah token yang diizinkan dalam interval per menit atau per detik. Anda dapat menggunakan elemen ini bersama dengan <Identifier> untuk mengatur traffic secara lancar saat runtime dengan menerima nilai dari klien. Gunakan elemen <UseEffectiveCount> untuk menetapkan algoritma pembatasan kecepatan yang digunakan oleh kebijakan.

Nilai Default T/A
Wajib? Wajib
Jenis Bilangan bulat
Elemen Induk <PromptTokenLimit>
Elemen Turunan Tidak ada

Sintaksis

Anda dapat menentukan tarif dengan salah satu cara berikut:

  • Tarif statis yang Anda tentukan sebagai isi elemen <Rate>
  • Nilai variabel, yang dapat diteruskan oleh klien; identifikasi nama variabel alur menggunakan atribut ref
<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME"
>
  <Rate ref="FLOW_VARIABLE">RATE[pm|ps]</Rate>
</PromptTokenLimit>

Nilai tarif yang valid (baik ditentukan sebagai nilai variabel atau di isi elemen) harus sesuai dengan format berikut:

  • intps (jumlah token per detik, dihaluskan menjadi interval milidetik)
  • intpm (jumlah token per menit, dihaluskan ke dalam interval detik)

Nilai int harus berupa bilangan bulat positif bukan nol.

Contoh 1

Contoh berikut menetapkan kecepatan ke lima token per detik:

<PromptTokenLimit name="PTL-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Kebijakan ini memperlancar laju ke satu token yang diizinkan setiap 200 milidetik (1000/5).

Contoh 2

Contoh berikut menetapkan kecepatan ke 12 token per menit:

<PromptTokenLimit name="PTL-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Contoh kebijakan ini memperlancar laju ke satu token yang diizinkan setiap lima detik (60/12).

Tabel berikut menjelaskan atribut <Rate>:

Atribut Deskripsi Kehadiran Default
ref Mengidentifikasi variabel alur yang menentukan tarif. Hal ini dapat berupa variabel alur apa pun, seperti parameter kueri HTTP, header, atau konten isi pesan, atau nilai seperti KVM. Untuk mengetahui informasi selengkapnya, lihat Referensi variabel alur.

Anda juga dapat menggunakan variabel kustom menggunakan kebijakan JavaScript atau kebijakan AssignMessage.

Jika Anda menentukan ref dan isi elemen ini, nilai ref akan diterapkan dan diprioritaskan saat variabel alur ditetapkan dalam permintaan. (Kebalikannya berlaku jika variabel yang diidentifikasi dalam ref tidak ditetapkan dalam permintaan.)

Contoh:

<Rate ref="request.header.custom_rate">1pm</Rate>

Dalam contoh ini, jika klien tidak meneruskan header custom_rate, maka laju untuk proxy API adalah 1 token per menit untuk semua klien. Jika klien meneruskan header custom_rate, yang nilainya adalah 10ps, untuk semua klien di proxy — hingga permintaan tanpa header custom_rate dikirim.

Anda dapat menggunakan <Identifier> untuk mengelompokkan permintaan guna menerapkan tarif kustom untuk berbagai jenis klien.

Jika Anda menentukan nilai untuk ref, tetapi tidak menetapkan tarif di isi elemen <Rate> dan klien tidak meneruskan nilai, kebijakan PromptTokenLimit akan menampilkan error.

 Opsional T/A
Tabel berikut menjelaskan atribut Rate yang menentukan perilaku pembatasan traffic:
Atribut Deskripsi
messagesPerPeriod Menentukan jumlah token yang diizinkan dalam periode yang ditentukan. Misalnya, jika kebijakan dikonfigurasi untuk '10ps' (10 token per detik), nilai messagesPerPeriod adalah 10.
periodInMicroseconds Menentukan jangka waktu, dalam mikrodetik, yang digunakan untuk menghitung messagesPerPeriod. Untuk konfigurasi '10ps', nilai ini adalah 1.000.000, yang setara dengan satu detik.
maxBurstMessageCount Mewakili jumlah maksimum token yang dapat diizinkan secara instan atau dalam burst singkat di awal interval baru.

<UseEffectiveCount>

Elemen ini memungkinkan Anda memilih antara algoritma PromptTokenLimit yang berbeda dengan menyetel nilai ke true atau false, seperti yang dijelaskan di bawah:

true

Jika disetel ke true, PromptTokenLimit didistribusikan di suatu wilayah. Artinya, jumlah permintaan disinkronkan di seluruh pemroses pesan (MP) dalam suatu region. Selain itu, algoritma pembatasan kapasitas "sliding window" diterapkan. Algoritma ini memberikan perilaku pembatasan kapasitas yang konsisten dan tidak "memperlancar" jumlah permintaan masuk yang dapat dikirim ke backend. Jika serangkaian permintaan dikirim dalam interval waktu yang singkat, permintaan tersebut diizinkan selama tidak melebihi batas frekuensi yang dikonfigurasi, sebagaimana ditetapkan dalam elemen <Rate>. Contoh:

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

false (default)

Jika disetel ke false (default), kebijakan PromptTokenLimit menggunakan algoritma "token bucket" yang memperlancar lonjakan token dengan membagi batas laju yang Anda tentukan ke dalam interval yang lebih kecil. Kekurangan dari pendekatan ini adalah beberapa token yang sah yang masuk dalam interval waktu singkat berpotensi ditolak.

Misalnya, Anda memasukkan kecepatan 30pm (30 token per menit). Dalam pengujian, Anda mungkin berpikir bahwa Anda dapat mengirim 30 token dalam 1 detik, selama token tersebut masuk dalam waktu satu menit. Namun, bukan begitu cara kebijakan menerapkan setelan. Jika dipikir-pikir, 30 token dalam jangka waktu 1 detik dapat dianggap sebagai lonjakan kecil di beberapa lingkungan.

  • Rasio per menit akan disesuaikan menjadi permintaan penuh yang diizinkan dalam interval detik.

    Misalnya, 30pm di-smoothing seperti ini:
    60 detik (1 menit) / 30pm = interval 2 detik, atau 1 token diizinkan setiap 2 detik. Token kedua dalam waktu 2 detik akan gagal. Selain itu, token ke-31 dalam satu menit akan gagal.

  • Kecepatan per detik dihaluskan menjadi permintaan penuh yang diizinkan dalam interval milidetik.

    Misalnya, 10ps di-smoothing seperti ini:
    1.000 milidetik (1 detik) / 10ps = interval 100 milidetik, atau 1 token diizinkan setiap 100 milidetik. Token kedua dalam waktu 100 md akan gagal. Selain itu, token ke-11 dalam satu detik akan gagal.

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

Tabel berikut menjelaskan atribut elemen <UseEffectiveCount>:

Atribut Deskripsi Default Kehadiran
ref Mengidentifikasi variabel yang berisi nilai <UseEffectiveCount>. Nilai ini dapat berupa variabel alur apa pun, seperti parameter kueri HTTP, header, atau konten isi pesan. Untuk mengetahui informasi selengkapnya, lihat Referensi variabel alur. Anda juga dapat menetapkan variabel kustom menggunakan kebijakan JavaScript atau kebijakan AssignMessage. T/A Opsional

<UserPromptSource>

Menyediakan sumber untuk mengambil teks perintah pengguna. Gunakan template pesan.

Template pesan harus memberikan satu nilai teks perintah pengguna.

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

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

Sintaksis

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME">
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

Contoh 1

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

<IgnoreUnresolvedVariables>

Menentukan apakah pemrosesan berhenti saat variabel yang belum diselesaikan ditemukan.

Setel ke true untuk mengabaikan variabel yang belum diselesaikan dan melanjutkan pemrosesan; jika tidak false. Nilai defaultnya adalah false.

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

Sintaksis

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME">
  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</PromptTokenLimit>

Contoh

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <Rate>10ps</Rate>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PromptTokenLimit>

Variabel alur

Saat kebijakan PromptTokenLimit dijalankan, variabel alur berikut akan diisi:

Variabel Jenis Izin Deskripsi
ratelimit.POLICY_NAME.failed Boolean Hanya Baca Menunjukkan apakah kebijakan gagal atau tidak (true atau false).
ratelimit.POLICY_NAME.resolvedUserPrompt String Hanya Baca Menampilkan perintah pengguna yang diekstrak.
ratelimit.POLICY_NAME.userPromptSource String Hanya Baca Menampilkan template pesan untuk perintah pengguna yang ditentukan dalam kebijakan.
ratelimit.POLICY_NAME.userPromptTokenCount String Hanya Baca Menampilkan jumlah token perintah pengguna yang diekstrak.

Untuk mengetahui informasi selengkapnya, lihat Referensi variabel alur.

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan serta variabel kesalahan yang ditetapkan oleh Apigee saat kebijakan ini memicu error. Anda juga dapat melihat Error kebijakan SpikeArrest. 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 Kesalahan Apigee Penyebab Perbaiki
policies.prompttokenlimit.FailedToExtractUserPrompt 400 FALSE Tidak dapat mengekstrak perintah pengguna dari permintaan API.
policies.prompttokenlimit.PromptTokenLimitViolation 429 FALSE Pelanggaran PromptTokenLimit.
policies.prompttokenlimit.FailedToCalculateUserPromptTokens 500 TRUE Token tidak dapat dihitung untuk perintah pengguna.

Error saat deployment

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

Kode kesalahan Status HTTP Kesalahan Apigee Penyebab Perbaiki
policies.prompttokenlimit.MessageWeightNotSupported 500 FALSE MessageWeight tidak didukung untuk kebijakan PromptTokenLimit.

Variabel kesalahan

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

Variabel Di mana Contoh
ratelimit.policy_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 "PromptTokenLimitViolation"
ratelimit.policy_name.failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menyebabkan kesalahan. ratelimit.PTL-PromptTokenLimitPolicy.failed = true

Contoh respons error

Di bawah ini adalah contoh respons error:

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.prompttokenlimit.PromptTokenLimitViolation"
      },
      "faultstring":"Prompt Token Limit Violation. Allowed rate : MessageRate{capacity=10, period=Minutes}"
   }
}

Contoh aturan kesalahan

Di bawah ini adalah contoh aturan kesalahan untuk menangani kesalahan PromptTokenLimitViolation:

<FaultRules>
    <FaultRule name="Prompt Token Limit Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "PromptTokenLimitViolation") </Condition>
        </Step>
        <Condition>ratelimit.PTL-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

Kode status HTTP saat ini untuk melampaui batas laju yang ditetapkan oleh kebijakan LLMTokenQuota atau PromptTokenLimit adalah 429 (Terlalu Banyak Permintaan).

Skema

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

Topik terkait