Avvio rapido: Usare il servizio Viso

Articolo
07/23/2024

Importante

Se si usano prodotti o servizi Microsoft per elaborare dati biometrici, l'utente è responsabile di: (i) inviare comunicazioni agli interessati, indicando anche i periodi di conservazione e i termini di distruzione; (ii) ottenere il consenso dagli interessati; infine (iii) eliminare i dati biometrici; tutto questo secondo quanto richiesto e opportuno, in conformità con i requisiti applicabili di protezione dati. Il termine "Dati biometrici" acquisisce il significato indicato nell'articolo 4 del GDPR e, se applicabile, nelle condizioni equivalenti esposte in altri requisiti di protezione dei dati. Per informazioni correlate, vedere Dati e privacy per Viso.

Attenzione

L'accesso al servizio Viso è limitato in base ai criteri di idoneità e utilizzo al fine di supportare i nostri principi di intelligenza artificiale responsabile. Il servizio Viso è disponibile solo per i clienti e i partner gestiti da Microsoft. Usare il modulo di acquisizione riconoscimento volto per richiedere l'accesso. Per altre informazioni, vedere la pagina Accesso limitato alla funzione Viso.

Introduzione al riconoscimento facciale con la libreria client di Viso per .NET. Il servizio Viso di Azure per intelligenza artificiale fornisce l'accesso ad algoritmi avanzati per il rilevamento e il riconoscimento dei visi umani nelle immagini. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per eseguire l'autenticazione dei volti di base per mezzo di immagini remote.

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (NuGet) | Esempi

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito
IDE di Visual Studio o la versione corrente di .NET Core.
L'account Azure deve avere un ruolo Cognitive Services Contributor assegnato per poter accettare le condizioni di intelligenza artificiale responsabile e creare una risorsa. Per assegnare questo ruolo all'account, seguire la procedura descritta nella documentazione Assegnare ruoli oppure contattare l'amministratore.
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.
- È 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.

Creare variabili di ambiente

In questo esempio, vengono scritte le credenziali nelle variabili di ambiente del computer locale che esegue l'applicazione.

Vai al portale di Azure. Se la risorsa creata nella sezione Prerequisiti è stata distribuita correttamente, selezionare Vai alla risorsa in Passaggi successivi. La chiave e l'endpoint saranno disponibili nella pagina Chiavi ed endpoint in Gestione risorse. La chiave della risorsa non corrisponde all'ID sottoscrizione di Azure.

Suggerimento

Non includere la chiave direttamente nel codice e non renderla mai pubblica. Vedere l'articolo sulla sicurezza dei Servizi di Azure AI per altre opzioni di autenticazione, ad esempio Azure Key Vault.

Per impostare la variabile di ambiente per la chiave e l'endpoint, aprire una finestra della console e seguire le istruzioni del sistema operativo e dell'ambiente di sviluppo.

Per impostare la FACE_APIKEYvariabile di ambiente, sostituire <your_key> con una delle chiavi della risorsa.
Per impostare la FACE_ENDPOINTvariabile di ambiente, sostituire <your_endpoint> con l'endpoint della risorsa.

Windows
Linux

setx FACE_APIKEY <your_key>

setx FACE_ENDPOINT <your_endpoint>

Dopo aver aggiunto le variabili di ambiente, potrebbe essere necessario riavviare gli eventuali programmi in esecuzione che leggeranno le variabili di ambiente, inclusa la finestra della console.

export FACE_APIKEY=<your_key>

export FACE_ENDPOINT=<your_endpoint>

Dopo avere aggiunto le variabili di ambiente, eseguire source ~/.bashrc dalla finestra della console per rendere effettive le modifiche.

Identificare e verificare i visi

Creare una nuova applicazione C#
- IDE di Visual Studio
- CLI
Creare un'applicazione .NET Core con Visual Studio.

Installare la libreria client

Dopo aver creato un nuovo progetto, installare la libreria client facendo clic con il pulsante destro del mouse sulla soluzione del progetto in Esplora soluzioni e scegliendo Gestisci pacchetti NuGet. Nella finestra di dialogo Gestione pacchetti visualizzata selezionare Sfoglia, Includi versione preliminare e cercare Azure.AI.Vision.Face. Selezionare la versione più recente e fare clic su Installa.
In una finestra di una console, ad esempio cmd, PowerShell o Bash, usare il comando dotnet new per creare una nuova app console con il nome face-quickstart. Questo comando crea un semplice progetto C# "Hello World" con un unico file di origine: program.cs.
```
dotnet new console -n face-quickstart
```
Spostarsi nella cartella dell'app appena creata. È possibile compilare l'applicazione con il comando seguente:
```
dotnet build
```
L'output di compilazione non deve contenere alcun avviso o errore.
```
...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...
```
Installare la libreria client

Nella directory dell'applicazione installare la libreria client dell'API Viso per .NET con il comando seguente:
```
dotnet add package Azure.AI.Vision.Face --prerelease
```

Aggiungere il codice seguente nel file Program.cs.

Nota

Se non è stato ricevuto l'accesso al servizio Viso usando il modulo di assunzione, alcune di queste funzioni non funzioneranno.

using System.Net.Http.Headers;
using System.Text;

using Azure;
using Azure.AI.Vision.Face;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

namespace FaceQuickstart
{
    class Program
    {
        static readonly string largePersonGroupId = Guid.NewGuid().ToString();

        // URL path for the images.
        const string IMAGE_BASE_URL = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/";

        // From your Face subscription in the Azure portal, get your subscription key and endpoint.
        static readonly string SUBSCRIPTION_KEY = Environment.GetEnvironmentVariable("FACE_APIKEY") ?? "<apikey>";
        static readonly string ENDPOINT = Environment.GetEnvironmentVariable("FACE_ENDPOINT") ?? "<endpoint>";

        static void Main(string[] args)
        {
            // Recognition model 4 was released in 2021 February.
            // It is recommended since its accuracy is improved
            // on faces wearing masks compared with model 3,
            // and its overall accuracy is improved compared
            // with models 1 and 2.
            FaceRecognitionModel RECOGNITION_MODEL4 = FaceRecognitionModel.Recognition04;

            // Authenticate.
            FaceClient client = Authenticate(ENDPOINT, SUBSCRIPTION_KEY);

            // Identify - recognize a face(s) in a large person group (a large person group is created in this example).
            IdentifyInLargePersonGroup(client, IMAGE_BASE_URL, RECOGNITION_MODEL4).Wait();

            Console.WriteLine("End of quickstart.");
        }

        /*
         *	AUTHENTICATE
         *	Uses subscription key and region to create a client.
         */
        public static FaceClient Authenticate(string endpoint, string key)
        {
            return new FaceClient(new Uri(endpoint), new AzureKeyCredential(key));
        }

