Tutorial: Compilación de un directorio de persona (versión preliminar)

Un directorio de persona proporciona un enfoque estructurado para almacenar datos faciales para tareas de reconocimiento. Permite agregar caras individuales, buscar caras visualmente similares y crear perfiles de persona. Puede asociar caras a estos perfiles y hacer coincidir imágenes de caras nuevas con personas conocidas. Esta configuración admite la coincidencia de caras flexible y el reconocimiento de identidad en imágenes y vídeos.

Recomendación de almacenamiento de datos

Para obtener acceso seguro y escalable, almacene imágenes de caras en Azure Blob Storage. Al realizar llamadas API, verifique que las URLs de las caras hagan referencia a esas imágenes almacenadas.

Inscripción

La inscripción implica los pasos siguientes:

1. Creación de un directorio de persona vacío
2. Agregar personas
3. Agregar caras y asociarlas a una persona

Creación de un directorio de persona vacío

Para crear un nuevo directorio de personas, envíe una PUT solicitud al punto de conexión de la API. Este directorio actúa como contenedor para almacenar caras y personas asociadas.

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: un identificador único definido por el usuario para el directorio dentro del recurso.
• description: (Opcional) Una breve descripción del propósito del directorio.
• tags: (Opcional) Pares clave-valor para ayudar a organizar y administrar el directorio.

La API crea el directorio y devuelve una respuesta de confirmación.

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
}

Agregar personas

Para reconocer o administrar usuarios, debe crear un perfil de persona. Una vez creado, puede asociar rostros a esta persona.

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

{
  "tags": {
    "name": "Alice",
    "employeeId": "E12345"
  }
}

• personDirectoryId: identificador único del directorio creado en el paso 1.
• tags: pares clave-valor para describir a la persona, como su nombre o edad.

La API devuelve un personId que identifica de forma única a la persona creada.

200 OK

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

Agregar caras y asociarlas a una persona

Puede agregar una cara al directorio y, opcionalmente, asociarla a una persona existente. La API admite direcciones URL de imagen y datos de imagen codificados 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: identificador único del directorio de persona creado en el paso 1.
• faceSource: especifica la imagen de cara.
  • url: ruta de acceso del archivo de la imagen almacenada en Azure Blob Storage.
  • data: datos de imagen codificados en Base64 como alternativa opcional a url.
  • imageReferenceId: (Opcional) Identificador definido por el usuario para la imagen. Este identificador puede ser útil para realizar un seguimiento del origen de la imagen o para asignarlo a otros datos.
  • targetBoundingBox: (Opcional) Ubicación aproximada de la cara en la imagen. Si se omite, la API detecta y usa el rostro más grande.
• qualityThreshold: (Opcional) Filtra la calidad de la cara (low, medium, o high). El valor predeterminado es medium, lo que significa que solo se almacenan caras medianas o de alta calidad. Se rechazan caras de menor calidad.
• personId: (Opcional) El personId de una persona existente con la que asociar la cara.

La API devuelve un faceId que identifica de forma única la cara creada con la detectada boundingBox de la cara.

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

Utilice el directorio de personas

Después de crear el directorio de personas y agregar imágenes faciales con asociaciones de personas opcionales, puede realizar dos tareas clave:

1. Identificar a una persona: haga coincidir una imagen de cara con las personas inscritas en el directorio y determine la identidad más probable.
2. Buscar caras similares: busque caras visualmente similares en todas las entradas de caras almacenadas del directorio.

Estas funcionalidades permiten un reconocimiento facial sólido y una coincidencia de similitud para varias aplicaciones.

Identificación de una persona

Identifique las coincidencias más probables de personas comparando el rostro de entrada con las personas registradas en el directorio.

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: la dirección URL de la imagen de rostro de entrada guardada en Azure Blob Storage.
• faceSource.targetBoundingBox: (Opcional) Cuadro delimitador aproximado de la cara en la imagen. Si se omite, la API detecta la cara más grande.
• maxPersonCandidates: (Opcional) Número máximo de candidatos a devolver. El valor predeterminado es 1.

La API devuelve el cuadro delimitador detectado del rostro junto con los principales candidatos.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "personCandidates": [
    {
      "personId": "{personId1}",
      "tags": {
        "name": "Alice",
        "employeeId": "E12345"
      },
      "confidence": 0.92
    }
  ]
}

• detectedFace.boundingBox: El cuadro delimitador de la cara detectada en la imagen de entrada.
• personCandidates: una lista de posibles coincidencias, cada una con un personId, asociado tags, y una puntuación confidence que indica la probabilidad de una coincidencia.

Buscar caras similares

Busque caras visualmente similares de todas las entradas de caras almacenadas en el directorio.

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: la dirección URL de la imagen facial de entrada almacenada en Azure Blob Storage.
• faceSource.targetBoundingBox: (Opcional) La caja delimitadora aproximada de la cara en la imagen. Si se omite, la API detecta la cara más grande.
• maxSimilarFaces: (Opcional) El número máximo de caras similares que se van a devolver. El valor predeterminado es 1000, con un límite máximo de 1000.

La API devuelve el cuadro delimitador detectado de la cara junto con las caras más similares del directorio.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "similarFaces": [
    {
      "faceId": "{faceId}",
      "boundingBox": { ... },
      "confidence": 0.92,
      "imageReferenceId": "face.jpg"
    }
  ]
}

• detectedFace.boundingBox: cuadro delimitador de la cara detectada en la imagen de entrada.
• similarFaces: una lista de caras similares, cada una con una puntuación basada en faceId, boundingBox y confidence, y un valor imageReferenceId que indica la imagen de origen.

Paso siguiente

Explore cómo identificar usuarios en contenido de vídeo mediante el Azure Content Understanding en las soluciones de vídeo de Foundry Tools (versión preliminar) .