1:N Search

1:N Search adalah kemampuan identifikasi wajah FREMIS-N: diberikan satu foto query, sistem mencari seluruh database keyspace dan mengembalikan daftar kandidat yang paling cocok beserta similarity score-nya. Berbeda dari verifikasi, di sini identitas orang dalam foto belum diketahui — pertanyaannya adalah "Siapa orang ini?"

Apa itu 1:N Search

1:N Search (face identification) membandingkan satu foto query terhadap seluruh enrollment yang tersimpan di keyspace yang ditentukan. Sistem menghitung kemiripan embedding foto query dengan setiap identitas yang terdaftar, lalu mengurutkan hasilnya berdasarkan similarity score dari yang tertinggi ke terendah.

Output utama adalah daftar top-k kandidat — masing-masing berisi face_id, similarity score, dan variasi enrollment yang cocok.

Perbedaan dengan 1:1 Match

Untuk skenario verifikasi (misalnya foto selfie vs. foto KTP), gunakan 1:1 Match.

Pipeline 1:N Recognition

Setiap request ke /v1/face/recognition melewati satu jalur ekstraksi melalui antrian kerja internal, lalu satu pencarian similarity terhadap keyspace yang diminta. Untuk detail cara kerja antrian internal, lihat Internal Work Queue.

Bentuk Response

{
  "result": {
    "face_recognition": {
      "candidates": [
        { "face_id": "emp_001", "similarity": 0.91, "variation": "1234567890123456789" },
        { "face_id": "emp_017", "similarity": 0.74, "variation": "1234567890123459111" }
      ]
    },
    "face_detected": [
      { "top": 0.18, "left": 0.22, "height": 0.42, "width": 0.40 }
    ]
  }
}

Catatan penting:

• candidates diurutkan dari similarity tertinggi (best-first).
• variation adalah ID variasi enrollment yang cocok dengan query — bukan face_id itu sendiri. Setiap face_id dapat memiliki beberapa variasi; jika salah satu variasi cocok, kandidat tersebut dikembalikan.
• face_detected hanya disertakan jika environment variable FREMISN_RETURN_FACE_DETECTION diaktifkan. Koordinat bersifat ternormalisasi dalam rentang [0, 1].
• Array candidates kosong berarti tidak ada enrollment di keyspace yang melewati threshold untuk query ini. Aplikasi memutuskan langkah selanjutnya — misalnya, memperlakukan sebagai identitas tidak dikenal atau meminta enrollment baru.

Konsep Top-k dan candidateCount

Saat melakukan 1:N search, FREMIS-N tidak harus mengembalikan satu kandidat saja. Anda dapat mengambil beberapa kandidat sekaligus melalui parameter candidateCount di dalam additional_params:

{
  "image": "<base64>",
  "keyspace": "watchlist",
  "additional_params": {
    "candidateCount": 5
  }
}

candidateCount (top-k) berguna ketika:

• Anda membangun antarmuka review manual di mana operator memilih dari beberapa kandidat
• Sistem downstream perlu mempertimbangkan beberapa kemungkinan sebelum membuat keputusan akhir
• Anda sedang melakukan investigasi atau audit dan ingin melihat alternatif selain kandidat teratas

Jika candidateCount tidak diisi, FREMIS-N mengembalikan 1 kandidat saja secara default.

Threshold dan Similarity untuk Filter False Match

Setiap kandidat yang dikembalikan menyertakan similarity score antara 0.0 dan 1.0. Nilai ini menunjukkan seberapa mirip foto query dengan enrollment di database:

• Nilai mendekati 1.0 — sangat mirip
• Nilai mendekati 0.0 — sangat berbeda

Threshold adalah batas minimum similarity yang Anda gunakan di sisi aplikasi untuk menyaring false match. FREMIS-N mengembalikan kandidat tanpa melakukan filtering berdasarkan threshold — keputusan apakah kandidat "cukup mirip" diserahkan ke aplikasi pemanggil.

Workflow: Enroll → Query → Ranking

1:N search memerlukan enrollment terlebih dahulu. Alurnya adalah:

1. Buat keyspace — siapkan namespace untuk kelompok identitas (Keyspace)
2. Enroll identitas — daftarkan foto wajah setiap identitas ke keyspace (Enrollment)
3. Query foto — kirim foto yang ingin diidentifikasi ke endpoint recognition
4. Terima ranking — FREMIS-N mengembalikan daftar top-k kandidat terurut dari similarity tertinggi

Untuk panduan enrollment dan manajemen keyspace, lihat Enrollment dan Keyspace.

Recognition by Embedding: Extract Dulu, Query Nanti

Selain menerima gambar langsung, FREMIS-N mendukung alur dua langkah:

1. Ekstrak embedding dari foto menggunakan /v1/face/extract-embedding
2. Query embedding menggunakan /v1/face/recognition-by-embedding

