Lompat ke konten utama
StableTerakhir diperbarui: 9 Okt 2026, 09.28

Pengendalian Biaya dan Limit Penggunaan

Platform DagangBot menerapkan sistem pengendalian biaya (cost-control) yang berlapis untuk memastikan merchant tidak mengalami tagihan yang tidak terduga, sementara operasional platform tetap berjalan dengan margin yang sehat. Sistem ini mengatur mulai dari batasan anggaran (budget caps), limit pengeluaran per-tenant atau cabang, ambang batas peringatan, hingga tuas-tuas penghematan token (token-saving levers) di sisi backend.

Pengendalian dan pemantauan biaya ini sangat kritikal, mengingat platform mengelola ribuan tenant dengan berbagai model langganan dan pola penggunaan kecerdasan buatan. Tanpa adanya kontrol yang ketat, lonjakan penggunaan API dari penyedia layanan Large Language Model (LLM) dapat mengakibatkan kerugian finansial yang masif dalam waktu singkat. Oleh karena itu, arsitektur ini dirancang untuk mendeteksi, membatasi, dan menghentikan pengeluaran yang tidak normal sebelum tagihan membengkak.

Sistem pengamanan biaya di DagangBot tertanam secara mendalam di dua area utama: Dynamic Router (AI) untuk kontrol biaya kognitif per-permintaan, dan Wallet/Ledger untuk kontrol batas kredit finansial dan alokasi anggaran lintas cabang.

Pengendalian Biaya dan Budget
Pengaturan limit anggaran pada dasbor pengelolaan biaya

1. Ambang Batas Token dan Limit Router (Token Thresholds)

Dalam merespons percakapan, router dinamis mengevaluasi estimasi token dan biaya sebelum meneruskan payload ke mesin komputasi AI. Batasan ini diatur melalui kebijakan perutean cerdas pada konfigurasi platform. Tujuan utamanya adalah memastikan bahwa setiap kueri dialokasikan ke model yang paling efisien secara biaya berdasarkan tingkat kerumitan yang dihitung.

Melalui modul perutean cerdas, platform membaca parameter ambang batas yang mengajukan tier berdasarkan ukuran token dan konteks:

Konfigurasi RoutingPolicy

Berikut adalah tabel parameter kebijakan routing utama yang memengaruhi ambang batas token:

Parameter Tipe Data Deskripsi dan Perilaku Sistem
free_max_tokens Integer Batas maksimal token untuk tier gratis (contoh: 500 token). Kueri di atas ini dipaksa naik tier.
medium_max_tokens Integer Batas maksimal token untuk tier menengah (contoh: 4000 token). Kueri kompleks menggunakan tier ini.
heavy_max_tokens Integer Batas token untuk tier berat. Dikhususkan untuk agen dengan beban penalaran tingkat tinggi.
default_fallback_tier String Tier cadangan (contoh: tier_2) jika tier yang diajukan gagal atau kelebihan muatan.

Jika prompt melebihi ambang batas token maksimal suatu tier (misalnya di atas free_max_tokens), router secara otomatis akan melakukan klasifikasi ulang ke tier yang lebih mampu atau menolak permintaan dengan log bahwa limit tier terlampaui. Logika ini memitigasi risiko di mana pengguna pada paket gratis mencoba memproses dokumen berukuran besar yang seharusnya memakan biaya premium.

2. Guardrail Anggaran Per-Request (Budget Caps)

Setiap request AI dinilai oleh modul ketahanan sistem dan Guardrails yang tertanam dalam alur pemrosesan sebelum dikirim ke mesin komputasi. Evaluasi ini dilakukan oleh lapisan pelindung komputasi (guardrail).

Parameter Guardrail Finansial

Terdapat empat guardrail finansial utama yang mengawal setiap kueri:

Guardrail Tipe Penjelasan
cost_guardrail_max_amount Float Nilai maksimal dalam IDR yang diizinkan untuk dihabiskan pada satu permintaan tunggal.
budget_guard_enabled Boolean Toggle yang mengaktifkan sirkuit pemutus anggaran. Jika false, platform hanya melakukan logging.
quality_guardrail_min_score Float Skor kualitas minimum yang disyaratkan untuk menghindari pemborosan budget pada respons buruk.
confidence_threshold Float Batas probabilitas (confidence) LLM. Mencegah retries mahal akibat kebingungan model.

