Schnellstart: Verwenden des Gesichtserkennungsdiensts

Artikel
09/03/2024

Wichtig

Wenn Sie Microsoft-Produkte oder -Dienste zur Verarbeitung biometrischer Daten verwenden, sind Sie für Folgendes verantwortlich: (i) Unterrichten der betroffenen Personen, auch über die Aufbewahrungsfristen und die Vernichtung; (ii) Einholen der Zustimmung der betroffenen Personen und (iii) Löschen der biometrischen Daten, soweit dies nach den geltenden Datenschutzvorschriften angemessen und erforderlich ist. „Biometrische Daten“ hat die in Artikel 4 der Datenschutz-Grundverordnung (DSGVO) und gegebenenfalls in anderen Datenschutzvorschriften festgelegte Bedeutung. Weitere Informationen finden Sie unter Daten und Datenschutz bei der Gesichtserkennung.

Achtung

Der Zugriff auf den Gesichtserkennungsdienst ist auf der Grundlage von Berechtigungs- und Nutzungskriterien begrenzt, um unsere Prinzipien für verantwortungsvolle KI zu unterstützen. Der Gesichtserkennungsdienst ist nur für von Microsoft verwaltete Kunden und Partner verfügbar. Verwenden Sie das Aufnahmeformular für die Gesichtserkennung, um sich für den Zugriff zu bewerben. Weitere Informationen finden Sie auf der Seite Eingeschränkter Zugriff auf die Gesichtserkennung.

Erste Schritte mit Gesichtserkennung unter Verwendung der Gesichtserkennungs-Clientbibliothek für .NET. Der Azure KI-Gesichtserkennungsdienst bietet Ihnen Zugriff auf erweiterte Algorithmen für die Erkennung von menschlichen Gesichtern in Bildern. Führen Sie diese Schritte aus, um das Paket zu installieren und den Beispielcode für eine einfache Gesichtserkennung mithilfe von remote gespeicherten Bildern auszuprobieren.

Referenzdokumentation | Quellcode der Bibliothek | Paket (NuGet) | Beispiele

Voraussetzungen

Azure-Abonnement – Erstellen eines kostenlosen Kontos
Die Visual Studio-IDE oder die aktuelle Version von .NET Core.
Wenn Sie über Ihr Azure-Abonnement verfügen, sollten Sie im Azure-Portal eine Gesichtserkennungsressource erstellen, um Ihren Schlüssel und Endpunkt abzurufen. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
- Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der Gesichtserkennungs-API zu verbinden.
- Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Erstellen von Umgebungsvariablen

In diesem Beispiel schreiben Sie Ihre Anmeldeinformationen in Umgebungsvariablen auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird.

Öffnen Sie das Azure-Portal. Wenn die Ressource, die Sie im Abschnitt Voraussetzungen erstellt haben, erfolgreich bereitgestellt wurde, wählen Sie unter Nächste Schritte die Option Zu Ressource wechseln aus. Schlüssel und Endpunkt finden Sie unter Ressourcenverwaltung auf der Seite Schlüssel und Endpunkte. Ihr Ressourcenschlüssel ist nicht mit Ihrer Azure-Abonnement-ID identisch.

Um die Umgebungsvariable für Ihren Ressourcenschlüssel und Endpunkt festzulegen, öffnen Sie ein Konsolenfenster und befolgen Sie die Anweisungen für Ihr Betriebssystem und Ihre Entwicklungsumgebung.

Zum Festlegen der Umgebungsvariablen FACE_APIKEY ersetzen Sie <your_key> durch einen der Schlüssel für Ihre Ressource.
Zum Festlegen der Umgebungsvariablen FACE_ENDPOINT ersetzen Sie <your_endpoint> durch den Endpunkt für Ihre Ressource.

Wichtig

Wenn Sie einen API-Schlüssel verwenden, speichern Sie ihn an einer anderen Stelle sicher, z. B. in Azure Key Vault. Fügen Sie den API-Schlüssel nicht direkt in Ihren Code ein, und machen Sie ihn nicht öffentlich zugänglich.

Weitere Informationen zur Sicherheit von KI Services finden Sie unter Authentifizieren von Anforderungen an Azure KI Services.

Windows
Linux

setx FACE_APIKEY <your_key>

setx FACE_ENDPOINT <your_endpoint>

Nachdem Sie die Umgebungsvariable hinzugefügt haben, müssen Sie unter Umständen alle ausgeführten Programme neu starten, von denen die Umgebungsvariablen gelesen werden, einschließlich des Konsolenfensters.

export FACE_APIKEY=<your_key>

export FACE_ENDPOINT=<your_endpoint>

Führen Sie nach dem Hinzufügen der Umgebungsvariablen im Konsolenfenster source ~/.bashrc aus, damit die Änderungen wirksam werden.

Identifizieren und Überprüfen von Gesichtern

Erstellen einer neuen C#-Anwendung
- Visual Studio-IDE
- BEFEHLSZEILENSCHNITTSTELLE (CLI)
Erstellen Sie mit Visual Studio eine neue .NET Core-Anwendung.

Installieren der Clientbibliothek

Installieren Sie nach der Erstellung eines neuen Projekts die Clientbibliothek, indem Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Projektmappe klicken und NuGet-Pakete verwalten auswählen. Wählen Sie im daraufhin geöffneten Paket-Manager die Option Durchsuchen aus, aktivieren Sie das Kontrollkästchen Vorabversion einbeziehen, und suchen Sie nach Azure.AI.Vision.Face. Wählen Sie die neueste Version und dann die Option Installieren aus.
Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen face-quickstart. Dieser Befehl erstellt ein einfaches C#-Projekt vom Typ „Hallo Welt“ mit einer einzelnen Quelldatei: program.cs.
```
dotnet new console -n face-quickstart
```
Wechseln Sie zum Ordner der neu erstellten App. Sie können die Anwendung mit folgendem Befehl erstellen:
```
dotnet build
```
Die Buildausgabe sollte keine Warnungen oder Fehler enthalten.
```
...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...
```
Installieren der Clientbibliothek

Installieren Sie im Anwendungsverzeichnis mit dem folgenden Befehl die Clientbibliothek zur Gesichtserkennung für .NET:
```
dotnet add package Azure.AI.Vision.Face --prerelease
```

Fügen Sie den folgenden Code in die Datei Program.cs ein.

Hinweis

Wenn Sie keinen Zugriff auf den Gesichtserkennungsdienst über das Aufnahmeformular erhalten haben, können Sie einige dieser Funktionen nicht nutzen.

using System.Net.Http.Headers;
using System.Text;

