Korzystanie ze struktury danych PersonDirectory (wersja zapoznawcza)

Artykuł
10/16/2024

Uwaga

Dostęp do usługi rozpoznawania twarzy jest ograniczony na podstawie kryteriów kwalifikowalności i użycia w celu obsługi naszych zasad odpowiedzialnej sztucznej inteligencji. Usługa rozpoznawania twarzy jest dostępna tylko dla klientów i partnerów zarządzanych przez firmę Microsoft. Użyj formularza do wprowadzania rozpoznawania twarzy, aby ubiegać się o dostęp. Aby uzyskać więcej informacji, zobacz stronę Dostęp ograniczony do twarzy.

Aby wykonywać operacje rozpoznawania twarzy, takie jak Identyfikowanie i znajdowanie podobnych, klienci interfejsu API rozpoznawania twarzy muszą utworzyć rozdzielaną listę obiektów osoby . PersonDirectory to struktura danych w publicznej wersji zapoznawczej zawierająca unikatowe identyfikatory, opcjonalne ciągi nazw i opcjonalne ciągi metadanych użytkownika dla każdej tożsamości osoby dodanej do katalogu. Postępuj zgodnie z tym przewodnikiem, aby dowiedzieć się, jak wykonywać podstawowe zadania w usłudze PersonDirectory.

Zalety obiektu PersonDirectory

Obecnie interfejs API rozpoznawania twarzy oferuje strukturę LargePersonGroup , która ma podobne funkcje, ale jest ograniczona do 1 miliona tożsamości. Struktura PersonDirectory może skalować do 75 milionów tożsamości.

Kolejną główną różnicą między osobą PersonDirectory i poprzednimi strukturami danych jest to, że nie trzeba już wykonywać żadnych wywołań interfejsu API trenowania po dodaniu twarzy do obiektu Person — proces aktualizacji odbywa się automatycznie.

Wymagania wstępne

Subskrypcja platformy Azure — utwórz jedną bezpłatnie.
Po utworzeniu subskrypcji platformy Azure utwórz zasób rozpoznawania twarzy w witrynie Azure Portal, aby uzyskać klucz i punkt końcowy. Po wdrożeniu wybierz pozycję Przejdź do zasobu.
- Będziesz potrzebować klucza i punktu końcowego z utworzonego zasobu, aby połączyć aplikację z interfejsem API rozpoznawania twarzy. Wkleisz klucz i punkt końcowy do poniższego kodu.
- Możesz użyć bezpłatnej warstwy cenowej (F0), aby wypróbować usługę, a następnie uaktualnić ją do warstwy płatnej dla środowiska produkcyjnego.

Dodawanie osób do personDirectory

Osoby są podstawowymi jednostkami rejestracji w usłudze PersonDirectory. Po dodaniu osoby do katalogu możesz dodać do tego modelu rozpoznawania maksymalnie 248 obrazów twarzy. Następnie można zidentyfikować twarze względem nich przy użyciu różnych zakresów.

Tworzenie osoby

Aby utworzyć osobę, musisz wywołać interfejs API CreatePerson i podać nazwę lub wartość właściwości userData.

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

Wywołanie CreatePerson zwróci wygenerowany identyfikator osoby i lokalizację operacji. Dane osoby zostaną przetworzone asynchronicznie, dlatego użyjesz lokalizacji operacji, aby pobrać wyniki.

Oczekiwanie na zakończenie operacji asynchronicznej

Aby sprawdzić postęp, należy wykonać zapytanie dotyczące stanu operacji asynchronicznych przy użyciu zwróconego ciągu lokalizacji operacji.

Najpierw należy zdefiniować model danych podobny do poniższego, aby obsłużyć odpowiedź stanu.

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

Korzystając z powyższego komunikatu HttpResponseMessage, możesz sondować adres URL i czekać na wyniki.

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

Stopwatch s = Stopwatch.StartNew();
string status = "notstarted";
do
{
    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));

Gdy stan zostanie zwrócony jako "powodzenie", obiekt Person zostanie uznany za dodany do katalogu.

Uwaga

Operacja asynchroniczna z wywołania Utwórz osobę nie musi pokazywać stanu "powodzenie", zanim można dodać do niej twarze, ale przed dodaniu osoby do grupy DynamicPersonGroup (zobacz poniżej tworzenie i aktualizowanie elementu DynamicPersonGroup) lub porównanie podczas wywołania identyfikowania. Sprawdź, czy połączenia będą działać natychmiast po pomyślnym dodaniu twarzy do osoby.

Dodawanie twarzy do osób

Po utworzeniu identyfikatora osoby z wywołania Tworzenie osoby możesz dodać do 248 obrazów twarzy do modelu rozpoznawania Osoby na model rozpoznawania. Określ model rozpoznawania (i opcjonalnie model wykrywania), który ma być używany w wywołaniu, ponieważ dane w ramach każdego modelu rozpoznawania będą przetwarzane oddzielnie wewnątrz obiektu PersonDirectory.

Obecnie obsługiwane modele rozpoznawania to:

Recognition_02
Recognition_03
Recognition_04

Ponadto, jeśli obraz zawiera wiele twarzy, należy określić pole ograniczenia prostokąta dla twarzy, która jest zamierzonym obiektem docelowym. Poniższy kod dodaje twarze do obiektu Person .

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

Po wywołaniu dodawania twarzy dane twarzy będą przetwarzane asynchronicznie i trzeba będzie poczekać na powodzenie operacji w taki sam sposób, jak wcześniej.

Po zakończeniu operacji dodawania twarzy dane będą gotowe do użycia w funkcji Identyfikowanie wywołań.

Tworzenie i aktualizowanie grupy DynamicPersonGroup

DynamicPersonGroups to kolekcje odwołań do obiektów Person w obiekcie PersonDirectory. Są one używane do tworzenia podzestawów katalogu. Typowym zastosowaniem jest uzyskanie mniejszej liczby wyników fałszywie dodatnich i zwiększenie dokładności operacji Identyfikowanie przez ograniczenie zakresu tylko do obiektów Osoby , które mają być zgodne. Praktyczne przypadki użycia obejmują katalogi do określonego dostępu do budynku między większym kampusem lub organizacją. Katalog organizacji może zawierać 5 milionów osób, ale wystarczy przeszukać tylko 800 osób dla określonego budynku, aby utworzyć grupę DynamicPersonGroup zawierającą te konkretne osoby.

Jeśli wcześniej użyto grupy PersonGroup , zanotuj dwie główne różnice:

Każda osoba wewnątrz grupy DynamicPersonGroup jest odwołaniem do rzeczywistej osoby w personDirectory, co oznacza, że nie jest konieczne ponowne utworzenie osoby w każdej grupie.
Jak wspomniano w poprzednich sekcjach, nie ma potrzeby wykonywania wywołań trenowania, ponieważ dane twarzy są przetwarzane automatycznie na poziomie katalogów.

Tworzenie grupy

Aby utworzyć grupę DynamicPersonGroup, musisz podać identyfikator grupy z znakami alfanumerycznymi lub kreskowymi. Ten identyfikator będzie działać jako unikatowy identyfikator dla wszystkich celów użycia grupy.

Istnieją dwa sposoby inicjowania kolekcji grup. Możesz początkowo utworzyć pustą grupę i wypełnić ją później:

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

Ten proces jest natychmiastowy i nie trzeba czekać na pomyślne wykonanie żadnych operacji asynchronicznych.

Alternatywnie można utworzyć go za pomocą zestawu identyfikatorów osób , które mają zawierać te odwołania od początku, podając zestaw w argumencie 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");
}

Uwaga

Po powrocie wywołania utworzona grupa DynamicPersonGroup będzie gotowa do użycia w wywołaniu Identyfikowanie z dowolnymi odwołaniami osoby podanymi w procesie. Z drugiej strony stan ukończenia zwróconej operacji wskazuje stan aktualizacji relacji osoba-grupa.

Aktualizowanie grupy DynamicPersonGroup

Po początkowym utworzeniu można dodawać i usuwać odwołania osoby z grupy DynamicPersonGroup przy użyciu interfejsu API aktualizując grupę osób dynamicznych. Aby dodać obiekty Person do grupy, wyświetl listę identyfikatorów osób w argumencie addPersonsIds . Aby usunąć obiekty Person , wyświetl je w argumencie removePersonIds . Zarówno dodawanie, jak i usuwanie można wykonać w jednym wywołaniu:

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

Po powrocie wywołania aktualizacje kolekcji zostaną odzwierciedlone po wysłaniu zapytania do grupy. Podobnie jak w przypadku interfejsu API tworzenia, zwrócona operacja wskazuje stan aktualizacji relacji osoba-grupa dla każdej osoby zaangażowanej w aktualizację. Nie musisz czekać na ukończenie operacji przed wykonaniem dalszych wywołań aktualizacji do grupy.

Identyfikowanie twarzy w personDirectory

Najczęstszym sposobem używania danych twarzy w personDirectory jest porównanie zarejestrowanych obiektów osoby z daną twarzą i zidentyfikowanie najbardziej prawdopodobnego kandydata, do którego należy. W żądaniu można podać wiele twarzy, a każdy z nich otrzyma własny zestaw wyników porównania w odpowiedzi.

W usłudze PersonDirectory istnieją trzy typy zakresów, względem których można zidentyfikować każdą twarz:

Scenariusz 1. Identyfikowanie elementu DynamicPersonGroup

Określenie właściwości dynamicPersonGroupId w żądaniu porównuje twarz z każdą osobą, do której odwołuje się dana osoba w grupie. W wywołaniu można zidentyfikować tylko jedną grupę DynamicPersonGroup .

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

Scenariusz 2. Identyfikowanie określonej listy osób

Możesz również określić listę identyfikatorów osób we właściwości personIds , aby porównać twarz z każdym z nich.

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

Scenariusz 3. Identyfikowanie całego elementu PersonDirectory

Podanie pojedynczej gwiazdki we właściwości personIds w żądaniu porównuje twarz z każdą osobą zarejestrowaną w 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);
}

W przypadku wszystkich trzech scenariuszy identyfikacja porównuje tylko przychodzącą twarz z twarzami, których wywołanie AddPersonFace zwróciło odpowiedź "powodzenie".

Weryfikowanie twarzy względem osób w usłudze PersonDirectory

Za pomocą identyfikatora twarzy zwróconego z wywołania wykrywania można sprawdzić, czy twarz należy do określonej osoby zarejestrowanej w usłudze PersonDirectory. Określ osobę przy użyciu właściwości 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}");
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);
}

Odpowiedź będzie zawierać wartość logiczną wskazującą, czy usługa uznaje nową twarz za należącą do tej samej osoby, oraz wskaźnik ufności przewidywania.

Następne kroki

W tym przewodniku przedstawiono sposób używania struktury PersonDirectory do przechowywania danych twarzy i osób dla aplikacji rozpoznawania twarzy. Następnie poznaj najlepsze rozwiązania dotyczące dodawania danych twarzy użytkowników.

Najlepsze rozwiązania dotyczące dodawania użytkowników

Udostępnij za pośrednictwem

Korzystanie ze struktury danych PersonDirectory (wersja zapoznawcza)

Zalety obiektu PersonDirectory

Wymagania wstępne

Dodawanie osób do personDirectory

Tworzenie osoby

Oczekiwanie na zakończenie operacji asynchronicznej

Dodawanie twarzy do osób

Tworzenie i aktualizowanie grupy DynamicPersonGroup

Tworzenie grupy

Aktualizowanie grupy DynamicPersonGroup

Identyfikowanie twarzy w personDirectory

Scenariusz 1. Identyfikowanie elementu DynamicPersonGroup

Scenariusz 2. Identyfikowanie określonej listy osób

Scenariusz 3. Identyfikowanie całego elementu PersonDirectory

Weryfikowanie twarzy względem osób w usłudze PersonDirectory

Następne kroki

Opinia

Dodatkowe zasoby