Freigeben über

Lernprogramm: Erstellen eines Personenverzeichnisses (Vorschau)

Ein Personenverzeichnis bietet einen strukturierten Ansatz zum Speichern von Gesichtsdaten für Erkennungsaufgaben. Sie können einzelne Gesichter hinzufügen, nach visuell ähnlichen Gesichtern suchen und Personenprofile erstellen. Sie können Gesichter mit diesen Profilen verknüpfen und neue Gesichtsbilder bekannten Personen zuordnen. Dieses Setup unterstützt sowohl flexible Gesichtsabgleichs- als auch Identitätserkennung für Bilder und Videos.

Diagramm, das die Prozesse der Registrierung und Suche in einem Personenverzeichnis veranschaulicht.

Empfehlung zur Datenspeicherung

Für den sicheren und skalierbaren Zugriff empfehlen wir, alle Gesichtsbilder in Azure Blob Storage zu speichern. Stellen Sie beim Durchführen von API-Aufrufen sicher, dass die Gesichts-URLs auf diese gespeicherten Bilder im Blob Storage verweisen.

Anmeldung

Die Registrierung umfasst die folgenden Schritte:

  1. Erstellen eines leeren Personenverzeichnisses
  2. Personen hinzufügen
  3. Hinzufügen von Gesichtern und Zuordnen zu einer Person

Erstellen eines leeren Personenverzeichnisses

Um ein neues Personenverzeichnis zu erstellen, senden Sie eine PUT Anforderung an den API-Endpunkt. Dieses Verzeichnis dient als Container zum Speichern von Gesichtern und zugeordneten Personen.

PUT {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}?api-version=2025-05-01-preview
Content-Type: application/json

{
  "description": "A brief description of the directory",
  "tags": {
    "project": "example-project",
    "owner": "team-name"
  }
}
  • personDirectoryId: Ein eindeutiger benutzerdefinierter Bezeichner für das Verzeichnis innerhalb der Ressource.
  • description: (Optional) Eine kurze Beschreibung des Zwecks des Verzeichnisses.
  • tags: (Optional) Schlüssel-Wert-Paare, um das Verzeichnis zu organisieren und zu verwalten.

Die API erstellt das Verzeichnis und gibt eine Bestätigungsantwort zurück.

200 OK

{
  "personDirectoryId": "{personDirectoryId}",
  "description": "A brief description of the directory",
  "createdAt": "2025-05-01T18:46:36.051Z",
  "lastModifiedAt": "2025-05-01T18:46:36.051Z",
  "tags": {
    "project": "example-project",
    "owner": "team-name"
  },
  "personCount": 0,
  "faceCount": 0
}

Personen hinzufügen

Um Einzelpersonen zu erkennen oder zu verwalten, müssen Sie ein Personenprofil erstellen. Nachdem Sie erstellt haben, können Sie dieser Person Gesichter zuordnen.

POST {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}/persons?api-version=2025-05-01-preview
Content-Type: application/json

{
  "tags": {
    "name": "Alice",
    "employeeId": "E12345"
  }
}
  • personDirectoryId: Der eindeutige Bezeichner des Verzeichnisses, das in Schritt 1 erstellt wurde.
  • tags: Schlüsselwertpaare, um die Person zu beschreiben, z. B. ihren Namen oder ihr Alter.

Die API gibt ein personId zurück, das die erstellte Person eindeutig identifiziert.

200 OK

{
  "personId": "4f66b612-e57d-4d17-9ef7-b951aea2cf0f",
  "tags": {
    "name": "Alice",
    "employeeId": "E12345"
  }
}

Hinzufügen von Gesichtern und Zuordnen zu einer Person

Sie können dem Verzeichnis ein Gesicht hinzufügen und optional einer vorhandenen Person zuordnen. Die API unterstützt sowohl Bild-URLs als auch base64-codierte Bilddaten.

POST {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}/faces?api-version=2025-05-01-preview
Content-Type: application/json

{
  "faceSource": {
    "url": "https://mystorageaccount.blob.core.windows.net/container/face.jpg",
    // "data": "<base64 data>",
    "imageReferenceId": "face.jpg",
    "targetBoundingBox": {
      "left": 33,
      "top": 73,
      "width": 262,
      "height": 324
    }
  },
  "qualityThreshold": "medium",
  "personId": "{personId}"
}
  • personDirectoryId: Der eindeutige Bezeichner des Personenverzeichnisses, das in Schritt 1 erstellt wurde.
  • faceSource: Gibt das Gesichtsbild an.
    • url: Der Dateipfad des in Azure Blob Storage gespeicherten Bilds.
    • data: Base64-codierte Bilddaten als optionale Alternative zu url.
    • imageReferenceId: (Optional) Ein benutzerdefinierter Bezeichner für das Bild. Dieser Bezeichner kann hilfreich sein, um den Ursprung des Bilds zu verfolgen oder es anderen Daten zuzuordnen.
    • targetBoundingBox: (Optional) Ungefähre Position des Gesichts im Bild. Wenn sie weggelassen wird, erkennt und verwendet die API das größte Gesicht.
  • qualityThreshold: (Optional) Filtert die Gesichtsqualität (low, mediumoder high). Der Standardwert ist medium, d. h. nur mittlere oder qualitativ hochwertige Gesichter werden gespeichert. Gesichter mit niedrigerer Qualität werden abgelehnt.
  • personId: (Optional) Das personId einer bestehenden Person, mit der das Gesicht verknüpft werden soll.

Die API gibt einen faceId zurück, der das erstellte Gesicht eindeutig mit den erkannten boundingBox Gesichtszügen identifiziert.

{
  "faceId": "{faceId}",
  "personId": "{personId}",
  "imageReferenceId": "face.jpg",
  "boundingBox": {
    "left": 30,
    "top": 78,
    "width": 251,
    "height": 309
  }
}

Verwenden des Personenverzeichnisses

Nachdem Sie Ihr Personenverzeichnis erstellt und Gesichtsbilder mit optionalen Personenzuordnungen hinzugefügt haben, können Sie zwei wichtige Aufgaben ausführen:

  1. Identifizieren einer Person: Abgleichen eines Gesichtsbilds mit registrierten Personen im Verzeichnis und Bestimmen der wahrscheinlichsten Identität.
  2. Suchen Nach ähnlichen Gesichtern: Suchen Sie nach visuell ähnlichen Gesichtern über alle gespeicherten Gesichtseinträge im Verzeichnis.

Diese Funktionen ermöglichen einen robusten Gesichtserkennungs- und Ähnlichkeitsabgleich für verschiedene Anwendungen.

Diagramm zur Veranschaulichung der Suchprozesse in einem Personenverzeichnis.

Identifizieren einer Person

Identifizieren Sie die wahrscheinlichsten Übereinstimmungen von Personen, indem Sie das Gesicht des Eingabefotos mit den eingetragenen Personen im Verzeichnis vergleichen.

POST {endpoint}/contentunderstanding/personDirectory/{personDirectoryId}/persons:identify?api-version=2025-05-01-preview
Content-Type: application/json

{
  "faceSource": {
    "url": "https://mystorageaccount.blob.core.windows.net/container/unknown.jpg",
    "targetBoundingBox": { ... }
  },
  "maxPersonCandidates": 1
}
  • faceSource.url: Die URL des Eingabebilds, das in Azure Blob Storage gespeichert ist.
  • faceSource.targetBoundingBox: (Optional) Das ungefähre Begrenzungsfeld des Gesichts im Bild. Wenn sie weggelassen wird, erkennt die API das größte Gesicht.
  • maxPersonCandidates: (Optional) Die maximale Anzahl von Personenkandidaten, die zurückgegeben werden sollen. Der Standardwert ist 1.

Die API gibt das erkannte umgebende Feld des Gesichts zusammen mit den Kandidaten der obersten Person zurück.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "personCandidates": [
    {
      "personId": "{personId1}",
      "tags": {
        "name": "Alice",
        "employeeId": "E12345"
      },
      "confidence": 0.92
    }
  ]
}
  • detectedFace.boundingBox: Das umgebende Feld der erkannten Oberfläche im Eingabebild.
  • personCandidates: Eine Liste der potenziellen Übereinstimmungen, die jeweils mit einer personId, zugeordneten tagsund einer confidence Bewertung, die die Wahrscheinlichkeit einer Übereinstimmung angibt.

Suchen ähnlicher Gesichter

Suchen Sie visuell ähnliche Gesichter aus allen gespeicherten Gesichtseinträgen im Verzeichnis.

POST {endpoint}/personDirectory/{personDirectoryId}/faces:find?api-version=2025-05-01-preview
Content-Type: application/json

{
  "faceSource": {
    "url": "https://mystorageaccount.blob.core.windows.net/container/target.jpg",
    "targetBoundingBox": { ... }
  },
  "maxSimilarFaces": 10
}
  • faceSource.url: Die URL des Eingabebilds, das in Azure Blob Storage gespeichert ist.
  • faceSource.targetBoundingBox: (Optional) Das ungefähre Begrenzungsfeld des Gesichts im Bild. Wenn sie weggelassen wird, erkennt die API das größte Gesicht.
  • maxSimilarFaces: (Optional) Die maximale Anzahl ähnlicher Gesichter, die zurückgegeben werden sollen. Der Standardwert ist 1000 mit maximal 1000.

Die API gibt das erkannte umgebende Feld des Gesichts zusammen mit den ähnlichsten Gesichtern aus dem Verzeichnis zurück.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "similarFaces": [
    {
      "faceId": "{faceId}",
      "boundingBox": { ... },
      "confidence": 0.92,
      "imageReferenceId": "face.jpg"
    }
  ]
}
  • detectedFace.boundingBox: Das umgebende Feld der erkannten Oberfläche im Eingabebild.
  • similarFaces: Eine Liste mit ähnlichen Gesichtern, die jeweils ein faceId, ein boundingBox, eine confidence-Punktzahl und ein imageReferenceId zur Angabe des Quellbilds haben.

Nächster Schritt

Erfahren Sie, wie Sie Personen in Videoinhalten mithilfe der Azure Content Understanding in Foundry Tools-Videolösungen (Vorschau) identifizieren können.

  • Last updated on