A PersonDirectory adatstruktúra használata (előzetes verzió)

Cikk
02/28/2024

Figyelemfelhívás

A Face Service hozzáférése a jogosultsági és használati feltételek alapján korlátozott a felelős AI-alapelvek támogatása érdekében. A Face service csak a Microsoft által felügyelt ügyfelek és partnerek számára érhető el. A Hozzáférés igényléséhez használja a Face Recognition beviteli űrlapot . További információt a Face korlátozott hozzáférésű oldalán talál.

Az olyan arcfelismerési műveletek végrehajtásához, mint az Azonosság és a Hasonló keresése, a Face API-ügyfeleknek létre kell hozniuk a Személy objektumok válogatott listáját. A PersonDirectory egy olyan adatstruktúra a nyilvános előzetes verzióban, amely egyedi azonosítókat, választható névsztringeket és opcionális felhasználói metaadat-sztringeket tartalmaz a címtárhoz hozzáadott egyes személyidentitásokhoz . Ebből az útmutatóból megtudhatja, hogyan végezhet alapvető feladatokat a PersonDirectory használatával.

A PersonDirectory előnyei

A Face API jelenleg a LargePersonGroup struktúrát kínálja, amely hasonló funkcionalitással rendelkezik, de legfeljebb 1 millió identitással rendelkezik. A PersonDirectory struktúra akár 75 millió identitást is felskálázhat.

A PersonDirectory és a korábbi adatstruktúrák közötti másik jelentős különbség az, hogy többé nem kell betanítási API-hívásokat indítania, miután arcokat ad hozzá egy Személy objektumhoz – a frissítési folyamat automatikusan megtörténik.

Előfeltételek

Azure-előfizetés – Hozzon létre egyet ingyenesen.
Miután megkapta az Azure-előfizetését, hozzon létre egy Face-erőforrást az Azure Portalon a kulcs és a végpont lekéréséhez. Az üzembe helyezés után válassza az Ugrás az erőforrásra lehetőséget.
- Az alkalmazás Face API-hoz való csatlakoztatásához szüksége lesz a létrehozott erőforrás kulcsára és végpontjára. Illessze be a kulcsot és a végpontot az alábbi kódba.
- Az ingyenes tarifacsomag (F0) használatával kipróbálhatja a szolgáltatást, és később frissíthet egy fizetős szintre az éles környezetben.

Személyek hozzáadása a PersonDirectoryhoz

A PersonDirectory alapregisztrációs egységei a személyek. Miután felvett egy személyt a címtárba, felismerési modellenként legfeljebb 248 arcképet adhat hozzá az adott személyhez. Ezután különböző hatókörökkel azonosíthatja az arcokat.

A személy létrehozása

Személy létrehozásához meg kell hívnia a CreatePerson API-t, és meg kell adnia egy nevet vagy egy userData tulajdonságértéket.

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

A CreatePerson hívás egy generált azonosítót ad vissza a személyhez és egy műveleti helyhez. A Person-adatok aszinkron módon lesznek feldolgozva, így a műveleti hely használatával lekérheti az eredményeket.

Várakozás az aszinkron művelet befejezésére

A folyamat ellenőrzéséhez le kell kérdeznie az aszinkron művelet állapotát a visszaadott műveleti hely sztringjének használatával.

Először az állapotválasz kezeléséhez az alábbihoz hasonló adatmodellt kell meghatároznia.

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

A httpResponseMessage felülről történő használatával lekérdezheti az URL-címet, és megvárhatja az eredményeket.

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

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

Miután az állapot "sikeres" állapotú lett, a Person objektumot hozzáadja a címtárhoz.

Feljegyzés

A Személy létrehozása hívás aszinkron műveletének nem kell "sikeres" állapotot mutatnia ahhoz, hogy arcokat lehessen hozzáadni hozzá, de ahhoz, hogy a személy hozzáadható legyen a DynamicPersonGrouphoz (lásd alább a DynamicPersonGroup létrehozását és frissítését), vagy össze kell hasonlítani egy azonosítási hívás során. Győződjön meg arról, hogy a hívások azonnal működni fognak, miután az arcok sikeresen hozzáadva lettek a személyhez.

Arcok hozzáadása személyekhez

Miután megkapta a Személy létrehozása hívás személyazonosítóját, legfeljebb 248 arcképet adhat hozzá egy személyhez felismerési modellenként. Adja meg a hívásban használni kívánt felismerési modellt (és opcionálisan az észlelési modellt), mivel az egyes felismerési modellek adatai külön lesznek feldolgozva a PersonDirectoryban.

A jelenleg támogatott felismerési modellek a következők:

Recognition_02
Recognition_03
Recognition_04

Továbbá, ha a kép több arcot is tartalmaz, meg kell adnia a kívánt célként megadott arc téglalaphatároló mezőjét. Az alábbi kód arcokat ad hozzá egy Személy objektumhoz.

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

Az Arcok hozzáadása hívás után az arcadatok aszinkron módon lesznek feldolgozva, és a művelet sikerére ugyanúgy kell várnia, mint korábban.

Amikor az arcfeladási művelet befejeződik, az adatok készen állnak a hívások azonosítására.

DynamicPersonGroup létrehozása és frissítése

A DynamicPersonGroups személyobjektumokra mutató hivatkozások gyűjteményei a PersonDirectoryban; a címtár részhalmazainak létrehozására szolgálnak. Gyakori felhasználási terület, ha kevesebb hamis pozitív értéket és nagyobb pontosságot szeretne kapni egy azonosítási műveletben úgy, hogy a hatókört csak a kívánt személyobjektumokra korlátozza. A gyakorlati használati esetek magukban foglalják a nagyobb campusok vagy szervezetek adott épülethozzáféréséhez szükséges könyvtárakat. A szervezeti címtár 5 millió személyt tartalmazhat, de csak egy adott épület 800 személyében kell keresnie, ezért létre kell hoznia egy DynamicPersonGroup csoportot, amely az adott személyeket tartalmazza.

Ha korábban personGroup-t használt, jegyezze fel két fő különbséget:

A DynamicPersonGroup minden egyes személye a PersonDirectory tényleges személyére mutató hivatkozás, ami azt jelenti, hogy nem szükséges létrehozni egy személyt az egyes csoportokban.
Ahogy az előző szakaszokban is említettük, nem kell betanítási hívásokat kezdeményezni, mivel a rendszer automatikusan feldolgozza az arcadatokat a címtár szintjén.

A csoport létrehozása

DynamicPersonGroup létrehozásához meg kell adnia egy csoportazonosítót alfanumerikus vagy szaggatott karakterekkel. Ez az azonosító a csoport összes használati céljának egyedi azonosítójaként fog működni.

A csoportgyűjtemények inicializálásának két módja van. Kezdetben létrehozhat egy üres csoportot, majd később feltöltheti:

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

Ez a folyamat azonnali, és nem kell megvárni, amíg az aszinkron műveletek sikeresek lesznek.

Azt is megteheti, hogy az AddPersonIds argumentumban adja meg a halmazt egy személyazonosító-készlettel, amely az elejétől kezdve tartalmazza ezeket a hivatkozásokat:

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

Feljegyzés

Amint a hívás visszatér, a létrehozott DynamicPersonGroup készen áll az azonosítási hívásban való használatra, a folyamat során megadott személyhivatkozásokkal. A visszaadott műveletazonosító befejezési állapota viszont a személy–csoport kapcsolat frissítési állapotát jelzi.

A DynamicPersonGroup frissítése

A kezdeti létrehozás után hozzáadhat és eltávolíthat személyhivatkozásokat a DynamicPersonGroupból a Dinamikus személycsoport frissítése API-val. Ha személyobjektumokat szeretne hozzáadni a csoporthoz, sorolja fel a személyazonosítókat az addPersonsIds argumentumban. A Person objektumok eltávolításához listázhatja őket a removePersonIds argumentumban. A hozzáadás és az eltávolítás is elvégezhető egyetlen hívásban:

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

A hívás visszatérése után a gyűjtemény frissítései megjelennek a csoport lekérdezésekor. A létrehozási API-hoz hasonlóan a visszaadott művelet a személy–csoport kapcsolat frissítési állapotát jelzi a frissítésben részt vevő bármely személy esetében. Nem kell megvárnia a művelet befejezését, mielőtt további frissítési hívásokat indít a csoportnak.

Arcok azonosítása a PersonDirectoryban

A PersonDirectoryban az arcadatok használatának leggyakoribb módja, ha összehasonlítja a regisztrált személy objektumait egy adott arccal, és azonosítja a legvalószínűbb jelöltet. A kérelemben több arc is megadható, és mindegyik saját összehasonlítási eredményeket kap a válaszban.

A PersonDirectoryban az egyes arcok három típusú hatókörrel azonosíthatók:

1. forgatókönyv: Azonosítás dynamicPersonGroup-csoporttal

A dinamikusPersonGroupId tulajdonság megadása a kérelemben összehasonlítja az arcot a csoport minden hivatkozott személyével. Egy hívásban csak egyetlen DynamicPersonGroup azonosítható.

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

2. forgatókönyv: Azonosítás adott személyek listájával

A personIds tulajdonságban megadhatja a személyazonosítók listáját is, hogy összehasonlítsa az arcot mindegyikével.

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

3. forgatókönyv: Azonosítsa a teljes PersonDirectory-t

Ha egyetlen csillagot ad meg a kérelem personIds tulajdonságában, az összehasonlítja az arcot a PersonDirectoryban regisztrált minden egyes személlyel.

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

Mindhárom forgatókönyv esetében az azonosítás csak azokkal az arcokkal hasonlítja össze a bejövő arcokat, akiknek az AddPersonFace hívása "sikeres" válaszsal lett visszaadva.

Arcok ellenőrzése személyek ellen a PersonDirectoryban

Az észlelési hívásból visszaadott arcazonosítóval ellenőrizheti, hogy az arc egy adott, a PersonDirectoryban regisztrált személyhez tartozik-e. Adja meg a personId tulajdonságot használó személyt.

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

A válasz tartalmaz egy logikai értéket, amely jelzi, hogy a szolgáltatás az új arcot ugyanahhoz a személyhez tartozónak tekinti-e, és egy megbízhatósági pontszámot az előrejelzéshez.

Következő lépések

Ebben az útmutatóban megtanulta, hogyan használhatja a PersonDirectory struktúrát a Face-alkalmazás arc- és személyadatainak tárolására. A következő lépésben megismerheti a felhasználói arcadatok hozzáadásának ajánlott eljárásait.

Ajánlott eljárások felhasználók hozzáadásához

Share via