Kunci API Sudah Diberi Kuota, Mengapa Masih Bisa Melebihi Anggaran? Tiga Garis Anggaran Uji Coba AI

Kunci API Sudah Diberi Kuota, Mengapa Masih Bisa Melebihi Anggaran? Tiga Garis Anggaran Uji Coba AI

Ringkasan: Kunci API sudah diberi kuota, tapi biaya tetap bisa melebihi perkiraan. Artikel ini menjelaskan penyebabnya sekaligus memecah kontrol anggaran uji coba AI menjadi tiga garis anggaran yang berurutan.

Kesimpulan dulu: kuota Key di gateway adalah batas atas yang lunak, dan saat ada permintaan konkuren kuota itu tidak bisa dijadikan batas tagihan yang keras. Mengacu pada dokumentasi token APIYI, kuota diperiksa pada saat permintaan dimulai. Beberapa permintaan yang lolos pemeriksaan secara bersamaan, atau satu permintaan yang memang mahal, bisa membuat konsumsi akhir melewati kuota yang sudah ditetapkan.

Cara yang andal adalah membaginya menjadi tiga lapisan:

  1. Backend aplikasi menyelesaikan pemeriksaan sebelum mengirim permintaan, dan menyisihkan anggaran secara atomik.
  2. Di sisi gateway, terbitkan Key terpisah khusus untuk lalu lintas uji coba, lengkapi dengan kuota dan daftar putih model, supaya dampak penyalahgunaan Key ini bisa dipersempit.
  3. Peringatan saldo akun hanya bertugas memberi notifikasi, dipakai untuk memicu respons manual.

Ketiga lapisan ini tidak saling menggantikan. Gerbang anggaran yang sesungguhnya terjadi di buku besar aplikasi sendiri.

api-key-quota-overspend-three-budget-lines-id-image-0

Peta Pengetahuan dan Indeks: Urutan serta Pembagian Tugas Tiga Lapis Anggaran

Tabel berikut sekaligus berperan sebagai peta pengetahuan dan indeks. Tabel ini mencantumkan urutan berlakunya tiga lapis anggaran, tanggung jawab masing-masing, alasan penempatannya, serta nomor bagian terkait di badan artikel.

Urutan Lapis Anggaran Tanggung Jawab Alasan Ditempatkan di Sini Tujuan Bagian
Prasyarat Memahami kuota lunak Membedakan pemeriksaan sebelum permintaan, pemotongan awal, dan pemotongan aktual Tanpa memahami urutan waktu penagihan, tiga lapis berikutnya tidak akan bisa dirancang Memahami bagaimana pembengkakan biaya terjadi 1, 1.1
Lapis Pertama Anggaran backend aplikasi Melakukan reservasi atomik dan penyelesaian berdasarkan pengguna dan kolam uji coba Hanya aplikasi yang tahu “siapa yang memakai, berapa banyak yang boleh dipakai” Membuat pembengkakan biaya terhenti sebelum permintaan dikirim 2.1, 3
Lapis Kedua Key uji coba terpisah Kuota, whitelist model, dan isolasi dari lalu lintas resmi Saat aplikasi bermasalah, gateway menjadi batas lapis kedua Memperkecil cakupan paparan satu Key 2.2
Lapis Ketiga Peringatan saldo akun Memberi notifikasi saat saldo di bawah ambang Peringatan adalah sinyal pasca-kejadian, tidak punya kemampuan memblokir Membuat orang bisa turun tangan tepat waktu 2.3
Penerapan Buku besar konkurensi dan pemeriksaan peluncuran Reservasi, penyelesaian, penanganan kegagalan, rekonsiliasi, pesan yang ramah Mengubah prinsip di atas menjadi alur yang bisa diverifikasi Bisa diverifikasi satu per satu sebelum peluncuran 3, 4

Saran urutan membaca: baca Bagian 1 lebih dulu untuk memahami urutan waktu, lalu Bagian 2 untuk memperjelas pembagian tugas, dan Bagian 3 adalah bagian implementasi. Bagian 4 cocok dipakai sebagai pembanding tersendiri sebelum peluncuran.

