Installare ed eseguire i contenitori di Analisi del testoInstall and run Text Analytics containers

Nota

  • Il contenitore per Analisi del sentiment e il rilevamento della lingua sono ora disponibili a livello generale.The container for Sentiment Analysis and language detection are now Generally Available. Il contenitore estrazione frasi chiave è disponibile come anteprima pubblica non gestita.The key phrase extraction container is available as an ungated public preview.
  • Il collegamento di entità e NER non sono attualmente disponibili come contenitore.Entity linking and NER are not currently available as a container.
  • Per accedere alla Analisi del testo per il contenitore di integrità è necessario un modulo di richiesta.Accessing the Text Analytics for health container requires a request form. Attualmente, non verrà addebitato l'utilizzo.Currently, you will not be billed for its usage.
  • I percorsi delle immagini del contenitore potrebbero essere stati modificati di recente.The container image locations may have recently changed. Leggere questo articolo per visualizzare il percorso aggiornato per questo contenitore.Read this article to see the updated location for this container.

I contenitori consentono di eseguire le API di analisi del testo nell'ambiente in uso e sono perfette per i requisiti di sicurezza e governance dei dati specifici.Containers enable you to run the Text Analytic APIs in your own environment and are great for your specific security and data governance requirements. I contenitori di Analisi del testo forniscono l'elaborazione avanzata in linguaggio naturale su testo non elaborato e includono tre funzioni principali: analisi dei sentimenti, estrazione di frasi chiave e rilevamento della lingua.The Text Analytics containers provide advanced natural language processing over raw text, and include three main functions: sentiment analysis, key phrase extraction, and language detection.

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.

Importante

L'account gratuito è limitato a 5.000 transazioni al mese e solo i piani tariffari gratuiti e standard sono validi per i contenitori.The free account is limited to 5,000 transactions per month and only the Free and Standard pricing tiers are valid for containers. Per ulteriori informazioni sulle frequenze delle richieste di transazioni, vedere limiti dei dati.For more information on transaction request rates, see Data Limits.

PrerequisitiPrerequisites

Per eseguire uno dei contenitori di Analisi del testo, è necessario disporre degli ambienti host e del computer host.To run any of the Text Analytics containers, you must have the host computer and container environments.

PreparazionePreparation

Per usare i contenitori di Analisi del testo, è necessario soddisfare i prerequisiti seguenti:You must meet the following prerequisites before using Text Analytics containers:

NecessarioRequired ScopoPurpose
Motore DockerDocker Engine È necessario il motore Docker installato in un computer host.You need the Docker Engine 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 deve essere configurato anche per supportare i contenitori Linux.On Windows, Docker must also be configured to support Linux containers.

Familiarità con DockerFamiliarity with Docker È opportuno avere una conoscenza di base dei concetti relativi a Docker, tra cui registri, repository, contenitori e immagini dei contenitori, nonché dei comandi docker di base.You should have a basic understanding of Docker concepts, like registries, repositories, containers, and container images, as well as knowledge of basic docker commands.
Risorsa Analisi del testoText Analytics resource Per usare il contenitore, è necessario disporre di:In order to use the container, you must have:

Una risorsa analisi del testo di Azure con il piano tariffariogratuito (F0) o standard (S).An Azure Text Analytics resource with the free (F0) or standard (S) pricing tier. È necessario ottenere la chiave API e l'URI dell'endpoint associati passando alla pagina chiave ed endpoint della risorsa nel portale di Azure.You will need to get the associated API key and endpoint URI by navigating to your resource's Key and endpoint page in the Azure portal.

{API_KEY}: una delle due chiavi di risorsa disponibili.{API_KEY}: One of the two available resource keys.

{ENDPOINT_URI}: l'endpoint per la risorsa.{ENDPOINT_URI}: The endpoint for your resource.

Raccolta dei parametri obbligatoriGathering required parameters

Sono disponibili tre parametri primari per tutti i contenitori di servizi cognitivi richiesti.There are three primary parameters for all Cognitive Services' containers that are required. Il contratto di licenza con l'utente finale deve essere presente con un valore pari a accept .The end-user license agreement (EULA) must be present with a value of accept. Sono inoltre necessari un URL dell'endpoint e una chiave API.Additionally, both an Endpoint URL and API Key are needed.

URI dell'endpoint {ENDPOINT_URI}Endpoint URI {ENDPOINT_URI}

Il valore dell'URI dell' endpoint è disponibile nella pagina Panoramica portale di Azure della risorsa del servizio cognitiva corrispondente.The Endpoint URI value is available on the Azure portal Overview page of the corresponding Cognitive Service resource. Passare alla pagina Panoramica , posizionare il puntatore del mouse sull'endpoint e Copy to clipboard verrà visualizzata un'icona.Navigate to the Overview page, hover over the Endpoint, and a Copy to clipboard icon will appear. Copiare e usare se necessario.Copy and use where needed.

Raccogliere l'URI dell'endpoint per un uso successivo

Chiavi {API_KEY}Keys {API_KEY}

Questa chiave viene usata per avviare il contenitore ed è disponibile nella pagina chiavi del portale di Azure della risorsa del servizio cognitiva corrispondente.This key is used to start the container, and is available on the Azure portal's Keys page of the corresponding Cognitive Service resource. Passare alla pagina chiavi e fare clic sull' Copy to clipboard icona.Navigate to the Keys page, and click on the Copy to clipboard icon.

Ottenere una delle due chiavi per un uso successivo

Importante

Queste chiavi di sottoscrizione vengono usate per accedere all'API di Servizi cognitivi.These subscription keys are used to access your Cognitive Service API. Non condividerle.Do not share your keys. Archiviarli in modo sicuro, ad esempio usando Azure Key Vault.Store them securely, for example, using Azure Key Vault. È inoltre consigliabile rigenerare queste chiavi regolarmente.We also recommend regenerating these keys regularly. Per effettuare una chiamata API è necessaria una sola chiave.Only one key is necessary to make an API call. Quando si rigenera la prima chiave, è possibile usare la seconda chiave per l'accesso continuato al servizio.When regenerating the first key, you can use the second key for continued access to the service.

Se si usa il Analisi del testo per il contenitore di integrità, il riconoscimento responsabile di intelligenza artificiale (Rai) deve essere presente anche con un valore di accept .If you're using the Text Analytics for health container, the responsible AI (RAI) acknowledgment must also be present with a value of accept.

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

Nella tabella seguente vengono descritte le specifiche minime e consigliate per i contenitori di Analisi del testo.The following table describes the minimum and recommended specifications for the Text Analytics containers. Sono necessari almeno 2 gigabyte (GB) di memoria e ogni core CPU deve essere almeno 2,6 gigahertz (GHz) o superiore.At least 2 gigabytes (GB) of memory are required, and each CPU core must be at least 2.6 gigahertz (GHz) or faster. Sono elencate anche le transazioni consentite per sezione (TPS).The allowable Transactions Per Section (TPS) are also listed.

Specifiche host minimeMinimum host specs Specifiche host consigliateRecommended host specs Numero minimo di transazioniMinimum TPS Numero massimo di transazioniMaximum TPS
Rilevamento della lingua, estrazione di frasi chiaveLanguage detection, key phrase extraction 1 core, 2 GB di memoria1 core, 2GB memory 1 core, 4 GB di memoria1 core, 4GB memory 1515 3030
Analisi del sentimentSentiment Analysis 1 core, 2 GB di memoria1 core, 2GB memory 4 core, 8 GB di memoria4 cores, 8GB memory 1515 3030
Analisi del testo per l'integrità-1 documento/richiestaText Analytics for health - 1 document/request 4 core, 10 GB di memoria4 core, 10GB memory 6 core, memoria 12 GB6 core, 12GB memory 1515 3030
Analisi del testo per l'integrità-10 documenti/richiestaText Analytics for health - 10 documents/request 6 core, 16GB di memoria6 core, 16GB memory 8 core, memoria 20 GB8 core, 20GB memory 1515 3030

Core CPU e memoria corrispondono alle --cpus Impostazioni e --memory , che vengono usate come parte del docker run comando.CPU 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 docker pullGet the container image with docker pull

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
<image-id>       <repository-path/name>    <tag-name>

Le immagini del contenitore per Analisi del testo sono disponibili in Microsoft Container Registry.Container images for Text Analytics are available on the Microsoft Container Registry.

Pull Docker per il contenitore Analisi del sentiment V3Docker pull for the Sentiment Analysis v3 container

Il contenitore dell'analisi dei sentimenti V3 è disponibile in diverse lingue.The sentiment analysis container v3 container is available in several languages. Per scaricare il contenitore per il contenitore inglese, usare il comando seguente.To download the container for the English container, use the command below.

docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/sentiment:3.0-en

Per scaricare il contenitore per un'altra lingua, sostituire en con uno dei codici di lingua indicati di seguito.To download the container for another language, replace en with one of the language codes below.

Contenitore di Analisi del testoText Analytics Container Codice linguaLanguage code
IngleseEnglish en
SpagnoloSpanish es
FranceseFrench fr
ItalianoItalian it
TedescoGerman de
Cinese semplificatoChinese - simplified zh
Cinese tradizionaleChinese - traditional zht
GiapponeseJapanese ja
PortoghesePortuguese pt
OlandeseDutch nl

Per una descrizione completa dei tag disponibili per i contenitori di Analisi del testo, vedere Hub Docker.For a full description of available tags for the Text Analytics containers, see Docker Hub.

Come usare il contenitoreHow to use the container

Dopo aver aggiunto il contenitore nel computer host, seguire questa procedura per usare il contenitore.Once the container is on the host computer, use the following process to work with the container.

  1. Eseguire il contenitore, con le impostazioni di fatturazione necessarie.Run the container, with the required billing settings.
  2. Eseguire una 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 i contenitori.Use the docker run command to run the containers. Il contenitore continuerà a essere eseguito fino a quando non lo si arresta.The container will continue to run until you stop it.

Importante

  • I comandi di Docker nelle sezioni seguenti usano la barra rovesciata, \, come carattere di continuazione di riga.The docker commands in the following sections use the back slash, \, as a line continuation character. Sostituirla o rimuoverla in base ai requisiti del sistema operativo host.Replace or remove this based on your host operating system's requirements.
  • È necessario specificare le opzioni Eula, Billing e ApiKey per eseguire il contenitore. In caso contrario, il contenitore non si avvia.The Eula, Billing, and ApiKey options must be specified to run the container; otherwise, the container won't start. Per altre informazioni, vedereFatturazione.For more information, see Billing.
  • I contenitori analisi dei sentimenti e rilevamento della lingua sono disponibili a livello generale.The sentiment analysis and language detection containers are generally available. Il contenitore estrazione frasi chiave USA V2 dell'API ed è in anteprima.The key phrase extraction container uses v2 of the API, and is in preview.

Per eseguire il contenitore analisi del sentiment V3 , eseguire il docker run comando seguente.To run the Sentiment Analysis v3 container, execute the following docker run command. Sostituire i segnaposto seguenti con valori personalizzati:Replace the placeholders below with your own values:

SegnapostoPlaceholder ValoreValue Formato o esempioFormat or example
{API_KEY}{API_KEY} Chiave per la risorsa Analisi del testo.The key for your Text Analytics resource. È possibile trovarlo nella pagina chiave ed endpoint della risorsa, nella portale di Azure.You can find it on your resource's Key and endpoint page, on the Azure portal. xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{ENDPOINT_URI}{ENDPOINT_URI} Endpoint per l'accesso alla API Analisi del testo.The endpoint for accessing the Text Analytics API. È possibile trovarlo nella pagina chiave ed endpoint della risorsa, nella portale di Azure.You can find it on your resource's Key and endpoint page, on the Azure portal. https://<your-custom-subdomain>.cognitiveservices.azure.com
docker run --rm -it -p 5000:5000 --memory 8g --cpus 1 \
mcr.microsoft.com/azure-cognitive-services/textanalytics/sentiment \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

Questo comando:This command:

  • Esegue un analisi del sentiment contenitore dall'immagine del contenitoreRuns a Sentiment Analysis container from the container image
  • Alloca un core CPU e 8 GB di memoriaAllocates one CPU core and 8 gigabytes (GB) of memory
  • Espone la porta TCP 5000 e alloca un pseudo terminale TTY per il contenitoreExposes 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.

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 una query sull'endpoint di stima del contenitoreQuery the container's prediction endpoint

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

Usare l'host http://localhost:5000 per le API del contenitore.Use the host, http://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. Individuare l'indirizzo IP esterno e la porta esposta del contenitore in questione e aprire il Web browser preferito.Locate the External IP address and exposed port of the container in question, and open your favorite web browser. Usare i vari URL di richiesta indicati di seguito per verificare che il contenitore sia in esecuzione.Use the various request URLs below to validate the container is running. Gli URL di richiesta di esempio elencati http://localhost:5000 di seguito sono, ma il contenitore specifico può variare.The example request URLs listed below are http://localhost:5000, but your specific container may vary. Tenere presente che si sta per fare affidamento sull'indirizzo IP esterno del contenitore e sulla porta esposta.Keep in mind that you're to rely on your container's External IP address and exposed port.

