Compartir a través de

Biblioteca cliente de Azure AI Face para JavaScript: versión 1.0.0-beta.1

El servicio Face de Azure AI ofrece algoritmos de IA que detectan, reconocen y analizan caras humanas en las imágenes. Incluye las siguientes características principales:

  • Detección y análisis de caras
  • Detección de ejecución
  • Reconocimiento facial
    • Verificación facial (coincidencia de uno a uno)
    • Identificación facial (coincidencia de uno a varios)
  • Búsqueda de caras similares
  • Agrupación de caras

| Documentación del productoCódigo | fuentePaquete (NPM) | Muestras | Documentación de referencia de API

Introducción

Entornos admitidos actualmente

  • Versiones de LTS de Node.js

Para más información, consulte la directiva de compatibilidad.

Requisitos previos

Creación de una cuenta de varios servicios de Azure AI o Face

Azure AI Face admite el acceso multiservicio y de un solo servicio. Cree una cuenta de varios servicios de Azure AI si planea acceder a varios servicios de Azure AI en un único punto de conexión o clave. Solo para el acceso a Face, cree un recurso de Face.

Instalar el paquete

Instale la biblioteca cliente REST de Azure Face para JavaScript con npm:

npm install @azure-rest/ai-vision-face

Autenticar el cliente

Para interactuar con el servicio Face, deberá crear una instancia de un cliente. Se necesita un punto de conexión y una credencial para crear instancias del objeto de cliente.

Tanto la credencial de clave como la credencial de id. de Microsoft Entra se admiten para autenticar al cliente. Para mejorar la seguridad, se recomienda encarecidamente usar las credenciales de Id. de Entra de Microsoft para la autenticación en el entorno de producción, mientras que AzureKeyCredential debe reservarse exclusivamente para el entorno de prueba.

Obtención del punto de conexión

Puede encontrar el punto de conexión del recurso de Face mediante Azure Portal o la CLI de Azure:

# Get the endpoint for the Face resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "properties.endpoint"

Se puede usar un punto de conexión regional o un subdominio personalizado para la autenticación. Tienen el siguiente formato:

Regional endpoint: https://<region>.api.cognitive.microsoft.com/
Custom subdomain: https://<resource-name>.cognitiveservices.azure.com/

Un punto de conexión regional es el mismo para cada recurso de una región. Aquí se puede consultar una lista completa de los puntos de conexión regionales admitidos. Tenga en cuenta que los puntos de conexión regionales no admiten la autenticación de Id. de Entra de Microsoft. Si desea migrar el recurso para usar un subdominio personalizado, siga las instrucciones que se indican aquí.

Un subdominio personalizado, por otro lado, es un nombre que es único para el recurso. Una vez creado y vinculado a un recurso, no se puede modificar.

Creación del cliente con una credencial de id. de Microsoft Entra

AzureKeyCredential La autenticación se usa en los ejemplos de esta guía de introducción, pero también puede autenticarse con el identificador de Entra de Microsoft mediante la biblioteca de @azure/identidad . Tenga en cuenta que los puntos de conexión regionales no admiten la autenticación de Identificador de Entra de Microsoft. Cree un nombre de subdominio personalizado para el recurso con el fin de usar este tipo de autenticación.

Para usar el tipo DefaultAzureCredential que se muestra a continuación u otros tipos de credenciales proporcionados con el SDK de Azure, instale el @azure/identity paquete:

npm install --save @azure/identity

También deberá registrar una nueva aplicación de id. de Microsoft Entra y conceder acceso a Face mediante la asignación del "Cognitive Services User" rol a la entidad de servicio.

Una vez completado, establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación microsoft Entra ID como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

/**
 * DefaultAzureCredential will use the values from these environment
 * variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
 */
import { DefaultAzureCredential } from '@azure/identity';
import createFaceClient from '@azure-rest/ai-vision-face';

const endpoint = process.env['FACE_ENDPOINT'] || '<endpoint>';
const credential = new DefaultAzureCredential();
const client = createFaceClient(endpoint, credential);

Creación del cliente con AzureKeyCredential

Para usar una clave de API como credential parámetro, pase la clave como una cadena a una instancia de AzureKeyCredential. Puede obtener la clave de API del recurso de Face mediante Azure Portal o la CLI de Azure:

# Get the API keys for the Face resource
az cognitiveservices account keys list --name "<resource-name>" --resource-group "<resource-group-name>"

import { AzureKeyCredential } from '@azure/core-auth';
import createFaceClient from '@azure-rest/ai-vision-face';

const endpoint = process.env['FACE_ENDPOINT'] || '<endpoint>';
const apikey = process.env['FACE_APIKEY'] || '<apikey>';
const credential = new AzureKeyCredential(apikey);
const client = createFaceClient(endpoint, credential);

Conceptos clave

FaceClient

FaceClient es la interfaz principal para los desarrolladores que interactúan con el servicio Azure AI Face. Sigue el diseño del cliente REST y actúa como puerta de enlace desde la que se producirá toda la interacción con la biblioteca.

Operaciones de larga duración

Las operaciones de ejecución prolongada son operaciones que constan de una solicitud inicial enviada al servicio para iniciar una operación, seguida de sondear el servicio a intervalos para determinar si la operación se ha completado o ha producido un error y, si se ha realizado correctamente, para obtener el resultado. Para obtener más información, consulte la sección "Operaciones de ejecución prolongada" de esta entrada de blog.

Operaciones de cara de larga duración actuales:

Ejemplos

En la siguiente sección se proporcionan varios fragmentos de código que abarcan algunas de las tareas de Face más comunes, entre las que se incluyen:

Detección facial

Detectar caras y analizarlas a partir de datos binarios.

import { readFileSync } from 'fs';
import { AzureKeyCredential } from '@azure/core-auth';

import createFaceClient, {
    isUnexpected,
} from '@azure-rest/ai-vision-face';

const endpoint = process.env['FACE_ENDPOINT'] || '<endpoint>';
const apikey = process.env['FACE_APIKEY'] || '<apikey>';
const credential = new AzureKeyCredential(apikey);
const client = createFaceClient(endpoint, credential);

const response = await client.path('/detect').post({
    contentType: 'application/octet-stream',
    queryParameters: {
        detectionModel: 'detection_03',
        recognitionModel: 'recognition_04',
        returnFaceLandmarks: true,
        returnRecognitionModel: true,
        faceIdTimeToLive: 120,
        returnFaceAttributes: ['headPose', 'mask', 'qualityForRecognition'],
        returnFaceId: false,
    },
    body: readFileSync('path/to/test/image'),
});
if (isUnexpected(response)) {
    throw new Error(response.body.error.message);
}
console.log(response.body);

Reconocimiento facial de LargePersonGroup

Identifique una cara con un LargePersonGroup definido.

En primer lugar, tenemos que crear un LargePersonGroup, agregarle algunas personas y, a continuación, registrar caras con estas personas.

import { readFileSync } from 'fs';
import { AzureKeyCredential } from '@azure/core-auth';

import createFaceClient, {
    getLongRunningPoller,
    isUnexpected,
} from '@azure-rest/ai-vision-face';

const endpoint = process.env['FACE_ENDPOINT'] || '<endpoint>';
const apikey = process.env['FACE_APIKEY'] || '<apikey>';
const credential = new AzureKeyCredential(apikey);
const client = createFaceClient(endpoint, credential);

const largePersonGroupId = 'lpg_family';

console.log(`Create a large person group with id: ${largePersonGroupId}`);
const createLargePersonGroupResponse = await client.path('/largepersongroups/{largePersonGroupId}', largePersonGroupId).put({
    body: {
        name: 'My Family',
        recognitionModel: 'recognition_04',
    },
});

console.log('Create a Person Bill and add a face to him.');
const createLargePersonGroupPersonResponse_bill = await client.path('/largepersongroups/{largePersonGroupId}/persons', largePersonGroupId).post({
    body: {
        name: 'Bill',
        userData: 'Dad',
    },
});
if (isUnexpected(createLargePersonGroupPersonResponse_bill)) {
    throw new Error(createLargePersonGroupPersonResponse_bill.body.error.message);
}
const personId_bill = createLargePersonGroupPersonResponse_bill.body.personId;
await client.path('/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces', largePersonGroupId, personId_bill).post({
    queryParameters: {
        userData: 'Dad-0001',
        detectionModel: 'detection_03',
    },
    contentType: 'application/octet-stream',
    body: readFileSync('path/to/bill/image'),
});

console.log('Create a Person Clare and add a face to her.');
const createLargePersonGroupPersonResponse_clare = await client.path('/largepersongroups/{largePersonGroupId}/persons', largePersonGroupId).post({
    body: {
        name: 'Clare',
        userData: 'Mom',
    },
});
if (isUnexpected(createLargePersonGroupPersonResponse_clare)) {
    throw new Error(createLargePersonGroupPersonResponse_clare.body.error.message);
}
const personId_clare = createLargePersonGroupPersonResponse_clare.body.personId;
await client.path('/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces', largePersonGroupId, personId_clare).post({
    queryParameters: {
        userData: 'Mom-0001',
        detectionModel: 'detection_03',
    },
    contentType: 'application/octet-stream',
    body: readFileSync('path/to/clare/image'),
});

Antes de realizar la identificación, primero debemos entrenar largePersonGroup.

console.log(`Start to train the large person group: ${largePersonGroupId}`);
const trainResponse = await client.path('/largepersongroups/{largePersonGroupId}/train', largePersonGroupId).post();
const trainPoller = await getLongRunningPoller(client, trainResponse);
await trainPoller.pollUntilDone();
// Check if poller.getOperationState().status is 'succeeded'.

Cuando la operación de entrenamiento se completa correctamente, podemos identificar las caras de este largePersonGroup throught.

console.log('Detect faces from the target image.');
const detectResponse = await client.path('/detect').post({
    contentType: 'application/octet-stream',
    queryParameters: {
        detectionModel: 'detection_03',
        recognitionModel: 'recognition_04',
        returnFaceId: true,
    },
    body: readFileSync('path/to/target/image'),
});
if (isUnexpected(detectResponse)) {
    throw new Error(detectResponse.body.error.message);
}
const faceIds = detectResponse.body.map(face => face.faceId as string)

console.log('Identify the faces in the large person group.');
const identifyResponse = await client.path('/identify').post({
    body: { faceIds, largePersonGroupId },
});
if (isUnexpected(identifyResponse)) {
    throw new Error(identifyResponse.body.error.message);
}
console.log(identifyResponse.body);

Por último, quite el grupo de personas grandes si ya no lo necesita.

console.log(`Delete the large person group: ${largePersonGroupId}`);
await client.path('/largepersongroups/{largePersonGroupId}', largePersonGroupId).delete();

Detección de ejecución

La detección de liveness de face se puede usar para determinar si una cara de una secuencia de vídeo de entrada es real (en directo) o falsa (suplantación de identidad). El objetivo de la detección de vida es garantizar que el sistema interactúe con una persona físicamente presente en el momento de la autenticación. Todo el proceso de autenticación se denomina sesión.

Hay dos componentes diferentes en la autenticación: una aplicación de front-end y un servidor o orquestador de aplicaciones. Antes de cargar la secuencia de vídeo, el servidor de aplicaciones tiene que crear una sesión y, a continuación, el cliente de front-end podría cargar la carga con para session authorization token llamar a la detección de ejecución. El servidor de aplicaciones puede consultar el resultado de la detección de ejecución y los registros de auditoría en cualquier momento hasta que se elimine la sesión.

La operación de detección de ejecución no solo puede confirmar si la entrada es activa o suplantación de identidad, sino que también comprueba si la entrada pertenece a la cara de la persona esperada, lo que se denomina detección de ejecución con verificación facial. Para obtener información detallada, consulte el tutorial.

Este paquete solo es responsable de que el servidor de aplicaciones cree, consulte, elimine una sesión y obtenga registros de auditoría. Para obtener información sobre cómo integrar la interfaz de usuario y el código en la aplicación de front-end nativa, siga las instrucciones del tutorial.

Este es un ejemplo para crear y obtener el resultado de detección de ejecución de una sesión.

import { randomUUID } from 'crypto';

import { AzureKeyCredential } from '@azure/core-auth';

import createFaceClient, {
    isUnexpected,
} from '@azure-rest/ai-vision-face';

const endpoint = process.env['FACE_ENDPOINT'] || '<endpoint>';
const apikey = process.env['FACE_APIKEY'] || '<apikey>';
const credential = new AzureKeyCredential(apikey);
const client = createFaceClient(endpoint, credential);

console.log('Create a new liveness session.');
const createLivenessSessionResponse = await client.path('/detectLiveness/singleModal/sessions').post({
    body: {
        livenessOperationMode: 'Passive',
        deviceCorrelationId: randomUUID(),
        sendResultsToClient: false,
        authTokenTimeToLiveInSeconds: 60,
    },
});
if (isUnexpected(createLivenessSessionResponse)) {
    throw new Error(createLivenessSessionResponse.body.error.message);
}
console.log(createLivenessSessionResponse.body);

const { sessionId } = createLivenessSessionResponse.body;

console.log('Get liveness detection results.');
const getLivenessSessionResponse = await client.path('/detectLiveness/singleModal/sessions/{sessionId}', sessionId).get();
if (isUnexpected(getLivenessSessionResponse)) {
    throw new Error(getLivenessSessionResponse.body.error.message);
}
console.log(getLivenessSessionResponse.body);

Este es otro ejemplo de detección de ejecución con comprobación facial.

import { randomUUID } from 'crypto';
import { readFileSync } from 'fs';

import { AzureKeyCredential } from '@azure/core-auth';

import createFaceClient, {
    isUnexpected,
} from '@azure-rest/ai-vision-face';

const endpoint = process.env['FACE_ENDPOINT'] || '<endpoint>';
const apikey = process.env['FACE_APIKEY'] || '<apikey>';
const credential = new AzureKeyCredential(apikey);
const client = createFaceClient(endpoint, credential);

console.log('Create a new liveness with verify session with verify image.');
const createLivenessSessionResponse = await client.path('/detectLivenessWithVerify/singleModal/sessions').post({
    contentType: 'multipart/form-data',
    body: [
        {
            name: 'VerifyImage',
            body: readFileSync('path/to/verify/image'),
        },
        {
            name: 'Parameters',
            body: {
                livenessOperationMode: 'Passive',
                sendResultsToClient: false,
                authTokenTimeToLiveInSeconds: 60,
                deviceCorrelationId: randomUUID(),
            },
        },
    ],
});
if (isUnexpected(createLivenessSessionResponse)) {
    throw new Error(createLivenessSessionResponse.body.error.message);
}
console.log(createLivenessSessionResponse.body);

const { sessionId } = createLivenessSessionResponse.body;

console.log('Get the liveness detection and verification result.');
const getLivenessSessionResultResponse = await client.path('/detectLivenessWithVerify/singleModal/sessions/{sessionId}', sessionId).get();
if (isUnexpected(getLivenessSessionResultResponse)) {
    throw new Error(getLivenessSessionResultResponse.body.error.message);
}
console.log(getLivenessSessionResultResponse.body);

Solución de problemas

General

Los códigos de error y los mensajes generados por el servicio Face se pueden encontrar en la documentación del servicio.

Registro

La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos del paquete @azure/logger.

Pasos siguientes

Más código de ejemplo

Consulte el archivo Léame de ejemplo para ver varios fragmentos de código que ilustran patrones comunes que se usan en Face JavaScript API.

Documentación adicional

Para obtener documentación más amplia sobre Azure AI Face, consulte la documentación de Face sobre learn.microsoft.com.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para obtener más información, vea las preguntas más frecuentes sobre el código de conducta o póngase en contacto con opencode@microsoft.com si tiene preguntas o comentarios.