Menggunakan struktur data PersonDirectory (pratinjau)

  • Artikel

Perhatian

Akses layanan Face dibatasi berdasarkan kelayakan dan kriteria penggunaan untuk mendukung prinsip AI kami yang Bertanggung Jawab. Layanan Face hanya tersedia untuk pelanggan dan mitra terkelola Microsoft. Gunakan formulir pengambilan Pengenalan Wajah untuk mengajukan akses. Untuk informasi selengkapnya, lihat halaman Akses terbatas Wajah.

Untuk melakukan operasi pengenalan wajah seperti Identifikasi dan Temukan yang Serupa, pelanggan Face API perlu membuat berbagai daftar urut objek Orang. PersonDirectory adalah struktur data di Pratinjau Umum yang berisi ID unik, string nama opsional, dan string metadata pengguna opsional untuk setiap identitas Orang yang ditambahkan ke direktori. Ikuti panduan ini untuk mempelajari cara melakukan tugas dasar dengan PersonDirectory.

Keuntungan dari PersonDirectory

Saat ini, Face API menawarkan struktur LargePersonGroup yang memiliki fungsi serupa tetapi terbatas pada 1 juta identitas. Struktur PersonDirectory dapat menskalakan hingga 75 juta identitas.

Perbedaan utama lainnya antara PersonDirectory dan struktur data sebelumnya adalah Anda tidak perlu lagi melakukan panggilan API Pelatihan setelah menambahkan wajah ke objek Orang—proses pembaruan terjadi secara otomatis.

Prasyarat

  • Langganan Azure - Buat langganan gratis.
  • Setelah Anda memiliki langganan Azure, buat sumber daya Face di portal Azure untuk mendapatkan kunci dan titik akhir Anda. Setelah menyebar, pilih Buka sumber daya.
    • Anda akan memerlukan kunci dan titik akhir dari sumber daya yang Anda buat untuk menyambungkan aplikasi Anda ke Face API. Anda akan menempelkan kunci dan titik akhir ke dalam kode di bawah ini.
    • Untuk mencoba layanan, Anda dapat menggunakan tingkat harga gratis (F0), lalu meningkatkannya ke tingkat berbayar untuk produksi.

Menambahkan Orang ke PersonDirectory

Orang adalah unit pendaftaran dasar di PersonDirectory. Setelah menambahkan Orang ke direktori, Anda dapat menambahkan hingga 248 gambar wajah ke Orang tersebut, per model pengenalan. Kemudian Anda dapat mengidentifikasi wajah terhadap mereka menggunakan berbagai cakupan.

Membuat Orang

Untuk membuat Orang, Anda perlu memanggil CreatePerson API dan memberikan nama atau userData nilai properti.

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

var addPersonUri = "https:// {endpoint}/face/v1.0-preview/persons";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("name", "Example Person");
body.Add("userData", "User defined data");
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PostAsync(addPersonUri, content); 
}

Panggilan CreatePerson akan menampilkan ID yang dihasilkan untuk Orang tersebut dan lokasi operasi. Data Orang akan diproses secara asinkron, sehingga Anda dapat menggunakan lokasi operasi untuk mengambil hasilnya.

Tunggu hingga operasi asinkron selesai

Anda harus mengkueri status operasi asinkron menggunakan string lokasi operasi yang ditampilkan untuk memeriksa perkembangannya.

Pertama, Anda harus menentukan model data seperti berikut ini untuk menangani respons status.

[Serializable]
public class AsyncStatus
{
    [DataMember(Name = "status")]
    public string Status { get; set; }

    [DataMember(Name = "createdTime")]
    public DateTime CreatedTime { get; set; }

    [DataMember(Name = "lastActionTime")]
    public DateTime? LastActionTime { get; set; }

    [DataMember(Name = "finishedTime", EmitDefaultValue = false)]
    public DateTime? FinishedTime { get; set; }

    [DataMember(Name = "resourceLocation", EmitDefaultValue = false)]
    public string ResourceLocation { get; set; }

    [DataMember(Name = "message", EmitDefaultValue = false)]
    public string Message { get; set; }
}

Dengan HttpResponseMessage dari atas, Anda kemudian dapat melakukan polling URL dan menunggu hasil.

string operationLocation = response.Headers.GetValues("Operation-Location").FirstOrDefault();

Stopwatch s = Stopwatch.StartNew();
string status = "notstarted";
do
{
    if (status == "succeeded")
    {
        await Task.Delay(500);
    }

    var operationResponseMessage = await client.GetAsync(operationLocation);

    var asyncOperationObj = JsonConvert.DeserializeObject<AsyncStatus>(await operationResponseMessage.Content.ReadAsStringAsync());
    status = asyncOperationObj.Status;

} while ((status == "running" || status == "notstarted") && s.Elapsed < TimeSpan.FromSeconds(30));

Setelah statusnya menampilkan "berhasil", objek Person dianggap sudah ditambahkan ke direktori.

Catatan

