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. Este sistema admite una coincidencia flexible de rostros y el reconocimiento de identidad en imágenes y vídeos.

Recomendación de almacenamiento de datos

Para un acceso seguro y escalable, se recomienda almacenar todas las imágenes faciales en Azure Blob Storage. Al realizar llamadas API, asegúrese de que las direcciones URL de la cara hacen referencia a estas imágenes almacenadas en Blob Storage.

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 directorio de personas, envíe una PUT solicitud al endpoint de 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, usted 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) personId de una persona existente con la que asociar la cara.

La API devuelve un faceId que identifica de forma única el rostro creado con el boundingBox detectado del rostro.

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

Uso del directorio personal

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 de persona más probables comparando la cara de entrada con las personas inscritas 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 URL de la imagen facial de entrada almacenada en Azure Blob Storage.
• faceSource.targetBoundingBox: (Opcional) Cuadro de límite aproximado de la cara de 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 de límite detectado de la cara junto con los candidatos principales.

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

• detectedFace.boundingBox: cuadro de límite 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.

Búsqueda de 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 URL de la imagen facial de entrada almacenada en Azure Blob Storage.
• faceSource.targetBoundingBox: (Opcional) Cuadro de límite aproximado de la cara de 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 de límite 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 de límite de la cara detectada en la imagen de entrada.
• similarFaces: una lista de caras similares, cada una con una puntuación faceId, boundingBox, confidence y un valor imageReferenceId que indica la imagen de origen.

Paso siguiente

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