Použití datové struktury PersonDirectory (Preview)

Článek
01/30/2025

Upozornění

Přístup ke službě Rozpoznávání tváře je omezený na základě kritérií způsobilosti a použití, aby bylo možné podporovat naše zásady zodpovědné umělé inteligence. Služba Rozpoznávání tváře je dostupná jenom pro zákazníky a partnery spravované Microsoftem. Pro přístup použijte formulář pro příjem rozpoznávání tváře. Další informace najdete na stránce s omezeným přístupem k tváři.

Aby zákazníci rozhraní API pro rozpoznávání tváře mohli provádět operace rozpoznávání tváře, jako je identifikace a hledání podobných , musí vytvořit seřazený seznam objektů osob . PersonDirectory je datová struktura ve verzi Public Preview, která obsahuje jedinečná ID, volitelné řetězce názvů a volitelné řetězce metadat uživatele pro každou identitu osob přidanou do adresáře. V tomto průvodci se dozvíte, jak provádět základní úlohy pomocí PersonDirectory.

Výhody Služby PersonDirectory

Rozhraní API pro rozpoznávání tváře také nabízí strukturu LargePersonGroup , která má podobné funkce, ale je omezená na 1 milion identit. Struktura PersonDirectory může vertikálně navýšit kapacitu až 20 milionů identit.

Dalším rozdílem mezi PersonDirectory a předchozími datovými strukturami je, že po přidání tváří do objektu Person nemusíte provádět žádná volání rozhraní API pro trénování – proces aktualizace se provede automaticky.

Požadavky

Předplatné Azure – Vytvořte si ho zdarma.
Jakmile budete mít předplatné Azure, vytvořte prostředek rozpoznávání tváře na webu Azure Portal, abyste získali klíč a koncový bod. Po nasazení vyberte Přejít k prostředku.
- K připojení aplikace k rozhraní API pro rozpoznávání tváře budete potřebovat klíč a koncový bod z prostředku, který vytvoříte. Klíč a koncový bod vložíte do kódu níže.
- Službu můžete vyzkoušet pomocí cenové úrovně Free (F0) a později upgradovat na placenou úroveň pro produkční prostředí.

Přidání osob do PersonDirectory

Osoby jsou základní registrační jednotky v PersonDirectory. Jakmile do adresáře přidáte osobu, můžete do daného modelu rozpoznávání přidat až 248 obrázků tváře. Pak můžete identifikovat tváře proti nim pomocí různých oborů.

Vytvoření osoby

Pokud chcete vytvořit osobu, musíte volat rozhraní API CreatePerson a zadat hodnotu vlastnosti jméno nebo 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); 
}

Volání CreatePerson vrátí vygenerované ID osoby a umístění operace. Data osob se zpracovávají asynchronně, takže k načtení výsledků použijete umístění operace.

Čekání na dokončení asynchronní operace

Pokud chcete zkontrolovat průběh, budete muset pomocí vráceného řetězce umístění operace zadat dotaz na stav asynchronní operace.

Nejprve byste měli definovat datový model podobný následujícímu, který zpracuje odpověď na stav.

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

Pomocí výše uvedeného HttpResponseMessage příkazu můžete adresu URL dotazovat a počkat na výsledky.

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

Jakmile se stav vrátí jako "úspěch", objekt Person se považuje za přidaný do adresáře.

Poznámka:

Asynchronní operace z volání Vytvořit osobu nemusí před přidáním tváří do ní zobrazit stav "úspěch", ale musí být dokončena před tím, než se osoba může přidat do skupiny DynamicPersonGroup (viz níže Vytvoření a aktualizace skupiny DynamicPersonGroup) nebo porovnání během volání Identifikovat. Ověřte, že hovory budou fungovat hned po úspěšném přidání tváří do osoby.

Přidání tváří do osob

Jakmile budete mít ID osoby z volání Vytvořit osobu, můžete do modelu rozpoznávání přidat až 248 obrázků tváře. Zadejte model rozpoznávání (a volitelně model detekce), který se má použít ve volání, protože data v rámci každého modelu rozpoznávání budou zpracována samostatně uvnitř PersonDirectory.

Aktuálně podporované modely rozpoznávání:

Recognition_02
Recognition_03
Recognition_04

Kromě toho, pokud obrázek obsahuje více tváří, budete muset zadat obdélník ohraničující rámeček pro tvář, která je zamýšleným cílem. Následující kód přidá tváře do objektu 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 volání Přidat tváře se data tváře zpracovávají asynchronně a budete muset počkat na úspěch operace stejným způsobem jako předtím.

Po dokončení operace přidání tváře jsou data připravená k použití ve voláníCh identifikace.

Vytvoření a aktualizace skupiny DynamicPersonGroup

DynamicPersonGroups jsou kolekce odkazů na objekty Person v rámci PersonDirectory. Slouží k vytváření podmnožin adresáře. Běžné použití spočívá v tom, že chcete získat méně falešně pozitivních výsledků a zvýšit přesnost operace Identifikace omezením rozsahu jenom na objekty osoby , které očekáváte, že se shodují. Příklady praktického použití zahrnují adresáře pro konkrétní přístup k budovám ve větším areálu nebo organizaci. Adresář organizace může obsahovat 5 milionů jednotlivců, ale potřebujete vyhledat konkrétní 800 lidí pouze pro konkrétní budovu, takže byste vytvořili DynamicPersonGroup obsahující tyto konkrétní jednotlivce.

Pokud jste dříve použili skupinu PersonGroup , poznamenejte si dvě hlavní rozdíly:

Každá osoba uvnitř skupiny DynamicPersonGroup je odkazem na skutečnou osobu v PersonDirectory, což znamená, že není nutné znovu vytvořit osobu v každé skupině.
Jak už jsme zmínili v předchozích částech, není potřeba volat trénování, protože data o tvářích se zpracovávají automaticky na úrovni adresáře.

Vytvoření skupiny

Pokud chcete vytvořit DynamicPersonGroup, musíte zadat ID skupiny s alfanumerickými nebo přerušovými znaky. Toto ID funguje jako jedinečný identifikátor pro všechny účely použití skupiny.

Kolekce skupin se inicializuje dvěma způsoby. Nejprve můžete vytvořit prázdnou skupinu a naplnit ji později:

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

Tento proces je okamžitý a není nutné čekat na úspěšné asynchronní operace.

Alternativně ji můžete vytvořit se sadou ID osob , která bude obsahovat tyto odkazy od začátku zadáním sady v argumentu 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");
}

Poznámka:

Jakmile se volání vrátí, je vytvořená skupina DynamicPersonGroup připravená k použití ve volání Identify s odkazy na osoby uvedené v procesu. Stav dokončení vráceného ID operace na druhé straně označuje pouze stav aktualizace pro vyhledávací volání Get Dynamic Person Group Reference .

Aktualizace skupiny DynamicPersonGroup

Po počátečním vytvoření můžete přidat a odebrat odkazy osob z skupiny DynamicPersonGroup pomocí rozhraní API pro aktualizaci dynamické skupiny osob. Pokud chcete do skupiny přidat objekty Person , vypište ID osob v argumentu addPersonsIds . Pokud chcete odebrat objekty Person , uveďte je v argumentu removePersonIds . Přidávání i odebírání je možné provést v jednom volání:

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

Jakmile se volání vrátí, aktualizace kolekce se projeví při dotazech skupiny. Stejně jako u rozhraní API pro vytváření označuje vrácená operace stav aktualizace vztahu mezi dvěma osobami pro všechny osoby , které jsou součástí aktualizace. Před dalším voláním aktualizace skupiny nemusíte čekat na dokončení operace.

Identifikace tváří v PersonDirectory

Nejběžnějším způsobem použití dat tváře v PersonDirectory je porovnání zaregistrovaných objektů Person s danou tváří a identifikace nejpravděpodobnějšího kandidáta, ke kterým patří. V požadavku je možné zadat více tváří a každá z nich obdrží vlastní sadu výsledků porovnání v odpovědi.

Ve službě PersonDirectory existují tři typy oborů, pro které je možné identifikovat jednotlivé tváře:

Scénář 1: Identifikace v rámci skupiny DynamicPersonGroup

Zadáním vlastnosti dynamicPersonGroupId v požadavku porovnáte tvář s každou osobou , na kterou odkazuje skupina. Ve volání je možné identifikovat pouze jednu skupinu 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);
}

Scénář 2: Identifikace podle konkrétního seznamu osob

Můžete také zadat seznam ID osob ve vlastnosti personIds , abyste mohli porovnat tvář s každou 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);
}

Scénář 3: Identifikace v celém adresáři PersonDirectory

Poskytnutí jedné hvězdičky ve vlastnosti personIds v požadavku porovnává tvář s každou osobou zaregistrovanou v 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);
}

Ve všech třech scénářích porovnává identifikace pouze příchozí tvář s tvářemi, jejichž volání AddPersonFace se vrátilo s "úspěšnou" odpovědí.

Ověření tváří proti osobám v PersonDirectory

Pomocí ID tváře vrácené z volání detekce můžete ověřit, jestli tvář patří konkrétní osobě zaregistrované v PersonDirectory. Zadejte osobu pomocí vlastnosti 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);
}

Odpověď obsahuje logickou hodnotu označující, jestli služba považuje novou tvář za stejnou osobu, a skóre spolehlivosti pro predikci.

