Instalación y uso de contenedores de FaceInstall and run Face containers

Azure Cognitive Services Face proporciona un contenedor de Linux estandarizado para Docker que detecta rostros humanos en imágenes.Azure Cognitive Services Face provides a standardized Linux container for Docker that detects human faces in images. También identifica atributos, incluidos faciales (como narices y ojos), sexo, edad y otras características faciales previstas por la máquina.It also identifies attributes, which include face landmarks such as noses and eyes, gender, age, and other machine-predicted facial features. Además de la detección, Face puede comprobar si dos rostros en la misma o en imágenes diferentes coinciden mediante una puntuación de confianza.In addition to detection, Face can check if two faces in the same image or different images are the same by using a confidence score. Face también puede comparar rostros en una base de datos para ver si ya existe algún otro rostro similar o idéntico.Face also can compare faces against a database to see if a similar-looking or identical face already exists. También puede organizar rostros similares en grupos mediante rasgos visuales compartidos.It also can organize similar faces into groups by using shared visual traits.

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.If you don't have an Azure subscription, create a free account before you begin.

Requisitos previosPrerequisites

Debe cumplir los siguientes requisitos previos para poder usar los contenedores de Face API.You must meet the following prerequisites before you use the Face API containers.

ObligatorioRequired PropósitoPurpose
Motor de DockerDocker Engine El motor de Docker debe estar instalado en un equipo host.The Docker Engine must be installed on a host computer. Docker dispone de paquetes que configuran el entorno de Docker en macOS, Windows y Linux.Docker provides packages that configure the Docker environment on macOS, Windows, and Linux. Para conocer los principios básicos de Docker y de los contenedores, consulte Introducción a Docker.For a primer on Docker and container basics, see the Docker overview.

Docker debe configurarse para permitir que los contenedores se conecten con Azure y envíen datos de facturación a dicho servicio.Docker must be configured to allow the containers to connect with and send billing data to Azure.

En Windows, Docker también debe configurarse para admitir los contenedores de Linux.On Windows, Docker also must be configured to support Linux containers.

Conocimientos sobre DockerFamiliarity with Docker Debe tener conocimientos básicos sobre los conceptos de Docker, como los registros, los repositorios, los contenedores y las imágenes de contenedor.You need a basic understanding of Docker concepts, such as registries, repositories, containers, and container images. También necesita conocimientos sobre comandos de docker básicos.You also need knowledge of basic docker commands.
Recurso de FaceFace resource Para usar el contenedor, debe tener:To use the container, you must have:

Un recurso de Azure Face y la clave de API y el URI de punto de conexión asociados.An Azure Face resource and the associated API key and the endpoint URI. Ambos valores están disponibles en las páginas de introducción y claves del recurso.Both values are available on the Overview and Keys pages for the resource. Esto es necesario para iniciar el contenedor.They're required to start the container.

{API_KEY} : una de las dos claves de recurso disponibles en la página Claves{API_KEY}: One of the two available resource keys on the Keys page

{ENDPOINT_URI} : el punto de conexión tal como se proporciona en la página de Introducción.{ENDPOINT_URI}: The endpoint as provided on the Overview page

Solicitud de acceso al registro de contenedor privadoRequest access to the private container registry

Rellene y envíe el formulario de solicitud de contenedores de visión de Cognitive Services para solicitar acceso al contenedor.Fill out and submit the Cognitive Services Vision Containers Request form to request access to the container. El formulario solicita información acerca del usuario y de su empresa, así como del escenario de usuario para el que se va a usar el contenedor.The form requests information about you, your company, and the user scenario for which you'll use the container. Después de enviar el formulario, el equipo de Azure Cognitive Services lo revisa para asegurarse de que cumple los criterios de acceso al registro de contenedor privado.After you submit the form, the Azure Cognitive Services team reviews it to make sure that you meet the criteria for access to the private container registry.

Importante

Debe usar una dirección de correo electrónico asociada con una cuenta de Microsoft (MSA) o de Azure Active Directory (Azure AD) en el formulario.You must use an email address associated with either a Microsoft Account (MSA) or an Azure Active Directory (Azure AD) account in the form.

Si se aprueba la solicitud, recibirá un correo electrónico con instrucciones que describen cómo obtener las credenciales y acceder al registro de contenedor privado.If your request is approved, you receive an email with instructions that describe how to obtain your credentials and access the private container registry.

Inicio de sesión en el registro de contenedor privadoLog in to the private container registry

Hay varias maneras de autenticarse con el registro de contenedor privado para los contenedores de Cognitive Services.There are several ways to authenticate with the private container registry for Cognitive Services containers. Se recomienda que utilice el método de línea de comandos mediante la CLI de Docker.We recommend that you use the command-line method by using the Docker CLI.

Use el comando docker login, como se muestra en el ejemplo siguiente, para iniciar sesión en containerpreview.azurecr.io, que es el registro de contenedor privado de los contenedores de Cognitive Services.Use the docker login command, as shown in the following example, to log in to containerpreview.azurecr.io, which is the private container registry for Cognitive Services containers. Reemplace <username> por el nombre de usuario y <password> por la contraseña proporcionada en las credenciales que recibió del equipo de Azure Cognitive Services.Replace <username> with the user name and <password> with the password provided in the credentials you received from the Azure Cognitive Services team.

docker login containerpreview.azurecr.io -u <username> -p <password>

Si ha protegido las credenciales en un archivo de texto, puede concatenar el contenido del archivo de texto con el comando docker login.If you secured your credentials in a text file, you can concatenate the contents of that text file to the docker login command. Use el comando cat, como se muestra en el siguiente ejemplo:Use the cat command, as shown in the following example. Sustituya <passwordFile> por la ruta y el nombre del archivo de texto que contiene la contraseña.Replace <passwordFile> with the path and name of the text file that contains the password. Reemplace <username> por el nombre de usuario proporcionado en las credenciales.Replace <username> with the user name provided in your credentials.

cat <passwordFile> | docker login containerpreview.azurecr.io -u <username> --password-stdin

El equipo hostThe host computer

El host es un equipo basado en x64 que ejecuta el contenedor de Docker.The host is a x64-based computer that runs the Docker container. Puede ser un equipo del entorno local o un servicio de hospedaje de Docker incluido en Azure, como:It can be a computer on your premises or a Docker hosting service in Azure, such as:

Recomendaciones y requisitos del contenedorContainer requirements and recommendations

En la tabla siguiente se describen los núcleos de CPU y memoria mínimos y recomendados para asignar cada contenedor de Face API.The following table describes the minimum and recommended CPU cores and memory to allocate for each Face API container.

ContenedorContainer MínimaMinimum RecomendadoRecommended Transacciones por segundoTransactions per second
(mínimo, máximo)(Minimum, maximum)
CarasFace 1 núcleo, 2 GB de memoria1 core, 2-GB memory 1 núcleos, 4 GB de memoria1 core, 4-GB memory 10, 2010, 20
  • Cada núcleo debe ser de 2,6 GHz como mínimo.Each core must be at least 2.6 GHz or faster.
  • Transacciones por segundo (TPS).Transactions per second (TPS).

El núcleo y la memoria se corresponden con los valores de --cpus y --memory que se usan como parte del comando docker run.Core and memory correspond to the --cpus and --memory settings, which are used as part of the docker run command.

Obtención de la imagen de contenedor con el comando docker pullGet the container image with docker pull

Las imágenes de contenedor para Face API están disponibles.Container images for the Face API are available.

ContenedorContainer RepositorioRepository
CarasFace containerpreview.azurecr.io/microsoft/cognitive-services-face:latest

Sugerencia

Puede usar el comando docker images para enumerar las imágenes de contenedor descargadas.You can use the docker images command to list your downloaded container images. Por ejemplo, el comando siguiente muestra el id., el repositorio y la etiqueta de cada imagen de contenedor descargada, con formato de tabla:For example, the following command lists the ID, repository, and tag of each downloaded container image, formatted as a table:

docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

IMAGE ID         REPOSITORY                TAG
<image-id>       <repository-path/name>    <tag-name>

Docker pull para el contenedor de FaceDocker pull for the Face container

docker pull containerpreview.azurecr.io/microsoft/cognitive-services-face:latest

Uso del contenedorUse the container

Cuando el contenedor esté en el equipo host, use el siguiente proceso para trabajar con el contenedor.After the container is on the host computer, use the following process to work with the container.

  1. Ejecute el contenedor con la configuración de facturación requerida.Run the container with the required billing settings. Hay más ejemplos del comando docker run disponibles.More examples of the docker run command are available.
  2. Consulta del punto de conexión de predicción del contenedor.Query the container's prediction endpoint.

Ejecute el contenedor con docker runRun the container with docker run

Utilice el comando docker run para ejecutar cualquiera de los tres contenedores.Use the docker run command to run any of the three containers. El comando usa los parámetros siguientes.The command uses the following parameters.

Marcador de posiciónPlaceholder ValorValue
{API_KEY}{API_KEY} Esta clave se usa para iniciar el contenedor y está disponible en la página Cognitive ServicesClavesde Azure.This key is used to start the container and is available on the Azure Cognitive Services Keys page.
{ENDPOINT_URI}{ENDPOINT_URI} El valor del URI del punto de conexión de facturación está disponible en la página Cognitive ServicesInformación generalde Azure.The billing endpoint URI value is available on the Azure Cognitive Services Overview page. Un ejemplo es https://westus.api.cognitive.microsoft.com/face/v1.0.An example is https://westus.api.cognitive.microsoft.com/face/v1.0.

Agregue el enrutamiento face/v1.0 al URI del punto de conexión, tal como se muestra en el ejemplo anterior de ENDPOINT_URI.Add the face/v1.0 routing to the endpoint URI, as shown in the preceding ENDPOINT_URI example.

Reemplace estos parámetros con sus propios valores en el siguiente comando docker run de ejemplo:Replace these parameters with your own values in the following docker run command example:

docker run --rm -it -p 5000:5000 --memory 4g --cpus 1 \
containerpreview.azurecr.io/microsoft/cognitive-services-face \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

Este comando:This command:

  • Ejecuta un contenedor de Face desde la imagen de contenedor.Runs a face container from the container image.
  • Asigna un núcleo de CPU y 4 GB de memoria.Allocates one CPU core and 4 GB of memory.
  • Expone el puerto TCP 5000 y asigna un seudo-TTY para el contenedor.Exposes TCP port 5000 and allocates a pseudo TTY for the container.
  • Una vez que se produce la salida, quita automáticamente el contenedor.Automatically removes the container after it exits. La imagen del contenedor sigue estando disponible en el equipo host.The container image is still available on the host computer.

Hay más ejemplos del comando docker run disponibles.More examples of the docker run command are available.

Importante

Para poder ejecutar el contenedor, las opciones Eula, Billing y ApiKey deben estar especificadas; de lo contrario, el contenedor no se iniciará.The Eula, Billing, and ApiKey options must be specified to run the container or the container won't start. Para obtener más información, vea Facturación.For more information, see Billing.

Ejecución de varios contenedores en el mismo hostRun multiple containers on the same host

Si tiene pensado ejecutar varios contenedores con puertos expuestos, asegúrese de que ejecuta cada contenedor con un puerto expuesto diferente.If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. Por ejemplo, ejecute el primer contenedor en el puerto 5000 y el segundo en el puerto 5001.For example, run the first container on port 5000 and the second container on port 5001.

Puede tener este contenedor y un contenedor de Azure Cognitive Services diferente en ejecución simultáneamente en el HOST.You can have this container and a different Azure Cognitive Services container running on the HOST together. También puede tener varios contenedores del mismo contenedor de Cognitive Services en ejecución.You also can have multiple containers of the same Cognitive Services container running.

Consulta del punto de conexión de predicción del contenedorQuery the container's prediction endpoint

El contenedor proporciona varias API de puntos de conexión de predicción de consultas basadas en REST.The container provides REST-based query prediction endpoint APIs.

Utilice el host, https://localhost:5000, con las API de contenedor.Use the host, https://localhost:5000, for container APIs.

Comprobación de que un contenedor está en ejecuciónValidate that a container is running

Hay varias maneras de comprobar que el contenedor está en ejecución.There are several ways to validate that the container is running.

SolicitudRequest PropósitoPurpose
http://localhost:5000/ El contenedor ofrece una página principal.The container provides a home page.
http://localhost:5000/status Se solicitó con GET, para comprobar que el contenedor está en ejecución sin causar una consulta al punto de conexión.Requested with GET, to validate that the container is running without causing an endpoint query. Esta solicitud se puede usar con los sondeos de ejecución y preparación de Kubernetes.This request can be used for Kubernetes liveness and readiness probes.
http://localhost:5000/swagger El contenedor cuenta con un completo conjunto de documentación sobre los puntos de conexión y con una característica Try it now.The container provides a full set of documentation for the endpoints and a Try it now feature. Esta característica le permite especificar la configuración en un formulario HTML basado en web y realizar la consulta sin necesidad de escribir código.With this feature, you can enter your settings into a web-based HTML form and make the query without having to write any code. Una vez que la consulta devuelve resultados, se proporciona un ejemplo del comando CURL para mostrar los encabezados HTTP y el formato de cuerpo requeridos.After the query returns, an example CURL command is provided to demonstrate the HTTP headers and body format that's required.

Página principal del contenedor

Detención del contenedorStop the container

Para apagar el contenedor, en el entorno de la línea de comandos donde se ejecuta el contenedor, seleccione Ctrl + C.To shut down the container, in the command-line environment where the container is running, select Ctrl+C.

solución de problemasTroubleshooting

Si ejecuta el contenedor con un montaje de salida y el registro habilitados, el contenedor genera archivos de registro que resultan útiles para solucionar problemas que se producen al iniciar o ejecutar el contenedor.If you run the container with an output mount and logging is enabled, the container generates log files that are helpful to troubleshoot issues that happen while you start or run the container.

FacturaciónBilling

Los contenedores de Face API envían información de facturación a Azure mediante un recurso de Face API en la cuenta de Azure.The Face API containers send billing information to Azure by using a Face API resource on your Azure account.

Las consultas en el contenedor se facturan con el plan de tarifa del recurso de Azure que se usa para <ApiKey>.Queries to the container are billed at the pricing tier of the Azure resource that's used for the <ApiKey>.

Los contenedores de Azure Cognitive Services no tienen licencia para ejecutarse si no están conectados al punto de conexión de facturación para las mediciones.Azure Cognitive Services containers aren't licensed to run without being connected to the billing endpoint for metering. Debe habilitar los contenedores para que comuniquen la información de facturación al punto de conexión de facturación en todo momento.You must enable the containers to communicate billing information with the billing endpoint at all times. Los contenedores de Cognitive Services no envían datos de los clientes (por ejemplo, la imagen o el texto que se está analizando) a Microsoft.Cognitive Services containers don't send customer data, such as the image or text that's being analyzed, to Microsoft.

Conexión a AzureConnect to Azure

El contenedor necesita que se ejecuten los valores del argumento de facturación.The container needs the billing argument values to run. Estos valores permiten al contenedor conectarse al punto de conexión de facturación.These values allow the container to connect to the billing endpoint. El contenedor informa sobre el uso cada 10 a 15 minutos.The container reports usage about every 10 to 15 minutes. Si el contenedor no se conecta a Azure en la ventana de tiempo permitida, continuará ejecutándose pero no atenderá las consultas hasta que se restaure el punto de conexión de facturación.If the container doesn't connect to Azure within the allowed time window, the container continues to run but doesn't serve queries until the billing endpoint is restored. Se intenta 10 veces la conexión en el mismo intervalo de tiempo de 10 a 15 minutos.The connection is attempted 10 times at the same time interval of 10 to 15 minutes. Si no se puede conectar con el punto de conexión de facturación en esos 10 intentos, el contenedor deja de ejecutarse.If it can't connect to the billing endpoint within the 10 tries, the container stops running.

Argumentos de facturaciónBilling arguments

Para que el comando docker run inicie el contenedor, se deben especificar las tres opciones siguientes se deben especificar con valores válidos:For the docker run command to start the container, all three of the following options must be specified with valid values:

OpciónOption DESCRIPCIÓNDescription
ApiKey La clave de API del recurso de Cognitive Services que se usa para realizar un seguimiento de la información de facturación.The API key of the Cognitive Services resource that's used to track billing information.
El valor de esta opción se debe establecer en una clave de API para el recurso aprovisionado que se especifica en Billing.The value of this option must be set to an API key for the provisioned resource that's specified in Billing.
Billing El punto de conexión del recurso de Cognitive Services que se usa para realizar el seguimiento de la información de facturación.The endpoint of the Cognitive Services resource that's used to track billing information.
El valor de esta opción debe establecerse en el URI del punto de conexión de un recurso aprovisionado de Azure.The value of this option must be set to the endpoint URI of a provisioned Azure resource.
Eula Indica que ha aceptado la licencia del contenedor.Indicates that you accepted the license for the container.
El valor de esta opción debe establecerse en accept.The value of this option must be set to accept.

Para obtener más información acerca de estas opciones, consulte Configure containers (Configuración de contenedores).For more information about these options, see Configure containers.

Publicaciones de blogBlog posts

Ejemplos para desarrolladoresDeveloper samples

Hay ejemplos para desarrolladores disponibles en nuestro repositorio de GitHub.Developer samples are available at our GitHub repository.

Ver seminario webView webinar

Únase al seminario web para más información sobre:Join the webinar to learn about:

  • Implementación de Cognitive Services en cualquier máquina con DockerHow to deploy Cognitive Services to any machine using Docker
  • Implementación de Cognitive Services en AKSHow to deploy Cognitive Services to AKS

ResumenSummary

En este artículo aprendió los conceptos y el flujo de trabajo para la descarga, instalación y ejecución de contenedores de Face API.In this article, you learned concepts and workflow for how to download, install, and run Face API containers. En resumen:In summary:

  • Face API proporciona tres contenedores de Linux para Docker, que proporcionan la extracción de frases clave, la detección de idioma y el análisis de sentimiento.The Face API provides three Linux containers for Docker that provide key phrase extraction, language detection, and sentiment analysis.
  • Las imágenes de contenedor se descargan de Azure Container Registry.Container images are downloaded from the Azure Container Registry.
  • Las imágenes de contenedor se ejecutan en Docker.Container images run in Docker.
  • Puede usar la API REST o el SDK para llamar a operaciones en contenedores de Face API mediante la especificación del URI del host del contenedor.You can use either the REST API or the SDK to call operations in Face API containers by specifying the host URI of the container.
  • Debe especificar la información de facturación al crear una instancia de contenedor.You must specify billing information when you instantiate a container.

Importante

Los contenedores de Cognitive Services no tienen licencia para ejecutarse sin estar conectados a Azure para realizar mediciones.Cognitive Services containers aren't licensed to run without being connected to Azure for metering. Los clientes tienen que habilitar los contenedores para comunicar la información de facturación con el servicio de medición en todo momento.Customers must enable the containers to communicate billing information with the metering service at all times. Los contenedores de Cognitive Services no envían datos de los clientes (por ejemplo, la imagen o el texto que se está analizando) a Microsoft.Cognitive Services containers don't send customer data, such as the image or text that's being analyzed, to Microsoft.

Pasos siguientesNext steps