Installer et exécuter des conteneurs de visageInstall and run Face containers

Visage de Services cognitifs Azure fournit un conteneur de Linux standardisé pour Docker qui détecte les visages humains dans des images.Azure Cognitive Services Face provides a standardized Linux container for Docker that detects human faces in images. Il identifie également les attributs, qui incluent des points de repère visage telles que noses et yeux, sexe, l’âge et autres fonctionnalités du visage prédite à la machine.It also identifies attributes, which include face landmarks such as noses and eyes, gender, age, and other machine-predicted facial features. En plus de détection, Face peut vérifier si deux visages dans la même image ou des images différentes sont identiques à l’aide d’un score de confiance.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 peut également comparer les visages par rapport à une base de données pour voir si un visage similaires ou identique existe déjà.Face also can compare faces against a database to see if a similar-looking or identical face already exists. Il peut également organiser les visages similaires dans des groupes à l’aide de traits visual partagés.It also can organize similar faces into groups by using shared visual traits.

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.If you don't have an Azure subscription, create a free account before you begin.

Conditions préalablesPrerequisites

Vous devez respecter les conditions préalables suivantes avant d’utiliser les conteneurs de l’API visage.You must meet the following prerequisites before you use the Face API containers.

ObligatoireRequired ObjectifPurpose
Moteur DockerDocker Engine Le moteur Docker doit être installé sur un ordinateur hôte.The Docker Engine must be installed on a host computer. Docker fournit des packages qui configurent l’environnement Docker sur macOS, Windows et Linux.Docker provides packages that configure the Docker environment on macOS, Windows, and Linux. Pour apprendre les principes de base de Docker et des conteneurs, consultez la vue d’ensemble de Docker.For a primer on Docker and container basics, see the Docker overview.

Vous devez configurer Docker pour permettre aux conteneurs de se connecter à Azure et de lui envoyer des données de facturation.Docker must be configured to allow the containers to connect with and send billing data to Azure.

Sur Windows, Docker doit également être configuré pour prendre en charge des conteneurs Linux.On Windows, Docker also must be configured to support Linux containers.

Bonne connaissance de DockerFamiliarity with Docker Vous avez besoin d’une compréhension élémentaire des concepts Docker, telles que les registres, les dépôts, les conteneurs et les images de conteneur.You need a basic understanding of Docker concepts, such as registries, repositories, containers, and container images. Vous devez également les connaissances de base docker commandes.You also need knowledge of basic docker commands.
Azure Cognitive Services ressourceAzure Cognitive Services resource Pour utiliser le conteneur, vous devez disposer de :To use the container, you must have:

Une ressource Azure Cognitive Services et la clé de facturation associée et l’URI de point de terminaison facturation.An Azure Cognitive Services resource and the associated billing key and the billing endpoint URI. Les deux valeurs sont disponibles sur le vue d’ensemble et clés pages pour la ressource.Both values are available on the Overview and Keys pages for the resource. Elles sont requises pour démarrer le conteneur.They're required to start the container. Ajouter le face/v1.0 routage vers le point de terminaison URI, comme indiqué dans l’exemple BILLING_ENDPOINT_URI suivant :Add the face/v1.0 routing to the endpoint URI, as shown in the following BILLING_ENDPOINT_URI example:

{BILLING_KEY}  : clé de ressource{BILLING_KEY}: resource key

{BILLING_ENDPOINT_URI} : exemple d’URI de point de terminaison est https://westus.api.cognitive.microsoft.com/face/v1.0{BILLING_ENDPOINT_URI}: endpoint URI example is https://westus.api.cognitive.microsoft.com/face/v1.0

Demander l’accès au registre de conteneurs privéRequest access to the private container registry

Vous devez d'abord compléter et envoyer le formulaire de demande de conteneurs Vision Cognitive Services pour demander l'accès au conteneur.You must first complete and submit the Cognitive Services Vision Containers Request form to request access to the container. Le formulaire demande des informations sur vous, votre entreprise et le scénario d’utilisateur pour lequel vous allez utiliser le conteneur.The form requests information about you, your company, and the user scenario for which you'll use the container. À la réception du formulaire, l’équipe Azure Cognitive Services vérifie que vous remplissez bien les critères d’accès au registre de conteneurs privé.Once submitted, the Azure Cognitive Services team reviews the form to ensure that you meet the criteria for access to the private container registry.

Important

Vous devez utiliser une adresse e-mail associée à un compte Microsoft (MSA) ou à un compte Azure Active Directory (Azure AD) dans le formulaire.You must use an email address associated with either a Microsoft Account (MSA) or Azure Active Directory (Azure AD) account in the form.

Si votre demande est approuvée, vous recevez un e-mail contenant des instructions relatives à l’obtention de vos informations d’identification et à l’accès au registre de conteneurs privé.If your request is approved, you then receive an email with instructions describing how to obtain your credentials and access the private container registry.

Se connecter au registre de conteneurs privéLog in to the private container registry

Il y a plusieurs façons de s’authentifier auprès du registre de conteneurs privé pour les conteneurs Cognitive Services, mais la méthode recommandée à partir de la ligne de commande est l’utilisation de la CLI Docker.There are several ways to authenticate with the private container registry for Cognitive Services Containers, but the recommended method from the command line is by using the Docker CLI.

Utilisez la commande docker login, comme indiqué dans l’exemple suivant, pour vous connecter à containerpreview.azurecr.io, le registre de conteneurs privé pour les conteneurs Cognitive Services.Use the docker login command, as shown in the following example, to log into containerpreview.azurecr.io, the private container registry for Cognitive Services Containers. Remplacez <username> par le nom de l’utilisateur et <password> par le mot de passe fourni dans les informations d’identification envoyées par l’équipe 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 vous avez sécurisé vos informations d’identification dans un fichier texte, vous pouvez utiliser la commande cat pour concaténer son contenu à la commande docker login, comme indiqué dans l’exemple suivant.If you have secured your credentials in a text file, you can concatenate the contents of that text file, using the cat command, to the docker login command as shown in the following example. Remplacez <passwordFile> par le chemin et le nom du fichier texte contenant le mot de passe, et <username> par le nom d’utilisateur fourni dans vos informations d’identification.Replace <passwordFile> with the path and name of the text file containing the password and <username> with the user name provided in your credentials.

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

L’ordinateur hôteThe host computer

Le hôte est un ordinateur x64 64 qui exécute le conteneur docker.The host is a x64-based computer that runs the docker container. Il peut s’agir d’un ordinateur local ou d’un service d’hébergement docker dans Azure, notamment :It can be a computer on your premises or a docker hosting service in Azure including:

Exigences et suggestions relatives au conteneurContainer requirements and recommendations

Le tableau suivant décrit la quantité minimale et recommandée de cœurs de processeur et de mémoire à allouer pour chaque conteneur de l’API Visage.The following table describes the minimum and recommended CPU cores and memory to allocate for each Face API container.

ConteneurContainer MinimaleMinimum RecommandéRecommended Transactions par secondeTransactions per second
(Minimum, maximum)(Minimum, maximum)
FaceFace 1 cœur, 2 Go de mémoire1 core, 2-GB memory 1 cœur, 4 Go de mémoire1 core, 4-GB memory 10, 2010, 20
  • Chaque cœur doit être au moins 2,6 GHz ou plus rapide.Each core must be at least 2.6 GHz or faster.
  • Transactions par seconde (TPS).Transactions per second (TPS).

Le nombre de cœurs et la quantité de mémoire correspondent aux paramètres --cpus et --memory qui sont utilisés dans le cadre de la commande docker run.Core and memory correspond to the --cpus and --memory settings, which are used as part of the docker run command.

