Kebijakan PromptTokenLimit

Kebijakan yang dapat diperluas

Halaman ini berlaku untuk Apigee dan 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 dirancang khusus untuk aplikasi LLM yang biaya dan performanya terkait langsung dengan jumlah token yang diproses.

Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau pemanfaatan, 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 yang tiba-tiba. Sebaliknya, kebijakan LLMTokenQuota digunakan untuk menerapkan batas penggunaan pada aplikasi klien dalam 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 menggunakan kebijakan PromptTokenLimit:

Contoh 1

Pembatasan Token Perintah dalam satu replika.

Dalam contoh ini, pembatasan token perintah terjadi dalam satu replika dan tidak didistribusikan di beberapa pemroses pesan dalam satu 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 Terdistribusi.

Dalam contoh ini, pembatasan token perintah didistribusikan di beberapa replika dalam suatu region, dan algoritma pembatasan kecepatan "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 suatu 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 terdistribusi dengan nilai default.

Dalam contoh ini, pembatasan token perintah terjadi dalam satu replika dan tidak didistribusikan di beberapa pemroses pesan dalam suatu 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 berdasarkan tarif PromptTokenLimit mereka sendiri, bukan semua permintaan ke proxy.

Jika Anda mengosongkan elemen <Identifier>, satu pembatasan kapasitas 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 flow variable apa pun untuk menunjukkan klien unik, seperti yang tersedia dengan kebijakan VerifyAPIKey. Anda juga dapat menetapkan variabel kustom menggunakan kebijakan JavaScript atau kebijakan AssignMessage. T/A Wajib

<Rate>

Menentukan kapasitas 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 membatasi traffic dengan lancar saat runtime dengan menerima nilai dari klien. Gunakan elemen <UseEffectiveCount> untuk menetapkan algoritma pembatasan kapasitas 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 flow variable 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 yang ditentukan sebagai nilai variabel atau dalam isi elemen) harus sesuai dengan format berikut:

  • intps (jumlah token per detik, dihaluskan menjadi interval milidetik)
  • intpm (jumlah token per menit, dihaluskan menjadi 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 memperhalus kapasitas menjadi satu token yang diizinkan setiap 200 milidetik (1000/5).

Contoh 2

Contoh berikut menetapkan kapasitas 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 flow variable yang menentukan tarif. Ini bisa 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, tarif 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> guna mengelompokkan permintaan untuk menerapkan tarif kustom bagi 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 akan menjadi 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 menetapkan nilai ke true atau false, seperti yang dijelaskan di bawah:

true

Jika ditetapkan ke true, PromptTokenLimit akan didistribusikan di suatu region. Artinya, jumlah permintaan disinkronkan di seluruh pemroses pesan (MP) di 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 burst permintaan dikirim dalam interval waktu yang singkat, permintaan tersebut diizinkan selama tidak melebihi batas kapasitas yang dikonfigurasi, seperti yang 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. Kelemahan 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 periode 1 detik dapat dianggap sebagai lonjakan kecil di beberapa lingkungan.

  • Rasio per menit dihaluskan 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 akan dihaluskan 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>. Ini dapat berupa variabel flow 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 akan berhenti saat variabel yang belum terselesaikan ditemukan.

Setel ke true untuk mengabaikan variabel yang belum terselesaikan 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 dieksekusi, flow variable berikut akan diisi:

Variabel Jenis Izin Deskripsi
ratelimit.POLICY_NAME.failed Boolean Hanya Baca Variabel ini adalah true jika kebijakan mengalami kegagalan eksekusi internal. Variabel ini tidak boleh digunakan untuk memeriksa apakah batas frekuensi telah terlampaui. Nilainya mungkin ditetapkan ke true dalam beban tinggi karena desain "fail-open" kebijakan.
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 dari 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>Assign-Message-1</Name>
        </Step>
        <Condition>(fault.name Matches "PromptTokenLimitViolation")</Condition>
    </FaultRule>
</FaultRules>

Kode status HTTP saat ini untuk melebihi pembatasan kapasitas yang ditetapkan oleh kebijakan LLMTokenQuota atau PromptTokenLimit adalah 429 (Too Many Requests).

Skema

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

Topik terkait