PersonDirectory yapısını kullanma

Benzerleri Belirleme ve Bulma gibi yüz tanıma işlemlerini gerçekleştirmek için Yüz Tanıma API'si müşterilerinin kişi nesnelerinin çeşitli bir listesini oluşturması gerekir. Yeni PersonDirectory, dizine eklenen her Kişi kimliği için benzersiz kimlikler, isteğe bağlı ad dizeleri ve isteğe bağlı kullanıcı meta veri dizeleri içeren bir veri yapısıdır.

Şu anda Yüz Tanıma API'si benzer işlevlere sahip olan ancak 1 milyon kimlikle sınırlı olan LargePersonGroup yapısını sunmaktadır. PersonDirectory yapısının ölçeği 75 milyona kadar olabilir.

PersonDirectory ile önceki veri yapıları arasındaki bir diğer önemli fark, güncelleştirme işleminin otomatik olarak gerçekleşirken person nesnesine yüz ekledikten sonra Train çağrısı yapmanıza gerek — kalmamasıdır.

Önkoşullar

• Azure aboneliği - Ücretsiz bir abonelik oluşturun.
• Azure aboneliğinize sahip olduktan sonra anahtarınızı ve uç noktanızı almak Azure portal içinde bir Yüz Yüzü kaynağı oluşturun. Dağıtımdan sonra Kaynağa git'e tıklayın.
  • Uygulamanıza Yüz Tanıma API'sini bağlamak için, oluşturmakta olduğu kaynağın anahtarına ve uç noktasına ihtiyacınız vardır. Anahtarınızı ve uç noktanızı aşağıdaki koda yapıştırabilirsiniz.
  • Hizmeti denemek ve daha sonra üretim için ücretli katmana yükseltmek üzere ücretsiz fiyatlandırma katmanını (F0) kullanabilirsiniz.

PersonDirectory'ye Kişi Ekleme

Kişiler, PersonDirectory dizininde bulunan temel kayıt birimleridir. Dizine bir Kişi eklemenizin ardından, tanıma modeli başına bu Kişi ' ye en fazla 248 yüz görseli ekebilirsiniz. Daha sonra, farklı kapsamları kullanarak yüzleri tanımlayabilirsiniz.

Kişi oluşturma

Kişi oluşturmak için CreatePerson API'sini çağırmanız ve bir ad veya userData özellik değeri sağlamanız gerekir.

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); 
}

CreatePerson çağrısı, Kişi ve işlem konumu için oluşturulmuş bir kimlik geri döner. Kişi verileri zaman uyumsuz olarak işlenir, bu nedenle sonuçları getirmek için işlem konumunu kullanırsiniz.

Zaman uyumsuz işlem tamamlanmasını bekleyin

İlerleme durumunu kontrol etmek için döndürülen işlem konumu dizesini kullanarak zaman uyumsuz işlem durumunu sorgulamak gerekir.

İlk olarak, durum yanıtını işlemek için aşağıdakine benzer bir veri modeli tanımlamanız gerekir.

[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; }
}

Yukarıdaki HttpResponseMessage'ı kullanarak URL'yi yoklar ve sonuçları bekleyebilirsiniz.

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));

Durum "başarılı" olarak döndüren Person nesnesinin dizine ekli olduğu kabul edilir.

Kişiler'e yüz ekleme

Kişi Oluştur çağrısından Kişi Kimliği'ne sahip olduktan sonra, tanıma modeli başına Kişi'ye en fazla 248 adet yüz görüntüleri eklemek için. Her tanıma modeli altındaki veriler PersonDirectory içinde ayrı olarak işlendiğinden, çağrıda kullanmak üzere tanıma modelini (ve isteğe bağlı olarak algılama modelini) belirtin.

Şu anda desteklenen tanıma modelleri:

• Recognition_02
• Recognition_03
• Recognition_04

Ayrıca, görüntü birden çok yüz içeriyorsa, hedeflenen hedef olan yüz için dikdörtgen sınırlayıcı kutuyu belirtmeniz gerekir. Aşağıdaki kod bir Person nesnesine yüz ekler.

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);
}

Yüz Ekle çağrısının ardından yüz verileri zaman uyumsuz olarak işlenir ve daha önce olduğu gibi işlemi başarıyla beklemelisiniz.

Yüz ekleme işlemi tamam olduğunda, veriler Tanımlama çağrılarında için hazır olur.

DynamicPersonGroup oluşturma ve güncelleştirme

DynamicPersonGroups, PersonDirectory içindeki Kişi nesnelerine yapılan başvuru koleksiyonlarıdır; dizinin alt kümelerini oluşturmak için kullanılır. Yaygın kullanımlardan biri, kapsamı yalnızca eşleşmeyi beklediğiniz Kişi nesneleriyle sınırlandırarak Bir Belirleme işleminde daha az hatalı pozitif sonuç ve daha fazla doğruluk elde etmek istemenizdir. Pratik kullanım örnekleri, daha büyük bir kampüs veya kuruluş arasında belirli bir bina erişimine yönelik dizinleri içerir. Kuruluş dizininde 5 milyon kişi olabilir, ancak belirli bir bina için yalnızca belirli bir 800 kişiyi aramanız gerekir, bu nedenle söz konusu belirli bireyleri içeren bir DynamicPersonGroup oluşturabilirsiniz.