Obtenir l’image de conteneur avec extraction de dockerGet the container image with docker pull

Images de conteneur pour l’API visage sont disponibles.Container images for the Face API are available.

ConteneurContainer DépôtRepository
FaceFace containerpreview.azurecr.io/microsoft/cognitive-services-face:latest

Conseil

Vous pouvez utiliser la commande docker images pour lister vos images conteneurs téléchargées.You can use the docker images command to list your downloaded container images. Par exemple, la commande suivante liste l’ID, le référentiel et la balise de chaque image conteneur téléchargée dans un tableau :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
ebbee78a6baa       <container-name>         latest

Commande docker pull du conteneur VisageDocker pull for the Face container

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

Utilisez le conteneurUse the container

Une fois le conteneur se trouve sur le ordinateur hôte, utilisez le processus suivant pour travailler avec le conteneur.After the container is on the host computer, use the following process to work with the container.

  1. Exécuter le conteneur avec les paramètres de facturation.Run the container with the required billing settings. D’autres exemples de commande docker run sont disponibles.More examples of the docker run command are available.
  2. Interrogez le point de terminaison de prédiction du conteneur.Query the container's prediction endpoint.

Exécuter le conteneur avec docker runRun the container with docker run

Utilisez la commande docker run pour exécuter l’un des trois conteneurs.Use the docker run command to run any of the three containers. La commande utilise les paramètres suivants.The command uses the following parameters.

PlaceholderPlaceholder ValeurValue
{BILLING_KEY}{BILLING_KEY} Cette clé est utilisée pour démarrer le conteneur et est disponible sur Azure Cognitive Services clés page.This key is used to start the container and is available on the Azure Cognitive Services Keys page.
{BILLING_ENDPOINT_URI}{BILLING_ENDPOINT_URI} La valeur de l’URI de point de terminaison facturation est disponible sur Azure Cognitive Services vue d’ensemble page.The billing endpoint URI value is available on the Azure Cognitive Services Overview page. Par exemple https://westus.api.cognitive.microsoft.com/face/v1.0.An example is https://westus.api.cognitive.microsoft.com/face/v1.0.

Ajouter le face/v1.0 routage vers le point de terminaison URI, comme indiqué dans l’exemple BILLING_ENDPOINT_URI précédent.Add the face/v1.0 routing to the endpoint URI, as shown in the preceding BILLING_ENDPOINT_URI example.

Remplacez ces paramètres par vos propres valeurs dans l’exemple suivant docker run exemple de commande :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={BILLING_ENDPOINT_URI} \
ApiKey={BILLING_KEY}

Cette commande :This command:

  • Exécute un conteneur de visage à partir de l’image de conteneur.Runs a face container from the container image.
  • Alloue un cœur de processeur et 4 Go de mémoire.Allocates one CPU core and 4 GB of memory.
  • Expose le port TCP 5000 et alloue une pseudo TTY pour le conteneur.Exposes TCP port 5000 and allocates a pseudo TTY for the container.
  • Supprime automatiquement le conteneur après sa fermeture.Automatically removes the container after it exits. L’image conteneur est toujours disponible sur l’ordinateur hôte.The container image is still available on the host computer.

D’autres exemples de commande docker run sont disponibles.More examples of the docker run command are available.

Important

Le Eula, Billing, et ApiKey options doivent être spécifiées pour exécuter le conteneur ou le conteneur ne démarre pas.The Eula, Billing, and ApiKey options must be specified to run the container or the container won't start. Pour plus d'informations, consultez Facturation.For more information, see Billing.

Plusieurs conteneurs en cours d’exécution sur le même hôteRunning multiple containers on the same host

Si vous envisagez d’exécuter plusieurs conteneurs avec les ports exposés, veillez à exécuter chaque conteneur avec un autre port exposé.If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. Par exemple, exécutez le premier conteneur sur le port 5000 et le second conteneur sur le port 5001.For example, run the first container on port 5000 and the second container on port 5001.

