빠른 시작: Face 클라이언트 라이브러리 사용Quickstart: Use the Face client library

.NET용 Face 클라이언트 라이브러리를 사용하여 얼굴 인식을 시작합니다.Get started with facial recognition using the Face client library for .NET. 이러한 단계에 따라 패키지를 설치하고 기본 작업을 위한 예제 코드를 사용해 봅니다.Follow these steps to install the package and try out the example code for basic tasks. Face 서비스는 이미지에서 사람의 얼굴을 감지하고 인식하기 위한 고급 알고리즘에 대한 액세스를 제공합니다.The Face service provides you with access to advanced algorithms for detecting and recognizing human faces in images.

.NET용 Face 클라이언트 라이브러리를 사용하여 다음을 수행합니다.Use the Face client library for .NET to:

참조 설명서 | 라이브러리 소스 코드 | 패키지(NuGet) | 샘플Reference documentation | Library source code | Package (NuGet) | Samples

사전 요구 사항Prerequisites

  • Azure 구독 - 체험 구독 만들기Azure subscription - Create one for free
  • Visual Studio IDE 또는 현재 버전의 .NET Core.The Visual Studio IDE or current version of .NET Core.
  • Azure 구독을 보유한 후에는 Azure Portal에서 Face 리소스 를 만들어 키와 엔드포인트를 가져옵니다.Once you have your Azure subscription, create a Face resource in the Azure portal to get your key and endpoint. 배포 후 리소스로 이동 을 클릭합니다.After it deploys, click Go to resource.
    • 애플리케이션을 Face API에 연결하려면 만든 리소스의 키와 엔드포인트가 필요합니다.You will need the key and endpoint from the resource you create to connect your application to the Face API. 이 빠른 시작의 뒷부분에 나오는 코드에 키와 엔드포인트를 붙여넣습니다.You'll paste your key and endpoint into the code below later in the quickstart.
    • 평가판 가격 책정 계층(F0)을 통해 서비스를 사용해보고, 나중에 프로덕션용 유료 계층으로 업그레이드할 수 있습니다.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

설치Setting up

새 C# 애플리케이션 만들기Create a new C# application

Visual Studio를 사용하여 새 .NET Core 애플리케이션을 만듭니다.Using Visual Studio, create a new .NET Core application.

클라이언트 라이브러리 설치Install the client library

새 프로젝트를 만든 후 솔루션 탐색기 에서 프로젝트 솔루션을 마우스 오른쪽 단추로 클릭하고 NuGet 패키지 관리 를 선택하여 클라이언트 라이브러리를 설치합니다.Once you've created a new project, install the client library by right-clicking on the project solution in the Solution Explorer and selecting Manage NuGet Packages. 열리는 패키지 관리자에서 찾아보기 를 선택하고, 시험판 포함 을 선택하고, Microsoft.Azure.CognitiveServices.Vision.Face를 검색합니다.In the package manager that opens select Browse, check Include prerelease, and search for Microsoft.Azure.CognitiveServices.Vision.Face. 2.6.0-preview.1 버전, 설치 를 차례로 선택합니다.Select version 2.6.0-preview.1, and then Install.

한 번에 전체 빠른 시작 코드 파일을 보시겠습니까?Want to view the whole quickstart code file at once? GitHub에서 찾을 수 있으며 이 빠른 시작의 코드 예제를 포함합니다.You can find it on GitHub, which contains the code examples in this quickstart.

프로젝트 디렉터리에서 program.cs 파일을 열고 using 지시문을 추가합니다.From the project directory, open the program.cs file and add the following using directives:

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;

애플리케이션의 Program 클래스에서 리소스의 키 및 엔드포인트에 대한 변수를 만듭니다.In the application's Program class, create variables for your resource's key and endpoint.

중요

Azure Portal로 이동합니다.Go to the Azure portal. 필수 구성 요소 섹션에서 만든 [제품 이름] 리소스가 성공적으로 배포된 경우 다음 단계 아래에서 리소스로 이동 단추를 클릭합니다.If the [Product name] resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. 리소스 관리 아래에 있는 리소스의 키 및 엔드포인트 페이지에서 키 및 엔드포인트를 찾을 수 있습니다.You can find your key and endpoint in the resource's key and endpoint page, under resource management.

완료되면 코드에서 키를 제거하고 공개적으로 게시하지 마세요.Remember to remove the key from your code when you're done, and never post it publicly. 프로덕션의 경우 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용하는 것이 좋습니다.For production, consider using a secure way of storing and accessing your credentials. 자세한 내용은 Cognitive Services 보안 문서를 참조하세요.See the Cognitive Services security article for more information.

// From your Face subscription in the Azure portal, get your subscription key and endpoint.
const string SUBSCRIPTION_KEY = "<your subscription key>";
const string ENDPOINT = "<your api endpoint>";

애플리케이션의 Main 메서드에서 이 빠른 시작에 사용된 메서드에 대한 호출을 추가합니다.In the application's Main method, add calls for the methods used in this quickstart. 이러한 기능은 나중에 구현합니다.You will implement these later.

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

// Detect - get features from faces.
DetectFaceExtract(client, IMAGE_BASE_URL, RECOGNITION_MODEL3).Wait();
// Find Similar - find a similar face from a list of faces.
FindSimilar(client, IMAGE_BASE_URL, RECOGNITION_MODEL3).Wait();
// Verify - compare two images if the same person or not.
Verify(client, IMAGE_BASE_URL, RECOGNITION_MODEL3).Wait();

// Identify - recognize a face(s) in a person group (a person group is created in this example).
IdentifyInPersonGroup(client, IMAGE_BASE_URL, RECOGNITION_MODEL3).Wait();
// LargePersonGroup - create, then get data.
LargePersonGroup(client, IMAGE_BASE_URL, RECOGNITION_MODEL3).Wait();
// Group faces - automatically group similar faces.
Group(client, IMAGE_BASE_URL, RECOGNITION_MODEL3).Wait();
// FaceList - create a face list, then get data

개체 모델Object model

Face .NET 클라이언트 라이브러리의 주요 기능 중 일부를 처리하는 클래스와 인터페이스는 다음과 같습니다.The following classes and interfaces handle some of the major features of the Face .NET client library:

NameName DescriptionDescription
FaceClientFaceClient 이 클래스는 Face 서비스를 사용할 수 있는 권한의 부여를 나타내며 모든 Face 기능에 필요합니다.This class represents your authorization to use the Face service, and you need it for all Face functionality. 구독 정보를 사용하여 인스턴스화하고, 다른 클래스의 인스턴스를 생성하는 데 사용합니다.You instantiate it with your subscription information, and you use it to produce instances of other classes.
FaceOperationsFaceOperations 이 클래스는 사람 얼굴을 사용하여 수행할 수 있는 기본 감지 및 인식 작업을 처리합니다.This class handles the basic detection and recognition tasks that you can do with human faces.
DetectedFaceDetectedFace 이 클래스는 이미지의 한 얼굴에서 감지된 모든 데이터를 나타냅니다.This class represents all of the data that was detected from a single face in an image. 얼굴에 대한 자세한 정보를 검색하는 데 사용할 수 있습니다.You can use it to retrieve detailed information about the face.
FaceListOperationsFaceListOperations 이 클래스는 분류된 얼굴 세트를 저장하는 클라우드 저장 FaceList 구문을 관리합니다.This class manages the cloud-stored FaceList constructs, which store an assorted set of faces.
PersonGroupPersonExtensionsPersonGroupPersonExtensions 이 클래스는 한 사람에게 속한 얼굴 세트를 저장하는 클라우드 저장 Person 구문을 관리합니다.This class manages the cloud-stored Person constructs, which store a set of faces that belong to a single person.
PersonGroupOperationsPersonGroupOperations 이 클래스는 분류된 Person 개체 세트를 저장하는 클라우드 저장 PersonGroup 구문을 관리합니다.This class manages the cloud-stored PersonGroup constructs, which store a set of assorted Person objects.

코드 예제Code examples

아래 코드 조각에서는 .NET용 Face 클라이언트 라이브러리를 사용하여 다음 작업을 수행하는 방법을 보여 줍니다.The code snippets below show you how to do the following tasks with the Face client library for .NET:

클라이언트 인증Authenticate the client

새 메서드에서 엔드포인트 및 키를 사용하여 클라이언트를 인스턴스화합니다.In a new method, instantiate a client with your endpoint and key. 키를 사용하여 ApiKeyServiceClientCredentials 개체를 만들고, 엔드포인트에서 이를 사용하여 FaceClient 개체를 만듭니다.Create a ApiKeyServiceClientCredentials object with your key, and use it with your endpoint to create a FaceClient object.

/*
 *	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 };
}

도우미 필드 선언Declare helper fields

다음 필드는 나중에 추가할 몇 가지 얼굴 작업에 필요합니다.The following fields are needed for several of the Face operations you'll add later. Program 클래스의 루트에서 다음 URL 문자열을 정의합니다.At the root of your Program class, define the following URL string. 이 URL은 샘플 이미지 폴더를 가리킵니다.This URL points to a folder of sample images.

// Used for all examples.
// URL for the images.
const string IMAGE_BASE_URL = "https://csdx.blob.core.windows.net/resources/Face/Images/";

Main 메서드에서 다른 인식 모델 유형을 가리키는 문자열을 정의합니다.In your Main method, define strings to point to the different recognition model types. 나중에 얼굴 감지에 사용할 인식 모델을 지정할 수 있습니다.Later on, you'll be able to specify which recognition model you want to use for face detection. 이러한 옵션에 대한 자세한 내용은 인식 모델 지정을 참조하세요.See Specify a recognition model for information on these options.

// Recognition model 3 was released in 2020 May.
// It is recommended since its overall accuracy is improved
// compared with models 1 and 2.
const string RECOGNITION_MODEL3 = RecognitionModel.Recognition03;

이미지에서 얼굴 감지Detect faces in an image

검색된 얼굴 개체 가져오기Get detected face objects

얼굴을 감지하는 새 메서드를 만듭니다.Create a new method to detect faces. DetectFaceExtract 메서드는 지정된 URL에서 세 개의 이미지를 처리하고 DetectedFace 개체의 목록을 프로그램 메모리에 만듭니다.The DetectFaceExtract method processes three of the images at the given URL and creates a list of DetectedFace objects in program memory. FaceAttributeType 값 목록은 추출할 기능을 지정합니다.The list of FaceAttributeType values specifies which features to extract.

/* 
 * DETECT FACES
 * Detects features from faces and IDs them.
 */
