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 flexible coincidencia de caras 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, asegúrese de que las URLs de los rostros hacen referencia a las imágenes que están 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 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, puedes 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 junto con el boundingBox detectado de la cara.

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

Uso del 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 a las personas que mejor coincidan comparando el rostro introducido con los de 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 facial de entrada almacenada en Azure Blob Storage.
• faceSource.targetBoundingBox: (opcional) el cuadro delimitador aproximado del rostro en la imagen. Si se omite, la API detecta la cara más grande.
• maxPersonCandidates: (opcional) el número máximo de candidatos que se debe 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 del rostro detectado 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 URL de la imagen facial de entrada almacenada en Azure Blob Storage.
• faceSource.targetBoundingBox: (opcional) el cuadro delimitador aproximado del rostro en la imagen. Si se omite, la API detecta el rostro más grande.
• maxSimilarFaces: (opcional) el número máximo de rostros 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 del rostro, junto con los rostros más similares del directorio.

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

• detectedFace.boundingBox: el cuadro delimitador del rostro detectado en la imagen de entrada.
• similarFaces: una lista de caras similares, cada una con una puntuación faceId, boundingBox, confidence, y un indicador 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) .