Vous pouvez avoir ce conteneur et un autre conteneur de Service COGNITIF qui exécutent ensemble sur l’ordinateur hôte, ou vous pouvez avoir plusieurs conteneurs du même conteneur Cognitive Service en cours d’exécution.You can have this container and a different Cognitive Service container running on the HOST together or you can have multiple containers of the same Cognitive Service container running.

Interroger le point de terminaison de prédiction du conteneurQuery the container's prediction endpoint

Le conteneur fournit des API de point de terminaison de prédiction de requête basées sur REST.The container provides REST-based query prediction endpoint APIs.

Utilisez l’hôte, https://localhost:5000, pour les API de conteneur.Use the host, https://localhost:5000, for container APIs.

Valider conteneur est en cours d’exécutionValidate container is running

Il existe plusieurs façons de valider le conteneur est en cours d’exécution :There are several ways to validate the container is running:

RequêteRequest ObjectifPurpose
http://localhost:5000/ Le conteneur fournit une page d’accueil.The container provides a homepage.
http://localhost:5000/status Demandé par GET, pour valider le conteneur est en cours d’exécution sans provoquer d’une requête de point de terminaison.Requested with GET, to validate the container is running without causing an endpoint query. Cela peut être utilisé pour Kubernetes sondes de temporisation et de préparation.This can be used for Kubernetes liveness and readiness probes.
http://localhost:5000/swagger Le conteneur fournit un ensemble complet de documentation pour les points de terminaison ainsi qu’une fonctionnalité Try it now.The container provides a full set of documentation for the endpoints as well as a Try it now feature. Cette fonctionnalité vous permet d’entrer vos paramètres dans un formulaire HTML basé sur le web et d’effectuer la requête sans avoir à écrire du code.This feature allows you to enter your settings into a web-based HTML form and make the query without having to write any code. Une fois la requête retournée, un exemple de commande CURL est fourni pour illustrer le format du corps et des en-têtes HTTP requis.Once the query returns, an example CURL command is provided to demonstrate the HTTP headers and body format required.

Page d’accueil du conteneur

Arrêter le conteneurStop the container

Pour arrêter le conteneur, dans l’environnement de ligne de commande où le conteneur est en cours d’exécution, appuyez sur Ctrl+C.To shut down the container, in the command-line environment where the container is running, press Ctrl+C.

Résolution de problèmesTroubleshooting

Si vous exécutez le conteneur avec une sortie monter et la journalisation est activée, le conteneur génère les fichiers journaux qui sont utiles résoudre les problèmes qui se produisent lors du démarrage ou d’exécuter le conteneur.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.

FacturationBilling

Les conteneurs de l’API visage envoient les informations de facturation sur Azure à l’aide d’une ressource de l’API visage sur votre compte Azure.The Face API containers send billing information to Azure by using a Face API resource on your Azure account.

Requêtes dans le conteneur sont facturées au niveau de tarification de la ressource Azure utilisé pour le <ApiKey>.Queries to the container are billed at the pricing tier of the Azure resource used for the <ApiKey>.

Les conteneurs de Services cognitifs ne sont pas concédés sous licence pour s’exécuter sans être connectés au point de terminaison de facturation pour le contrôle.Cognitive Services containers are not licensed to run without being connected to the billing endpoint for metering. Les clients doivent activer les conteneurs de communiquer des informations de facturation avec point de terminaison de facturation en permanence.Customers need to enable the containers to communicate billing information with billing endpoint at all times. Les conteneurs Cognitive Services n’envoient pas de données relatives aux clients (par exemple, l’image ou le texte en cours d’analyse) à Microsoft.Cognitive Services containers do not send customer data (for example, the image or text that is being analyzed) to Microsoft.

Connexion à AzureConnecting to Azure

