Ketika webhook dari layanan eksternal harus memicu inference AI lokal di Jetson Nano, kontrak API harus lebih dari sekadar mengirim prompt. Artikel ini menjelaskan pendekatan praktis untuk memastikan payload konsisten, autentikasi kuat, dan sistem dapat menoleransi gangguan gateway atau perangkat, berlandaskan pengalaman benchmark Ollama di Jetson Nano.

Dalam pengujian internal Ollama, Jetson Nano mampu menangani inference lokal dengan skalabilitas terbatas. Karena latency cukup sensitif terhadap antrian, kontrak webhook harus eksplisit tentang ukuran payload, timeout, dan skenario fallback agar sistem tetap responsif tanpa memblokir sumber daya.

Memahami Konteks Kontrak Webhook untuk Inference Lokal

Solusi webhook mengandalkan dua bagian: pengirim yang memanggil endpoint Jetson Nano dan penerima yang menjalankan inference. Kontrak harus mendefinisikan format request, respons yang diharapkan, timeout, serta bagaimana menangani gagal kirim (retry dan deduplikasi). Tanpa spesifikasi ini, Jetson Nano dapat kewalahan jika webhook mengirim ulang request besar atau menunggu respons terlalu lama.

Kontrak juga harus menegaskan bahwa Jetson Nano tidak menerima payload berukuran besar tanpa kompresi atau chunking, agar tidak memaksa RAM terbatas. Dalam konteks benchmark Ollama, pastikan payload hanya berisi prompt dan metadata minimal; proses pre- dan post-processing tetap dilakukan di sistem lain untuk menjaga inference tetap ringan.

Desain Payload dan Validasi

Payload harus memiliki struktur tetap agar penerima dapat mem-parsing tanpa failover. Berikut contoh struktur JSON yang dikunci:

{
  "request_id": "uuid",
  "model": "ollama:/local/model",
  "prompt": "ringkasan teks",
  "max_tokens": 512,
  "metadata": {
    "source": "pipeline-42",
    "priority": "low"
  }
}

Gunakan skema JSON Schema minimal di sisi penerima untuk menolak request tanpa field penting. Validasi ini mencegah Jetson Nano mencoba melakukan inference dengan konfigurasi tidak lengkap. Pastikan juga ada pengecekan ukuran string prompt, dan lengkapi dengan sanitization di gateway untuk menghindari injeksi atau karakter kontrol yang tidak diharapkan.

Autentikasi dan Idempotensi

Jetson Nano biasanya tidak ditempatkan di perimeter dengan proteksi jaringan lengkap, sehingga webhook harus memiliki autentikasi kuat. Satu pendekatan ringan adalah menggunakan HMAC-SHA256 pada header X-Signature dengan secret yang dibagikan. Ini menghindari overhead TLS mutual di banyak deployment lokal.

const payload = JSON.stringify(requestBody);
const signature = crypto
  .createHmac('sha256', sharedSecret)
  .update(payload)
  .digest('hex');
headers['X-Signature'] = signature;

Jetson Nano mengecek signature sebelum mengeksekusi inference sehingga request palsu ditolak lebih awal. Kombinasikan dengan header X-Request-Id untuk mendukung idempotensi. Sistem penerima menyimpan ID terakhir selama windows tertentu (misalnya 2 menit) dan menolak request yang sama dua kali.

Idempotensi juga penting ketika webhook diatur untuk retry otomatis. Teknisnya, seluruh payload dianggap sama jika request_id juga sama. Jika Jetson Nano menerima request_id yang pernah diproses, ia bisa langsung mengembalikan respons cache atau status 409 dengan informasi duplikasi untuk pengirim.

Retry Policy dan Deteksi Duplikasi

Gunakan retry berbasis exponential backoff di pengirim, dengan batasan total durasi agar Jetson Nano tidak menerima request beruntun saat sedang sibuk. Contoh pola retry:

  • Retry pertama setelah 250 ms
  • Selanjutnya bertambah dua kali lipat sampai maksimal 3 detik
  • Batasi total percobaan 5 kali untuk mencegah pemborosan resource

Jetson Nano perlu membedakan error sementara (misalnya inference queue penuh) dan error permanen (payload tidak valid). Jika tidak bisa memproses karena queue penuh, respons 503 dengan header Retry-After memberi sinyal syistem pengirim kapan mencoba ulang.

Deteksi duplikasi sebaiknya mengandalkan penyimpanan ringkas seperti cache Redis lokal atau penyimpanan in-memory dengan TTL. Simpan pasangan request_id dan hash payload untuk 2-3 menit. Jika Jetson Nano menerima request dengan ID sama tapi hash berbeda, segera laporkan konflik agar pengirim dapat memperbaiki data.

Fallback saat Gateway atau Hardware Bermasalah

Jetson Nano bisa mengalami Gangguan akibat kernel panic, overheating, atau konektivitas jaringan. Desain fallback untuk status gateway mencakup beberapa lapis:

  1. Gunakan circuit breaker di gateway untuk mengenali Jetson Nano tidak responsif; setelah threshold kegagalan tercapai, alihkan request ke queue atau endpoint alternatif.
  2. Sediakan mekanisme graceful degradation dengan fallback: jika Jetson Nano sedang tidak tersedia, kirim respons status 202 dan simpan request di queue seperti Redis Streams atau RabbitMQ untuk diproses saat perangkat kembali.
  3. Siapkan health-check endpoint terpisah yang memonitor suhu CPU/GPU dan antrian inference. Sistem orchestration (misalnya Prometheus + Alertmanager) dapat memicu alert atau restart jika health-check gagal selama 3 interval berturut-turut.

Contoh sederhana fallback: Jetson Nano menerima request, tapi antrean penuh. Daripada menolak, ia menulis payload ke file sistem lokal atau queue, lalu mengembalikan 202. Sebuah proses worker terpisah mencoba membaca queue dan menjalankan inference saat resource tersedia.

Verifikasi di Environment Terbatas

Sebelum deploy ke produksi, tim perlu memverifikasi kontrak di lingkungan terbatas yang meniru keterbatasan Jetson Nano. Langkah verifikasinya:

  • Gunakan tes integrasi dengan emulator webhook dan Jetson Nano (bisa container dengan simulasi batas CPU) untuk memastikan validasi payload dan signature bekerja.
  • Lakukan chaos testing ringan: hentikan layanan inference secara acak untuk mengecek apakah fallback queue dan 202 respons berfungsi.
  • Uji retry policy dengan memaksa Jetson Nano menolak pertama kali, lalu pastikan pengirim mengikuti backoff yang diharapkan.
  • Verifikasi idempotensi dengan mengirim request duplikat cepat dan pastikan Jetson Nano mengembalikan status duplikat tanpa men-trigger inference kedua.

Log yang jelas sangat penting. Catat setiap request_id yang ditolak karena duplikasi atau kesalahan signature agar gampang menyelidiki masalah dengan throughput rendah. Kesemuanya harus terekam dalam observability stack lokal sebelum live.

Dengan kontrak webhook yang eksplisit, autentikasi, idempotensi, retry, dan fallback yang teruji, Jetson Nano akan bisa melayani inference Ollama secara andal meski dalam batasan hardware dan jaringan.