URL della richiestaRequest URL ScopoPurpose
http://localhost:5000/ Il contenitore fornisce un home page.The container provides a home page.
http://localhost:5000/ready Richiesto con GET, in questo modo viene verificata la disponibilità del contenitore per l'accettazione di una query sul modello.Requested with GET, this provides a verification that the container is ready to accept a query against the model. 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/status Richiesto anche con GET, verifica se la chiave API usata per avviare il contenitore è valida senza causare una query dell'endpoint.Also requested with GET, this verifies if the api-key used to start the container is valid 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 un set completo di documentazione per gli endpoint e una funzionalità Prova.The container provides a full set of documentation for the endpoints and a Try it out 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 punto di montaggio di output e la registrazione attivata, il contenitore genera file di log utili per risolvere i problemi che si verificano durante l'avvio o l'esecuzione del contenitore.If you run the container with an output mount and logging enabled, the container generates log files that are helpful to troubleshoot issues that happen while starting or running the container.

Suggerimento

Per ulteriori informazioni e indicazioni sulla risoluzione dei problemi, vedere la pagina relativa alle domande frequenti sui contenitori di servizi cognitivi.For more troubleshooting information and guidance, see Cognitive Services containers frequently asked questions (FAQ).

FatturazioneBilling

I contenitori Analisi del testo inviano le informazioni di fatturazione ad Azure usando una risorsa di Analisi del testo nell'account di Azure.The Text Analytics containers send billing information to Azure, using a Text Analytics 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 sono concessi in licenza per l'esecuzione senza essere connessi all'endpoint di misurazione/fatturazione.Azure Cognitive Services containers aren't licensed to run without being connected to the metering / billing endpoint. È 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.

Connettersi ad 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 connettersi all'endpoint di fatturazione entro 10 tentativi, il contenitore smette di soddisfare le richieste.If it can't connect to the billing endpoint within the 10 tries, the container stops serving requests. Per un esempio delle informazioni inviate a Microsoft per la fatturazione, vedere domande frequenti sul contenitore di servizi cognitivi .See the Cognitive Services container FAQ for an example of the information sent to Microsoft for billing.

Argomenti di fatturazioneBilling arguments

docker run Il comando avvierà il contenitore quando tutte e tre le opzioni seguenti vengono fornite con valori validi:The docker run command will start the container when all three of the following options are provided 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.

RiepilogoSummary

In questo articolo sono stati descritti i concetti e il flusso di lavoro per scaricare, installare ed eseguire i contenitori di Analisi del testo.In this article, you learned concepts and workflow for downloading, installing, and running Text Analytics containers. In sintesi:In summary:

  • Analisi del testo offre tre contenitori Linux per Docker, incapsulando varie funzionalità:Text Analytics provides three Linux containers for Docker, encapsulating various capabilities:
    • Analisi del sentimentSentiment Analysis
    • Estrazione frasi chiave (anteprima)Key Phrase Extraction (preview)
    • Rilevamento linguaLanguage Detection
    • Analisi del testo per la sanità (anteprima)Text Analytics for health (preview)
  • Le immagini del contenitore vengono scaricate dal repository del contenitore Microsoft Container Registry (o di anteprima).Container images are downloaded from the Microsoft Container Registry (MCR) or preview container repository.
  • Le immagini dei contenitori vengono eseguite in Docker.Container images run in Docker.
  • È possibile usare l'API REST o l'SDK per chiamare le operazioni nei contenitori di Analisi del testo specificando l'URI host del contenitore.You can use either the REST API or SDK to call operations in Text Analytics 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 instantiating a container.

Importante

I contenitori di Servizi cognitivi non sono concessi in licenza per l'esecuzione senza essere connessi ad Azure per la misurazione.Cognitive Services containers are not licensed to run without being connected to Azure for metering. I clienti devono consentire ai contenitori di comunicare sempre le informazioni di fatturazione al servizio di misurazione.Customers need to enable the containers to communicate billing information with the metering service at all times. I contenitori di servizi cognitivi non inviano i dati dei clienti (ad esempio, il testo analizzato) a Microsoft.Cognitive Services containers do not send customer data (e.g. text that is being analyzed) to Microsoft.

Passaggi successiviNext steps