Краткое руководство. Использование клиентской библиотеки API Распознавания лиц

Важно!

Доступ к службе "Распознавание лиц" ограничен на основе соответствия требованиям и критериев использования для реализации поддержки наших принципов ответственного ИИ. Служба "Распознавание лиц" доступна только для клиентов и партнеров, управляемых корпорацией Майкрософт. Используйте форму приема Распознавания лиц, чтобы подать заявку на доступ.

В этом руководстве описано, как приступить к работе с клиентской библиотекой API "Распознавание лиц" для .NET. В службе "Распознавание лиц" доступны передовые алгоритмы обнаружения и распознавания лиц на изображениях. Выполните следующие действия, чтобы установить пакет и опробовать пример кода для базовой идентификации лица с помощью удаленных изображений.

Справочная документация | Исходный код библиотеки | Пакет (NuGet) | Примеры

Предварительные требования

  • Подписка Azure — создайте бесплатную учетную запись.
  • IDE Visual Studio или текущая версия .NET Core.
  • Вашей учетной записи Azure должна быть назначена роль участника Cognitive Services, чтобы вы могли принять условия использования искусственного интеллекта и создать ресурс. Чтобы назначить эту роль своей учетной записи, следуйте инструкциям, описанным в документации по назначению ролей, или обратитесь к администратору.
  • Получив подписку Azure, перейдите к созданию ресурса Распознавания лиц на портале Azure, чтобы получить ключ и конечную точку. После развертывания щелкните Перейти к ресурсам.
    • Для подключения приложения к API Распознавания лиц потребуется ключ и конечная точка из созданного ресурса. Ключ и конечная точка будут вставлены в приведенный ниже код в кратком руководстве.
    • Используйте бесплатную ценовую категорию (F0), чтобы опробовать службу, а затем выполните обновление до платного уровня для рабочей среды.

Идентификация лиц

  1. Создание нового приложения C#

    С помощью Visual Studio создайте приложение .NET Core.

    Установка клиентской библиотеки

    После создания проекта установите клиентскую библиотеку, щелкнув правой кнопкой мыши решение проекта в Обозревателе решений и выбрав пункт Управление пакетами NuGet. В открывшемся диспетчере пакетов выберите Просмотр, установите флажок Включить предварительные версии и выполните поиск по запросу Microsoft.Azure.CognitiveServices.Vision.Face. Выберите версию 2.7.0-preview.1, а затем Установить.

  2. Добавьте следующий код в файл Program.cs.

    using System;
    using System.Collections.Generic;
    using System.IO;
    using System.Linq;
    using System.Threading;
    using System.Threading.Tasks;
    
    using Microsoft.Azure.CognitiveServices.Vision.Face;
    using Microsoft.Azure.CognitiveServices.Vision.Face.Models;
    
    namespace FaceQuickstart
    {
        class Program
        {
            static string personGroupId = Guid.NewGuid().ToString();
    
            // URL path for the images.
            const string IMAGE_BASE_URL = "https://csdx.blob.core.windows.net/resources/Face/Images/";
    
            // From your Face subscription in the Azure portal, get your subscription key and endpoint.
            const string SUBSCRIPTION_KEY = "PASTE_YOUR_FACE_SUBSCRIPTION_KEY_HERE";
            const string ENDPOINT = "PASTE_YOUR_FACE_SUBSCRIPTION_ENDPOINT_HERE";
    
             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.
                const string RECOGNITION_MODEL4 = RecognitionModel.Recognition04;
    
                // Authenticate.
                IFaceClient client = Authenticate(ENDPOINT, SUBSCRIPTION_KEY);
    
                // Identify - recognize a face(s) in a person group (a person group is created in this example).
                IdentifyInPersonGroup(client, IMAGE_BASE_URL, RECOGNITION_MODEL4).Wait();
    
                Console.WriteLine("End of quickstart.");
            }
    
            /*
             *	AUTHENTICATE
             *	Uses subscription key and region to create a client.
             */
            public static IFaceClient Authenticate(string endpoint, string key)
            {
                return new FaceClient(new ApiKeyServiceClientCredentials(key)) { Endpoint = endpoint };
            }
    
            // Detect faces from image url for recognition purpose. This is a helper method for other functions in this quickstart.
            // Parameter `returnFaceId` of `DetectWithUrlAsync` must be set to `true` (by default) for recognition purpose.
            // Parameter `FaceAttributes` 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 Face - Find Similar, Face - Verify. and Face - Identify.
            // It will expire 24 hours after the detection call.
            private static async Task<List<DetectedFace>> DetectFaceRecognize(IFaceClient faceClient, string url, string recognition_model)
            {
                // Detect faces from image URL. Since only recognizing, use the recognition model 1.
                // We use detection model 3 because we are not retrieving attributes.
                IList<DetectedFace> detectedFaces = await faceClient.Face.DetectWithUrlAsync(url, recognitionModel: recognition_model, detectionModel: DetectionModel.Detection03, returnFaceAttributes: new List<FaceAttributeType> { FaceAttributeType.QualityForRecognition });
                List<DetectedFace> sufficientQualityFaces = new List<DetectedFace>();
                foreach (DetectedFace detectedFace in detectedFaces){
                    var faceQualityForRecognition = detectedFace.FaceAttributes.QualityForRecognition;
                    if (faceQualityForRecognition.HasValue && (faceQualityForRecognition.Value >= QualityForRecognition.Medium)){
                        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.ToList();
            }
    
            /*
             * IDENTIFY FACES
             * To identify faces, you need to create and define a person group.
             * The Identify operation takes one or several face IDs from DetectedFace or PersistedFace and a PersonGroup 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 IdentifyInPersonGroup(IFaceClient client, string url, string 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" } },
                          { "Family1-Daughter", new[] { "Family1-Daughter1.jpg", "Family1-Daughter2.jpg" } },
                          { "Family2-Lady", new[] { "Family2-Lady1.jpg", "Family2-Lady2.jpg" } },
                          { "Family2-Man", new[] { "Family2-Man1.jpg", "Family2-Man2.jpg" } }
                        };
                // A group photo that includes some of the persons you seek to identify from your dictionary.
                string sourceImageFileName = "identification1.jpg";
    
                // Create a person group. 
                Console.WriteLine($"Create a person group ({personGroupId}).");
                await client.PersonGroup.CreateAsync(personGroupId, personGroupId, recognitionModel: recognitionModel);
                // The similar faces will be grouped into a single person group person.
                foreach (var groupedFace in personDictionary.Keys)
                {
                    // Limit TPS
                    await Task.Delay(250);
                    Person person = await client.PersonGroupPerson.CreateAsync(personGroupId: personGroupId, name: groupedFace);
                    Console.WriteLine($"Create a person group person '{groupedFace}'.");
    
                    // Add face to the person group person.
                    foreach (var similarImage in personDictionary[groupedFace])
                    {
                        Console.WriteLine($"Check whether image is of sufficient quality for recognition");
                        IList<DetectedFace> detectedFaces1 = await client.Face.DetectWithUrlAsync($"{url}{similarImage}", 
                            recognitionModel: recognitionModel, 
                            detectionModel: DetectionModel.Detection03,
                            returnFaceAttributes: new List<FaceAttributeType> { FaceAttributeType.QualityForRecognition });
                        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;
                        }
    
    
                        Console.WriteLine($"Add face to the person group person({groupedFace}) from image `{similarImage}`");
                        PersistedFace face = await client.PersonGroupPerson.AddFaceFromUrlAsync(personGroupId, person.PersonId,
                            $"{url}{similarImage}", similarImage);
                    }
                }
    
                // Start to train the person group.
                Console.WriteLine();
                Console.WriteLine($"Train person group {personGroupId}.");
                await client.PersonGroup.TrainAsync(personGroupId);
    
                // Wait until the training is completed.
                while (true)
                {
                    await Task.Delay(1000);
                    var trainingStatus = await client.PersonGroup.GetTrainingStatusAsync(personGroupId);
                    Console.WriteLine($"Training status: {trainingStatus.Status}.");
                    if (trainingStatus.Status == TrainingStatusType.Succeeded) { break; }
                }
                Console.WriteLine();
    
                List<Guid> sourceFaceIds = new List<Guid>();
                // Detect faces from source image url.
                List<DetectedFace> 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 person group. 
                var identifyResults = await client.Face.IdentifyAsync(sourceFaceIds, personGroupId);
    
                foreach (var identifyResult in identifyResults)
                {
                    if (identifyResult.Candidates.Count==0) {
                        Console.WriteLine($"No person is identified for the face in: {sourceImageFileName} - {identifyResult.FaceId},");
                        continue;
                    }
                    Person person = await client.PersonGroupPerson.GetAsync(personGroupId, identifyResult.Candidates[0].PersonId);
                    Console.WriteLine($"Person '{person.Name}' is identified for the face in: {sourceImageFileName} - {identifyResult.FaceId}," +
                        $" confidence: {identifyResult.Candidates[0].Confidence}.");
                }
                Console.WriteLine();
            }
        }
    }
    
  3. Введите ключ и конечную точку в соответствующих полях.

    Важно!

    Перейдите на портал Azure. Если ресурс "Распознавание лиц", созданный в соответствии с указаниями в разделе Предварительные требования, успешно развернут, нажмите кнопку Перейти к ресурсу в разделе Дальнейшие действия. Ключ и конечная точка располагаются на странице ключа и конечной точки ресурса в разделе управления ресурсами.

    Важно!

    Не забудьте удалить ключ из кода, когда закончите, и никогда не публикуйте его в открытом доступе. Для рабочей среды рекомендуется использовать безопасный способ хранения и доступа к учетным данным. Дополнительные сведения см. в статье о безопасности в Cognitive Services.

  4. Выполнение приложения

    Запустите приложение, нажав кнопку Отладка в верхней части окна интегрированной среды разработки.

Выходные данные

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

Create a person group (3972c063-71b3-4328-8579-6d190ee76f99).
Create a person group person 'Family1-Dad'.
Add face to the person group person(Family1-Dad) from image `Family1-Dad1.jpg`
Add face to the person group person(Family1-Dad) from image `Family1-Dad2.jpg`
Create a person group person 'Family1-Mom'.
Add face to the person group person(Family1-Mom) from image `Family1-Mom1.jpg`
Add face to the person group person(Family1-Mom) from image `Family1-Mom2.jpg`
Create a person group person 'Family1-Son'.
Add face to the person group person(Family1-Son) from image `Family1-Son1.jpg`
Add face to the person group person(Family1-Son) from image `Family1-Son2.jpg`
Create a person group person 'Family1-Daughter'.
Create a person group person 'Family2-Lady'.
Add face to the person group person(Family2-Lady) from image `Family2-Lady1.jpg`
Add face to the person group person(Family2-Lady) from image `Family2-Lady2.jpg`
Create a person group person 'Family2-Man'.
Add face to the person group person(Family2-Man) from image `Family2-Man1.jpg`
Add face to the person group person(Family2-Man) from image `Family2-Man2.jpg`

Train person group 3972c063-71b3-4328-8579-6d190ee76f99.
Training status: Succeeded.

4 face(s) with 4 having sufficient quality for recognition detected from image `identification1.jpg`
Person 'Family1-Dad' is identified for face in: identification1.jpg - 994bfd7a-0d8f-4fae-a5a6-c524664cbee7, confidence: 0.96725.
Person 'Family1-Mom' is identified for face in: identification1.jpg - 0c9da7b9-a628-429d-97ff-cebe7c638fb5, confidence: 0.96921.
No person is identified for face in: identification1.jpg - a881259c-e811-4f7e-a35e-a453e95ca18f,
Person 'Family1-Son' is identified for face in: identification1.jpg - 53772235-8193-46eb-bdfc-1ebc25ea062e, confidence: 0.92886.

End of quickstart.

Совет

API службы "Распознавание лиц" выполняется на наборе предварительно созданных моделей, которые по своей природе являются статическими (производительность модели не ухудшается и не улучшается при выполнении службы). Результаты, предоставляемые моделью, могут измениться, если корпорация Майкрософт обновит внутреннюю структуру модели без перехода на полностью новую версию модели. Чтобы воспользоваться преимуществами новой версии модели, вы можете повторно обучить PersonGroup, указав более новую модель в качестве параметра с такими же изображениями для регистрации.

Очистка ресурсов

Если вы хотите очистить и удалить подписку Cognitive Services, вы можете удалить ресурс или группу ресурсов. При этом удаляются все ресурсы, связанные с ней.

Чтобы удалить PersonGroup, выполните следующий код в программе.

// At end, delete person groups in both regions (since testing only)
Console.WriteLine("========DELETE PERSON GROUP========");
Console.WriteLine();
DeletePersonGroup(client, personGroupId).Wait();

Определите метод удаления со следующим кодом:

/*
 * DELETE PERSON GROUP
 * After this entire example is executed, delete the person group in your Azure account,
 * otherwise you cannot recreate one with the same name (if running example repeatedly).
 */
public static async Task DeletePersonGroup(IFaceClient client, String personGroupId)
{
    await client.PersonGroup.DeleteAsync(personGroupId);
    Console.WriteLine($"Deleted the person group {personGroupId}.");
}

Дальнейшие действия

Из этого краткого руководство вы узнали, как с помощью клиентской библиотеки Распознавания лиц для .NET выполнять базовое распознавание лиц. Далее вы узнаете о различных моделях определения лиц и о том, как указать правильную модель для вашего варианта использования.

Узнайте, как приступить к распознаванию лиц с помощью клиентской библиотеки Распознавания лиц для JavaScript. Выполните приведенные здесь действия, чтобы установить пакет и протестировать пример кода для выполнения базовых задач. В службе "Распознавание лиц" доступны передовые алгоритмы обнаружения и распознавания лиц на изображениях. Выполните следующие действия, чтобы установить пакет и опробовать пример кода для базовой идентификации лица с помощью удаленных изображений.

Справочная документация | Исходный код библиотеки | Пакет (npm) | Примеры

Предварительные требования

  • Подписка Azure — создайте бесплатную учетную запись.
  • Последняя версия Node.js.
  • Вашей учетной записи Azure должна быть назначена роль участника Cognitive Services, чтобы вы могли принять условия использования искусственного интеллекта и создать ресурс. Чтобы назначить эту роль своей учетной записи, следуйте инструкциям, описанным в документации по назначению ролей, или обратитесь к администратору.
  • Получив подписку Azure, создайте ресурс Распознавания лиц на портале Azure, чтобы получить ключ и конечную точку. После развертывания щелкните Перейти к ресурсам.
    • Для подключения приложения к API Распознавания лиц потребуется ключ и конечная точка из созданного ресурса. Ключ и конечная точка будут вставлены в приведенный ниже код в кратком руководстве.
    • Используйте бесплатную ценовую категорию (F0), чтобы опробовать службу, а затем выполните обновление до платного уровня для рабочей среды.

Идентификация лиц

  1. создание приложения Node.js;

    В окне консоли (например, cmd, PowerShell или Bash) создайте новый каталог для приложения и перейдите в него.

    mkdir myapp && cd myapp
    

    Выполните команду npm init, чтобы создать приложение узла с помощью файла package.json.

    npm init
    
  2. Установите пакеты NPM: ms-rest-azure и azure-cognitiveservices-face.

    npm install @azure/cognitiveservices-face @azure/ms-rest-js uuid
    

    Файл package.json этого приложения будет дополнен зависимостями.

  3. Создайте файл с именем index.js, откройте его в текстовом редакторе и вставьте следующий код.

    'use strict';
    
    const msRest = require("@azure/ms-rest-js");
    const Face = require("@azure/cognitiveservices-face");
    const { v4: uuid } = require('uuid');
    
    key = "PASTE_YOUR_FACE_SUBSCRIPTION_KEY_HERE";
    endpoint = "PASTE_YOUR_FACE_ENDPOINT_HERE";
    
    const credentials = new msRest.ApiKeyCredentials({ inHeader: { 'Ocp-Apim-Subscription-Key': key } });
    const client = new Face.FaceClient(credentials, endpoint);
    
    
    const image_base_url = "https://csdx.blob.core.windows.net/resources/Face/Images/";
    const person_group_id = uuid();
    
    function sleep(ms) {
        return new Promise(resolve => setTimeout(resolve, ms));
    }
    
    async function DetectFaceRecognize(url) {
        // Detect faces from image URL. Since only recognizing, use the recognition model 4.
        // We use detection model 3 because we are only retrieving the qualityForRecognition attribute.
        // Result faces with quality for recognition lower than "medium" are filtered out.
        let detected_faces = await client.face.detectWithUrl(url,
            {
                detectionModel: "detection_03",
                recognitionModel: "recognition_04",
                returnFaceAttributes: ["QualityForRecognition"]
            });
        return detected_faces.filter(face => face.faceAttributes.qualityForRecognition == 'high' || face.faceAttributes.qualityForRecognition == 'medium');
    }
    
    async function AddFacesToPersonGroup(person_dictionary, person_group_id) {
        console.log ("Adding faces to person group...");
        // The similar faces will be grouped into a single person group person.
        
        await Promise.all (Object.keys(person_dictionary).map (async function (key) {
            const value = person_dictionary[key];
    
            // Wait briefly so we do not exceed rate limits.
            await sleep (2000);
    
            let person = await client.personGroupPerson.create(person_group_id, { name : key });
            console.log("Create a persongroup person: " + key + ".");
    
            // Add faces to the person group person.
            await Promise.all (value.map (async function (similar_image) {
                // Check if the image is of sufficent quality for recognition.
                let sufficientQuality = true;
                let detected_faces = await client.face.detectWithUrl(image_base_url + similar_image,
                    {
                        returnFaceAttributes: ["QualityForRecognition"],
                        detectionModel: "detection_03",
                        recognitionModel: "recognition_03"
                    });
                detected_faces.forEach(detected_face => {
                    if (detected_face.faceAttributes.qualityForRecognition != 'high'){
                        sufficientQuality = false;
                    }
                });
    
                // Quality is sufficent, add to group.
                if (sufficientQuality){
                    console.log("Add face to the person group person: (" + key + ") from image: " + similar_image + ".");
                    await client.personGroupPerson.addFaceFromUrl(person_group_id, person.personId, image_base_url + similar_image);
                }
            }));
        }));
    
        console.log ("Done adding faces to person group.");
    }
    
    async function WaitForPersonGroupTraining(person_group_id) {
        // Wait so we do not exceed rate limits.
        console.log ("Waiting 10 seconds...");
        await sleep (10000);
        let result = await client.personGroup.getTrainingStatus(person_group_id);
        console.log("Training status: " + result.status + ".");
        if (result.status !== "succeeded") {
            await WaitForPersonGroupTraining(person_group_id);
        }
    }
    
    /* NOTE This function might not work with the free tier of the Face service
    because it might exceed the rate limits. If that happens, try inserting calls
    to sleep() between calls to the Face service.
    */
    async function IdentifyInPersonGroup() {
        console.log("========IDENTIFY FACES========");
        console.log();
    
    // Create a dictionary for all your images, grouping similar ones under the same key.
        const person_dictionary = {
            "Family1-Dad" : ["Family1-Dad1.jpg", "Family1-Dad2.jpg"],
            "Family1-Mom" : ["Family1-Mom1.jpg", "Family1-Mom2.jpg"],
            "Family1-Son" : ["Family1-Son1.jpg", "Family1-Son2.jpg"],
            "Family1-Daughter" : ["Family1-Daughter1.jpg", "Family1-Daughter2.jpg"],
            "Family2-Lady" : ["Family2-Lady1.jpg", "Family2-Lady2.jpg"],
            "Family2-Man" : ["Family2-Man1.jpg", "Family2-Man2.jpg"]
        };
    
        // A group photo that includes some of the persons you seek to identify from your dictionary.
        let source_image_file_name = "identification1.jpg";
    
        
        // Create a person group. 
        console.log("Creating a person group with ID: " + person_group_id);
        await client.personGroup.create(person_group_id, person_group_id, {recognitionModel : "recognition_04" });
    
        await AddFacesToPersonGroup(person_dictionary, person_group_id);
    
        // Start to train the person group.
        console.log();
        console.log("Training person group: " + person_group_id + ".");
        await client.personGroup.train(person_group_id);
    
        await WaitForPersonGroupTraining(person_group_id);
        console.log();
    
        // Detect faces from source image url and only take those with sufficient quality for recognition.
        let face_ids = (await DetectFaceRecognize(image_base_url + source_image_file_name)).map (face => face.faceId);
        // Identify the faces in a person group.
        let results = await client.face.identify(face_ids, { personGroupId : person_group_id});
        await Promise.all (results.map (async function (result) {
            let person = await client.personGroupPerson.get(person_group_id, result.candidates[0].personId);
            console.log("Person: " + person.name + " is identified for face in: " + source_image_file_name + " with ID: " + result.faceId + ". Confidence: " + result.candidates[0].confidence + ".");
        }));
        console.log();
    }
    
    async function main() {
        await IdentifyInPersonGroup();
        console.log ("Done.");
    }
    main();
    
  4. Введите ключ и конечную точку в соответствующие поля.

    Важно!

    Перейдите на портал Azure. Если ресурс "Распознавание лиц", созданный в соответствии с указаниями в разделе Предварительные требования, успешно развернут, нажмите кнопку Перейти к ресурсу в разделе Дальнейшие действия. Ключ и конечная точка располагаются на странице ключа и конечной точки ресурса в разделе управления ресурсами.

    Важно!

    Не забудьте удалить ключ из кода, когда закончите, и никогда не публикуйте его в открытом доступе. Для рабочей среды рекомендуется использовать безопасный способ хранения и доступа к учетным данным. Дополнительные сведения см. в статье о безопасности в Cognitive Services.

  5. Запустите приложение, выполнив команду node для файла quickstart.

    node index.js
    

Выходные данные

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

Creating a person group with ID: c08484e0-044b-4610-8b7e-c957584e5d2d
Adding faces to person group...
Create a persongroup person: Family1-Dad.
Create a persongroup person: Family1-Mom.
Create a persongroup person: Family2-Lady.
Create a persongroup person: Family1-Son.
Create a persongroup person: Family1-Daughter.
Create a persongroup person: Family2-Man.
Add face to the person group person: (Family1-Son) from image: Family1-Son2.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-Mom1.jpg.
Add face to the person group person: (Family2-Man) from image: Family2-Man1.jpg.
Add face to the person group person: (Family1-Son) from image: Family1-Son1.jpg.
Add face to the person group person: (Family2-Lady) from image: Family2-Lady2.jpg.
Add face to the person group person: (Family1-Mom) from image: Family1-Mom2.jpg.
Add face to the person group person: (Family1-Dad) from image: Family1-Dad1.jpg.
Add face to the person group person: (Family2-Man) from image: Family2-Man2.jpg.
Add face to the person group person: (Family2-Lady) from image: Family2-Lady1.jpg.
Done adding faces to person group.

Training person group: c08484e0-044b-4610-8b7e-c957584e5d2d.
Waiting 10 seconds...
Training status: succeeded.

Person: Family1-Mom is identified for face in: identification1.jpg with ID: b7f7f542-c338-4a40-ad52-e61772bc6e14. Confidence: 0.96921.
Person: Family1-Son is identified for face in: identification1.jpg with ID: 600dc1b4-b2c4-4516-87de-edbbdd8d7632. Confidence: 0.92886.
Person: Family1-Dad is identified for face in: identification1.jpg with ID: e83b494f-9ad2-473f-9d86-3de79c01e345. Confidence: 0.96725.

Очистка ресурсов

Если вы хотите очистить и удалить подписку Cognitive Services, вы можете удалить ресурс или группу ресурсов. При этом удаляются все ресурсы, связанные с ней.

Дальнейшие действия

Из этого краткого руководство вы узнали, как с помощью клиентской библиотеки Распознавания лиц для JavaScript выполнять базовое распознавание лиц. Далее вы узнаете о различных моделях определения лиц и о том, как указать правильную модель для вашего варианта использования.

В этом руководстве показано, как начать работу с клиентской библиотекой API Распознавания лиц для Python. Выполните приведенные здесь действия, чтобы установить пакет и протестировать пример кода для выполнения базовых задач. В службе "Распознавание лиц" доступны передовые алгоритмы обнаружения и распознавания лиц на изображениях. Выполните следующие действия, чтобы установить пакет и опробовать пример кода для базовой идентификации лица с помощью удаленных изображений.

Справочная документация | Исходный код библиотеки | Пакет (PiPy) | Примеры

Предварительные требования

  • Подписка Azure — создайте бесплатную учетную запись.
  • Python 3.x
    • Установка Python должна включать pip. Чтобы проверить, установлен ли pip, выполните команду pip --version в командной строке. Чтобы использовать pip, установите последнюю версию Python.
  • Вашей учетной записи Azure должна быть назначена роль участника Cognitive Services, чтобы вы могли принять условия использования искусственного интеллекта и создать ресурс. Чтобы назначить эту роль своей учетной записи, следуйте инструкциям, описанным в документации по назначению ролей, или обратитесь к администратору.
  • Получив подписку Azure, создайте ресурс "Распознавание лиц" на портале Azure, чтобы получить ключ и конечную точку. После развертывания щелкните Перейти к ресурсам.
    • Для подключения приложения к API Распознавания лиц потребуется ключ и конечная точка из созданного ресурса. Ключ и конечная точка будут вставлены в приведенный ниже код в кратком руководстве.
    • Используйте бесплатную ценовую категорию (F0), чтобы опробовать службу, а затем выполните обновление до платного уровня для рабочей среды.

Идентификация лиц

  1. Установка клиентской библиотеки

    После установки Python вы можете установить клиентскую библиотеку с помощью следующей команды:

    pip install --upgrade azure-cognitiveservices-vision-face
    
  2. Создание приложения Python

    Создайте новый скрипт Python, напримерquickstart-file.py. Откройте его в редакторе или интегрированной среде разработки и вставьте следующий код.

    import asyncio
    import io
    import os
    import sys
    import time
    import uuid
    import requests
    from urllib.parse import urlparse
    from io import BytesIO
    # To install this module, run:
    # python -m pip install Pillow
    from PIL import Image, ImageDraw
    from azure.cognitiveservices.vision.face import FaceClient
    from msrest.authentication import CognitiveServicesCredentials
    from azure.cognitiveservices.vision.face.models import TrainingStatusType, Person, QualityForRecognition
    
    
    # This key will serve all examples in this document.
    KEY = "PASTE_YOUR_FACE_SUBSCRIPTION_KEY_HERE"
    
    # This endpoint will be used in all examples in this quickstart.
    ENDPOINT = "PASTE_YOUR_FACE_ENDPOINT_HERE"
    
    # Base url for the Verify and Facelist/Large Facelist operations
    IMAGE_BASE_URL = 'https://csdx.blob.core.windows.net/resources/Face/Images/'
    
    # Used in the Person Group Operations and Delete Person Group examples.
    # You can call list_person_groups to print a list of preexisting PersonGroups.
    # SOURCE_PERSON_GROUP_ID should be all lowercase and alphanumeric. For example, 'mygroupname' (dashes are OK).
    PERSON_GROUP_ID = str(uuid.uuid4()) # assign a random ID (or name it anything)
    
    # Used for the Delete Person Group example.
    TARGET_PERSON_GROUP_ID = str(uuid.uuid4()) # assign a random ID (or name it anything)
    
    # Create an authenticated FaceClient.
    face_client = FaceClient(ENDPOINT, CognitiveServicesCredentials(KEY))
    
    '''
    Create the PersonGroup
    '''
    # Create empty Person Group. Person Group ID must be lower case, alphanumeric, and/or with '-', '_'.
    print('Person group:', PERSON_GROUP_ID)
    face_client.person_group.create(person_group_id=PERSON_GROUP_ID, name=PERSON_GROUP_ID, recognition_model='recognition_04')
    
    # Define woman friend
    woman = face_client.person_group_person.create(PERSON_GROUP_ID, name="Woman")
    # Define man friend
    man = face_client.person_group_person.create(PERSON_GROUP_ID, name="Man")
    # Define child friend
    child = face_client.person_group_person.create(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://csdx.blob.core.windows.net/resources/Face/Images/Family1-Mom1.jpg", "https://csdx.blob.core.windows.net/resources/Face/Images/Family1-Mom2.jpg"]
    man_images = ["https://csdx.blob.core.windows.net/resources/Face/Images/Family1-Dad1.jpg", "https://csdx.blob.core.windows.net/resources/Face/Images/Family1-Dad2.jpg"]
    child_images = ["https://csdx.blob.core.windows.net/resources/Face/Images/Family1-Son1.jpg", "https://csdx.blob.core.windows.net/resources/Face/Images/Family1-Son2.jpg"]
    
    # 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.face.detect_with_url(url=image, detection_model='detection_03', recognition_model='recognition_04', return_face_attributes=['qualityForRecognition'])
        for face in detected_faces:
            if face.face_attributes.quality_for_recognition != QualityForRecognition.high:
                sufficientQuality = False
                break
            face_client.person_group_person.add_face_from_url(PERSON_GROUP_ID, woman.person_id, image)
            print("face {} added to person {}".format(face.face_id, woman.person_id))
    
        if not sufficientQuality: continue
    
    # 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.face.detect_with_url(url=image, detection_model='detection_03', recognition_model='recognition_04', return_face_attributes=['qualityForRecognition'])
        for face in detected_faces:
            if face.face_attributes.quality_for_recognition != QualityForRecognition.high:
                sufficientQuality = False
                break
            face_client.person_group_person.add_face_from_url(PERSON_GROUP_ID, man.person_id, image)
            print("face {} added to person {}".format(face.face_id, man.person_id))
    
        if not sufficientQuality: continue
    
    # 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.face.detect_with_url(url=image, detection_model='detection_03', recognition_model='recognition_04', return_face_attributes=['qualityForRecognition'])
        for face in detected_faces:
            if face.face_attributes.quality_for_recognition != QualityForRecognition.high:
                sufficientQuality = False
                print("{} has insufficient quality".format(face))
                break
            face_client.person_group_person.add_face_from_url(PERSON_GROUP_ID, child.person_id, image)
            print("face {} added to person {}".format(face.face_id, child.person_id))
        if not sufficientQuality: continue
    
    
    '''
    Train PersonGroup
    '''
    # Train the person group
    print("pg resource is {}".format(PERSON_GROUP_ID))
    rawresponse = face_client.person_group.train(PERSON_GROUP_ID, raw= True)
    print(rawresponse)
    
    while (True):
        training_status = face_client.person_group.get_training_status(PERSON_GROUP_ID)
        print("Training status: {}.".format(training_status.status))
        print()
        if (training_status.status is TrainingStatusType.succeeded):
            break
        elif (training_status.status is TrainingStatusType.failed):
            face_client.person_group.delete(person_group_id=PERSON_GROUP_ID)
            sys.exit('Training the person group has failed.')
        time.sleep(5)
    
    '''
    Identify a face against a defined PersonGroup
    '''
    # Group image for testing against
    test_image = "https://csdx.blob.core.windows.net/resources/Face/Images/identification1.jpg"
    
    print('Pausing for 10 seconds to avoid triggering rate limit on free account...')
    time.sleep (10)
    
    # Detect faces
    face_ids = []
    # We use detection model 3 to get better performance, recognition model 4 to support quality for recognition attribute.
    faces = face_client.face.detect_with_url(test_image, detection_model='detection_03', recognition_model='recognition_04', return_face_attributes=['qualityForRecognition'])
    for face in faces:
        # Only take the face if it is of sufficient quality.
        if face.face_attributes.quality_for_recognition == QualityForRecognition.high or face.face_attributes.quality_for_recognition == QualityForRecognition.medium:
            face_ids.append(face.face_id)
    
    # Identify faces
    results = face_client.face.identify(face_ids, PERSON_GROUP_ID)
    print('Identifying faces in image')
    if not results:
        print('No person identified in the person group')
    for person in results:
        if len(person.candidates) > 0:
            print('Person for face ID {} is identified in image, with a confidence of {}.'.format(person.face_id, person.candidates[0].confidence)) # Get topmost confidence score
        else:
            print('No person identified for face ID {} in image.'.format(person.face_id))
    
    print()
    print('End of quickstart.')
    
    
  3. Введите ключ и конечную точку в соответствующие поля.

    Важно!

    Перейдите на портал Azure. Если ресурс "Распознавание лиц", созданный в соответствии с указаниями в разделе Предварительные требования, успешно развернут, нажмите кнопку Перейти к ресурсу в разделе Дальнейшие действия. Ключ и конечная точка располагаются на странице ключа и конечной точки ресурса в разделе управления ресурсами.

    Важно!

    Не забудьте удалить ключ из кода, когда закончите, и никогда не публикуйте его в открытом доступе. Для рабочей среды рекомендуется использовать безопасный способ хранения и доступа к учетным данным. Дополнительные сведения см. в статье о безопасности в Cognitive Services.

  4. Запустите приложение распознавания лиц из каталога приложения с помощью команды python.

    python quickstart-file.py
    

    Совет

    API службы "Распознавание лиц" выполняется на наборе предварительно созданных моделей, которые по своей природе являются статическими (производительность модели не ухудшается и не улучшается при выполнении службы). Результаты, предоставляемые моделью, могут измениться, если корпорация Майкрософт обновит внутреннюю структуру модели без перехода на полностью новую версию модели. Чтобы воспользоваться преимуществами новой версии модели, вы можете повторно обучить PersonGroup, указав более новую модель в качестве параметра с такими же изображениями для регистрации.

Очистка ресурсов

Если вы хотите очистить и удалить подписку Cognitive Services, вы можете удалить ресурс или группу ресурсов. При этом удаляются все ресурсы, связанные с ней.

Чтобы удалить PersonGroup, выполните следующий код в скрипте.

# Delete the main person group.
face_client.person_group.delete(person_group_id=PERSON_GROUP_ID)
print("Deleted the person group {} from the source location.".format(PERSON_GROUP_ID))
print()

Дальнейшие действия

Из этого краткого руководство вы узнали, как с помощью клиентской библиотеки Распознавания лиц для Python выполнять базовое распознавание лиц. Далее вы узнаете о различных моделях определения лиц и о том, как указать правильную модель для вашего варианта использования.

Из этого руководства вы узнаете, как начать работу с REST API Распознавания лиц. В службе "Распознавание лиц" доступны передовые алгоритмы обнаружения и распознавания лиц на изображениях.

Примечание

В рамках этого краткого руководства для вызова REST API используются команды cURL. Вы также можете вызывать REST API с помощью языка программирования. Сложные сценарии, такие как идентификация лиц, проще реализовать с помощью языкового пакета SDK. Примеры см. в репозиториях GitHub для C#, Python, Java, JavaScript и Go.

Предварительные требования

  • Подписка Azure — создайте бесплатную учетную запись.
  • Вашей учетной записи Azure должна быть назначена роль участника Cognitive Services, чтобы вы могли принять условия использования искусственного интеллекта и создать ресурс. Чтобы назначить эту роль своей учетной записи, следуйте инструкциям, описанным в документации по назначению ролей, или обратитесь к администратору.
  • Получив подписку Azure, перейдите к созданию ресурса Распознавания лиц на портале Azure, чтобы получить ключ и конечную точку. После развертывания щелкните Перейти к ресурсам.
    • Для подключения приложения к API Распознавания лиц потребуется ключ и конечная точка из созданного ресурса. Ключ и конечная точка будут вставлены в приведенный ниже код в кратком руководстве.
    • Используйте бесплатную ценовую категорию (F0), чтобы опробовать службу, а затем выполните обновление до платного уровня для рабочей среды.
  • PowerShell версии 6.0 и выше или аналогичное приложение командной строки.

Идентификация лиц

  1. Сначала вызовите API обнаружения для исходного лица. Это лицо, которое мы попытаемся определить в более крупной группе. Скопируйте следующую команду в текстовый редактор, вставьте собственный ключ, а затем скопируйте его в окно оболочки и выполните его.

    curl -v -X POST "https://westus.api.cognitive.microsoft.com/face/v1.0/detect?returnFaceId=true&returnFaceLandmarks=false&returnFaceAttributes={string}&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://csdx.blob.core.windows.net/resources/Face/Images/identification1.jpg\"}"
    

    Сохраните возвращенную строку идентификатора лица во временном расположении. Вы будете использовать ее снова в конце.

  2. Далее необходимо создать LargePersonGroup. Этот объект будет хранить агрегированные данные о лицах нескольких человек. Выполните следующую команду, вставив собственный ключ. При необходимости измените имя и метаданные группы в тексте запроса.

    curl -v -X PUT "https://westus.api.cognitive.microsoft.com/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_03\"
    }"
    

    Сохраните возвращенный идентификатор созданной группы во временном расположении.

  3. Далее вы создадите объекты Person, принадлежащие группе. Выполните следующую команду, вставив собственный ключ и идентификатор LargePersonGroup из предыдущего шага. Эта команда создает объект Person с именем Family1-Dad.

    curl -v -X POST "https://westus.api.cognitive.microsoft.com/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.\"
    }"
    

    После выполнения этой команды запустите ее еще раз с другими входными данными, чтобы создать другие объекты Person: Family1-Mom, Family1-Son, Family1-Daughter, Family2-Lady и Family2-Man.

    Сохраните идентификаторы каждого созданного объекта Person. Важно отслеживать связь между именем человеком и идентификатором.

  4. Далее необходимо обнаружить новые лица и связать их с существующими объектами Person. Следующая команда обнаруживает лицо на изображении Family1-Dad.jpg и добавляет его для соответствующего человека. Вам необходимо указать personId в качестве идентификатора, который был возвращен при создании объекта Person Family1-Dad. Имя изображения соответствует имени созданного объекта Person. Также введите идентификатор LargePersonGroup и ключ в соответствующие поля.

    curl -v -X POST "https://westus.api.cognitive.microsoft.com/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://csdx.blob.core.windows.net/resources/Face/Images/Family1-Dad.jpg\"}"
    

    Затем снова выполните приведенную выше команду с другим исходным изображением и целевым объектом Person. Доступны следующие изображения: 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.jpg и Family2-Man2.jpg. Убедитесь, что объект Person, идентификатор которого вы указываете в вызове API, совпадает с именем файла изображения в тексте запроса.

    В конце этого шага должно быть несколько объектов Person, каждый из которых имеет одно или несколько соответствующих лиц, обнаруженных непосредственно на предоставленных изображениях.

  5. Затем мы обучим LargePersonGroup с использованием текущих данных о лицах. Операция обучения обучает модель тому, как связать признаки лица, иногда агрегированные из нескольких исходных изображений, с каждым отдельным человеком. Вставьте идентификатор LargePersonGroup и ключ перед выполнением команды.

    curl -v -X POST "https://westus.api.cognitive.microsoft.com/face/v1.0/largepersongroups/{largePersonGroupId}/train" -H "Ocp-Apim-Subscription-Key: {subscription key}"
    
  6. Теперь вы готовы вызвать API идентификации, используя исходный идентификатор лица с первого шага и идентификатор LargePersonGroup. Вставьте эти значения в соответствующие поля в тексте запроса, а затем вставьте ключ.

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

    Ответ должен вернуть идентификатор объекта Person, указывающий на человека, для которого определено исходное лицо. Это должен быть идентификатор, соответствующий человеку Family1-Dad, так как исходное лицо принадлежит этому человеку.

Очистка ресурсов

Чтобы удалить LargePersonGroup, выполните вызов LargePersonGroup - Delete.

curl -v -X DELETE "https://westus.api.cognitive.microsoft.com/face/v1.0/largepersongroups/{largePersonGroupId}" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Если вы хотите очистить и удалить подписку Cognitive Services, вы можете удалить ресурс или группу ресурсов. При этом удаляются все ресурсы, связанные с ней.

Дальнейшие действия

Из этого краткого руководства вы узнали, как с помощью REST API Распознавания лиц выполнять базовые задачи по распознаванию лиц. Далее вы узнаете о различных моделях определения лиц и о том, как указать правильную модель для вашего варианта использования.

Используйте Vision Studio для идентификации лица. Это упрощенная версия функции идентификации лица: вы можете обучить модель только на одном человеке, а затем проверить, соответствует ли ему новое лицо. Обычно вы обучаете модель на нескольких людях, а затем проверяете новое изображение на всех. Чтобы выполнить полный сценарий идентификации, используйте REST API или клиентский пакет SDK.

Предварительные требования

  • Войдите в Vision Studio с использованием подписки Azure и ресурса Cognitive Services. Если вам нужна помощь с этим шагом, ознакомьтесь с разделом Начало работы.
  • Вам понадобится как минимум три изображения лица человека: два или более для обучения модели и одно для ее тестирования.

Идентификация лиц

  1. Перейдите на вкладку Анализ лиц и выберите панель Распознать определенного человека.
  2. Чтобы использовать пробный вариант, вам нужно будет выбрать ресурс и подтвердить, что он будет использоваться в соответствии с вашей ценовой категорией.
  3. Затем вы присвоите человеку имя и отправите изображения его лица. Затем выберите Зарегистрировать лицо и дождитесь завершения обучения модели.
  4. Наконец, отправьте еще одно изображение в область внизу, и служба определит, принадлежит ли оно тому человеку, для которого выполнено обучение.
  5. Сведения о результатах соответствия и оценках достоверности см. в области Обнаруженные атрибуты.
  6. Ниже описаны дальнейшие шаги по использованию этой возможности в вашем приложении.

Дальнейшие действия

Из этого краткого руководства вы узнали, как с помощью Vision Studio выполнять базовые задачи по распознаванию лиц. Далее вы узнаете о различных моделях определения лиц и о том, как указать правильную модель для вашего варианта использования.