Developer Guide

Halaman ini menjelaskan konsep inti dan pipeline internal FREMIS-N — model mental yang perlu Anda pahami sebelum mengintegrasikan API. Untuk gambaran umum kapabilitas dan posisi FREMIS-N dalam stack Nodeflux, lihat halaman utama FREMIS-N.

---

Konsep Inti

Enrollment

Enrollment adalah proses mendaftarkan satu identitas ke dalam database FREMIS-N. Saat enrollment, FREMIS-N mengekstrak representasi matematis unik dari wajah dalam foto — disebut embedding — dan menyimpannya agar bisa dicari di kemudian hari.

Satu identitas dapat memiliki beberapa variasi enrollment: foto dari sudut berbeda, kondisi pencahayaan berbeda, atau dengan maupun tanpa kacamata. Semakin beragam variasi yang didaftarkan, semakin baik kemampuan sistem mengenali orang tersebut dalam kondisi nyata yang beragam.

Embedding

Embedding adalah representasi matematis sebuah wajah dalam bentuk vektor fitur. Vektor ini dihasilkan oleh model ekstraksi fitur dan bersifat unik untuk setiap identitas — dua foto orang yang sama akan menghasilkan vektor yang sangat berdekatan dalam ruang vektor tersebut.

Setiap embedding disimpan di dua tempat secara bersamaan:

Index default FREMIS-N melakukan pencarian eksak terhadap seluruh enrollment di keyspace — akurasi penuh dijaga, tetapi waktu pencarian tumbuh dengan jumlah enrollment. Mode opsional compressed (--index-mode compressed) menggunakan pencarian compressed yang di-akselerasi GPU untuk kapasitas jutaan enrollment.

Setiap keyspace memiliki indeks pencarian in-memory tersendiri; pencarian tidak pernah bercampur lintas keyspace.

Keyspace

Keyspace adalah namespace atau grup terisolasi tempat enrollment disimpan. Analoginya seperti folder atau tenant yang terpisah: enrollment di keyspace A sama sekali tidak bercampur dengan keyspace B, bahkan jika keduanya berjalan di FREMIS-N yang sama.

Keyspace berguna untuk:

• Isolasi departemen — karyawan divisi A dan divisi B disimpan di keyspace berbeda
• Multi-use-case — database VIP dan database watchlist keamanan tidak saling menginterferensi
• Multi-tenant — beberapa klien atau deployment berbagi satu instansi FREMIS-N tanpa data overlap

Saat melakukan recognition atau search, Anda menentukan keyspace mana yang menjadi target pencarian.

1:1 Match vs 1:N Search

Similarity Score & Threshold

Setiap hasil matching dan recognition disertai similarity score — angka antara 0.0 dan 1.0 yang menunjukkan seberapa mirip dua wajah yang dibandingkan. Nilai mendekati 1.0 berarti sangat mirip; nilai mendekati 0.0 berarti sangat berbeda.

Threshold adalah batas minimum similarity yang Anda tentukan untuk menyatakan bahwa dua wajah "cocok". Ini adalah trade-off yang perlu disesuaikan dengan kebutuhan deployment:

Top-k

Saat melakukan 1:N search, FREMIS-N dapat mengembalikan lebih dari satu kandidat — ini disebut top-k. Misalnya, top-3 berarti tiga identitas dengan similarity score tertinggi dikembalikan sekaligus.

Top-k berguna ketika:

• Anda ingin membangun antarmuka review manual di mana operator memilih dari beberapa kandidat
• Sistem downstream perlu mempertimbangkan beberapa kemungkinan sebelum memutuskan
• Anda sedang melakukan audit atau investigasi dan ingin melihat kandidat alternatif selain yang paling cocok

---

Quotas & Limits

FREMIS-N menerapkan dua jenis batasan berdasarkan lisensi yang aktif:

Batas Enrollment

Lisensi menentukan jumlah maksimum identitas (enrollment) yang dapat disimpan di seluruh keyspace dalam satu deployment. Saat batas ini tercapai, permintaan enrollment baru akan ditolak hingga sebagian enrollment dihapus atau lisensi ditingkatkan.

Batas QPS (Queries Per Second)

Selain batas enrollment, lisensi juga membatasi laju permintaan untuk operasi recognition, match, dan operasi utility lainnya. Jika laju permintaan melampaui batas yang diizinkan, permintaan yang melebihi kuota akan ditolak sementara — bukan diproses dengan penundaan.