Kapan menggunakan alur ini:

• Batch processing — jika Anda perlu mengidentifikasi banyak foto sekaligus, ekstrak semua embedding terlebih dahulu (bisa diparalelkan), lalu query satu per satu atau dalam pipeline terpisah
• Hemat komputasi — jika foto yang sama perlu di-query ke beberapa keyspace berbeda, ekstrak embedding sekali dan gunakan berulang kali
• Persistensi embedding di sisi klien — simpan hasil embedding di sistem Anda untuk keperluan audit, deduplication, atau query ulang tanpa perlu menyimpan foto asli

Extract Embedding sebagai Utility

Endpoint /v1/face/extract-embedding dapat digunakan secara independen dari alur recognition. Respons menyertakan dua versi embedding:

• embeddings — hasil kuantisasi, lebih kompak untuk penyimpanan
• original — presisi penuh (tersedia jika dikonfigurasi), untuk keperluan yang membutuhkan akurasi tinggi

Embedding yang diekstrak dapat disimpan di sistem klien dan digunakan untuk:

• Enrollment via /v1/face/enrollment-by-embedding
• Recognition via /v1/face/recognition-by-embedding
• Match via /v2/face/match (input vektor)

Use Cases

• Pencarian DPO — identifikasi individu dalam daftar buronan dari foto CCTV atau foto yang dilaporkan
• Watchlist matching — deteksi real-time individu dalam daftar pengawasan keamanan
• Batch deduplication — temukan identitas duplikat dalam database enrollment yang besar
• Access control berbasis pengenalan — identifikasi karyawan atau tamu tanpa kartu fisik
• Event retrospektif — cari siapa saja yang hadir di suatu lokasi berdasarkan rekaman historis

Tips & Troubleshooting

Tiga gejala paling umum saat 1:N recognition tidak menghasilkan jawaban yang Anda harapkan, beserta langkah diagnosanya.

"No Match Found" Padahal Seharusnya Cocok

Sistem mengembalikan candidates kosong meskipun identitas target sudah di-enroll.

• Threshold di sisi aplikasi terlalu tinggi. Ingat, FREMIS-N tidak melakukan filtering — aplikasi Anda yang membandingkan similarity dengan threshold. Coba turunkan sementara dari 0.85 ke 0.75. Jika kandidat sekarang muncul, threshold perlu disesuaikan dengan data deployment.
• Keyspace berbeda. Pastikan request enrollment dan request recognition menggunakan nilai keyspace yang sama persis.
• Identitas belum di-enroll. Verifikasi via GET /v1/face/keyspace/{keyspace}/enrollment bahwa face_id benar-benar terdaftar.
• Query image kualitas rendah. Foto blur, sudut ekstrem, atau wajah terlalu kecil membuat embedding query menjauh dari embedding enrollment. Aktifkan IQA di sisi enrollment dan re-test dengan foto query yang lebih baik.
• Enrollment hanya satu variasi. Tambahkan 2–3 variasi per identitas dengan sudut dan pencahayaan berbeda — multi-variasi adalah cara paling efektif menutupi gap kondisi pengambilan foto query.

False Match — Cocok dengan Orang Lain

Sistem mengembalikan kandidat dengan similarity tinggi tetapi orangnya berbeda.

• Naikkan threshold. Coba 0.88 dan monitor false positive rate. Untuk audit forensik, naikkan ke 0.90+.
• Audit data enrollment. Cari duplikat atau identitas yang salah label menggunakan get-duplicate-variations. Hapus variasi berkualitas rendah, masker, kacamata gelap, atau crop wajah parsial.
• Catat kasus untuk review. Simpan face_id yang salah dikenali beserta similarity yang dikembalikan — pola false match sering menunjukkan bahwa enrollment satu identitas perlu diperbaiki.

Similarity Score Selalu Rendah

Setiap recognition mengembalikan similarity konsisten rendah (< 0.60) bahkan untuk foto yang jelas cocok.

1. Bandingkan dengan referensi terkontrol. Ambil dua foto frontal berkualitas baik dari orang yang sama, jalankan 1:1 match — similarity harus berada di range 0.80–0.95. Jika masih rendah, suspect model mismatch.
2. Cek versi FREMIS-N di seluruh node. Untuk cluster, semua worker dan coordinator harus menjalankan versi yang sama. Setelah upgrade major, sample re-enroll mungkin diperlukan agar embedding kompatibel.
3. Verifikasi preprocessing klien. Jika klien Anda melakukan resize/crop/kompresi sebelum kirim, kirim foto raw langsung sebagai test untuk menyingkirkan preprocessing sebagai penyebab.
4. Konsistensi flag sigmoid. Jika FREMISN_SIGMOID_SIMILARITY_ENABLE diubah, threshold lama tidak setara — lakukan tuning ulang.

Selanjutnya