Le conteneur doit les valeurs d’argument facturation à exécuter.The container needs the billing argument values to run. Ces valeurs permettent le conteneur pour se connecter au point de terminaison de facturation.These values allow the container to connect to billing endpoint. La conteneur crée des rapports sur l'utilisation toutes les 10 à 15 minutes.The container reports usage about every 10 to 15 minutes. Si le conteneur ne connecte pas au sein de la fenêtre de temps autorisée vers Azure, le conteneur continuera à fonctionner, mais elle ne traite pas les requêtes jusqu'à ce que le point de terminaison de facturation est restauré.If the container doesn't connect within the allowed time window to Azure, the container will continue to run but will not serve queries until the billing endpoint is restored. La connexion est exécutée 10 fois sur le même intervalle de temps de 10 à 15 minutes.The connection is attempted 10 times at the same time interval of 10 to 15 minutes. S’il ne peut pas se connecter au point de terminaison de facturation dans les 10 tentatives, le conteneur s’arrête en cours d’exécution.If it can't connect to the billing endpoint within the 10 tries, the container will stop running.

Arguments de facturationBilling arguments

Les trois options suivantes doivent être spécifiées avec les valeurs valides dans l’ordre pour la docker run commande pour démarrer le conteneur :All three of the following options must be specified with valid values in order for the docker run command to start the container:

OptionOption DescriptionDescription
ApiKey Clé API de la ressource Service cognitif utilisée pour le suivi des informations de facturation.The API key of the Cognitive Service resource used to track billing information.
La valeur de cette option doit être définie sur une clé API pour la ressource approvisionnée spécifiée dans Billing.The value of this option must be set to an API key for the provisioned resource specified in Billing.
Billing Clé API de la ressource Service cognitif utilisée pour le suivi des informations de facturation.The endpoint of the Cognitive Service resource used to track billing information.
La valeur de cette option doit être définie au point de terminaison URI d’une ressource Azure configurée.The value of this option must be set to the endpoint URI of a provisioned Azure resource.
Eula Indique que vous avez accepté la licence pour le conteneur.Indicates that you've accepted the license for the container.
La valeur de cette option doit être accept.The value of this option must be set to accept.

Pour plus d’informations sur ces options, consultez Configurer des conteneurs.For more information about these options, see Configure containers.

RésuméSummary

Dans cet article, vous avez appris des concepts et des flux de travail pour savoir comment télécharger, installer et exécuter des conteneurs de l’API visage.In this article, you learned concepts and workflow for how to download, install, and run Face API containers. En résumé :In summary:

  • L’API visage fournit trois conteneurs Linux pour Docker qui fournissent l’extraction de phrases clés, détection de la langue et l’analyse des sentiments.The Face API provides three Linux containers for Docker that provide key phrase extraction, language detection, and sentiment analysis.
  • Images de conteneur sont téléchargées à partir du Registre de conteneur Azure.Container images are downloaded from the Azure Container Registry.
  • Les images conteneurs s’exécutent dans Docker.Container images run in Docker.
  • Vous pouvez utiliser l’API REST ou le Kit de développement pour appeler des opérations dans des conteneurs de l’API visage en spécifiant l’URI du conteneur hôte.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.
  • Vous devez spécifier les informations de facturation lorsque vous instanciez un conteneur.You must specify billing information when you instantiate a container.

Important

Les conteneurs de Services cognitifs ne sont pas concédés sous licence pour s’exécuter sans être connecté à Azure pour le contrôle.Cognitive Services containers aren't licensed to run without being connected to Azure for metering. Les clients doivent activer les conteneurs de communiquer des informations de facturation avec le service de contrôle à tout moment.Customers must enable the containers to communicate billing information with the metering service at all times. Les conteneurs de Services cognitifs n’envoient des données client, telles que l’image ou le texte qui est en cours d’analyse, à Microsoft.Cognitive Services containers don't send customer data, such as the image or text that's being analyzed, to Microsoft.

Étapes suivantesNext steps