Přehled asynchronních operací

Následující tabulky shrnují, jestli je volání správy PersonDirectory dlouhotrvající operací (LRO) zpracovávané asynchronně, nebo se okamžitě a synchronně dokončí:

Správa osob/tváří	Identifikátor URI	LRO?
Získat osoby	/osoby
Vytvořit osobu	/osoby	✅
Získat osobu	/persons/{personId}
Aktualizovat osobu	/persons/{personId}
Odstranit osobu	/persons/{personId}	✅
Získání tváří osob	/persons/{personId}/recognitionModels/{model}/persistedfaces
Přidat tvář osoby	/persons/{personId}/recognitionModels/{model}/persistedfaces	✅
Přidání tváře osoby z adresy URL	/persons/{personId}/recognitionModels/{model}/persistedfaces	✅
Získání tváře osoby	/persons/{personId}/recognitionModels/{model}/persistedfaces/{persistedFaceId}
Aktualizace tváře osoby	/persons/{personId}/recognitionModels/{model}/persistedfaces/{persistedFaceId}
Odstranit tvář osoby	/persons/{personId}/recognitionModels/{model}/persistedfaces/{persistedFaceId}	✅

Správa skupin	Identifikátor URI	LRO?
Získání dynamických skupin osob	/dynamicpersongroups
Vytvoření dynamické skupiny osob	/dynamicpersongroups/{dynamicPersonGroupId}
Vytvoření dynamické skupiny osob s osobou	/dynamicpersongroups/{dynamicPersonGroupId}	✅
Získání dynamické skupiny osob	/dynamicpersongroups/{dynamicPersonGroupId}
Aktualizace dynamické skupiny osob	/dynamicpersongroups/{dynamicPersonGroupId}
Aktualizace dynamické skupiny osob se změnami osob	/dynamicpersongroups/{dynamicPersonGroupId}	✅
Odstranit dynamickou skupinu osob	/dynamicpersongroups/{dynamicPersonGroupId}	✅
Získání dynamických osob skupin osob	/dynamicpersongroups/{dynamicPersonGroupId}/persons
Získání odkazů na dynamickou skupinu osob	/persons/{personId}/dynamicPersonGroupReferences

Následující kód znázorňuje závislosti těchto asynchronních operací:

var createPersonResponse = await CreatePersonAsync();
var personId = createPersonResponse.PersonId;

// faces can be added once the person creation HTTP call returns, even if it's still processing
var addPersonFaceResponse = await AddPersonFaceAsync(personId);
var addPersonFaceFromUrlResponse = await AddPersonFaceFromUrlAsync(personId);

switch (scenario)
{
    case Scenario.Verify:
        // only need to ensure the addition of face data has propagated
        await WaitForLongRunningOperationsAsync(new[]
        {
            addPersonFaceResponse.OperationLocation,
            addPersonFaceFromUrlResponse.OperationLocation
        });
        await VerifyFromPersonDirectoryAsync(queryFaceId, personId);
        break;

    case Scenario.IdentifyInPersonDirectory:
        // ensure person creation and face data enrollment finish successfully
        await WaitForLongRunningOperationsAsync(new[]
        {
            createPersonResponse.OperationLocation,
            addPersonFaceResponse.OperationLocation,
            addPersonFaceFromUrlResponse.OperationLocation
        });
        await IdentifyFromPersonDirectoryAsync(queryFaceId);
        break;

    case Scenario.IdentifyAgainstDynamicPersonGroup:
        // person creation needs to be completed before it can be added to a group
        await WaitForLongRunningOperationsAsync(new[]
        {
            createPersonResponse.OperationLocation
        });
        var groupResponse = await CreateOrUpdateDynamicPersonGroupWithPersonChangesAsync(groupId, [personId]);
        // and make sure face data are ready before identification
        await WaitForLongRunningOperationsAsync(new[]
        {
            addPersonFaceResponse.OperationLocation,
            addPersonFaceFromUrlResponse.OperationLocation
        });
        await IdentifyFromDynamicPersonGroupAsync(queryFaceId, groupId);
        // optionally check the person-to-group relationship, which requires the completion of the group's creation or updating call
        await WaitForLongRunningOperationsAsync(new[]
        {
            groupResponse.OperationLocation
        });
        var groupIds = await GetDynamicPersonGroupReferencesAsync(personId);
        break;

    default:
        break;
}

Další kroky

V této příručce jste se dozvěděli, jak pomocí struktury PersonDirectory ukládat data tváří a osob pro vaši aplikaci Rozpoznávání tváře. Dále se seznamte s osvědčenými postupy pro přidání dat o tvářích uživatelů.

Osvědčené postupy pro přidávání uživatelů

Sdílet prostřednictvím