Operasi asinkron dari panggilan Buat Orang tidak harus menunjukkan status "berhasil" sebelum wajah dapat ditambahkan ke dalamnya, tetapi perlu diselesaikan sebelum Orang tersebut dapat ditambahkan ke DynamicPersonGroup (lihat di bawah Membuat dan memperbarui DynamicPersonGroup) atau dibandingkan selama panggilan Identifikasi. Verifikasi panggilan akan segera berfungsi setelah wajah berhasil ditambahkan ke Orang.

Menambahkan wajah ke Orang

Setelah Anda memiliki ID Orang dari panggilan Buat Orang, Anda dapat menambahkan hingga 248 gambar wajah ke model Orang per pengenalan. Tentukan model pengenalan (dan secara opsional model deteksi) untuk digunakan dalam panggilan, karena data dengan setiap model pengenalan akan diproses secara terpisah di dalam PersonDirectory.

Model pengenalan yang saat ini didukung adalah:

  • Recognition_02
  • Recognition_03
  • Recognition_04

Selain itu, jika gambar berisi beberapa wajah, Anda harus menentukan kotak pembatas persegi panjang untuk wajah yang merupakan target yang dimaksud. Kode berikut menambahkan wajah ke objek Orang.

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

// Optional query strings for more fine grained face control
var queryString = "userData={userDefinedData}&targetFace={left,top,width,height}&detectionModel={detectionModel}";
var uri = "https://{endpoint}/face/v1.0-preview/persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces?" + queryString;

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("url", "{image url}");
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PostAsync(uri, content);
}

Setelah panggilan Tambahkan Wajah, data wajah akan diproses secara tidak sinkron, dan Anda harus menunggu keberhasilan operasi dengan cara yang sama seperti sebelumnya.

Ketika operasi untuk penambahan wajah selesai, data akan siap untuk panggilan Identifikasi.

Membuat dan memperbarui DynamicPersonGroup

DynamicPersonGroups adalah kumpulan referensi ke objek Orang dalam PersonDirectory; koleksi ini digunakan untuk membuat subset direktori. Penggunaan umum adalah ketika Anda ingin mendapatkan lebih sedikit positif palsu dan peningkatan akurasi dalam operasi Identifikasi dengan membatasi cakupan hanya untuk objek Orang yang Anda harapkan cocok. Kasus penggunaan praktis mencakup direktori untuk akses bangunan tertentu di antara kampus atau organisasi yang lebih besar. Direktori organisasi mungkin berisi 5 juta individu, tetapi Anda hanya perlu mencari 800 orang tertentu untuk bangunan tertentu, sehingga Anda akan membuat DynamicPersonGroup yang berisi individu tertentu.

Jika Anda telah menggunakan PersonGroup sebelumnya, perhatikan dua perbedaan utama:

  • Setiap Orang di dalam DynamicPersonGroup adalah referensi ke Orang yang sebenarnya dalam PersonDirectory, yang berarti bahwa tidak perlu membuat ulang Orang di setiap grup.
  • Seperti yang telah disebutkan pada bagian sebelumnya, panggilan Pelatihan tidak perlu dilakukan, karena data wajah diproses di tingkat Direktori secara otomatis.

Membuat grup

Untuk membuat DynamicPersonGroup, Anda perlu menyediakan ID grup dengan karakter alfanumerik atau garis putus-putus. ID ini akan berfungsi sebagai pengidentifikasi unik untuk semua tujuan penggunaan grup.

Ada dua cara untuk menginisialisasi koleksi grup. Anda dapat membuat grup kosong di awal, dan mengisinya nanti:

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

var uri = "https://{endpoint}/face/v1.0-preview/dynamicpersongroups/{dynamicPersonGroupId}";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("name", "Example DynamicPersonGroup");
body.Add("userData", "User defined data");
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PutAsync(uri, content);
}

Proses ini bersifat langsung dan tidak perlu menunggu keberhasilan operasi asinkron.

Atau, Anda dapat membuatnya dengan sekumpulan ID Orang agar berisi referensi tersebut dari awal dengan menyediakan set dalam argumen AddPersonIds:

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

var uri = "https://{endpoint}/face/v1.0-preview/dynamicpersongroups/{dynamicPersonGroupId}";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("name", "Example DynamicPersonGroup");
body.Add("userData", "User defined data");
body.Add("addPersonIds", new List<string>{"{guid1}", "{guid2}", …});
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PutAsync(uri, content);

    // Async operation location to query the completion status from
    var operationLocation = response.Headers.Get("Operation-Location");
}

Catatan

Segera setelah panggilan muncul, DynamicPersonGroup yang dibuat akan siap digunakan dalam panggilan Identifikasi, dengan referensi Orang yang disediakan dalam proses. Status penyelesaian ID operasi yang ditampilkan, di sisi lain, menunjukkan status pembaruan hubungan orang dengan grup.

Memperbarui DynamicPersonGroup

Setelah pembuatan awal, Anda dapat menambahkan dan menghapus referensi Orang dari DynamicPersonGroup dengan Update Dynamic Person Group API. Untuk menambahkan objek Orang ke grup, cantumkan ID Orang dalam argumen addPersonsIds. Untuk menghapus objek Orang, cantumkan daftar ID tersebut dalam argumen removePersonIds. Menambahkan dan menghapus dapat dilakukan dalam satu panggilan:

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

var uri = "https://{endpoint}/face/v1.0-preview/dynamicpersongroups/{dynamicPersonGroupId}";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("name", "Example Dynamic Person Group updated");
body.Add("userData", "User defined data updated");
body.Add("addPersonIds", new List<string>{"{guid1}", "{guid2}", …});
body.Add("removePersonIds", new List<string>{"{guid1}", "{guid2}", …});
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PatchAsync(uri, content);

    // Async operation location to query the completion status from
    var operationLocation = response.Headers.Get("Operation-Location");
}

Setelah panggilan tampil, pembaruan untuk koleksi akan tercermin saat grup dikueri. Seperti halnya API pembuatan, operasi yang ditampilkan menunjukkan status pembaruan hubungan orang dengan grup untuk setiap Orang yang terlibat dalam pembaruan. Anda tidak perlu menunggu penyelesaian operasi sebelum melakukan panggilan Pembaruan lebih lanjut ke grup.

Mengidentifikasi wajah dalam PersonDirectory

Cara paling umum untuk menggunakan data wajah dalam PersonDirectory adalah dengan membandingkan objek Orang yang terdaftar dengan wajah tertentu dan mengidentifikasi kandidat yang paling mungkin dimilikinya. Beberapa wajah dapat dimasukkan dalam permintaan, dan masing-masing akan menerima serangkaian hasil perbandingannya sendiri dalam merespons.

Dalam PersonDirectory, ada tiga jenis cakupan yang menjadi dasar identifikasi setiap wajah:

Skenario 1: Identifikasi terhadap DynamicPersonGroup

Menentukan properti dynamicPersonGroupId dalam permintaan akan membandingkan wajah dengan setiap Orang yang direferensikan dalam grup. Hanya satu DynamicPersonGroup yang dapat diidentifikasi dalam panggilan.

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

// Optional query strings for more fine grained face control
var uri = "https://{endpoint}/face/v1.0-preview/identify";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("faceIds", new List<string>{"{guid1}", "{guid2}", …});
body.Add("dynamicPersonGroupId", "{dynamicPersonGroupIdToIdentifyIn}");
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PostAsync(uri, content);
}

Skenario 2: Identifikasi terhadap daftar orang tertentu

Anda juga dapat menentukan daftar ID Orang di properti personIds untuk membandingkan wajah masing-masing.

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");
            
var uri = "https://{endpoint}/face/v1.0-preview/identify";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("faceIds", new List<string>{"{guid1}", "{guid2}", …});
body.Add("personIds", new List<string>{"{guid1}", "{guid2}", …});
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PostAsync(uri, content);
}

Skenario 3: Identifikasi terhadap seluruh PersonDirectory

Menyediakan satu tanda bintang di properti personIds dalam permintaan membandingkan wajah terhadap setiap Orang yang terdaftar dalam PersonDirectory.

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");
            
var uri = "https://{endpoint}/face/v1.0-preview/identify";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("faceIds", new List<string>{"{guid1}", "{guid2}", …});
body.Add("personIds", new List<string>{"*"});
byte[] byteData = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PostAsync(uri, content);
}

Untuk ketiga skenario, identifikasi hanya membandingkan wajah yang masuk terhadap wajah yang panggilan AddPersonFace-nya telah ditampilkan dengan respons "berhasil".

Memverifikasi wajah terhadap orang dalam PersonDirectory

Dengan ID wajah yang ditampilkan dari panggilan deteksi, Anda dapat memverifikasi apakah wajah tersebut milik Orang tertentu yang terdaftar dalam PersonDirectory. Tentukan Orang yang menggunakan properti personId.

var client = new HttpClient();

// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

var uri = "https://{endpoint}/face/v1.0-preview/verify";

HttpResponseMessage response;

// Request body
var body = new Dictionary<string, object>();
body.Add("faceId", "{guid1}");
body.Add("personId", "{guid1}");
var jsSerializer = new JavaScriptSerializer();
byte[] byteData = Encoding.UTF8.GetBytes(jsSerializer.Serialize(body));

using (var content = new ByteArrayContent(byteData))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    response = await client.PostAsync(uri, content);
}

Respons akan berisi nilai Boolean yang menunjukkan apakah layanan menganggap wajah baru milik Orang yang sama, dan skor keyakinan untuk prediksi.

Langkah berikutnya

Dalam panduan ini, Anda telah mempelajari cara menggunakan struktur PersonDirectory untuk menyimpan data wajah dan orang untuk aplikasi Face Anda. Selanjutnya, pelajari praktik terbaik untuk menambahkan data wajah pengguna.