        // Detect faces from image url for recognition purposes. This is a helper method for other functions in this quickstart.
        // Parameter `returnFaceId` of `DetectAsync` must be set to `true` (by default) for recognition purposes.
        // Parameter `returnFaceAttributes` is set to include the QualityForRecognition attribute. 
        // Recognition model must be set to recognition_03 or recognition_04 as a result.
        // Result faces with insufficient quality for recognition are filtered out. 
        // The field `faceId` in returned `DetectedFace`s will be used in Verify and Identify.
        // It will expire 24 hours after the detection call.
        private static async Task<List<FaceDetectionResult>> DetectFaceRecognize(FaceClient faceClient, string url, FaceRecognitionModel recognition_model)
        {
            // Detect faces from image URL.
            Response<IReadOnlyList<FaceDetectionResult>> response = await faceClient.DetectAsync(new Uri(url), FaceDetectionModel.Detection03, recognition_model, returnFaceId: true, [FaceAttributeType.QualityForRecognition]);
            IReadOnlyList<FaceDetectionResult> detectedFaces = response.Value;
            List<FaceDetectionResult> sufficientQualityFaces = new List<FaceDetectionResult>();
            foreach (FaceDetectionResult detectedFace in detectedFaces)
            {
                var faceQualityForRecognition = detectedFace.FaceAttributes.QualityForRecognition;
                if (faceQualityForRecognition.HasValue && (faceQualityForRecognition.Value != QualityForRecognition.Low))
                {
                    sufficientQualityFaces.Add(detectedFace);
                }
            }
            Console.WriteLine($"{detectedFaces.Count} face(s) with {sufficientQualityFaces.Count} having sufficient quality for recognition detected from image `{Path.GetFileName(url)}`");

            return sufficientQualityFaces;
        }

        /*
         * IDENTIFY FACES
         * To identify faces, you need to create and define a large person group.
         * The Identify operation takes one or several face IDs from DetectedFace or PersistedFace and a LargePersonGroup and returns 
         * a list of Person objects that each face might belong to. Returned Person objects are wrapped as Candidate objects, 
         * which have a prediction confidence value.
         */
        public static async Task IdentifyInLargePersonGroup(FaceClient client, string url, FaceRecognitionModel recognitionModel)
        {
            Console.WriteLine("========IDENTIFY FACES========");
            Console.WriteLine();

            // Create a dictionary for all your images, grouping similar ones under the same key.
            Dictionary<string, string[]> personDictionary =
                new Dictionary<string, string[]>
                    { { "Family1-Dad", new[] { "Family1-Dad1.jpg", "Family1-Dad2.jpg" } },
                      { "Family1-Mom", new[] { "Family1-Mom1.jpg", "Family1-Mom2.jpg" } },
                      { "Family1-Son", new[] { "Family1-Son1.jpg", "Family1-Son2.jpg" } }
                    };
            // A group photo that includes some of the persons you seek to identify from your dictionary.
            string sourceImageFileName = "identification1.jpg";

            // Create a large person group.
            Console.WriteLine($"Create a person group ({largePersonGroupId}).");
            HttpClient httpClient = new HttpClient();
            httpClient.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", SUBSCRIPTION_KEY);
            using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["name"] = largePersonGroupId, ["recognitionModel"] = recognitionModel.ToString() }))))
            {
                content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                await httpClient.PutAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}", content);
            }
            // The similar faces will be grouped into a single large person group person.
            foreach (var groupedFace in personDictionary.Keys)
            {
                // Limit TPS
                await Task.Delay(250);
                string? personId = null;
                using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["name"] = groupedFace }))))
                {
                    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                    using (var response = await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}/persons", content))
                    {
                        string contentString = await response.Content.ReadAsStringAsync();
                        personId = (string?)(JsonConvert.DeserializeObject<Dictionary<string, object>>(contentString)?["personId"]);
                    }
                }
                Console.WriteLine($"Create a person group person '{groupedFace}'.");

                // Add face to the large person group person.
                foreach (var similarImage in personDictionary[groupedFace])
                {
                    Console.WriteLine($"Check whether image is of sufficient quality for recognition");
                    Response<IReadOnlyList<FaceDetectionResult>> response = await client.DetectAsync(new Uri($"{url}{similarImage}"), FaceDetectionModel.Detection03, recognitionModel, returnFaceId: false, [FaceAttributeType.QualityForRecognition]);
                    IReadOnlyList<FaceDetectionResult> detectedFaces1 = response.Value;
                    bool sufficientQuality = true;
                    foreach (var face1 in detectedFaces1)
                    {
                        var faceQualityForRecognition = face1.FaceAttributes.QualityForRecognition;
                        //  Only "high" quality images are recommended for person enrollment
                        if (faceQualityForRecognition.HasValue && (faceQualityForRecognition.Value != QualityForRecognition.High))
                        {
                            sufficientQuality = false;
                            break;
                        }
                    }

                    if (!sufficientQuality)
                    {
                        continue;
                    }

                    if (detectedFaces1.Count != 1)
                    {
                        continue;
                    }

                    // add face to the large person group
                    Console.WriteLine($"Add face to the person group person({groupedFace}) from image `{similarImage}`");
                    using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["url"] = $"{url}{similarImage}" }))))
                    {
                        content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                        await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces?detectionModel=detection_03", content);
                    }
                }
            }

            // Start to train the large person group.
            Console.WriteLine();
            Console.WriteLine($"Train person group {largePersonGroupId}.");
            await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}/train", null);

            // Wait until the training is completed.
            while (true)
            {
                await Task.Delay(1000);
                string? trainingStatus = null;
                using (var response = await httpClient.GetAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}/training"))
                {
                    string contentString = await response.Content.ReadAsStringAsync();
                    trainingStatus = (string?)(JsonConvert.DeserializeObject<Dictionary<string, object>>(contentString)?["status"]);
                }
                Console.WriteLine($"Training status: {trainingStatus}.");
                if ("succeeded".Equals(trainingStatus)) { break; }
            }
            Console.WriteLine();

            Console.WriteLine("Pausing for 60 seconds to avoid triggering rate limit on free account...");
            await Task.Delay(60000);

            List<Guid> sourceFaceIds = new List<Guid>();
            // Detect faces from source image url.
            List<FaceDetectionResult> detectedFaces = await DetectFaceRecognize(client, $"{url}{sourceImageFileName}", recognitionModel);

            // Add detected faceId to sourceFaceIds.
            foreach (var detectedFace in detectedFaces) { sourceFaceIds.Add(detectedFace.FaceId.Value); }

            // Identify the faces in a large person group.
            List<Dictionary<string, object>> identifyResults = new List<Dictionary<string, object>>();
            using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["faceIds"] = sourceFaceIds, ["largePersonGroupId"] = largePersonGroupId }))))
            {
                content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                using (var response = await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/identify", content))
                {
                    string contentString = await response.Content.ReadAsStringAsync();
                    identifyResults = JsonConvert.DeserializeObject<List<Dictionary<string, object>>>(contentString) ?? [];
                }
            }

            foreach (var identifyResult in identifyResults)
            {
                string faceId = (string)identifyResult["faceId"];
                List<Dictionary<string, object>> candidates = JsonConvert.DeserializeObject<List<Dictionary<string, object>>>(((JArray)identifyResult["candidates"]).ToString()) ?? [];
                if (candidates.Count == 0)
                {
                    Console.WriteLine($"No person is identified for the face in: {sourceImageFileName} - {faceId},");
                    continue;
                }

                string? personName = null;
                using (var response = await httpClient.GetAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{candidates.First()["personId"]}"))
                {
                    string contentString = await response.Content.ReadAsStringAsync();
                    personName = (string?)(JsonConvert.DeserializeObject<Dictionary<string, object>>(contentString)?["name"]);
                }
                Console.WriteLine($"Person '{personName}' is identified for the face in: {sourceImageFileName} - {faceId}," +
                    $" confidence: {candidates.First()["confidence"]}.");

                Dictionary<string, object> verifyResult = new Dictionary<string, object>();
                using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["faceId"] = faceId, ["personId"] = candidates.First()["personId"], ["largePersonGroupId"] = largePersonGroupId }))))
                {
                    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                    using (var response = await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/verify", content))
                    {
                        string contentString = await response.Content.ReadAsStringAsync();
                        verifyResult = JsonConvert.DeserializeObject<Dictionary<string, object>>(contentString) ?? [];
                    }
                }
                Console.WriteLine($"Verification result: is a match? {verifyResult["isIdentical"]}. confidence: {verifyResult["confidence"]}");
            }
            Console.WriteLine();

            // Delete large person group.
            Console.WriteLine("========DELETE PERSON GROUP========");
            Console.WriteLine();
            await httpClient.DeleteAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}");
            Console.WriteLine($"Deleted the person group {largePersonGroupId}.");
            Console.WriteLine();
        }
    }
}