Sebagai contoh, jika cost_guardrail_max_amount diatur pada angka 500, maka setiap request yang diprediksi (melalui EstimatedCost) memakan biaya di atas Rp 500 akan digagalkan. Sistem akan menyematkan alasan COST_GUARDRAIL_EXCEEDED dan menaruh status cost_guardrail:fail pada array Checks.

Jika budget_guard_enabled bernilai true, sistem memanggil modul dompet untuk memverifikasi EffectiveExposure. Apabila tagihan estimasi melampaui sisa saldo, sirkuit akan memutus koneksi dengan flag budget_guard:fail. Jika berhasil, flag akan berisi budget_guard:pass, dan jika dilewati akan berisi budget_guard:skipped. Penjaga ini memastikan tidak ada satupun request yang dieksekusi tanpa validasi dana, beroperasi dengan latensi sangat rendah di dalam pipeline.

3. Limit Pengeluaran Per-Tenant dan Cabang (Spend Limits)

Pengendalian biaya tidak hanya di level request AI, tetapi juga pada dompet virtual finansial (wallet). DagangBot memberikan kapabilitas tingkat lanjut pada akun Agency dan Multi-branch (Multi-Cabang) untuk membatasi pengeluaran sub-akun atau cabang melalui alokasi anggaran terpusat.

Aturan perlindungan saldo ini dikelola dalam layanan dompet dan alokasi anggaran. Terdapat beberapa komponen arsitektur yang menjamin saldo tidak pernah minus melebihi batas:

Mekanisme Wallet Credit dan Alokasi

  • CreditPolicy dan Limit Global: Diatur oleh kebijakan batas kredit global dari konfigurasi platform. Tidak ada tenant yang dapat diberikan limit melebihi batas atas global sistem.
  • TenantLimit dan Alokasi Deterministik: Merupakan anggaran virtual yang dialokasikan (remaining budget). Menggunakan entitas catatan anggaran toko, platform melacak sisa anggaran per-toko atau per-cabang secara aman.
  • EffectiveExposure: Ini adalah mekanisme perlindungan ganda andalan DagangBot. Kapasitas belanja sebuah toko tidak hanya dilihat dari limitnya sendiri, melainkan diambil dari nilai terkecil antara saldo agensi dan batas cabang: min(owner_effective_balance, tenant_remaining_budget). Jika cabang B memiliki batas Rp 1.000.000, tetapi saldo agensi pusat tinggal Rp 200.000, maka batas efektif yang berlaku dan dijaga oleh router adalah Rp 200.000.
  • Recall dan Reallocation: Agensi dapat menarik kembali (Recall) saldo yang tidak terpakai dari cabang. Proses ini mengecek keberadaan reservasi aktif. Jika ada pending request, sistem akan menolak dengan ACTIVE_REQUESTS_PENDING guna mencegah kebocoran saldo yang sedang memproses antrean kueri.

4. Ambang Batas Toleransi dan Alerting (Alerting Thresholds)

Peringatan limit (alerting) dan toleransi low-balance membantu merchant dan admin mencegah layanan terhenti secara tiba-tiba tanpa pemberitahuan. Manajemen ekspektasi ini penting untuk kelancaran bisnis, terutama saat kampanye pemasaran sedang berjalan.

Eskalasi dan Notifikasi

  • Topup Tolerance (Reserve Policy): Sistem membaca parameter toleransi pengisian saldo. Jika sisa saldo ditambah penggunaan melebihi ambang batas toleransi topup, layanan masuk ke mode perlindungan. Tenant akan menerima email peringatan batas saldo krisis.
  • Manual Approval Threshold: Pada pengembalian dana (refund) atau klaim alokasi yang tidak biasa yang diproses melalui Wallet, transaksi dengan nominal melebihi ambang batas verifikasi manual akan ditahan pada status pending. Transaksi baru bisa berlanjut apabila ada otorisasi eksplisit dari Tim Layanan Dukungan Platform.
  • Routing Alert Escalation: Jika seluruh rantai fallback AI mengalami kegagalan berulang karena pemblokiran tier atau kendala jaringan penyedia eksternal, modul perutean cerdas akan memicu eskalasi darurat otomatis ke entitas notifikasi sistem agar tim keandalan platform segera melakukan penanganan.

