Installare ed eseguire i contenitori di visoInstall and run Face containers

Azure viso di servizi cognitivi fornisce un contenitore Linux standardizzato per Docker che rileva i visi umani nelle immagini.Azure Cognitive Services Face provides a standardized Linux container for Docker that detects human faces in images. Vengono inoltre identificati attributi, che includono riquadri, ad esempio oblique e gli occhi, sesso, età e altre caratteristiche del viso stimato macchina.It also identifies attributes, which include face landmarks such as noses and eyes, gender, age, and other machine-predicted facial features. Oltre a rilevamento viso possibile verificare se due visi nella stessa immagine o immagini diverse sono uguali utilizzando un punteggio di confidenza.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. Viso può anche confrontare visi in un database per vedere se esiste già un viso simili o identico.Face also can compare faces against a database to see if a similar-looking or identical face already exists. Anche possibile organizzare i visi simili in gruppi tramite condiviso traits visual.It also can organize similar faces into groups by using shared visual traits.

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.If you don't have an Azure subscription, create a free account before you begin.

PrerequisitiPrerequisites

È necessario soddisfare i prerequisiti seguenti prima di usare i contenitori l'API viso.You must meet the following prerequisites before you use the Face API containers.

ObbligatoriaRequired ScopoPurpose
Motore DockerDocker Engine Il motore Docker deve essere installato in un computer host.The Docker Engine must be installed on a host computer. Docker offre pacchetti per la configurazione dell'ambiente Docker in macOS, Windows e Linux.Docker provides packages that configure the Docker environment on macOS, Windows, and Linux. Per una panoramica dei concetti fondamentali relativi a Docker e ai contenitori, vedere Docker overview (Panoramica di Docker).For a primer on Docker and container basics, see the Docker overview.

Docker deve essere configurato per consentire ai contenitori di connettersi ai dati di fatturazione e inviarli ad Azure.Docker must be configured to allow the containers to connect with and send billing data to Azure.

In Windows, Docker anche deve essere configurato per supportare i contenitori Linux.On Windows, Docker also must be configured to support Linux containers.

Familiarità con DockerFamiliarity with Docker È necessario una conoscenza di base dei concetti relativi a Docker, ad esempio i registri, gli archivi, i contenitori e immagini del contenitore.You need a basic understanding of Docker concepts, such as registries, repositories, containers, and container images. È anche necessario conoscere basic docker comandi.You also need knowledge of basic docker commands.
Azure Cognitive Services risorsaAzure Cognitive Services resource Per usare il contenitore, è necessario disporre di:To use the container, you must have:

Una risorsa di servizi cognitivi di Azure e la chiave di fatturazione associata e l'URI dell'endpoint fatturazione.An Azure Cognitive Services resource and the associated billing key and the billing endpoint URI. Entrambi i valori sono disponibili sul Overview e chiavi pagine per la risorsa.Both values are available on the Overview and Keys pages for the resource. Sono richieste per avviare il contenitore.They're required to start the container. Aggiungere il face/v1.0 routing per l'URI dell'endpoint, come illustrato nell'esempio BILLING_ENDPOINT_URI seguente:Add the face/v1.0 routing to the endpoint URI, as shown in the following BILLING_ENDPOINT_URI example:

{BILLING_KEY} : chiave della risorsa{BILLING_KEY}: resource key

{BILLING_ENDPOINT_URI} : esempio di URI dell'endpoint è 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

Richiedere l'accesso al registro contenitori privatoRequest access to the private container registry

Compilare e inviare il modulo di richiesta di contenitori visione servizi cognitivi per richiedere l'accesso al contenitore.Fill out and submit the Cognitive Services Vision Containers Request form to request access to the container. Il modulo richiede informazioni sull'utente, sull'azienda e sullo scenario utente per cui si userà il contenitore.The form requests information about you, your company, and the user scenario for which you'll use the container. Dopo aver inviato il form, il team di servizi cognitivi di Azure esamina per assicurarsi che siano soddisfatti i criteri di accesso al registro contenitori privato.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

È necessario usare un indirizzo di posta elettronica associato con un Account Microsoft (MSA) o un account di Azure Active Directory (Azure AD) nel form.You must use an email address associated with either a Microsoft Account (MSA) or an Azure Active Directory (Azure AD) account in the form.

Se la richiesta viene approvata, si riceverà un messaggio di posta elettronica con istruzioni che descrivono come ottenere le credenziali e accedere al registro contenitori privato.If your request is approved, you receive an email with instructions that describe how to obtain your credentials and access the private container registry.

Accedere al registro contenitori privatoLog in to the private container registry

Esistono diversi modi per eseguire l'autenticazione con registro contenitori privato per i contenitori di servizi cognitivi.There are several ways to authenticate with the private container registry for Cognitive Services containers. È consigliabile usare il metodo della riga di comando usando il CLI di Docker.We recommend that you use the command-line method by using the Docker CLI.

Usare la accesso a docker comando, come illustrato nell'esempio seguente, per accedere a containerpreview.azurecr.io, che è il registro contenitori privato per i contenitori di servizi cognitivi.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. Sostituire <username> con il nome utente e <password> con la password specificata nelle credenziali ricevute dal team di Servizi cognitivi di Azure.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>

Se si è protetto le credenziali in un file di testo, è possibile concatenare il contenuto del file di testo per il docker login comando.If you secured your credentials in a text file, you can concatenate the contents of that text file to the docker login command. Usare il cat comando, come illustrato nell'esempio seguente.Use the cat command, as shown in the following example. Sostituire <passwordFile> con il percorso e nome del file di testo che contiene la password.Replace <passwordFile> with the path and name of the text file that contains the password. Sostituire <username> con il nome utente fornito le credenziali.Replace <username> with the user name provided in your credentials.

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

Computer hostThe host computer

L'host è un computer basato su x64 che esegue il contenitore Docker.The host is a x64-based computer that runs the Docker container. Può essere un computer dell'ambiente locale o un servizio di hosting Docker in Azure, tra cui:It can be a computer on your premises or a Docker hosting service in Azure, such as:

Indicazioni e requisiti per i contenitoriContainer requirements and recommendations

La tabella seguente indica il valore minimo e consigliato per CPU e memoria da allocare per ogni contenitore di API Viso.The following table describes the minimum and recommended CPU cores and memory to allocate for each Face API container.

ContenitoreContainer MinimaMinimum ConsigliatoRecommended Transazioni al secondoTransactions per second
(Minimo, massimo)(Minimum, maximum)
VisoFace 1 core, 2 GB di memoria1 core, 2-GB memory 1 core, 4 GB di memoria1 core, 4-GB memory 10, 2010, 20
  • Ciascun core deve essere almeno a 2,6 GHz o superiore.Each core must be at least 2.6 GHz or faster.
  • Transazioni al secondo (TPS).Transactions per second (TPS).

Core e memoria corrispondono alle impostazioni --cpus e --memory che vengono usate come 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.

Ottenere l'immagine del contenitore con il pull di dockerGet the container image with docker pull

Sono disponibili immagini del contenitore per l'API viso.Container images for the Face API are available.

ContenitoreContainer RepositoryRepository
VisoFace containerpreview.azurecr.io/microsoft/cognitive-services-face:latest

Suggerimento

È possibile usare il comando docker images per visualizzare l'elenco delle immagini dei contenitori scaricate.You can use the docker images command to list your downloaded container images. Ad esempio, il comando seguente visualizza l'ID, il repository e il tag di ogni immagine del contenitore scaricata, in formato tabella: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

Docker pull per il contenitore di VisoDocker pull for the Face container

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

Usare il contenitoreUse the container

Dopo aver creato il contenitore nel computer host, utilizzare la seguente procedura per lavorare con il contenitore.After the container is on the host computer, use the following process to work with the container.

  1. Eseguire il contenitore con le necessarie impostazioni di fatturazione.Run the container with the required billing settings. Sono disponibili altri esempi del comando docker run.More examples of the docker run command are available.
  2. Eseguire le query sull'endpoint di stima del contenitore.Query the container's prediction endpoint.

Eseguire il contenitore con docker runRun the container with docker run

Usare il comando docker run per eseguire uno qualsiasi dei tre contenitori.Use the docker run command to run any of the three containers. Il comando Usa i parametri seguenti.The command uses the following parameters.

PlaceholderPlaceholder ValueValue
{BILLING_KEY}{BILLING_KEY} Questa chiave viene usata per avviare il contenitore e sono disponibile in Azure Cognitive Services chiavi pagina.This key is used to start the container and is available on the Azure Cognitive Services Keys page.
{BILLING_ENDPOINT_URI}{BILLING_ENDPOINT_URI} Il valore URI dell'endpoint di fatturazione è disponibile in Azure Cognitive Services Cenni preliminari su pagina.The billing endpoint URI value is available on the Azure Cognitive Services Overview page. Un esempio è https://westus.api.cognitive.microsoft.com/face/v1.0.An example is https://westus.api.cognitive.microsoft.com/face/v1.0.

Aggiungere il face/v1.0 routing per l'URI dell'endpoint, come illustrato nell'esempio BILLING_ENDPOINT_URI precedente.Add the face/v1.0 routing to the endpoint URI, as shown in the preceding BILLING_ENDPOINT_URI example.

Sostituire questi parametri con valori personalizzati nel seguente docker run comando di esempio: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}

Questo comando:This command:

  • Esegue un contenitore di visi dall'immagine del contenitore.Runs a face container from the container image.
  • Consente di allocare un core CPU e 4 GB di memoria.Allocates one CPU core and 4 GB of memory.
  • Espone la porta TCP 5000 e alloca una pseudo TTY per il contenitore.Exposes TCP port 5000 and allocates a pseudo TTY for the container.
  • Rimuove automaticamente il contenitore dopo la chiusura.Automatically removes the container after it exits. L'immagine del contenitore rimane disponibile nel computer host.The container image is still available on the host computer.

Sono disponibili altri esempi del comando docker run.More examples of the docker run command are available.

Importante

Il Eula, Billing, e ApiKey opzioni devono essere specificate per l'esecuzione del contenitore o non si avvia il contenitore.The Eula, Billing, and ApiKey options must be specified to run the container or the container won't start. Per altre informazioni, vedereFatturazione.For more information, see Billing.

Eseguire più contenitori nello stesso hostRun multiple containers on the same host

Se si intende eseguire più contenitori con porte esposte, assicurarsi di eseguire ogni contenitore con una porta esposta diversa.If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. Eseguire ad esempio il primo contenitore sulla porta 5000 e il secondo sulla porta 5001.For example, run the first container on port 5000 and the second container on port 5001.

Questo contenitore e un contenitore di Servizi cognitivi diverso sono in esecuzione contemporaneamente sull'HOST.You can have this container and a different Azure Cognitive Services container running on the HOST together. Sono inoltre in esecuzione più contenitori dello stesso contenitore di Servizi cognitivi.You also can have multiple containers of the same Cognitive Services container running.

Eseguire query sull'endpoint di stima del contenitoreQuery the container's prediction endpoint

Il contenitore fornisce API dell'endpoint di stima di query basate su REST.The container provides REST-based query prediction endpoint APIs.

Usare l'host, https://localhost:5000, per le API del contenitore.Use the host, https://localhost:5000, for container APIs.

Verificare che il contenitore sia in esecuzioneValidate that a container is running

Per verificare se il contenitore è in esecuzione, sono disponibili diverse opzioni.There are several ways to validate that the container is running.

RichiestaRequest ScopoPurpose
http://localhost:5000/ Il contenitore fornisce una home page.The container provides a home page.
http://localhost:5000/status Viene effettuata una richiesta con GET, per verificare che il contenitore sia in esecuzione senza generare una query dell'endpoint.Requested with GET, to validate that the container is running without causing an endpoint query. Questa richiesta può essere usata per i probe di attività e di idoneità di Kubernetes.This request can be used for Kubernetes liveness and readiness probes.
http://localhost:5000/swagger Il contenitore fornisce una serie completa di documentazione per gli endpoint, oltre a una funzionalità Try it now.The container provides a full set of documentation for the endpoints and a Try it now feature. Con questa funzionalità, è possibile immettere le impostazioni in un modulo HTML basato sul Web ed eseguire la query senza scrivere codice.With this feature, you can enter your settings into a web-based HTML form and make the query without having to write any code. Dopo che la query restituisce il risultato, viene fornito un comando CURL di esempio per illustrare il formato richiesto per il corpo e le intestazioni HTTP.After the query returns, an example CURL command is provided to demonstrate the HTTP headers and body format that's required.

Home page del contenitore

Arrestare il contenitoreStop the container

Per arrestare il contenitore, nell'ambiente della riga di comando in cui è in esecuzione il contenitore premere CTRL+C.To shut down the container, in the command-line environment where the container is running, select Ctrl+C.

risoluzione dei problemiTroubleshooting

Se si esegue il contenitore con un output montare e la registrazione è abilitata, il contenitore genera file di log che sono utili per risolvere i problemi che si verificano durante l'avvio o esegue il contenitore.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.

FatturazioneBilling

I contenitori di viso inviare le informazioni di fatturazione in Azure usando una risorsa API viso nell'account Azure.The Face API containers send billing information to Azure by using a Face API resource on your Azure account.

Le query sul contenitore vengono fatturate secondo il piano tariffario della risorsa di Azure usata per <ApiKey>.Queries to the container are billed at the pricing tier of the Azure resource that's used for the <ApiKey>.

I contenitori di Servizi cognitivi di Azure non vengono concessi in licenza per l'esecuzione senza connessione all'endpoint di fatturazione per la misurazione.Azure Cognitive Services containers aren't licensed to run without being connected to the billing endpoint for metering. È necessario consentire ai contenitori di comunicare sempre le informazioni di fatturazione all'endpoint di fatturazione.You must enable the containers to communicate billing information with the billing endpoint at all times. I contenitori di Servizi cognitivi non inviano a Microsoft i dati dei clienti, ad esempio l'immagine o il testo analizzato.Cognitive Services containers don't send customer data, such as the image or text that's being analyzed, to Microsoft.

Connect to AzureConnect to Azure

Per eseguire il contenitore, sono necessari i valori dell'argomento di fatturazione.The container needs the billing argument values to run. Questi valori consentono al contenitore di connettersi all'endpoint di fatturazione.These values allow the container to connect to the billing endpoint. Il contenitore segnala l'utilizzo ogni 10-15 minuti.The container reports usage about every 10 to 15 minutes. Se il contenitore non si connette ad Azure entro la finestra temporale consentita, continuerà a essere eseguito ma non fornirà query finché l'endpoint di fatturazione non verrà ripristinato.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. Il tentativo di connessione viene effettuato 10 volte nello stesso intervallo di tempo di 10-15 minuti.The connection is attempted 10 times at the same time interval of 10 to 15 minutes. Se non è possibile stabilire la connessione con l'endpoint di fatturazione entro i 10 tentativi, l'esecuzione del contenitore verrà arrestata.If it can't connect to the billing endpoint within the 10 tries, the container stops running.

Argomenti di fatturazioneBilling arguments

Per avviare il contenitore con il comando docker run, è necessario che vengano specificate tutte e tre le opzioni seguenti con valori validi:For the docker run command to start the container, all three of the following options must be specified with valid values:

OpzioneOption DESCRIZIONEDescription
ApiKey Chiave API della risorsa di Servizi cognitivi usata per tenere traccia delle informazioni di fatturazione.The API key of the Cognitive Services resource that's used to track billing information.
Il valore di questa opzione deve essere impostato su una chiave API per la risorsa di cui è stato effettuato il provisioning specificata in Billing.The value of this option must be set to an API key for the provisioned resource that's specified in Billing.
Billing Endpoint della risorsa di Servizi cognitivi usata per tenere traccia delle informazioni di fatturazione.The endpoint of the Cognitive Services resource that's used to track billing information.
Il valore di questa opzione deve essere impostato sull'URI dell'endpoint di una risorsa di Azure di cui è stato effettuato il provisioning.The value of this option must be set to the endpoint URI of a provisioned Azure resource.
Eula Indica che è la licenza per il contenitore è stata accettata.Indicates that you accepted the license for the container.
Il valore di questa opzione deve essere impostato su accept.The value of this option must be set to accept.

Per altre informazioni su queste opzioni, vedere Configurare i contenitori.For more information about these options, see Configure containers.

Post di BLOGBlog posts

Esempi per gli sviluppatoriDeveloper samples

Gli esempi per gli sviluppatori sono disponibili nel repository GitHub.Developer samples are available at our GitHub repository.

Visualizza il webinarView webinar

Partecipare al webinar per saperne di più sugli argomenti seguenti:Join the webinar to learn about:

  • Come distribuire Servizi cognitivi in qualsiasi computer con DockerHow to deploy Cognitive Services to any machine using Docker
  • Come distribuire Servizi cognitivi nel servizio Azure ContainerHow to deploy Cognitive Services to AKS

RiepilogoSummary

In questo articolo si è appreso i concetti e flusso di lavoro per la procedura scaricare, installare ed eseguire i contenitori l'API viso.In this article, you learned concepts and workflow for how to download, install, and run Face API containers. In sintesi:In summary:

  • L'API viso fornisce tre contenitori di Linux per Docker che forniscono l'estrazione di frasi chiave, il rilevamento della lingua e l'analisi del sentiment.The Face API provides three Linux containers for Docker that provide key phrase extraction, language detection, and sentiment analysis.
  • Le immagini del contenitore vengono scaricate dal registro contenitori di Azure.Container images are downloaded from the Azure Container Registry.
  • Le immagini dei contenitori vengono eseguite in Docker.Container images run in Docker.
  • È possibile utilizzare l'API REST o SDK di chiamare le operazioni nei contenitori di viso specificando l'URI del contenitore di host.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.
  • Quando si crea un'istanza di un contenitore, è necessario specificare le informazioni di fatturazione.You must specify billing information when you instantiate a container.

Importante

I contenitori di servizi cognitivi non sono concessi in licenza per l'esecuzione senza connettersi ad Azure per il controllo.Cognitive Services containers aren't licensed to run without being connected to Azure for metering. I clienti è necessario abilitare i contenitori di comunicare le informazioni di fatturazione con il servizio di controllo in qualsiasi momento.Customers must enable the containers to communicate billing information with the metering service at all times. I contenitori di Servizi cognitivi non inviano a Microsoft i dati dei clienti, ad esempio l'immagine o il testo analizzato.Cognitive Services containers don't send customer data, such as the image or text that's being analyzed, to Microsoft.

Passaggi successiviNext steps