Compartilhar via

Início Rápido: Usar o serviço de Detecção Facial

Important

Se você estiver usando produtos ou serviços da Microsoft para processar dados biométricos, você será responsável por: (i) fornecer aviso aos titulares dos dados, inclusive com relação aos períodos de retenção e destruição; (ii) obter o consentimento dos titulares dos dados; e (iii) excluir os dados biométricos, tudo conforme apropriado e exigido pelos requisitos de proteção de dados aplicáveis. "Dados Biométricos" terão o significado definido no artigo 4º do GDPR e, se aplicável, termos equivalentes em outros requisitos de proteção de dados. Para obter informações relacionadas, confira Dados e privacidade da Detecção Facial.

Caution

O acesso ao serviço Detecção Facial é limitado com base em critérios de elegibilidade e uso para dar suporte aos nossos princípios de IA Responsável. O serviço de Detecção Facial só está disponível para clientes e parceiros gerenciados da Microsoft. Use o Formulário de admissão de reconhecimento facial para solicitar acesso. Para concluir as etapas deste início rápido, solicite a Identificação Facial [API de Detecção Facial] (comparação 1:N ou 1:1) com detecção de vida facial opcional para controle de acesso sem toque caso de uso. Para obter mais informações, consulte a página Acesso limitado facial.

Use o portal do Microsoft Foundry para detectar rostos em uma imagem.

Prerequisites

Setup

Acesse o portal do Microsoft Foundry e entre com sua conta do Azure que tem o recurso Foundry.

Selecione Microsoft Foundry no canto superior esquerdo, role para baixo e selecione Explorar Ferramentas do Foundry e selecione Vision + Document. Na guia Rosto, selecione Detectar rostos em uma imagem.

Detectar faces

Selecione uma imagem no conjunto disponível ou carregue uma imagem própria. O serviço detectará rostos na imagem e retornará as coordenadas da caixa delimitadora, as coordenadas de pontos de referência do rosto e as características. Selecione a guia JSON para ver a resposta JSON completa da API.

Próximas etapas

Neste início rápido, você fez a detecção facial usando o portal do Microsoft Foundry. Em seguida, saiba mais sobre os diferentes modelos de detecção facial e como especificar o modelo certo para o caso de uso.

Especificar uma versão de modelo de detecção facial

Comece a usar o reconhecimento facial usando a biblioteca de clientes de Detecção Facial para .NET. O serviço de Detecção Facial da IA do Azure fornece acesso a algoritmos avançados para detectar e reconhecer rostos humanos em imagens. Siga estas etapas para instalar o pacote e experimente o código de exemplo para realizar a identificação básica de rostos usando imagens remotas.

Documentação de referência | Código-fonte da biblioteca | Pacote (NuGet) | Exemplos

Prerequisites

Criar variáveis de ambiente

Nesse exemplo, grave as credenciais em variáveis de ambiente no computador local que executa o aplicativo.

Vá para o portal do Azure. Se o recurso criado na seção Pré-requisitos tiver sido implantado com êxito, selecione Ir para o recurso em Próximas etapas. Encontre a chave e o ponto de extremidade em Gerenciamento de Recursos na página Chaves e Ponto de Extremidade do recurso de Detecção Facial. Sua chave de recurso não é igual à sua ID de assinatura do Azure.

Para definir a variável de ambiente da sua chave e ponto de extremidade, abra uma janela do console e siga as instruções a seguir para o seu SO e ambiente de desenvolvimento.

  • Para definir a variável de ambiente FACE_APIKEY, substitua <your_key> por uma das chaves do recurso.
  • Para definir a variável de ambiente FACE_ENDPOINT, substitua <your_endpoint> pelo ponto de extremidade do recurso.

Important

Use as chaves de API com cautela. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente. Se você usar uma chave de API, armazene-a com segurança no Azure Key Vault. Para obter mais informações sobre como usar chaves de API com segurança em seus aplicativos, confira Chaves de API com o Azure Key Vault.

Para obter mais informações sobre segurança dos serviços de IA, confira Autenticar solicitações para os serviços de IA do Azure.

setx FACE_APIKEY <your_key>

setx FACE_ENDPOINT <your_endpoint>

Depois de adicionar as variáveis de ambiente, talvez seja necessário reiniciar todos os programas em execução que lerão as variáveis de ambiente, incluindo a janela do console.

Identificar e verificar rostos

  1. Criar um aplicativo em C#.

    Usando o Visual Studio, crie um aplicativo de console .NET.

    Instalar a biblioteca de clientes

    Depois de criar um projeto, instale a biblioteca de clientes clicando com o botão direito do mouse no projeto em Gerenciador de Soluções e selecionando Gerenciar pacotes NuGet. No gerenciador de pacotes que abrir, selecione Procurar, marque Incluir pré-lançamento e pesquise por Azure.AI.Vision.Face. Selecione a última versão e, em seguida, selecione Instalar.

  2. Adicione o código a seguir ao arquivo Program.cs, substituindo o código existente.

    Note

    Se você não tiver recebido acesso ao serviço de Detecção Facial por meio do formulário de inscrição, algumas dessas funções não funcionarão.

    using Azure;
using Azure.AI.Vision.Face;

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

        // URL path for the images.
        const string ImageBaseUrl = "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 SubscriptionKey = 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 RecognitionModel4 = FaceRecognitionModel.Recognition04;

            // Authenticate.
            FaceClient client = Authenticate(Endpoint, SubscriptionKey);

            // Identify - recognize a face(s) in a large person group (a large person group is created in this example).
            IdentifyInLargePersonGroup(client, ImageBaseUrl, RecognitionModel4).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 recognitionModel)
        {
            // Detect faces from image URL.
            var response = await faceClient.DetectAsync(new Uri(url), FaceDetectionModel.Detection03, recognitionModel, true, [FaceAttributeType.QualityForRecognition]);
            IReadOnlyList<FaceDetectionResult> detectedFaces = response.Value;
            List<FaceDetectionResult> sufficientQualityFaces = new List<FaceDetectionResult>();
            foreach (FaceDetectionResult detectedFace in detectedFaces)
            {
                QualityForRecognition? 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}).");
            LargePersonGroupClient largePersonGroupClient = new FaceAdministrationClient(new Uri(Endpoint), new AzureKeyCredential(SubscriptionKey)).GetLargePersonGroupClient(LargePersonGroupId);
            await largePersonGroupClient.CreateAsync(LargePersonGroupId, recognitionModel: recognitionModel);
            // The similar faces will be grouped into a single large person group person.
            foreach (string groupedFace in personDictionary.Keys)
            {
                // Limit TPS
                await Task.Delay(250);
                var createPersonResponse = await largePersonGroupClient.CreatePersonAsync(groupedFace);
                Guid personId = createPersonResponse.Value.PersonId;
                Console.WriteLine($"Create a person group person '{groupedFace}'.");

                // Add face to the large person group person.
                foreach (string similarImage in personDictionary[groupedFace])
                {
                    Console.WriteLine($"Check whether image is of sufficient quality for recognition");
                    var detectResponse = await client.DetectAsync(new Uri($"{url}{similarImage}"), FaceDetectionModel.Detection03, recognitionModel, false, [FaceAttributeType.QualityForRecognition]);
                    IReadOnlyList<FaceDetectionResult> facesInImage = detectResponse.Value;
                    bool sufficientQuality = true;
                    foreach (FaceDetectionResult face in facesInImage)
                    {
                        QualityForRecognition? faceQualityForRecognition = face.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 (facesInImage.Count != 1)
                    {
                        continue;
                    }

                    // add face to the large person group
                    Console.WriteLine($"Add face to the person group person({groupedFace}) from image `{similarImage}`");
                    await largePersonGroupClient.AddFaceAsync(personId, new Uri($"{url}{similarImage}"), detectionModel: FaceDetectionModel.Detection03);
                }
            }

            // Start to train the large person group.
            Console.WriteLine();
            Console.WriteLine($"Train person group {LargePersonGroupId}.");
            Operation operation = await largePersonGroupClient.TrainAsync(WaitUntil.Completed);

            // Wait until the training is completed.
            await operation.WaitForCompletionResponseAsync();
            Console.WriteLine("Training status: succeeded.");
            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 (FaceDetectionResult detectedFace in detectedFaces) { sourceFaceIds.Add(detectedFace.FaceId.Value); }

            // Identify the faces in a large person group.
            var identifyResponse = await client.IdentifyFromLargePersonGroupAsync(sourceFaceIds, LargePersonGroupId);
            IReadOnlyList<FaceIdentificationResult> identifyResults = identifyResponse.Value;
            foreach (FaceIdentificationResult identifyResult in identifyResults)
            {
                if (identifyResult.Candidates.Count == 0)
                {
                    Console.WriteLine($"No person is identified for the face in: {sourceImageFileName} - {identifyResult.FaceId},");
                    continue;
                }

                FaceIdentificationCandidate candidate = identifyResult.Candidates.First();
                var getPersonResponse = await largePersonGroupClient.GetPersonAsync(candidate.PersonId);
                string personName = getPersonResponse.Value.Name;
                Console.WriteLine($"Person '{personName}' is identified for the face in: {sourceImageFileName} - {identifyResult.FaceId}," + $" confidence: {candidate.Confidence}.");

                var verifyResponse = await client.VerifyFromLargePersonGroupAsync(identifyResult.FaceId, LargePersonGroupId, candidate.PersonId);
                FaceVerificationResult verifyResult = verifyResponse.Value;
                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 largePersonGroupClient.DeleteAsync();
            Console.WriteLine($"Deleted the person group {LargePersonGroupId}.");
            Console.WriteLine();
        }
    }
}

  3. Executar o aplicativo

    Execute o aplicativo selecionando o botão Depurar na parte superior da janela do IDE.

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.

Tip

A API de Detecção Facial é executada em um conjunto de modelos predefinidos que estão estáticos por natureza (o desempenho do modelo não regredirá nem será aprimorado conforme o serviço for executado). Os resultados que o modelo produz poderão ser alterados se a Microsoft atualizar o back-end do modelo sem fazer a migração para uma versão totalmente nova do modelo. Para aproveitar uma versão mais recente de um modelo, você pode treinar novamente seu PersonGroup, especificando o modelo mais recente como um parâmetro com as mesmas imagens de registro.

Limpar os recursos

Se você quiser limpar e remover uma assinatura do Foundry Tools, poderá excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Próximas etapas

Neste guia de início rápido, você aprendeu a usar a biblioteca de clientes de Detecção Facial para .NET a fim de realizar a identificação básica de rostos. Em seguida, saiba mais sobre os diferentes modelos de detecção facial e como especificar o modelo certo para o caso de uso.

Especificar uma versão de modelo de detecção facial

Comece a usar o reconhecimento facial usando a biblioteca de clientes de Detecção Facial para Python. Siga essas etapas para instalar o pacote e testar o código de exemplo para tarefas básicas. O serviço de Detecção Facial fornece acesso a algoritmos avançados para detectar e reconhecer rostos humanos em imagens. Siga estas etapas para instalar o pacote e experimente o código de exemplo para realizar a identificação básica de rostos usando imagens remotas.

Documentação de referência | Código-fonte da biblioteca | Pacote (PiPy) | Amostras

Prerequisites

  • Assinatura do Azure – Criar uma gratuitamente
  • Python 3.x
    • A instalação do Python deve incluir o pip. Você pode executar pip --version na linha de comando para verificar se o pip está instalado. Instale a versão mais recente do Python para obter o pip.
  • Depois de obter sua assinatura do Azure, crie um recurso da Detecção Facial no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
    • Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API de Detecção Facial.
    • Use o tipo de preço gratuito (F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.

Criar variáveis de ambiente

Nesse exemplo, grave as credenciais em variáveis de ambiente no computador local que executa o aplicativo.

Vá para o portal do Azure. Se o recurso criado na seção Pré-requisitos tiver sido implantado com êxito, selecione Ir para o recurso em Próximas etapas. Encontre a chave e o ponto de extremidade em Gerenciamento de Recursos na página Chaves e Ponto de Extremidade do recurso de Detecção Facial. Sua chave de recurso não é igual à sua ID de assinatura do Azure.

Para definir a variável de ambiente da sua chave e ponto de extremidade, abra uma janela do console e siga as instruções a seguir para o seu SO e ambiente de desenvolvimento.

  • Para definir a variável de ambiente FACE_APIKEY, substitua <your_key> por uma das chaves do recurso.
  • Para definir a variável de ambiente FACE_ENDPOINT, substitua <your_endpoint> pelo ponto de extremidade do recurso.

Important

Use as chaves de API com cautela. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente. Se você usar uma chave de API, armazene-a com segurança no Azure Key Vault. Para obter mais informações sobre como usar chaves de API com segurança em seus aplicativos, confira Chaves de API com o Azure Key Vault.

Para obter mais informações sobre segurança dos serviços de IA, confira Autenticar solicitações para os serviços de IA do Azure.

setx FACE_APIKEY <your_key>

setx FACE_ENDPOINT <your_endpoint>

Depois de adicionar as variáveis de ambiente, talvez seja necessário reiniciar todos os programas em execução que lerão as variáveis de ambiente, incluindo a janela do console.

Identificar e verificar rostos

  1. Instalar a biblioteca de clientes

    Depois de instalar o Python, você pode instalar a biblioteca de clientes com:

    pip install --upgrade azure-ai-vision-face

  2. Criar um novo aplicativo Python

    Criar um novo script Python — quickstart-file.py, por exemplo. Em seguida, abra-o no seu editor ou IDE preferido e cole o código a seguir.

    Note

    Se você não tiver recebido acesso ao serviço Face usando o formulário de solicitação, algumas dessas funções não funcionarão.

    import os
import time
import uuid

from azure.core.credentials import AzureKeyCredential
from azure.ai.vision.face import FaceAdministrationClient, 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)

# Create an authenticated FaceClient.
with FaceAdministrationClient(endpoint=ENDPOINT, credential=AzureKeyCredential(KEY)) as face_admin_client, \
     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)
    face_admin_client.large_person_group.create(
        large_person_group_id=LARGE_PERSON_GROUP_ID,
        name=LARGE_PERSON_GROUP_ID,
        recognition_model=FaceRecognitionModel.RECOGNITION04,
    )

    # Define woman friend
    woman = face_admin_client.large_person_group.create_person(
        large_person_group_id=LARGE_PERSON_GROUP_ID,
        name="Woman",
    )
    # Define man friend
    man = face_admin_client.large_person_group.create_person(
        large_person_group_id=LARGE_PERSON_GROUP_ID,
        name="Man",
    )
    # Define child friend
    child = face_admin_client.large_person_group.create_person(
        large_person_group_id=LARGE_PERSON_GROUP_ID,
        name="Child",
    )

    '''
    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",
        "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Mom2.jpg",
    ]
    man_images = [
        "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Dad1.jpg",
        "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Dad2.jpg",
    ]
    child_images = [
        "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Son1.jpg",
        "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Son2.jpg",
    ]

    # Add to woman person
    for image in woman_images:
        # Check if the image is of sufficent quality for recognition.
        sufficient_quality = True
        detected_faces = face_client.detect_from_url(
            url=image,
            detection_model=FaceDetectionModel.DETECTION03,
            recognition_model=FaceRecognitionModel.RECOGNITION04,
            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:
                sufficient_quality = False
                break

        if not sufficient_quality:
            continue

        if len(detected_faces) != 1:
            continue

        face_admin_client.large_person_group.add_face_from_url(
            large_person_group_id=LARGE_PERSON_GROUP_ID,
            person_id=woman.person_id,
            url=image,
            detection_model=FaceDetectionModel.DETECTION03,
        )
        print(f"face {face.face_id} added to person {woman.person_id}")


    # Add to man person
    for image in man_images:
        # Check if the image is of sufficent quality for recognition.
        sufficient_quality = True
        detected_faces = face_client.detect_from_url(
            url=image,
            detection_model=FaceDetectionModel.DETECTION03,
            recognition_model=FaceRecognitionModel.RECOGNITION04,
            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:
                sufficient_quality = False
                break

        if not sufficient_quality:
            continue

        if len(detected_faces) != 1:
            continue

        face_admin_client.large_person_group.add_face_from_url(
            large_person_group_id=LARGE_PERSON_GROUP_ID,
            person_id=man.person_id,
            url=image,
            detection_model=FaceDetectionModel.DETECTION03,
        )
        print(f"face {face.face_id} added to person {man.person_id}")

    # Add to child person
    for image in child_images:
        # Check if the image is of sufficent quality for recognition.
        sufficient_quality = True
        detected_faces = face_client.detect_from_url(
            url=image,
            detection_model=FaceDetectionModel.DETECTION03,
            recognition_model=FaceRecognitionModel.RECOGNITION04,
            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:
                sufficient_quality = False
                break
        if not sufficient_quality:
            continue

        if len(detected_faces) != 1:
            continue

        face_admin_client.large_person_group.add_face_from_url(
            large_person_group_id=LARGE_PERSON_GROUP_ID,
            person_id=child.person_id,
            url=image,
            detection_model=FaceDetectionModel.DETECTION03,
        )
        print(f"face {face.face_id} added to person {child.person_id}")

    '''
    Train LargePersonGroup
    '''
    # Train the large person group and set the polling interval to 5s
    print(f"Train the person group {LARGE_PERSON_GROUP_ID}")
    poller = face_admin_client.large_person_group.begin_train(
        large_person_group_id=LARGE_PERSON_GROUP_ID,
        polling_interval=5,
    )

    poller.wait()
    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"

    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.DETECTION03,
        recognition_model=FaceRecognitionModel.RECOGNITION04,
        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
    identify_results = face_client.identify_from_large_person_group(
        face_ids=face_ids,
        large_person_group_id=LARGE_PERSON_GROUP_ID,
    )
    print("Identifying faces in image")
    for identify_result in identify_results:
        if identify_result.candidates:
            print(f"Person is identified for face ID {identify_result.face_id} in image, with a confidence of "
                  f"{identify_result.candidates[0].confidence}.")  # Get topmost confidence score

            # Verify faces
            verify_result = face_client.verify_from_large_person_group(
                face_id=identify_result.face_id,
                large_person_group_id=LARGE_PERSON_GROUP_ID,
                person_id=identify_result.candidates[0].person_id,
            )
            print(f"verification result: {verify_result.is_identical}. confidence: {verify_result.confidence}")
        else:
            print(f"No person identified for face ID {identify_result.face_id} in image.")

    print()

    # Delete the large person group
    face_admin_client.large_person_group.delete(LARGE_PERSON_GROUP_ID)
    print(f"The person group {LARGE_PERSON_GROUP_ID} is deleted.")

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

  3. Execute o aplicativo de reconhecimento facial no diretório do aplicativo com o comando python.

    python quickstart-file.py

    Tip

    A API de Detecção Facial é executada em um conjunto de modelos predefinidos que estão estáticos por natureza (o desempenho do modelo não regredirá nem será aprimorado conforme o serviço for executado). Os resultados que o modelo produz poderão ser alterados se a Microsoft atualizar o back-end do modelo sem fazer a migração para uma versão totalmente nova do modelo. Para aproveitar uma versão mais recente de um modelo, você pode treinar novamente seu PersonGroup, especificando o modelo mais recente como um parâmetro com as mesmas imagens de registro.

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.

Limpar os recursos

Se você quiser limpar e remover uma assinatura do Foundry Tools, poderá excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Próximas etapas

Neste guia de início rápido, você aprendeu a usar a biblioteca de clientes de Detecção Facial para Python a fim de realizar a identificação básica de rostos. Em seguida, saiba mais sobre os diferentes modelos de detecção facial e como especificar o modelo certo para o caso de uso.

Especificar uma versão de modelo de detecção facial

Introdução ao reconhecimento facial usando a biblioteca de clientes de Detecção Facial para Java. Siga essas etapas para instalar o pacote e testar o código de exemplo para tarefas básicas. O serviço de Detecção Facial fornece acesso a algoritmos avançados para detectar e reconhecer rostos humanos em imagens. Siga estas etapas para instalar o pacote e experimente o código de exemplo para realizar a identificação básica de rostos usando imagens remotas.

Documentação de referência | Código-fonte da biblioteca | Pacote (Maven) | Exemplos

Prerequisites

  • Assinatura do Azure – Criar uma gratuitamente
  • A versão atual do JDK (Java Development Kit)
  • Apache Maven instalado. No Linux, instale nos repositórios de distribuição, se disponível.
  • Depois de obter sua assinatura do Azure, crie um recurso da Detecção Facial no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
    • Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API de Detecção Facial.
    • Use o tipo de preço gratuito (F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.

Criar variáveis de ambiente

Nesse exemplo, grave as credenciais em variáveis de ambiente no computador local que executa o aplicativo.

Vá para o portal do Azure. Se o recurso criado na seção Pré-requisitos tiver sido implantado com êxito, selecione Ir para o recurso em Próximas etapas. Encontre a chave e o ponto de extremidade em Gerenciamento de Recursos na página Chaves e Ponto de Extremidade do recurso de Detecção Facial. Sua chave de recurso não é igual à sua ID de assinatura do Azure.

Para definir a variável de ambiente da sua chave e ponto de extremidade, abra uma janela do console e siga as instruções a seguir para o seu SO e ambiente de desenvolvimento.

  • Para definir a variável de ambiente FACE_APIKEY, substitua <your_key> por uma das chaves do recurso.
  • Para definir a variável de ambiente FACE_ENDPOINT, substitua <your_endpoint> pelo ponto de extremidade do recurso.

Important

Use as chaves de API com cautela. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente. Se você usar uma chave de API, armazene-a com segurança no Azure Key Vault. Para obter mais informações sobre como usar chaves de API com segurança em seus aplicativos, confira Chaves de API com o Azure Key Vault.

Para obter mais informações sobre segurança dos serviços de IA, confira Autenticar solicitações para os serviços de IA do Azure.

setx FACE_APIKEY <your_key>

setx FACE_ENDPOINT <your_endpoint>

Depois de adicionar as variáveis de ambiente, talvez seja necessário reiniciar todos os programas em execução que lerão as variáveis de ambiente, incluindo a janela do console.

Identificar e verificar rostos

  1. Instalar a biblioteca de clientes

    Abra uma janela do console e crie uma nova pasta para seu aplicativo de início rápido. Copie o conteúdo a seguir para um novo arquivo. Salve o arquivo como pom.xml no diretório do projeto:

    <project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>my-application-name</artifactId>
  <version>1.0.0</version>
  <dependencies>
    <!-- https://mvnrepository.com/artifact/com.azure/azure-ai-vision-face -->
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-ai-vision-face</artifactId>
      <version>1.0.0-beta.2</version>
    </dependency>
  </dependencies>
</project>

    Instale o SDK e as dependências executando o seguinte no diretório do projeto:

    mvn clean dependency:copy-dependencies

  2. Criar um aplicativo Java

    Crie um arquivo chamado Quickstart.java, abra-o em um editor de texto e cole o seguinte código:

    Note

    Se você não tiver recebido acesso ao serviço Face usando o formulário de solicitação, algumas dessas funções não funcionarão.

    import java.util.Arrays;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
import java.util.UUID;

import com.azure.ai.vision.face.FaceClient;
import com.azure.ai.vision.face.FaceClientBuilder;
import com.azure.ai.vision.face.administration.FaceAdministrationClient;
import com.azure.ai.vision.face.administration.FaceAdministrationClientBuilder;
import com.azure.ai.vision.face.administration.LargePersonGroupClient;
import com.azure.ai.vision.face.models.DetectOptions;
import com.azure.ai.vision.face.models.FaceAttributeType;
import com.azure.ai.vision.face.models.FaceDetectionModel;
import com.azure.ai.vision.face.models.FaceDetectionResult;
import com.azure.ai.vision.face.models.FaceIdentificationCandidate;
import com.azure.ai.vision.face.models.FaceIdentificationResult;
import com.azure.ai.vision.face.models.FaceRecognitionModel;
import com.azure.ai.vision.face.models.FaceTrainingResult;
import com.azure.ai.vision.face.models.FaceVerificationResult;
import com.azure.ai.vision.face.models.QualityForRecognition;
import com.azure.core.credential.KeyCredential;
import com.azure.core.util.polling.SyncPoller;

public class Quickstart {
    // LARGE_PERSON_GROUP_ID should be all lowercase and alphanumeric. For example, 'mygroupname' (dashes are OK).
    private static final String LARGE_PERSON_GROUP_ID = UUID.randomUUID().toString();

    // URL path for the images.
    private static final 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.
    private static final String SUBSCRIPTION_KEY = System.getenv("FACE_APIKEY");
    private static final String ENDPOINT = System.getenv("FACE_ENDPOINT");

    public static void main(String[] args) throws Exception {
        // 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.RECOGNITION_04;

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

        System.out.println("End of quickstart.");
    }

    /*
     *	AUTHENTICATE
     *	Uses subscription key and region to create a client.
     */
    public static FaceClient authenticate(String endpoint, String key) {
        return new FaceClientBuilder().endpoint(endpoint).credential(new KeyCredential(key)).buildClient();
    }


    // Detect faces from image url for recognition purposes. This is a helper method for other functions in this quickstart.
    // Parameter `returnFaceId` of `DetectOptions` 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 List<FaceDetectionResult> detectFaceRecognize(FaceClient faceClient, String url, FaceRecognitionModel recognitionModel) {
        // Detect faces from image URL.
        DetectOptions options = new DetectOptions(FaceDetectionModel.DETECTION_03, recognitionModel, true).setReturnFaceAttributes(Arrays.asList(FaceAttributeType.QUALITY_FOR_RECOGNITION));
        List<FaceDetectionResult> detectedFaces = faceClient.detect(url, options);
        List<FaceDetectionResult> sufficientQualityFaces = detectedFaces.stream().filter(f -> f.getFaceAttributes().getQualityForRecognition() != QualityForRecognition.LOW).collect(Collectors.toList());
        System.out.println(detectedFaces.size() + " face(s) with " + sufficientQualityFaces.size() + " having sufficient quality for recognition.");

        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 void identifyInLargePersonGroup(FaceClient client, String url, FaceRecognitionModel recognitionModel) throws Exception {
        System.out.println("========IDENTIFY FACES========");
        System.out.println();

        // Create a dictionary for all your images, grouping similar ones under the same key.
        Map<String, String[]> personDictionary = new LinkedHashMap<String, String[]>();
        personDictionary.put("Family1-Dad", new String[]{"Family1-Dad1.jpg", "Family1-Dad2.jpg"});
        personDictionary.put("Family1-Mom", new String[]{"Family1-Mom1.jpg", "Family1-Mom2.jpg"});
        personDictionary.put("Family1-Son", new String[]{"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.
        System.out.println("Create a person group (" + LARGE_PERSON_GROUP_ID + ").");
        FaceAdministrationClient faceAdministrationClient = new FaceAdministrationClientBuilder().endpoint(ENDPOINT).credential(new KeyCredential(SUBSCRIPTION_KEY)).buildClient();
        LargePersonGroupClient largePersonGroupClient = faceAdministrationClient.getLargePersonGroupClient(LARGE_PERSON_GROUP_ID);
        largePersonGroupClient.create(LARGE_PERSON_GROUP_ID, null, recognitionModel);
        // The similar faces will be grouped into a single large person group person.
        for (String groupedFace : personDictionary.keySet()) {
            // Limit TPS
            Thread.sleep(250);
            String personId = largePersonGroupClient.createPerson(groupedFace).getPersonId();
            System.out.println("Create a person group person '" + groupedFace + "'.");

            // Add face to the large person group person.
            for (String similarImage : personDictionary.get(groupedFace)) {
                System.out.println("Check whether image is of sufficient quality for recognition");
                DetectOptions options = new DetectOptions(FaceDetectionModel.DETECTION_03, recognitionModel, false).setReturnFaceAttributes(Arrays.asList(FaceAttributeType.QUALITY_FOR_RECOGNITION));
                List<FaceDetectionResult> facesInImage = client.detect(url + similarImage, options);
                if (facesInImage.stream().anyMatch(f -> f.getFaceAttributes().getQualityForRecognition() != QualityForRecognition.HIGH)) {
                    continue;
                }

                if (facesInImage.size() != 1) {
                    continue;
                }

                // add face to the large person group
                System.out.println("Add face to the person group person(" + groupedFace + ") from image `" + similarImage + "`");
                largePersonGroupClient.addFace(personId, url + similarImage, null, FaceDetectionModel.DETECTION_03, null);
            }
        }

        // Start to train the large person group.
        System.out.println();
        System.out.println("Train person group " + LARGE_PERSON_GROUP_ID + ".");
        SyncPoller<FaceTrainingResult, Void> poller = largePersonGroupClient.beginTrain();

        // Wait until the training is completed.
        poller.waitForCompletion();
        System.out.println("Training status: succeeded.");
        System.out.println();

        System.out.println("Pausing for 60 seconds to avoid triggering rate limit on free account...");
        Thread.sleep(60000);

        // Detect faces from source image url.
        List<FaceDetectionResult> detectedFaces = detectFaceRecognize(client, url + sourceImageFileName, recognitionModel);
        // Add detected faceId to sourceFaceIds.
        List<String> sourceFaceIds = detectedFaces.stream().map(FaceDetectionResult::getFaceId).collect(Collectors.toList());

        // Identify the faces in a large person group.
        List<FaceIdentificationResult> identifyResults = client.identifyFromLargePersonGroup(sourceFaceIds, LARGE_PERSON_GROUP_ID);

        for (FaceIdentificationResult identifyResult : identifyResults) {
            if (identifyResult.getCandidates().isEmpty()) {
                System.out.println("No person is identified for the face in: " + sourceImageFileName + " - " + identifyResult.getFaceId() + ".");
                continue;
            }

            FaceIdentificationCandidate candidate = identifyResult.getCandidates().stream().findFirst().orElseThrow();
            String personName = largePersonGroupClient.getPerson(candidate.getPersonId()).getName();
            System.out.println("Person '" + personName + "' is identified for the face in: " + sourceImageFileName + " - " + identifyResult.getFaceId() + ", confidence: " + candidate.getConfidence() + ".");

            FaceVerificationResult verifyResult = client.verifyFromLargePersonGroup(identifyResult.getFaceId(), LARGE_PERSON_GROUP_ID, candidate.getPersonId());
            System.out.println("Verification result: is a match? " + verifyResult.isIdentical() + ". confidence: " + verifyResult.getConfidence());
        }
        System.out.println();

        // Delete large person group.
        System.out.println("========DELETE PERSON GROUP========");
        System.out.println();
        largePersonGroupClient.delete();
        System.out.println("Deleted the person group " + LARGE_PERSON_GROUP_ID + ".");
        System.out.println();
    }
}

  3. Execute seu aplicativo de reconhecimento facial no diretório do aplicativo com os comandos javac e java.

    javac -cp target\dependency\* Quickstart.java
java -cp .;target\dependency\* Quickstart

Output

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

Create a person group (3761e61a-16b2-4503-ad29-ed34c58ba676).
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 3761e61a-16b2-4503-ad29-ed34c58ba676.
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.
Person 'Family1-Dad' is identified for the face in: identification1.jpg - d7995b34-1b72-47fe-82b6-e9877ed2578d, confidence: 0.96807.
Verification result: is a match? true. confidence: 0.96807
Person 'Family1-Mom' is identified for the face in: identification1.jpg - 844da0ed-4890-4bbf-a531-e638797f96fc, confidence: 0.96902.
Verification result: is a match? true. confidence: 0.96902
No person is identified for the face in: identification1.jpg - c543159a-57f3-4872-83ce-2d4a733d71c9.
Person 'Family1-Son' is identified for the face in: identification1.jpg - 414fac6c-7381-4dba-9c8b-fd26d52e879b, confidence: 0.9281.
Verification result: is a match? true. confidence: 0.9281

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

Deleted the person group 3761e61a-16b2-4503-ad29-ed34c58ba676.

End of quickstart.

Limpar os recursos

Se você quiser limpar e remover uma assinatura do Foundry Tools, poderá excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Próximas etapas

Neste início rápido, você aprendeu a usar a biblioteca de clientes de Detecção Facial para Java para fazer a identificação facial básica. Em seguida, saiba mais sobre os diferentes modelos de detecção facial e como especificar o modelo certo para o caso de uso.

Especificar uma versão de modelo de detecção facial

Comece a usar o reconhecimento facial usando a biblioteca de clientes de Detecção Facial para JavaScript. O serviço de Detecção Facial fornece acesso a algoritmos avançados para detectar e reconhecer rostos humanos em imagens. Siga estas etapas para instalar o pacote e experimente o código de exemplo para realizar a identificação básica de rostos usando imagens remotas.

Documentação de referência | Código-fonte da biblioteca | Pacote (npm) | Exemplos

Prerequisites

Criar variáveis de ambiente

Nesse exemplo, grave as credenciais em variáveis de ambiente no computador local que executa o aplicativo.

Vá para o portal do Azure. Se o recurso criado na seção Pré-requisitos tiver sido implantado com êxito, selecione Ir para o recurso em Próximas etapas. Encontre a chave e o ponto de extremidade em Gerenciamento de Recursos na página Chaves e Ponto de Extremidade do recurso de Detecção Facial. Sua chave de recurso não é igual à sua ID de assinatura do Azure.

Para definir a variável de ambiente da sua chave e ponto de extremidade, abra uma janela do console e siga as instruções a seguir para o seu SO e ambiente de desenvolvimento.

  • Para definir a variável de ambiente FACE_APIKEY, substitua <your_key> por uma das chaves do recurso.
  • Para definir a variável de ambiente FACE_ENDPOINT, substitua <your_endpoint> pelo ponto de extremidade do recurso.

Important

Use as chaves de API com cautela. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente. Se você usar uma chave de API, armazene-a com segurança no Azure Key Vault. Para obter mais informações sobre como usar chaves de API com segurança em seus aplicativos, confira Chaves de API com o Azure Key Vault.

Para obter mais informações sobre segurança dos serviços de IA, confira Autenticar solicitações para os serviços de IA do Azure.

setx FACE_APIKEY <your_key>

setx FACE_ENDPOINT <your_endpoint>

Depois de adicionar as variáveis de ambiente, talvez seja necessário reiniciar todos os programas em execução que lerão as variáveis de ambiente, incluindo a janela do console.

Identificar e verificar rostos

  1. Criar um novo aplicativo do Node.js

    Em uma janela de console (como cmd, PowerShell ou Bash), crie um novo diretório para seu aplicativo e navegue até ele.

    mkdir myapp && cd myapp

    Execute o comando npm init para criar um aplicativo do Node com um arquivo package.json.

    npm init

  2. Instalar os pacotes npm @azure-rest/ai-vision-face:

    npm install @azure-rest/ai-vision-face

    O arquivo package.json do seu aplicativo é atualizado com as dependências.

  3. Crie um arquivo chamado index.js, abra-o em um editor de texto, cole o código a seguir e salve-o na pasta que contém o aplicativo.

    Note

    Se você não tiver recebido acesso ao serviço Face usando o formulário de solicitação, algumas dessas funções não funcionarão.

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

  4. Execute o aplicativo com o comando node no seu arquivo de início rápido.

    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.

Limpar os recursos

Se você quiser limpar e remover uma assinatura do Foundry Tools, poderá excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Próximas etapas

Neste guia de início rápido, você aprendeu a usar a biblioteca de clientes de Detecção Facial para JavaScript a fim de realizar a identificação básica de rostos. Em seguida, saiba mais sobre os diferentes modelos de detecção facial e como especificar o modelo certo para o caso de uso.

Especificar uma versão de modelo de detecção facial

Introdução ao reconhecimento facial usando a biblioteca de clientes de detecção facial para TypeScript. Siga essas etapas para instalar o pacote e testar o código de exemplo para tarefas básicas. O serviço de Detecção Facial fornece acesso a algoritmos avançados para detectar e reconhecer rostos humanos em imagens. Siga estas etapas para instalar o pacote e experimente o código de exemplo para realizar a identificação básica de rostos usando imagens remotas.

Documentação de referência | Código-fonte da biblioteca | Pacote (npm) | Exemplos

Prerequisites

  • Assinatura do Azure – Criar uma gratuitamente
  • Node.js LTS
  • TypeScript
  • Código do Visual Studio
  • Depois de obter sua assinatura do Azure, Crie um recurso da Detecção Facial no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
    • Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API de Detecção Facial.
    • Use o tipo de preço gratuito (F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.

Configurar o ambiente de desenvolvimento local

  1. Crie um novo diretório para seu projeto e navegue até ele:

    mkdir face-identification
cd face-identification
code .

  2. Crie um novo pacote para módulos ESM no diretório do projeto:

    npm init -y
npm pkg set type=module

  3. Instale os pacotes necessários:

    npm install @azure-rest/ai-vision-face

  4. Instalar dependências de desenvolvimento:

    npm install typescript @types/node --save-dev

  5. Crie um tsconfig.json arquivo no diretório do projeto:

    {
  "compilerOptions": {
    "target": "es2022",
    "module": "esnext",
    "moduleResolution": "bundler",
    "rootDir": "./src",
    "outDir": "./dist/",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "declaration": true,
    "sourceMap": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "allowSyntheticDefaultImports": true,
    "verbatimModuleSyntax": false
  },
  "include": [
    "src/**/*.ts"
  ],
  "exclude": [
    "node_modules/**/*",
    "**/*.spec.ts"
  ]
}

  6. Atualize package.json para incluir um script para a criação de arquivos TypeScript:

    "scripts": {
  "build": "tsc",
  "start": "node dist/index.js"
}

  7. Crie uma resources pasta e adicione imagens de exemplo a ela.

  8. Crie um src diretório para o código TypeScript.

Nesse exemplo, grave as credenciais em variáveis de ambiente no computador local que executa o aplicativo.

Vá para o portal do Azure. Se o recurso criado na seção Pré-requisitos tiver sido implantado com êxito, selecione Ir para o recurso em Próximas etapas. Encontre a chave e o ponto de extremidade em Gerenciamento de Recursos na página Chaves e Ponto de Extremidade do recurso de Detecção Facial. Sua chave de recurso não é igual à sua ID de assinatura do Azure.

Para definir a variável de ambiente da sua chave e ponto de extremidade, abra uma janela do console e siga as instruções a seguir para o seu SO e ambiente de desenvolvimento.

  • Para definir a variável de ambiente FACE_APIKEY, substitua <your_key> por uma das chaves do recurso.
  • Para definir a variável de ambiente FACE_ENDPOINT, substitua <your_endpoint> pelo ponto de extremidade do recurso.

Important

Use as chaves de API com cautela. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente. Se você usar uma chave de API, armazene-a com segurança no Azure Key Vault. Para obter mais informações sobre como usar chaves de API com segurança em seus aplicativos, confira Chaves de API com o Azure Key Vault.

Para obter mais informações sobre segurança dos serviços de IA, confira Autenticar solicitações para os serviços de IA do Azure.

setx FACE_APIKEY <your_key>

setx FACE_ENDPOINT <your_endpoint>

Depois de adicionar as variáveis de ambiente, talvez seja necessário reiniciar todos os programas em execução que lerão as variáveis de ambiente, incluindo a janela do console.

Identificar e verificar rostos

Crie um novo arquivo em seu src diretório index.tse cole o código a seguir. Substitua os caminhos das imagens e os nomes dos grupos/pessoas conforme necessário.

Note

Se você não tiver recebido acesso ao serviço Face usando o formulário de solicitação, algumas dessas funções não funcionarão.

import { randomUUID } from "crypto";
import { AzureKeyCredential } from "@azure/core-auth";
import createFaceClient, {
  getLongRunningPoller,
  isUnexpected,
} from "@azure-rest/ai-vision-face";
import "dotenv/config";

/**
 * This sample demonstrates how to identify and verify faces using Azure Face API.
 *
 * @summary Face identification and verification.
 */

const sleep = (ms: number) => 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========\n");

  // Create a dictionary for all your images, grouping similar ones under the same key.
  const personDictionary: Record<string, string[]> = {
    "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}`);
  const createGroupResponse = await client
    .path("/largepersongroups/{largePersonGroupId}", largePersonGroupId)
    .put({
      body: {
        name: largePersonGroupId,
        recognitionModel: "recognition_04",
      },
    });
  if (isUnexpected(createGroupResponse)) {
    throw new Error(createGroupResponse.body.error.message);
  }

  // Add faces to person group.
  console.log("Adding faces to person group...");
  await Promise.all(
    Object.keys(personDictionary).map(async (name) => {
      console.log(`Create a persongroup person: ${name}`);
      const createPersonResponse = await client
        .path("/largepersongroups/{largePersonGroupId}/persons", largePersonGroupId)
        .post({
          body: { name },
        });
      if (isUnexpected(createPersonResponse)) {
        throw new Error(createPersonResponse.body.error.message);
      }
      const { personId } = createPersonResponse.body;

      await Promise.all(
        personDictionary[name].map(async (similarImage) => {
          // Check if the image is of sufficient 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}` },
          });
          if (isUnexpected(detectResponse)) {
            throw new Error(detectResponse.body.error.message);
          }

          const sufficientQuality = detectResponse.body.every(
            (face: any) => face.faceAttributes?.qualityForRecognition === "high"
          );
          if (!sufficientQuality || detectResponse.body.length !== 1) {
            return;
          }

          // Quality is sufficient, add to group.
          console.log(
            `Add face to the person group person: (${name}) from image: (${similarImage})`
          );
          const addFaceResponse = await client
            .path(
              "/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces",
              largePersonGroupId,
              personId
            )
            .post({
              queryParameters: { detectionModel: "detection_03" },
              body: { url: `${imageBaseUrl}${similarImage}` },
            });
          if (isUnexpected(addFaceResponse)) {
            throw new Error(addFaceResponse.body.error.message);
          }
        })
      );
    })
  );
  console.log("Done adding faces to person group.");

  // Train the large person group.
  console.log(`\nTraining person group: ${largePersonGroupId}`);
  const trainResponse = await client
    .path("/largepersongroups/{largePersonGroupId}/train", largePersonGroupId)
    .post();
  if (isUnexpected(trainResponse)) {
    throw new Error(trainResponse.body.error.message);
  }
  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 detectSourceResponse = await client.path("/detect").post({
    contentType: "application/json",
    queryParameters: {
      detectionModel: "detection_03",
      recognitionModel: "recognition_04",
      returnFaceId: true,
      returnFaceAttributes: ["qualityForRecognition"],
    },
    body: { url: `${imageBaseUrl}${sourceImageFileName}` },
  });
  if (isUnexpected(detectSourceResponse)) {
    throw new Error(detectSourceResponse.body.error.message);
  }
  const faceIds = detectSourceResponse.body
    .filter((face: any) => face.faceAttributes?.qualityForRecognition !== "low")
    .map((face: any) => face.faceId);

  // Identify the faces in a large person group.
  const identifyResponse = await client.path("/identify").post({
    body: { faceIds, largePersonGroupId },
  });
  if (isUnexpected(identifyResponse)) {
    throw new Error(identifyResponse.body.error.message);
  }

  await Promise.all(
    identifyResponse.body.map(async (result: any) => {
      try {
        const candidate = result.candidates[0];
        if (!candidate) {
          console.log(`No persons identified for face with ID ${result.faceId}`);
          return;
        }
        const getPersonResponse = await client
          .path(
            "/largepersongroups/{largePersonGroupId}/persons/{personId}",
            largePersonGroupId,
            candidate.personId
          )
          .get();
        if (isUnexpected(getPersonResponse)) {
          throw new Error(getPersonResponse.body.error.message);
        }
        const person = getPersonResponse.body;
        console.log(
          `Person: ${person.name} is identified for face in: ${sourceImageFileName} with ID: ${result.faceId}. Confidence: ${candidate.confidence}`
        );

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

  // Delete large person group.
  console.log(`Deleting person group: ${largePersonGroupId}`);
  const deleteResponse = await client
    .path("/largepersongroups/{largePersonGroupId}", largePersonGroupId)
    .delete();
  if (isUnexpected(deleteResponse)) {
    throw new Error(deleteResponse.body.error.message);
  }
  console.log();

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

main().catch(console.error);

Criar e executar o exemplo

  1. Compile o código TypeScript:

    npm run build

  2. Execute o JavaScript compilado:

    npm run start

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.

Limpar os recursos

Se você quiser limpar e remover uma assinatura do Foundry Tools, poderá excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Próximas etapas

Neste início rápido, você aprendeu a usar a biblioteca de clientes de detecção facial para TypeScript para fazer a identificação facial básica. Em seguida, saiba mais sobre os diferentes modelos de detecção facial e como especificar o modelo certo para o caso de uso.

Especificar uma versão de modelo de detecção facial

Comece a usar o reconhecimento do rosto usando a API REST de Detecção Facial. O serviço de Detecção Facial fornece acesso a algoritmos avançados para detectar e reconhecer rostos humanos em imagens.

Note

Este guia de início rápido usa comandos cURL para chamar a API REST. Você também pode chamar a API REST usando uma linguagem de programação. Cenários complexos, como identificação de rosto, são mais fáceis de serem implementados por meio de um SDK de linguagem. Consulte os exemplos do GitHub para obter exemplos em C#, Python, Java, JavaScript e Go.

Prerequisites

  • Assinatura do Azure – Criar uma gratuitamente
  • Depois de obter sua assinatura do Azure, crie um recurso de Detecção Facial no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
    • Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API de Detecção Facial. Cole a chave e o ponto de extremidade no código abaixo mais adiante no guia de início rápido.
    • Use o tipo de preço gratuito (F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.
  • PowerShell versão 6.0+ ou um aplicativo de linha de comando semelhante.
  • cURL instalado.

Identificar e verificar rostos

Note

Se você não tiver recebido acesso ao serviço Face usando o formulário de solicitação, algumas dessas funções não funcionarão.

  1. Primeiro, chame a API de Detecção no rosto de origem. Este é o rosto que tentaremos identificar no grupo maior. Copie o comando a seguir em um editor de texto, insira sua chave e ponto de extremidade, depois copie isso para uma janela do shell e execute.

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

    Salve a cadeia de caracteres da ID de rosto em um local temporário. Você vai usá-la novamente no final.

  2. Em seguida, você precisará criar um LargePersonGroup e dar a ele uma ID arbitrária que corresponda ao padrão ^[a-z0-9-_]+$regex. Esse objeto armazenará os dados de rosto agregados de várias pessoas. Execute o comando a seguir, inserindo sua chave. Opcionalmente, altere o nome e os metadados do grupo no corpo da solicitação.

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

    Salve a ID especificada do grupo criado em um local temporário.

  3. Em seguida, você criará objetos Person que pertencem ao grupo. Execute o comando a seguir, inserindo sua própria chave e a ID do LargePersonGroup da etapa anterior. Este comando cria uma pessoa chamada "Family1-Dad".

    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.""
}"

    Depois de executar esse comando, execute-o novamente com dados de entrada diferentes para criar mais objetos person : "Family1-Mom", "Family1-Son", "Family1-Daughter", "Family2-Lady" e "Family2-Man".

    Salve as IDs de cada pessoa criada; é importante manter o controle de qual nome de pessoa tem qual ID.

  4. Em seguida, você precisará detectar novos rostos e associá-los aos objetos Person existentes. O comando a seguir detecta um rosto da imagem Family1-Dad1.jpg e o adiciona à pessoa correspondente. Você precisa especificar como personId a ID que foi retornada quando você criou o objeto "Family1-Dad" Person . O nome da imagem corresponde ao nome da Pessoa criada. Insira também a ID do LargePersonGroup e sua chave nos campos apropriados.

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

    Em seguida, execute o comando acima novamente com uma imagem de origem diferente e uma Pessoa de destino diferente. As imagens disponíveis são: Family1-Dad1.jpg, Family1-Dad2.jpgFamily1-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.jpge Family2-Man2.jpg. Verifique se a pessoa cuja ID você especificar na chamada à API corresponde ao nome do arquivo de imagem no corpo da solicitação.

    No final desta etapa, você deve ter vários objetos person que cada um tem um ou mais rostos correspondentes, detectados diretamente das imagens fornecidas.

  5. Em seguida, treine o LargePersonGroup com os dados de rosto atuais. A operação de treinamento ensina o modelo a associar as características de rosto, às vezes agregadas de várias imagens de origem, a cada pessoa. Insira a ID do LargePersonGroup e sua chave antes de executar o comando.

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

  6. Verifique se o status do treinamento foi bem-sucedido. Caso contrário, aguarde um pouco e consulte novamente.

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

  7. Agora você está pronto para chamar a API de Identificação, usando a ID de Rosto de origem da primeira etapa e a ID do LargePersonGroup. Insira esses valores nos campos apropriados do corpo da solicitação e insira a chave.

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

    A resposta fornecerá uma ID de Pessoa indicando a pessoa identificada com o rosto de origem. Essa deverá ser a ID que corresponde à pessoa "Family1-Dad", pois o rosto de origem é dessa pessoa.

  8. Para fazer a verificação facial, você usará a ID da Pessoa retornada na etapa anterior, a ID do LargePersonGroup e também a ID do rosto de origem. Insira esses valores nos campos do corpo da solicitação e insira sua chave.

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

    A resposta deve fornecer um resultado de verificação booliano junto com um valor de confiança.

Limpar os recursos

Para excluir o LargePersonGroup que você criou neste exercício, execute a chamada LargePersonGroup – Delete .

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

Se você quiser limpar e remover uma assinatura do Foundry Tools, poderá excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Próximas etapas

Neste guia de início rápido, você aprendeu a usar a API REST de Detecção Facial para realizar tarefas básicas de reconhecimento do rosto. Em seguida, saiba mais sobre os diferentes modelos de detecção facial e como especificar o modelo certo para o caso de uso.

Especificar uma versão de modelo de detecção facial

  • Last updated on