public static async Task DetectFaceExtract(IFaceClient client, string url, string recognitionModel)
{
    Console.WriteLine("========DETECT FACES========");
    Console.WriteLine();

    // Create a list of images
    List<string> imageFileNames = new List<string>
                    {
                        "detection1.jpg",    // single female with glasses
                        // "detection2.jpg", // (optional: single man)
                        // "detection3.jpg", // (optional: single male construction worker)
                        // "detection4.jpg", // (optional: 3 people at cafe, 1 is blurred)
                        "detection5.jpg",    // family, woman child man
                        "detection6.jpg"     // elderly couple, male female
                    };

    foreach (var imageFileName in imageFileNames)
    {
        IList<DetectedFace> detectedFaces;

        // Detect faces with all attributes from image url.
        detectedFaces = await client.Face.DetectWithUrlAsync($"{url}{imageFileName}",
                returnFaceAttributes: new List<FaceAttributeType?> { FaceAttributeType.Accessories, FaceAttributeType.Age,
                FaceAttributeType.Blur, FaceAttributeType.Emotion, FaceAttributeType.Exposure, FaceAttributeType.FacialHair,
                FaceAttributeType.Gender, FaceAttributeType.Glasses, FaceAttributeType.Hair, FaceAttributeType.HeadPose,
                FaceAttributeType.Makeup, FaceAttributeType.Noise, FaceAttributeType.Occlusion, FaceAttributeType.Smile },
                // We specify detection model 1 because we are retrieving attributes.
                detectionModel: DetectionModel.Detection01,
                recognitionModel: recognitionModel);

        Console.WriteLine($"{detectedFaces.Count} face(s) detected from image `{imageFileName}`.");

로컬 이미지에서 얼굴을 검색할 수도 있습니다.You can also detect faces in a local image. IFaceOperations 메서드(예: DetectWithStreamAsync)를 참조하세요.See the IFaceOperations methods such as DetectWithStreamAsync.

검색된 얼굴 데이터 표시Display detected face data

나머지 DetectFaceExtract 메서드는 검색된 각 얼굴에 대한 특성 데이터를 구문 분석하고 출력합니다.The rest of the DetectFaceExtract method parses and prints the attribute data for each detected face. 각 특성은 원래 얼굴 검색 API 호출( FaceAttributeType 목록의)에서 별도로 지정해야 합니다.Each attribute must be specified separately in the original face detection API call (in the FaceAttributeType list). 다음 코드는 모든 특성을 처리하지만 하나 또는 몇 가지를 사용해야 할 가능성이 높습니다.The following code processes every attribute, but you will likely only need to use one or a few.

        // Parse and print all attributes of each detected face.
        foreach (var face in detectedFaces)
        {
            Console.WriteLine($"Face attributes for {imageFileName}:");

            // Get bounding box of the faces
            Console.WriteLine($"Rectangle(Left/Top/Width/Height) : {face.FaceRectangle.Left} {face.FaceRectangle.Top} {face.FaceRectangle.Width} {face.FaceRectangle.Height}");

            // Get accessories of the faces
            List<Accessory> accessoriesList = (List<Accessory>)face.FaceAttributes.Accessories;
            int count = face.FaceAttributes.Accessories.Count;
            string accessory; string[] accessoryArray = new string[count];
            if (count == 0) { accessory = "NoAccessories"; }
            else
            {
                for (int i = 0; i < count; ++i) { accessoryArray[i] = accessoriesList[i].Type.ToString(); }
                accessory = string.Join(",", accessoryArray);
            }
            Console.WriteLine($"Accessories : {accessory}");

            // Get face other attributes
            Console.WriteLine($"Age : {face.FaceAttributes.Age}");
            Console.WriteLine($"Blur : {face.FaceAttributes.Blur.BlurLevel}");

            // Get emotion on the face
            string emotionType = string.Empty;
            double emotionValue = 0.0;
            Emotion emotion = face.FaceAttributes.Emotion;
            if (emotion.Anger > emotionValue) { emotionValue = emotion.Anger; emotionType = "Anger"; }
            if (emotion.Contempt > emotionValue) { emotionValue = emotion.Contempt; emotionType = "Contempt"; }
            if (emotion.Disgust > emotionValue) { emotionValue = emotion.Disgust; emotionType = "Disgust"; }
            if (emotion.Fear > emotionValue) { emotionValue = emotion.Fear; emotionType = "Fear"; }
            if (emotion.Happiness > emotionValue) { emotionValue = emotion.Happiness; emotionType = "Happiness"; }
            if (emotion.Neutral > emotionValue) { emotionValue = emotion.Neutral; emotionType = "Neutral"; }
            if (emotion.Sadness > emotionValue) { emotionValue = emotion.Sadness; emotionType = "Sadness"; }
            if (emotion.Surprise > emotionValue) { emotionType = "Surprise"; }
            Console.WriteLine($"Emotion : {emotionType}");

            // Get more face attributes
            Console.WriteLine($"Exposure : {face.FaceAttributes.Exposure.ExposureLevel}");
            Console.WriteLine($"FacialHair : {string.Format("{0}", face.FaceAttributes.FacialHair.Moustache + face.FaceAttributes.FacialHair.Beard + face.FaceAttributes.FacialHair.Sideburns > 0 ? "Yes" : "No")}");
            Console.WriteLine($"Gender : {face.FaceAttributes.Gender}");
            Console.WriteLine($"Glasses : {face.FaceAttributes.Glasses}");

            // Get hair color
            Hair hair = face.FaceAttributes.Hair;
            string color = null;
            if (hair.HairColor.Count == 0) { if (hair.Invisible) { color = "Invisible"; } else { color = "Bald"; } }
            HairColorType returnColor = HairColorType.Unknown;
            double maxConfidence = 0.0f;
            foreach (HairColor hairColor in hair.HairColor)
            {
                if (hairColor.Confidence <= maxConfidence) { continue; }
                maxConfidence = hairColor.Confidence; returnColor = hairColor.Color; color = returnColor.ToString();
            }
            Console.WriteLine($"Hair : {color}");

            // Get more attributes
            Console.WriteLine($"HeadPose : {string.Format("Pitch: {0}, Roll: {1}, Yaw: {2}", Math.Round(face.FaceAttributes.HeadPose.Pitch, 2), Math.Round(face.FaceAttributes.HeadPose.Roll, 2), Math.Round(face.FaceAttributes.HeadPose.Yaw, 2))}");
            Console.WriteLine($"Makeup : {string.Format("{0}", (face.FaceAttributes.Makeup.EyeMakeup || face.FaceAttributes.Makeup.LipMakeup) ? "Yes" : "No")}");
            Console.WriteLine($"Noise : {face.FaceAttributes.Noise.NoiseLevel}");
            Console.WriteLine($"Occlusion : {string.Format("EyeOccluded: {0}", face.FaceAttributes.Occlusion.EyeOccluded ? "Yes" : "No")} " +
                $" {string.Format("ForeheadOccluded: {0}", face.FaceAttributes.Occlusion.ForeheadOccluded ? "Yes" : "No")}   {string.Format("MouthOccluded: {0}", face.FaceAttributes.Occlusion.MouthOccluded ? "Yes" : "No")}");
            Console.WriteLine($"Smile : {face.FaceAttributes.Smile}");
            Console.WriteLine();
        }
    }
}

유사 얼굴 찾기Find similar faces

다음 코드에서는 감지된 하나의 얼굴(원본)을 가져오고, 다른 얼굴(대상) 세트를 검색하여 일치 항목을 찾습니다(이미지별 얼굴 검색).The following code takes a single detected face (source) and searches a set of other faces (target) to find matches (face search by image). 일치 항목을 찾으면 일치하는 얼굴의 ID를 콘솔에 출력합니다.When it finds a match, it prints the ID of the matched face to the console.

비교할 얼굴 감지Detect faces for comparison

먼저 두 번째 얼굴 감지 메서드를 정의합니다.First, define a second face detection method. 이미지를 비교하기 전에 이미지에서 얼굴을 감지해야 하며, 이 감지 메서드는 비교 작업에 최적화되어 있습니다.You need to detect faces in images before you can compare them, and this detection method is optimized for comparison operations. 위의 섹션과 같이 자세한 얼굴 특성을 추출하지 않으며 다른 인식 모델을 사용합니다.It doesn't extract detailed face attributes like in the section above, and it uses a different recognition model.

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 2 because we are not retrieving attributes.
    IList<DetectedFace> detectedFaces = await faceClient.Face.DetectWithUrlAsync(url, recognitionModel: recognition_model, detectionModel: DetectionModel.Detection02);
    Console.WriteLine($"{detectedFaces.Count} face(s) detected from image `{Path.GetFileName(url)}`");
    return detectedFaces.ToList();
}

일치 항목 찾기Find matches

다음 메서드는 대상 이미지 세트와 단일 원본 이미지에서 얼굴을 감지합니다.The following method detects faces in a set of target images and in a single source image. 그런 다음, 이를 비교하여 원본 이미지와 유사한 모든 대상 이미지를 찾습니다.Then, it compares them and finds all the target images that are similar to the source image.

/*
 * FIND SIMILAR
 * This example will take an image and find a similar one to it in another image.
 */
public static async Task FindSimilar(IFaceClient client, string url, string recognition_model)
{
    Console.WriteLine("========FIND SIMILAR========");
    Console.WriteLine();

    List<string> targetImageFileNames = new List<string>
                        {
                            "Family1-Dad1.jpg",
                            "Family1-Daughter1.jpg",
                            "Family1-Mom1.jpg",
                            "Family1-Son1.jpg",
                            "Family2-Lady1.jpg",
                            "Family2-Man1.jpg",
                            "Family3-Lady1.jpg",
                            "Family3-Man1.jpg"
                        };

    string sourceImageFileName = "findsimilar.jpg";
    IList<Guid?> targetFaceIds = new List<Guid?>();
    foreach (var targetImageFileName in targetImageFileNames)
    {
        // Detect faces from target image url.
        var faces = await DetectFaceRecognize(client, $"{url}{targetImageFileName}", recognition_model);
        // Add detected faceId to list of GUIDs.
        targetFaceIds.Add(faces[0].FaceId.Value);
    }

    // Detect faces from source image url.
    IList<DetectedFace> detectedFaces = await DetectFaceRecognize(client, $"{url}{sourceImageFileName}", recognition_model);
    Console.WriteLine();

    // Find a similar face(s) in the list of IDs. Comapring only the first in list for testing purposes.
    IList<SimilarFace> similarResults = await client.Face.FindSimilarAsync(detectedFaces[0].FaceId.Value, null, null, targetFaceIds);

다음 코드에서는 일치 항목 세부 정보를 콘솔에 출력합니다.The following code prints the match details to the console:

foreach (var similarResult in similarResults)
{
    Console.WriteLine($"Faces from {sourceImageFileName} & ID:{similarResult.FaceId} are similar with confidence: {similarResult.Confidence}.");
}
Console.WriteLine();

얼굴 식별Identify a face

Identify(식별) 작업은 사람(또는 여러 사람)의 이미지를 가져와서 이미지에서 각 얼굴의 ID를 찾습니다(얼굴 인식 검색).The Identify operation takes an image of a person (or multiple people) and looks to find the identity of each face in the image (facial recognition search). 감지된 각 얼굴을 얼굴 특징이 알려진 다른 Person 개체의 데이터베이스인 PersonGroup 과 비교합니다.It compares each detected face to a PersonGroup, a database of different Person objects whose facial features are known. 식별 작업을 수행하려면 먼저 PersonGroup 을 만들고 학습해야 합니다.In order to do the Identify operation, you first need to create and train a PersonGroup

사용자 그룹 만들기Create a person group

다음 코드에서는 6개의 서로 다른 Person 개체를 사용하여 PersonGroup 을 만듭니다.The following code creates a PersonGroup with six different Person objects. Person 을 예제 이미지 세트와 연결한 다음, 해당 얼굴 특성을 통해 각 사람을 인식하도록 학습시킵니다.It associates each Person with a set of example images, and then it trains to recognize each person by their facial characteristics. PersonPersonGroup 개체는 Verify(검증), Identify(식별) 및 Group(그룹) 작업에 사용됩니다.Person and PersonGroup objects are used in the Verify, Identify, and Group operations.

PersonGroup 의 ID를 나타내도록 클래스의 루트에서 문자열 변수를 선언합니다.Declare a string variable at the root of your class to represent the ID of the PersonGroup you'll create.

static string personGroupId = Guid.NewGuid().ToString();

새 메서드에서 다음 코드를 추가합니다.In a new method, add the following code. 이 메서드는 식별 작업을 수행합니다.This method will carry out the Identify operation. 첫 번째 코드 블록은 사람의 이름을 해당 예제 이미지와 연결합니다.The first block of code associates the names of persons with their example images.

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

이 코드는 sourceImageFileName 변수를 정의합니다.Notice that this code defines a variable sourceImageFileName. 이 변수는 식별할 사람이 포함된 원본 이미지에 해당합니다.This variable corresponds to the source image—the image that contains people to identify.

다음으로, 다음 코드를 추가하여 Dictionary(사전)의 각 사람에 대한 Person 개체를 만들고 적절한 이미지에서 얼굴 데이터를 추가합니다.Next, add the following code to create a Person object for each person in the Dictionary and add the face data from the appropriate images. Person 개체는 고유 ID 문자열을 통해 동일한 PersonGroup 과 연결됩니다.Each Person object is associated with the same PersonGroup through its unique ID string. client, urlRECOGNITION_MODEL1 변수를 이 메서드에 전달해야 합니다.Remember to pass the variables client, url, and RECOGNITION_MODEL1 into this method.

// 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($"Add face to the person group person({groupedFace}) from image `{similarImage}`");
        PersistedFace face = await client.PersonGroupPerson.AddFaceFromUrlAsync(personGroupId, person.PersonId,
            $"{url}{similarImage}", similarImage);
    }
}

로컬 이미지에서 PersonGroup 을 만들 수도 있습니다.You can also create a PersonGroup from local images. IPersonGroupPerson 메서드(예: AddFaceFromStreamAsync)를 참조하세요.See the IPersonGroupPerson methods such as AddFaceFromStreamAsync.

PersonGroup 학습Train the PersonGroup

이미지에서 얼굴 데이터를 추출하여 다른 Person 개체에 정렬했으면 각 Person 개체와 연결된 시각적 기능을 식별하도록 PersonGroup 을 학습시켜야 합니다.Once you've extracted face data from your images and sorted it into different Person objects, you must train the PersonGroup to identify the visual features associated with each of its Person objects. 다음 코드에서는 비동기 train 메서드를 호출하고, 결과를 폴링하여 상태를 콘솔에 출력합니다.The following code calls the asynchronous train method and polls the results, printing the status to the console.

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

