Verwenden der PersonDirectory-Datenstruktur (Vorschau)

Artikel
09/03/2024

Achtung

Der Zugriff auf den Gesichtserkennungsdienst ist auf der Grundlage von Berechtigungs- und Nutzungskriterien begrenzt, um unsere Prinzipien für verantwortungsvolle KI zu unterstützen. Der Gesichtserkennungsdienst ist nur für von Microsoft verwaltete Kunden und Partner verfügbar. Verwenden Sie das Aufnahmeformular für die Gesichtserkennung, um sich für den Zugriff zu bewerben. Weitere Informationen finden Sie auf der Seite Eingeschränkter Zugriff auf die Gesichtserkennung.

Um Gesichtserkennungsvorgänge wie „Identifizieren“ und „Ähnliches suchen“ durchzuführen, müssen Kunden der Gesichtserkennungs-API eine gemischte Liste von Personenobjekten erstellen. PersonDirectory ist eine Datenstruktur in Public Preview, die eindeutige IDs, optionale Namenszeichenfolgen und optionale Benutzermetadaten-Zeichenfolgen für jede Person-Identität enthält, die dem Verzeichnis hinzugefügt wird. Folgen Sie diesem Leitfaden, um zu erfahren, wie grundlegende Aufgaben mit PersonDirectory ausgeführt werden.

Vorteile von PersonDirectory

Derzeit bietet die Gesichtserkennungs-API die LargePersonGroup-Struktur, die über ähnliche Funktionen verfügt, aber auf 1 Mio. Identitäten beschränkt ist. Die PersonDirectory-Struktur kann auf bis zu 75 Milo. Identitäten hochskaliert werden.

Ein weiterer wichtiger Unterschied zwischen PersonDirectory und vorherigen Datenstrukturen besteht darin, dass Sie nach dem Hinzufügen von Gesichtern zu einem Person-Objekt keine Train-API-Aufrufe mehr tätigen müssen – der Aktualisierungsprozess erfolgt automatisch.

Voraussetzungen

Azure-Abonnement – Erstellen eines kostenlosen Kontos
Sobald Sie über Ihr Azure-Abonnement verfügen, sollten Sie im Azure-Portal eine Gesichtserkennungsressource erstellen, um Ihren Schlüssel und Endpunkt zu erhalten. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
- Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der Gesichtserkennungs-API zu verbinden. Der Schlüssel und der Endpunkt werden weiter unten in den Code eingefügt.
- Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Hinzufügen von Personen zum PersonDirectory

Personen sind die Basisregistrierungseinheiten im PersonDirectory. Nachdem Sie dem Verzeichnis eine Person hinzugefügt haben, können Sie dieser Person bis zu 248 Gesichtsbilder pro Erkennungsmodell hinzufügen. Anschließend können Sie anhand dieser Bilder Gesichter mithilfe unterschiedlicher Bereiche identifizieren.

Erstellen der Person

Um eine Person zu erstellen, müssen Sie die CreatePerson-API aufrufen und einen Namen oder einen userData-Eigenschaftswert angeben.

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

Der CreatePerson-Aufruf gibt eine generierte ID für die Person einen Vorgangsort zurück. Die Personendaten werden asynchron verarbeitet, weshalb Sie den Vorgangsort verwenden, um die Ergebnisse abzurufen.

Warten auf den Abschluss des asynchronen Vorgangs

Sie müssen den Status des asynchronen Vorgangs mithilfe der zurückgegebenen Vorgangsortzeichenfolge abfragen, um den Fortschritt zu überprüfen.

Zunächst sollten Sie ein Datenmodell wie das folgende definieren, um die Statusantwort zu verarbeiten.

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

Mithilfe der oben genannten HttpResponseMessage können Sie dann die URL abrufen und auf Ergebnisse warten.

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

Sobald der Status als „erfolgreich“ zurückgegeben wird, gilt das Personenobjekt als dem Verzeichnis hinzugefügt.

Hinweis

Der asynchrone Vorgang aus dem Aufruf „Person erstellen“ muss keinen Status „erfolgreich“ anzeigen, damit Gesichter hinzugefügt werden können. Er muss jedoch abgeschlossen sein, bevor die Person einer DynamicPersonGroup hinzugefügt (siehe unten „Erstellen und Aktualisieren einer DynamicPersonGroup“) oder während eines Identify-Aufrufs verglichen werden kann. Vergewissern Sie sich, dass Aufrufe sofort funktionieren, nachdem Gesichter der Person erfolgreich hinzugefügt wurden.

Hinzufügen von Gesichtern zu Personen

Sobald Sie über die Personen-ID aus dem Aufruf „Person erstellen“ verfügen, können Sie pro Erkennungsmodell bis zu 248 Gesichtsbilder zu einer Person hinzufügen. Geben Sie das Erkennungsmodell („recognition“, und optional das Erkennungsmodell („detection“)) an, das im Aufruf verwendet werden soll, da die Daten unter jedem Erkennungsmodell separat innerhalb des PersonDirectory verarbeitet werden.

Die derzeit unterstützten Erkennungsmodelle sind:

Recognition_02
Recognition_03
Recognition_04

Wenn das Bild mehrere Gesichter enthält, müssen Sie außerdem den rechteckigen Begrenzungsrahmen für das Gesicht angeben, das das beabsichtigte Ziel ist. Der folgende Code fügt einem Personenobjekt Gesichter hinzu.

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

Nach dem Aufruf von „Gesichter hinzufügen“ werden die Gesichtsdaten asynchron verarbeitet, und Sie müssen auf dieselbe Weise wie zuvor auf den Erfolg des Vorgangs warten.

Wenn der Vorgang für die Gesichtshinzufügung abgeschlossen ist, sind die Daten für Identify-Aufrufe bereit.

Erstellen und Aktualisieren einer DynamicPersonGroup

DynamicPersonGroups sind Sammlungen von Verweisen auf Personenobjekte in einem PersonDirectory. Sie werden verwendet, um Teilmengen des Verzeichnisses zu erstellen. Eine häufige Verwendung besteht darin, wenn Sie weniger falsch positive Ergebnisse und eine höhere Genauigkeit in einem Identify-Vorgang erhalten möchten, den Bereich auf die Personenobjekte zu beschränken, bei denen Sie eine Übereinstimmung erwarten. Zu den praktischen Anwendungsfällen gehören Verzeichnisse für den spezifischen Gebäudezugang auf einem größeren Campus oder bei einer größeren Organisation. Das Organisationsverzeichnis kann 5 Mio. Personen enthalten, aber Sie müssen nur eine bestimmte Gruppe von 800 Personen nach einem bestimmten Gebäude durchsuchen, sodass Sie eine DynamicPersonGroup erstellen würden, die diese spezifischen Personen enthält.

Wenn Sie schon einmal eine PersonGroup verwendet haben, beachten Sie zwei wesentliche Unterschiede:

Jede Person innerhalb einer DynamicPersonGroup ist ein Verweis auf die tatsächliche Person im PersonDirectory, was bedeutet, dass es nicht erforderlich ist, eine Person in jeder Gruppe neu zu erstellen.
Wie in den vorherigen Abschnitten erwähnt, ist es nicht notwendig, Train-Aufrufe zu tätigen, da die Gesichtsdaten automatisch auf Verzeichnisebene verarbeitet werden.

Erstellen der Gruppe

Um eine DynamicPersonGroup zu erstellen, müssen Sie eine Gruppen-ID mit alphanumerischen Zeichen oder Bindestrichen bereitstellen. Diese ID dient als eindeutiger Bezeichner für alle Verwendungszwecke der Gruppe.

Es gibt zwei Möglichkeiten, um eine Gruppensammlung zu initialisieren. Sie können zunächst eine leere Gruppe erstellen und diese dann später auffüllen:

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

Dieser Prozess ist unmittelbar, und es ist nicht notwendig, auf den Erfolg asynchroner Vorgänge zu warten.

Alternativ können Sie sie mit einem Satz von Personen-IDs erstellen, um diese Verweise von Anfang an aufzunehmen, indem Sie den Satz im Argument AddPersonIds angeben:

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

Hinweis

Sobald der Aufruf zurückgegeben wird, kann die erstellte DynamicPersonGroup in einem Identify-Aufruf verwendet werden, wobei in dem Prozess alle Personenverweise bereitgestellt werden. Der Abschlussstatus der zurückgegebenen Vorgangs-ID zeigt hingegen den Aktualisierungsstatus der Beziehung zwischen Person und Gruppe an.

Aktualisieren der DynamicPersonGroup

Nach der anfänglichen Erstellung können Sie der DynamicPersonGroup mit der API zum Aktualisieren dynamischer Personengruppen Personenverweise hinzufügen und daraus entfernen. Um der Gruppe Personenobjekte hinzuzufügen, listen Sie die Personen-IDs im Argument addPersonsIds auf. Um Personenobjekte zu entfernen, listen Sie sie im Argument removePersonIds auf. Das Hinzufügen wie das Entfernen kann in einem einzigen Aufruf erfolgen:

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

Sobald der Aufruf zurückgegeben wurde, werden die Aktualisierungen an der Sammlung widergespiegelt, wenn die Gruppe abgefragt wird. Wie bei der Erstellungs-API zeigt der zurückgegebene Vorgang den Aktualisierungsstatus der Beziehung zwischen Person und Gruppe für jede Person an, die an der Aktualisierung beteiligt ist. Sie müssen nicht auf den Abschluss des Vorgangs warten, bevor Sie weitere Update-Aufrufe an die Gruppe senden.

Identifizieren von Gesichtern in einem PersonDirectory

Die gängigste Methode zum Verwenden von Gesichtsdaten in einem PersonDirectory besteht darin, die registrierten Personenobjekte mit einem bestimmten Gesicht zu vergleichen und den wahrscheinlichsten Kandidaten zu identifizieren, zu dem es gehört. In der Anforderung können mehrere Gesichter bereitgestellt werden, wovon jedes in der Antwort einen eigenen Satz von Vergleichsergebnissen erhält.

Im PersonDirectory gibt es drei Arten von Bereichen, anhand derer jedes Gesicht identifiziert werden kann:

Szenario 1: Identifizieren anhand einer DynamicPersonGroup

Wenn Sie die dynamicPersonGroupId-Eigenschaft in der Anforderung angeben, wird das Gesicht mit jeder Person verglichen, auf die in der Gruppe verwiesen wird. In einem Aufruf kann nur eine einzige DynamicPersonGroup angegeben werden.

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

Szenario 2: Identifizieren anhand einer spezifischen Liste von Personen

Sie können auch eine Liste mit Personen-IDs in der personIds-Eigenschaft angeben, um das Gesicht jeder davon zu vergleichen.

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

Szenario 3: Identifizieren anhand des gesamten PersonDirectory

Wenn Sie in der Anforderung ein einzelnes Sternchen in der personIds-Eigenschaft angeben, wird das Gesicht mit jeder einzelnen Person verglichen, die im PersonDirectory registriert ist.

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

In allen drei Szenarien vergleicht die Identifikation nur das eingehende Gesicht mit Gesichtern, deren AddPersonFace-Aufruf mit einer „erfolgreich“-Antwort zurückgegeben wurde.

Überprüfen von Gesichtern anhand von Personen im PersonDirectory

Mit einer Gesichts-ID, die von einem Erkennungsaufruf zurückgegeben wird, können Sie überprüfen, ob das Gesicht zu einer bestimmten Person gehört, die im PersonDirectory registriert ist. Geben Sie die Person mithilfe der personId-Eigenschaft an.

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

Die Antwort enthält einen booleschen Wert, der angibt, ob der Dienst das neue Gesicht derselben Person zurechnet. Außerdem wird eine Zuverlässigkeitsbewertung für die Vorhersage angegeben.

Nächste Schritte

In diesem Leitfaden haben Sie erfahren, wie Sie die PersonDirectory-Struktur verwenden, um Gesichts- und Personendaten für Ihre Gesichtserkennungs-App zu speichern. Als Nächstes lernen Sie die bewährten Methoden zum Hinzufügen der Gesichtsdaten Ihrer Benutzer kennen.

Best Practices für das Hinzufügen von Benutzern

Freigeben über