Pembatasan QPS menggunakan mekanisme token-bucket per analytic group: endpoint recognition, match, dan utility masing-masing memiliki bucket terpisah, sehingga lonjakan request recognition tidak menghabiskan kuota utility, dan sebaliknya. Saat batas tercapai, server mengembalikan HTTP 429 Too Many Requests.

Di mode cluster, worker yang berjalan tanpa deployment key (lisensi terpusat di coordinator) hanya menerima permintaan yang ditandatangani secara HMAC dari coordinator — permintaan langsung dari klien eksternal akan ditolak.

Untuk mengetahui batas yang berlaku pada lisensi Anda, hubungi tim Nodeflux atau lihat halaman Quota & License Management.

---

Bagaimana FREMIS-N Memproses Permintaan

Bagian ini menjelaskan pipeline internal FREMIS-N — dari HTTP request masuk hingga respons keluar. Memahami bagian ini membantu Anda menjawab pertanyaan operasional seperti: "Apakah ada antrian internal?", "Apa yang terjadi saat server penuh?", dan "Berapa banyak inferensi AI yang dijalankan per request?"

1. HTTP Intake

FREMIS-N menggunakan async HTTP server untuk menerima permintaan. Setiap request HTTP yang masuk ditangani secara konkuren, sehingga ratusan koneksi dapat diproses tanpa overhead memori yang besar per koneksi.

2. Internal Work Queue

Ya, ada antrian internal di dalam FREMIS-N — namun bukan message broker eksternal.

Internal Work Queue adalah buffer in-process antara HTTP server dan worker inferensi AI. Setelah request HTTP diterima dan divalidasi, FREMIS-N meletakkan tugas ekstraksi ke dalam antrian ini; worker thread kemudian mengambil tugas secara berurutan dan menjalankan inferensi.

Mengapa ada antrian ini? Antrian memisahkan laju kedatangan request HTTP dari laju pemrosesan GPU. Saat terjadi lonjakan request singkat (burst), antrian menyerap kelebihannya — klien tetap menerima respons akhirnya tanpa harus menunggu giliran secara sinkron di level jaringan.

Karakteristik antrian

Tidak ada prioritas di antara tipe request — enrollment, recognition, dan match berbagi satu antrian yang sama secara FIFO. Request yang masuk lebih awal diproses lebih awal, terlepas dari jenisnya.

Karena tidak ada GPU batching, menambah worker (via --max-workers) adalah satu-satunya cara meningkatkan throughput paralel. Dua worker memproses dua tugas sekaligus; sepuluh worker memproses sepuluh tugas sekaligus.

Batas sistem dan admission control

FREMIS-N tidak menolak request berdasarkan kedalaman antrian. Admission control bekerja berdasarkan tren latensi (lihat Backpressure & Admission Control), sehingga antrian bisa tumbuh sebelum ada 503 dikembalikan. Ini berarti pada kondisi overload, respons akhir tetap datang — hanya lebih lambat — hingga server mendeteksi tren latensi yang cukup buruk untuk mulai menolak request baru.

Karena antrian bersifat in-RAM dan tidak persisten, semua tugas yang sedang mengantri akan hilang jika FREMIS-N di-restart. Pastikan klien Anda mengimplementasikan retry untuk permintaan yang gagal karena restart.

3. Inferensi AI (Tanpa Batching GPU)

FREMIS-N tidak menggabungkan (batch) beberapa request ke dalam satu inferensi GPU. FREMIS-N memproses inferensi satu tugas dalam satu waktu per worker; tidak ada batching GPU lintas request. Setiap tugas diproses secara individual oleh satu worker.

Untuk setiap gambar, pipeline menjalankan tiga tahap secara berurutan:

IQA (Image Quality Assessment) bersifat opsional dan hanya berjalan saat enrollment jika diaktifkan — menilai kecerahan dan ketajaman gambar sebelum deteksi.

Jumlah inferensi neural network per jenis request:

4. Backpressure & Admission Control

FREMIS-N memiliki dua lapisan perlindungan saat server kelebihan beban:

Admission control bekerja berdasarkan tren kemiringan latensi (linear regression), bukan kedalaman antrian. Ini berarti server mulai menolak request baru saat sistem terdeteksi sedang kewalahan, bahkan jika antrian belum penuh. Tidak ada batas keras pada jumlah item di antrian.

5. Startup: Preload Model & Index

Saat FREMIS-N pertama kali start, sebelum request pertama pun diterima:

• Setiap worker mendekripsi dan memuat file model ke dalam session inferensi.
• Seluruh embedding yang tersimpan di database persisten di-load ke dalam indeks pencarian in-memory.

Waktu startup bergantung pada ukuran database enrollment dan jumlah worker. Cluster mode juga me-load semua embedding per keyspace ke indeks pencarian in-memory di masing-masing worker node.

Diagram Pipeline

---

Performance Issues

Tiga skenario performa paling sering muncul saat FREMIS-N digunakan di produksi.

Latency Tinggi pada Recognition

Setiap request memakan waktu lama (misalnya > 5 detik) meskipun beban tampak normal.

1. Periksa ukuran keyspace. Indeks pencarian default melakukan pencarian eksak, jadi waktu pencarian tumbuh dengan jumlah enrollment per keyspace. Jika keyspace > 1 juta enrollment, pertimbangkan --index-mode compressed (GPU-accelerated), pecah ke beberapa keyspace, atau deploy cluster.
2. Pantau kedalaman antrean internal. Metrik Prometheus queue_face (Gauge) menunjukkan request yang menunggu worker. Jika konsisten tinggi, naikkan --max-workers atau tambah resource GPU.
3. Cek resource node. CPU/GPU/memory yang maxed-out di puncak traffic adalah sinyal scale-up atau load redistribution. Lihat /v1/resource-stats per node.
4. Untuk cluster, verifikasi distribusi partisi. Jika satu node memegang sebagian besar enrollment yang aktif diquery, latency-nya akan menonjol. Lihat Cluster Sharding — Partition Imbalance.
5. Network. Latency klien-to-FREMIS-N harus < 50ms di LAN; di Internet/VPN lebih tinggi adalah expected.

Throughput Rendah Padahal GPU Tersedia

GPU utilization rendah tetapi hanya sedikit request yang diproses per detik.

• Tingkatkan parallelism di klien. FREMIS-N tidak melakukan GPU batching antar request; throughput tinggi tergantung pada banyak request konkuren mengisi worker pool. Mulai dari 10–20 concurrent request, monitor, naikkan hingga GPU utilization mendekati saturated.
• Profile bottleneck. Jika round-trip latency tinggi tetapi GPU low, bottleneck adalah network/I/O. Jika latency rendah tetapi throughput rendah, klien yang sequential.
• Verifikasi GPU benar-benar aktif. Cek startup logs — nvidia-smi di host menunjukkan FREMIS-N sebagai proses, container dijalankan dengan --gpus all.

HTTP 429 — Request Di-Throttle

API mengembalikan 429 (Too Many Requests) meskipun traffic tidak terasa tinggi. Ini adalah admission control terhadap QPS limit lisensi.

1. Konfirmasi QPS limit lisensi Anda dengan tim Nodeflux dan dokumentasikan agar bisa dibandingkan dengan traffic ekspektasi.
2. Monitor actual QPS. Cek metrik per detik — average bisa di bawah limit, tetapi burst (peak QPS) yang melebihi limit sudah cukup memicu 429.
3. Implementasi backoff & retry. Saat menerima 429, tunggu 1–5 detik sebelum retry; gunakan exponential backoff (1s, 2s, 4s, ...) untuk retry berulang.
4. Upgrade lisensi jika QPS limit memang tidak mencukupi untuk use case Anda.

Lihat Batas QPS untuk dasar quota lisensi.

---

Kapan Hubungi Support

Setelah mencoba langkah-langkah di halaman ini dan halaman troubleshooting per-fitur, jika masalah masih persisten siapkan informasi berikut sebelum menghubungi tim Nodeflux:

• Versi FREMIS-N — output fremis_n_app --version atau Docker image tag
• Mode deployment — standalone atau cluster, jumlah worker node, alamat coordinator
• Logs — stderr/stdout dari rentang 5–10 menit sebelum dan sesudah incident
• Output /health dan /v1/resource-stats dari node yang bermasalah
• Ringkasan symptom — deskripsi singkat, langkah reproduksi, dan hasil troubleshooting yang sudah dilakukan
• Opsional tetapi membantu — error message lengkap, network topology, resource metrics saat incident, jumlah enrollment dan QPS rata-rata per keyspace

---

Selanjutnya