PersonDirectory veri yapısını kullanma (önizleme)

Makale
02/27/2024

Dikkat

Yüz tanıma hizmeti erişimi, Sorumlu yapay zeka ilkelerimizi desteklemek için uygunluk ve kullanım ölçütlerine göre sınırlıdır. Yüz tanıma hizmeti yalnızca Microsoft tarafından yönetilen müşteriler ve iş ortakları tarafından kullanılabilir. Erişim için başvurmak için Yüz Tanıma giriş formunu kullanın. Daha fazla bilgi için Yüz sınırlı erişim sayfasına bakın.

Benzerini Tanımla ve Bul 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. PersonDirectory , Genel Önizleme'de 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. PersonDirectory ile temel görevlerin nasıl yapılacağını öğrenmek için bu kılavuzu izleyin.

PersonDirectory'nin Avantajları

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

PersonDirectory ile önceki veri yapıları arasındaki bir diğer önemli fark da, bir Kişi nesnesine yüz ekledikten sonra artık Herhangi bir Train API çağrısı yapmanız gerekmeyebilecek olmasıdır; güncelleştirme işlemi otomatik olarak gerçekleşir.

Önkoşullar

Azure aboneliği - Ücretsiz bir abonelik oluşturun.
Azure aboneliğinizi aldıktan sonra anahtarınızı ve uç noktanızı almak için Azure portalında bir Yüz Tanıma kaynağı oluşturun. Dağıtıldıktan sonra Kaynağa git'i seçin.
- Uygulamanızı Yüz Tanıma API'sine bağlamak için oluşturduğunuz kaynaktan anahtara ve uç noktaya ihtiyacınız olacaktır. Anahtarınızı ve uç noktanızı aşağıdaki koda yapıştıracaksınız.
- Ücretsiz fiyatlandırma katmanını (F0) kullanarak hizmeti deneyebilir ve daha sonra üretim için ücretli bir katmana yükseltebilirsiniz.

PersonDirectory'ye Kişi Ekleme

Kişiler , PersonDirectory'deki temel kayıt birimleridir. Dizine bir Kişi ekledikten sonra, tanıma modeli başına bu Kişiye en fazla 248 yüz görüntüsü ekleyebilirsiniz. Ardından, farklı kapsamlar kullanarak yüzleri tanımlayabilirsiniz.

Kişiyi 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 için oluşturulan bir kimliği ve bir işlem konumunu döndürür. Kişi verileri zaman uyumsuz olarak işlenir, bu nedenle sonuçları getirmek için işlem konumunu kullanırsınız.

Zaman uyumsuz işlemin tamamlanmasını bekleyin

İlerleme durumunu denetlemek için döndürülen işlem konumu dizesini kullanarak zaman uyumsuz işlem durumunu sorgulamanız 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 yoklayabilir 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ürüldüğünde, Person nesnesi dizine eklendiği kabul edilir.

Not

Kişi Oluştur çağrısının zaman uyumsuz işleminin, yüzlerin eklenebilmesi için önce "başarılı" durumunu göstermesi gerekmez, ancak Kişinin bir DynamicPersonGroup'a eklenebilmesi (dynamicpersongroup oluşturma ve güncelleştirme bölümüne bakın) veya Bir Tanımlayıcı çağrısı sırasında karşılaştırılmadan önce tamamlanması gerekir. Yüzler Kişi'ye başarıyla eklendikten hemen sonra çağrıların çalıştığını doğrulayın.

Kişilere yüz ekleme

Kişi Oluştur aramasından Kişi Kimliğini aldıktan sonra, tanıma modeli başına bir Kişiye en fazla 248 yüz görüntüsü ekleyebilirsiniz. Çağrıda kullanılacak tanıma modelini (ve isteğe bağlı olarak algılama modelini) belirtin; her tanıma modeli altındaki veriler PersonDirectory içinde ayrı olarak işlenecektir.

Şu anda desteklenen tanıma modelleri şunlardır:

Recognition_02
Recognition_03
Recognition_04

Ayrıca, görüntü birden çok yüz içeriyorsa, hedeflenen 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ından sonra yüz verileri zaman uyumsuz olarak işlenir ve işlemin daha önce olduğu gibi başarılı olmasını beklemeniz gerekir.

Yüz ekleme işlemi tamamlandığında, tanımlama çağrılarında veriler hazır olur.

DynamicPersonGroup oluşturma ve güncelleştirme

DynamicPersonGroups, bir PersonDirectory içindeki Person nesnelerine yapılan başvuru koleksiyonlarıdır; dizinin alt kümelerini oluşturmak için kullanılır. Kapsamı yalnızca eşleşmesini beklediğiniz Kişi nesneleriyle sınırlayarak bir Tanımlama işleminde daha az hatalı pozitif sonuç ve daha fazla doğruluk elde etmek istediğinizde yaygın bir kullanımdır. Pratik kullanım örnekleri, daha büyük bir kampüs veya kuruluş arasında belirli bina erişimine yönelik dizinleri içerir. Kuruluş dizini 5 milyon kişi içerebilir, ancak belirli bir bina için yalnızca belirli bir 800 kişiyi aramanız gerekir, bu nedenle söz konusu kişileri içeren bir DynamicPersonGroup oluşturabilirsiniz.

Daha önce bir PersonGroup kullandıysanız, iki önemli farka dikkat edin:

Bir DynamicPersonGroup içindeki her Kişi, PersonDirectory'deki gerçek Kişiye bir başvurudur, yani her grupta bir Kişi'yi yeniden oluşturmak gerekli değildir.
Önceki bölümlerde belirtildiği gibi, yüz verileri Dizin düzeyinde otomatik olarak işlendiğinden Train çağrıları yapmanıza gerek yoktur.

Grubu oluşturma

DynamicPersonGroup oluşturmak için alfasayısal veya tire karakterleri içeren bir grup kimliği sağlamanız gerekir. Bu kimlik, grubun tüm kullanım amaçları için benzersiz tanımlayıcı işlevi görür.

Grup koleksiyonunu başlatmanın iki yolu vardır. Başlangıçta boş bir grup oluşturabilir ve daha sonra doldurabilirsiniz:

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 gerçekleşir ve zaman uyumsuz işlemlerin başarılı olmasını beklemeniz gerekmez.

Alternatif olarak, AddPersonIds bağımsız değişkeninde kümeyi sağlayarak bu başvuruları baştan içerecek bir 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");
}

Not

Çağrı geri döner dönmez, oluşturulan DynamicPersonGroup, süreçte sağlanan kişi başvuruları ile bir Tanımla çağrısında kullanılmaya hazır olur. Öte yandan, döndürülen işlem kimliğinin tamamlanma durumu, kişi-grup ilişkisinin güncelleştirme durumunu gösterir.

DynamicPersonGroup'ı güncelleştirme

İlk oluşturma işleminden sonra, Dinamik Kişi Grubunu Güncelleştir API'siyle DynamicPersonGroup'a Kişi başvuruları ekleyebilir ve kaldırabilirsiniz. Gruba Kişi nesneleri eklemek için addPersonsIds bağımsız değişkeninde Kişi Kimliklerini listeleyin. Kişi nesnelerini kaldırmak için removePersonIds bağımsız değişkeninde listeleyin. Hem ekleme hem de kaldırma işlemleri tek bir çağrıda gerçekleştirilebilir:

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ı döndürüldükten sonra, grup sorgulandığında koleksiyon güncelleştirmeleri yansıtılır. Oluşturma API'sinde olduğu gibi, döndürülen işlem de güncelleştirmeye katılan kişiler arası ilişkinin güncelleştirme durumunu gösterir. Gruba daha fazla Güncelleştirme çağrısı yapmadan önce işlemin tamamlanmasını beklemeniz gerekmez.

PersonDirectory'de yüzleri tanımlama

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

PersonDirectory'de, her yüzün tanımlanabileceği üç tür kapsam vardır:

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

İstekte dynamicPersonGroupId özelliğinin belirtilmesi, yüzü grupta başvuruda bulunan her Kişiyle karşılaştırır. Bir çağrıda yalnızca tek bir DynamicPersonGroup tanımlanabilir.

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üzü her biriyle 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

İstekteki personIds özelliğinde tek bir yıldız işareti sağlamak, yüzü PersonDirectory'ye kaydedilen her bir Kişiyle karşılaştırır.

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

Bu üç senaryo için de tanımlama yalnızca gelen yüzü AddPersonFace çağrısı "başarılı" yanıtla döndüren yüzlerle karşılaştırır.

PersonDirectory'deki kişilere karşı yüzleri doğrulama

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

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ü aynı Kişiye ait olarak kabul edip etmediğini belirten bir Boole değeri ve tahmin için bir güvenilirlik puanı içerir.

Sonraki adımlar

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

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