Instalar e executar contentores da Análise de TextoInstall and run Text Analytics containers

Nota

  • O recipiente para Análise de Sentimento v3 está agora geralmente disponível.The container for Sentiment Analysis v3 is now Generally Available. Os contentores de deteção de idioma e extração de expressões-chave estão disponíveis como uma pré-visualização pública livre.The key phrase extraction and language detection containers are available as an ungated public preview.
  • A ligação da entidade e o NER não estão atualmente disponíveis como recipiente.Entity linking and NER are not currently available as a container.
  • O acesso ao Texto Analytics para recipiente de saúde requer um formulário de pedido.Accessing the Text Analytics for health container requires a request form. Atualmente, não será cobrado pelo seu uso.Currently, you will not be billed for its usage.
  • As localizações de imagem do contentor podem ter mudado recentemente.The container image locations may have recently changed. Leia este artigo para ver a localização atualizada deste recipiente.Read this article to see the updated location for this container.

Os contentores permitem-lhe executar as APIs de Análise de Texto no seu próprio ambiente e são ótimos para os requisitos específicos de governação de dados e segurança.Containers enable you to run the Text Analytic APIs in your own environment and are great for your specific security and data governance requirements. Os recipientes Text Analytics fornecem processamento avançado da linguagem natural sobre o texto cru, e incluem três funções principais: análise de sentimento, extração de frases-chave e deteção de linguagem.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 não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.If you don't have an Azure subscription, create a free account before you begin.

Importante

A conta gratuita está limitada a 5.000 transações por mês e apenas os níveis de preços Gratuitos e Standard são válidos para contentores.The free account is limited to 5,000 transactions per month and only the Free and Standard pricing tiers are valid for containers. Para obter mais informações sobre as taxas de pedido de transação, consulte Limites de Dados.For more information on transaction request rates, see Data Limits.

Pré-requisitosPrerequisites

Para executar qualquer um dos recipientes text Analytics, você deve ter os ambientes do computador e do recipiente hospedeiro.To run any of the Text Analytics containers, you must have the host computer and container environments.

PreparaçãoPreparation

Deve encontrar os seguintes pré-requisitos antes de utilizar os recipientes text Analytics:You must meet the following prerequisites before using Text Analytics containers:

NecessárioRequired ObjetivoPurpose
Motor do DockerDocker Engine Precisa do Motor Docker instalado num computador anfitrião.You need the Docker Engine installed on a host computer. O Docker oferece pacotes que configuram o ambiente do Docker no macOS, no Windows e no Linux.Docker provides packages that configure the Docker environment on macOS, Windows, and Linux. Para um manual de noções básicas do Docker e do contentor, veja a descrição geral do Docker.For a primer on Docker and container basics, see the Docker overview.

O Docker deve ser configurado para permitir que os contentores se conectem e enviem dados de faturação para a Azure.Docker must be configured to allow the containers to connect with and send billing data to Azure.

No Windows, o Docker também deve ser configurado para suportar recipientes Linux.On Windows, Docker must also be configured to support Linux containers.

Familiaridade com DockerFamiliarity with Docker Você deve ter uma compreensão básica de conceitos docker, como registos, repositórios, contentores e imagens de contentores, bem como conhecimento de docker comandos básicos.You should have a basic understanding of Docker concepts, like registries, repositories, containers, and container images, as well as knowledge of basic docker commands.
Recurso de análise de textoText Analytics resource Para utilizar o recipiente, deve ter:In order to use the container, you must have:

Um recurso Azure Text Analytics para obter a chave API associada e ponto final URI.An Azure Text Analytics resource to get the associated API key and endpoint URI. Ambos os valores estão disponíveis nas páginas de Análise de Texto e Chaves do portal Azure e são obrigados a iniciar o contentor.Both values are available on the Azure portal's Text Analytics Overview and Keys pages and are required to start the container.

{API_KEY}: Uma das duas teclas de recursos disponíveis na página Keys{API_KEY}: One of the two available resource keys on the Keys page

{ENDPOINT_URI}: O ponto final, conforme fornecido na página 'Vista Geral',{ENDPOINT_URI}: The endpoint as provided on the Overview page

Recolha de parâmetros necessáriosGathering required parameters

Existem três parâmetros primários para todos os contentores dos Serviços Cognitivos que são necessários.There are three primary parameters for all Cognitive Services' containers that are required. O contrato de licença de utilizador final (EULA) deve estar presente com um valor de accept .The end-user license agreement (EULA) must be present with a value of accept. Além disso, tanto um URL endpoint como uma chave API são necessários.Additionally, both an Endpoint URL and API Key are needed.

Endpoint URI {ENDPOINT_URI}Endpoint URI {ENDPOINT_URI}

O valor Endpoint URI está disponível na página geral do portal Azure do recurso correspondente do Serviço Cognitivo.The Endpoint URI value is available on the Azure portal Overview page of the corresponding Cognitive Service resource. Navegue para a página overview, paire sobre o Ponto final e aparecerá um Copy to clipboard ícone.Navigate to the Overview page, hover over the Endpoint, and a Copy to clipboard icon will appear. Copiar e usar sempre que necessário.Copy and use where needed.

Reúna o ponto final uri para utilização posterior

Chaves {API_KEY}Keys {API_KEY}

Esta chave é utilizada para iniciar o contentor e está disponível na página Chaves do portal Azure do recurso serviço cognitivo correspondente.This key is used to start the container, and is available on the Azure portal's Keys page of the corresponding Cognitive Service resource. Navegue na página Chaves e clique no Copy to clipboard ícone.Navigate to the Keys page, and click on the Copy to clipboard icon.

Pegue uma das duas chaves para uso posterior

Importante

Estas chaves de subscrição são usadas para aceder à sua API de Serviço Cognitivo.These subscription keys are used to access your Cognitive Service API. Não partilhem as chaves.Do not share your keys. Guarde-os de forma segura, por exemplo, utilizando o Cofre da Chave Azure.Store them securely, for example, using Azure Key Vault. Recomendamos também a regeneração regular destas teclas.We also recommend regenerating these keys regularly. Apenas uma chave é necessária para fazer uma chamada da API.Only one key is necessary to make an API call. Ao regenerar a primeira chave, pode utilizar a segunda chave para o acesso continuado ao serviço.When regenerating the first key, you can use the second key for continued access to the service.

O computador anfitriãoThe host computer

O hospedeiro é um computador baseado em X64 que gere o contentor Docker.The host is a x64-based computer that runs the Docker container. Pode ser um computador nas suas instalações ou um serviço de hospedagem Docker em Azure, tais como:It can be a computer on your premises or a Docker hosting service in Azure, such as:

Requisitos e recomendações do contentorContainer requirements and recommendations

O quadro a seguir descreve as especificações mínimas e recomendadas para os recipientes Text Analytics.The following table describes the minimum and recommended specifications for the Text Analytics containers. São necessários pelo menos 2 gigabytes (GB) de memória, e cada núcleo de CPU deve ser de pelo menos 2,6 gigahertz (GHz) ou mais rápido.At least 2 gigabytes (GB) of memory are required, and each CPU core must be at least 2.6 gigahertz (GHz) or faster. As transações admissíveis por secção (TPS) também estão listadas.The allowable Transactions Per Section (TPS) are also listed.

Especificações mínimas de anfitriãoMinimum host specs Especificações recomendadas do anfitriãoRecommended host specs TPS mínimosMinimum TPS TPS máximoMaximum TPS
Deteção de linguagem, extração de frases-chaveLanguage detection, key phrase extraction 1 núcleo, 2GB de memória1 core, 2GB memory 1 núcleo, 4GB de memória1 core, 4GB memory 1515 3030
Análise de Sentimento v3Sentiment Analysis v3 1 núcleo, 2GB de memória1 core, 2GB memory 4 núcleos, memória de 8GB4 cores, 8GB memory 1515 3030
Análise de texto para a saúde - 1 documento/pedidoText Analytics for health - 1 document/request 4 núcleo, memória de 10GB4 core, 10GB memory 6 núcleo, 12GB de memória6 core, 12GB memory 1515 3030
Análise de texto para saúde - 10 documentos/pedidoText Analytics for health - 10 documents/request 6 núcleo, 16GB de memória6 core, 16GB memory 8 núcleo, 20GB de memória8 core, 20GB memory 1515 3030

O núcleo e a memória do CPU correspondem às --cpus --memory definições e configurações, que são utilizadas como parte do docker run comando.CPU core and memory correspond to the --cpus and --memory settings, which are used as part of the docker run command.

Obtenha a imagem do recipiente com docker pullGet the container image with docker pull

Dica

Pode utilizar o comando de imagens estivadores para listar as imagens do seu contentor descarregado.You can use the docker images command to list your downloaded container images. Por exemplo, o seguinte comando lista o ID, repositório e etiqueta de cada imagem de recipiente descarregado, formatado como tabela: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>

As imagens do contentor para Análise de Texto estão disponíveis no Registo do Contentor da Microsoft.Container images for Text Analytics are available on the Microsoft Container Registry.

Docker puxa para o recipiente de Análise de Sentimento v3Docker pull for the Sentiment Analysis v3 container

O recipiente de análise de sentimento v3 está disponível em várias línguas.The sentiment analysis container v3 container is available in several languages. Para descarregar o recipiente para o recipiente inglês, utilize o comando abaixo.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

Para descarregar o recipiente para outro idioma, en substitua-o por um dos códigos linguísticos abaixo.To download the container for another language, replace en with one of the language codes below.

Recipiente de análise de textoText Analytics Container Código do idiomaLanguage code
InglêsEnglish en
EspanholSpanish es
FrancêsFrench fr
ItalianoItalian it
AlemãoGerman de
Chinês - simplificadoChinese - simplified zh
Chinês - tradicionalChinese - traditional zht
JaponêsJapanese ja
PortuguêsPortuguese pt
NeerlandêsDutch nl

Para obter uma descrição completa das etiquetas disponíveis para os recipientes Text Analytics, consulte Docker Hub.For a full description of available tags for the Text Analytics containers, see Docker Hub.

Como usar o recipienteHow to use the container

Uma vez que o recipiente esteja no computador anfitrião,utilize o seguinte processo para trabalhar com o recipiente.Once the container is on the host computer, use the following process to work with the container.

  1. Executar o recipiente,com as definições de faturação necessárias.Run the container, with the required billing settings.
  2. Consultar o ponto final de previsão do recipiente.Query the container's prediction endpoint.

Executar o recipiente com docker runRun the container with docker run

Use o comando de execução do estivador para executar os contentores.Use the docker run command to run the containers. O contentor continuará a funcionar até o parar.The container will continue to run until you stop it.

Importante

  • Os comandos do estivador nas seguintes secções usam o corte \ traseiro, como um personagem de continuação de linha.The docker commands in the following sections use the back slash, \, as a line continuation character. Substitua ou remova isto com base nos requisitos do seu sistema operativo anfitrião.Replace or remove this based on your host operating system's requirements.
  • As Eula Billing opções , e ApiKey opções devem ser especificadas para executar o recipiente; caso contrário, o recipiente não arranca.The Eula, Billing, and ApiKey options must be specified to run the container; otherwise, the container won't start. Para mais informações, consulte Billing.For more information, see Billing.
  • O contentor v3 de análise de sentimento está agora geralmente disponível, que devolve rótulos de sentimento na resposta.The sentiment analysis v3 container is now generally available, which returns sentiment labels in the response. Os recipientes de extração de frases-chave e de deteção de linguagem utilizam v2 da API e estão em pré-visualização.The key phrase extraction and language detection containers use v2 of the API, and are in preview.

Para executar o recipiente Análise de Sentimento v3, execute o seguinte docker run comando.To run the Sentiment Analysis v3 container, execute the following docker run command. Substitua os espaços reservados abaixo pelos seus próprios valores:Replace the placeholders below with your own values:

Marcador de posiçãoPlaceholder ValorValue Formato ou exemploFormat or example
{API_KEY}{API_KEY} A chave para o seu recurso Text Analytics.The key for your Text Analytics resource. Pode encontrá-lo na página chave e ponta final do seu recurso, no portal Azure.You can find it on your resource's Key and endpoint page, on the Azure portal. xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{ENDPOINT_URI}{ENDPOINT_URI} O ponto final para aceder à API de Análise de Texto.The endpoint for accessing the Text Analytics API. Pode encontrá-lo na página chave e ponta final do seu recurso, no portal 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}

Este comando:This command:

  • Executa um recipiente de Análise de Sentimento a partir da imagem do recipienteRuns a Sentiment Analysis container from the container image
  • Atribui um núcleo de CPU e 8 gigabytes (GB) de memóriaAllocates one CPU core and 8 gigabytes (GB) of memory
  • Expõe a porta TCP 5000 e atribui uma pseudo-TTY para o contentorExposes TCP port 5000 and allocates a pseudo-TTY for the container
  • Remove automaticamente o recipiente depois de sair.Automatically removes the container after it exits. A imagem do recipiente ainda está disponível no computador anfitrião.The container image is still available on the host computer.

Executar vários recipientes no mesmo hospedeiroRun multiple containers on the same host

Se pretender executar vários recipientes com portas expostas, certifique-se de que funciona cada recipiente com uma porta exposta diferente.If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. Por exemplo, executar o primeiro contentor no porto 5000 e o segundo contentor no porto 5001.For example, run the first container on port 5000 and the second container on port 5001.