Yang Perlu Diketahui: Istilah Penting Sebelum Memahami Garis Anggaran

Istilah Penjelasan singkat
Batas lunak Kuota diperiksa saat permintaan dimulai; setelah lolos pemeriksaan, total konsumsi belum tentu tetap di bawah batas
Pemotongan di muka Gateway memotong sebagian kuota berdasarkan estimasi lebih dulu, lalu menyelesaikan berdasarkan pemakaian aktual setelah permintaan selesai
Reservasi atomik Melakukan “periksa sisa kuota dan klaim” dalam satu operasi yang tidak bisa dipecah, mencegah permintaan bersamaan lolos semua sekaligus
Reservasi dalam proses Bagian anggaran yang masih berstatus terpakai di buku besar ketika permintaan sudah dikirim tetapi biaya aktualnya belum dikonfirmasi
remain_quota Field total kuota sekali pakai untuk token APIYI; menurut dokumentasi, 500000 setara $1
Rekonsiliasi Mencocokkan log gateway dengan buku besar sendiri satu per satu, lalu memperbaiki selisih antara estimasi dan aktual

1 Mengapa kuota kunci API bisa terlampaui karena permintaan bersamaan

Dokumentasi token APIYI menjelaskan hal ini dengan sangat jelas: kuota kunci API adalah batas lunak yang diperiksa saat permintaan dimulai. Jadi, permintaan yang berjalan bersamaan, atau satu permintaan berbiaya tinggi, bisa membuat pemakaian aktual melebihi kuota yang ditetapkan. Ini adalah karakteristik dari struktur penagihan “periksa di awal, selesaikan di akhir”, bukan soal ada atau tidaknya bug di platform tertentu.

Kita bisa memahaminya lewat skenario hipotetis (semua angka hanya ilustrasi, bukan hasil pengukuran). Sebuah kunci API uji coba punya sisa kuota setara $1, lalu 20 permintaan masuk pada saat yang sama. Setiap permintaan melihat “saldo masih positif” saat dimulai, sehingga semuanya diloloskan. Saat permintaan-permintaan itu selesai satu per satu dan diselesaikan berdasarkan pemakaian aktual, total konsumsi sudah jauh melewati $1. Bahkan tanpa permintaan bersamaan, satu permintaan dengan konteks panjang dan output besar pun bisa memakan biaya sekali jalan yang melebihi sisa kuota.

Ada dua kesalahpahaman umum yang perlu dijelaskan:

  • Kuota tidak pulih otomatis setiap hari. Dokumentasi menjelaskan bahwa remain_quota adalah total kuota sekali pakai; “reset setiap hari” perlu diterapkan sendiri oleh pihak aplikasi melalui skrip terjadwal.
  • Daftar putih model bukan berarti batas biaya. Itu hanya membatasi model mana yang bisa dipanggil; jumlah panggilan ke model yang sama dan skala tiap panggilan tidak dibatasi.

api-key-quota-overspend-three-budget-lines-id-image-1

1.1 Tiga titik waktu kuota kunci API: pemeriksaan sebelum permintaan, estimasi, dan pemotongan aktual

Satu panggilan punya tiga titik waktu dalam penagihan, dan masing-masing menjawab pertanyaan yang berbeda:

Titik waktu Terjadi di mana Pertanyaan yang dijawab Bisa dijadikan batas keras?
Pemeriksaan sebelum permintaan Gateway, saat permintaan dimulai Apakah kunci API ini masih punya sisa kuota saat itu Tidak, saat permintaan bersamaan semuanya bisa lolos sekaligus
Estimasi dan pemotongan di muka Gateway, berdasarkan estimasi Perkiraan berapa yang akan dipakai permintaan ini Tidak, estimasi bisa berbeda dari aktual
Pemotongan aktual Gateway, setelah permintaan selesai Berapa pemakaian aktual permintaan ini Data setelah kejadian, tidak bisa dipakai untuk menentukan penerimaan

Penjelasan APIYI tentang pemotongan kuota di muka adalah: gateway memotong berdasarkan estimasi lebih dulu, lalu menyelesaikan berdasarkan pemakaian aktual setelah permintaan selesai; mekanisme ini tidak menggantikan reservasi atomik di sisi bisnis. Pemotongan di muka oleh gateway adalah untuk penagihan gateway sendiri; gateway tidak tahu berapa sisa kuota uji coba milik salah satu pengguna Anda hari ini. Jadi, pertanyaan “apakah pengguna ini boleh mengirim satu permintaan lagi” hanya bisa dijawab oleh backend aplikasi.


2 Tiga Lapis Batas Anggaran untuk Uji Coba AI

Ketiga lapis ini menghadapi tiga jenis risiko: pemakaian berlebih di level logika bisnis, penyalahgunaan atau kebocoran di level kunci API, dan saldo akun yang habis. API4 “Unrestricted Resource Consumption” dalam OWASP API Security Top 10 (2023) juga membahas hal yang sama: antarmuka yang tidak membatasi konsumsi resource akan membawa risiko di sisi layanan maupun biaya. Untuk antarmuka AI, risiko biaya biasanya lebih langsung terasa.

2.1 Lapis pertama: anggaran pengguna dan pool uji coba di backend aplikasi

Ini satu-satunya lapisan yang bisa melakukan “kendali masuk”, dan harus mengelola dua tingkat:

  • Anggaran level pengguna: total kuota tiap pengguna uji coba, atau kuota harian. Kuota harian direset oleh tugas terjadwal milik aplikasi sendiri, tidak bergantung pada gateway.
  • Anggaran pool uji coba: batas atas total yang dipakai bersama oleh semua pengguna uji coba. Meskipun tidak ada satu pun pengguna yang melewati batas, saat jumlah pengguna melonjak, total biaya tetap harus punya plafon.

Sebuah permintaan harus lolos reservasi di level pengguna dan level pool sekaligus sebelum diizinkan, dan keduanya wajib selesai dalam satu operasi atomik atau satu transaksi yang sama. Kalau tidak, akan muncul race condition seperti “reservasi pengguna berhasil, tapi pool sudah penuh”.

Lapisan ini juga harus menentukan skala permintaan di sisi server: model mana yang boleh dipakai, batas atas max_tokens, dan panjang input maksimum. Parameter-parameter ini tidak boleh diteruskan mentah-mentah dari input frontend, karena pengguna cukup mengubah satu parameter saja dan perkiraan biayanya langsung jadi tidak akurat.

2.2 Lapis kedua: kunci API uji coba terpisah, kuota, dan daftar putih model

Di sisi gateway, trafik uji coba diberi kunci API tersendiri yang terisolasi penuh dari trafik produksi. Tugas kunci ini adalah membatasi permukaan eksposur: kalau ledger aplikasi bermasalah atau kunci bocor, kerugian hanya sebatas kuota kunci tersebut dan tidak merembet ke bisnis produksi.

Saat mengonfigurasi, perhatikan:

  • Kuota diset berdasarkan “anggaran pool uji coba + sedikit buffer”. Nilainya sebaiknya sedikit lebih tinggi daripada anggaran pool di sisi aplikasi, sebagai jaring pengaman. Jangan disamakan dengan anggaran pool, karena kalau sama, reservasi di lapisan aplikasi jadi tidak ada gunanya.
  • Daftar putih model hanya memuat model yang dibuka untuk uji coba. Ini mencegah kunci uji coba dipakai untuk memanggil model mahal, tapi tidak membatasi jumlah dan skala permintaan, jadi pembatasan skala di sisi server pada bagian 2.1 tetap wajib ada.
  • Karena kuota bersifat batas atas lunak, lapis ini membolehkan “sedikit melewati batas”. Maknanya adalah menjaga besaran pelanggaran batas tetap dalam rentang yang bisa diterima; jangan berharap lapis ini bisa mencapai nol pembengkakan.

Praktik umum memisahkan kunci API, kuota, dan log per proyek adalah topik lain. Di sini hanya ditekankan satu hal: trafik uji coba memakai satu kunci API tersendiri.

2.3 Lapis ketiga: peringatan saldo akun

Dokumentasi peringatan saldo APIYI menyatakan dengan jelas bahwa peringatan hanya bersifat notifikasi dan tidak memblokir permintaan. Saat saldo turun di bawah ambang batas, peringatan bertugas mengirim pesan ke penanggung jawab, lalu orang tersebut yang memutuskan apakah akan melakukan top up, menutup sementara pintu masuk uji coba, atau menyelidiki trafik anomali.

Ada dua saran saat memakai lapis ini:

  • Ambang peringatan ditentukan berdasarkan “konsumsi maksimum selama waktu yang dibutuhkan dari deteksi hingga penanganan”, jangan asal memasang angka bulat.
  • Peringatan harus dikaitkan dengan tindakan penanganan yang konkret, misalnya di panduan giliran jaga (on-call) ditulis “setelah menerima peringatan, tutup dulu pintu pendaftaran uji coba”. Peringatan yang hanya berupa notifikasi tanpa tindak lanjut sama saja tidak ada gunanya.

3 Buku besar konkurensi hipotetis: dari reservasi atomik hingga rekonsiliasi

Bagian ini menyajikan desain ilustratif. Struktur tabel, harga, dan angka semuanya bersifat hipotetis, digunakan untuk menjelaskan alur, dan tidak mewakili data pengukuran aktual sistem mana pun. Alurnya terdiri dari lima langkah:

Pemeriksaan dan reservasi atomik → server mengunci model dan skala → mengirim permintaan
      → penyelesaian / penanganan kegagalan → koreksi rekonsiliasi offline

api-key-quota-overspend-three-budget-lines-id-image-2

3.1 Struktur tabel dan status buku besar anggaran

Struktur data ilustratif memiliki dua tabel: budgets mencatat batas atas, jumlah yang sudah dibelanjakan, dan jumlah yang sudah direservasi untuk setiap pengguna dan pool uji coba; reservations mencatat setiap reservasi beserta statusnya.

Status reservasi Arti Dampak terhadap “sisa yang tersedia”
reserved Sudah direservasi, permintaan sedang berjalan Menempati jumlah perkiraan
settled Mendapatkan usage aktual, sudah diselesaikan Berubah menjadi sudah dibelanjakan, melepaskan selisih
released Dipastikan permintaan tidak dieksekusi Dilepaskan sepenuhnya
unknown Timeout, koneksi terputus, biaya tidak diketahui Tetap menempati, menunggu rekonsiliasi

Cara menghitung sisa yang tersedia adalah limit - spent - reserved, di mana reserved mencakup reservasi berstatus unknown.

3.2 Pemeriksaan dan reservasi atomik: mencegah lolosnya permintaan secara bersamaan

Kuncinya adalah menggabungkan “pemeriksaan” dan “penggunaan” menjadi satu pernyataan pembaruan bersyarat, dan membiarkan database yang menjamin sifat atomiknya:

-- Ilustrasi: hanya reservasi jika sisa anggaran cukup, kembalikan jumlah baris yang terpengaruh
UPDATE budgets
SET reserved = reserved + :estimate
WHERE owner_id IN (:user_id, :pool_id)
  AND limit_amount - spent - reserved >= :estimate;
-- Jumlah baris yang terpengaruh harus sama dengan 2 (pengguna dan pool keduanya berhasil), jika tidak, rollback transaksi dan tolak permintaan

Jumlah estimasi harus memakai nilai batas atas: kalikan jumlah token input dengan harga satuan input, lalu tambahkan max_tokens dikalikan harga satuan output. Penggunaan sebenarnya biasanya lebih rendah dari angka ini, jadi selisihnya bisa dikembalikan saat penyelesaian. Lebih baik mereservasi sedikit lebih banyak daripada kurang.

3.3 Server mengunci model dan skala tugas

Parameter estimasi yang dipakai untuk reservasi harus benar-benar identik dengan parameter permintaan yang benar-benar dikirim. Contoh kodenya sebagai berikut:

ALLOWED_TRIAL_MODELS = {"trial-model-a"}   # Ilustrasi: model yang dibuka untuk uji coba
MAX_OUTPUT_TOKENS = 1024                   # Ilustrasi: batas maksimum yang dipaksakan server
MAX_INPUT_TOKENS = 8000

def build_trial_request(user_input, requested_model):
    model = requested_model if requested_model in ALLOWED_TRIAL_MODELS \
        else "trial-model-a"
    input_tokens = count_tokens(user_input)
    if input_tokens > MAX_INPUT_TOKENS:
        raise InputTooLarge()
    estimate = price_in(model) * input_tokens \
             + price_out(model) * MAX_OUTPUT_TOKENS
    return model, MAX_OUTPUT_TOKENS, estimate

max_tokens dan model yang dikirim dari frontend hanyalah nilai referensi; keputusan akhir tetap ditentukan oleh server.

3.4 Mengirim Permintaan, Penyelesaian Biaya, dan Penanganan Kegagalan

Sebelum mengirim permintaan, buat ID permintaan unik dan tuliskan ke catatan reservasi, agar nanti mudah dicocokkan di log. Setelah permintaan kembali, ada tiga kasus yang perlu ditangani:

  1. Berhasil dan mendapatkan usage: Hitung jumlah berdasarkan pemakaian aktual, spent += actual, reserved -= estimate, status reservasi diubah menjadi settled.
  2. Kegagalan yang jelas tidak dieksekusi: Misalnya validasi parameter gagal atau autentikasi gagal—error yang bisa dipastikan tidak membuat permintaan masuk ke penagihan. Dalam kasus ini, lepaskan reservasi, status diubah menjadi released.
  3. Timeout atau koneksi terputus: Permintaan mungkin sudah dieksekusi di sisi upstream dan menimbulkan biaya, hanya saja hasilnya tidak kembali. Di sini jangan menganggap biayanya nol; catat status sebagai unknown dan biarkan reservasi tetap ditahan.

Kasus ketiga paling rawan salah. Kalau timeout langsung melepas reservasi, sama saja menghapus dari buku besar biaya yang mungkin sudah terjadi. Pada periode dengan konkurensi tinggi dan tingkat timeout yang tinggi, galat ini akan terus menumpuk.

3.5 Rekonsiliasi Offline: Memperbaiki unknown dan Penyimpangan Estimasi

Kueri log APIYI mendukung ekspor inkremental; dokumentasinya memposisikannya untuk rekonsiliasi offline, bukan sebagai dasar untuk melakukan pelepasan per permintaan. Jadi rekonsiliasi sebaiknya dibuat sebagai tugas terjadwal:

  • Tarik log inkremental sejak rekonsiliasi terakhir, lalu cocokkan dengan tabel reservations berdasarkan ID permintaan atau jendela waktu.
  • Reservasi unknown yang bisa ditemukan di log diubah menjadi settled sesuai jumlah aktual di log; yang masih tidak ditemukan setelah melewati jendela waktu yang disepakati diubah menjadi released.
  • Hitung distribusi selisih antara “jumlah estimasi dan jumlah aktual”. Jika jumlah aktual sering mendekati bahkan melebihi estimasi, periksa kembali rumus estimasi di Bagian 3.3.

Hasil rekonsiliasi juga menjadi input untuk lini anggaran ketiga: jika total buku besar dan konsumsi aktual akun terus tidak cocok, itu sendiri adalah sinyal yang perlu penyelidikan manual.

api-key-quota-overspend-three-budget-lines-id-image-3


4 Pemeriksaan Peluncuran Lini Anggaran dan Petunjuk Ramah Saat Kuota Tidak Cukup

4.1 Daftar Periksa Peluncuran Tiga Lini Anggaran

