快速入門:使用臉部服務

重要

如果您使用 Microsoft 產品或服務來處理生物特徵辨識數據,您必須負責:(i) 向數據主體提供通知,包括保留期間和銷毀:(二) 取得數據主體的同意:和 (iii) 刪除生物特徵辨識數據,在適用的數據保護需求下,一切適當且必要。 「生物特徵辨識數據」將具有GDPR第4條中所述的意義,如果適用的話,其他數據保護需求中的對等詞彙。 如需相關信息,請參閱 臉部的數據與隱私權。

警告

臉部服務存取受限於資格和使用準則,以支援我們的負責任 AI 原則。 臉部服務僅適用於 Microsoft 受控客戶和合作夥伴。 使用臉部辨識接收窗體來申請存取。 如需詳細資訊,請參閱 臉部有限存取 頁面。

使用適用於 .NET 的臉部用戶端連結庫開始使用臉部辨識。 臉部服務可讓您存取進階演算法,以偵測和辨識影像中的人臉。 請遵循下列步驟來安裝套件,並試用使用遠端影像進行基本臉部識別的範例程序代碼。

參考文檔 | 庫原始程式碼 | 套件 (NuGet)範例 |

必要條件

  • Azure 訂用帳戶 - 免費建立一個訂用帳戶
  • Visual Studio IDE 或 .NET Core目前版本。
  • Azure 帳戶必須已獲指派 Cognitive Services Contributor 角色,您才能同意負責任的 AI 條款並建立資源。 若要將此角色指派給您的帳戶,請遵循指派角色檔中的步驟,或連絡您的系統管理員。
  • 擁有 Azure 訂用帳戶之後,請在 Azure 入口網站 中建立臉部資源,以取得您的密鑰和端點。 部署之後,請選取 [移至資源]。
    • 您需要從您建立的資源取得密鑰和端點,才能將應用程式連線到臉部 API。
    • 您可以使用免費定價層 (F0) 來試用服務,稍後再升級至生產環境的付費層。

建立環境變數

在此範例中,在執行應用程式的本機電腦上將認證寫入環境變數。

前往 Azure 入口網站。 如果已成功部署您在 [必要條件] 區段中建立的資源,請選取 [後續步驟] 下的 [前往資源] 按鈕。 您可以在 [金鑰和端點] 頁面中 [資源管理] 底下找到金鑰和端點。 您的資源金鑰與您的 Azure 訂用帳戶識別碼不同。

提示

請勿將金鑰直接包含在您的程式代碼中,且絕不會公開發佈。 如需更多驗證選項 (例如 Azure Key Vault),請參閱 Azure AI 服務安全性文章。

若要設定金鑰和端點的環境變數,請開啟主控台視窗,然後遵循作業系統和開發環境的指示進行。

  1. 若要設定 VISION_KEY 環境變數,請將 取代 your-key 為您資源的其中一個密鑰。
  2. 若要設定 VISION_ENDPOINT 環境變數,請將 取代 your-endpoint 為您資源的端點。
setx VISION_KEY your-key
setx VISION_ENDPOINT your-endpoint

新增環境變數之後,您可能需要重新啟動任何將讀取環境變數的執行中程式,包括主控台視窗。

識別並驗證臉部

  1. 建立新的 C# 應用程式

    使用 Visual Studio 建立新的 .NET Core 應用程式。

    安裝客戶端連結庫

    建立新項目之後,請以滑鼠右鍵按兩下 方案總管 中的專案方案,然後選取 [管理 NuGet 套件],以安裝客戶端連結庫。 開啟的套件管理員中,選取 [ 瀏覽],勾選 [包含發行前版本],然後搜尋 Microsoft.Azure.CognitiveServices.Vision.Face。 選取最新版本,然後 選取 [安裝]。

  2. 將下列程式代碼新增至 Program.cs 檔案。

    注意

    如果您尚未使用 取用表單來存取臉部服務,部分函式將無法運作。

    using System;
    using System.Collections.Generic;
    using System.IO;
    using System.Linq;
    using System.Threading;
    using System.Threading.Tasks;
    
    using Microsoft.Azure.CognitiveServices.Vision.Face;
    using Microsoft.Azure.CognitiveServices.Vision.Face.Models;
    
    namespace FaceQuickstart
    {
        class Program
        {
            static string personGroupId = Guid.NewGuid().ToString();
    
            // URL path for the images.
            const string IMAGE_BASE_URL = "https://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();
            }
        }
    }
    
  3. 執行應用程式

    按兩下 IDE 視窗頂端的 [偵錯] 按鈕,以執行應用程式。

輸出

========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 的臉部用戶端連結庫來執行基本臉部識別。 接下來,瞭解不同的臉部偵測模型,以及如何為您的使用案例指定正確的模型。

使用適用於 JavaScript 的臉部用戶端連結庫開始使用臉部辨識。 請遵循下列步驟來安裝套件,並試用基本工作的範例程序代碼。 臉部服務可讓您存取進階演算法,以偵測和辨識影像中的人臉。 請遵循下列步驟來安裝套件,並試用使用遠端影像進行基本臉部識別的範例程序代碼。

參考文檔 | 庫原始程式碼 | 套件 (npm)範例 |

必要條件

  • Azure 訂用帳戶 - 免費建立一個訂用帳戶
  • 最新版 的 Node.js
  • Azure 帳戶必須已獲指派 Cognitive Services Contributor 角色,您才能同意負責任的 AI 條款並建立資源。 若要將此角色指派給您的帳戶,請遵循指派角色檔中的步驟,或連絡您的系統管理員。
  • 擁有 Azure 訂用帳戶之後,請在 Azure 入口網站 中建立臉部資源,以取得您的密鑰和端點。 部署之後,請選取 [移至資源]。
    • 您需要從您建立的資源取得密鑰和端點,才能將應用程式連線到臉部 API。
    • 您可以使用免費定價層 (F0) 來試用服務,稍後再升級至生產環境的付費層。

建立環境變數

在此範例中,在執行應用程式的本機電腦上將認證寫入環境變數。

前往 Azure 入口網站。 如果已成功部署您在 [必要條件] 區段中建立的資源,請選取 [後續步驟] 下的 [前往資源] 按鈕。 您可以在 [金鑰和端點] 頁面中 [資源管理] 底下找到金鑰和端點。 您的資源金鑰與您的 Azure 訂用帳戶識別碼不同。

提示

請勿將金鑰直接包含在您的程式代碼中,且絕不會公開發佈。 如需更多驗證選項 (例如 Azure Key Vault),請參閱 Azure AI 服務安全性文章。

若要設定金鑰和端點的環境變數,請開啟主控台視窗,然後遵循作業系統和開發環境的指示進行。

  1. 若要設定 VISION_KEY 環境變數,請將 取代 your-key 為您資源的其中一個密鑰。
  2. 若要設定 VISION_ENDPOINT 環境變數,請將 取代 your-endpoint 為您資源的端點。
setx VISION_KEY your-key
setx VISION_ENDPOINT your-endpoint

新增環境變數之後,您可能需要重新啟動任何將讀取環境變數的執行中程式,包括主控台視窗。

識別並驗證臉部

  1. 建立新的Node.js應用程式

    在主控台視窗中(例如 cmd、PowerShell 或 Bash),為您的應用程式建立新的目錄,然後流覽至它。

    mkdir myapp && cd myapp
    

    npm init執行 命令以使用 package.json 檔案建立節點應用程式。

    npm init
    
  2. ms-rest-azure安裝 和 azure-cognitiveservices-face npm 套件:

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

    您的應用程式檔案 package.json 會隨著相依性更新。

  3. 建立名為 index.js的檔案,在文字編輯器中開啟它,然後貼上下列程序代碼:

    注意

    如果您尚未使用 取用表單來存取臉部服務,部分函式將無法運作。

    'use strict';
    
    const msRest = require("@azure/ms-rest-js");
    const Face = require("@azure/cognitiveservices-face");
    const { v4: uuid } = require('uuid');
    
    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();
    
  4. 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 的臉部用戶端連結庫來執行基本的臉部識別。 接下來,瞭解不同的臉部偵測模型,以及如何為您的使用案例指定正確的模型。

使用適用於 Python 的臉部用戶端連結庫開始使用臉部辨識。 請遵循下列步驟來安裝套件,並試用基本工作的範例程序代碼。 臉部服務可讓您存取進階演算法,以偵測和辨識影像中的人臉。 請遵循下列步驟來安裝套件,並試用使用遠端影像進行基本臉部識別的範例程序代碼。

參考文檔 | 庫原始程式碼 | 套件 (PiPy)範例 |

必要條件

  • Azure 訂用帳戶 - 免費建立一個訂用帳戶
  • Python 3.x
    • 您的 Python 安裝應該包含 pip。 您可以藉由在命令列上執行 pip --version 來檢查您是否已安裝 pip。 安裝最新版本的 Python 以取得 pip。
  • Azure 帳戶必須已獲指派 Cognitive Services Contributor 角色,您才能同意負責任的 AI 條款並建立資源。 若要將此角色指派給您的帳戶,請遵循指派角色檔中的步驟,或連絡您的系統管理員。
  • 擁有 Azure 訂用帳戶之後,請在 Azure 入口網站 中建立臉部資源,以取得您的密鑰和端點。 部署之後,請選取 [移至資源]。
    • 您需要從您建立的資源取得密鑰和端點,才能將應用程式連線到臉部 API。
    • 您可以使用免費定價層 (F0) 來試用服務,稍後再升級至生產環境的付費層。

建立環境變數

在此範例中,在執行應用程式的本機電腦上將認證寫入環境變數。

前往 Azure 入口網站。 如果已成功部署您在 [必要條件] 區段中建立的資源,請選取 [後續步驟] 下的 [前往資源] 按鈕。 您可以在 [金鑰和端點] 頁面中 [資源管理] 底下找到金鑰和端點。 您的資源金鑰與您的 Azure 訂用帳戶識別碼不同。

提示

請勿將金鑰直接包含在您的程式代碼中,且絕不會公開發佈。 如需更多驗證選項 (例如 Azure Key Vault),請參閱 Azure AI 服務安全性文章。

若要設定金鑰和端點的環境變數,請開啟主控台視窗,然後遵循作業系統和開發環境的指示進行。

  1. 若要設定 VISION_KEY 環境變數,請將 取代 your-key 為您資源的其中一個密鑰。
  2. 若要設定 VISION_ENDPOINT 環境變數,請將 取代 your-endpoint 為您資源的端點。
setx VISION_KEY your-key
setx VISION_ENDPOINT your-endpoint

新增環境變數之後,您可能需要重新啟動任何將讀取環境變數的執行中程式,包括主控台視窗。

識別並驗證臉部

  1. 安裝客戶端連結庫

    安裝 Python 之後,您可以使用下列項目來安裝用戶端連結庫:

    pip install --upgrade azure-cognitiveservices-vision-face
    
  2. 建立新的 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.')
    
    
  3. 使用 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 的臉部用戶端連結庫來執行基本臉部識別。 接下來,瞭解不同的臉部偵測模型,以及如何為您的使用案例指定正確的模型。

使用臉部 REST API 開始使用臉部辨識。 臉部服務可讓您存取進階演算法,以偵測和辨識影像中的人臉。

注意

本快速入門會使用 cURL 命令來呼叫 REST API。 您也可以使用程式設計語言呼叫 REST API。 臉部識別等複雜案例更容易使用語言 SDK 來實作。 如需 C#、PythonJava、JavaScriptGo 中的範例,請參閱 GitHub 範例。

必要條件

  • Azure 訂用帳戶 - 免費建立一個訂用帳戶
  • Azure 帳戶必須已獲指派 Cognitive Services Contributor 角色,您才能同意負責任的 AI 條款並建立資源。 若要將此角色指派給您的帳戶,請遵循指派角色檔中的步驟,或連絡您的系統管理員。
  • 擁有 Azure 訂用帳戶之後,請在 Azure 入口網站 中建立臉部資源,以取得您的密鑰和端點。 部署之後,請選取 [移至資源]。
    • 您需要從您建立的資源取得密鑰和端點,才能將應用程式連線到臉部 API。 您稍後會在快速入門中將金鑰和端點貼到下列程式代碼中。
    • 您可以使用免費定價層 (F0) 來試用服務,稍後再升級至生產環境的付費層。
  • PowerShell 6.0 版或類似的命令行應用程式。

識別並驗證臉部

注意

如果您尚未使用 取用表單來存取臉部服務,部分函式將無法運作。

  1. 首先,在來源臉部上呼叫偵測 API。 這是我們將嘗試從較大的群組識別的臉部。 將下列命令複製到文本編輯器、插入您自己的金鑰,然後將它複製到殼層視窗並加以執行。

    curl -v -X POST "https://westus.api.cognitive.microsoft.com/face/v1.0/detect?returnFaceId=true&returnFaceLandmarks=false&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\"}'
    

    將傳回的臉部標識符字串儲存到暫存位置。 您會在結尾再次使用它。

  2. 接下來,您必須建立 LargePersonGroup。 此物件會儲存數人的匯總臉部數據。 執行下列命令,插入您自己的金鑰。 選擇性地變更要求主體中的群組名稱和元數據。

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

    將所建立群組的傳回標識碼儲存至暫存位置。

  3. 接下來,您將建立 屬於群組的 Person 物件。 執行下列命令,從上一個步驟插入您自己的密鑰和 LargePersonGroup識別碼。 此命令會 建立名為 「Family1-Dad」 的人員

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

    執行此命令之後,請以不同的輸入數據再次執行它,以建立更多 Person 物件:“Family1-Mom”、“Family1-Son”、“Family1-Daughter”、“Family2-Lady”和 “Family2-Man”。

    儲存所建立每個人的標識碼;請務必追蹤哪些人員名稱具有哪個標識符。

  4. 接下來,您必須偵測新的臉部,並將其與 存在的 Person 對象產生關聯。 下列命令會從影像 Family1-Dad1.jpg 偵測臉部,並將它新增至對應的人員。 您必須將 指定 personId 為建立 「Family1-Dad」 Person 物件時所傳回的識別碼。 映像名稱會對應至所建立 人員的名稱。 此外, 請在適當的欄位中輸入 LargePersonGroup 識別碼和密鑰。

    curl -v -X POST "https://westus.api.cognitive.microsoft.com/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces?detectionModel=detection_03" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii '{\"url\":\"https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Dad1.jpg\"}'
    

    然後,以不同的來源映像和目標 Person 再次執行上述命令。 可用的映射包括:Family1-Dad1.jpg、Family1-Dad2.jpg Family1-Mom1.jpg、Family1-Mom2.jpgFamily1-Son1.jpg、Family1-Son2.jpg、Family1-Daughter1.jpg、Family1-Daughter2.jpg、Family2-Lady1.jpg、Family2-Lady2.jpg、Family2-Man1.jpg和Family2-Man2.jpg。 請確定您在 API 呼叫中指定的識別碼符合要求本文中影像檔的名稱。

    在此步驟結束時,您應該有多個 Person 物件,每個物件都有一或多個對應的臉部,直接從提供的影像偵測到。

  5. 接下來,使用目前的臉部數據來 定型 LargePersonGroup 。 定型作業會教導模型如何將臉部特徵,有時從多個來源影像匯總到每個人員。 在執行命令之前, 請先插入 LargePersonGroup 識別碼和密鑰。

    curl -v -X POST "https://westus.api.cognitive.microsoft.com/face/v1.0/largepersongroups/{largePersonGroupId}/train" -H "Ocp-Apim-Subscription-Key: {subscription key}"
    
  6. 現在您已準備好使用來自第一個步驟的來源臉部標識碼和 LargePersonGroup 識別碼來呼叫識別 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
    }"
    

    回應應該會提供一個 人員 標識碼,指出以來源臉部識別的人員。 它應該是對應到「家庭一爸爸」人員的標識符,因為來源臉部是該人。

  7. 若要進行臉部驗證,您將使用上一個步驟中傳回的人員標識碼 LargePersonGroup 識別符,以及來源臉部標識碼。 將這些值插入要求本文中的欄位,然後插入您的索引鍵。

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

    回應應該會提供布爾驗證結果以及信賴值。

清除資源

若要刪除您在此練習中建立的 LargePersonGroup ,請執行 LargePersonGroup - Delete 呼叫。

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

如果您想要清除和移除 Azure AI 服務訂用帳戶,則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。

下一步

在本快速入門中,您已瞭解如何使用臉部 REST API 來執行基本的臉部辨識工作。 接下來,瞭解不同的臉部偵測模型,以及如何為您的使用案例指定正確的模型。