De gegevensstructuur PersonDirectory gebruiken (preview)

Artikel
03/05/2024

Let op

Toegang tot face-services is beperkt op basis van geschiktheids- en gebruikscriteria om onze verantwoorde AI-principes te ondersteunen. Face-service is alleen beschikbaar voor door Microsoft beheerde klanten en partners. Gebruik het intakeformulier voor gezichtsherkenning om toegang aan te vragen. Zie de pagina beperkte toegang van Face voor meer informatie.

Om gezichtsherkenningsbewerkingen uit te voeren, zoals Identificeren en Zoeken, moeten klanten van de Face-API een gesorteerde lijst met Person-objecten maken. PersonDirectory is een gegevensstructuur in openbare preview met unieke id's, optionele naamtekenreeksen en optionele tekenreeksen voor gebruikersmetagegevens voor elke persoonsidentiteit die is toegevoegd aan de map. Volg deze handleiding voor meer informatie over het uitvoeren van basistaken met PersonDirectory.

Voordelen van PersonDirectory

Momenteel biedt de Face-API de LargePersonGroup-structuur , die vergelijkbare functionaliteit heeft, maar beperkt is tot 1 miljoen identiteiten. De PersonDirectory-structuur kan maximaal 75 miljoen identiteiten schalen.

Een ander belangrijk verschil tussen PersonDirectory en eerdere gegevensstructuren is dat u geen Train-API-aanroepen meer hoeft uit te voeren nadat u gezichten hebt toegevoegd aan een Person-object . Het updateproces gebeurt automatisch.

Vereisten

Azure-abonnement: Maak een gratis abonnement aan.
Zodra u uw Azure-abonnement hebt, maakt u een Face-resource in Azure Portal om uw sleutel en eindpunt op te halen. Nadat de app is geïmplementeerd, selecteert u Ga naar resource.
- U hebt de sleutel en het eindpunt nodig van de resource die u maakt om de toepassing te verbinden met de Face-API. U plakt uw sleutel en eindpunt in de onderstaande code.
- U kunt de gratis prijscategorie (F0) gebruiken om de service uit te proberen en later upgraden naar een betaalde laag voor productie.

Personen toevoegen aan de persondirectory

Personen zijn de basisinschrijvingseenheden in PersonDirectory. Zodra u een persoon aan de directory hebt toegevoegd, kunt u per herkenningsmodel maximaal 248 gezichtsafbeeldingen toevoegen aan die persoon. Vervolgens kunt u gezichten identificeren met behulp van verschillende bereiken.

De persoon maken

Als u een persoon wilt maken, moet u de CreatePerson-API aanroepen en een naam of userData-eigenschapswaarde opgeven.

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

De aanroep CreatePerson retourneert een gegenereerde id voor de persoon en een bewerkingslocatie. De gegevens van de persoon worden asynchroon verwerkt, dus u gebruikt de locatie van de bewerking om de resultaten op te halen.

Wachten op voltooiing van asynchrone bewerking

U moet een query uitvoeren op de asynchrone bewerkingsstatus met behulp van de tekenreeks voor de geretourneerde bewerkingslocatie om de voortgang te controleren.

Eerst moet u een gegevensmodel definiëren zoals hieronder om het statusantwoord af te handelen.

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

Met behulp van de HttpResponseMessage van hierboven kunt u vervolgens de URL peilen en wachten op resultaten.

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

Zodra de status is geretourneerd als 'geslaagd', wordt het object Person als toegevoegd aan de map beschouwd.

Notitie

De asynchrone bewerking van de aanroep Persoon maken hoeft niet de status Geslaagd weer te geven voordat gezichten eraan kunnen worden toegevoegd, maar deze moet wel worden voltooid voordat de Persoon kan worden toegevoegd aan een DynamicPersonGroup (zie hieronder Een DynamicPersonGroup maken en bijwerken) of vergeleken tijdens een identificatiegesprek. Controleer of oproepen direct werken nadat gezichten aan de persoon zijn toegevoegd.

Gezichten toevoegen aan Personen

Zodra u de persoons-id van de aanroep Persoon maken hebt, kunt u maximaal 248 gezichtsafbeeldingen toevoegen aan een persoon per herkenningsmodel. Geef het herkenningsmodel (en optioneel het detectiemodel) op dat in de aanroep moet worden gebruikt, omdat gegevens onder elk herkenningsmodel afzonderlijk in de PersonDirectory worden verwerkt.

De momenteel ondersteunde herkenningsmodellen zijn:

Recognition_02
Recognition_03
Recognition_04

Als de afbeelding meerdere gezichten bevat, moet u bovendien het begrenzingsvak voor de rechthoek opgeven voor het gezicht dat het beoogde doel is. Met de volgende code worden gezichten toegevoegd aan een Person-object .

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

Na de aanroep Gezichten toevoegen worden de gezichtsgegevens asynchroon verwerkt en moet u wachten op het slagen van de bewerking op dezelfde manier als voorheen.

Wanneer de bewerking voor het toevoegen van gezichten is voltooid, zijn de gegevens gereed voor in Identify-aanroepen.

Een DynamicPersonGroup maken en bijwerken

DynamicPersonGroups zijn verzamelingen verwijzingen naar Person-objecten in een PersonDirectory. Ze worden gebruikt om subsets van de map te maken. Een veelvoorkomend gebruik is wanneer u minder fout-positieven wilt krijgen en de nauwkeurigheid in een identificatiebewerking wilt verhogen door het bereik te beperken tot alleen de persoonsobjecten die u verwacht te vinden. Praktische gebruiksvoorbeelden zijn mappen voor specifieke bouwtoegang tussen een grotere campus of organisatie. De organisatiedirectory kan 5 miljoen personen bevatten, maar u hoeft slechts een specifieke 800 personen te doorzoeken voor een bepaald gebouw, dus u maakt een DynamicPersonGroup die deze specifieke personen bevat.

Als u eerder een PersonGroup hebt gebruikt, moet u rekening houden met twee belangrijke verschillen:

Elke persoon in een DynamicPersonGroup is een verwijzing naar de werkelijke persoon in de persondirectory, wat betekent dat het niet nodig is om een persoon in elke groep opnieuw te maken.
Zoals vermeld in de vorige secties, hoeft u geen Train-aanroepen te doen, omdat de gezichtsgegevens automatisch op adreslijstniveau worden verwerkt.

De groep maken

Als u een DynamicPersonGroup wilt maken, moet u een groeps-id opgeven met alfanumerieke tekens of streepjes. Deze id werkt als de unieke id voor alle gebruiksdoeleinden van de groep.

Er zijn twee manieren om een groepverzameling te initialiseren. U kunt in eerste instantie een lege groep maken en deze later vullen:

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

Dit proces is onmiddellijk en u hoeft niet te wachten totdat asynchrone bewerkingen zijn geslaagd.

U kunt deze ook maken met een set persoons-id's om deze verwijzingen vanaf het begin te bevatten door de set op te geven in het argument 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");
}

Notitie

Zodra de aanroep wordt geretourneerd, is de gemaakte DynamicPersonGroup gereed voor gebruik in een Identificatie-oproep, met eventuele persoonsverwijzingen in het proces. De voltooiingsstatus van de geretourneerde bewerkings-id geeft daarentegen de updatestatus van de relatie tussen personen aan.

DynamicPersonGroup bijwerken

Na het maken kunt u persoonsverwijzingen toevoegen aan en verwijderen uit de DynamicPersonGroup met de API Voor dynamische personengroep bijwerken. Als u persoonsobjecten aan de groep wilt toevoegen, vermeldt u de persoons-id's in het argument addPersonsIds. Als u persoonsobjecten wilt verwijderen, vermeldt u deze in het argument removePersonIds. Zowel het toevoegen als verwijderen kan in één aanroep worden uitgevoerd:

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

Zodra de aanroep wordt geretourneerd, worden de updates voor de verzameling weergegeven wanneer de groep wordt opgevraagd. Net als bij de aanmaak-API geeft de geretourneerde bewerking de updatestatus aan van de persoon-naar-groep-relatie voor elke persoon die betrokken is bij de update. U hoeft niet te wachten totdat de bewerking is voltooid voordat u verdere update-aanroepen naar de groep doet.

Gezichten in een PersonDirectory identificeren

De meest voorkomende manier om gezichtsgegevens in een PersonDirectory te gebruiken, is door de geregistreerde Persoonsobjecten te vergelijken met een bepaald gezicht en de meest waarschijnlijke kandidaat te identificeren waartoe deze behoort. Er kunnen meerdere gezichten worden opgegeven in de aanvraag en elk krijgt een eigen set vergelijkingsresultaten in het antwoord.

In PersonDirectory zijn er drie typen bereiken waar elk gezicht mee kan worden geïdentificeerd:

Scenario 1: Identificeren op basis van een DynamicPersonGroup

Als u de eigenschap dynamicPersonGroupId in de aanvraag opgeeft, wordt het gezicht vergeleken met elke persoon waarnaar in de groep wordt verwezen. Slechts één DynamicPersonGroup kan worden geïdentificeerd in een gesprek.

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

Scenario 2: Identificeren op basis van een specifieke lijst met personen

U kunt ook een lijst met persoons-id's opgeven in de eigenschap personIds om het gezicht te vergelijken met elk van deze id's.

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

Scenario 3: Identificeren op basis van de hele PersonDirectory

Als u één sterretje opgeeft in de eigenschap personIds in de aanvraag, wordt het gezicht vergeleken met elke persoon die is ingeschreven in de 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);
}

Voor alle drie de scenario's vergelijkt de identificatie alleen het binnenkomende gezicht met gezichten waarvan de addPersonFace-aanroep is geretourneerd met een 'geslaagd' antwoord.

Gezichten controleren op personen in de PersonDirectory

Wanneer een gezichts-id wordt geretourneerd vanuit een detectiegesprek, kunt u controleren of het gezicht deel uitmaakt van een specifieke persoon die is ingeschreven in de PersonDirectory. Geef de persoon op met behulp van de eigenschap 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);
}

Het antwoord bevat een Booleaanse waarde die aangeeft of de service het nieuwe gezicht van dezelfde persoon beschouwt en een betrouwbaarheidsscore voor de voorspelling.

Volgende stappen

In deze handleiding hebt u geleerd hoe u de Structuur PersonDirectory gebruikt om gezichts- en persoonsgegevens voor uw Face-app op te slaan. Leer vervolgens de aanbevolen procedures voor het toevoegen van gezichtsgegevens van uw gebruikers.

Aanbevolen procedures voor het toevoegen van gebruikers

Delen via