Daha önce bir PersonGroup kullandıysanız iki önemli farkı göz önünde bulundurabilirsiniz:

• DynamicPersonGroup içindeki her Kişi, PersonDirectory içindeki gerçek Kişiye başvurur. Başka bir ifadeyle, her grupta bir Kişi oluşturmak gerekli değildir.
• Önceki bölümlerde belirtildiği gibi, yüz verileri Dizin düzeyinde otomatik olarak işlendiğinden Eğitim çağrıları yapmaya gerek yoktur.

Grubu oluşturma

DynamicPersonGroup oluşturmak için alfasayısal veya kısa çizgi karakterleri içeren bir grup kimliği sağlamalıdır. Bu kimlik, grubun tüm kullanım amaçları için benzersiz tanımlayıcı olarak işlev gösterir.

Bir grup koleksiyonunu başlatmanın iki yolu vardır. Başlangıçta boş bir grup oluşturabilir ve daha sonra bu grubu doldurmak için:

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);
}

Bu işlem hemen uzer ve zaman uyumsuz işlemlerin başarılı olması için beklemeye gerek yoktur.

Alternatif olarak, AddPersonIds bağımsız değişkensinde kümeyi sağlayarak en baştan bu başvuruları içeren kişi kimlikleri kümesiyle oluşturabilirsiniz:

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");
}

DynamicPersonGroup'ları güncelleştirme

İlk oluşturmadan sonra, Dinamik Kişi Grubunu Güncelleştirme API'sini kullanarak DynamicPersonGroup'tan Kişi başvuruları ekleyebilir ve kaldırabilirsiniz. Gruba Kişi nesneleri eklemek için addPersonsIds bağımsız değişkende Kişi Kimliklerini listele. Kişi nesnelerini kaldırmak için bunları removePersonIds bağımsız değişkende listele. Ekleme ve kaldırma işlemi tek bir çağrıda yapılabilir:

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");
}

Çağrı geri döndüğünde, grup sorgulanan koleksiyon güncelleştirmeleri yansıtıldı. Oluşturma API'sinde olduğu gibi, döndürülen işlem güncelleştirmeye dahil olan herhangi bir Kişi için kişi-grup ilişkisinin güncelleştirme durumunu gösterir. Gruba daha fazla Update çağrısı yapmadan önce işlem tamamlanmasını beklemeniz gerekir.

PersonDirectory'de yüzleri tanımlama

PersonDirectory'de yüz verilerini kullanmanın en yaygın yolu, kayıtlı Kişi nesnelerini verilen bir yüzle karşılaştırmak ve ait olduğu en olası adayı belirlemektir. İstekte birden çok yüz sağlanmalıdır ve her biri yanıtta kendi karşılaştırma sonuçları kümesi alır.

PersonDirectory'de her yüz için üç tür kapsam tanımlanır:

Senaryo 1: DynamicPersonGroup'a karşı tanımlama

İstekte dynamicPersonGroupId özelliğinin belirterek yüzü grupta başvurulan her Kişi ile karşılaştırıldığında. Bir çağrıda yalnızca tek bir DynamicPersonGroup ile belirlen olabilir.

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);
}

Senaryo 2: Belirli bir kişi listesine göre tanımlama

Yüzleri her biri ile karşılaştırmak için personIds özelliğinde Kişi Kimliklerinin listesini de belirtebilirsiniz.

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);
}

Senaryo 3: PersonDirectory'nin tamamına karşı tanımlama

İstekte personIds özelliğinde tek bir yıldız işareti sağlamak, yüzü PersonDirectory'ye kayıtlı her bir Kişi ile karşılaştırıldığında.

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);
}

Üç senaryoda da belirleme, gelen yüzü yalnızca AddPersonFace çağrısı "başarılı" yanıtla döndürülen yüzlerle karşılaştırıldığında sağlar.

PersonDirectory'de yüzleri kişilerden doğrulama

Algılama çağrısından döndürülen bir yüz kimliğiyle, yüzün PersonDirectory içinde kayıtlı belirli bir Kişiye ait olup olmadığını doğrularsiniz. personId özelliğini kullanarak Kişi'i belirtin.

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);
}

Yanıt, hizmetin yeni yüzün aynı Kişi'ye ait olduğunu kabul edip edip ede olmadığını belirten bir Boole değeri ve tahmin için bir güven puanı içerir.

Sonraki adımlar

Bu kılavuzda, Yüz Yüze uygulamanıza yüz ve kişi verilerini depolamak için PersonDirectory yapısını kullanmayı öğrendiniz. Şimdi kullanıcılarının yüz verilerini eklemeye yönelik en iyi yöntemleri öğrenin.

• Kullanıcı eklemeye yönelik en iyi yöntemler