Eseguire l'applicazione
- IDE di Visual Studio
- CLI
Eseguire l'applicazione facendo clic sul pulsante Debug nella parte superiore della finestra dell'ambiente di sviluppo integrato.
Eseguire l'applicazione dalla directory dell'applicazione con il comando dotnet run.
```
dotnet run
```

Output

========IDENTIFY FACES========

Create a person group (18d1c443-a01b-46a4-9191-121f74a831cd).
Create a person group person 'Family1-Dad'.
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Dad) from image `Family1-Dad1.jpg`
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Dad) from image `Family1-Dad2.jpg`
Create a person group person 'Family1-Mom'.
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Mom) from image `Family1-Mom1.jpg`
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Mom) from image `Family1-Mom2.jpg`
Create a person group person 'Family1-Son'.
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Son) from image `Family1-Son1.jpg`
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Son) from image `Family1-Son2.jpg`

Train person group 18d1c443-a01b-46a4-9191-121f74a831cd.
Training status: succeeded.

Pausing for 60 seconds to avoid triggering rate limit on free account...
4 face(s) with 4 having sufficient quality for recognition detected from image `identification1.jpg`
Person 'Family1-Dad' is identified for the face in: identification1.jpg - ad813534-9141-47b4-bfba-24919223966f, confidence: 0.96807.
Verification result: is a match? True. confidence: 0.96807
Person 'Family1-Mom' is identified for the face in: identification1.jpg - 1a39420e-f517-4cee-a898-5d968dac1a7e, confidence: 0.96902.
Verification result: is a match? True. confidence: 0.96902
No person is identified for the face in: identification1.jpg - 889394b1-e30f-4147-9be1-302beb5573f3,
Person 'Family1-Son' is identified for the face in: identification1.jpg - 0557d87b-356c-48a8-988f-ce0ad2239aa5, confidence: 0.9281.
Verification result: is a match? True. confidence: 0.9281

========DELETE PERSON GROUP========

Deleted the person group 18d1c443-a01b-46a4-9191-121f74a831cd.

End of quickstart.

Suggerimento

L'API Viso esegue una serie di modelli predefiniti che sono per natura statici (le prestazioni del modello non regrediscono né migliorano durante l'esecuzione del servizio). I risultati generati dal modello potrebbero cambiare se Microsoft ne aggiorna il back-end senza eseguire la migrazione a una versione interamente nuova. Per trarre vantaggio da una versione più recente di un modello, è possibile ripetere il training di PersonGroup specificando il nuovo modello come parametro con le stesse immagini di registrazione.

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di Azure AI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.

Passaggi successivi

In queste istruzioni di avvio rapido si è appreso come usare la libreria client di Viso per .NET per eseguire l'identificazione facciale di base. Informazioni sui diversi modelli di rilevamento dei volti e su come specificare il modello appropriato per il caso d'uso.

Specificare la versione di un modello di rilevamento dei volti

Che cos'è il servizio Viso?
Un codice di esempio più completo è disponibile in GitHub.

Introduzione al riconoscimento facciale con la libreria client di Viso per Python. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base. Il servizio Viso fornisce l'accesso ad algoritmi avanzati per il rilevamento e il riconoscimento dei visi umani nelle immagini. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per eseguire l'autenticazione dei volti di base per mezzo di immagini remote.

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (PiPy) | Esempi

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito
Python 3.x
- L'installazione di Python deve includere pip. È possibile verificare se pip è installato eseguendo pip --version nella riga di comando. Ottenere pip installando la versione più recente di Python.
L'account Azure deve avere un ruolo Cognitive Services Contributor assegnato per poter accettare le condizioni di intelligenza artificiale responsabile e creare una risorsa. Per assegnare questo ruolo all'account, seguire la procedura descritta nella documentazione Assegnare ruoli oppure contattare l'amministratore.
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.
- È 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.

Creare variabili di ambiente

In questo esempio, vengono scritte le credenziali nelle variabili di ambiente del computer locale che esegue l'applicazione.

Suggerimento

Non includere la chiave direttamente nel codice e non renderla mai pubblica. Vedere l'articolo sulla sicurezza dei Servizi di Azure AI per altre opzioni di autenticazione, ad esempio Azure Key Vault.

Per impostare la variabile di ambiente per la chiave e l'endpoint, aprire una finestra della console e seguire le istruzioni del sistema operativo e dell'ambiente di sviluppo.

