Använda PersonDirectory-datastrukturen (förhandsversion)

Artikel
03/06/2024

Varning

Åtkomsten till ansiktstjänsten är begränsad baserat på berättigande- och användningskriterier för att stödja våra principer för ansvarsfull AI. Ansiktstjänsten är endast tillgänglig för Microsofts hanterade kunder och partner. Använd formuläret ansiktsigenkänning för att ansöka om åtkomst. Mer information finns på sidan ansiktsbegränsade åtkomst .

För att kunna utföra ansiktsigenkänningsåtgärder som Identifiera och Hitta liknande måste kunder med Ansikts-API skapa en blandad lista över personobjekt . PersonDirectory är en datastruktur i offentlig förhandsversion som innehåller unika ID:er, valfria namnsträngar och valfria användarmetadatasträngar för varje personidentitet som läggs till i katalogen. Följ den här guiden om du vill lära dig hur du utför grundläggande uppgifter med PersonDirectory.

Fördelar med PersonDirectory

För närvarande erbjuder Ansikts-API:et LargePersonGroup-strukturen , som har liknande funktioner men är begränsad till 1 miljon identiteter. PersonDirectory-strukturen kan skala upp till 75 miljoner identiteter.

En annan stor skillnad mellan PersonDirectory och tidigare datastrukturer är att du inte längre behöver göra några Train API-anrop efter att ha lagt till ansikten i ett personobjekt – uppdateringsprocessen sker automatiskt.

Förutsättningar

Azure-prenumeration – Skapa en kostnadsfritt.
När du har din Azure-prenumeration skapar du en ansiktsresurs i Azure-portalen för att hämta din nyckel och slutpunkt. När den har distribuerats väljer du Gå till resurs.
- Du behöver nyckeln och slutpunkten från den resurs som du skapar för att ansluta ditt program till ansikts-API:et. Du klistrar in nyckeln och slutpunkten i koden nedan.
- Du kan använda den kostnadsfria prisnivån (F0) för att prova tjänsten och uppgradera senare till en betald nivå för produktion.

Lägg till personer i PersonDirectory

Personer är basregistreringsenheterna i PersonDirectory. När du lägger till en person i katalogen kan du lägga till upp till 248 ansiktsbilder till den personen, per igenkänningsmodell. Sedan kan du identifiera ansikten mot dem med olika omfång.

Skapa personen

Om du vill skapa en person måste du anropa CreatePerson-API:et och ange ett namn eller ett userData-egenskapsvärde.

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-anropet returnerar ett genererat ID för personen och en åtgärdsplats. Persondata bearbetas asynkront, så du använder åtgärdsplatsen för att hämta resultatet.

Vänta tills asynkron åtgärd har slutförts

Du måste fråga asynkron åtgärdsstatus med hjälp av den returnerade åtgärdsplatssträngen för att kontrollera förloppet.

Först bör du definiera en datamodell som följande för att hantera statussvaret.

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

Med hjälp av HttpResponseMessage ovan kan du sedan avsöka URL:en och vänta på resultat.

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

När statusen returneras som "lyckades" anses personobjektet ha lagts till i katalogen.

Kommentar

Den asynkrona åtgärden från anropet Skapa person behöver inte visa statusen "lyckades" innan ansikten kan läggas till i den, men den måste slutföras innan personen kan läggas till i en DynamicPersonGroup (se nedan Skapa och uppdatera en DynamicPersonGroup) eller jämföras under ett Identifiera-anrop. Kontrollera att anrop fungerar omedelbart när ansikten har lagts till i personen.

Lägga till ansikten i personer

När du har person-ID:t från anropet Skapa person kan du lägga till upp till 248 ansiktsbilder till en person per igenkänningsmodell. Ange den igenkänningsmodell (och eventuellt identifieringsmodellen) som ska användas i anropet, eftersom data under varje igenkänningsmodell bearbetas separat i PersonDirectory.

De igenkänningsmodeller som stöds för närvarande är:

Recognition_02
Recognition_03
Recognition_04

Om bilden dessutom innehåller flera ansikten måste du ange rektangelns avgränsningsruta för ansiktet som är det avsedda målet. Följande kod lägger till ansikten i ett personobjekt .

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

Efter anropet Lägg till ansikten bearbetas ansiktsdata asynkront och du måste vänta tills åtgärden har slutförts på samma sätt som tidigare.

När åtgärden för ansiktstillägget är klar är data redo för i Identifiera anrop.

Skapa och uppdatera en DynamicPersonGroup

DynamicPersonGroups är samlingar med referenser till Person-objekt i en PersonDirectory. De används för att skapa delmängder av katalogen. En vanlig användning är när du vill få färre falska positiva identifieringar och ökad noggrannhet i en Identifiera-åtgärd genom att begränsa omfånget till bara de personobjekt som du förväntar dig att matcha. Praktiska användningsfall omfattar kataloger för specifik byggnadsåtkomst mellan ett större campus eller en större organisation. Organisationskatalogen kan innehålla 5 miljoner personer, men du behöver bara söka efter en viss byggnad på 800 personer, så du skapar en DynamicPersonGroup som innehåller dessa specifika personer.

Om du har använt en PersonGroup tidigare bör du notera två större skillnader:

Varje person i en DynamicPersonGroup är en referens till den faktiska personen i PersonDirectory, vilket innebär att det inte är nödvändigt att återskapa en person i varje grupp.
Som nämnts i föregående avsnitt behöver du inte göra Train-anrop eftersom ansiktsdata bearbetas automatiskt på katalognivå.

Skapa gruppen

Om du vill skapa en DynamicPersonGroup måste du ange ett grupp-ID med alfanumeriska tecken eller bindestreck. Det här ID:t fungerar som unik identifierare för alla användningsändamål i gruppen.

Det finns två sätt att initiera en gruppsamling. Du kan skapa en tom grupp från början och fylla i den senare:

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

Den här processen är omedelbar och du behöver inte vänta på att asynkrona åtgärder ska lyckas.

Du kan också skapa den med en uppsättning person-ID :er för att innehålla dessa referenser från början genom att ange uppsättningen i argumentet 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");
}

Kommentar

Så snart anropet returneras är den skapade DynamicPersonGroup redo att användas i ett Identifiera-anrop, med alla personreferenser som anges i processen. Slutförandestatusen för det returnerade åtgärds-ID:t anger å andra sidan uppdateringsstatusen för relationen person-till-grupp.

Uppdatera DynamicPersonGroup

När du har skapat den första versionen kan du lägga till och ta bort personreferenser från DynamicPersonGroup med API:et Uppdatera dynamisk persongrupp. Om du vill lägga till personobjekt i gruppen listar du person-ID :na i argumentet addPersonsIds . Om du vill ta bort personobjekt listar du dem i argumentet removePersonIds . Du kan både lägga till och ta bort i ett enda anrop:

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

När anropet returneras återspeglas uppdateringarna av samlingen när gruppen efterfrågas. Precis som med API:et för skapande anger den returnerade åtgärden uppdateringsstatusen för en person-till-grupp-relation för alla personer som är inblandade i uppdateringen. Du behöver inte vänta tills åtgärden har slutförts innan du gör ytterligare uppdateringsanrop till gruppen.

Identifiera ansikten i en PersonDirectory

Det vanligaste sättet att använda ansiktsdata i en PersonDirectory är att jämföra registrerade personobjekt mot ett visst ansikte och identifiera den mest sannolika kandidaten som det tillhör. Flera ansikten kan anges i begäran och var och en får sin egen uppsättning jämförelseresultat i svaret.

I PersonDirectory finns det tre typer av omfång som varje ansikte kan identifieras mot:

Scenario 1: Identifiera mot en DynamicPersonGroup

Om du anger egenskapen dynamicPersonGroupId i begäran jämförs ansiktet mot varje person som refereras i gruppen. Endast en enda DynamicPersonGroup kan identifieras mot i ett anrop.

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: Identifiera mot en specifik lista över personer

Du kan också ange en lista över person-ID :n i egenskapen personIds för att jämföra ansiktet mot var och en av dem.

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: Identifiera mot hela PersonDirectory

Om du anger en enda asterisk i egenskapen personIds i begäran jämförs ansiktet mot varje enskild person som registrerats i 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);
}

För alla tre scenarier jämför identifieringen endast det inkommande ansiktet mot ansikten vars AddPersonFace-anrop har returnerats med ett "lyckades"-svar.

Verifiera ansikten mot personer i PersonDirectory

Med ett ansikts-ID som returneras från ett identifieringsanrop kan du kontrollera om ansiktet tillhör en specifik person som registrerats i PersonDirectory. Ange person med egenskapen 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);
}

Svaret innehåller ett booleskt värde som anger om tjänsten anser att det nya ansiktet tillhör samma person och en konfidenspoäng för förutsägelsen.

Nästa steg

I den här guiden har du lärt dig hur du använder PersonDirectory-strukturen för att lagra ansikts- och persondata för din ansiktsapp. Lär dig sedan metodtipsen för att lägga till användarnas ansiktsdata.

Metodtips för att lägga till användare

Dela via