Face API는 기본적으로 정적인 사전 빌드된 모델 세트에서 실행됩니다(서비스가 실행될 때 모델의 성능이 저하되거나 향상되지 않음).The Face API runs on a set of pre-built models that are static by nature (the model's performance will not regress or improve as the service is run). Microsoft에서 완전히 새로운 모델 버전으로 마이그레이션하지 않고 모델의 백엔드를 업데이트하면 모델이 생성하는 결과가 변경될 수 있습니다.The results that the model produces might change if Microsoft updates the model's backend without migrating to an entirely new model version. 최신 버전의 모델을 사용하려면 PersonGroup 을 동일한 등록 이미지를 가진 매개 변수로 지정하여 다시 학습할 수 있습니다.To take advantage of a newer version of a model, you can retrain your PersonGroup, specifying the newer model as a parameter with the same enrollment images.

이제 이 Person 그룹 및 연결된 해당 Person 개체는 Verify(검증), Identify(식별) 또는 Group(그룹) 작업에 사용할 수 있습니다.This Person group and its associated Person objects are now ready to be used in the Verify, Identify, or Group operations.

얼굴 식별Identify faces

다음 코드에서는 원본 이미지를 가져와서 이미지에서 감지된 모든 얼굴의 목록을 만듭니다.The following code takes the source image and creates a list of all the faces detected in the image. 이러한 얼굴은 PersonGroup 과 비교하여 식별되는 얼굴입니다.These are the faces that will be identified against the PersonGroup.

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

다음 코드 조각에서는 IdentifyAsync 작업을 호출하고 결과를 콘솔에 출력합니다.The next code snippet calls the IdentifyAsync operation and prints the results to the console. 여기서는 서비스에서 원본 이미지의 각 얼굴을 지정된 PersonGroupPerson 과 일치시키려고 합니다.Here, the service attempts to match each face from the source image to a Person in the given PersonGroup. 이렇게 하면 Identify 메서드가 종료됩니다.This closes out your Identify method.

    // Identify the faces in a person group. 
    var identifyResults = await client.Face.IdentifyAsync(sourceFaceIds, personGroupId);

    foreach (var identifyResult in identifyResults)
    {
        Person person = await client.PersonGroupPerson.GetAsync(personGroupId, identifyResult.Candidates[0].PersonId);
        Console.WriteLine($"Person '{person.Name}' is identified for face in: {sourceImageFileName} - {identifyResult.FaceId}," +
            $" confidence: {identifyResult.Candidates[0].Confidence}.");
    }
    Console.WriteLine();
}

애플리케이션 실행Run the application

IDE 창의 위쪽에서 디버그 단추를 클릭하여 애플리케이션을 실행합니다.Run the application by clicking the Debug button at the top of the IDE window.

리소스 정리Clean up resources

Cognitive Services 구독을 정리하고 제거하려면 리소스나 리소스 그룹을 삭제하면 됩니다.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. 리소스 그룹을 삭제하면 해당 리소스 그룹에 연결된 다른 모든 리소스가 함께 삭제됩니다.Deleting the resource group also deletes any other resources associated with it.

이 빠른 시작에서는 PersonGroup 을 만들었으며, 이를 삭제하려면 프로그램에서 다음 코드를 실행합니다.If you created a PersonGroup in this quickstart and you want to delete it, run the following code in your program:

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

다음 코드를 사용하여 삭제 메서드를 정의합니다.Define the deletion method with the following code:

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

다음 단계Next steps

이 빠른 시작에서는 .NET용 Face 클라이언트 라이브러리를 사용하여 기본 얼굴 인식 작업을 수행하는 방법을 알아보았습니다.In this quickstart, you learned how to use the Face client library for .NET to do basic facial recognition tasks. 다음으로 라이브러리에 대해 자세히 알아보려면 참조 설명서를 살펴보세요.Next, explore the reference documentation to learn more about the library.

Python용 Face 클라이언트 라이브러리를 사용하여 얼굴 인식을 시작합니다.Get started with facial recognition using the Face client library for Python. 이러한 단계에 따라 패키지를 설치하고 기본 작업을 위한 예제 코드를 사용해 봅니다.Follow these steps to install the package and try out the example code for basic tasks. Face 서비스는 이미지에서 사람의 얼굴을 감지하고 인식하기 위한 고급 알고리즘에 대한 액세스를 제공합니다.The Face service provides you with access to advanced algorithms for detecting and recognizing human faces in images.

Python용 Face 클라이언트 라이브러리를 사용하여 다음을 수행합니다.Use the Face client library for Python to:

참조 설명서 | 라이브러리 소스 코드 | 패키지(PiPy) | 샘플Reference documentation | Library source code | Package (PiPy) | Samples

사전 요구 사항Prerequisites

  • Azure 구독 - 체험 구독 만들기Azure subscription - Create one for free
  • Python 3.xPython 3.x
  • Azure 구독을 보유한 후에는 Azure Portal에서 Face 리소스 를 만들어 키와 엔드포인트를 가져옵니다.Once you have your Azure subscription, create a Face resource in the Azure portal to get your key and endpoint. 배포 후 리소스로 이동 을 클릭합니다.After it deploys, click Go to resource.
    • 애플리케이션을 Face API에 연결하려면 만든 리소스의 키와 엔드포인트가 필요합니다.You will need the key and endpoint from the resource you create to connect your application to the Face API. 이 빠른 시작의 뒷부분에 나오는 코드에 키와 엔드포인트를 붙여넣습니다.You'll paste your key and endpoint into the code below later in the quickstart.
    • 평가판 가격 책정 계층(F0)을 통해 서비스를 사용해보고, 나중에 프로덕션용 유료 계층으로 업그레이드할 수 있습니다.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

설치Setting up

클라이언트 라이브러리 설치Install the client library

Python을 설치한 후, 다음을 사용하여 클라이언트 라이브러리를 설치할 수 있습니다.After installing Python, you can install the client library with:

pip install --upgrade azure-cognitiveservices-vision-face

새 Python 애플리케이션 만들기Create a new Python application

예를 들어 새 Python 스크립트(quickstart-file.py)를 만듭니다.Create a new Python script—quickstart-file.py, for example. 그런 다음, 원하는 편집기 또는 IDE에서 이 파일을 열고, 다음 라이브러리를 가져옵니다.Then open it in your preferred editor or IDE and import the following libraries.

import asyncio
import io
import glob
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

한 번에 전체 빠른 시작 코드 파일을 보시겠습니까?Want to view the whole quickstart code file at once? GitHub에서 찾을 수 있으며 이 빠른 시작의 코드 예제를 포함합니다.You can find it on GitHub, which contains the code examples in this quickstart.

그런 다음, 리소스의 Azure 엔드포인트 및 키에 대한 변수를 만듭니다.Then, create variables for your resource's Azure endpoint and key.

# This key will serve all examples in this document.
KEY = "<your subscription key>"

# This endpoint will be used in all examples in this quickstart.
ENDPOINT = "<your api endpoint>"

중요

Azure Portal로 이동합니다.Go to the Azure portal. 필수 구성 요소 섹션에서 만든 [제품 이름] 리소스가 성공적으로 배포된 경우 다음 단계 아래에서 리소스로 이동 단추를 클릭합니다.If the [Product name] resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. 리소스 관리 아래에 있는 리소스의 키 및 엔드포인트 페이지에서 키 및 엔드포인트를 찾을 수 있습니다.You can find your key and endpoint in the resource's key and endpoint page, under resource management.

완료되면 코드에서 키를 제거하고 공개적으로 게시하지 마세요.Remember to remove the key from your code when you're done, and never post it publicly. 프로덕션의 경우 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용하는 것이 좋습니다.For production, consider using a secure way of storing and accessing your credentials. 예를 들어 Azure Key Vault입니다.For example, Azure key vault.

개체 모델Object model

Face Python 클라이언트 라이브러리의 주요 기능 중 일부를 처리하는 클래스와 인터페이스는 다음과 같습니다.The following classes and interfaces handle some of the major features of the Face Python client library.

NameName DescriptionDescription
FaceClientFaceClient 이 클래스는 Face 서비스를 사용할 수 있는 권한의 부여를 나타내며 모든 Face 기능에 필요합니다.This class represents your authorization to use the Face service, and you need it for all Face functionality. 구독 정보를 사용하여 인스턴스화하고, 다른 클래스의 인스턴스를 생성하는 데 사용합니다.You instantiate it with your subscription information, and you use it to produce instances of other classes.
FaceOperationsFaceOperations 이 클래스는 사람 얼굴을 사용하여 수행할 수 있는 기본 감지 및 인식 작업을 처리합니다.This class handles the basic detection and recognition tasks that you can do with human faces.
DetectedFaceDetectedFace 이 클래스는 이미지의 한 얼굴에서 감지된 모든 데이터를 나타냅니다.This class represents all of the data that was detected from a single face in an image. 얼굴에 대한 자세한 정보를 검색하는 데 사용할 수 있습니다.You can use it to retrieve detailed information about the face.
FaceListOperationsFaceListOperations 이 클래스는 분류된 얼굴 세트를 저장하는 클라우드 저장 FaceList 구문을 관리합니다.This class manages the cloud-stored FaceList constructs, which store an assorted set of faces.
PersonGroupPersonOperationsPersonGroupPersonOperations 이 클래스는 한 사람에게 속한 얼굴 세트를 저장하는 클라우드 저장 Person 구문을 관리합니다.This class manages the cloud-stored Person constructs, which store a set of faces that belong to a single person.
PersonGroupOperationsPersonGroupOperations 이 클래스는 분류된 Person 개체 세트를 저장하는 클라우드 저장 PersonGroup 구문을 관리합니다.This class manages the cloud-stored PersonGroup constructs, which store a set of assorted Person objects.
ShapshotOperationsShapshotOperations 이 클래스는 스냅샷 기능을 관리합니다. 이를 사용하여 모든 클라우드 기반 얼굴 데이터를 임시로 저장하고 해당 데이터를 새 Azure 구독으로 마이그레이션할 수 있습니다.This class manages the Snapshot functionality; you can use it to temporarily save all of your cloud-based face data and migrate that data to a new Azure subscription.

코드 예제Code examples

여기에 나와 있는 코드 조각에서는 Python용 Face 클라이언트 라이브러리를 사용하여 다음 작업을 수행하는 방법을 보여 줍니다.These code snippets show you how to do the following tasks with the Face client library for Python:

클라이언트 인증Authenticate the client

엔드포인트 및 키를 사용하여 클라이언트를 인스턴스화합니다.Instantiate a client with your endpoint and key. 키를 사용하여 CognitiveServicesCredentials 개체를 만들고, 엔드포인트에서 이를 사용하여 FaceClient 개체를 만듭니다.Create a CognitiveServicesCredentials object with your key, and use it with your endpoint to create a FaceClient object.

# Create an authenticated FaceClient.
face_client = FaceClient(ENDPOINT, CognitiveServicesCredentials(KEY))

이미지에서 얼굴 감지Detect faces in an image

다음 코드에서는 원격 이미지에서 얼굴을 감지합니다.The following code detects a face in a remote image. 감지된 얼굴의 ID를 콘솔에 출력하고, 프로그램 메모리에 저장합니다.It prints the detected face's ID to the console and also stores it in program memory. 그런 다음, 여러 사람이 있는 이미지에서도 얼굴을 감지하고, 해당 ID를 콘솔에 출력합니다.Then, it detects the faces in an image with multiple people and prints their IDs to the console as well. detect_with_url 메서드의 매개 변수를 변경하면 각 DetectedFace 개체와 관련된 다른 정보를 반환할 수 있습니다.By changing the parameters in the detect_with_url method, you can return different information with each DetectedFace object.

# Detect a face in an image that contains a single face
single_face_image_url = 'https://www.biography.com/.image/t_share/MTQ1MzAyNzYzOTgxNTE0NTEz/john-f-kennedy---mini-biography.jpg'
single_image_name = os.path.basename(single_face_image_url)
# We use detection model 3 to get better performance.
detected_faces = face_client.face.detect_with_url(url=single_face_image_url, detection_model='detection_03')
if not detected_faces:
    raise Exception('No face detected from image {}'.format(single_image_name))

# Display the detected face ID in the first single-face image.
# Face IDs are used for comparison to faces (their IDs) detected in other images.
print('Detected face ID from', single_image_name, ':')
for face in detected_faces: print (face.face_id)
print()

# Save this ID for use in Find Similar
first_image_face_ID = detected_faces[0].face_id

로컬 이미지에서 얼굴을 검색할 수도 있습니다.You can also detect faces in a local image. FaceOperations 메서드(예: detect_with_stream)를 참조하세요.See the FaceOperations methods such as detect_with_stream.

표시 및 프레임 면Display and frame faces

다음 코드는 DetectedFace.faceRectangle 속성을 사용하여 지정된 이미지를 디스플레이에 출력하고 얼굴 주위에 사각형을 그립니다.The following code outputs the given image to the display and draws rectangles around the faces, using the DetectedFace.faceRectangle property.

# Detect a face in an image that contains a single face
single_face_image_url = 'https://raw.githubusercontent.com/Microsoft/Cognitive-Face-Windows/master/Data/detection1.jpg'
single_image_name = os.path.basename(single_face_image_url)
# We use detection model 3 to get better performance.
detected_faces = face_client.face.detect_with_url(url=single_face_image_url, detection_model='detection_03')
if not detected_faces:
    raise Exception('No face detected from image {}'.format(single_image_name))

# Convert width height to a point in a rectangle
def getRectangle(faceDictionary):
    rect = faceDictionary.face_rectangle
    left = rect.left
    top = rect.top
    right = left + rect.width
    bottom = top + rect.height
    
    return ((left, top), (right, bottom))


# Download the image from the url
response = requests.get(single_face_image_url)
img = Image.open(BytesIO(response.content))

# For each face returned use the face rectangle and draw a red box.
print('Drawing rectangle around face... see popup for results.')
draw = ImageDraw.Draw(img)
for face in detected_faces:
    draw.rectangle(getRectangle(face), outline='red')

# Display the image in the users default image browser.
img.show()

얼굴 주위에 빨간색 사각형이 그려진 젊은 여자

유사 얼굴 찾기Find similar faces

다음 코드에서는 감지된 하나의 얼굴(원본)을 가져오고, 다른 얼굴(대상) 세트를 검색하여 일치 항목을 찾습니다(이미지별 얼굴 검색).The following code takes a single detected face (source) and searches a set of other faces (target) to find matches (face search by image). 일치 항목을 찾으면 일치하는 얼굴의 ID를 콘솔에 출력합니다.When it finds a match, it prints the ID of the matched face to the console.

일치 항목 찾기Find matches

먼저 위의 섹션(이미지에서 얼굴 감지)에서 코드를 실행하여 단일 얼굴에 대한 참조를 저장합니다.First, run the code in the above section (Detect faces in an image) to save a reference to a single face. 그런 다음, 다음 코드를 실행하여 그룹 이미지에서 여러 얼굴에 대한 참조를 가져옵니다.Then run the following code to get references to several faces in a group image.

# Detect the faces in an image that contains multiple faces
# Each detected face gets assigned a new ID
multi_face_image_url = "http://www.historyplace.com/kennedy/president-family-portrait-closeup.jpg"
multi_image_name = os.path.basename(multi_face_image_url)
# We use detection model 3 to get better performance.
detected_faces2 = face_client.face.detect_with_url(url=multi_face_image_url, detection_model='detection_03')

그런 다음, 다음 코드 블록을 추가하여 그룹에서 첫 번째 얼굴의 인스턴스를 찾습니다.Then add the following code block to find instances of the first face in the group. 이 동작을 수정하는 방법에 대한 자세한 내용은 find_simply 메서드를 참조하세요.See the find_similar method to learn how to modify this behavior.

# Search through faces detected in group image for the single face from first image.
# First, create a list of the face IDs found in the second image.
second_image_face_IDs = list(map(lambda x: x.face_id, detected_faces2))
# Next, find similar face IDs like the one detected in the first image.
similar_faces = face_client.face.find_similar(face_id=first_image_face_ID, face_ids=second_image_face_IDs)
if not similar_faces:
    print('No similar faces found in', multi_image_name, '.')

다음 코드를 사용하여 일치 항목 세부 정보를 콘솔에 출력합니다.Use the following code to print the match details to the console.

# Print the details of the similar faces detected
else:
    print('Similar faces found in', multi_image_name + ':')
    for face in similar_faces:
        first_image_face_ID = face.face_id
        # The similar face IDs of the single face image and the group image do not need to match, 
        # they are only used for identification purposes in each image.
        # The similar faces are matched using the Cognitive Services algorithm in find_similar().
        face_info = next(x for x in detected_faces2 if x.face_id == first_image_face_ID)
        if face_info:
            print('  Face ID: ', first_image_face_ID)
            print('  Face rectangle:')
            print('    Left: ', str(face_info.face_rectangle.left))
            print('    Top: ', str(face_info.face_rectangle.top))
            print('    Width: ', str(face_info.face_rectangle.width))
            print('    Height: ', str(face_info.face_rectangle.height))

사람 그룹 만들기 및 학습Create and train a person group

다음 코드에서는 서로 다른 세 개의 Person 개체를 사용하여 PersonGroup 을 만듭니다.The following code creates a PersonGroup with three different Person objects. Person 을 예제 이미지 세트와 연결한 다음, 각 사용자를 인식할 수 있도록 학습시킵니다.It associates each Person with a set of example images, and then it trains to be able to recognize each person.

PersonGroup 만들기Create PersonGroup

이 시나리오를 단계별로 실행하려면 https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images 의 이미지를 프로젝트의 루트 디렉터리에 저장해야 합니다.To step through this scenario, you need to save the following images to the root directory of your project: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images.

이 이미지 그룹에는 서로 다른 세 명의 사람에 해당하는 세 개의 얼굴 이미지 세트가 포함되어 있습니다.This group of images contains three sets of face images corresponding to three different people. 코드에서는 세 개의 Person 개체를 정의하고, woman, manchild로 시작하는 이미지 파일에 연결합니다.The code will define three Person objects and associate them with image files that start with woman, man, and child.

이미지가 설정되면 만들 PersonGroup 개체에 대한 레이블을 스크립트의 위쪽에 정의합니다.Once you've set up your images, define a label at the top of your script for the PersonGroup object you'll create.

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

그런 다음, 다음 코드를 Python 스크립트의 아래쪽에 추가합니다.Then add the following code to the bottom of your script. 이 코드는 PersonGroup 및 세 개의 Person 개체를 만듭니다.This code creates a PersonGroup and three Person objects.

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

# Define woman friend
woman = face_client.person_group_person.create(PERSON_GROUP_ID, "Woman")
# Define man friend
man = face_client.person_group_person.create(PERSON_GROUP_ID, "Man")
# Define child friend
child = face_client.person_group_person.create(PERSON_GROUP_ID, "Child")

Person에 얼굴 할당Assign faces to Persons

다음 코드는 접두사를 기준으로 이미지를 정렬하고, 얼굴을 감지하며, 해당 얼굴을 각 Person 개체에 할당합니다.The following code sorts your images by their prefix, detects faces, and assigns the faces to each Person object.

'''
Detect faces and register to correct person
'''
# Find all jpeg images of friends in working directory
woman_images = [file for file in glob.glob('*.jpg') if file.startswith("w")]
man_images = [file for file in glob.glob('*.jpg') if file.startswith("m")]
child_images = [file for file in glob.glob('*.jpg') if file.startswith("ch")]

# Add to a woman person
for image in woman_images:
    w = open(image, 'r+b')
    face_client.person_group_person.add_face_from_stream(PERSON_GROUP_ID, woman.person_id, w)

# Add to a man person
for image in man_images:
    m = open(image, 'r+b')
    face_client.person_group_person.add_face_from_stream(PERSON_GROUP_ID, man.person_id, m)

# Add to a child person
for image in child_images:
    ch = open(image, 'r+b')
    face_client.person_group_person.add_face_from_stream(PERSON_GROUP_ID, child.person_id, ch)

URL에서 참조하는 원격 이미지에서 PersonGroup 을 만들 수도 있습니다.You can also create a PersonGroup from remote images referenced by URL. PersonGroupPersonOperations 메서드(예: add_face_from_url)를 참조하세요.See the PersonGroupPersonOperations methods such as add_face_from_url.

PersonGroup 학습Train PersonGroup

얼굴이 할당되면 각 Person 개체와 관련된 시각적 기능을 식별할 수 있도록 PersonGroup 을 학습시켜야 합니다.Once you've assigned faces, you must train the PersonGroup so that it can identify the visual features associated with each of its Person objects. 다음 코드는 비동기 train 메서드를 호출하고, 결과를 폴링하여 상태를 콘솔에 출력합니다.The following code calls the asynchronous train method and polls the result, printing the status to the console.

'''
Train PersonGroup
'''
print()
print('Training the person group...')
# Train the person group
face_client.person_group.train(PERSON_GROUP_ID)

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):
        sys.exit('Training the person group has failed.')
    time.sleep(5)

Face API는 기본적으로 정적인 사전 빌드된 모델 세트에서 실행됩니다(서비스가 실행될 때 모델의 성능이 저하되거나 향상되지 않음).The Face API runs on a set of pre-built models that are static by nature (the model's performance will not regress or improve as the service is run). Microsoft에서 완전히 새로운 모델 버전으로 마이그레이션하지 않고 모델의 백엔드를 업데이트하면 모델이 생성하는 결과가 변경될 수 있습니다.The results that the model produces might change if Microsoft updates the model's backend without migrating to an entirely new model version. 최신 버전의 모델을 사용하려면 PersonGroup 을 동일한 등록 이미지를 가진 매개 변수로 지정하여 다시 학습할 수 있습니다.To take advantage of a newer version of a model, you can retrain your PersonGroup, specifying the newer model as a parameter with the same enrollment images.

얼굴 식별Identify a face

Identify(식별) 작업은 사람(또는 여러 사람)의 이미지를 가져와서 이미지에서 각 얼굴의 ID를 찾습니다(얼굴 인식 검색).The Identify operation takes an image of a person (or multiple people) and looks to find the identity of each face in the image (facial recognition search). 감지된 각 얼굴을 얼굴 특징이 알려진 다른 Person 개체의 데이터베이스인 PersonGroup 과 비교합니다.It compares each detected face to a PersonGroup, a database of different Person objects whose facial features are known.

중요

이 예제를 실행하려면 먼저 사람 그룹 만들기 및 학습에서 코드를 실행해야 합니다.In order to run this example, you must first run the code in Create and train a person group.

테스트 이미지 가져오기Get a test image

다음 코드는 프로젝트 루트에서 test-image-person-group.jpg 이미지를 살펴보고, 이미지에서 얼굴을 감지합니다.The following code looks in the root of your project for an image test-image-person-group.jpg and detects the faces in the image. 이 이미지는 PersonGroup 관리에 사용된 이미지(https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images )에서 찾을 수 있습니다.You can find this image with the images used for PersonGroup management: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images.

'''
Identify a face against a defined PersonGroup
'''
# Group image for testing against
test_image_array = glob.glob('test-image-person-group.jpg')
image = open(test_image_array[0], 'r+b')

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

# Detect faces
face_ids = []
# We use detection model 3 to get better performance.
faces = face_client.face.detect_with_stream(image, detection_model='detection_03')
for face in faces:
    face_ids.append(face.face_id)

얼굴 식별Identify faces

identify 메서드는 감지된 얼굴의 배열을 사용하여 PersonGroup 과 비교합니다.The identify method takes an array of detected faces and compares them to a PersonGroup. 감지된 얼굴을 Person 과 일치시킬 수 있으면 결과가 저장됩니다.If it can match a detected face to a Person, it saves the result. 이 코드는 자세한 일치 항목 결과를 콘솔에 출력합니다.This code prints detailed match results to the console.

# Identify faces
results = face_client.face.identify(face_ids, PERSON_GROUP_ID)
print('Identifying faces in {}'.format(os.path.basename(image.name)))
if not results:
    print('No person identified in the person group for faces from {}.'.format(os.path.basename(image.name)))
for person in results:
    if len(person.candidates) > 0:
        print('Person for face ID {} is identified in {} with a confidence of {}.'.format(person.face_id, os.path.basename(image.name), person.candidates[0].confidence)) # Get topmost confidence score
    else:
        print('No person identified for face ID {} in {}.'.format(person.face_id, os.path.basename(image.name)))

얼굴 확인Verify faces

확인 작업은 얼굴 ID와 다른 얼굴 ID 또는 Person 개체를 가져와서 동일한 사람에게 속하는지 여부를 확인합니다.The Verify operation takes a face ID and either another face ID or a Person object and determines whether they belong to the same person.

다음 코드는 두 개의 원본 이미지에서 얼굴을 감지한 다음, 대상 이미지에서 검색된 얼굴에 대해 확인합니다.The following code detects faces in two source images and then verifies them against a face detected from a target image.

테스트 이미지 가져오기Get test images

다음 코드 블록은 확인 작업을 위한 소스 및 대상 이미지를 가리키는 변수를 선언합니다.The following code blocks declare variables that will point to the source and target images for the verification operation.

# Base url for the Verify and Facelist/Large Facelist operations
IMAGE_BASE_URL = 'https://csdx.blob.core.windows.net/resources/Face/Images/'
# Create a list to hold the target photos of the same person
target_image_file_names = ['Family1-Dad1.jpg', 'Family1-Dad2.jpg']
# The source photos contain this person
source_image_file_name1 = 'Family1-Dad3.jpg'
source_image_file_name2 = 'Family1-Son1.jpg'

확인을 위한 얼굴 감지Detect faces for verification

다음 코드는 소스 및 대상 이미지에서 얼굴을 감지하고 변수에 저장합니다.The following code detects faces in the source and target images and saves them to variables.

# Detect face(s) from source image 1, returns a list[DetectedFaces]
# We use detection model 3 to get better performance.
detected_faces1 = face_client.face.detect_with_url(IMAGE_BASE_URL + source_image_file_name1, detection_model='detection_03')
# Add the returned face's face ID
source_image1_id = detected_faces1[0].face_id
print('{} face(s) detected from image {}.'.format(len(detected_faces1), source_image_file_name1))

# Detect face(s) from source image 2, returns a list[DetectedFaces]
detected_faces2 = face_client.face.detect_with_url(IMAGE_BASE_URL + source_image_file_name2, detection_model='detection_03')
# Add the returned face's face ID
source_image2_id = detected_faces2[0].face_id
print('{} face(s) detected from image {}.'.format(len(detected_faces2), source_image_file_name2))

# List for the target face IDs (uuids)
detected_faces_ids = []
# Detect faces from target image url list, returns a list[DetectedFaces]
for image_file_name in target_image_file_names:
    # We use detection model 3 to get better performance.
    detected_faces = face_client.face.detect_with_url(IMAGE_BASE_URL + image_file_name, detection_model='detection_03')
    # Add the returned face's face ID
    detected_faces_ids.append(detected_faces[0].face_id)
    print('{} face(s) detected from image {}.'.format(len(detected_faces), image_file_name))

확인 결과 가져오기Get verification results

다음 코드는 각 원본 이미지를 대상 이미지와 비교하고 동일한 사람에 속하는지 여부를 나타내는 메시지를 출력합니다.The following code compares each of the source images to the target image and prints a message indicating whether they belong to the same person.

# Verification example for faces of the same person. The higher the confidence, the more identical the faces in the images are.
# Since target faces are the same person, in this example, we can use the 1st ID in the detected_faces_ids list to compare.
verify_result_same = face_client.face.verify_face_to_face(source_image1_id, detected_faces_ids[0])
print('Faces from {} & {} are of the same person, with confidence: {}'
    .format(source_image_file_name1, target_image_file_names[0], verify_result_same.confidence)
    if verify_result_same.is_identical
    else 'Faces from {} & {} are of a different person, with confidence: {}'
        .format(source_image_file_name1, target_image_file_names[0], verify_result_same.confidence))

# Verification example for faces of different persons.
# Since target faces are same person, in this example, we can use the 1st ID in the detected_faces_ids list to compare.
verify_result_diff = face_client.face.verify_face_to_face(source_image2_id, detected_faces_ids[0])
print('Faces from {} & {} are of the same person, with confidence: {}'
    .format(source_image_file_name2, target_image_file_names[0], verify_result_diff.confidence)
    if verify_result_diff.is_identical
    else 'Faces from {} & {} are of a different person, with confidence: {}'
        .format(source_image_file_name2, target_image_file_names[0], verify_result_diff.confidence))

애플리케이션 실행Run the application

python 명령을 사용하여 애플리케이션 디렉터리에서 얼굴 인식 앱을 실행합니다.Run your face recognition app from the application directory with the python command.

python quickstart-file.py

리소스 정리Clean up resources

Cognitive Services 구독을 정리하고 제거하려면 리소스나 리소스 그룹을 삭제하면 됩니다.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. 리소스 그룹을 삭제하면 해당 리소스 그룹에 연결된 다른 모든 리소스가 함께 삭제됩니다.Deleting the resource group also deletes any other resources associated with it.

이 빠른 시작에서는 PersonGroup 을 만들었으며, 이를 삭제하려면 스크립트에서 다음 코드를 실행합니다.If you created a PersonGroup in this quickstart and you want to delete it, run the following code in your script:

# 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()

다음 단계Next steps

이 빠른 시작에서는 Python용 Face 클라이언트 라이브러리를 사용하여 기본 얼굴 인식 작업을 수행하는 방법을 알아보았습니다.In this quickstart, you learned how to use the Face client library for Python to do basis facial recognition tasks. 다음으로 라이브러리에 대해 자세히 알아보려면 참조 설명서를 살펴보세요.Next, explore the reference documentation to learn more about the library.

Go용 Face 클라이언트 라이브러리를 사용하여 얼굴 인식을 시작합니다.Get started with facial recognition using the Face client library for Go. 이러한 단계에 따라 패키지를 설치하고 기본 작업을 위한 예제 코드를 사용해 봅니다.Follow these steps to install the package and try out the example code for basic tasks. Face 서비스는 이미지에서 사람의 얼굴을 감지하고 인식하기 위한 고급 알고리즘에 대한 액세스를 제공합니다.The Face service provides you with access to advanced algorithms for detecting and recognizing human faces in images.

Go용 Face 서비스 클라이언트 라이브러리를 사용하여 다음을 수행합니다.Use the Face service client library for Go to:

참조 설명서 | 라이브러리 소스 코드 | SDK 다운로드Reference documentation | Library source code | SDK download

필수 구성 요소Prerequisites

  • 최신 버전의 GoThe latest version of Go
  • Azure 구독 - 체험 구독 만들기Azure subscription - Create one for free
  • Azure 구독을 보유한 후에는 Azure Portal에서 Face 리소스 를 만들어 키와 엔드포인트를 가져옵니다.Once you have your Azure subscription, create a Face resource in the Azure portal to get your key and endpoint. 배포 후 리소스로 이동 을 클릭합니다.After it deploys, click Go to resource.
    • 애플리케이션을 Face API에 연결하려면 만든 리소스의 키와 엔드포인트가 필요합니다.You will need the key and endpoint from the resource you create to connect your application to the Face API. 이 빠른 시작의 뒷부분에 나오는 코드에 키와 엔드포인트를 붙여넣습니다.You'll paste your key and endpoint into the code below later in the quickstart.
    • 평가판 가격 책정 계층(F0)을 통해 서비스를 사용해보고, 나중에 프로덕션용 유료 계층으로 업그레이드할 수 있습니다.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.
  • 키와 엔드포인트를 가져온 후에는 각각 FACE_SUBSCRIPTION_KEYFACE_ENDPOINT라는 키 및 엔드포인트에 대한 환경 변수를 만듭니다.After you get a key and endpoint, create environment variables for the key and endpoint, named FACE_SUBSCRIPTION_KEY and FACE_ENDPOINT, respectively.

설치Setting up

Go 프로젝트 디렉터리 만들기Create a Go project directory

콘솔 창(cmd, PowerShell, 터미널, Bash)에서 Go 프로젝트에 대한 새 작업 영역 my-app을 만들고 해당 작업 영역으로 이동합니다.In a console window (cmd, PowerShell, Terminal, Bash), create a new workspace for your Go project, named my-app, and navigate to it.

mkdir -p my-app/{src, bin, pkg}  
cd my-app

작업 영역에는 다음 세 개의 폴더가 있습니다.Your workspace will contain three folders:

  • src - 이 디렉터리에는 소스 코드와 패키지가 포함됩니다.src - This directory will contain source code and packages. go get 명령으로 설치된 패키지는 이 디렉터리에 있습니다.Any packages installed with the go get command will be in this folder.
  • pkg - 이 디렉터리에는 컴파일된 Go 패키지 개체가 포함됩니다.pkg - This directory will contain the compiled Go package objects. 이러한 파일의 확장명은 모두 .a입니다.These files all have a .a extension.
  • bin - 이 디렉터리에는 go install을 실행할 때 만들어지는 이진 실행 파일이 포함됩니다.bin - This directory will contain the binary executable files that are created when you run go install.

Go 작업 영역의 구조에 대한 자세한 내용은 Go 언어 설명서를 참조하세요.To learn more about the structure of a Go workspace, see the Go language documentation. 이 가이드에는 $GOPATH$GOROOT 설정에 대한 정보가 있습니다.This guide includes information for setting $GOPATH and $GOROOT.

Go용 클라이언트 라이브러리 설치Install the client library for Go

다음으로, Go용 클라이언트 라이브러리를 설치합니다.Next, install the client library for Go:

go get -u github.com/Azure/azure-sdk-for-go/tree/master/services/cognitiveservices/v1.0/face

dep를 사용하는 경우에는 리포지토리 내에서 다음을 실행합니다.or if you use dep, within your repo run:

dep ensure -add https://github.com/Azure/azure-sdk-for-go/tree/master/services/cognitiveservices/v1.0/face

Go 애플리케이션 빌드Create a Go application

다음으로, src 디렉터리에 sample-app.go라는 파일을 만듭니다.Next, create a file in the src directory named sample-app.go:

cd src
touch sample-app.go

원하는 IDE 또는 텍스트 편집기에서 sample-app.go를 엽니다.Open sample-app.go in your preferred IDE or text editor. 그런 다음, 패키지 이름을 추가하고 다음 라이브러리를 가져옵니다.Then add the package name and import the following libraries:

package main

import (
    "encoding/json"
    "container/list"
    "context"
    "fmt"
    "github.com/Azure/azure-sdk-for-go/services/cognitiveservices/v1.0/face"
    "github.com/Azure/go-autorest/autorest"
    "github.com/satori/go.uuid"
    "io"
    "io/ioutil"
    "log"
    "os"
    "path"
    "strconv"
    "strings"
    "time"
)

다음으로, 다른 Face 서비스 작업을 수행하는 코드를 추가하겠습니다.Next, you'll begin adding code to carry out different Face service operations.

개체 모델Object model

Face 서비스 Go 클라이언트 라이브러리의 주요 기능 중 일부를 처리하는 클래스와 인터페이스는 다음과 같습니다.The following classes and interfaces handle some of the major features of the Face service Go client library.

NameName DescriptionDescription
BaseClientBaseClient 이 클래스는 Face 서비스를 사용할 수 있는 권한의 부여를 나타내며 모든 Face 기능에 필요합니다.This class represents your authorization to use the Face service, and you need it for all Face functionality. 구독 정보를 사용하여 인스턴스화하고, 다른 클래스의 인스턴스를 생성하는 데 사용합니다.You instantiate it with your subscription information, and you use it to produce instances of other classes.
클라이언트Client 이 클래스는 사람 얼굴을 사용하여 수행할 수 있는 기본 감지 및 인식 작업을 처리합니다.This class handles the basic detection and recognition tasks that you can do with human faces.
DetectedFaceDetectedFace 이 클래스는 이미지의 한 얼굴에서 감지된 모든 데이터를 나타냅니다.This class represents all of the data that was detected from a single face in an image. 얼굴에 대한 자세한 정보를 검색하는 데 사용할 수 있습니다.You can use it to retrieve detailed information about the face.
ListClientListClient 이 클래스는 분류된 얼굴 세트를 저장하는 클라우드 저장 FaceList 구문을 관리합니다.This class manages the cloud-stored FaceList constructs, which store an assorted set of faces.
PersonGroupPersonClientPersonGroupPersonClient 이 클래스는 한 사람에게 속한 얼굴 세트를 저장하는 클라우드 저장 Person 구문을 관리합니다.This class manages the cloud-stored Person constructs, which store a set of faces that belong to a single person.
PersonGroupClientPersonGroupClient 이 클래스는 분류된 Person 개체 세트를 저장하는 클라우드 저장 PersonGroup 구문을 관리합니다.This class manages the cloud-stored PersonGroup constructs, which store a set of assorted Person objects.
SnapshotClientSnapshotClient 이 클래스는 스냅샷 기능을 관리합니다.This class manages the Snapshot functionality. 이를 사용하여 모든 클라우드 기반 Face 데이터를 임시로 저장하고, 해당 데이터를 새 Azure 구독으로 마이그레이션할 수 있습니다.You can use it to temporarily save all of your cloud-based Face data and migrate that data to a new Azure subscription.

코드 예제Code examples

다음 코드 샘플에서는 Go용 Face 서비스 클라이언트 라이브러리를 사용하여 기본 작업을 완료하는 방법을 보여줍니다.These code samples show you how to complete basic tasks using the Face service client library for Go:

클라이언트 인증Authenticate the client

참고

이 빠른 시작에서는 각각 FACE_SUBSCRIPTION_KEYFACE_ENDPOINT라는 Face 키 및 엔드포인트에 대한 환경 변수를 만들었다고 가정합니다.This quickstart assumes you've created environment variables for your Face key and endpoint, named FACE_SUBSCRIPTION_KEY and FACE_ENDPOINT respectively.

main 함수를 만들고, 클라이언트를 엔드포인트 및 키로 인스턴스화하는 다음 코드를 이 함수에 추가합니다.Create a main function and add the following code to it to instantiate a client with your endpoint and key. 키를 사용하여 CognitiveServicesAuthorizer 개체를 만들고, 엔드포인트에서 이 개체를 사용하여 Client 개체를 만듭니다.You create a CognitiveServicesAuthorizer object with your key, and use it with your endpoint to create a Client object. 또한 이 코드는 클라이언트 개체를 만드는 데 필요한 컨텍스트 개체를 인스턴스화합니다.This code also instantiates a context object, which is needed for the creation of client objects. 뿐만 아니라 이 빠른 시작의 샘플 이미지 중 일부가 있는 원격 위치를 정의합니다.It also defines a remote location where some of the sample images in this quickstart are found.

func main() {

    // A global context for use in all samples
    faceContext := context.Background()

    // Base url for the Verify and Large Face List examples
    const imageBaseURL = "https://csdx.blob.core.windows.net/resources/Face/Images/"

    /*
    Authenticate
    */
    // Add FACE_SUBSCRIPTION_KEY, FACE_ENDPOINT, and AZURE_SUBSCRIPTION_ID to your environment variables.
    subscriptionKey := os.Getenv("FACE_SUBSCRIPTION_KEY")
    endpoint := os.Getenv("FACE_ENDPOINT")

    // Client used for Detect Faces, Find Similar, and Verify examples.
    client := face.NewClient(endpoint)
    client.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscriptionKey)
    /*
    END - Authenticate
    */

이미지에서 얼굴 감지Detect faces in an image

main 메서드에 다음 코드를 추가합니다.Add the following code in your main method. 이 코드는 원격 샘플 이미지를 정의하고 이미지에서 추출할 얼굴 특징을 지정합니다.This code defines a remote sample image and specifies which face features to extract from the image. 또한 감지된 얼굴에서 데이터를 추출하는 데 사용할 AI 모델을 지정합니다.It also specifies which AI model to use to extract data from the detected face(s). 이러한 옵션에 대한 자세한 내용은 인식 모델 지정을 참조하세요.See Specify a recognition model for information on these options. 마지막으로, DetectWithURL 메서드는 이미지에서 얼굴 검색 작업을 수행하고 그 결과를 프로그램 메모리에 저장합니다.Finally, the DetectWithURL method does the face detection operation on the image and saves the results in program memory.

// Detect a face in an image that contains a single face
singleFaceImageURL := "https://www.biography.com/.image/t_share/MTQ1MzAyNzYzOTgxNTE0NTEz/john-f-kennedy---mini-biography.jpg" 
singleImageURL := face.ImageURL { URL: &singleFaceImageURL } 
singleImageName := path.Base(singleFaceImageURL)
// Array types chosen for the attributes of Face
attributes := []face.AttributeType {"age", "emotion", "gender"}
returnFaceID := true
returnRecognitionModel := false
returnFaceLandmarks := false

// API call to detect faces in single-faced image, using recognition model 3
// We specify detection model 1 because we are retrieving attributes.
detectSingleFaces, dErr := client.DetectWithURL(faceContext, singleImageURL, &returnFaceID, &returnFaceLandmarks, attributes, face.Recognition03, &returnRecognitionModel, face.Detection01)
if dErr != nil { log.Fatal(dErr) }

// Dereference *[]DetectedFace, in order to loop through it.
dFaces := *detectSingleFaces.Value

로컬 이미지에서 얼굴을 검색할 수도 있습니다.You can also detect faces in a local image. 클라이언트 메서드(예: DetectWithStream)를 참조하세요.See the Client methods such as DetectWithStream.

검색된 얼굴 데이터 표시Display detected face data

코드의 그 다음 블록은 DetectedFace 개체 배열의 첫 번째 요소를 가져와서 해당 특성을 콘솔에 출력합니다.The next block of code takes the first element in the array of DetectedFace objects and prints its attributes to the console. 여러 얼굴에 이미지를 사용한 경우 그 대신 배열을 반복해야 합니다.If you used an image with multiple faces, you should iterate through the array instead.

fmt.Println("Detected face in (" + singleImageName + ") with ID(s): ")
fmt.Println(dFaces[0].FaceID)
fmt.Println()
// Find/display the age and gender attributes
for _, dFace := range dFaces { 
    fmt.Println("Face attributes:")
    fmt.Printf("  Age: %.0f", *dFace.FaceAttributes.Age) 
    fmt.Println("\n  Gender: " + dFace.FaceAttributes.Gender) 
} 
// Get/display the emotion attribute
emotionStruct := *dFaces[0].FaceAttributes.Emotion
// Convert struct to a map
var emotionMap map[string]float64
result, _ := json.Marshal(emotionStruct)
json.Unmarshal(result, &emotionMap)
// Find the emotion with the highest score (confidence level). Range is 0.0 - 1.0.
var highest float64 
emotion := ""
dScore := -1.0
for name, value := range emotionMap{
    if (value > highest) {
        emotion, dScore = name, value
        highest = value
    }
}
fmt.Println("  Emotion: " + emotion + " (score: " + strconv.FormatFloat(dScore, 'f', 3, 64) + ")")

유사 얼굴 찾기Find similar faces

다음 코드에서는 감지된 하나의 얼굴(원본)을 가져오고, 다른 얼굴(대상) 세트를 검색하여 일치 항목을 찾습니다(이미지별 얼굴 검색).The following code takes a single detected face (source) and searches a set of other faces (target) to find matches (face search by image). 일치 항목을 찾으면 일치하는 얼굴의 ID를 콘솔에 출력합니다.When it finds a match, it prints the ID of the matched face to the console.

비교할 얼굴 감지Detect faces for comparison

먼저 이미지에서 얼굴 감지 섹션에서 감지한 얼굴의 참조를 저장합니다.First, save a reference to the face you detected in the Detect faces in an image section. 이 얼굴이 원본입니다.This face will be the source.

// Select an ID in single-faced image for comparison to faces detected in group image. Used in Find Similar.
firstImageFaceID := dFaces[0].FaceID

그런 다음, 다른 이미지에서 얼굴 세트를 감지할 다음 코드를 입력합니다.Then enter the following code to detect a set of faces in a different image. 여기서 감지되는 얼굴이 대상입니다.These faces will be the target.

// Detect the faces in an image that contains multiple faces
groupImageURL := "http://www.historyplace.com/kennedy/president-family-portrait-closeup.jpg"
groupImageName := path.Base(groupImageURL)
groupImage := face.ImageURL { URL: &groupImageURL } 

// API call to detect faces in group image, using recognition model 3. This returns a ListDetectedFace struct.
// We specify detection model 2 because we are not retrieving attributes.
detectedGroupFaces, dgErr := client.DetectWithURL(faceContext, groupImage, &returnFaceID, &returnFaceLandmarks, nil, face.Recognition03, &returnRecognitionModel, face.Detection02)
if dgErr != nil { log.Fatal(dgErr) }
fmt.Println()

// Detect faces in the group image.
// Dereference *[]DetectedFace, in order to loop through it.
dFaces2 := *detectedGroupFaces.Value
// Make slice list of UUIDs
faceIDs := make([]uuid.UUID, len(dFaces2))
fmt.Print("Detected faces in (" + groupImageName + ") with ID(s):\n")
for i, face := range dFaces2 {
    faceIDs[i] = *face.FaceID // Dereference DetectedFace.FaceID
    fmt.Println(*face.FaceID)
}

일치 항목 찾기Find matches

다음 코드는 FindSimilar 메서드를 사용하여 원본 얼굴과 일치하는 모든 대상 얼굴을 찾습니다.The following code uses the FindSimilar method to find all of the target faces that match the source face.

// Add single-faced image ID to struct
findSimilarBody := face.FindSimilarRequest { FaceID: firstImageFaceID, FaceIds: &faceIDs }
// Get the list of similar faces found in the group image of previously detected faces
listSimilarFaces, sErr := client.FindSimilar(faceContext, findSimilarBody)
if sErr != nil { log.Fatal(sErr) }

// The *[]SimilarFace 
simFaces := *listSimilarFaces.Value

다음 코드에서는 일치 항목 세부 정보를 콘솔에 출력합니다.The following code prints the match details to the console.

// Print the details of the similar faces detected 
fmt.Print("Similar faces found in (" + groupImageName + ") with ID(s):\n")
var sScore float64
for _, face := range simFaces {
    fmt.Println(face.FaceID)
    // Confidence of the found face with range 0.0 to 1.0.
    sScore = *face.Confidence
    fmt.Println("The similarity confidence: ", strconv.FormatFloat(sScore, 'f', 3, 64))
}

사람 그룹 만들기 및 학습Create and train a person group

이 시나리오를 단계별로 실행하려면 https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images 의 이미지를 프로젝트의 루트 디렉터리에 저장해야 합니다.To step through this scenario, you need to save the following images to the root directory of your project: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images.

이 이미지 그룹에는 서로 다른 세 명의 사람과 일치하는 세 개의 단일 얼굴 이미지 세트가 포함되어 있습니다.This group of images contains three sets of single-face images that correspond to three different people. 이 코드는 세 개의 PersonGroup Person 개체를 정의하고, woman, manchild로 시작하는 이미지 파일에 이 개체를 연결합니다.The code will define three PersonGroup Person objects and associate them with image files that start with woman, man, and child.

PersonGroup 만들기Create PersonGroup

이미지를 다운로드한 후에는 main 메서드의 맨 아래에 다음 코드를 추가합니다.Once you've downloaded your images, add the following code to the bottom of your main method. 이 코드는 PersonGroupClient 개체를 인증 한 다음, 이 개체를 사용하여 새 PersonGroup 을 정의합니다.This code authenticates a PersonGroupClient object and then uses it to define a new PersonGroup.

// Get working directory
root, rootErr := os.Getwd()
if rootErr != nil { log.Fatal(rootErr) }

// Full path to images folder
imagePathRoot := path.Join(root+"\\images\\")

// Authenticate - Need a special person group client for your person group
personGroupClient := face.NewPersonGroupClient(endpoint)
personGroupClient.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscriptionKey)

// Create the Person Group
// Create an empty Person Group. Person Group ID must be lower case, alphanumeric, and/or with '-', '_'.
personGroupID := "unique-person-group"
fmt.Println("Person group ID: " + personGroupID)
metadata := face.MetaDataContract { Name: &personGroupID }

// Create the person group
personGroupClient.Create(faceContext, personGroupID, metadata)

PersonGroup Person 만들기Create PersonGroup Persons

다음 코드 블록은 PersonGroupPersonClient 개체를 인증하고, 이 개체를 사용하여 세 개의 새 PersonGroup Person 개체를 정의합니다.The next block of code authenticates a PersonGroupPersonClient and uses it to define three new PersonGroup Person objects. 이러한 개체는 각각 이미지 세트의 사용자 한 명을 나타냅니다.These objects each represent a single person in the set of images.

// Authenticate - Need a special person group person client for your person group person
personGroupPersonClient := face.NewPersonGroupPersonClient(endpoint)
personGroupPersonClient.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscriptionKey)

// Create each person group person for each group of images (woman, man, child)
// Define woman friend
w := "Woman"
nameWoman := face.NameAndUserDataContract { Name: &w }
// Returns a Person type
womanPerson, wErr := personGroupPersonClient.Create(faceContext, personGroupID, nameWoman)
if wErr != nil { log.Fatal(wErr) }
fmt.Print("Woman person ID: ")
fmt.Println(womanPerson.PersonID)
// Define man friend
m := "Man"
nameMan := face.NameAndUserDataContract { Name: &m }
// Returns a Person type
manPerson, wErr := personGroupPersonClient.Create(faceContext, personGroupID, nameMan)
if wErr != nil { log.Fatal(wErr) }
fmt.Print("Man person ID: ")
fmt.Println(manPerson.PersonID)
// Define child friend
ch := "Child"
nameChild := face.NameAndUserDataContract { Name: &ch }
// Returns a Person type
childPerson, wErr := personGroupPersonClient.Create(faceContext, personGroupID, nameChild)
if wErr != nil { log.Fatal(wErr) }
fmt.Print("Child person ID: ")
fmt.Println(childPerson.PersonID)

Person에 얼굴 할당Assign faces to Persons

다음 코드는 접두사를 기준으로 이미지를 정렬하고, 얼굴을 감지하고, 이미지 파일 이름에 따라 얼굴을 각 PersonGroup Person 개체에 할당합니다.The following code sorts the images by their prefix, detects faces, and assigns the faces to each respective PersonGroup Person object, based on the image file name.

// Detect faces and register to correct person
// Lists to hold all their person images
womanImages := list.New()
manImages := list.New()
childImages := list.New()

// Collect the local images for each person, add them to their own person group person
images, fErr := ioutil.ReadDir(imagePathRoot)
if fErr != nil { log.Fatal(fErr)}
for _, f := range images {
    path:= (imagePathRoot+f.Name())
    if strings.HasPrefix(f.Name(), "w") {
        var wfile io.ReadCloser
        wfile, err:= os.Open(path)
        if err != nil { log.Fatal(err) }
        womanImages.PushBack(wfile)
        personGroupPersonClient.AddFaceFromStream(faceContext, personGroupID, *womanPerson.PersonID, wfile, "", nil, face.Detection02)
    }
    if strings.HasPrefix(f.Name(), "m") {
        var mfile io.ReadCloser
        mfile, err:= os.Open(path)
        if err != nil { log.Fatal(err) }
        manImages.PushBack(mfile)
        personGroupPersonClient.AddFaceFromStream(faceContext, personGroupID, *manPerson.PersonID, mfile, "", nil, face.Detection02)
    }
    if strings.HasPrefix(f.Name(), "ch") {
        var chfile io.ReadCloser
        chfile, err:= os.Open(path)
        if err != nil { log.Fatal(err) }
        childImages.PushBack(chfile)
        personGroupPersonClient.AddFaceFromStream(faceContext, personGroupID, *childPerson.PersonID, chfile, "", nil, face.Detection02)
    }
}

URL에서 참조하는 원격 이미지에서 PersonGroup 을 만들 수도 있습니다.You can also create a PersonGroup from remote images referenced by URL. PersonGroupPersonClient 메서드(예: AddFaceFromURL)를 참조하세요.See the PersonGroupPersonClient methods such as AddFaceFromURL.

PersonGroup 학습Train PersonGroup

얼굴을 할당한 후에는 각 Person 개체와 관련된 시각적 특징을 식별할 수 있도록 PersonGroup 을 학습시켜야 합니다.Once you've assigned faces, you train the PersonGroup so it can identify the visual features associated with each of its Person objects. 다음 코드는 비동기 train 메서드를 호출하고, 결과를 폴링하여 상태를 콘솔에 출력합니다.The following code calls the asynchronous train method and polls the result, printing the status to the console.

// Train the person group
personGroupClient.Train(faceContext, personGroupID)

// Wait for it to succeed in training
for {
    trainingStatus, tErr := personGroupClient.GetTrainingStatus(faceContext, personGroupID)
    if tErr != nil { log.Fatal(tErr) }
    
    if trainingStatus.Status == "succeeded" {
        fmt.Println("Training status:", trainingStatus.Status)
        break
    }
    time.Sleep(2)
}

Face API는 기본적으로 정적인 사전 빌드된 모델 세트에서 실행됩니다(서비스가 실행될 때 모델의 성능이 저하되거나 향상되지 않음).The Face API runs on a set of pre-built models that are static by nature (the model's performance will not regress or improve as the service is run). Microsoft에서 완전히 새로운 모델 버전으로 마이그레이션하지 않고 모델의 백엔드를 업데이트하면 모델이 생성하는 결과가 변경될 수 있습니다.The results that the model produces might change if Microsoft updates the model's backend without migrating to an entirely new model version. 최신 버전의 모델을 사용하려면 PersonGroup 을 동일한 등록 이미지를 가진 매개 변수로 지정하여 다시 학습할 수 있습니다.To take advantage of a newer version of a model, you can retrain your PersonGroup, specifying the newer model as a parameter with the same enrollment images.

얼굴 식별Identify a face

Identify(식별) 작업은 사람(또는 여러 사람)의 이미지를 가져와서 이미지에서 각 얼굴의 ID를 찾습니다(얼굴 인식 검색).The Identify operation takes an image of a person (or multiple people) and looks to find the identity of each face in the image (facial recognition search). 감지된 각 얼굴을 얼굴 특징이 알려진 다른 Person 개체의 데이터베이스인 PersonGroup 과 비교합니다.It compares each detected face to a PersonGroup, a database of different Person objects whose facial features are known.

중요

이 예제를 실행하려면 먼저 사람 그룹 만들기 및 학습에서 코드를 실행해야 합니다.In order to run this example, you must first run the code in Create and train a person group.

테스트 이미지 가져오기Get a test image

다음 코드는 프로젝트의 루트에서 test-image-person-group.jpg 이미지를 찾아 프로그램 메모리에 로드합니다.The following code looks in the root of your project for an image test-image-person-group.jpg and loads it into program memory. 이 이미지는 사람 그룹 만들기 및 학습: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images 에 사용한 이미지와 동일한 리포지토리에서 찾을 수 있습니다.You can find this image in the same repo as the images used in Create and train a person group: https://github.com/Azure-Samples/cognitive-services-sample-data-files/tree/master/Face/images.

personGroupTestImageName := "test-image-person-group.jpg"
// Use image path root from the one created in person group
personGroupTestImagePath := imagePathRoot
var personGroupTestImage io.ReadCloser
// Returns a ReaderCloser
personGroupTestImage, identErr:= os.Open(personGroupTestImagePath+personGroupTestImageName)
if identErr != nil { log.Fatal(identErr) }

테스트 이미지에서 원본 얼굴 감지Detect source faces in test image

다음 코드 블록은 테스트 이미지를 대상으로 일반적인 얼굴 감지를 수행하여 모든 얼굴을 감지하고 배열에 저장합니다.The next code block does ordinary face detection on the test image to retrieve all of the faces and save them to an array.

// Detect faces in group test image, using recognition model 1 (default)
returnIdentifyFaceID := true
// Returns a ListDetectedFaces
// Recognition03 is not compatible.
// We specify detection model 2 because we are not retrieving attributes.
detectedTestImageFaces, dErr := client.DetectWithStream(faceContext, personGroupTestImage, &returnIdentifyFaceID, nil, nil, face.Recognition01, nil, face.Detection02)
if dErr != nil { log.Fatal(dErr) }

// Make list of face IDs from the detection. 
length := len(*detectedTestImageFaces.Value)
testImageFaceIDs := make([]uuid.UUID, length)
// ListDetectedFace is a struct with a Value property that returns a *[]DetectedFace
for i, f := range *detectedTestImageFaces.Value {
    testImageFaceIDs[i] = *f.FaceID
}

얼굴 식별Identify faces

Identify 메서드는 감지된 얼굴 배열을 가져와서 지정된 (이전 섹션에서 정의하고 학습시킨) PersonGroup 과 비교합니다.The Identify method takes the array of detected faces and compares them to the given PersonGroup (defined and trained in the earlier section). 감지된 얼굴을 Person 과 매칭할 수 있으면 결과가 저장됩니다.If it can match a detected face to a Person in the group, it saves the result.

// Identify the faces in the test image with everyone in the person group as a query
identifyRequestBody := face.IdentifyRequest { FaceIds: &testImageFaceIDs, PersonGroupID: &personGroupID }
identifiedFaces, err := client.Identify(faceContext, identifyRequestBody)
if err != nil { log.Fatal(err) }

그런 다음, 이 코드는 자세한 매칭 결과를 콘솔에 출력합니다.This code then prints detailed match results to the console.

// Get the result which person(s) were identified
iFaces := *identifiedFaces.Value
for _, person := range iFaces {
    fmt.Println("Person for face ID: " )
    fmt.Print(person.FaceID)
    fmt.Println(" is identified in " + personGroupTestImageName + ".")
}

얼굴 확인Verify faces

확인 작업은 얼굴 ID와 다른 얼굴 ID 또는 Person 개체를 가져와서 동일한 사람에게 속하는지 여부를 확인합니다.The Verify operation takes a face ID and either another face ID or a Person object and determines whether they belong to the same person.

다음 코드는 두 개의 원본 이미지에서 얼굴을 감지한 다음, 대상 이미지에서 검색된 각 얼굴과 대조합니다.The following code detects faces in two source images and then verifies each of them against a face detected from a target image.

테스트 이미지 가져오기Get test images

다음 코드 블록은 확인 작업을 위한 원본 및 대상 이미지를 가리키는 변수를 선언합니다.The following code blocks declare variables that will point to the target and source images for the verification operation.

// Create a slice list to hold the target photos of the same person
targetImageFileNames :=  make([]string, 2)
targetImageFileNames[0] = "Family1-Dad1.jpg"
targetImageFileNames[1] = "Family1-Dad2.jpg"

// The source photos contain this person, maybe
sourceImageFileName1 := "Family1-Dad3.jpg"
sourceImageFileName2 := "Family1-Son1.jpg"

확인을 위한 얼굴 감지Detect faces for verification

다음 코드는 소스 및 대상 이미지에서 얼굴을 감지하고 변수에 저장합니다.The following code detects faces in the source and target images and saves them to variables.

// DetectWithURL parameters
urlSource1 := imageBaseURL + sourceImageFileName1
urlSource2 := imageBaseURL + sourceImageFileName2
url1 :=  face.ImageURL { URL: &urlSource1 }
url2 := face.ImageURL { URL: &urlSource2 }
returnFaceIDVerify := true
returnFaceLandmarksVerify := false
returnRecognitionModelVerify := false

// Detect face(s) from source image 1, returns a ListDetectedFace struct
// We specify detection model 2 because we are not retrieving attributes.
detectedVerifyFaces1, dErrV1 := client.DetectWithURL(faceContext, url1 , &returnFaceIDVerify, &returnFaceLandmarksVerify, nil, face.Recognition03, &returnRecognitionModelVerify, face.Detection02)
if dErrV1 != nil { log.Fatal(dErrV1) }
// Dereference the result, before getting the ID
dVFaceIds1 := *detectedVerifyFaces1.Value 
// Get ID of the detected face
imageSource1Id := dVFaceIds1[0].FaceID
fmt.Println(fmt.Sprintf("%v face(s) detected from image: %v", len(dVFaceIds1), sourceImageFileName1))

// Detect face(s) from source image 2, returns a ListDetectedFace struct
// We specify detection model 2 because we are not retrieving attributes.
detectedVerifyFaces2, dErrV2 := client.DetectWithURL(faceContext, url2 , &returnFaceIDVerify, &returnFaceLandmarksVerify, nil, face.Recognition03, &returnRecognitionModelVerify, face.Detection02)
if dErrV2 != nil { log.Fatal(dErrV2) }
// Dereference the result, before getting the ID
dVFaceIds2 := *detectedVerifyFaces2.Value 
// Get ID of the detected face
imageSource2Id := dVFaceIds2[0].FaceID
fmt.Println(fmt.Sprintf("%v face(s) detected from image: %v", len(dVFaceIds2), sourceImageFileName2))
// Detect faces from each target image url in list. DetectWithURL returns a VerifyResult with Value of list[DetectedFaces]
// Empty slice list for the target face IDs (UUIDs)
var detectedVerifyFacesIds [2]uuid.UUID
for i, imageFileName := range targetImageFileNames {
    urlSource := imageBaseURL + imageFileName 
    url :=  face.ImageURL { URL: &urlSource}
    // We specify detection model 2 because we are not retrieving attributes.
    detectedVerifyFaces, dErrV := client.DetectWithURL(faceContext, url, &returnFaceIDVerify, &returnFaceLandmarksVerify, nil, face.Recognition03, &returnRecognitionModelVerify, face.Detection02)
    if dErrV != nil { log.Fatal(dErrV) }
    // Dereference *[]DetectedFace from Value in order to loop through it.
    dVFaces := *detectedVerifyFaces.Value
    // Add the returned face's face ID
    detectedVerifyFacesIds[i] = *dVFaces[0].FaceID
    fmt.Println(fmt.Sprintf("%v face(s) detected from image: %v", len(dVFaces), imageFileName))
}

확인 결과 가져오기Get verification results

다음 코드는 각 원본 이미지를 대상 이미지와 비교하고 동일한 사람에 속하는지 여부를 나타내는 메시지를 출력합니다.The following code compares each of the source images to the target image and prints a message indicating whether they belong to the same person.

// Verification example for faces of the same person. The higher the confidence, the more identical the faces in the images are.
// Since target faces are the same person, in this example, we can use the 1st ID in the detectedVerifyFacesIds list to compare.
verifyRequestBody1 := face.VerifyFaceToFaceRequest{ FaceID1: imageSource1Id, FaceID2: &detectedVerifyFacesIds[0] }
verifyResultSame, vErrSame := client.VerifyFaceToFace(faceContext, verifyRequestBody1)
if vErrSame != nil { log.Fatal(vErrSame) }

fmt.Println()

// Check if the faces are from the same person.
if (*verifyResultSame.IsIdentical) {
    fmt.Println(fmt.Sprintf("Faces from %v & %v are of the same person, with confidence %v", 
    sourceImageFileName1, targetImageFileNames[0], strconv.FormatFloat(*verifyResultSame.Confidence, 'f', 3, 64)))
} else {
    // Low confidence means they are more differant than same.
    fmt.Println(fmt.Sprintf("Faces from %v & %v are of a different person, with confidence %v", 
    sourceImageFileName1, targetImageFileNames[0], strconv.FormatFloat(*verifyResultSame.Confidence, 'f', 3, 64)))
}

// Verification example for faces of different persons. 
// Since target faces are same person, in this example, we can use the 1st ID in the detectedVerifyFacesIds list to compare.
verifyRequestBody2 := face.VerifyFaceToFaceRequest{ FaceID1: imageSource2Id, FaceID2: &detectedVerifyFacesIds[0] }
verifyResultDiff, vErrDiff := client.VerifyFaceToFace(faceContext, verifyRequestBody2)
if vErrDiff != nil { log.Fatal(vErrDiff) }
// Check if the faces are from the same person.
if (*verifyResultDiff.IsIdentical) {
    fmt.Println(fmt.Sprintf("Faces from %v & %v are of the same person, with confidence %v", 
    sourceImageFileName2, targetImageFileNames[0], strconv.FormatFloat(*verifyResultDiff.Confidence, 'f', 3, 64)))
} else {
    // Low confidence means they are more differant than same.
    fmt.Println(fmt.Sprintf("Faces from %v & %v are of a different person, with confidence %v", 
    sourceImageFileName2, targetImageFileNames[0], strconv.FormatFloat(*verifyResultDiff.Confidence, 'f', 3, 64)))
}

애플리케이션 실행Run the application

go run <app-name> 명령을 사용하여 애플리케이션 디렉터리에서 얼굴 인식 앱을 실행합니다.Run your face recognition app from the application directory with the go run <app-name> command.

go run sample-app.go

리소스 정리Clean up resources

Cognitive Services 구독을 정리하고 제거하려면 리소스나 리소스 그룹을 삭제하면 됩니다.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. 리소스 그룹을 삭제하면 해당 리소스 그룹에 연결된 다른 모든 리소스가 함께 삭제됩니다.Deleting the resource group also deletes any other resources associated with it.

이 빠른 시작에서 PersonGroup 을 만든 경우 Delete 메서드를 호출하여 삭제할 수 있습니다.If you created a PersonGroup in this quickstart and you want to delete it, call the Delete method.

다음 단계Next steps

이 빠른 시작에서는 Go용 Face 클라이언트 라이브러리를 사용하여 기본 얼굴 인식 작업을 수행하는 방법을 알아보았습니다.In this quickstart, you learned how to use the Face client library for Go to do basis facial recognition tasks. 다음으로 라이브러리에 대해 자세히 알아보려면 참조 설명서를 살펴보세요.Next, explore the reference documentation to learn more about the library.

Face REST API를 사용하여 얼굴 인식을 시작합니다.Get started with facial recognition using the Face REST API. Face 서비스는 이미지에서 사람의 얼굴을 감지하고 인식하기 위한 고급 알고리즘에 대한 액세스를 제공합니다.The Face service provides you with access to advanced algorithms for detecting and recognizing human faces in images.

Face REST API를 사용하여 다음을 수행합니다.Use the Face REST API to:

참고

이 빠른 시작에서는 cURL 명령을 사용하여 REST API를 호출합니다.This quickstart uses cURL commands to call the REST API. 프로그래밍 언어를 사용하여 REST API를 호출할 수도 있습니다.You can also call the REST API using a programming language. C#, Python, Java, JavaScript, Go의 예는 GitHub 샘플을 참조하세요.See the GitHub samples for examples in C#, Python, Java, JavaScript, and Go.

필수 구성 요소Prerequisites

  • Azure 구독 - 체험 구독 만들기Azure subscription - Create one for free
  • Azure 구독을 보유한 후에는 Azure Portal에서 Face 리소스 를 만들어 키와 엔드포인트를 가져옵니다.Once you have your Azure subscription, create a Face resource in the Azure portal to get your key and endpoint. 배포 후 리소스로 이동 을 클릭합니다.After it deploys, click Go to resource.
    • 애플리케이션을 Face API에 연결하려면 생성한 리소스의 키와 엔드포인트가 필요합니다.You'll need the key and endpoint from the resource you create to connect your application to the Face API. 이 빠른 시작의 뒷부분에 나오는 코드에 키와 엔드포인트를 붙여넣습니다.You'll paste your key and endpoint into the code below later in the quickstart.
    • 평가판 가격 책정 계층(F0)을 통해 서비스를 사용해보고, 나중에 프로덕션용 유료 계층으로 업그레이드할 수 있습니다.You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

이미지에서 얼굴 감지Detect faces in an image

다음과 같은 명령을 사용하여 Face API를 호출하고 이미지에서 얼굴 특성 데이터를 가져옵니다.You'll use a command like the following to call the Face API and get face attribute data from an image. 먼저, 텍스트 편집기에 코드를 복사합니다. 코드를 명령의 특정 부분으로 변경해야 실행할 수 있습니다.—First, copy the code into a text editor—you'll need to make changes to certain parts of the command before you can run it.

curl -H "Ocp-Apim-Subscription-Key: TODO_INSERT_YOUR_FACE_SUBSCRIPTION_KEY_HERE" "TODO_INSERT_YOUR_FACE_ENDPOINT_HERE/face/v1.0/detect?detectionModel=detection_02&returnFaceId=true&returnFaceLandmarks=false" -H "Content-Type: application/json" --data-ascii "{\"url\":\"https://upload.wikimedia.org/wikipedia/commons/c/c3/RH_Louise_Lillian_Gish.jpg\"}"

다음과 같이 변경합니다.Make the following changes:

  1. Ocp-Apim-Subscription-Key를 유효한 Face 구독 키에 할당합니다.Assign Ocp-Apim-Subscription-Key to your valid Face subscription key.
  2. 쿼리 URL의 첫 번째 부분을 구독 키에 해당하는 엔드포인트에 맞게 변경합니다.Change the first part of the query URL to match the endpoint that corresponds to your subscription key.

    참고

    2019년 7월 1일 이후에 만들어진 새 리소스는 사용자 지정 하위 도메인 이름을 사용합니다.New resources created after July 1, 2019, will use custom subdomain names. 자세한 내용 및 지역별 엔드포인트의 전체 목록은 Cognitive Services에 대한 사용자 지정 하위 도메인 이름을 참조하세요.For more information and a complete list of regional endpoints, see Custom subdomain names for Cognitive Services.

  3. 필요에 따라 다른 이미지를 가리키도록 요청의 본문에서 URL을 변경합니다.Optionally change the URL in the body of the request to point to a different image.

변경한 후에는 명령 프롬프트를 열고 새 명령을 입력합니다.Once you've made your changes, open a command prompt and enter the new command.

결과 검사Examine the results

콘솔 창에 얼굴 정보가 JSON 데이터로 표시됩니다.You should see the face information displayed as JSON data in the console window. 예를 들면 다음과 같습니다.For example:

[
  {
    "faceId": "49d55c17-e018-4a42-ba7b-8cbbdfae7c6f",
    "faceRectangle": {
      "top": 131,
      "left": 177,
      "width": 162,
      "height": 162
    }
  }
]  

얼굴 특성 가져오기Get face attributes

얼굴 특성을 추출하려면 Detect API를 다시 호출하되, detectionModeldetection_01로 설정합니다.To extract face attributes, call the Detect API again, but set detectionModel to detection_01. returnFaceAttributes 쿼리 매개 변수도 추가합니다.Add the returnFaceAttributes query parameter as well. 이제 명령은 다음과 같이 표시됩니다.The command should now look like the following. 이전과 같이 Face 구독 키와 엔드포인트를 삽입합니다.As before, insert your Face subscription key and endpoint.

curl -H "Ocp-Apim-Subscription-Key: TODO_INSERT_YOUR_FACE_SUBSCRIPTION_KEY_HERE" "TODO_INSERT_YOUR_FACE_ENDPOINT_HERE/face/v1.0/detect?detectionModel=detection_01&returnFaceId=true&returnFaceLandmarks=false&returnFaceAttributes=age,gender,headPose,smile,facialHair,glasses,emotion,hair,makeup,occlusion,accessories,blur,exposure,noise" -H "Content-Type: application/json" --data-ascii "{\"url\":\"https://upload.wikimedia.org/wikipedia/commons/c/c3/RH_Louise_Lillian_Gish.jpg\"}"

결과 검사Examine the results

이제 반환된 얼굴 정보에 얼굴 특성이 포함됩니다.The returned face information now includes face attributes. 예를 들면 다음과 같습니다.For example:

[
  {
    "faceId": "49d55c17-e018-4a42-ba7b-8cbbdfae7c6f",
    "faceRectangle": {
      "top": 131,
      "left": 177,
      "width": 162,
      "height": 162
    },
    "faceAttributes": {
      "smile": 0,
      "headPose": {
        "pitch": 0,
        "roll": 0.1,
        "yaw": -32.9
      },
      "gender": "female",
      "age": 22.9,
      "facialHair": {
        "moustache": 0,
        "beard": 0,
        "sideburns": 0
      },
      "glasses": "NoGlasses",
      "emotion": {
        "anger": 0,
        "contempt": 0,
        "disgust": 0,
        "fear": 0,
        "happiness": 0,
        "neutral": 0.986,
        "sadness": 0.009,
        "surprise": 0.005
      },
      "blur": {
        "blurLevel": "low",
        "value": 0.06
      },
      "exposure": {
        "exposureLevel": "goodExposure",
        "value": 0.67
      },
      "noise": {
        "noiseLevel": "low",
        "value": 0
      },
      "makeup": {
        "eyeMakeup": true,
        "lipMakeup": true
      },
      "accessories": [],
      "occlusion": {
        "foreheadOccluded": false,
        "eyeOccluded": false,
        "mouthOccluded": false
      },
      "hair": {
        "bald": 0,
        "invisible": false,
        "hairColor": [
          {
            "color": "brown",
            "confidence": 1
          },
          {
            "color": "black",
            "confidence": 0.87
          },
          {
            "color": "other",
            "confidence": 0.51
          },
          {
            "color": "blond",
            "confidence": 0.08
          },
          {
            "color": "red",
            "confidence": 0.08
          },
          {
            "color": "gray",
            "confidence": 0.02
          }
        ]
      }
    }
  }
]

유사 얼굴 찾기Find similar faces

이 작업에서는 감지된 하나의 얼굴(원본)을 가져오고, 다른 얼굴(대상) 세트를 검색하여 일치 항목을 찾습니다(이미지별 얼굴 검색).This operation takes a single detected face (source) and searches a set of other faces (target) to find matches (face search by image). 일치 항목을 찾으면 일치하는 얼굴의 ID를 콘솔에 출력합니다.When it finds a match, it prints the ID of the matched face to the console.

비교할 얼굴 감지Detect faces for comparison

먼저 이미지에서 얼굴을 감지해야 이를 비교할 수 있습니다.First, you need to detect faces in images before you can compare them. 얼굴 감지 섹션에서 했던 것처럼 이 명령을 실행합니다.Run this command as you did in the Detect faces section. 이 검색 방법은 비교 작업에 최적화되어 있습니다.This detection method is optimized for comparison operations. 위의 섹션과 같이 자세한 얼굴 특성을 추출하지 않으며 다른 검색 모델을 사용합니다.It doesn't extract detailed face attributes like in the section above, and it uses a different detection model.

curl -H "Ocp-Apim-Subscription-Key: TODO_INSERT_YOUR_FACE_SUBSCRIPTION_KEY_HERE" "TODO_INSERT_YOUR_FACE_ENDPOINT_HERE/face/v1.0/detect?detectionModel=detection_02&returnFaceId=true&returnFaceLandmarks=false" -H "Content-Type: application/json" --data-ascii "{\"url\":\"https://csdx.blob.core.windows.net/resources/Face/Images/Family1-Dad1.jpg\"}"

JSON 응답에서 "faceId" 값을 찾아 임시 위치에 저장합니다.Find the "faceId" value in the JSON response and save it to a temporary location. 그런 다음, 이러한 다른 이미지 URL에 대해 위의 명령을 다시 호출하고 얼굴 ID도 저장합니다.Then, call the above command again for these other image URLs, and save their face IDs as well. 이러한 ID를 대상 얼굴 그룹으로 사용하여 비슷한 얼굴을 찾습니다.You'll use these IDs as the target group of faces from which to find a similar face.

https://csdx.blob.core.windows.net/resources/Face/Images/Family1-Daughter1.jpg
https://csdx.blob.core.windows.net/resources/Face/Images/Family1-Mom1.jpg
https://csdx.blob.core.windows.net/resources/Face/Images/Family1-Son1.jpg
https://csdx.blob.core.windows.net/resources/Face/Images/Family2-Lady1.jpg
https://csdx.blob.core.windows.net/resources/Face/Images/Family2-Man1.jpg
https://csdx.blob.core.windows.net/resources/Face/Images/Family3-Lady1.jpg
https://csdx.blob.core.windows.net/resources/Face/Images/Family3-Man1.jpg

마지막으로 매칭에 사용할 단일 원본 얼굴을 검색하고 ID를 저장합니다.Finally, detect the single source face that you'll use for matching, and save its ID. 이 ID는 다른 ID와 구분하여 보관합니다.Keep this ID separate from the others.

https://csdx.blob.core.windows.net/resources/Face/Images/findsimilar.jpg

일치 항목 찾기Find matches

다음 명령을 텍스트 편집기에 복사합니다.Copy the following command to a text editor.

curl -v -X POST "https://westus.api.cognitive.microsoft.com/face/v1.0/findsimilars" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{body}"

그런 다음, 다음과 같이 변경합니다.Then make the following changes:

  1. Ocp-Apim-Subscription-Key를 유효한 Face 구독 키에 할당합니다.Assign Ocp-Apim-Subscription-Key to your valid Face subscription key.
  2. 쿼리 URL의 첫 번째 부분을 구독 키에 해당하는 엔드포인트에 맞게 변경합니다.Change the first part of the query URL to match the endpoint that corresponds to your subscription key.

body 값에 다음 JSON 콘텐츠를 사용합니다.Use the following JSON content for the body value:

{
    "faceId": "",
    "faceIds": [],
    "maxNumOfCandidatesReturned": 10,
    "mode": "matchPerson"
}
  1. "faceId"에 원본 얼굴 ID를 사용합니다.Use the source face ID for "faceId".
  2. 다른 얼굴 ID를 "faceIds" 배열의 용어로 붙여 넣습니다.Paste the other face IDs as terms in the "faceIds" array.

결과 검사Examine the results

쿼리 얼굴과 일치하는 얼굴의 ID를 나열하는 JSON 응답을 받게 됩니다.You'll receive a JSON response that lists the IDs of the faces that match your query face.

[
    {
        "persistedFaceId" : "015839fb-fbd9-4f79-ace9-7675fc2f1dd9",
        "confidence" : 0.82
    },
    ...
] 

리소스 정리Clean up resources

Cognitive Services 구독을 정리하고 제거하려면 리소스나 리소스 그룹을 삭제하면 됩니다.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. 리소스 그룹을 삭제하면 해당 리소스 그룹에 연결된 다른 모든 리소스가 함께 삭제됩니다.Deleting the resource group also deletes any other resources associated with it.

다음 단계Next steps

이 빠른 시작에서는 Face REST API를 사용하여 기본 얼굴 인식 작업을 수행하는 방법을 알아보았습니다.In this quickstart, you learned how to use the Face REST API to do basic facial recognition tasks. 다음으로 라이브러리에 대해 자세히 알아보려면 참조 설명서를 살펴보세요.Next, explore the reference documentation to learn more about the library.