Per impostare la FACE_APIKEYvariabile di ambiente, sostituire <your_key> con una delle chiavi della risorsa.
Per impostare la FACE_ENDPOINTvariabile di ambiente, sostituire <your_endpoint> con l'endpoint della risorsa.

Windows
Linux

setx FACE_APIKEY <your_key>

setx FACE_ENDPOINT <your_endpoint>

Dopo aver aggiunto le variabili di ambiente, potrebbe essere necessario riavviare gli eventuali programmi in esecuzione che leggeranno le variabili di ambiente, inclusa la finestra della console.

export FACE_APIKEY=<your_key>

export FACE_ENDPOINT=<your_endpoint>

Dopo avere aggiunto le variabili di ambiente, eseguire source ~/.bashrc dalla finestra della console per rendere effettive le modifiche.

Identificare e verificare i visi

Installare la libreria client

Dopo l'installazione di Python, è possibile installare la libreria client con:
```
pip install --upgrade azure-ai-vision-face
```

Creare una nuova applicazione Python

Creare un nuovo script Python, ad esempio quickstart-file.py. Successivamente, aprirlo nell'editor o nell'IDE preferito e incollarlo nel codice seguente.

Nota

Se non è stato ricevuto l'accesso al servizio Viso usando il modulo di assunzione, alcune di queste funzioni non funzioneranno.

import os
import time
import uuid
import requests

from azure.core.credentials import AzureKeyCredential
from azure.ai.vision.face import FaceClient
from azure.ai.vision.face.models import (
    FaceAttributeTypeRecognition04,
    FaceDetectionModel,
    FaceRecognitionModel,
    QualityForRecognition,
)


# This key will serve all examples in this document.
KEY = os.environ["FACE_APIKEY"]

# This endpoint will be used in all examples in this quickstart.
ENDPOINT = os.environ["FACE_ENDPOINT"]

# Used in the Large Person Group Operations and Delete Large Person Group examples.
# LARGE_PERSON_GROUP_ID should be all lowercase and alphanumeric. For example, 'mygroupname' (dashes are OK).
LARGE_PERSON_GROUP_ID = str(uuid.uuid4())  # assign a random ID (or name it anything)

HEADERS = {"Ocp-Apim-Subscription-Key": KEY, "Content-Type": "application/json"}

# Create an authenticated FaceClient.
with FaceClient(endpoint=ENDPOINT, credential=AzureKeyCredential(KEY)) as face_client:
    '''
    Create the LargePersonGroup
    '''
    # Create empty Large Person Group. Large Person Group ID must be lower case, alphanumeric, and/or with '-', '_'.
    print("Person group:", LARGE_PERSON_GROUP_ID)
    response = requests.put(
        ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}",
        headers=HEADERS,
        json={"name": LARGE_PERSON_GROUP_ID, "recognitionModel": "recognition_04"})
    response.raise_for_status()

    # Define woman friend
    response = requests.post(ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/persons", headers=HEADERS, json={"name": "Woman"})
    response.raise_for_status()
    woman = response.json()
    # Define man friend
    response = requests.post(ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/persons", headers=HEADERS, json={"name": "Man"})
    response.raise_for_status()
    man = response.json()
    # Define child friend
    response = requests.post(ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/persons", headers=HEADERS, json={"name": "Child"})
    response.raise_for_status()
    child = response.json()

    '''
    Detect faces and register them to each person
    '''
    # Find all jpeg images of friends in working directory (TBD pull from web instead)
    woman_images = [
        "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Mom1.jpg",  # noqa: E501
        "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Mom2.jpg",  # noqa: E501
    ]
    man_images = [
        "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Dad1.jpg",  # noqa: E501
        "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Dad2.jpg",  # noqa: E501
    ]
    child_images = [
        "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Son1.jpg",  # noqa: E501
        "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Son2.jpg",  # noqa: E501
    ]

    # Add to woman person
    for image in woman_images:
        # Check if the image is of sufficent quality for recognition.
        sufficientQuality = True
        detected_faces = face_client.detect_from_url(
            url=image,
            detection_model=FaceDetectionModel.DETECTION_03,
            recognition_model=FaceRecognitionModel.RECOGNITION_04,
            return_face_id=True,
            return_face_attributes=[FaceAttributeTypeRecognition04.QUALITY_FOR_RECOGNITION])
        for face in detected_faces:
            if face.face_attributes.quality_for_recognition != QualityForRecognition.HIGH:
                sufficientQuality = False
                break

        if not sufficientQuality:
            continue

        if len(detected_faces) != 1:
            continue

        response = requests.post(
            ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/persons/{woman['personId']}/persistedFaces",
            headers=HEADERS,
            json={"url": image})
        response.raise_for_status()
        print(f"face {face.face_id} added to person {woman['personId']}")


    # Add to man person
    for image in man_images:
        # Check if the image is of sufficent quality for recognition.
        sufficientQuality = True
        detected_faces = face_client.detect_from_url(
            url=image,
            detection_model=FaceDetectionModel.DETECTION_03,
            recognition_model=FaceRecognitionModel.RECOGNITION_04,
            return_face_id=True,
            return_face_attributes=[FaceAttributeTypeRecognition04.QUALITY_FOR_RECOGNITION])
        for face in detected_faces:
            if face.face_attributes.quality_for_recognition != QualityForRecognition.HIGH:
                sufficientQuality = False
                break

        if not sufficientQuality:
            continue

        if len(detected_faces) != 1:
            continue

        response = requests.post(
            ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/persons/{man['personId']}/persistedFaces",
            headers=HEADERS,
            json={"url": image})
        response.raise_for_status()
        print(f"face {face.face_id} added to person {man['personId']}")

    # Add to child person
    for image in child_images:
        # Check if the image is of sufficent quality for recognition.
        sufficientQuality = True
        detected_faces = face_client.detect_from_url(
            url=image,
            detection_model=FaceDetectionModel.DETECTION_03,
            recognition_model=FaceRecognitionModel.RECOGNITION_04,
            return_face_id=True,
            return_face_attributes=[FaceAttributeTypeRecognition04.QUALITY_FOR_RECOGNITION])
        for face in detected_faces:
            if face.face_attributes.quality_for_recognition != QualityForRecognition.HIGH:
                sufficientQuality = False
                break
        if not sufficientQuality:
            continue

        if len(detected_faces) != 1:
            continue

        response = requests.post(
            ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/persons/{child['personId']}/persistedFaces",
            headers=HEADERS,
            json={"url": image})
        response.raise_for_status()
        print(f"face {face.face_id} added to person {child['personId']}")

    '''
    Train LargePersonGroup
    '''
    # Train the large person group
    print(f"Train the person group {LARGE_PERSON_GROUP_ID}")
    response = requests.post(ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/train", headers=HEADERS)
    response.raise_for_status()

    while (True):
        response = requests.get(ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/training", headers=HEADERS)
        response.raise_for_status()
        training_status = response.json()["status"]
        if training_status == "succeeded":
            break
    print(f"The person group {LARGE_PERSON_GROUP_ID} is trained successfully.")

    '''
    Identify a face against a defined LargePersonGroup
    '''
    # Group image for testing against
    test_image = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/identification1.jpg"  # noqa: E501

    print("Pausing for 60 seconds to avoid triggering rate limit on free account...")
    time.sleep(60)

    # Detect faces
    face_ids = []
    # We use detection model 03 to get better performance, recognition model 04 to support quality for
    # recognition attribute.
    faces = face_client.detect_from_url(
        url=test_image,
        detection_model=FaceDetectionModel.DETECTION_03,
        recognition_model=FaceRecognitionModel.RECOGNITION_04,
        return_face_id=True,
        return_face_attributes=[FaceAttributeTypeRecognition04.QUALITY_FOR_RECOGNITION])
    for face in faces:
        # Only take the face if it is of sufficient quality.
        if face.face_attributes.quality_for_recognition != QualityForRecognition.LOW:
            face_ids.append(face.face_id)

    # Identify faces
    response = requests.post(
        ENDPOINT + f"/face/v1.0/identify",
        headers=HEADERS,
        json={"faceIds": face_ids, "largePersonGroupId": LARGE_PERSON_GROUP_ID})
    response.raise_for_status()
    results = response.json()
    print("Identifying faces in image")
    if not results:
        print("No person identified in the person group")
    for identifiedFace in results:
        if len(identifiedFace["candidates"]) > 0:
            print(f"Person is identified for face ID {identifiedFace['faceId']} in image, with a confidence of "
                  f"{identifiedFace['candidates'][0]['confidence']}.")  # Get topmost confidence score

            # Verify faces
            response = requests.post(
                ENDPOINT + f"/face/v1.0/verify",
                headers=HEADERS,
                json={"faceId": identifiedFace["faceId"], "personId": identifiedFace["candidates"][0]["personId"], "largePersonGroupId": LARGE_PERSON_GROUP_ID})
            response.raise_for_status()
            verify_result = response.json()
            print(f"verification result: {verify_result['isIdentical']}. confidence: {verify_result['confidence']}")
        else:
            print(f"No person identified for face ID {identifiedFace['faceId']} in image.")

    print()

    # Delete the large person group
    response = requests.delete(ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}", headers=HEADERS)
    response.raise_for_status()
    print(f"The person group {LARGE_PERSON_GROUP_ID} is deleted.")

    print()
    print("End of quickstart.")

Eseguire l'app di riconoscimento volto dalla directory dell'applicazione con il comando python.
```
python quickstart-file.py
```
Suggerimento

L'API Viso esegue una serie di modelli predefiniti che sono per natura statici (le prestazioni del modello non regrediscono né migliorano durante l'esecuzione del servizio). I risultati generati dal modello potrebbero cambiare se Microsoft ne aggiorna il back-end senza eseguire la migrazione a una versione interamente nuova. Per trarre vantaggio da una versione più recente di un modello, è possibile ripetere il training di PersonGroup specificando il nuovo modello come parametro con le stesse immagini di registrazione.

Output

Person group: ad12b2db-d892-48ec-837a-0e7168c18224
face 335a2cb1-5211-4c29-9c45-776dd014b2af added to person 9ee65510-81a5-47e5-9e50-66727f719465
face df57eb50-4a13-4f93-b804-cd108327ad5a added to person 9ee65510-81a5-47e5-9e50-66727f719465
face d8b7b8b8-3ca6-4309-b76e-eeed84f7738a added to person 00651036-4236-4004-88b9-11466c251548
face dffbb141-f40b-4392-8785-b6c434fa534e added to person 00651036-4236-4004-88b9-11466c251548
face 9cdac36e-5455-447b-a68d-eb1f5e2ec27d added to person 23614724-b132-407a-aaa0-67003987ce93
face d8208412-92b7-4b8d-a2f8-3926c839c87e added to person 23614724-b132-407a-aaa0-67003987ce93
Train the person group ad12b2db-d892-48ec-837a-0e7168c18224
The person group ad12b2db-d892-48ec-837a-0e7168c18224 is trained successfully.
Pausing for 60 seconds to avoid triggering rate limit on free account...
Identifying faces in image
Person is identified for face ID bc52405a-5d83-4500-9218-557468ccdf99 in image, with a confidence of 0.96726.
verification result: True. confidence: 0.96726
Person is identified for face ID dfcc3fc8-6252-4f3a-8205-71466f39d1a7 in image, with a confidence of 0.96925.
verification result: True. confidence: 0.96925
No person identified for face ID 401c581b-a178-45ed-8205-7692f6eede88 in image.
Person is identified for face ID 8809d9c7-e362-4727-8c95-e1e44f5c2e8a in image, with a confidence of 0.92898.
verification result: True. confidence: 0.92898

The person group ad12b2db-d892-48ec-837a-0e7168c18224 is deleted.

End of quickstart.

Pulire le risorse

Passaggi successivi

In queste istruzioni di avvio rapido si è appreso come usare la libreria client di Viso per Python per eseguire l'identificazione facciale di base. Informazioni sui diversi modelli di rilevamento dei volti e su come specificare il modello appropriato per il caso d'uso.

Specificare la versione di un modello di rilevamento dei volti

Che cos'è il servizio Viso?
Un codice di esempio più completo è disponibile in GitHub.

Introduzione al riconoscimento facciale con la libreria client di Viso per JavaScript. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base. Il servizio Viso fornisce l'accesso ad algoritmi avanzati per il rilevamento e il riconoscimento dei visi umani nelle immagini. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per eseguire l'autenticazione dei volti di base per mezzo di immagini remote.

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (npm) | Esempi

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito
La versione più recente di Node.js
L'account Azure deve avere un ruolo Cognitive Services Contributor assegnato per poter accettare le condizioni di intelligenza artificiale responsabile e creare una risorsa. Per assegnare questo ruolo all'account, seguire la procedura descritta nella documentazione Assegnare ruoli oppure contattare l'amministratore.
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.
- È 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.

Creare variabili di ambiente

In questo esempio, vengono scritte le credenziali nelle variabili di ambiente del computer locale che esegue l'applicazione.

Suggerimento

Non includere la chiave direttamente nel codice e non renderla mai pubblica. Vedere l'articolo sulla sicurezza dei Servizi di Azure AI per altre opzioni di autenticazione, ad esempio Azure Key Vault.

Per impostare la variabile di ambiente per la chiave e l'endpoint, aprire una finestra della console e seguire le istruzioni del sistema operativo e dell'ambiente di sviluppo.

Per impostare la FACE_APIKEYvariabile di ambiente, sostituire <your_key> con una delle chiavi della risorsa.
Per impostare la FACE_ENDPOINTvariabile di ambiente, sostituire <your_endpoint> con l'endpoint della risorsa.

Windows
Linux

setx FACE_APIKEY <your_key>

setx FACE_ENDPOINT <your_endpoint>

Dopo aver aggiunto le variabili di ambiente, potrebbe essere necessario riavviare gli eventuali programmi in esecuzione che leggeranno le variabili di ambiente, inclusa la finestra della console.

export FACE_APIKEY=<your_key>

export FACE_ENDPOINT=<your_endpoint>

Dopo avere aggiunto le variabili di ambiente, eseguire source ~/.bashrc dalla finestra della console per rendere effettive le modifiche.

Identificare e verificare i visi

Creare una nuova applicazione Node.js

In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app.
```
mkdir myapp && cd myapp
```
Eseguire il comando npm init per creare un'applicazione Node con un file package.json.
```
npm init
```
Installare i pacchetti npm @azure-rest/ai-vision-face:
```
npm install @azure-rest/ai-vision-face
```
Il file package.json dell'app viene aggiornato con le dipendenze.

Creare un file denominato index.js, aprirlo in un editor di testo e incollarlo nel codice seguente:

Nota

Se non è stato ricevuto l'accesso al servizio Viso usando il modulo di assunzione, alcune di queste funzioni non funzioneranno.

const { randomUUID } = require("crypto");

const { AzureKeyCredential } = require("@azure/core-auth");

const createFaceClient = require("@azure-rest/ai-vision-face").default,
  { getLongRunningPoller } = require("@azure-rest/ai-vision-face");

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const main = async () => {
  const endpoint = process.env["FACE_ENDPOINT"] ?? "<endpoint>";
  const apikey = process.env["FACE_APIKEY"] ?? "<apikey>";
  const credential = new AzureKeyCredential(apikey);
  const client = createFaceClient(endpoint, credential);

  const imageBaseUrl =
    "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/";
  const largePersonGroupId = randomUUID();

  console.log("========IDENTIFY FACES========");
  console.log();

  // Create a dictionary for all your images, grouping similar ones under the same key.
  const personDictionary = {
    "Family1-Dad": ["Family1-Dad1.jpg", "Family1-Dad2.jpg"],
    "Family1-Mom": ["Family1-Mom1.jpg", "Family1-Mom2.jpg"],
    "Family1-Son": ["Family1-Son1.jpg", "Family1-Son2.jpg"],
  };

  // A group photo that includes some of the persons you seek to identify from your dictionary.
  const sourceImageFileName = "identification1.jpg";

  // Create a large person group.
  console.log(`Creating a person group with ID: ${largePersonGroupId}`);
  await client.path("/largepersongroups/{largePersonGroupId}", largePersonGroupId).put({
    body: {
      name: largePersonGroupId,
      recognitionModel: "recognition_04",
    },
  });

  // The similar faces will be grouped into a single large person group person.
  console.log("Adding faces to person group...");
  await Promise.all(
    Object.keys(personDictionary).map(async (name) => {
      console.log(`Create a persongroup person: ${name}`);
      const createLargePersonGroupPersonResponse = await client
        .path("/largepersongroups/{largePersonGroupId}/persons", largePersonGroupId)
        .post({
          body: { name },
        });

      const { personId } = createLargePersonGroupPersonResponse.body;

      await Promise.all(
        personDictionary[name].map(async (similarImage) => {
          // Check if the image is of sufficent quality for recognition.
          const detectResponse = await client.path("/detect").post({
            contentType: "application/json",
            queryParameters: {
              detectionModel: "detection_03",
              recognitionModel: "recognition_04",
              returnFaceId: false,
              returnFaceAttributes: ["qualityForRecognition"],
            },
            body: { url: `${imageBaseUrl}${similarImage}` },
          });

          const sufficientQuality = detectResponse.body.every(
            (face) => face.faceAttributes?.qualityForRecognition === "high",
          );
          if (!sufficientQuality) {
            return;
          }

          if (detectResponse.body.length != 1) {
            return;
          }

          // Quality is sufficent, add to group.
          console.log(
            `Add face to the person group person: (${name}) from image: (${similarImage})`,
          );
          await client
            .path(
              "/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces",
              largePersonGroupId,
              personId,
            )
            .post({
              queryParameters: { detectionModel: "detection_03" },
              body: { url: `${imageBaseUrl}${similarImage}` },
            });
        }),
      );
    }),
  );
  console.log("Done adding faces to person group.");

  // Start to train the large person group.
  console.log();
  console.log(`Training person group: ${largePersonGroupId}`);
  const trainResponse = await client
    .path("/largepersongroups/{largePersonGroupId}/train", largePersonGroupId)
    .post();
  const poller = await getLongRunningPoller(client, trainResponse);
  await poller.pollUntilDone();
  console.log(`Training status: ${poller.getOperationState().status}`);
  if (poller.getOperationState().status !== "succeeded") {
    return;
  }

  console.log("Pausing for 60 seconds to avoid triggering rate limit on free account...");
  await sleep(60000);

  // Detect faces from source image url and only take those with sufficient quality for recognition.
  const detectResponse = await client.path("/detect").post({
    contentType: "application/json",
    queryParameters: {
      detectionModel: "detection_03",
      recognitionModel: "recognition_04",
      returnFaceId: true,
      returnFaceAttributes: ["qualityForRecognition"],
    },
    body: { url: `${imageBaseUrl}${sourceImageFileName}` },
  });
  const faceIds = detectResponse.body.filter((face) => face.faceAttributes?.qualityForRecognition !== "low").map((face) => face.faceId);

  // Identify the faces in a large person group.
  const identifyResponse = await client.path("/identify").post({
    body: { faceIds, largePersonGroupId: largePersonGroupId },
  });
  await Promise.all(
    identifyResponse.body.map(async (result) => {
      try {
        const getLargePersonGroupPersonResponse = await client
          .path(
            "/largepersongroups/{largePersonGroupId}/persons/{personId}",
            largePersonGroupId,
            result.candidates[0].personId,
          )
          .get();
        const person = getLargePersonGroupPersonResponse.body;
        console.log(
          `Person: ${person.name} is identified for face in: ${sourceImageFileName} with ID: ${result.faceId}. Confidence: ${result.candidates[0].confidence}`,
        );

        // Verification:
        const verifyResponse = await client.path("/verify").post({
          body: {
            faceId: result.faceId,
            largePersonGroupId: largePersonGroupId,
            personId: person.personId,
          },
        });
        console.log(
          `Verification result between face ${result.faceId} and person ${person.personId}: ${verifyResponse.body.isIdentical} with confidence: ${verifyResponse.body.confidence}`,
        );
      } catch (error) {
        console.log(`No persons identified for face with ID ${result.faceId}`);
      }
    }),
  );
  console.log();

  // Delete large person group.
  console.log(`Deleting person group: ${largePersonGroupId}`);
  await client.path("/largepersongroups/{largePersonGroupId}", largePersonGroupId).delete();
  console.log();

  console.log("Done.");
};

main().catch(console.error);

Eseguire l'applicazione con il comando node nel file quickstart.
```
node index.js
```

Output

========IDENTIFY FACES========

Creating a person group with ID: a230ac8b-09b2-4fa0-ae04-d76356d88d9f
Adding faces to person group...
Create a persongroup person: Family1-Dad
Create a persongroup person: Family1-Mom
Create a persongroup person: Family1-Son
Add face to the person group person: (Family1-Dad) from image: (Family1-Dad1.jpg)
Add face to the person group person: (Family1-Mom) from image: (Family1-Mom1.jpg)
Add face to the person group person: (Family1-Son) from image: (Family1-Son1.jpg)
Add face to the person group person: (Family1-Dad) from image: (Family1-Dad2.jpg)
Add face to the person group person: (Family1-Mom) from image: (Family1-Mom2.jpg)
Add face to the person group person: (Family1-Son) from image: (Family1-Son2.jpg)
Done adding faces to person group.

Training person group: a230ac8b-09b2-4fa0-ae04-d76356d88d9f
Training status: succeeded
Pausing for 60 seconds to avoid triggering rate limit on free account...
No persons identified for face with ID 56380623-8bf0-414a-b9d9-c2373386b7be
Person: Family1-Dad is identified for face in: identification1.jpg with ID: c45052eb-a910-4fd3-b1c3-f91ccccc316a. Confidence: 0.96807
Person: Family1-Son is identified for face in: identification1.jpg with ID: 8dce9b50-513f-4fe2-9e19-352acfd622b3. Confidence: 0.9281
Person: Family1-Mom is identified for face in: identification1.jpg with ID: 75868da3-66f6-4b5f-a172-0b619f4d74c1. Confidence: 0.96902
Verification result between face c45052eb-a910-4fd3-b1c3-f91ccccc316a and person 35a58d14-fd58-4146-9669-82ed664da357: true with confidence: 0.96807
Verification result between face 8dce9b50-513f-4fe2-9e19-352acfd622b3 and person 2d4d196c-5349-431c-bf0c-f1d7aaa180ba: true with confidence: 0.9281
Verification result between face 75868da3-66f6-4b5f-a172-0b619f4d74c1 and person 35d5de9e-5f92-4552-8907-0d0aac889c3e: true with confidence: 0.96902

Deleting person group: a230ac8b-09b2-4fa0-ae04-d76356d88d9f

Done.

Pulire le risorse

Passaggi successivi

In queste istruzioni di avvio rapido si è appreso come usare la libreria client di Viso per JavaScript per eseguire l'identificazione facciale di base. Informazioni sui diversi modelli di rilevamento dei volti e su come specificare il modello appropriato per il caso d'uso.

Specificare la versione di un modello di rilevamento dei volti

Che cos'è il servizio Viso?
Un codice di esempio più completo è disponibile in GitHub.

Introduzione al riconoscimento facciale con l'API REST Viso. Il servizio Viso fornisce l'accesso ad algoritmi avanzati per il rilevamento e il riconoscimento dei visi umani nelle immagini.

Nota

Questa guida di avvio rapido usa comandi cURL per chiamare l'API REST. È anche possibile chiamare l'API REST usando un linguaggio di programmazione. Scenari complessi come l'identificazione del viso sono più facili da implementare usando un SDK del linguaggio. In GitHub sono disponibili esempi in C#, Python, Java, JavaScript e Go.

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito
L'account Azure deve avere un ruolo Cognitive Services Contributor assegnato per poter accettare le condizioni di intelligenza artificiale responsabile e creare una risorsa. Per assegnare questo ruolo all'account, seguire la procedura descritta nella documentazione Assegnare ruoli oppure contattare l'amministratore.
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 riportato di seguito nell'argomento di avvio rapido.
- È 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.
PowerShell versione 6.0+ o un'applicazione della riga di comando simile.
cURL installato.

Identificare e verificare i visi

Nota

Se non è stato ricevuto l'accesso al servizio Viso usando il modulo di assunzione, alcune di queste funzioni non funzioneranno.

Prima di tutto, chiamare l'API Rilevamento sul viso di origine. Questo è il viso che tenteremo di identificare dal gruppo più grande. Copiare il comando seguente in un editor di testo, inserire la propria chiave ed endpoint, copiarlo in una finestra della shell ed eseguirlo.

Windows
Linux

curl.exe -v -X POST "https://{resource endpoint}/face/v1.0/detect?returnFaceId=true&returnFaceLandmarks=false&recognitionModel=recognition_04&returnRecognitionModel=false&detectionModel=detection_03&faceIdTimeToLive=86400" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{""url"":""https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/identification1.jpg""}"

curl -v -X POST "https://{resource endpoint}/face/v1.0/detect?returnFaceId=true&returnFaceLandmarks=false&recognitionModel=recognition_04&returnRecognitionModel=false&detectionModel=detection_03&faceIdTimeToLive=86400" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{\"url\":\"https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/identification1.jpg\"}"

Salvare la stringa di ID viso restituita in un percorso temporaneo. Verrà usato di nuovo alla fine.

Sarà quindi necessario creare un oggetto LargePersonGroup e assegnargli un ID arbitrario che corrisponda al criterio regex ^[a-z0-9-_]+$. Questo oggetto archivierà i dati aggregati sui visi di varie persone. Eseguire il comando seguente, inserendo la propria chiave. Facoltativamente, modificare il nome e i metadati del gruppo nel corpo della richiesta.

Windows
Linux

curl.exe -v -X PUT "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{
    ""name"": ""large-person-group-name"",
    ""userData"": ""User-provided data attached to the large person group."",
    ""recognitionModel"": ""recognition_04""
}"

curl -v -X PUT "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{
    \"name\": \"large-person-group-name\",
    \"userData\": \"User-provided data attached to the large person group.\",
    \"recognitionModel\": \"recognition_04\"
}"

Salvare l'ID specificato del gruppo creato in un percorso temporaneo.

Successivamente, si creeranno oggetti Persona che appartengono al gruppo. Eseguire il comando seguente, inserendo la propria chiave e l'ID di LargePersonGroup del passaggio precedente. Questo comando crea una Persona denominata "Family1-Dad".

Windows
Linux

curl.exe -v -X POST "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/persons" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{
    ""name"": ""Family1-Dad"",
    ""userData"": ""User-provided data attached to the person.""
}"

curl -v -X POST "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/persons" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{
    \"name\": \"Family1-Dad\",
    \"userData\": \"User-provided data attached to the person.\"
}"

Dopo aver eseguito questo comando, eseguirlo di nuovo con dati di input differenti per creare altri oggetti Persona: "Family1-Mom", "Family1-Son", "Family1-Daughter", "Family2-Lady" e "Family2-Man".

Salvare gli ID di ogni Persona creata. È importante tenere traccia dell'ID di ogni persona.

Sarà quindi necessario rilevare nuovi visi e associarli agli oggetti Persona esistenti. Il comando seguente rileva un viso dall'immagine Family1-Dad1.jpg e lo aggiunge alla persona corrispondente. È necessario specificare personId come ID restituito quando è stato creato l'oggetto Persona "Family1-Dad". Il nome dell'immagine corrisponde al nome della Persona creata. Immettere anche l'ID LargePersonGroup e la chiave nei campi appropriati.
- Windows
- Linux
```
curl.exe -v -X POST "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces?detectionModel=detection_03" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{""url"":""https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Dad1.jpg""}"
```
```
curl -v -X POST "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces?detectionModel=detection_03" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{\"url\":\"https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Dad1.jpg\"}"
```
Eseguire quindi di nuovo il comando precedente con un'immagine di origine e una Persona di destinazione differenti. Le immagini disponibili sono: Family1-Dad1.jpg, Family1-Dad2.jpg Family1-Mom1.jpg, Family1-Mom2.jpg, Family1-Son1.jpg, Family1-Son2.jpg, Family1-Daughter1.jpg, Family1-Daughter2.jpg, Family2-Lady1.jpg, Family2-Lady2.jpg, Family2-Man1.jpg e Family2-Man2.jpg. Assicurarsi che la Persona il cui ID si ha specificato nella chiamata API corrisponda al nome del file di immagine nel corpo della richiesta.

Al termine di questo passaggio, si dovrebbe disporre di vari oggetti Persona con uno o più visi corrispondenti, rilevati direttamente dalle immagini fornite.

Eseguire quindi il training di LargePersonGroup con i dati sul viso correnti. L'operazione di training insegna al modello come associare le caratteristiche facciali, talvolta aggregate da diverse immagini di origine, a ogni singola persona. Inserire l'ID LargePersonGroup e la chiave prima di eseguire il comando.

Windows
Linux

curl.exe -v -X POST "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/train" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data ""

curl -v -X POST "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/train" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data ""

Verificare se lo stato del training è riuscito. In caso contrario, attendere un po' di tempo ed eseguire di nuovo la query.

Windows
Linux

curl.exe -v "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/training" -H "Ocp-Apim-Subscription-Key: {subscription key}"

curl -v "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/training" -H "Ocp-Apim-Subscription-Key: {subscription key}"

A questo punto è possibile chiamare l'API Identificazione, usando l'ID del viso di origine del primo passaggio e l'ID LargePersonGroup. Inserire questi valori nei campi appropriati nel corpo della richiesta, quindi inserire la chiave.

Windows
Linux

curl.exe -v -X POST "https://{resource endpoint}/face/v1.0/identify" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{
    ""largePersonGroupId"": ""INSERT_PERSONGROUP_ID"",
    ""faceIds"": [
        ""INSERT_SOURCE_FACE_ID""
    ],
    ""maxNumOfCandidatesReturned"": 1,
    ""confidenceThreshold"": 0.5
}"

curl -v -X POST "https://{resource endpoint}/face/v1.0/identify" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{
    \"largePersonGroupId\": \"INSERT_PERSONGROUP_ID\",
    \"faceIds\": [
        \"INSERT_SOURCE_FACE_ID\"
    ],
    \"maxNumOfCandidatesReturned\": 1,
    \"confidenceThreshold\": 0.5
}"

La risposta deve fornire un'ID Persona che indica la persona identificata con il viso di origine. Deve essere l'ID che corrisponde alla persona "Family1-Dad", perché il viso di origine è di quella persona.

Per eseguire la verifica del viso, si userà l'ID Persona restituito nel passaggio precedente, l'ID LargePersonGroup e anche l'ID viso di origine. Inserire questi valori nei campi nel corpo della richiesta e inserire la chiave.

Windows
Linux

curl.exe -v -X POST "https://{resource endpoint}/face/v1.0/verify" `
-H "Content-Type: application/json" `
-H "Ocp-Apim-Subscription-Key: {subscription key}" `
--data-ascii "{
    ""faceId"": ""INSERT_SOURCE_FACE_ID"",
    ""personId"": ""INSERT_PERSON_ID"",
    ""largePersonGroupId"": ""INSERT_PERSONGROUP_ID""
}"

curl -v -X POST "https://{resource endpoint}/face/v1.0/verify" \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: {subscription key}" \
--data-ascii "{
    \"faceId\": \"INSERT_SOURCE_FACE_ID\",
    \"personId\": \"INSERT_PERSON_ID\",
    \"largePersonGroupId\": \"INSERT_PERSONGROUP_ID\"
}"

La risposta deve fornire un risultato di verifica booleano insieme a un valore di attendibilità.

Pulire le risorse

Per eliminare l'oggetto LargePersonGroup creato in questo esercizio, eseguire la chiamata LargePersonGroup - Delete.

Windows
Linux

curl.exe -v -X DELETE "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}" -H "Ocp-Apim-Subscription-Key: {subscription key}"

curl -v -X DELETE "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Passaggi successivi

In questo argomento di avvio rapido si è appreso come usare l'API REST Viso per eseguire attività di riconoscimento facciale di base. Informazioni sui diversi modelli di rilevamento dei volti e su come specificare il modello appropriato per il caso d'uso.

Specificare la versione di un modello di rilevamento dei volti

Che cos'è il servizio Viso?

Condividi tramite

Avvio rapido: Usare il servizio Viso

Prerequisiti

Creare variabili di ambiente

Identificare e verificare i visi

Installare la libreria client

Installare la libreria client

Output

Pulire le risorse

Passaggi successivi

Prerequisiti

Creare variabili di ambiente

Identificare e verificare i visi

Output

Pulire le risorse

Passaggi successivi

Prerequisiti

Creare variabili di ambiente

Identificare e verificare i visi

Output

Pulire le risorse

Passaggi successivi

Prerequisiti

Identificare e verificare i visi

Pulire le risorse

Passaggi successivi

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive