Usare la struttura dei dati PersonDirectory (anteprima)

Articolo
07/20/2023

Attenzione

L'accesso al servizio Viso è limitato in base ai criteri di idoneità e utilizzo per supportare i principi di IA responsabile. Il servizio Viso è disponibile solo per i clienti e i partner gestiti da Microsoft. Usare il modulo di assunzione riconoscimento viso per richiedere l'accesso. Per altre informazioni, vedere la pagina Viso con accesso limitato .

Per eseguire operazioni di riconoscimento dei visi, ad esempio Identificare e trovare simili, i clienti dell'API Viso devono creare un elenco variegato di oggetti Person . PersonDirectory è una struttura di dati in anteprima pubblica che contiene ID univoci, stringhe di nomi facoltative e stringhe di metadati utente facoltative per ogni identità persona aggiunta alla directory. Seguire questa guida per informazioni su come eseguire attività di base con PersonDirectory.

Vantaggi di PersonDirectory

Attualmente, l'API Viso offre la struttura LargePersonGroup , che ha funzionalità simili, ma è limitata a 1 milione di identità. La struttura PersonDirectory può aumentare fino a 75 milioni di identità.

Un'altra differenza principale tra PersonDirectory e le strutture di dati precedenti consiste nel fatto che non sarà più necessario effettuare chiamate ALL'API Train dopo l'aggiunta di visi a un oggetto Person . Il processo di aggiornamento viene eseguito automaticamente.

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito.
Dopo aver creato la sottoscrizione di Azure, creare una risorsa Viso nel portale di Azure per ottenere la chiave e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
- La chiave e l'endpoint della risorsa creata saranno necessari per connettere l'applicazione all'API Viso. La chiave e l'endpoint verranno incollati nel codice seguente.
- È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

Aggiungere persone a PersonDirectory

Le persone sono le unità di registrazione di base in PersonDirectory. Dopo aver aggiunto una persona alla directory, è possibile aggiungere fino a 248 immagini del viso a tale persona, per modello di riconoscimento. È quindi possibile identificare i visi in base a essi usando ambiti diversi.

Creare la persona

Per creare una persona, è necessario chiamare l'API CreatePerson e specificare un nome o un valore della proprietà 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); 
}

La chiamata CreatePerson restituirà un ID generato per Person e un percorso dell'operazione. I dati person verranno elaborati in modo asincrono, quindi si usa la posizione dell'operazione per recuperare i risultati.

Attendere il completamento dell'operazione asincrona

Per controllare lo stato dell'operazione asincrona, è necessario eseguire una query sullo stato dell'operazione asincrona usando la stringa del percorso dell'operazione restituita.

Prima di tutto, è necessario definire un modello di dati simile al seguente per gestire la risposta di stato.

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

Usando HttpResponseMessage riportato sopra, è possibile eseguire il polling dell'URL e attendere i risultati.

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

Quando lo stato viene restituito come "riuscito", l'oggetto Person viene considerato aggiunto alla directory.

Nota

L'operazione asincrona dalla chiamata Create Person non deve mostrare lo stato "succeeded" prima che i visi possano essere aggiunti, ma è necessario completare prima che person possa essere aggiunto a DynamicPersonGroup (vedere di seguito Create and update a DynamicPersonGroup) o confrontato durante una chiamata Di identificazione. Verificare che le chiamate funzionino immediatamente dopo che i visi sono stati aggiunti correttamente alla persona.

Aggiungere visi alle persone

Dopo aver ottenuto l'ID persona dalla chiamata create person, è possibile aggiungere fino a 248 immagini del viso a un modello di riconoscimento Persona per ogni persona. Specificare il modello di riconoscimento (e facoltativamente il modello di rilevamento) da usare nella chiamata, in quanto i dati in ogni modello di riconoscimento verranno elaborati separatamente all'interno di PersonDirectory.

I modelli di riconoscimento attualmente supportati sono:

Recognition_02
Recognition_03
Recognition_04

Inoltre, se l'immagine contiene più visi, è necessario specificare il rettangolo delimitatore per il viso che rappresenta la destinazione desiderata. Il codice seguente aggiunge visi a un oggetto 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);
}

Dopo la chiamata Aggiungi visi, i dati del viso verranno elaborati in modo asincrono e sarà necessario attendere l'esito positivo dell'operazione nello stesso modo di prima.

Al termine dell'operazione per l'aggiunta del viso, i dati saranno pronti per in Identificare le chiamate.

Creare e aggiornare un DynamicPersonGroup

DynamicPersonGroups sono raccolte di riferimenti a oggetti Person all'interno di un Oggetto PersonDirectory; vengono usati per creare subset della directory. Un uso comune è quando si desidera ottenere un minor numero di falsi positivi e una maggiore accuratezza in un'operazione di identificazione limitando l'ambito solo agli oggetti Person che si prevede corrispondano. I casi d'uso pratici includono directory per l'accesso a edifici specifici tra un campus o un'organizzazione più grande. La directory dell'organizzazione può contenere 5 milioni di utenti, ma è sufficiente cercare in un edificio specifico 800 persone, in modo da creare un DynamicPersonGroup contenente tali utenti specifici.

Se in precedenza è stato usato un PersonGroup , prendere nota di due differenze principali:

Ogni persona all'interno di un DynamicPersonGroup è un riferimento alla persona effettiva in PersonDirectory, ovvero non è necessario ricreare una persona in ogni gruppo.
Come accennato nelle sezioni precedenti, non è necessario eseguire il training delle chiamate, perché i dati del viso vengono elaborati automaticamente a livello di directory.

Creare il gruppo

Per creare un DynamicPersonGroup, è necessario specificare un ID gruppo con caratteri alfanumerici o trattini. Questo ID funzionerà come identificatore univoco per tutti gli scopi di utilizzo del gruppo.

Esistono due modi per inizializzare una raccolta di gruppi. È possibile creare inizialmente un gruppo vuoto e popolarlo in un secondo momento:

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

Questo processo è immediato e non è necessario attendere che le operazioni asincrone abbiano esito positivo.

In alternativa, è possibile crearlo con un set di ID persona per contenere tali riferimenti dall'inizio specificando il set nell'argomento 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");
}

Nota

Non appena viene restituita la chiamata, il DynamicPersonGroup creato sarà pronto per l'uso in una chiamata Di identificazione, con tutti i riferimenti Person forniti nel processo. Lo stato di completamento dell'ID operazione restituito, d'altra parte, indica lo stato di aggiornamento della relazione da persona a gruppo.

Aggiornare DynamicPersonGroup

Dopo la creazione iniziale, è possibile aggiungere e rimuovere riferimenti person da DynamicPersonGroup con l'API Aggiorna gruppo di persone dinamiche. Per aggiungere oggetti Person al gruppo, elencare gli ID persona nell'argomento addPersonsIds . Per rimuovere gli oggetti Person , elencarli nell'argomento removePersonIds . Sia l'aggiunta che la rimozione possono essere eseguite in una singola chiamata:

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

Al termine della chiamata, gli aggiornamenti alla raccolta verranno riflessi quando viene eseguita una query sul gruppo. Come per l'API di creazione, l'operazione restituita indica lo stato di aggiornamento della relazione da persona a gruppo per qualsiasi persona coinvolta nell'aggiornamento. Non è necessario attendere il completamento dell'operazione prima di effettuare ulteriori chiamate di aggiornamento al gruppo.

Identificare i visi in una PersonDirectory

Il modo più comune per usare i dati dei visi in una PersonDirectory consiste nel confrontare gli oggetti Person registrati con un determinato viso e identificare il candidato più probabile a cui appartiene. Nella richiesta possono essere forniti più visi e ognuno riceverà il proprio set di risultati di confronto nella risposta.

In PersonDirectory è possibile identificare tre tipi di ambiti per ogni viso:

Scenario 1: Identificare in base a un DynamicPersonGroup

Se si specifica la proprietà dynamicPersonGroupId nella richiesta, il viso viene confrontato con ogni persona a cui viene fatto riferimento nel gruppo. In una chiamata è possibile identificare solo un singolo 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);
}

Scenario 2: Identificare in base a un elenco specifico di persone

È anche possibile specificare un elenco di ID persona nella proprietà personIds per confrontare il viso con ognuno di essi.

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: Identificare in base all'intera PersonDirectory

Se si specifica un singolo asterisco nella proprietà personIds nella richiesta, il viso viene confrontato con ogni singola persona registrata in 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);
}

Per tutti e tre gli scenari, l'identificazione confronta solo il viso in ingresso con i visi la cui chiamata AddPersonFace è stata restituita con una risposta "riuscita".

Verificare i visi contro le persone in PersonDirectory

Con un ID viso restituito da una chiamata di rilevamento, è possibile verificare se il viso appartiene a una persona specifica registrata all'interno di PersonDirectory. Specificare la persona usando la proprietà 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);
}

La risposta conterrà un valore booleano che indica se il servizio considera il nuovo viso appartenente alla stessa persona e un punteggio di attendibilità per la stima.

Passaggi successivi

In questa guida si è appreso come usare la struttura PersonDirectory per archiviare i dati dei visi e delle persone per l'app Viso. Si apprenderà quindi le procedure consigliate per aggiungere i dati dei visi degli utenti.

Procedure consigliate per l'aggiunta di utenti

Share via