1:1 Match

Verifikasi apakah dua foto wajah merupakan orang yang sama menggunakan similarity score dan threshold.

1:1 Match — atau face verification — adalah kemampuan FREMIS-N untuk membandingkan dua foto wajah secara langsung dan menjawab satu pertanyaan sederhana: "Apakah kedua foto ini menampilkan orang yang sama?" Berbeda dengan pencarian 1:N yang membutuhkan database enrollment, 1:1 match bekerja sepenuhnya antara dua foto tanpa perlu menyimpan identitas terlebih dahulu.

Halaman ini menjelaskan konsep dan use case 1:1 match. Untuk referensi endpoint lengkap, lihat 1:1 Match API.

Apa itu 1:1 Match

1:1 match membandingkan representasi matematis wajah dari dua foto — disebut embedding — dan mengukur seberapa mirip keduanya. Hasilnya adalah similarity score: angka antara 0.0 dan 1.0 yang mencerminkan tingkat kemiripan wajah dalam kedua foto.

Gunakan 1:1 match ketika:

Anda sudah tahu identitas yang perlu diverifikasi — misalnya, memastikan foto selfie cocok dengan foto KTP
Tidak perlu menyimpan identitas ke database; cukup bandingkan dua foto secara langsung
Anda membangun flow verifikasi di mana keputusan "cocok atau tidak" diambil saat itu juga

Perbedaan dengan 1:N Search

	1:1 Match	1:N Search
Pertanyaan	"Apakah A dan B orang yang sama?"	"Siapa orang ini?"
Input	Dua foto (atau embedding/face_id)	Satu foto query
Membutuhkan enrollment	Tidak	Ya
Output	Similarity score (dan flag `match` di v1)	Daftar kandidat top-k beserta similarity
Use case	Verifikasi identitas, KYC	Pengenalan dari CCTV, akses kontrol

Untuk skenario di mana identitas sudah perlu didaftarkan terlebih dahulu sebelum diverifikasi, lihat 1:N Search.

Similarity Score dan Threshold

Setiap perbandingan menghasilkan similarity score — nilai antara 0.0 dan 1.0. Nilai mendekati 1.0 berarti dua wajah sangat mirip; nilai mendekati 0.0 berarti sangat berbeda.

Threshold adalah batas minimum yang Anda tentukan untuk menyatakan bahwa dua wajah "cocok". Pilihan threshold memengaruhi akurasi:

Threshold	Efek
Terlalu rendah (misal `0.60`)	Banyak pasangan berbeda yang dianggap cocok (false match)
Terlalu tinggi (misal `0.95`)	Pasangan yang sebenarnya sama bisa terlewat (false negative)
Seimbang (misal `0.80–0.87`)	Titik tengah yang baik untuk sebagian besar deployment

Tidak ada nilai threshold universal. Lakukan evaluasi dengan data nyata dari lingkungan deployment Anda. Untuk panduan lengkap tuning threshold, lihat Developer Guide.

Similarity dihitung dengan membandingkan kedua embedding wajah, lalu dipetakan ke rentang 0.0–1.0. Jika Anda mengaktifkan FREMISN_SIGMOID_SIMILARITY_ENABLE, nilai similarity akan diproses ulang melalui fungsi sigmoid — ini mengubah skala numeriknya. Jika Anda mengaktifkan atau menonaktifkan opsi ini, lakukan tuning ulang threshold karena nilai yang berlaku sebelumnya tidak akan setara.

Pipeline 1:1 Match

Setiap request ke /v1/face/match menjalankan pipeline ekstraksi dua kali — satu kali untuk setiap gambar. Kedua gambar diproses secara independen melalui antrian kerja internal (FIFO) yang dikerjakan oleh sejumlah thread sesuai konfigurasi --max-workers. Untuk penjelasan lengkap cara kerja antrian ini, lihat Internal Work Queue.

Total inferensi neural network per request: 4 (deteksi + ekstraksi untuk setiap gambar). 1:1 match tidak menyentuh database atau indeks pencarian — seluruh komputasi berlangsung di pipeline vision.

Bentuk Response

`POST /v1/face/match`

{
  "face_match": {
    "match": true,
    "similarity": 0.873
  }
}

`POST /v2/face/match`

{
  "similarity": 0.873
}

v2 hanya mengembalikan angka similarity — tanpa field match. Keputusan threshold sepenuhnya ada di sisi aplikasi pemanggil. Ini berguna jika Anda ingin memusatkan logika threshold di satu tempat, atau ingin menerapkan threshold berbeda per konteks penggunaan.

v1 vs v2: Pilih yang Mana

FREMIS-N menyediakan dua versi endpoint 1:1 match dengan perilaku berbeda:

v1 — `/v1/face/match`

Menerima dua foto wajah dalam format base64 (image_a dan image_b)
Mengembalikan similarity score sekaligus flag boolean match berdasarkan threshold internal FREMIS-N
Cocok untuk integrasi cepat di mana keputusan threshold diserahkan ke service

v2 — `/v2/face/match`

Menerima input yang jauh lebih fleksibel: setiap sisi (face_a, face_b) dapat berupa gambar base64, vektor embedding, atau face_id yang sudah terdaftar di keyspace
Hanya mengembalikan similarity score tanpa flag match — keputusan threshold sepenuhnya di sisi aplikasi pemanggil
Cocok ketika salah satu atau kedua sisi sudah memiliki embedding tersimpan, menghindari komputasi ulang ekstraksi fitur

Jika salah satu wajah sudah dienroll di FREMIS-N, gunakan v2 dengan face_id untuk efisiensi. Embedding tidak perlu dihitung ulang dari gambar.

Use Cases

KYC (Know Your Customer) — verifikasi bahwa foto selfie yang dikirim pengguna cocok dengan foto dokumen identitas (KTP, paspor)
Akses kontrol — konfirmasi bahwa wajah yang terdeteksi di kamera pintu cocok dengan foto referensi yang tersimpan
Verifikasi identitas transaksi — pastikan orang yang melakukan transaksi adalah pemilik akun yang sah
Deduplication — cek apakah dua entri dalam database merupakan orang yang sama sebelum enrollment
Audit forensik — bandingkan wajah dari rekaman CCTV dengan foto referensi untuk keperluan investigasi