Você pode ter este recipiente e um recipiente diferente Azure Cognitive Services funcionando no HOST juntos.You can have this container and a different Azure Cognitive Services container running on the HOST together. Também pode ter vários contentores do mesmo recipiente dos Serviços Cognitivos em funcionamento.You also can have multiple containers of the same Cognitive Services container running.

Consultar o ponto final de predição do contentorQuery the container's prediction endpoint

O contentor fornece APIs de ponto final de predição de consulta com base em REST.The container provides REST-based query prediction endpoint APIs.

Utilize o anfitrião, http://localhost:5000, para APIs de contentor.Use the host, http://localhost:5000, for container APIs.

Validar que um contentor está a funcionarValidate that a container is running

Há várias formas de validar que o contentor está a funcionar.There are several ways to validate that the container is running. Localize o endereço IP externo e a porta exposta do recipiente em questão e abra o seu navegador web favorito.Locate the External IP address and exposed port of the container in question, and open your favorite web browser. Utilize os urls de vários pedidos abaixo para validar o recipiente em funcionamento.Use the various request URLs below to validate the container is running. O exemplo de pedido URLs listados abaixo são http://localhost:5000 , mas o seu recipiente específico pode variar.The example request URLs listed below are http://localhost:5000, but your specific container may vary. Tenha em mente que deve confiar no endereço IP externo do seu contentor e na porta exposta.Keep in mind that you're to rely on your container's External IP address and exposed port.

URL do PedidoRequest URL ObjetivoPurpose
http://localhost:5000/ O contentor fornece uma home page.The container provides a home page.
http://localhost:5000/ready Solicitado com GET, isto fornece uma verificação de que o recipiente está pronto para aceitar uma consulta contra o modelo.Requested with GET, this provides a verification that the container is ready to accept a query against the model. Este pedido pode ser utilizado para sondas kubernetes de prontidão e prontidão.This request can be used for Kubernetes liveness and readiness probes.
http://localhost:5000/status Também solicitado com GET, isto verifica se a chave api utilizada para iniciar o contentor é válida sem causar uma consulta de ponto final.Also requested with GET, this verifies if the api-key used to start the container is valid without causing an endpoint query. Este pedido pode ser utilizado para sondas kubernetes de prontidão e prontidão.This request can be used for Kubernetes liveness and readiness probes.
http://localhost:5000/swagger O contentor fornece um conjunto completo de documentação para os pontos finais e uma funcionalidade Experimentar.The container provides a full set of documentation for the endpoints and a Try it out feature. Com esta funcionalidade, pode introduzir as suas definições num formulário HTML baseado na Web e fazer a consulta sem ter de escrever qualquer 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. Após o retorno da consulta, é fornecido um comando CURL de exemplo para demonstrar os cabeçalhos HTTP e o formato corporal que é necessário.After the query returns, an example CURL command is provided to demonstrate the HTTP headers and body format that's required.

Página inicial do contentor

Parar o contentorStop the container

Para desligar o recipiente, no ambiente da linha de comando onde o recipiente está em funcionamento, selecione Ctrl+C.To shut down the container, in the command-line environment where the container is running, select Ctrl+C.

Resolução de problemasTroubleshooting

Se executar o recipiente com um suporte de saída e um registo ativado, o recipiente gera ficheiros de registo que são úteis para resolver problemas que ocorrem durante o arranque ou execução do recipiente.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.

Dica

Para obter mais informações e orientações sobre resolução de problemas, consulte os recipientes dos Serviços Cognitivos frequentemente questionados (FAQ).For more troubleshooting information and guidance, see Cognitive Services containers frequently asked questions (FAQ).

FaturaçãoBilling

Os recipientes Text Analytics enviam informações de faturação para o Azure, utilizando um recurso Text Analytics na sua conta Azure.The Text Analytics containers send billing information to Azure, using a Text Analytics resource on your Azure account.

As consultas ao contentor são cobradas no nível de preços do recurso Azure que é usado para ApiKey .Queries to the container are billed at the pricing tier of the Azure resource that's used for the ApiKey.

Os recipientes Azure Cognitive Services não estão licenciados para funcionar sem estarem ligados ao ponto final de medição/faturação.Azure Cognitive Services containers aren't licensed to run without being connected to the metering / billing endpoint. Deve permitir que os recipientes comuniquem sempre informações de faturação com o ponto final de faturação.You must enable the containers to communicate billing information with the billing endpoint at all times. Os contentores dos Serviços Cognitivos não enviam dados dos clientes, como a imagem ou texto que está a ser analisado, para a Microsoft.Cognitive Services containers don't send customer data, such as the image or text that's being analyzed, to Microsoft.

Ligar ao AzureConnect to Azure

O contentor precisa que os valores do argumento da faturação corram.The container needs the billing argument values to run. Estes valores permitem que o recipiente se conecte ao ponto final de faturação.These values allow the container to connect to the billing endpoint. O recipiente relata o uso a cada 10 a 15 minutos.The container reports usage about every 10 to 15 minutes. Se o recipiente não ligar ao Azure dentro da janela de tempo permitida, o recipiente continua a funcionar, mas não serve consultas até que o ponto final de faturação seja restaurado.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. A ligação é tentada 10 vezes ao mesmo tempo de 10 a 15 minutos.The connection is attempted 10 times at the same time interval of 10 to 15 minutes. Se não conseguir ligar-se ao ponto final de faturação dentro dos 10 tentativas, o recipiente deixa de servir os pedidos.If it can't connect to the billing endpoint within the 10 tries, the container stops serving requests.

Argumentos de faturaçãoBilling arguments

docker run O comando iniciará o contentor quando as três opções seguintes forem fornecidas com valores válidos:The docker run command will start the container when all three of the following options are provided with valid values:

OpçãoOption DescriçãoDescription
ApiKey A chave API do recurso Serviços Cognitivos que é usado para rastrear informações de faturação.The API key of the Cognitive Services resource that's used to track billing information.
O valor desta opção deve ser definido como uma chave API para o recurso provisionado especificado em Billing .The value of this option must be set to an API key for the provisioned resource that's specified in Billing.
Billing O ponto final do recurso dos Serviços Cognitivos que é usado para rastrear a informação de faturação.The endpoint of the Cognitive Services resource that's used to track billing information.
O valor desta opção deve ser definido como uri ponto final de um recurso Azure provisionado.The value of this option must be set to the endpoint URI of a provisioned Azure resource.
Eula Indica que aceitou a licença para o contentor.Indicates that you accepted the license for the container.
O valor desta opção deve ser definido para ser aceite.The value of this option must be set to accept.

Para obter mais informações sobre estas opções, consulte os recipientes Configure.For more information about these options, see Configure containers.

Publicações no blogueBlog posts

Exemplos de programadorDeveloper samples

As amostras de desenvolvedores estão disponíveis no nosso repositório GitHub.Developer samples are available at our GitHub repository.

Ver webinarView webinar

Junte-se ao webinar para saber:Join the webinar to learn about:

  • Como implantar serviços cognitivos em qualquer máquina que use DockerHow to deploy Cognitive Services to any machine using Docker
  • Como implantar serviços cognitivos na AKSHow to deploy Cognitive Services to AKS

ResumoSummary

Neste artigo, aprendeu conceitos e fluxo de trabalho para descarregar, instalar e executar recipientes de Text Analytics.In this article, you learned concepts and workflow for downloading, installing, and running Text Analytics containers. Em resumo:In summary:

  • A Text Analytics fornece três recipientes Linux para Docker, encapsulando várias capacidades:Text Analytics provides three Linux containers for Docker, encapsulating various capabilities:
    • Análise de SentimentosSentiment Analysis
    • Extração de frases-chave (pré-visualização)Key Phrase Extraction (preview)
    • Deteção de Idiomas (pré-visualização)Language Detection (preview)
    • Análise de Texto para Saúde (pré-visualização)Text Analytics for Health (preview)
  • As imagens do contentor são descarregadas a partir do Registo de Contentores da Microsoft (MCR) ou do repositório de contentores de pré-visualização.Container images are downloaded from the Microsoft Container Registry (MCR) or preview container repository.
  • Imagens de contentores correm em Docker.Container images run in Docker.
  • Pode utilizar a API REST ou a SDK para ligar para operações em recipientes Text Analytics especificando o hospedeiro URI do recipiente.You can use either the REST API or SDK to call operations in Text Analytics containers by specifying the host URI of the container.
  • Deve especificar as informações de faturação ao instantaneamente um recipiente.You must specify billing information when instantiating a container.

Importante

Os recipientes dos Serviços Cognitivos não estão licenciados para funcionar sem estarem ligados ao Azure para a medição.Cognitive Services containers are not licensed to run without being connected to Azure for metering. Os clientes precisam de permitir que os contentores comuniquem informações de faturação com o serviço de medição em todos os momentos.Customers need to enable the containers to communicate billing information with the metering service at all times. Os recipientes de Serviços Cognitivos não enviam dados do cliente (por exemplo, texto que está a ser analisado) para a Microsoft.Cognitive Services containers do not send customer data (e.g. text that is being analyzed) to Microsoft.

Passos seguintesNext steps