using Azure;
using Azure.AI.Vision.Face;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

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

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

        // From your Face subscription in the Azure portal, get your subscription key and endpoint.
        static readonly string SUBSCRIPTION_KEY = Environment.GetEnvironmentVariable("FACE_APIKEY") ?? "<apikey>";
        static readonly string ENDPOINT = Environment.GetEnvironmentVariable("FACE_ENDPOINT") ?? "<endpoint>";

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

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

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

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

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

        // Detect faces from image url for recognition purposes. This is a helper method for other functions in this quickstart.
        // Parameter `returnFaceId` of `DetectAsync` must be set to `true` (by default) for recognition purposes.
        // Parameter `returnFaceAttributes` is set to include the QualityForRecognition attribute. 
        // Recognition model must be set to recognition_03 or recognition_04 as a result.
        // Result faces with insufficient quality for recognition are filtered out. 
        // The field `faceId` in returned `DetectedFace`s will be used in Verify and Identify.
        // It will expire 24 hours after the detection call.
        private static async Task<List<FaceDetectionResult>> DetectFaceRecognize(FaceClient faceClient, string url, FaceRecognitionModel recognition_model)
        {
            // Detect faces from image URL.
            Response<IReadOnlyList<FaceDetectionResult>> response = await faceClient.DetectAsync(new Uri(url), FaceDetectionModel.Detection03, recognition_model, returnFaceId: true, [FaceAttributeType.QualityForRecognition]);
            IReadOnlyList<FaceDetectionResult> detectedFaces = response.Value;
            List<FaceDetectionResult> sufficientQualityFaces = new List<FaceDetectionResult>();
            foreach (FaceDetectionResult detectedFace in detectedFaces)
            {
                var faceQualityForRecognition = detectedFace.FaceAttributes.QualityForRecognition;
                if (faceQualityForRecognition.HasValue && (faceQualityForRecognition.Value != QualityForRecognition.Low))
                {
                    sufficientQualityFaces.Add(detectedFace);
                }
            }
            Console.WriteLine($"{detectedFaces.Count} face(s) with {sufficientQualityFaces.Count} having sufficient quality for recognition detected from image `{Path.GetFileName(url)}`");

            return sufficientQualityFaces;
        }

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

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

            // Create a large person group.
            Console.WriteLine($"Create a person group ({largePersonGroupId}).");
            HttpClient httpClient = new HttpClient();
            httpClient.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", SUBSCRIPTION_KEY);
            using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["name"] = largePersonGroupId, ["recognitionModel"] = recognitionModel.ToString() }))))
            {
                content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                await httpClient.PutAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}", content);
            }
            // The similar faces will be grouped into a single large person group person.
            foreach (var groupedFace in personDictionary.Keys)
            {
                // Limit TPS
                await Task.Delay(250);
                string? personId = null;
                using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["name"] = groupedFace }))))
                {
                    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                    using (var response = await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}/persons", content))
                    {
                        string contentString = await response.Content.ReadAsStringAsync();
                        personId = (string?)(JsonConvert.DeserializeObject<Dictionary<string, object>>(contentString)?["personId"]);
                    }
                }
                Console.WriteLine($"Create a person group person '{groupedFace}'.");

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

                    if (!sufficientQuality)
                    {
                        continue;
                    }

                    if (detectedFaces1.Count != 1)
                    {
                        continue;
                    }

                    // add face to the large person group
                    Console.WriteLine($"Add face to the person group person({groupedFace}) from image `{similarImage}`");
                    using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["url"] = $"{url}{similarImage}" }))))
                    {
                        content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                        await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces?detectionModel=detection_03", content);
                    }
                }
            }

            // Start to train the large person group.
            Console.WriteLine();
            Console.WriteLine($"Train person group {largePersonGroupId}.");
            await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}/train", null);

            // Wait until the training is completed.
            while (true)
            {
                await Task.Delay(1000);
                string? trainingStatus = null;
                using (var response = await httpClient.GetAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}/training"))
                {
                    string contentString = await response.Content.ReadAsStringAsync();
                    trainingStatus = (string?)(JsonConvert.DeserializeObject<Dictionary<string, object>>(contentString)?["status"]);
                }
                Console.WriteLine($"Training status: {trainingStatus}.");
                if ("succeeded".Equals(trainingStatus)) { break; }
            }
            Console.WriteLine();

            Console.WriteLine("Pausing for 60 seconds to avoid triggering rate limit on free account...");
            await Task.Delay(60000);

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

            // Add detected faceId to sourceFaceIds.
            foreach (var detectedFace in detectedFaces) { sourceFaceIds.Add(detectedFace.FaceId.Value); }

            // Identify the faces in a large person group.
            List<Dictionary<string, object>> identifyResults = new List<Dictionary<string, object>>();
            using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["faceIds"] = sourceFaceIds, ["largePersonGroupId"] = largePersonGroupId }))))
            {
                content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                using (var response = await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/identify", content))
                {
                    string contentString = await response.Content.ReadAsStringAsync();
                    identifyResults = JsonConvert.DeserializeObject<List<Dictionary<string, object>>>(contentString) ?? [];
                }
            }

            foreach (var identifyResult in identifyResults)
            {
                string faceId = (string)identifyResult["faceId"];
                List<Dictionary<string, object>> candidates = JsonConvert.DeserializeObject<List<Dictionary<string, object>>>(((JArray)identifyResult["candidates"]).ToString()) ?? [];
                if (candidates.Count == 0)
                {
                    Console.WriteLine($"No person is identified for the face in: {sourceImageFileName} - {faceId},");
                    continue;
                }

                string? personName = null;
                using (var response = await httpClient.GetAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{candidates.First()["personId"]}"))
                {
                    string contentString = await response.Content.ReadAsStringAsync();
                    personName = (string?)(JsonConvert.DeserializeObject<Dictionary<string, object>>(contentString)?["name"]);
                }
                Console.WriteLine($"Person '{personName}' is identified for the face in: {sourceImageFileName} - {faceId}," +
                    $" confidence: {candidates.First()["confidence"]}.");

                Dictionary<string, object> verifyResult = new Dictionary<string, object>();
                using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["faceId"] = faceId, ["personId"] = candidates.First()["personId"], ["largePersonGroupId"] = largePersonGroupId }))))
                {
                    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                    using (var response = await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/verify", content))
                    {
                        string contentString = await response.Content.ReadAsStringAsync();
                        verifyResult = JsonConvert.DeserializeObject<Dictionary<string, object>>(contentString) ?? [];
                    }
                }
                Console.WriteLine($"Verification result: is a match? {verifyResult["isIdentical"]}. confidence: {verifyResult["confidence"]}");
            }
            Console.WriteLine();

            // Delete large person group.
            Console.WriteLine("========DELETE PERSON GROUP========");
            Console.WriteLine();
            await httpClient.DeleteAsync($"{ENDPOINT}/face/v1.0/largepersongroups/{largePersonGroupId}");
            Console.WriteLine($"Deleted the person group {largePersonGroupId}.");
            Console.WriteLine();
        }
    }
}

Ausführen der Anwendung
- Visual Studio-IDE
- BEFEHLSZEILENSCHNITTSTELLE (CLI)
Führen Sie die Anwendung aus, indem Sie oben im IDE-Fenster auf die Schaltfläche Debuggen klicken.
Führen Sie die Anwendung mit dem Befehl dotnet run aus dem Anwendungsverzeichnis aus.
```
dotnet run
```

Output

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

Create a person group (18d1c443-a01b-46a4-9191-121f74a831cd).
Create a person group person 'Family1-Dad'.
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Dad) from image `Family1-Dad1.jpg`
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Dad) from image `Family1-Dad2.jpg`
Create a person group person 'Family1-Mom'.
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Mom) from image `Family1-Mom1.jpg`
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Mom) from image `Family1-Mom2.jpg`
Create a person group person 'Family1-Son'.
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Son) from image `Family1-Son1.jpg`
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Son) from image `Family1-Son2.jpg`

Train person group 18d1c443-a01b-46a4-9191-121f74a831cd.
Training status: succeeded.

Pausing for 60 seconds to avoid triggering rate limit on free account...
4 face(s) with 4 having sufficient quality for recognition detected from image `identification1.jpg`
Person 'Family1-Dad' is identified for the face in: identification1.jpg - ad813534-9141-47b4-bfba-24919223966f, confidence: 0.96807.
Verification result: is a match? True. confidence: 0.96807
Person 'Family1-Mom' is identified for the face in: identification1.jpg - 1a39420e-f517-4cee-a898-5d968dac1a7e, confidence: 0.96902.
Verification result: is a match? True. confidence: 0.96902
No person is identified for the face in: identification1.jpg - 889394b1-e30f-4147-9be1-302beb5573f3,
Person 'Family1-Son' is identified for the face in: identification1.jpg - 0557d87b-356c-48a8-988f-ce0ad2239aa5, confidence: 0.9281.
Verification result: is a match? True. confidence: 0.9281

========DELETE PERSON GROUP========

Deleted the person group 18d1c443-a01b-46a4-9191-121f74a831cd.

End of quickstart.

Tipp

Die Gesichtserkennungs-API wird für verschiedene vordefinierte Modelle ausgeführt, die von Natur aus statisch sind. (Die Leistung der Modelle verschlechtert oder verbessert sich bei der Dienstausführung nicht.) Die vom Modell erzeugten Ergebnisse können sich ändern, wenn Microsoft das Back-End des Modells aktualisiert, ohne zu einer vollständig neuen Modellversion zu migrieren. Um von einer neueren Version eines Modells zu profitieren, können Sie Ihre Personengruppe (PersonGroup) erneut trainieren und dabei das neuere Modell als Parameter mit denselben Registrierungsimages angeben.

Bereinigen von Ressourcen

Wenn Sie ein Azure KI Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind.

Nächste Schritte

In dieser Schnellstartanleitung haben Sie gelernt, wie Sie die Gesichtserkennungs-Clientbibliothek für .NET für eine einfache Gesichtserkennung verwenden. Als Nächstes erfahren Sie mehr über die verschiedenen Gesichtserkennungsmodelle und zum Angeben des richtigen Modells für Ihren Anwendungsfall.

Angeben einer Gesichtserkennungsmodellversion

Was ist der Gesichtserkennungsdienst?
Ausführlicheren Beispielcode finden Sie auf GitHub.

Erste Schritte mit Gesichtserkennung unter Verwendung der Gesichtserkennungs-Clientbibliothek für Python. Führen Sie die nachfolgenden Schritte zum Installieren des Pakets aus, und testen Sie den Beispielcode für grundlegende Aufgaben. Über den Gesichtserkennungsdienst haben Sie Zugriff auf erweiterte Algorithmen für die Erkennung von menschlichen Gesichtern in Bildern. Führen Sie diese Schritte aus, um das Paket zu installieren und den Beispielcode für eine einfache Gesichtserkennung mithilfe von remote gespeicherten Bildern auszuprobieren.

Referenzdokumentation | Quellcode der Bibliothek | Paket (PiPy) | Beispiele

Voraussetzungen

Azure-Abonnement – Erstellen eines kostenlosen Kontos
Python 3.x
- Ihre Python-Installation sollte pip enthalten. Sie können überprüfen, ob pip installiert ist, indem Sie pip --version in der Befehlszeile ausführen. Installieren Sie die aktuelle Python-Version, um pip zu erhalten.
Wenn Sie über Ihr Azure-Abonnement verfügen, sollten Sie im Azure-Portal eine Gesichtserkennungsressource erstellen, um Ihren Schlüssel und Endpunkt abzurufen. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
- Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der Gesichtserkennungs-API zu verbinden.
- Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Erstellen von Umgebungsvariablen

In diesem Beispiel schreiben Sie Ihre Anmeldeinformationen in Umgebungsvariablen auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird.

Zum Festlegen der Umgebungsvariablen FACE_APIKEY ersetzen Sie <your_key> durch einen der Schlüssel für Ihre Ressource.
Zum Festlegen der Umgebungsvariablen FACE_ENDPOINT ersetzen Sie <your_endpoint> durch den Endpunkt für Ihre Ressource.

Wichtig

Weitere Informationen zur Sicherheit von KI Services finden Sie unter Authentifizieren von Anforderungen an Azure KI Services.

Windows
Linux

setx FACE_APIKEY <your_key>

setx FACE_ENDPOINT <your_endpoint>

export FACE_APIKEY=<your_key>

export FACE_ENDPOINT=<your_endpoint>

Führen Sie nach dem Hinzufügen der Umgebungsvariablen im Konsolenfenster source ~/.bashrc aus, damit die Änderungen wirksam werden.

Identifizieren und Überprüfen von Gesichtern

Installieren der Clientbibliothek

Nach der Installation von Python, können Sie die Clientbibliothek mit Folgendem installieren:
```
pip install --upgrade azure-ai-vision-face
```

Erstellen einer neuen Python-Anwendung

Erstellen Sie ein neues Python-Skript, etwa quickstart-file.py. Öffnen Sie die Datei in Ihrem bevorzugten Editor oder Ihrer bevorzugten IDE, und fügen Sie den folgenden Code ein.

Hinweis

Wenn Sie keinen Zugriff auf den Gesichtserkennungsdienst über das Aufnahmeformular erhalten haben, können Sie einige dieser Funktionen nicht nutzen.

import os
import time
import uuid
import requests

from azure.core.credentials import AzureKeyCredential
from azure.ai.vision.face import FaceClient
from azure.ai.vision.face.models import (
    FaceAttributeTypeRecognition04,
    FaceDetectionModel,
    FaceRecognitionModel,
    QualityForRecognition,
)


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

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

# Used in the Large Person Group Operations and Delete Large Person Group examples.
# LARGE_PERSON_GROUP_ID should be all lowercase and alphanumeric. For example, 'mygroupname' (dashes are OK).
LARGE_PERSON_GROUP_ID = str(uuid.uuid4())  # assign a random ID (or name it anything)

HEADERS = {"Ocp-Apim-Subscription-Key": KEY, "Content-Type": "application/json"}

# Create an authenticated FaceClient.
with FaceClient(endpoint=ENDPOINT, credential=AzureKeyCredential(KEY)) as face_client:
    '''
    Create the LargePersonGroup
    '''
    # Create empty Large Person Group. Large Person Group ID must be lower case, alphanumeric, and/or with '-', '_'.
    print("Person group:", LARGE_PERSON_GROUP_ID)
    response = requests.put(
        ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}",
        headers=HEADERS,
        json={"name": LARGE_PERSON_GROUP_ID, "recognitionModel": "recognition_04"})
    response.raise_for_status()

    # Define woman friend
    response = requests.post(ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/persons", headers=HEADERS, json={"name": "Woman"})
    response.raise_for_status()
    woman = response.json()
    # Define man friend
    response = requests.post(ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/persons", headers=HEADERS, json={"name": "Man"})
    response.raise_for_status()
    man = response.json()
    # Define child friend
    response = requests.post(ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/persons", headers=HEADERS, json={"name": "Child"})
    response.raise_for_status()
    child = response.json()

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

    # Add to woman person
    for image in woman_images:
        # Check if the image is of sufficent quality for recognition.
        sufficientQuality = True
        detected_faces = face_client.detect_from_url(
            url=image,
            detection_model=FaceDetectionModel.DETECTION_03,
            recognition_model=FaceRecognitionModel.RECOGNITION_04,
            return_face_id=True,
            return_face_attributes=[FaceAttributeTypeRecognition04.QUALITY_FOR_RECOGNITION])
        for face in detected_faces:
            if face.face_attributes.quality_for_recognition != QualityForRecognition.HIGH:
                sufficientQuality = False
                break

        if not sufficientQuality:
            continue

        if len(detected_faces) != 1:
            continue

        response = requests.post(
            ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/persons/{woman['personId']}/persistedFaces",
            headers=HEADERS,
            json={"url": image})
        response.raise_for_status()
        print(f"face {face.face_id} added to person {woman['personId']}")


    # Add to man person
    for image in man_images:
        # Check if the image is of sufficent quality for recognition.
        sufficientQuality = True
        detected_faces = face_client.detect_from_url(
            url=image,
            detection_model=FaceDetectionModel.DETECTION_03,
            recognition_model=FaceRecognitionModel.RECOGNITION_04,
            return_face_id=True,
            return_face_attributes=[FaceAttributeTypeRecognition04.QUALITY_FOR_RECOGNITION])
        for face in detected_faces:
            if face.face_attributes.quality_for_recognition != QualityForRecognition.HIGH:
                sufficientQuality = False
                break

        if not sufficientQuality:
            continue

        if len(detected_faces) != 1:
            continue

        response = requests.post(
            ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/persons/{man['personId']}/persistedFaces",
            headers=HEADERS,
            json={"url": image})
        response.raise_for_status()
        print(f"face {face.face_id} added to person {man['personId']}")

    # Add to child person
    for image in child_images:
        # Check if the image is of sufficent quality for recognition.
        sufficientQuality = True
        detected_faces = face_client.detect_from_url(
            url=image,
            detection_model=FaceDetectionModel.DETECTION_03,
            recognition_model=FaceRecognitionModel.RECOGNITION_04,
            return_face_id=True,
            return_face_attributes=[FaceAttributeTypeRecognition04.QUALITY_FOR_RECOGNITION])
        for face in detected_faces:
            if face.face_attributes.quality_for_recognition != QualityForRecognition.HIGH:
                sufficientQuality = False
                break
        if not sufficientQuality:
            continue

        if len(detected_faces) != 1:
            continue

        response = requests.post(
            ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/persons/{child['personId']}/persistedFaces",
            headers=HEADERS,
            json={"url": image})
        response.raise_for_status()
        print(f"face {face.face_id} added to person {child['personId']}")

    '''
    Train LargePersonGroup
    '''
    # Train the large person group
    print(f"Train the person group {LARGE_PERSON_GROUP_ID}")
    response = requests.post(ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/train", headers=HEADERS)
    response.raise_for_status()

    while (True):
        response = requests.get(ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}/training", headers=HEADERS)
        response.raise_for_status()
        training_status = response.json()["status"]
        if training_status == "succeeded":
            break
    print(f"The person group {LARGE_PERSON_GROUP_ID} is trained successfully.")

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

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

    # Detect faces
    face_ids = []
    # We use detection model 03 to get better performance, recognition model 04 to support quality for
    # recognition attribute.
    faces = face_client.detect_from_url(
        url=test_image,
        detection_model=FaceDetectionModel.DETECTION_03,
        recognition_model=FaceRecognitionModel.RECOGNITION_04,
        return_face_id=True,
        return_face_attributes=[FaceAttributeTypeRecognition04.QUALITY_FOR_RECOGNITION])
    for face in faces:
        # Only take the face if it is of sufficient quality.
        if face.face_attributes.quality_for_recognition != QualityForRecognition.LOW:
            face_ids.append(face.face_id)

    # Identify faces
    response = requests.post(
        ENDPOINT + f"/face/v1.0/identify",
        headers=HEADERS,
        json={"faceIds": face_ids, "largePersonGroupId": LARGE_PERSON_GROUP_ID})
    response.raise_for_status()
    results = response.json()
    print("Identifying faces in image")
    if not results:
        print("No person identified in the person group")
    for identifiedFace in results:
        if len(identifiedFace["candidates"]) > 0:
            print(f"Person is identified for face ID {identifiedFace['faceId']} in image, with a confidence of "
                  f"{identifiedFace['candidates'][0]['confidence']}.")  # Get topmost confidence score

            # Verify faces
            response = requests.post(
                ENDPOINT + f"/face/v1.0/verify",
                headers=HEADERS,
                json={"faceId": identifiedFace["faceId"], "personId": identifiedFace["candidates"][0]["personId"], "largePersonGroupId": LARGE_PERSON_GROUP_ID})
            response.raise_for_status()
            verify_result = response.json()
            print(f"verification result: {verify_result['isIdentical']}. confidence: {verify_result['confidence']}")
        else:
            print(f"No person identified for face ID {identifiedFace['faceId']} in image.")

    print()

    # Delete the large person group
    response = requests.delete(ENDPOINT + f"/face/v1.0/largepersongroups/{LARGE_PERSON_GROUP_ID}", headers=HEADERS)
    response.raise_for_status()
    print(f"The person group {LARGE_PERSON_GROUP_ID} is deleted.")

    print()
    print("End of quickstart.")

Führen Sie Ihre Anwendung zur Gesichtserkennung aus dem Anwendungsverzeichnis mit dem python-Befehl aus.
```
python quickstart-file.py
```
Tipp

Die Gesichtserkennungs-API wird für verschiedene vordefinierte Modelle ausgeführt, die von Natur aus statisch sind. (Die Leistung der Modelle verschlechtert oder verbessert sich bei der Dienstausführung nicht.) Die vom Modell erzeugten Ergebnisse können sich ändern, wenn Microsoft das Back-End des Modells aktualisiert, ohne zu einer vollständig neuen Modellversion zu migrieren. Um von einer neueren Version eines Modells zu profitieren, können Sie Ihre Personengruppe (PersonGroup) erneut trainieren und dabei das neuere Modell als Parameter mit denselben Registrierungsimages angeben.

Output

Person group: ad12b2db-d892-48ec-837a-0e7168c18224
face 335a2cb1-5211-4c29-9c45-776dd014b2af added to person 9ee65510-81a5-47e5-9e50-66727f719465
face df57eb50-4a13-4f93-b804-cd108327ad5a added to person 9ee65510-81a5-47e5-9e50-66727f719465
face d8b7b8b8-3ca6-4309-b76e-eeed84f7738a added to person 00651036-4236-4004-88b9-11466c251548
face dffbb141-f40b-4392-8785-b6c434fa534e added to person 00651036-4236-4004-88b9-11466c251548
face 9cdac36e-5455-447b-a68d-eb1f5e2ec27d added to person 23614724-b132-407a-aaa0-67003987ce93
face d8208412-92b7-4b8d-a2f8-3926c839c87e added to person 23614724-b132-407a-aaa0-67003987ce93
Train the person group ad12b2db-d892-48ec-837a-0e7168c18224
The person group ad12b2db-d892-48ec-837a-0e7168c18224 is trained successfully.
Pausing for 60 seconds to avoid triggering rate limit on free account...
Identifying faces in image
Person is identified for face ID bc52405a-5d83-4500-9218-557468ccdf99 in image, with a confidence of 0.96726.
verification result: True. confidence: 0.96726
Person is identified for face ID dfcc3fc8-6252-4f3a-8205-71466f39d1a7 in image, with a confidence of 0.96925.
verification result: True. confidence: 0.96925
No person identified for face ID 401c581b-a178-45ed-8205-7692f6eede88 in image.
Person is identified for face ID 8809d9c7-e362-4727-8c95-e1e44f5c2e8a in image, with a confidence of 0.92898.
verification result: True. confidence: 0.92898

The person group ad12b2db-d892-48ec-837a-0e7168c18224 is deleted.

End of quickstart.

Bereinigen von Ressourcen

Nächste Schritte

In dieser Schnellstartanleitung haben Sie gelernt, wie Sie die Gesichtserkennungs-Clientbibliothek für Python für eine einfache Gesichtserkennung verwenden. Als Nächstes erfahren Sie mehr über die verschiedenen Gesichtserkennungsmodelle und zum Angeben des richtigen Modells für Ihren Anwendungsfall.

Angeben einer Gesichtserkennungsmodellversion

Was ist der Gesichtserkennungsdienst?
Ausführlicheren Beispielcode finden Sie auf GitHub.

Erste Schritte mit Gesichtserkennung unter Verwendung der Gesichtserkennungs-Clientbibliothek für Java. Führen Sie die nachfolgenden Schritte zum Installieren des Pakets aus, und testen Sie den Beispielcode für grundlegende Aufgaben. Über den Gesichtserkennungsdienst haben Sie Zugriff auf erweiterte Algorithmen für die Erkennung von menschlichen Gesichtern in Bildern. Führen Sie diese Schritte aus, um das Paket zu installieren und den Beispielcode für eine einfache Gesichtserkennung mithilfe von remote gespeicherten Bildern auszuprobieren.

Referenzdokumentation | Quellcode der Bibliothek | Paket (Maven) | Beispiele

Voraussetzungen

Azure-Abonnement – Erstellen eines kostenlosen Kontos
Aktuelle Version des Java Development Kit (JDK)
Apache Maven muss installiert sein. Installieren Sie es unter Linux über die Verteilungsrepositorys, falls verfügbar.
Wenn Sie über Ihr Azure-Abonnement verfügen, sollten Sie im Azure-Portal eine Gesichtserkennungsressource erstellen, um Ihren Schlüssel und Endpunkt abzurufen. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
- Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der Gesichtserkennungs-API zu verbinden.
- Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Erstellen von Umgebungsvariablen

In diesem Beispiel schreiben Sie Ihre Anmeldeinformationen in Umgebungsvariablen auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird.

Zum Festlegen der Umgebungsvariablen FACE_APIKEY ersetzen Sie <your_key> durch einen der Schlüssel für Ihre Ressource.
Zum Festlegen der Umgebungsvariablen FACE_ENDPOINT ersetzen Sie <your_endpoint> durch den Endpunkt für Ihre Ressource.

Wichtig

Weitere Informationen zur Sicherheit von KI Services finden Sie unter Authentifizieren von Anforderungen an Azure KI Services.

Windows
Linux

setx FACE_APIKEY <your_key>

setx FACE_ENDPOINT <your_endpoint>

export FACE_APIKEY=<your_key>

export FACE_ENDPOINT=<your_endpoint>

Führen Sie nach dem Hinzufügen der Umgebungsvariablen im Konsolenfenster source ~/.bashrc aus, damit die Änderungen wirksam werden.

Identifizieren und Überprüfen von Gesichtern

Installieren der Clientbibliothek

Öffnen Sie ein Konsolenfenster, und erstellen Sie einen neuen Ordner für Ihre Schnellstartanwendung. Kopieren Sie den folgenden Inhalt in eine neue Datei. Speichern Sie die Datei als pom.xml in Ihrem Projektverzeichnis:

<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>my-application-name</artifactId>
  <version>1.0.0</version>
  <dependencies>
    <!-- https://mvnrepository.com/artifact/com.azure/azure-ai-vision-face -->
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-ai-vision-face</artifactId>
      <version>1.0.0-beta.1</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/org.apache.httpcomponents/httpclient -->
    <dependency>
      <groupId>org.apache.httpcomponents</groupId>
      <artifactId>httpclient</artifactId>
      <version>4.5.13</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
    <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.11.0</version>
    </dependency>
  </dependencies>
</project>

Installieren Sie das SDK und die Abhängigkeiten, indem Sie folgendes im Projektverzeichnis ausführen:

mvn clean dependency:copy-dependencies

Erstellen einer neuen Java-Anwendung

Erstellen Sie eine Datei namens Quickstart.java, öffnen Sie sie in einem Text-Editor, und fügen Sie den folgenden Code ein:

Hinweis

Wenn Sie keinen Zugriff auf den Gesichtserkennungsdienst über das Aufnahmeformular erhalten haben, können Sie einige dieser Funktionen nicht nutzen.

import java.util.Arrays;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
import java.util.UUID;

import com.azure.ai.vision.face.FaceClient;
import com.azure.ai.vision.face.FaceClientBuilder;
import com.azure.ai.vision.face.models.DetectOptions;
import com.azure.ai.vision.face.models.FaceAttributeType;
import com.azure.ai.vision.face.models.FaceDetectionModel;
import com.azure.ai.vision.face.models.FaceDetectionResult;
import com.azure.ai.vision.face.models.FaceRecognitionModel;
import com.azure.ai.vision.face.models.QualityForRecognition;
import com.azure.core.credential.KeyCredential;
import com.google.gson.Gson;
import com.google.gson.reflect.TypeToken;

import org.apache.http.HttpHeaders;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpDelete;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicHeader;
import org.apache.http.util.EntityUtils;

public class Quickstart {
    // LARGE_PERSON_GROUP_ID should be all lowercase and alphanumeric. For example, 'mygroupname' (dashes are OK).
    private static final String LARGE_PERSON_GROUP_ID = UUID.randomUUID().toString();

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

    // From your Face subscription in the Azure portal, get your subscription key and endpoint.
    private static final String SUBSCRIPTION_KEY = System.getenv("FACE_APIKEY");
    private static final String ENDPOINT = System.getenv("FACE_ENDPOINT");

    public static void main(String[] args) throws Exception {
        // Recognition model 4 was released in 2021 February.
        // It is recommended since its accuracy is improved
        // on faces wearing masks compared with model 3,
        // and its overall accuracy is improved compared
        // with models 1 and 2.
        FaceRecognitionModel RECOGNITION_MODEL4 = FaceRecognitionModel.RECOGNITION_04;

        // Authenticate.
        FaceClient client = authenticate(ENDPOINT, SUBSCRIPTION_KEY);

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

        System.out.println("End of quickstart.");
    }

    /*
     *	AUTHENTICATE
     *	Uses subscription key and region to create a client.
     */
    public static FaceClient authenticate(String endpoint, String key) {
        return new FaceClientBuilder().endpoint(endpoint).credential(new KeyCredential(key)).buildClient();
    }


    // Detect faces from image url for recognition purposes. This is a helper method for other functions in this quickstart.
    // Parameter `returnFaceId` of `DetectOptions` must be set to `true` (by default) for recognition purposes.
    // Parameter `returnFaceAttributes` is set to include the QualityForRecognition attribute. 
    // Recognition model must be set to recognition_03 or recognition_04 as a result.
    // Result faces with insufficient quality for recognition are filtered out. 
    // The field `faceId` in returned `DetectedFace`s will be used in Verify and Identify.
    // It will expire 24 hours after the detection call.
    private static List<FaceDetectionResult> detectFaceRecognize(FaceClient faceClient, String url, FaceRecognitionModel recognitionModel) {
        // Detect faces from image URL.
        DetectOptions options = new DetectOptions(FaceDetectionModel.DETECTION_03, recognitionModel, true).setReturnFaceAttributes(Arrays.asList(FaceAttributeType.QUALITY_FOR_RECOGNITION));
        List<FaceDetectionResult> detectedFaces = faceClient.detect(url, options);
        List<FaceDetectionResult> sufficientQualityFaces = detectedFaces.stream().filter(f -> f.getFaceAttributes().getQualityForRecognition() != QualityForRecognition.LOW).collect(Collectors.toList());
        System.out.println(detectedFaces.size() + " face(s) with " + sufficientQualityFaces.size() + " having sufficient quality for recognition.");

        return sufficientQualityFaces;
    }

    /*
     * IDENTIFY FACES
     * To identify faces, you need to create and define a large person group.
     * The Identify operation takes one or several face IDs from DetectedFace or PersistedFace and a LargePersonGroup and returns
     * a list of Person objects that each face might belong to. Returned Person objects are wrapped as Candidate objects,
     * which have a prediction confidence value.
     */
    public static void identifyInLargePersonGroup(FaceClient client, String url, FaceRecognitionModel recognitionModel) throws Exception {
        System.out.println("========IDENTIFY FACES========");
        System.out.println();

        // Create a dictionary for all your images, grouping similar ones under the same key.
        Map<String, String[]> personDictionary = new LinkedHashMap<String, String[]>();
        personDictionary.put("Family1-Dad", new String[]{"Family1-Dad1.jpg", "Family1-Dad2.jpg"});
        personDictionary.put("Family1-Mom", new String[]{"Family1-Mom1.jpg", "Family1-Mom2.jpg"});
        personDictionary.put("Family1-Son", new String[]{"Family1-Son1.jpg", "Family1-Son2.jpg"});
        // A group photo that includes some of the persons you seek to identify from your dictionary.
        String sourceImageFileName = "identification1.jpg";

        // Create a large person group.
        System.out.println("Create a person group (" + LARGE_PERSON_GROUP_ID + ").");
        List<BasicHeader> headers = Arrays.asList(new BasicHeader("Ocp-Apim-Subscription-Key", SUBSCRIPTION_KEY), new BasicHeader(HttpHeaders.CONTENT_TYPE, "application/json"));
        HttpClient httpClient = HttpClients.custom().setDefaultHeaders(headers).build();
        createLargePersonGroup(httpClient, recognitionModel);
        // The similar faces will be grouped into a single large person group person.
        for (String groupedFace : personDictionary.keySet()) {
            // Limit TPS
            Thread.sleep(250);
            String personId = createLargePersonGroupPerson(httpClient, groupedFace);
            System.out.println("Create a person group person '" + groupedFace + "'.");

            // Add face to the large person group person.
            for (String similarImage : personDictionary.get(groupedFace)) {
                System.out.println("Check whether image is of sufficient quality for recognition");
                DetectOptions options = new DetectOptions(FaceDetectionModel.DETECTION_03, recognitionModel, false).setReturnFaceAttributes(Arrays.asList(FaceAttributeType.QUALITY_FOR_RECOGNITION));
                List<FaceDetectionResult> detectedFaces1 = client.detect(url + similarImage, options);
                if (detectedFaces1.stream().anyMatch(f -> f.getFaceAttributes().getQualityForRecognition() != QualityForRecognition.HIGH)) {
                    continue;
                }

                if (detectedFaces1.size() != 1) {
                    continue;
                }

                // add face to the large person group
                System.out.println("Add face to the person group person(" + groupedFace + ") from image `" + similarImage + "`");
                addFaceToLargePersonGroup(httpClient, personId, url + similarImage);
            }
        }

        // Start to train the large person group.
        System.out.println();
        System.out.println("Train person group " + LARGE_PERSON_GROUP_ID + ".");
        trainLargePersonGroup(httpClient);

        // Wait until the training is completed.
        while (true) {
            Thread.sleep(1000);
            String trainingStatus = getLargePersonGroupTrainingStatus(httpClient);
            System.out.println("Training status: " + trainingStatus + ".");
            if ("succeeded".equals(trainingStatus)) {
                break;
            }
        }
        System.out.println();

        System.out.println("Pausing for 60 seconds to avoid triggering rate limit on free account...");
        Thread.sleep(60000);

        // Detect faces from source image url.
        List<FaceDetectionResult> detectedFaces = detectFaceRecognize(client, url + sourceImageFileName, recognitionModel);
        // Add detected faceId to sourceFaceIds.
        List<String> sourceFaceIds = detectedFaces.stream().map(FaceDetectionResult::getFaceId).collect(Collectors.toList());

        // Identify the faces in a large person group.
        List<Map<String, Object>> identifyResults = identifyFacesInLargePersonGroup(httpClient, sourceFaceIds);

        for (Map<String, Object> identifyResult : identifyResults) {
            String faceId = identifyResult.get("faceId").toString();
            List<Map<String, Object>> candidates = new Gson().fromJson(new Gson().toJson(identifyResult.get("candidates")), new TypeToken<List<Map<String, Object>>>(){});
            if (candidates.isEmpty()) {
                System.out.println("No person is identified for the face in: " + sourceImageFileName + " - " + faceId + ".");
                continue;
            }

            Map<String, Object> candidate = candidates.stream().findFirst().orElseThrow();
            String personName = getLargePersonGroupPersonName(httpClient, candidate.get("personId").toString());
            System.out.println("Person '" + personName + "' is identified for the face in: " + sourceImageFileName + " - " + faceId + ", confidence: " + candidate.get("confidence") + ".");

            Map<String, Object> verifyResult = verifyFaceWithLargePersonGroupPerson(httpClient, faceId, candidate.get("personId").toString());
            System.out.println("Verification result: is a match? " + verifyResult.get("isIdentical") + ". confidence: " + verifyResult.get("confidence"));
        }
        System.out.println();

        // Delete large person group.
        System.out.println("========DELETE PERSON GROUP========");
        System.out.println();
        deleteLargePersonGroup(httpClient);
        System.out.println("Deleted the person group " + LARGE_PERSON_GROUP_ID + ".");
        System.out.println();
    }

    private static void createLargePersonGroup(HttpClient httpClient, FaceRecognitionModel recognitionModel) throws Exception {
        HttpPut request = new HttpPut(new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID).build());
        request.setEntity(new StringEntity(new Gson().toJson(Map.of("name", LARGE_PERSON_GROUP_ID, "recognitionModel", recognitionModel.toString()))));
        httpClient.execute(request);
        request.releaseConnection();
    }

    private static String createLargePersonGroupPerson(HttpClient httpClient, String name) throws Exception {
        HttpPost request = new HttpPost(new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID + "/persons").build());
        request.setEntity(new StringEntity(new Gson().toJson(Map.of("name", name))));
        String response = EntityUtils.toString(httpClient.execute(request).getEntity());
        request.releaseConnection();
        return new Gson().fromJson(response, new TypeToken<Map<String, Object>>(){}).get("personId").toString();
    }

    private static void addFaceToLargePersonGroup(HttpClient httpClient, String personId, String url) throws Exception {
        URIBuilder builder = new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID + "/persons/" + personId + "/persistedfaces");
        builder.setParameter("detectionModel", "detection_03");
        HttpPost request = new HttpPost(builder.build());
        request.setEntity(new StringEntity(new Gson().toJson(Map.of("url", url))));
        httpClient.execute(request);
        request.releaseConnection();
    }

    private static void trainLargePersonGroup(HttpClient httpClient) throws Exception {
        HttpPost request = new HttpPost(new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID + "/train").build());
        httpClient.execute(request);
        request.releaseConnection();
    }

    private static String getLargePersonGroupTrainingStatus(HttpClient httpClient) throws Exception {
        HttpGet request = new HttpGet(new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID + "/training").build());
        String response = EntityUtils.toString(httpClient.execute(request).getEntity());
        request.releaseConnection();
        return new Gson().fromJson(response, new TypeToken<Map<String, Object>>(){}).get("status").toString();
    }

    private static List<Map<String, Object>> identifyFacesInLargePersonGroup(HttpClient httpClient, List<String> sourceFaceIds) throws Exception {
        HttpPost request = new HttpPost(new URIBuilder(ENDPOINT + "/face/v1.0/identify").build());
        request.setEntity(new StringEntity(new Gson().toJson(Map.of("faceIds", sourceFaceIds, "largePersonGroupId", LARGE_PERSON_GROUP_ID))));
        String response = EntityUtils.toString(httpClient.execute(request).getEntity());
        request.releaseConnection();
        return new Gson().fromJson(response, new TypeToken<List<Map<String, Object>>>(){});
    }

    private static String getLargePersonGroupPersonName(HttpClient httpClient, String personId) throws Exception {
        HttpGet request = new HttpGet(new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID + "/persons/" + personId).build());
        String response = EntityUtils.toString(httpClient.execute(request).getEntity());
        request.releaseConnection();
        return new Gson().fromJson(response, new TypeToken<Map<String, Object>>(){}).get("name").toString();
    }

    private static Map<String, Object> verifyFaceWithLargePersonGroupPerson(HttpClient httpClient, String faceId, String personId) throws Exception {
        HttpPost request = new HttpPost(new URIBuilder(ENDPOINT + "/face/v1.0/verify").build());
        request.setEntity(new StringEntity(new Gson().toJson(Map.of("faceId", faceId, "personId", personId, "largePersonGroupId", LARGE_PERSON_GROUP_ID))));
        String response = EntityUtils.toString(httpClient.execute(request).getEntity());
        request.releaseConnection();
        return new Gson().fromJson(response, new TypeToken<Map<String, Object>>(){});
    }

    private static void deleteLargePersonGroup(HttpClient httpClient) throws Exception {
        HttpDelete request = new HttpDelete(new URIBuilder(ENDPOINT + "/face/v1.0/largepersongroups/" + LARGE_PERSON_GROUP_ID).build());
        httpClient.execute(request);
        request.releaseConnection();
    }
}

Führen Sie Ihre Anwendung zur Gesichtserkennung aus dem Anwendungsverzeichnis mit den Befehlen javac und java aus.

Windows
Linux

javac -cp target\dependency\* Quickstart.java
java -cp .;target\dependency\* Quickstart

javac -cp target/dependency/* Quickstart.java
java -cp .:target/dependency/* Quickstart

Output

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

Create a person group (3761e61a-16b2-4503-ad29-ed34c58ba676).
Create a person group person 'Family1-Dad'.
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Dad) from image `Family1-Dad1.jpg`
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Dad) from image `Family1-Dad2.jpg`
Create a person group person 'Family1-Mom'.
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Mom) from image `Family1-Mom1.jpg`
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Mom) from image `Family1-Mom2.jpg`
Create a person group person 'Family1-Son'.
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Son) from image `Family1-Son1.jpg`
Check whether image is of sufficient quality for recognition
Add face to the person group person(Family1-Son) from image `Family1-Son2.jpg`

Train person group 3761e61a-16b2-4503-ad29-ed34c58ba676.
Training status: succeeded.

Pausing for 60 seconds to avoid triggering rate limit on free account...
4 face(s) with 4 having sufficient quality for recognition.
Person 'Family1-Dad' is identified for the face in: identification1.jpg - d7995b34-1b72-47fe-82b6-e9877ed2578d, confidence: 0.96807.
Verification result: is a match? true. confidence: 0.96807
Person 'Family1-Mom' is identified for the face in: identification1.jpg - 844da0ed-4890-4bbf-a531-e638797f96fc, confidence: 0.96902.
Verification result: is a match? true. confidence: 0.96902
No person is identified for the face in: identification1.jpg - c543159a-57f3-4872-83ce-2d4a733d71c9.
Person 'Family1-Son' is identified for the face in: identification1.jpg - 414fac6c-7381-4dba-9c8b-fd26d52e879b, confidence: 0.9281.
Verification result: is a match? true. confidence: 0.9281

========DELETE PERSON GROUP========

Deleted the person group 3761e61a-16b2-4503-ad29-ed34c58ba676.

End of quickstart.

Bereinigen von Ressourcen

Nächste Schritte

In diesem Schnellstart haben Sie gelernt, wie Sie die Gesichtserkennungs-Clientbibliothek für Java für eine einfache Gesichtserkennung verwenden. Als Nächstes erfahren Sie mehr über die verschiedenen Gesichtserkennungsmodelle und zum Angeben des richtigen Modells für Ihren Anwendungsfall.

Angeben einer Gesichtserkennungsmodellversion

Was ist der Gesichtserkennungsdienst?
Ausführlicheren Beispielcode finden Sie auf GitHub.

Hier erfahren Sie mehr zu den ersten Schritten mit Gesichtserkennung unter Verwendung der Gesichtserkennungs-Clientbibliothek für JavaScript. Führen Sie die nachfolgenden Schritte zum Installieren des Pakets aus, und testen Sie den Beispielcode für grundlegende Aufgaben. Über den Gesichtserkennungsdienst haben Sie Zugriff auf erweiterte Algorithmen für die Erkennung von menschlichen Gesichtern in Bildern. Führen Sie diese Schritte aus, um das Paket zu installieren und den Beispielcode für eine einfache Gesichtserkennung mithilfe von remote gespeicherten Bildern auszuprobieren.

Referenzdokumentation | Quellcode der Bibliothek | Paket (npm) | Beispiele

Voraussetzungen

Azure-Abonnement – Erstellen eines kostenlosen Kontos
Die aktuelle Version von Node.js
Sobald Sie über Ihr Azure-Abonnement verfügen, sollten Sie im Azure-Portal eine Gesichtserkennungsressource erstellen, um Ihren Schlüssel und Endpunkt zu erhalten. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
- Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der Gesichtserkennungs-API zu verbinden.
- Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Erstellen von Umgebungsvariablen

In diesem Beispiel schreiben Sie Ihre Anmeldeinformationen in Umgebungsvariablen auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird.

Zum Festlegen der Umgebungsvariablen FACE_APIKEY ersetzen Sie <your_key> durch einen der Schlüssel für Ihre Ressource.
Zum Festlegen der Umgebungsvariablen FACE_ENDPOINT ersetzen Sie <your_endpoint> durch den Endpunkt für Ihre Ressource.

Wichtig

Weitere Informationen zur Sicherheit von KI Services finden Sie unter Authentifizieren von Anforderungen an Azure KI Services.

Windows
Linux

setx FACE_APIKEY <your_key>

setx FACE_ENDPOINT <your_endpoint>

export FACE_APIKEY=<your_key>

export FACE_ENDPOINT=<your_endpoint>

Führen Sie nach dem Hinzufügen der Umgebungsvariablen im Konsolenfenster source ~/.bashrc aus, damit die Änderungen wirksam werden.

Identifizieren und Überprüfen von Gesichtern

Erstellen einer neuen Node.js-Anwendung

Erstellen Sie in einem Konsolenfenster (etwa cmd, PowerShell oder Bash) ein neues Verzeichnis für Ihre App, und rufen Sie es auf.
```
mkdir myapp && cd myapp
```
Führen Sie den Befehl npm init aus, um eine Knotenanwendung mit der Datei package.json zu erstellen.
```
npm init
```
Installieren Sie die @azure-rest/ai-vision-face-NPM-Pakete:
```
npm install @azure-rest/ai-vision-face
```
Die Datei package.json Ihrer App wird mit den Abhängigkeiten aktualisiert.

Erstellen Sie eine Datei namens index.js, öffnen Sie sie in einem Text-Editor, und fügen Sie den folgenden Code ein:

Hinweis

Wenn Sie keinen Zugriff auf den Gesichtserkennungsdienst über das Aufnahmeformular erhalten haben, können Sie einige dieser Funktionen nicht nutzen.

const { randomUUID } = require("crypto");

const { AzureKeyCredential } = require("@azure/core-auth");

const createFaceClient = require("@azure-rest/ai-vision-face").default,
  { getLongRunningPoller } = require("@azure-rest/ai-vision-face");

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const main = async () => {
  const endpoint = process.env["FACE_ENDPOINT"] ?? "<endpoint>";
  const apikey = process.env["FACE_APIKEY"] ?? "<apikey>";
  const credential = new AzureKeyCredential(apikey);
  const client = createFaceClient(endpoint, credential);

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

  console.log("========IDENTIFY FACES========");
  console.log();

  // Create a dictionary for all your images, grouping similar ones under the same key.
  const personDictionary = {
    "Family1-Dad": ["Family1-Dad1.jpg", "Family1-Dad2.jpg"],
    "Family1-Mom": ["Family1-Mom1.jpg", "Family1-Mom2.jpg"],
    "Family1-Son": ["Family1-Son1.jpg", "Family1-Son2.jpg"],
  };

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

  // Create a large person group.
  console.log(`Creating a person group with ID: ${largePersonGroupId}`);
  await client.path("/largepersongroups/{largePersonGroupId}", largePersonGroupId).put({
    body: {
      name: largePersonGroupId,
      recognitionModel: "recognition_04",
    },
  });

  // The similar faces will be grouped into a single large person group person.
  console.log("Adding faces to person group...");
  await Promise.all(
    Object.keys(personDictionary).map(async (name) => {
      console.log(`Create a persongroup person: ${name}`);
      const createLargePersonGroupPersonResponse = await client
        .path("/largepersongroups/{largePersonGroupId}/persons", largePersonGroupId)
        .post({
          body: { name },
        });

      const { personId } = createLargePersonGroupPersonResponse.body;

      await Promise.all(
        personDictionary[name].map(async (similarImage) => {
          // Check if the image is of sufficent quality for recognition.
          const detectResponse = await client.path("/detect").post({
            contentType: "application/json",
            queryParameters: {
              detectionModel: "detection_03",
              recognitionModel: "recognition_04",
              returnFaceId: false,
              returnFaceAttributes: ["qualityForRecognition"],
            },
            body: { url: `${imageBaseUrl}${similarImage}` },
          });

          const sufficientQuality = detectResponse.body.every(
            (face) => face.faceAttributes?.qualityForRecognition === "high",
          );
          if (!sufficientQuality) {
            return;
          }

          if (detectResponse.body.length != 1) {
            return;
          }

          // Quality is sufficent, add to group.
          console.log(
            `Add face to the person group person: (${name}) from image: (${similarImage})`,
          );
          await client
            .path(
              "/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces",
              largePersonGroupId,
              personId,
            )
            .post({
              queryParameters: { detectionModel: "detection_03" },
              body: { url: `${imageBaseUrl}${similarImage}` },
            });
        }),
      );
    }),
  );
  console.log("Done adding faces to person group.");

  // Start to train the large person group.
  console.log();
  console.log(`Training person group: ${largePersonGroupId}`);
  const trainResponse = await client
    .path("/largepersongroups/{largePersonGroupId}/train", largePersonGroupId)
    .post();
  const poller = await getLongRunningPoller(client, trainResponse);
  await poller.pollUntilDone();
  console.log(`Training status: ${poller.getOperationState().status}`);
  if (poller.getOperationState().status !== "succeeded") {
    return;
  }

  console.log("Pausing for 60 seconds to avoid triggering rate limit on free account...");
  await sleep(60000);

  // Detect faces from source image url and only take those with sufficient quality for recognition.
  const detectResponse = await client.path("/detect").post({
    contentType: "application/json",
    queryParameters: {
      detectionModel: "detection_03",
      recognitionModel: "recognition_04",
      returnFaceId: true,
      returnFaceAttributes: ["qualityForRecognition"],
    },
    body: { url: `${imageBaseUrl}${sourceImageFileName}` },
  });
  const faceIds = detectResponse.body.filter((face) => face.faceAttributes?.qualityForRecognition !== "low").map((face) => face.faceId);

  // Identify the faces in a large person group.
  const identifyResponse = await client.path("/identify").post({
    body: { faceIds, largePersonGroupId: largePersonGroupId },
  });
  await Promise.all(
    identifyResponse.body.map(async (result) => {
      try {
        const getLargePersonGroupPersonResponse = await client
          .path(
            "/largepersongroups/{largePersonGroupId}/persons/{personId}",
            largePersonGroupId,
            result.candidates[0].personId,
          )
          .get();
        const person = getLargePersonGroupPersonResponse.body;
        console.log(
          `Person: ${person.name} is identified for face in: ${sourceImageFileName} with ID: ${result.faceId}. Confidence: ${result.candidates[0].confidence}`,
        );

        // Verification:
        const verifyResponse = await client.path("/verify").post({
          body: {
            faceId: result.faceId,
            largePersonGroupId: largePersonGroupId,
            personId: person.personId,
          },
        });
        console.log(
          `Verification result between face ${result.faceId} and person ${person.personId}: ${verifyResponse.body.isIdentical} with confidence: ${verifyResponse.body.confidence}`,
        );
      } catch (error) {
        console.log(`No persons identified for face with ID ${result.faceId}`);
      }
    }),
  );
  console.log();

  // Delete large person group.
  console.log(`Deleting person group: ${largePersonGroupId}`);
  await client.path("/largepersongroups/{largePersonGroupId}", largePersonGroupId).delete();
  console.log();

  console.log("Done.");
};

main().catch(console.error);

Führen Sie die Anwendung mit dem Befehl node für die Schnellstartdatei aus.
```
node index.js
```

Output

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

Creating a person group with ID: a230ac8b-09b2-4fa0-ae04-d76356d88d9f
Adding faces to person group...
Create a persongroup person: Family1-Dad
Create a persongroup person: Family1-Mom
Create a persongroup person: Family1-Son
Add face to the person group person: (Family1-Dad) from image: (Family1-Dad1.jpg)
Add face to the person group person: (Family1-Mom) from image: (Family1-Mom1.jpg)
Add face to the person group person: (Family1-Son) from image: (Family1-Son1.jpg)
Add face to the person group person: (Family1-Dad) from image: (Family1-Dad2.jpg)
Add face to the person group person: (Family1-Mom) from image: (Family1-Mom2.jpg)
Add face to the person group person: (Family1-Son) from image: (Family1-Son2.jpg)
Done adding faces to person group.

Training person group: a230ac8b-09b2-4fa0-ae04-d76356d88d9f
Training status: succeeded
Pausing for 60 seconds to avoid triggering rate limit on free account...
No persons identified for face with ID 56380623-8bf0-414a-b9d9-c2373386b7be
Person: Family1-Dad is identified for face in: identification1.jpg with ID: c45052eb-a910-4fd3-b1c3-f91ccccc316a. Confidence: 0.96807
Person: Family1-Son is identified for face in: identification1.jpg with ID: 8dce9b50-513f-4fe2-9e19-352acfd622b3. Confidence: 0.9281
Person: Family1-Mom is identified for face in: identification1.jpg with ID: 75868da3-66f6-4b5f-a172-0b619f4d74c1. Confidence: 0.96902
Verification result between face c45052eb-a910-4fd3-b1c3-f91ccccc316a and person 35a58d14-fd58-4146-9669-82ed664da357: true with confidence: 0.96807
Verification result between face 8dce9b50-513f-4fe2-9e19-352acfd622b3 and person 2d4d196c-5349-431c-bf0c-f1d7aaa180ba: true with confidence: 0.9281
Verification result between face 75868da3-66f6-4b5f-a172-0b619f4d74c1 and person 35d5de9e-5f92-4552-8907-0d0aac889c3e: true with confidence: 0.96902

Deleting person group: a230ac8b-09b2-4fa0-ae04-d76356d88d9f

Done.

Bereinigen von Ressourcen

Nächste Schritte

In dieser Schnellstartanleitung haben Sie gelernt, wie Sie die Gesichtserkennungs-Clientbibliothek für JavaScript für eine einfache Gesichtserkennung verwenden. Als Nächstes erfahren Sie mehr über die verschiedenen Gesichtserkennungsmodelle und zum Angeben des richtigen Modells für Ihren Anwendungsfall.

Angeben einer Gesichtserkennungsmodellversion

Was ist der Gesichtserkennungsdienst?
Ausführlicheren Beispielcode finden Sie auf GitHub.

Erste Schritte mit der Gesichtserkennung unter Verwendung der Gesichtserkennungs-REST-API. Über den Gesichtserkennungsdienst haben Sie Zugriff auf erweiterte Algorithmen für die Erkennung von menschlichen Gesichtern in Bildern.

Hinweis

In dieser Schnellstartanleitung wird die REST-API mithilfe von cURL-Befehlen aufgerufen. Die REST-API kann aber auch mit einer Programmiersprache aufgerufen werden. Komplexe Szenarien wie die Gesichtserkennung lassen sich leichter mit einem Sprach-SDK implementieren. Auf GitHub stehen Beispiele für C#, Python, Java, JavaScript und Go zur Verfügung.

Voraussetzungen

Azure-Abonnement – Erstellen eines kostenlosen Kontos
Wenn Sie über Ihr Azure-Abonnement verfügen, sollten Sie im Azure-Portal eine Gesichtserkennungsressource erstellen, um Ihren Schlüssel und Endpunkt abzurufen. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
- Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der Gesichtserkennungs-API zu verbinden. Der Schlüssel und der Endpunkt werden weiter unten in der Schnellstartanleitung in den Code eingefügt.
- Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.
PowerShell-Version 6.0 oder höher oder eine ähnliche Befehlszeilenanwendung
cURL muss installiert sein.

Identifizieren und Überprüfen von Gesichtern

Hinweis

Wenn Sie keinen Zugriff auf den Gesichtserkennungsdienst über das Aufnahmeformular erhalten haben, können Sie einige dieser Funktionen nicht nutzen.

Rufen Sie zuerst die Erkennungs-API für das Quellbild des Gesichts auf. Dies ist das Gesicht, das in der größeren Gruppe identifiziert werden soll. Kopieren Sie den folgenden Befehl in einen Texteditor, und fügen Sie Ihren eigenen Schlüssel und Endpunkt ein. Kopieren Sie den Befehl dann in ein Shellfenster, und führen Sie ihn aus.

Windows
Linux

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

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

Speichern Sie die zurückgegebene Zeichenfolge für die Gesichts-ID an einem temporären Speicherort. Sie werden sie am Schluss erneut verwenden.

Als Nächstes müssen Sie eine LargePersonGroup erstellen und ihr eine beliebige ID zuweisen, die dem Muster ^[a-z0-9-_]+$ eines regulären Ausdrucks entspricht. Dieses Objekt speichert die aggregierten Gesichtsdaten mehrerer Personen. Führen Sie den folgenden Befehl aus, und fügen Sie dabei Ihren eigenen Schlüssel ein. Optional können Sie den Namen und die Metadaten der Gruppe im Anforderungstext ändern.

Windows
Linux

curl.exe -v -X PUT "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{
    ""name"": ""large-person-group-name"",
    ""userData"": ""User-provided data attached to the large person group."",
    ""recognitionModel"": ""recognition_04""
}"

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

Speichern Sie die angegebene ID der erstellten Gruppe an einem temporären Speicherort.

Als Nächstes erstellen Sie Person-Objekte, die zur Gruppe gehören. Führen Sie den folgenden Befehl aus, und fügen Sie dabei Ihren eigenen Schlüssel und die ID der LargePersonGroup aus dem vorherigen Schritt ein. Dieser Befehl erstellt eine Person namens „Family1-Dad“.

Windows
Linux

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

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

Führen Sie diesen Befehl erneut mit anderen Eingabedaten aus, um weitere Person-Objekte zu erstellen: „Family1-Mom“, „Family1-Son“, „Family1-Daughter“, „Family2-Lady“ und „Family2-Man“.

Speichern Sie die IDs jeder erstellten Person. Sie müssen nachverfolgen können, welche ID welcher Person zugewiesen wurde.

Als Nächstes müssen Sie Erkennungen für neue Gesichter ausführen und diese Gesichter den vorhandenen Person-Objekte zuordnen. Der folgende Befehl erkennt ein Gesicht aus dem Bild Family1-Dad1.jpg und fügt es der entsprechenden Person hinzu. Sie müssen die personId als die ID angeben, die beim Erstellen des Person-Objekts „Family1-Dad“ zurückgegeben wurde. Der Bildname entspricht dem Namen der erstellten Person. Geben Sie auch die LargePersonGroup-ID und Ihren Schlüssel in die entsprechenden Felder ein.
- Windows
- Linux
```
curl.exe -v -X POST "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces?detectionModel=detection_03" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{""url"":""https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Dad1.jpg""}"
```
```
curl -v -X POST "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces?detectionModel=detection_03" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{\"url\":\"https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/Family1-Dad1.jpg\"}"
```
Führen Sie dann den obigen Befehl erneut mit einem anderen Quellbild und einer anderen Person als Ziel aus. Folgende Bilder sind verfügbar: 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 und Family2-Man2.jpg. Achten Sie darauf, dass die Person, deren ID Sie im API-Aufruf angeben, mit dem Namen der Bilddatei im Anforderungstext übereinstimmt.

Am Ende dieses Schritts sollten Sie über mehrere Person-Objekte verfügen, die jeweils über mindestens ein entsprechendes Gesicht verfügen, das direkt aus den bereitgestellten Bildern erkannt wurde.
Als Nächstes trainieren Sie die LargePersonGroup mit den aktuellen Gesichtsdaten. Beim Trainingsvorgang lernt das Modell, wie Gesichtsmerkmale – die in manchen Fällen aus mehreren Quellbildern aggregiert sind – den einzelnen Personen zuzuordnen sind. Fügen Sie die LargePersonGroup-ID und Ihren Schlüssel ein, bevor Sie den Befehl ausführen.
- Windows
- Linux
```
curl.exe -v -X POST "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/train" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data ""
```
```
curl -v -X POST "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/train" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data ""
```

Überprüfen Sie, ob der Trainingsstatus „erfolgreich“ ist. Wenn nicht, warten Sie eine Weile, und führen Sie die Abfrage erneut durch.

Windows
Linux

curl.exe -v "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/training" -H "Ocp-Apim-Subscription-Key: {subscription key}"

curl -v "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/training" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Rufen Sie jetzt die Identifizierungs-API auf, und verwenden Sie dabei die ID des Quellbilds für das Gesicht aus dem ersten Schritt und die LargePersonGroup-ID. Fügen Sie diese Werte in die entsprechenden Felder im Anforderungstext ein, und fügen Sie Ihren Schlüssel ein.

Windows
Linux

curl.exe -v -X POST "https://{resource endpoint}/face/v1.0/identify" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {subscription key}" --data-ascii "{
    ""largePersonGroupId"": ""INSERT_PERSONGROUP_ID"",
    ""faceIds"": [
        ""INSERT_SOURCE_FACE_ID""
    ],
    ""maxNumOfCandidatesReturned"": 1,
    ""confidenceThreshold"": 0.5
}"

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

Die Antwort sollte eine Person-ID zurückgeben, die die Person angibt, die mit dem Quellbild des Gesichts identifiziert wurde. Es sollte sich hierbei um die ID handeln, die der Person „Family1-Dad“ entspricht, da dieser Person das Quellbild des Gesichts zugeordnet wurde.

Für die Gesichtsüberprüfung verwenden Sie die im vorherigen Schritt zurückgegebene Personen-ID, die LargePersonGroup-ID und außerdem die Quell-Gesichts-ID. Fügen Sie diese Werte in die Felder im Anforderungstext ein, und fügen Sie Ihren Schlüssel ein.

Windows
Linux

curl.exe -v -X POST "https://{resource endpoint}/face/v1.0/verify" `
-H "Content-Type: application/json" `
-H "Ocp-Apim-Subscription-Key: {subscription key}" `
--data-ascii "{
    ""faceId"": ""INSERT_SOURCE_FACE_ID"",
    ""personId"": ""INSERT_PERSON_ID"",
    ""largePersonGroupId"": ""INSERT_PERSONGROUP_ID""
}"

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

Die Antwort sollte Ihnen ein boolesches Überprüfungsergebnis zusammen mit einem Konfidenzwert liefern.

Bereinigen von Ressourcen

Um die LargePersonGroup zu löschen, die Sie in dieser Übung erstellt haben, führen Sie den Aufruf „Delete“ für LargePersonGroup aus.

Windows
Linux

curl.exe -v -X DELETE "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}" -H "Ocp-Apim-Subscription-Key: {subscription key}"

curl -v -X DELETE "https://{resource endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}" -H "Ocp-Apim-Subscription-Key: {subscription key}"

Nächste Schritte

In dieser Schnellstartanleitung haben Sie gelernt, wie Sie die Gesichtserkennungs-REST-API für einfache Gesichtserkennungsaufgaben verwenden. Als Nächstes erfahren Sie mehr über die verschiedenen Gesichtserkennungsmodelle und darüber, wie Sie das richtige Modell für Ihren Anwendungsfall angeben.

Angeben einer Gesichtserkennungsmodellversion

Was ist der Gesichtserkennungsdienst?

Freigeben über

Schnellstart: Verwenden des Gesichtserkennungsdiensts

Voraussetzungen

Erstellen von Umgebungsvariablen

Identifizieren und Überprüfen von Gesichtern

Installieren der Clientbibliothek

Installieren der Clientbibliothek

Output

Bereinigen von Ressourcen

Nächste Schritte

Voraussetzungen

Erstellen von Umgebungsvariablen

Identifizieren und Überprüfen von Gesichtern

Output

Bereinigen von Ressourcen

Nächste Schritte

Voraussetzungen

Erstellen von Umgebungsvariablen

Identifizieren und Überprüfen von Gesichtern

Output

Bereinigen von Ressourcen

Nächste Schritte

Voraussetzungen

Erstellen von Umgebungsvariablen

Identifizieren und Überprüfen von Gesichtern

Output

Bereinigen von Ressourcen

Nächste Schritte

Voraussetzungen

Identifizieren und Überprüfen von Gesichtern

Bereinigen von Ressourcen

Nächste Schritte

Feedback

Zusätzliche Ressourcen