Partager via

Tutoriel : Créer un répertoire de personnes (préversion)

Un répertoire de personne fournit une approche structurée pour stocker les données de visage pour les tâches de reconnaissance. Il vous permet d’ajouter des visages individuels, de rechercher des visages visuellement similaires et de créer des profils de personne. Vous pouvez associer des visages à ces profils et faire correspondre de nouvelles images de visage à des personnes connues. Cette configuration prend en charge la correspondance flexible des visages et la reconnaissance des identités entre les images et les vidéos.

Diagramme illustrant les processus d’inscription et de recherche dans un annuaire de personnes.

Recommandation de stockage des données

Pour un accès sécurisé et évolutif, nous vous recommandons de stocker toutes les images de visages dans Azure Blob Storage. Lorsque vous effectuez des appels d’API, assurez-vous que les URLs de visages font référence à ces images stockées dans le Stockage Blob.

Inscription

L’inscription implique les étapes suivantes :

  1. Créer un répertoire de personnes vide
  2. Ajouter des personnes
  3. Ajouter des visages et associer à une personne

Créer un répertoire de personnes vide

Pour créer un répertoire de personnes, envoyez une PUT demande au point de terminaison de l’API. Ce répertoire sert de conteneur pour stocker des visages et des personnes associées.

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: identificateur unique défini par l’utilisateur pour le répertoire dans la ressource.
  • description: (Facultatif) Brève description de l’objectif du répertoire.
  • tags: (Facultatif) Paires clé-valeur pour faciliter l’organisation et la gestion du répertoire.

L’API crée le répertoire et retourne une réponse de confirmation.

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
}

Ajouter des personnes

Pour reconnaître ou gérer des personnes, vous devez créer un profil de personne. Une fois créé, vous pouvez associer des visages à cette personne.

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

{
  "tags": {
    "name": "Alice",
    "employeeId": "E12345"
  }
}
  • personDirectoryId: identificateur unique du répertoire créé à l’étape 1.
  • tags: paires clé-valeur pour décrire la personne, telle que son nom ou son âge.

L’API retourne une personId valeur qui identifie de manière unique la personne créée.

200 OK

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

Ajouter des visages et associer à une personne

Vous pouvez ajouter un visage au répertoire et éventuellement l’associer à une personne existante. L’API prend en charge les URL d’image et les données d’image encodées en base64.

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: identificateur unique du répertoire de personne créé à l’étape 1.
  • faceSource: spécifie l’image du visage.
    • url: chemin d'accès du fichier image stocké dans Azure Blob Storage.
    • data: Données d’image encodées en base64 comme alternative facultative à url.
    • imageReferenceId: (Facultatif) Identificateur défini par l’utilisateur pour l’image. Cet identificateur peut être utile pour suivre l’origine de l’image ou pour la mapper à d’autres données.
    • targetBoundingBox: (Facultatif) Emplacement approximatif du visage dans l’image. Si elle est omise, l’API détecte et utilise le visage le plus grand.
  • qualityThreshold: (Facultatif) Filtre la qualité du visage (low, mediumou high). La valeur par défaut est medium, ce qui signifie que seuls les visages de moyenne ou haute qualité sont stockés. Les visages de qualité inférieure sont rejetés.
  • personId: (Facultatif) Personne personId existante à laquelle associer le visage.

L'API retourne un faceId qui identifie de manière unique le visage créé grâce à l'identifiant détecté boundingBox du visage.

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

Utiliser l’annuaire de personnes

Après avoir créé votre répertoire de personnes et ajouté des images visage avec des associations de personnes facultatives, vous pouvez effectuer deux tâches clés :

  1. Identifier une personne : faire correspondre une image visage à des personnes inscrites dans le répertoire et déterminer l’identité la plus probable.
  2. Rechercher des visages similaires : recherchez des visages visuellement similaires sur toutes les entrées de visage stockées dans le répertoire.

Ces fonctionnalités permettent une reconnaissance faciale robuste et une correspondance de similarité pour différentes applications.

Diagramme illustrant les processus de recherche dans un répertoire de personne.

Identifier une personne

Identifiez la personne la plus susceptible de correspondre en comparant le visage en entrée à celui des personnes inscrites dans l’annuaire.

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: URL de l’image faciale d’entrée stockée dans Azure Blob Storage.
  • faceSource.targetBoundingBox : (Facultatif) Cadre englobant approximatif du visage dans l’image. Si omis, l’API détecte le visage le plus grand.
  • maxPersonCandidates : (Facultatif) Nombre maximal de candidats à retourner. 1 constitue la valeur par défaut.

L’API retourne le cadre englobant détecté du visage, ainsi que les principaux candidats.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "personCandidates": [
    {
      "personId": "{personId1}",
      "tags": {
        "name": "Alice",
        "employeeId": "E12345"
      },
      "confidence": 0.92
    }
  ]
}
  • detectedFace.boundingBox : Cadre englobant du visage détecté dans l’image en entrée.
  • personCandidates: liste de correspondances potentielles, chacune avec un personId, associé tagset un confidence score indiquant la probabilité d’une correspondance.

Rechercher des visages semblables

Recherchez des visages visuellement similaires à partir de toutes les entrées de visage stockées dans le répertoire.

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: URL de l’image faciale d’entrée stockée dans Azure Blob Storage.
  • faceSource.targetBoundingBox : (Facultatif) Cadre englobant approximatif du visage dans l’image. Si omis, l’API détecte le visage le plus grand.
  • maxSimilarFaces : (Facultatif) Nombre maximal de visages similaires à retourner. La valeur par défaut est 1 000, avec une limite maximale de 1 000.

L’API retourne le cadre englobant détecté du visage, ainsi que les visages les plus similaires de l’annuaire.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "similarFaces": [
    {
      "faceId": "{faceId}",
      "boundingBox": { ... },
      "confidence": 0.92,
      "imageReferenceId": "face.jpg"
    }
  ]
}
  • detectedFace.boundingBox : Cadre englobant du visage détecté dans l’image en entrée.
  • similarFaces: Une liste de visages similaires, chacun avec un score faceId, boundingBox, confidence et un imageReferenceId indiquant l'image source.

Étape suivante

Découvrez comment identifier des personnes dans du contenu vidéo à l’aide des solutions vidéo d'Azure Content Understanding dans les outils Foundry (préversion).

  • Last updated on