Item Pemeriksaan Lini Anggaran Metode Verifikasi
Reservasi pengguna dan pool selesai dalam transaksi yang sama Lini pertama Uji tekanan permintaan bersamaan, pastikan jumlah terpakai ditambah reservasi tidak melebihi batas
model, max_tokens, dan panjang input ditetapkan oleh server Lini pertama Ubah parameter dari frontend, pastikan perubahan tidak berlaku
Permintaan timeout dicatat sebagai unknown dan tetap menempati kuota Lini pertama Suntikkan kegagalan timeout, periksa status buku besar
Tugas rekonsiliasi berjalan terjadwal dan menangani unknown Lini pertama Periksa log rekonsiliasi dan alur status
Key trial berdiri sendiri, kuota sedikit di atas anggaran pool Lini kedua Periksa konfigurasi Key dan nilai anggaran pool
Whitelist model pada Key trial hanya berisi model trial Lini kedua Panggil dengan model di luar whitelist, pastikan ditolak
Skrip reset kuota harian tersedia dan termonitor Lini pertama dan kedua Periksa catatan eksekusi tugas terjadwal
Ambang alarm saldo sesuai dengan manual penanganan Lini ketiga Latih alur dari alarm hingga penutupan akses

4.2 Petunjuk untuk Pengguna Saat Kuota Tidak Cukup

Saat reservasi gagal, aplikasi harus mengembalikan error bisnis yang jelas; jangan biarkan permintaan sampai ke gateway lalu baru melaporkan error yang sulit dipahami. Petunjuk sebaiknya memuat tiga informasi:

  • Apa yang terjadi: misalnya “Kuota trial hari ini sudah habis” atau “Kuota trial saat ini sudah penuh”. Kuota pengguna yang tidak cukup dan pool trial yang penuh harus diberi petunjuk terpisah.
  • Kapan pulih: jika kuota harian diatur, beri tahu waktu reset; jika kuota sekali pakai habis, jelaskan opsi upgrade yang tersedia.
  • Status saat ini: boleh menampilkan sisa kuota, tetapi harus berdasarkan sisa yang tersedia di buku besar dan memperhitungkan reservasi yang sedang berjalan, agar tidak muncul situasi “terlihat masih ada saldo tetapi justru ditolak”.

Setelah pemeriksaan di atas selesai, seluruh lini anggaran dapat diverifikasi dengan cara sederhana: simulasikan puncak permintaan bersamaan yang dibarengi timeout dari upstream, lalu pastikan bahwa “terpakai + reservasi dalam perjalanan” di buku besar selalu tidak lebih rendah dari konsumsi aktual setelah rekonsiliasi, sekaligus memastikan konsumsi Key trial tidak melewati kuotanya secara signifikan. Jika kedua syarat itu terpenuhi, barulah ketiga lini anggaran ini benar-benar dapat diandalkan.


Referensi

  1. Dokumentasi manajemen token APIYI: penjelasan tentang batas lunak, remain_quota, reset harian, dan daftar putih model
    • Tautan: docs.apiyi.com/api-capabilities/token-management
  2. Penjelasan kuota pemotongan di muka APIYI: mekanisme estimasi pemotongan awal dan penyelesaian setelah pemakaian
    • Tautan: docs.apiyi.com/faq/pre-deduction-quota
  3. Penjelasan peringatan saldo APIYI: peringatan hanya mengirim notifikasi, tidak memblokir
    • Tautan: docs.apiyi.com/faq/balance-alerts
  4. Dokumentasi kueri log APIYI: ekspor inkremental dan rekonsiliasi offline
    • Tautan: docs.apiyi.com/api-capabilities/log-query
  5. OWASP API Security Top 10 2023: API4 Unrestricted Resource Consumption
    • Tautan: api-security.owasp.org/editions/2023/en/0xa4-unrestricted-resource-consumption/

Segala sesuatu yang direncanakan dengan matang akan berdiri tegak; yang tidak direncanakan akan runtuh. —《Liji·Zhongyong》

Similar Posts