5. Tuas Penghematan Token (Token-Saving Levers)

Untuk memastikan efisiensi biaya komputasi, DagangBot menerapkan desain optimasi anggaran secara otomatis sejak lapisan pemrosesan awal.

Optimalisasi Gateway dan Reasoning

  1. Lightweight Tiering Target: Pengenalan klasifikasi awal intensi pengguna (Intent Classifier) memberikan optimasi beban komputasi. Untuk frasa dasar seperti salam atau ucapan terima kasih, router mengarahkan ke Tier 1 (Fast Conversational Engine). Ini menghindarkan penggunaan mesin nalar komputasi berat untuk percakapan pembuka yang sederhana.
  2. Pembatasan Reasoning Budget: Pada konfigurasi mesin dengan kapasitas nalar tinggi, respons percakapan difokuskan murni pada jawaban substantif pelanggan tanpa memboroskan kuota pada pemikiran reflektif yang tidak perlu.
  3. Gateway Cap Outbound: Biaya transmisi pesan keluar WhatsApp (gateway) kepada merchant sengaja dibatasi oleh batas proteksi maksimal GATEWAY_OUTBOUND_CAP sebesar Rp 5 per pesan. Aturan ini melindungi merchant dari pembebanan berlebih apabila menjalankan pengiriman pesan dalam volume besar.

Troubleshooting

Sistem akan mengeluarkan beberapa pesan kesalahan atau status pemblokiran ketika operasi anggaran menyentuh batasan. Tabel berikut membantu admin dalam mendiagnosis dan memulihkan layanan:

Kode Error Akar Masalah Langkah Resolusi
COST_GUARDRAIL_EXCEEDED Request ditolak karena EstimatedCost melampaui cost_guardrail_max_amount. Periksa ukuran prompt. Jika diperlukan, tingkatkan guardrail cap di pengaturan config.
CREDIT_LIMIT_EXCEEDS_CAP Terjadi saat mengatur limit kredit melampaui batasan GlobalCap. Gunakan nilai di bawah global limit atau konsultasikan penyesuaian limit dengan tim platform.
ACTIVE_REQUESTS_PENDING Gagal memanggil fungsi Recall atau Reallocate karena ada status reservasi tertahan (held). Tunggu hingga seluruh antrean reservasi partially_settled atau held selesai, lalu ulangi.
ALLOCATION_EXCEEDS_EXPOSURE Total alokasi dana ke cabang melebihi limit efektif. Top-up dompet utama agensi atau tarik dana dari cabang lain yang memiliki saldo menganggur.
BILLING_BLOCKED Transaksi alokasi ke cabang ditolak karena lifecycle tidak dalam kondisi active. Periksa apakah cabang sedang dalam mode terblokir atau suspended. Aktifkan kembali dari panel admin.

Skenario Edge Cases

Sebagai aplikasi skala besar, DagangBot memiliki proteksi untuk kondisi batas (edge cases) berikut:

  • Pencegahan Angka Negatif: Segala bentuk penugasan batas kredit yang bernilai minus dilarang. Jika pemanggilan UpdateCreditLimit diberikan limit negatif, maka akan ditolak dengan error credit limit cannot be negative.
  • Idempotency Key Collision: Saat terjadi interupsi jaringan di tengah alokasi anggaran, sistem mencegah agensi membagikan dua kali. Pemanggilan dengan idempotency_key yang sama akan direkonsiliasi otomatis oleh sistem untuk memvalidasi saldo tanpa mengurasi dompet dua kali.
  • Race Conditions pada Reallocation: Pada skenario di mana dua instruksi penarikan saldo terjadi bersamaan, fungsi lockBudgetsSorted mengunci urutan tenant secara deterministik. Ini mencegah PostgreSQL mengalami deadlock di tengah transaksi WithTx.
  • Tier Fallback Loops: Jika seluruh tier, bahkan cadangan sekalipun, tidak merespons (misal API Cloudflare dan AWS down serentak), router tidak akan terjebak dalam loop retries yang memakan biaya komputasi lambat. Sistem memotong sirkuit pada percobaan terakhir dan langsung mengeksekusi escalateDeadLetter untuk peringatan dini.
content/docs/advanced/cost-control.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot