Guia de início rápido: usar o serviço Face
Importante
Se estiver a utilizar produtos ou serviços da Microsoft para processar Dados Biométricos, é responsável por: (i) notificar os titulares dos dados, incluindo no que diz respeito a períodos de retenção e destruição; (ii) obtenção do consentimento dos titulares dos dados; e (iii) eliminar os Dados Biométricos, tudo conforme adequado e exigido ao abrigo dos Requisitos de Proteção de Dados aplicáveis. "Dados Biométricos" terá o significado definido no Artigo 4 do RGPD e, se aplicável, termos equivalentes em outros requisitos de proteção de dados. Para obter informações relacionadas, consulte Dados e privacidade para o rosto.
Atenção
O acesso ao serviço presencial é limitado com base em critérios de elegibilidade e uso, a fim de apoiar nossos princípios de IA responsável. O serviço Face só está disponível para clientes e parceiros geridos pela Microsoft. Use o formulário de admissão de Reconhecimento Facial para solicitar acesso. Para obter mais informações, consulte a página Acesso limitado Face.
Introdução ao reconhecimento facial usando a biblioteca de cliente Face para .NET. O serviço Azure AI Face fornece acesso a algoritmos avançados para detetar e reconhecer rostos humanos em imagens. Siga estas etapas para instalar o pacote e experimente o código de exemplo para identificação facial básica usando imagens remotas.
Documentação | de referência Pacote de código-fonte | da biblioteca (NuGet)Amostras |
Pré-requisitos
- Subscrição do Azure - Criar uma gratuitamente
- O IDE do Visual Studio ou a versão atual do .NET Core.
- Depois de ter sua assinatura do Azure, crie um recurso Face no portal do Azure para obter sua chave e ponto de extremidade. Depois de implantar, selecione Ir para recurso.
- Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API do Face.
- Você pode usar o nível de preço gratuito (
F0
) para experimentar o serviço e atualizar posteriormente para um nível pago para produção.
Criar variáveis de ambiente
Neste exemplo, escreva suas credenciais em variáveis de ambiente na máquina local que executa o aplicativo.
Aceda ao portal do Azure. Se o recurso criado na seção Pré-requisitos for implantado com êxito, selecione Ir para o recurso em Próximas etapas. Você pode encontrar sua chave e ponto de extremidade em Gerenciamento de Recursos na página Chaves e Ponto de Extremidade . Sua chave de recurso não é a mesma que sua ID de assinatura do Azure.
Gorjeta
Não inclua a chave diretamente no seu código e nunca a publique publicamente. Consulte o artigo de segurança dos serviços de IA do Azure para obter mais opções de autenticação, como o Azure Key Vault.
Para definir a variável de ambiente para sua chave e ponto de extremidade, abra uma janela do console e siga as instruções para seu sistema operacional e ambiente de desenvolvimento.
- Para definir a
FACE_APIKEY
variável de ambiente, substitua<your_key>
por uma das chaves do seu recurso. - Para definir a variável de
FACE_ENDPOINT
ambiente, substitua<your_endpoint>
pelo ponto de extremidade do seu recurso.
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
Criar um novo aplicativo C#
Usando o Visual Studio, crie um novo aplicativo .NET Core.
Instalar a biblioteca de cliente
Depois de criar um novo projeto, instale a biblioteca de cliente clicando com o botão direito do mouse na solução do projeto no Gerenciador de Soluções e selecionando Gerenciar Pacotes NuGet. No gestor de pacotes que abre, selecione Procurar, marque a caixa Incluir pré-lançamento e procure
Azure.AI.Vision.Face
. Selecione a versão mais recente e, em seguida , Instalar.Adicione o seguinte código ao arquivo Program.cs .
Nota
Se você não recebeu acesso ao serviço Face usando o formulário de admissão, algumas dessas funções não funcionarão.
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(); } } }
Executar a aplicação
Execute o aplicativo clicando no botão Depurar na parte superior da janela do IDE.
Saída
========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.
Gorjeta
A API Face é executada em um conjunto de modelos pré-construídos que são estáticos por natureza (o desempenho do modelo não regredirá ou melhorará à medida que o serviço for executado). Os resultados que o modelo produz podem mudar se a Microsoft atualizar o back-end do modelo sem migrar para uma versão de modelo totalmente nova. 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.
Clean up resources (Limpar recursos)
Se quiser limpar e remover uma assinatura de serviços do Azure AI, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.
Próximos passos
Neste guia de início rápido, você aprendeu como usar a biblioteca de cliente Face para .NET para fazer a identificação facial básica. Em seguida, saiba mais sobre os diferentes modelos de deteção de rosto e como especificar o modelo certo para o seu caso de uso.
- O que é o serviço Face?
- Um código de exemplo mais extenso pode ser encontrado no GitHub.
Comece a usar o reconhecimento facial usando a biblioteca de cliente Face para Python. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas. O serviço Face fornece acesso a algoritmos avançados para detetar e reconhecer rostos humanos em imagens. Siga estas etapas para instalar o pacote e experimente o código de exemplo para identificação facial básica usando imagens remotas.
Documentação | de referência Pacote de código-fonte | da biblioteca (PiPy)Amostras |
Pré-requisitos
- Subscrição do Azure - Criar uma gratuitamente
- Python 3.x
- Sua instalação do Python deve incluir pip. Você pode verificar se você tem pip instalado executando
pip --version
na linha de comando. Obtenha pip instalando a versão mais recente do Python.
- Sua instalação do Python deve incluir pip. Você pode verificar se você tem pip instalado executando
- Depois de ter sua assinatura do Azure, crie um recurso Face no portal do Azure para obter sua chave e ponto de extremidade. Depois de implantar, selecione Ir para recurso.
- Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API do Face.
- Você pode usar o nível de preço gratuito (
F0
) para experimentar o serviço e atualizar posteriormente para um nível pago para produção.
Criar variáveis de ambiente
Neste exemplo, escreva suas credenciais em variáveis de ambiente na máquina local que executa o aplicativo.
Aceda ao portal do Azure. Se o recurso criado na seção Pré-requisitos for implantado com êxito, selecione Ir para o recurso em Próximas etapas. Você pode encontrar sua chave e ponto de extremidade em Gerenciamento de Recursos na página Chaves e Ponto de Extremidade . Sua chave de recurso não é a mesma que sua ID de assinatura do Azure.
Gorjeta
Não inclua a chave diretamente no seu código e nunca a publique publicamente. Consulte o artigo de segurança dos serviços de IA do Azure para obter mais opções de autenticação, como o Azure Key Vault.
Para definir a variável de ambiente para sua chave e ponto de extremidade, abra uma janela do console e siga as instruções para seu sistema operacional e ambiente de desenvolvimento.
- Para definir a
FACE_APIKEY
variável de ambiente, substitua<your_key>
por uma das chaves do seu recurso. - Para definir a variável de
FACE_ENDPOINT
ambiente, substitua<your_endpoint>
pelo ponto de extremidade do seu recurso.
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
Instalar a biblioteca de cliente
Depois de instalar o Python, pode instalar a biblioteca de cliente com:
pip install --upgrade azure-ai-vision-face
Criar uma aplicação Python nova
Crie um novo script Python — quickstart-file.py, por exemplo. Em seguida, abra-o no seu editor ou IDE preferido e cole no código a seguir.
Nota
Se você não recebeu acesso ao serviço Face usando o formulário de admissão, algumas dessas funções não funcionarão.
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.")
Execute seu aplicativo de reconhecimento facial a partir do diretório do aplicativo com o
python
comando.python quickstart-file.py
Gorjeta
A API Face é executada em um conjunto de modelos pré-construídos que são estáticos por natureza (o desempenho do modelo não regredirá ou melhorará à medida que o serviço for executado). Os resultados que o modelo produz podem mudar se a Microsoft atualizar o back-end do modelo sem migrar para uma versão de modelo totalmente nova. 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.
Saída
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.
Clean up resources (Limpar recursos)
Se quiser limpar e remover uma assinatura de serviços do Azure AI, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.
Próximos passos
Neste início rápido, você aprendeu como usar a biblioteca de cliente Face para Python para fazer identificação facial básica. Em seguida, saiba mais sobre os diferentes modelos de deteção de rosto e como especificar o modelo certo para o seu caso de uso.
- O que é o serviço Face?
- Um código de exemplo mais extenso pode ser encontrado no GitHub.
Comece a usar o reconhecimento facial usando a biblioteca de cliente Face para Java. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas. O serviço Face fornece acesso a algoritmos avançados para detetar e reconhecer rostos humanos em imagens. Siga estas etapas para instalar o pacote e experimente o código de exemplo para identificação facial básica usando imagens remotas.
Documentação | de referência Pacote de código-fonte | da biblioteca (Maven)Amostras |
Pré-requisitos
- Subscrição do Azure - Criar uma gratuitamente
- A versão atual do Java Development Kit (JDK)
- Apache Maven instalado. No Linux, instale a partir dos repositórios de distribuição, se disponíveis.
- Depois de ter sua assinatura do Azure, crie um recurso Face no portal do Azure para obter sua chave e ponto de extremidade. Depois de implantar, selecione Ir para recurso.
- Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API do Face.
- Você pode usar o nível de preço gratuito (
F0
) para experimentar o serviço e atualizar posteriormente para um nível pago para produção.
Criar variáveis de ambiente
Neste exemplo, escreva suas credenciais em variáveis de ambiente na máquina local que executa o aplicativo.
Aceda ao portal do Azure. Se o recurso criado na seção Pré-requisitos for implantado com êxito, selecione Ir para o recurso em Próximas etapas. Você pode encontrar sua chave e ponto de extremidade em Gerenciamento de Recursos na página Chaves e Ponto de Extremidade . Sua chave de recurso não é a mesma que sua ID de assinatura do Azure.
Gorjeta
Não inclua a chave diretamente no seu código e nunca a publique publicamente. Consulte o artigo de segurança dos serviços de IA do Azure para obter mais opções de autenticação, como o Azure Key Vault.
Para definir a variável de ambiente para sua chave e ponto de extremidade, abra uma janela do console e siga as instruções para seu sistema operacional e ambiente de desenvolvimento.
- Para definir a
FACE_APIKEY
variável de ambiente, substitua<your_key>
por uma das chaves do seu recurso. - Para definir a variável de
FACE_ENDPOINT
ambiente, substitua<your_endpoint>
pelo ponto de extremidade do seu recurso.
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
Instalar a biblioteca de cliente
Abra uma janela de console e crie uma nova pasta para seu aplicativo de início rápido. Copie o seguinte conteúdo 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.1</version> </dependency> <!-- https://mvnrepository.com/artifact/org.apache.httpcomponents/httpclient --> <dependency> <groupId>org.apache.httpcomponents</groupId> <artifactId>httpclient</artifactId> <version>4.5.13</version> </dependency> <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson --> <dependency> <groupId>com.google.code.gson</groupId> <artifactId>gson</artifactId> <version>2.11.0</version> </dependency> </dependencies> </project>
Instale o SDK e as dependências executando o seguinte no diretório do projeto:
mvn clean dependency:copy-dependencies
Criar uma nova aplicação Java
Crie um arquivo chamado
Quickstart.java
, abra-o em um editor de texto e cole o seguinte código:Nota
Se você não recebeu acesso ao serviço Face usando o formulário de admissã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.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.FaceRecognitionModel; import com.azure.ai.vision.face.models.QualityForRecognition; import com.azure.core.credential.KeyCredential; import com.google.gson.Gson; import com.google.gson.reflect.TypeToken; import org.apache.http.HttpHeaders; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpDelete; import org.apache.http.client.methods.HttpGet; import org.apache.http.client.methods.HttpPost; import org.apache.http.client.methods.HttpPut; import org.apache.http.client.utils.URIBuilder; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.HttpClients; import org.apache.http.message.BasicHeader; import org.apache.http.util.EntityUtils; 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 + ")."); List<BasicHeader> headers = Arrays.asList(new BasicHeader("Ocp-Apim-Subscription-Key", SUBSCRIPTION_KEY), new BasicHeader(HttpHeaders.CONTENT_TYPE, "application/json")); HttpClient httpClient = HttpClients.custom().setDefaultHeaders(headers).build(); createLargePersonGroup(httpClient, 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 = createLargePersonGroupPerson(httpClient, groupedFace); 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> detectedFaces1 = client.detect(url + similarImage, options); if (detectedFaces1.stream().anyMatch(f -> f.getFaceAttributes().getQualityForRecognition() != QualityForRecognition.HIGH)) { continue; } if (detectedFaces1.size() != 1) { continue; } // add face to the large person group System.out.println("Add face to the person group person(" + groupedFace + ") from image `" + similarImage + "`"); addFaceToLargePersonGroup(httpClient, personId, url + similarImage); } } // Start to train the large person group. System.out.println(); System.out.println("Train person group " + LARGE_PERSON_GROUP_ID + "."); trainLargePersonGroup(httpClient); // Wait until the training is completed. while (true) { Thread.sleep(1000); String trainingStatus = getLargePersonGroupTrainingStatus(httpClient); System.out.println("Training status: " + trainingStatus + "."); if ("succeeded".equals(trainingStatus)) { break; } } 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<Map<String, Object>> identifyResults = identifyFacesInLargePersonGroup(httpClient, sourceFaceIds); for (Map<String, Object> identifyResult : identifyResults) { String faceId = identifyResult.get("faceId").toString(); List<Map<String, Object>> candidates = new Gson().fromJson(new Gson().toJson(identifyResult.get("candidates")), new TypeToken<List<Map<String, Object>>>(){}); if (candidates.isEmpty()) { System.out.println("No person is identified for the face in: " + sourceImageFileName + " - " + faceId + "."); continue; } Map<String, Object> candidate = candidates.stream().findFirst().orElseThrow(); String personName = getLargePersonGroupPersonName(httpClient, candidate.get("personId").toString()); System.out.println("Person '" + personName + "' is identified for the face in: " + sourceImageFileName + " - " + faceId + ", confidence: " + candidate.get("confidence") + "."); Map<String, Object> verifyResult = verifyFaceWithLargePersonGroupPerson(httpClient, faceId, candidate.get("personId").toString()); System.out.println("Verification result: is a match? " + verifyResult.get("isIdentical") + ". confidence: " + verifyResult.get("confidence")); } System.out.println(); // Delete large person group. System.out.println("========DELETE PERSON GROUP========"); System.out.println(); deleteLargePersonGroup(httpClient); System.out.println("Deleted the person group " + LARGE_PERSON_GROUP_ID + "."); System.out.println(); } private static void createLargePersonGroup(HttpClient httpClient, FaceRecognitionModel recognitionModel) throws Exception { HttpPut request = new HttpPut(new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID).build()); request.setEntity(new StringEntity(new Gson().toJson(Map.of("name", LARGE_PERSON_GROUP_ID, "recognitionModel", recognitionModel.toString())))); httpClient.execute(request); request.releaseConnection(); } private static String createLargePersonGroupPerson(HttpClient httpClient, String name) throws Exception { HttpPost request = new HttpPost(new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID + "/persons").build()); request.setEntity(new StringEntity(new Gson().toJson(Map.of("name", name)))); String response = EntityUtils.toString(httpClient.execute(request).getEntity()); request.releaseConnection(); return new Gson().fromJson(response, new TypeToken<Map<String, Object>>(){}).get("personId").toString(); } private static void addFaceToLargePersonGroup(HttpClient httpClient, String personId, String url) throws Exception { URIBuilder builder = new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID + "/persons/" + personId + "/persistedfaces"); builder.setParameter("detectionModel", "detection_03"); HttpPost request = new HttpPost(builder.build()); request.setEntity(new StringEntity(new Gson().toJson(Map.of("url", url)))); httpClient.execute(request); request.releaseConnection(); } private static void trainLargePersonGroup(HttpClient httpClient) throws Exception { HttpPost request = new HttpPost(new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID + "/train").build()); httpClient.execute(request); request.releaseConnection(); } private static String getLargePersonGroupTrainingStatus(HttpClient httpClient) throws Exception { HttpGet request = new HttpGet(new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID + "/training").build()); String response = EntityUtils.toString(httpClient.execute(request).getEntity()); request.releaseConnection(); return new Gson().fromJson(response, new TypeToken<Map<String, Object>>(){}).get("status").toString(); } private static List<Map<String, Object>> identifyFacesInLargePersonGroup(HttpClient httpClient, List<String> sourceFaceIds) throws Exception { HttpPost request = new HttpPost(new URIBuilder(ENDPOINT + "/face/v1.0/identify").build()); request.setEntity(new StringEntity(new Gson().toJson(Map.of("faceIds", sourceFaceIds, "largePersonGroupId", LARGE_PERSON_GROUP_ID)))); String response = EntityUtils.toString(httpClient.execute(request).getEntity()); request.releaseConnection(); return new Gson().fromJson(response, new TypeToken<List<Map<String, Object>>>(){}); } private static String getLargePersonGroupPersonName(HttpClient httpClient, String personId) throws Exception { HttpGet request = new HttpGet(new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID + "/persons/" + personId).build()); String response = EntityUtils.toString(httpClient.execute(request).getEntity()); request.releaseConnection(); return new Gson().fromJson(response, new TypeToken<Map<String, Object>>(){}).get("name").toString(); } private static Map<String, Object> verifyFaceWithLargePersonGroupPerson(HttpClient httpClient, String faceId, String personId) throws Exception { HttpPost request = new HttpPost(new URIBuilder(ENDPOINT + "/face/v1.0/verify").build()); request.setEntity(new StringEntity(new Gson().toJson(Map.of("faceId", faceId, "personId", personId, "largePersonGroupId", LARGE_PERSON_GROUP_ID)))); String response = EntityUtils.toString(httpClient.execute(request).getEntity()); request.releaseConnection(); return new Gson().fromJson(response, new TypeToken<Map<String, Object>>(){}); } private static void deleteLargePersonGroup(HttpClient httpClient) throws Exception { HttpDelete request = new HttpDelete(new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID).build()); httpClient.execute(request); request.releaseConnection(); } }
Execute seu aplicativo de reconhecimento facial a partir do diretório do aplicativo com os
javac
comandos andjava
.
Saída
========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.
Clean up resources (Limpar recursos)
Se quiser limpar e remover uma assinatura de serviços do Azure AI, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.
Próximos passos
Neste início rápido, você aprendeu como usar a biblioteca de cliente Face para Java para fazer a identificação facial básica. Em seguida, saiba mais sobre os diferentes modelos de deteção de rosto e como especificar o modelo certo para o seu caso de uso.
- O que é o serviço Face?
- Um código de exemplo mais extenso pode ser encontrado no GitHub.
Comece a usar o reconhecimento facial usando a biblioteca de cliente Face para JavaScript. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas. O serviço Face fornece acesso a algoritmos avançados para detetar e reconhecer rostos humanos em imagens. Siga estas etapas para instalar o pacote e experimente o código de exemplo para identificação facial básica usando imagens remotas.
Documentação | de referência Pacote de código-fonte | da biblioteca (npm)Exemplos |
Pré-requisitos
- Subscrição do Azure - Criar uma gratuitamente
- A última versão do Node.js
- Depois de ter sua assinatura do Azure, crie um recurso Face no portal do Azure para obter sua chave e ponto de extremidade. Depois de implantar, selecione Ir para recurso.
- Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API do Face.
- Você pode usar o nível de preço gratuito (
F0
) para experimentar o serviço e atualizar posteriormente para um nível pago para produção.
Criar variáveis de ambiente
Neste exemplo, escreva suas credenciais em variáveis de ambiente na máquina local que executa o aplicativo.
Aceda ao portal do Azure. Se o recurso criado na seção Pré-requisitos for implantado com êxito, selecione Ir para o recurso em Próximas etapas. Você pode encontrar sua chave e ponto de extremidade em Gerenciamento de Recursos na página Chaves e Ponto de Extremidade . Sua chave de recurso não é a mesma que sua ID de assinatura do Azure.
Gorjeta
Não inclua a chave diretamente no seu código e nunca a publique publicamente. Consulte o artigo de segurança dos serviços de IA do Azure para obter mais opções de autenticação, como o Azure Key Vault.
Para definir a variável de ambiente para sua chave e ponto de extremidade, abra uma janela do console e siga as instruções para seu sistema operacional e ambiente de desenvolvimento.
- Para definir a
FACE_APIKEY
variável de ambiente, substitua<your_key>
por uma das chaves do seu recurso. - Para definir a variável de
FACE_ENDPOINT
ambiente, substitua<your_endpoint>
pelo ponto de extremidade do seu recurso.
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
Criar uma nova aplicação Node.js
Numa janela de consola (como cmd, PowerShell ou Bash), crie um novo diretório para a sua aplicação e navegue para a mesma.
mkdir myapp && cd myapp
Execute o comando
npm init
para criar uma aplicação de nó com um ficheiropackage.json
.npm init
Instale os
@azure-rest/ai-vision-face
pacotes npm:npm install @azure-rest/ai-vision-face
O arquivo do
package.json
seu aplicativo é atualizado com as dependências.Crie um arquivo chamado
index.js
, abra-o em um editor de texto e cole o seguinte código:Nota
Se você não recebeu acesso ao serviço Face usando o formulário de admissã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);
Execute a aplicação com o comando
node
no seu ficheiro de início rápido.node index.js
Saída
========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.
Clean up resources (Limpar recursos)
Se quiser limpar e remover uma assinatura de serviços do Azure AI, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.
Próximos passos
Neste guia de início rápido, você aprendeu como usar a biblioteca de cliente Face para JavaScript para fazer a identificação facial básica. Em seguida, saiba mais sobre os diferentes modelos de deteção de rosto e como especificar o modelo certo para o seu caso de uso.
- O que é o serviço Face?
- Um código de exemplo mais extenso pode ser encontrado no GitHub.
Comece a usar o reconhecimento facial usando a API Face REST. O serviço Face fornece acesso a algoritmos avançados para detetar e reconhecer rostos humanos em imagens.
Nota
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 a identificação facial, são mais fáceis de implementar usando um SDK de linguagem. Consulte os exemplos do GitHub para obter exemplos em C#, Python, Java, JavaScript e Go.
Pré-requisitos
- Subscrição do Azure - Criar uma gratuitamente
- Depois de ter sua assinatura do Azure, crie um recurso Face no portal do Azure para obter sua chave e ponto de extremidade. Depois de implantar, selecione Ir para recurso.
- Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API do Face. Você colará sua chave e ponto de extremidade no código abaixo mais adiante no início rápido.
- Você pode usar o nível de preço gratuito (
F0
) para experimentar o serviço e atualizar posteriormente 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
Nota
Se você não recebeu acesso ao serviço Face usando o formulário de admissão, algumas dessas funções não funcionarão.
Primeiro, chame a API de deteção na face de origem. Este é o rosto que tentaremos identificar do grupo maior. Copie o comando a seguir para um editor de texto, insira sua própria chave e ponto de extremidade e, em seguida, copie-o em uma janela do shell e execute-o.
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 de identificação facial retornada em um local temporário. Você vai usá-lo novamente no final.
Em seguida, você precisará criar um LargePersonGroup e dar-lhe uma ID arbitrária que corresponda ao padrão
^[a-z0-9-_]+$
regex. Este objeto armazenará os dados de face agregados de várias pessoas. Execute o seguinte comando, inserindo sua própria 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.
Em seguida, você criará objetos Person que pertencem ao grupo. Execute o seguinte comando, 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 diferentes dados de entrada para criar mais objetos Person : "Family1-Mom", "Family1-Son", "Family1-Daughter", "Family2-Lady" e "Family2-Man".
Salve os IDs de cada Pessoa criada, é importante acompanhar qual nome de pessoa tem qual ID.
Em seguida, você precisará detetar novos rostos e associá-los aos objetos Person existentes. O comando a seguir deteta um rosto da imagem Family1-Dad1.jpg e o adiciona à pessoa correspondente. Você precisa especificar o
personId
como o ID que foi retornado quando você criou o objeto Person "Family1-Dad". O nome da imagem corresponde ao nome da Pessoa criada. Insira também o ID 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 Pessoa de destino. As imagens disponíveis são: 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. Certifique-se de que a Pessoa cujo ID você especifica na chamada da API corresponde ao nome do arquivo de imagem no corpo da solicitação.
No final desta etapa, você deve ter vários objetos Person cada um com uma ou mais faces correspondentes, detetados diretamente das imagens fornecidas.
Em seguida, treine o LargePersonGroup com os dados faciais atuais. A operação de treinamento ensina o modelo a associar características faciais, às vezes agregadas a partir de várias imagens de origem, a cada pessoa. Insira o ID LargePersonGroup e sua chave antes de executar o comando.
Verifique se o status do treinamento foi bem-sucedido. Caso contrário, aguarde um pouco e consulte novamente.
Agora você está pronto para chamar a API de identificação, usando o ID do rosto de origem da primeira etapa e o ID do LargePersonGroup . Insira esses valores nos campos apropriados no corpo da solicitação e insira sua 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 deve fornecer-lhe um ID de Pessoa indicando a pessoa identificada com o rosto de origem. Deve ser o ID que corresponde à pessoa "Família1-Pai", porque o rosto de origem é dessa pessoa.
Para fazer a verificação facial, você usará o ID da pessoa retornado na etapa anterior, o ID do LargePersonGroup e também o ID do rosto de origem. Insira esses valores nos campos no 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 booleano juntamente com um valor de confiança.
Clean up resources (Limpar recursos)
Para excluir o LargePersonGroup criado 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 quiser limpar e remover uma assinatura de serviços do Azure AI, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.
Próximos passos
Neste guia de início rápido, você aprendeu como usar a API Face REST para fazer tarefas básicas de reconhecimento facial. Em seguida, saiba mais sobre os diferentes modelos de deteção de rosto e como especificar o modelo certo para o seu caso de uso.
Comentários
https://aka.ms/ContentUserFeedback.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários