你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：使用人脸服务

项目
10/25/2023

重要

如果使用 Microsoft 产品或服务处理生物识别数据，则需负责以下事项：(i) 向数据主体提供通知，包括有关保留期和销毁的通知；(ii) 从数据主体处获得同意；(iii) 根据适用的数据保护要求删除生物识别数据。 “生物识别数据”将具有 GDPR 第 4 条中所述的含义，以及其他数据保护要求中的等效术语（如果适用）。如需相关信息，请参阅人脸的数据和隐私。

注意

为了支持我们负责任的 AI 原则，基于资格和使用标准对人脸服务访问进行限制。人脸服务仅适用于 Microsoft 托管客户和合作伙伴。使用人脸识别引入表单来申请访问。有关详细信息，请参阅人脸受限访问页面。

开始使用适用于 .NET 的人脸客户端库进行人脸识别。通过人脸服务，可以访问用于检测和识别图像中的人脸的高级算法。按照以下步骤安装包，并尝试使用远程图像进行基本面部识别的示例代码。

参考文档 | 库源代码 | 包 (NuGet) | 示例

先决条件

Azure 订阅 - 免费创建订阅
Visual Studio IDE 或最新版本的 .NET Core。
你的 Azure 帐户必须分配有 Cognitive Services Contributor 角色，这样你才能同意负责任 AI 条款并创建资源。若要将此角色分配给你的帐户，请按照分配角色文档中的步骤进行操作，或与管理员联系。
拥有 Azure 订阅后，请在 Azure 门户中创建人脸资源，以获取密钥和终结点。部署后，选择”转到资源”。
- 需要从创建的资源获取密钥和终结点，以便将应用程序连接到人脸 API。
- 可以使用免费定价层 (F0) 试用该服务，然后再升级到付费层进行生产。

创建环境变量

在此示例中，将凭据写入运行应用程序的本地计算机上的环境变量。

转到 Azure 门户。如果在“先决条件”部分创建的资源部署成功，请选择“后续步骤”下的“转到资源”。在“密钥和终结点”页的“资源管理”下，可以找到密钥和终结点。你的资源密钥与你的 Azure 订阅 ID 不同。

提示

请不要直接在代码中包含密钥，并且绝不公开发布密钥。有关 Azure Key Vault 等更多身份验证选项，请参阅 Azure AI 服务安全性一文。

若要为密钥和终结点设置环境变量，请打开控制台窗口，并按照操作系统和开发环境的说明进行操作。

若要设置 VISION_KEY 环境变量，请将 your-key 替换为资源的其中一个密钥。
若要设置 VISION_ENDPOINT 环境变量，请将 your-endpoint 替换为资源的终结点。

Windows
Linux

setx VISION_KEY your-key

setx VISION_ENDPOINT your-endpoint

添加环境变量后，可能需要重启任何正在运行的、将读取环境变量的程序（包括控制台窗口）。

export VISION_KEY=your-key

export VISION_ENDPOINT=your-endpoint

添加环境变量后，请从控制台窗口运行 source ~/.bashrc，使更改生效。

识别和验证人脸

新建 C# 应用程序
- Visual Studio IDE
- CLI
使用 Visual Studio 创建新的 .NET Core 应用程序。

安装客户端库

创建新项目后，右键单击“解决方案资源管理器”中的项目解决方案，然后选择“管理 NuGet 包”，以安装客户端库。在打开的包管理器中，选择“浏览”，选中“包括预发行版”并搜索 Microsoft.Azure.CognitiveServices.Vision.Face。选择最新版本，然后选择“安装”。
在控制台窗口（例如 cmd、PowerShell 或 Bash）中，使用 dotnet new 命令创建名为 face-quickstart 的新控制台应用。此命令将创建包含单个源文件的简单“Hello World”C# 项目：program.cs。
```
dotnet new console -n face-quickstart
```
将目录更改为新创建的应用文件夹。可使用以下代码生成应用程序：
```
dotnet build
```
生成输出不应包含警告或错误。
```
...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...
```
安装客户端库

在应用程序目录中，使用以下命令安装适用于 .NET 的人脸客户端库：
```
dotnet add package Microsoft.Azure.CognitiveServices.Vision.Face --prerelease
```

将以下代码添加到 Program.cs 文件。

注意

如果你还没有通过入口表单获得对人脸服务的访问权限，则其中一些功能将不起作用。

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;

using Microsoft.Azure.CognitiveServices.Vision.Face;
using Microsoft.Azure.CognitiveServices.Vision.Face.Models;

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

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

        // From your Face subscription in the Azure portal, get your subscription key and endpoint.
        const string SUBSCRIPTION_KEY = Environment.GetEnvironmentVariable("VISION_KEY");
        const string ENDPOINT = Environment.GetEnvironmentVariable("VISION_ENDPOINT");


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

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

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

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

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

        // Detect faces from image url for recognition purposes. This is a helper method for other functions in this quickstart.
        // Parameter `returnFaceId` of `DetectWithUrlAsync` must be set to `true` (by default) for recognition purposes.
        // Parameter `FaceAttributes` is set to include the QualityForRecognition attribute. 
        // Recognition model must be set to recognition_03 or recognition_04 as a result.
        // Result faces with insufficient quality for recognition are filtered out. 
        // The field `faceId` in returned `DetectedFace`s will be used in Face - Face - Verify and Face - Identify.
        // It will expire 24 hours after the detection call.
        private static async Task<List<DetectedFace>> DetectFaceRecognize(IFaceClient faceClient, string url, string recognition_model)
        {
            // Detect faces from image URL. Since only recognizing, use the recognition model 1.
            // We use detection model 3 because we are not retrieving attributes.
            IList<DetectedFace> detectedFaces = await faceClient.Face.DetectWithUrlAsync(url, recognitionModel: recognition_model, detectionModel: DetectionModel.Detection03, returnFaceAttributes: new List<FaceAttributeType> { FaceAttributeType.QualityForRecognition });
            List<DetectedFace> sufficientQualityFaces = new List<DetectedFace>();
            foreach (DetectedFace detectedFace in detectedFaces){
                var faceQualityForRecognition = detectedFace.FaceAttributes.QualityForRecognition;
                if (faceQualityForRecognition.HasValue && (faceQualityForRecognition.Value >= QualityForRecognition.Medium)){
                    sufficientQualityFaces.Add(detectedFace);
                }
            }
            Console.WriteLine($"{detectedFaces.Count} face(s) with {sufficientQualityFaces.Count} having sufficient quality for recognition detected from image `{Path.GetFileName(url)}`");

            return sufficientQualityFaces.ToList();
        }

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

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

            // Create a person group. 
            Console.WriteLine($"Create a person group ({personGroupId}).");
            await client.PersonGroup.CreateAsync(personGroupId, personGroupId, recognitionModel: recognitionModel);
            // The similar faces will be grouped into a single person group person.
            foreach (var groupedFace in personDictionary.Keys)
            {
                // Limit TPS
                await Task.Delay(250);
                Person person = await client.PersonGroupPerson.CreateAsync(personGroupId: personGroupId, name: groupedFace);
                Console.WriteLine($"Create a person group person '{groupedFace}'.");

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

                    if (!sufficientQuality){
                        continue;
                    }

                    // add face to the person group
                    Console.WriteLine($"Add face to the person group person({groupedFace}) from image `{similarImage}`");
                    PersistedFace face = await client.PersonGroupPerson.AddFaceFromUrlAsync(personGroupId, person.PersonId,
                        $"{url}{similarImage}", similarImage);
                }
            }

            // Start to train the person group.
            Console.WriteLine();
            Console.WriteLine($"Train person group {personGroupId}.");
            await client.PersonGroup.TrainAsync(personGroupId);

            // Wait until the training is completed.
            while (true)
            {
                await Task.Delay(1000);
                var trainingStatus = await client.PersonGroup.GetTrainingStatusAsync(personGroupId);
                Console.WriteLine($"Training status: {trainingStatus.Status}.");
                if (trainingStatus.Status == TrainingStatusType.Succeeded) { break; }
            }
            Console.WriteLine();

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

            // Add detected faceId to sourceFaceIds.
            foreach (var detectedFace in detectedFaces) { sourceFaceIds.Add(detectedFace.FaceId.Value); }
            
            // Identify the faces in a person group. 
            var identifyResults = await client.Face.IdentifyAsync(sourceFaceIds, personGroupId);

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

                VerifyResult verifyResult = await client.Face.VerifyFaceToPersonAsync(identifyResult.FaceId, person.PersonId, personGroupId);
                Console.WriteLine($"Verification result: is a match? {verifyResult.IsIdentical}. confidence: {verifyResult.Confidence}");
            }
            Console.WriteLine();
        }
    }
}

运行应用程序
- Visual Studio IDE
- CLI
单击 IDE 窗口顶部的“调试”按钮，运行应用程序。
从应用程序目录使用 dotnet run 命令运行应用程序。
```
dotnet run
```

输出

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

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

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

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

End of quickstart.

提示

人脸 API 在一组预构建的模型呢上运行，这些模型在本质上是静态的（模型的性能不会因为运行服务而提高或降低）。如果 Microsoft 更新模型的后端，但不迁移整个新模型版本，那么模型生成的结果可能会变化。若要使用更新的模型版本，可重新训练 PersonGroup，将更新的模型指定为具有相同注册映像的参数。

清理资源

如果想要清理并移除 Azure AI 服务订阅，可以删除资源或资源组。删除资源组同时也会删除与之相关联的任何其他资源。

若要删除在本快速入门中创建的 PersonGroup，请在程序中运行以下代码：

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

使用以下代码定义删除方法：

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

后续步骤

在本快速入门中，你已了解如何使用适用于 .NET 的人脸客户端库来执行基本人脸识别。接下来，了解不同的人脸检测模型，学习如何为你的用例指定适当的模型。

指定人脸检测模型版本

什么是人脸服务？
更多的示例代码可在 GitHub 上找到。

开始使用适用于 JavaScript 的人脸客户端库进行人脸识别。请按照以下步骤安装程序包并试用基本任务的示例代码。通过人脸服务，可以访问用于检测和识别图像中的人脸的高级算法。按照以下步骤安装包，并尝试使用远程图像进行基本面部识别的示例代码。

参考文档 | 库源代码 | 包 (npm) | 示例

先决条件

Azure 订阅 - 免费创建订阅
最新版本的 Node.js
你的 Azure 帐户必须分配有 Cognitive Services Contributor 角色，这样你才能同意负责任 AI 条款并创建资源。若要将此角色分配给你的帐户，请按照分配角色文档中的步骤进行操作，或与管理员联系。
拥有 Azure 订阅后，请在 Azure 门户中创建人脸资源，以获取密钥和终结点。部署后，选择”转到资源”。
- 需要从创建的资源获取密钥和终结点，以便将应用程序连接到人脸 API。
- 可以使用免费定价层 (F0) 试用该服务，然后再升级到付费层进行生产。

创建环境变量

在此示例中，将凭据写入运行应用程序的本地计算机上的环境变量。

提示

请不要直接在代码中包含密钥，并且绝不公开发布密钥。有关 Azure Key Vault 等更多身份验证选项，请参阅 Azure AI 服务安全性一文。

若要为密钥和终结点设置环境变量，请打开控制台窗口，并按照操作系统和开发环境的说明进行操作。

若要设置 VISION_KEY 环境变量，请将 your-key 替换为资源的其中一个密钥。
若要设置 VISION_ENDPOINT 环境变量，请将 your-endpoint 替换为资源的终结点。

Windows
Linux

setx VISION_KEY your-key

setx VISION_ENDPOINT your-endpoint

添加环境变量后，可能需要重启任何正在运行的、将读取环境变量的程序（包括控制台窗口）。

export VISION_KEY=your-key

export VISION_ENDPOINT=your-endpoint

添加环境变量后，请从控制台窗口运行 source ~/.bashrc，使更改生效。

识别和验证人脸

创建新的 Node.js 应用程序

在控制台窗口（例如 cmd、PowerShell 或 Bash）中，为应用创建一个新目录并导航到该目录。
```
mkdir myapp && cd myapp
```
运行 npm init 命令以使用 package.json 文件创建一个 node 应用程序。
```
npm init
```
安装 ms-rest-azure 和 azure-cognitiveservices-face NPM 包：
```
npm install @azure/cognitiveservices-face @azure/ms-rest-js uuid
```
应用的 package.json 文件将使用依赖项进行更新。

创建名为 index.js 的文件，在文本编辑器中打开该文件，并粘贴以下代码：

注意

如果你还没有通过入口表单获得对人脸服务的访问权限，则其中一些功能将不起作用。

'use strict';

const msRest = require("@azure/ms-rest-js");
const Face = require("@azure/cognitiveservices-face");
const { v4: uuid } = require('uuid');

const key = process.env.VISION_KEY;
const endpoint = process.env.VISION_ENDPOINT;

const credentials = new msRest.ApiKeyCredentials({ inHeader: { 'Ocp-Apim-Subscription-Key': key } });
const client = new Face.FaceClient(credentials, endpoint);


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

function sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

async function DetectFaceRecognize(url) {
    // Detect faces from image URL. Since only recognizing, use the recognition model 4.
    // We use detection model 3 because we are only retrieving the qualityForRecognition attribute.
    // Result faces with quality for recognition lower than "medium" are filtered out.
    let detected_faces = await client.face.detectWithUrl(url,
        {
            detectionModel: "detection_03",
            recognitionModel: "recognition_04",
            returnFaceAttributes: ["QualityForRecognition"]
        });
    return detected_faces.filter(face => face.faceAttributes.qualityForRecognition == 'high' || face.faceAttributes.qualityForRecognition == 'medium');
}

async function AddFacesToPersonGroup(person_dictionary, person_group_id) {
    console.log ("Adding faces to person group...");
    // The similar faces will be grouped into a single person group person.
    
    await Promise.all (Object.keys(person_dictionary).map (async function (key) {
        const value = person_dictionary[key];


        let person = await client.personGroupPerson.create(person_group_id, { name : key });
        console.log("Create a persongroup person: " + key + ".");

        // Add faces to the person group person.
        await Promise.all (value.map (async function (similar_image) {

            // Wait briefly so we do not exceed rate limits.
            await sleep (1000);


            // Check if the image is of sufficent quality for recognition.
            let sufficientQuality = true;
            let detected_faces = await client.face.detectWithUrl(image_base_url + similar_image,
                {
                    returnFaceAttributes: ["QualityForRecognition"],
                    detectionModel: "detection_03",
                    recognitionModel: "recognition_03"
                });
            detected_faces.forEach(detected_face => {
                if (detected_face.faceAttributes.qualityForRecognition != 'high'){
                    sufficientQuality = false;
                }
            });

            // Wait briefly so we do not exceed rate limits.
            await sleep (1000);

            // Quality is sufficent, add to group.
            if (sufficientQuality){
                console.log("Add face to the person group person: (" + key + ") from image: " + similar_image + ".");
                await client.personGroupPerson.addFaceFromUrl(person_group_id, person.personId, image_base_url + similar_image);
            }
            // Wait briefly so we do not exceed rate limits.
            await sleep (1000);
        }));
    }));

    console.log ("Done adding faces to person group.");
}

async function WaitForPersonGroupTraining(person_group_id) {
    // Wait so we do not exceed rate limits.
    console.log ("Waiting 10 seconds...");
    await sleep (10000);
    let result = await client.personGroup.getTrainingStatus(person_group_id);
    console.log("Training status: " + result.status + ".");
    if (result.status !== "succeeded") {
        await WaitForPersonGroupTraining(person_group_id);
    }
}

/* NOTE This function might not work with the free tier of the Face service
because it might exceed the rate limits. If that happens, try inserting calls
to sleep() between calls to the Face service.
*/
async function IdentifyInPersonGroup() {
    console.log("========IDENTIFY FACES========");
    console.log();

// Create a dictionary for all your images, grouping similar ones under the same key.
    const person_dictionary = {
        "Family1-Dad" : ["Family1-Dad1.jpg", "Family1-Dad2.jpg"],
        "Family1-Mom" : ["Family1-Mom1.jpg", "Family1-Mom2.jpg"],
        "Family1-Son" : ["Family1-Son1.jpg", "Family1-Son2.jpg"],
        "Family1-Daughter" : ["Family1-Daughter1.jpg", "Family1-Daughter2.jpg"],
        "Family2-Lady" : ["Family2-Lady1.jpg", "Family2-Lady2.jpg"],
        "Family2-Man" : ["Family2-Man1.jpg", "Family2-Man2.jpg"]
    };

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

    
    // Create a person group. 
    console.log("Creating a person group with ID: " + person_group_id);
    await client.personGroup.create(person_group_id, person_group_id, {recognitionModel : "recognition_04" });

    await AddFacesToPersonGroup(person_dictionary, person_group_id);

    // Start to train the person group.
    console.log();
    console.log("Training person group: " + person_group_id + ".");
    await client.personGroup.train(person_group_id);

    await WaitForPersonGroupTraining(person_group_id);
    console.log();

    // Detect faces from source image url and only take those with sufficient quality for recognition.
    let face_ids = (await DetectFaceRecognize(image_base_url + source_image_file_name)).map (face => face.faceId);
    
    // Identify the faces in a person group.
    let results = await client.face.identify(face_ids, { personGroupId : person_group_id});
    await Promise.all (results.map (async function (result) {
        try{
            let person = await client.personGroupPerson.get(person_group_id, result.candidates[0].personId);

            console.log("Person: " + person.name + " is identified for face in: " + source_image_file_name + " with ID: " + result.faceId + ". Confidence: " + result.candidates[0].confidence + ".");

            // Verification:
            let verifyResult = await client.face.verifyFaceToPerson(result.faceId, person.personId, {personGroupId : person_group_id});
            console.log("Verification result between face "+ result.faceId +" and person "+ person.personId+ ": " +verifyResult.isIdentical + " with confidence: "+ verifyResult.confidence);

        } catch(error) {
            //console.log("no persons identified for face with ID " + result.faceId);
            console.log(error.toString());
        }
        
    }));
    console.log();
}

async function main() {
    await IdentifyInPersonGroup();
    console.log ("Done.");
}
main();

在快速入门文件中使用 node 命令运行应用程序。
```
node index.js
```

输出

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

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

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

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

清理资源

如果想要清理并移除 Azure AI 服务订阅，可以删除资源或资源组。删除资源组同时也会删除与之相关联的任何其他资源。

后续步骤

在本快速入门中，你已了解如何使用适用于 JavaScript 的人脸客户端库来执行基本人脸识别。接下来，了解不同的人脸检测模型，学习如何为你的用例指定适当的模型。

指定人脸检测模型版本

什么是人脸服务？
更多的示例代码可在 GitHub 上找到。

开始使用适用于 Python 的人脸客户端库进行人脸识别。请按照以下步骤安装程序包并试用基本任务的示例代码。通过人脸服务，可以访问用于检测和识别图像中的人脸的高级算法。按照以下步骤安装包，并尝试使用远程图像进行基本面部识别的示例代码。

参考文档 | 库源代码 | 包 (PiPy) | 示例

先决条件

Azure 订阅 - 免费创建订阅
Python 3.x
- 你的 Python 安装应包含 pip。可以通过在命令行上运行 pip --version 来检查是否安装了 pip。通过安装最新版本的 Python 获取 pip。
你的 Azure 帐户必须分配有 Cognitive Services Contributor 角色，这样你才能同意负责任 AI 条款并创建资源。若要将此角色分配给你的帐户，请按照分配角色文档中的步骤进行操作，或与管理员联系。
拥有 Azure 订阅后，请在 Azure 门户中创建人脸资源，以获取密钥和终结点。部署后，选择”转到资源”。
- 需要从创建的资源获取密钥和终结点，以便将应用程序连接到人脸 API。
- 可以使用免费定价层 (F0) 试用该服务，然后再升级到付费层进行生产。

创建环境变量

在此示例中，将凭据写入运行应用程序的本地计算机上的环境变量。

提示

请不要直接在代码中包含密钥，并且绝不公开发布密钥。有关 Azure Key Vault 等更多身份验证选项，请参阅 Azure AI 服务安全性一文。

若要为密钥和终结点设置环境变量，请打开控制台窗口，并按照操作系统和开发环境的说明进行操作。

若要设置 VISION_KEY 环境变量，请将 your-key 替换为资源的其中一个密钥。
若要设置 VISION_ENDPOINT 环境变量，请将 your-endpoint 替换为资源的终结点。

Windows
Linux

setx VISION_KEY your-key

setx VISION_ENDPOINT your-endpoint

添加环境变量后，可能需要重启任何正在运行的、将读取环境变量的程序（包括控制台窗口）。

export VISION_KEY=your-key

export VISION_ENDPOINT=your-endpoint

添加环境变量后，请从控制台窗口运行 source ~/.bashrc，使更改生效。

识别和验证人脸

安装客户端库

在安装 Python 后，可以通过以下命令安装客户端库：
```
pip install --upgrade azure-cognitiveservices-vision-face
```

创建新的 Python 应用程序

创建新的 Python 脚本，例如 quickstart-file.py。然后在偏好的编辑器或 IDE 中打开它，并粘贴以下代码。

注意

如果你还没有通过入口表单获得对人脸服务的访问权限，则其中一些功能将不起作用。

import asyncio
import io
import os
import sys
import time
import uuid
import requests
from urllib.parse import urlparse
from io import BytesIO
# To install this module, run:
# python -m pip install Pillow
from PIL import Image, ImageDraw
from azure.cognitiveservices.vision.face import FaceClient
from msrest.authentication import CognitiveServicesCredentials
from azure.cognitiveservices.vision.face.models import TrainingStatusType, Person, QualityForRecognition


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

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

# Base url for the Verify and Facelist/Large Facelist operations
IMAGE_BASE_URL = 'https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/'

# Used in the Person Group Operations and Delete Person Group examples.
# You can call list_person_groups to print a list of preexisting PersonGroups.
# SOURCE_PERSON_GROUP_ID should be all lowercase and alphanumeric. For example, 'mygroupname' (dashes are OK).
PERSON_GROUP_ID = str(uuid.uuid4()) # assign a random ID (or name it anything)

# Used for the Delete Person Group example.
TARGET_PERSON_GROUP_ID = str(uuid.uuid4()) # assign a random ID (or name it anything)

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

'''
Create the PersonGroup
'''
# Create empty Person Group. Person Group ID must be lower case, alphanumeric, and/or with '-', '_'.
print('Person group:', PERSON_GROUP_ID)
face_client.person_group.create(person_group_id=PERSON_GROUP_ID, name=PERSON_GROUP_ID, recognition_model='recognition_04')

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

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

# Add to woman person
for image in woman_images:
    # Check if the image is of sufficent quality for recognition.
    sufficientQuality = True
    detected_faces = face_client.face.detect_with_url(url=image, detection_model='detection_03', recognition_model='recognition_04', return_face_attributes=['qualityForRecognition'])
    for face in detected_faces:
        if face.face_attributes.quality_for_recognition != QualityForRecognition.high:
            sufficientQuality = False
            break
        face_client.person_group_person.add_face_from_url(PERSON_GROUP_ID, woman.person_id, image)
        print("face {} added to person {}".format(face.face_id, woman.person_id))

    if not sufficientQuality: continue

# Add to man person
for image in man_images:
    # Check if the image is of sufficent quality for recognition.
    sufficientQuality = True
    detected_faces = face_client.face.detect_with_url(url=image, detection_model='detection_03', recognition_model='recognition_04', return_face_attributes=['qualityForRecognition'])
    for face in detected_faces:
        if face.face_attributes.quality_for_recognition != QualityForRecognition.high:
            sufficientQuality = False
            break
        face_client.person_group_person.add_face_from_url(PERSON_GROUP_ID, man.person_id, image)
        print("face {} added to person {}".format(face.face_id, man.person_id))

    if not sufficientQuality: continue

# Add to child person
for image in child_images:
    # Check if the image is of sufficent quality for recognition.
    sufficientQuality = True
    detected_faces = face_client.face.detect_with_url(url=image, detection_model='detection_03', recognition_model='recognition_04', return_face_attributes=['qualityForRecognition'])
    for face in detected_faces:
        if face.face_attributes.quality_for_recognition != QualityForRecognition.high:
            sufficientQuality = False
            print("{} has insufficient quality".format(face))
            break
        face_client.person_group_person.add_face_from_url(PERSON_GROUP_ID, child.person_id, image)
        print("face {} added to person {}".format(face.face_id, child.person_id))
    if not sufficientQuality: continue


'''
Train PersonGroup
'''
# Train the person group
print("pg resource is {}".format(PERSON_GROUP_ID))
rawresponse = face_client.person_group.train(PERSON_GROUP_ID, raw= True)
print(rawresponse)

while (True):
    training_status = face_client.person_group.get_training_status(PERSON_GROUP_ID)
    print("Training status: {}.".format(training_status.status))
    print()
    if (training_status.status is TrainingStatusType.succeeded):
        break
    elif (training_status.status is TrainingStatusType.failed):
        face_client.person_group.delete(person_group_id=PERSON_GROUP_ID)
        sys.exit('Training the person group has failed.')
    time.sleep(5)

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

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

# Detect faces
face_ids = []
# We use detection model 3 to get better performance, recognition model 4 to support quality for recognition attribute.
faces = face_client.face.detect_with_url(test_image, detection_model='detection_03', recognition_model='recognition_04', return_face_attributes=['qualityForRecognition'])
for face in faces:
    # Only take the face if it is of sufficient quality.
    if face.face_attributes.quality_for_recognition == QualityForRecognition.high or face.face_attributes.quality_for_recognition == QualityForRecognition.medium:
        face_ids.append(face.face_id)

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

        # Verify faces
        verify_result = face_client.face.verify_face_to_person(identifiedFace.face_id, identifiedFace.candidates[0].person_id, PERSON_GROUP_ID)
        print('verification result: {}. confidence: {}'.format(verify_result.is_identical, verify_result.confidence))
    else:
        print('No person identified for face ID {} in image.'.format(identifiedFace.face_id))
 

print()
print('End of quickstart.')

使用 python 命令从应用程序目录运行人脸识别应用。
```
python quickstart-file.py
```
提示

人脸 API 在一组预构建的模型呢上运行，这些模型在本质上是静态的（模型的性能不会因为运行服务而提高或降低）。如果 Microsoft 更新模型的后端，但不迁移整个新模型版本，那么模型生成的结果可能会变化。若要使用更新的模型版本，可重新训练 PersonGroup，将更新的模型指定为具有相同注册映像的参数。

输出

Person group: c8e679eb-0b71-43b4-aa91-ab8200cae7df
face 861d769b-d014-40e8-8b4a-7fd3bc9b425b added to person f80c1cfa-b8cb-46f8-9f7f-e72fbe402bc3
face e3c356a4-1ac3-4c97-9219-14648997f195 added to person f80c1cfa-b8cb-46f8-9f7f-e72fbe402bc3
face f9119820-c374-4c4d-b795-96ae2fec5069 added to person be4084a7-0c7b-4cf9-9463-3756d2e28e17
face 67d626df-3f75-4801-9364-601b63c8296a added to person be4084a7-0c7b-4cf9-9463-3756d2e28e17
face 19e2e8cc-5029-4087-bca0-9f94588fb850 added to person 3ff07c65-6193-4d3e-bf18-d7c106393cd5
face dcc61e80-16b1-4241-ae3f-9721597bae4c added to person 3ff07c65-6193-4d3e-bf18-d7c106393cd5
pg resource is c8e679eb-0b71-43b4-aa91-ab8200cae7df
<msrest.pipeline.ClientRawResponse object at 0x00000240DAD47310>
Training status: running.

Training status: succeeded.

Pausing for 10 seconds to avoid triggering rate limit on free account...
Identifying faces in image
Person for face ID 40582995-d3a8-41c4-a9d1-d17ae6b46c5c is identified in image, with a confidence of 0.96725.
Person for face ID 7a0368a2-332c-4e7a-81c4-2db3d74c78c5 is identified in image, with a confidence of 0.96921.
No person identified for face ID c4a3dd28-ef2d-457e-81d1-a447344242c4 in image.
Person for face ID 360edf1a-1e8f-402d-aa96-1734d0c21c1c is identified in image, with a confidence of 0.92886.

清理资源

如果想要清理并移除 Azure AI 服务订阅，可以删除资源或资源组。删除资源组同时也会删除与之相关联的任何其他资源。

若要删除在本快速入门中创建的 PersonGroup，请在脚本中运行以下代码：

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

后续步骤

在本快速入门中，你已了解如何使用适用于 Python 的人脸客户端库来执行基本人脸识别。接下来，了解不同的人脸检测模型，学习如何为你的用例指定适当的模型。

指定人脸检测模型版本

什么是人脸服务？
更多的示例代码可在 GitHub 上找到。

开始使用人脸 REST API 进行人脸识别。通过人脸服务，可以访问用于检测和识别图像中的人脸的高级算法。

注意

此快速入门使用 cURL 命令来调用 REST API。也可以使用编程语言调用 REST API。使用语言 SDK 可以更容易实现人脸识别等复杂方案。请参阅 GitHub 示例，查看 C#、Python、Java、JavaScript 和 Go 的相关示例。

先决条件

Azure 订阅 - 免费创建订阅
你的 Azure 帐户必须分配有 Cognitive Services Contributor 角色，这样你才能同意负责任 AI 条款并创建资源。若要将此角色分配给你的帐户，请按照分配角色文档中的步骤进行操作，或与管理员联系。
拥有 Azure 订阅后，请在 Azure 门户中创建人脸资源，以获取密钥和终结点。部署后，选择”转到资源”。
- 需要从创建的资源获取密钥和终结点，以便将应用程序连接到人脸 API。你稍后会在快速入门中将密钥和终结点粘贴到下方的代码中。
- 可以使用免费定价层 (F0) 试用该服务，然后再升级到付费层进行生产。
PowerShell 6.0 及以上版本，或类似的命令行应用程序。

识别和验证人脸

注意

如果你还没有通过入口表单获得对人脸服务的访问权限，则其中一些功能将不起作用。

首先，在源人脸上调用检测 API。这是我们试图从更大的群体中识别的人脸。将以下命令复制到文本编辑器，插入自己的密钥，然后将其复制到 shell 窗口中并运行它。

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

将返回的人脸 ID 字符串保存到临时位置。你将在最后再次使用它。

接下来，需要创建 LargePersonGroup。此对象将存储多人的聚合人脸数据。运行以下命令，插入自己的密钥。或者，在请求正文中更改组的名称和元数据。

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

将创建的组的返回 ID 保存到临时位置。

接下来，你将创建属于该组的人员对象。运行以下命令，插入自己的密钥和上一步中的 LargePersonGroup 的 ID。此命令创建名为 Family1-Dad 的人员。
```
curl -v -X POST "https://westus.api.cognitive.microsoft.com/face/v1.0/largepersongroups/{largePersonGroupId}/persons" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{
    \"name\": \"Family1-Dad\",
    \"userData\": \"User-provided data attached to the person.\"
}"
```
运行此命令后，使用不同的输入数据再次运行它，以创建更多人员对象：Family1-Mom、Family1-Son、Family1-Daughter、Family2-Lady 和 Family2-Man。

保存创建的每个人员的 ID；务必记下哪些人名具有哪个 ID。
接下来，需要检测新人脸并将其与已有的人员对象相关联。以下命令从图像 Family1-Dad1.jpg 检测人脸，并将其添加到对应人员。需要将 personId 制定为创建 Family1-Dad 人员对象时返回的 ID。图像名称对应于所创建人员的名称。此外，请在相应的字段中输入 LargePersonGroup ID 和密钥。
```
curl -v -X POST "https://westus.api.cognitive.microsoft.com/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces?detectionModel=detection_03" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii '{\"url\":\"https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Dad1.jpg\"}'
```
然后，使用不同的源图像和目标人员对象再次运行上述命令。可用的图像包括：Family1-Dad1.jpg、Family1-Dad2.jpg、Family1-Mom1.jpg、Family1-Mom2.jpg、Family1-Son1.jpg、Family1-Son2.jpg、Family1-Daughter1.jpg、Family1-Daughter2.jpg、Family2-Lady1.jpg、Family2-Lady2.jpg、Family2-Man1.jpg 和 Family2-Man2.jpg。请确保你在 API 调用中指定的人员 ID 与请求正文中的图像文件名称相匹配。

在此步骤结束时，应有多个人员对象，每个对象都有一个或多个对应的人脸，可以直接从提供的图像检测到。
接下来，使用当前人脸数据训练 LargePersonGroup 。训练操作教模型如何将面部特征（有时从多个源图像聚合而来）与每个人相关联。在运行命令之前插入 LargePersonGroup ID 和密钥。
```
curl -v -X POST "https://westus.api.cognitive.microsoft.com/face/v1.0/largepersongroups/{largePersonGroupId}/train" -H "Ocp-Apim-Subscription-Key: {subscription key}"
```

现在，你已准备好使用第一步中的源人脸 ID 和 LargePersonGroup ID 调用识别 API。将这些值插入请求正文中的相应字段，并插入密钥。

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

响应返回一个人员 ID，指示该人员由源人脸识别。它应该是对应于 Family1-Dad 人员的 ID，因为源人脸是这个人。

若要执行人脸验证，需使用上一步返回的人员 ID、LargePersonGroup ID 以及源人脸 ID。请将这些值插入请求正文中的字段，并插入密钥。

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

响应应提供布尔验证结果以及置信度值。

清理资源

若要删除在本练习中创建的 LargePersonGrou，请运行 LargePersonGroup - Delete 调用。

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

如果想要清理并移除 Azure AI 服务订阅，则可以删除资源或资源组。删除资源组同时也会删除与之相关联的任何其他资源。

后续步骤

在本快速入门中，你已了解如何使用人脸 REST API 来执行基本人脸识别任务。接下来，了解不同的人脸检测模型，学习如何为你的用例指定适当的模型。

指定人脸检测模型版本

什么是人脸服务？

快速入门：使用人脸服务

先决条件

创建环境变量

识别和验证人脸

安装客户端库

输出

清理资源

后续步骤

先决条件

创建环境变量

识别和验证人脸

输出

清理资源

后续步骤

先决条件

创建环境变量

识别和验证人脸

输出

清理资源

后续步骤

先决条件

识别和验证人脸

清理资源

后续步骤

其他资源