Instalar e executar contentores de Extração de Expressões-Chave

Os contentores permitem-lhe alojar a API de Extração de Expressões-Chave na sua própria infraestrutura. Se tiver requisitos de segurança ou governação de dados que não podem ser cumpridos ao chamar remotamente a Extração de Expressões-Chave, os contentores poderão ser uma boa opção.

Nota

• A conta gratuita está limitada a 5000 registos de texto por mês e apenas os escalões de preçoGratuito e Standard são válidos para contentores. Para obter mais informações sobre as taxas de pedidos de transação, veja Limites de dados e serviços.

Os contentores permitem-lhe executar as APIs de Extração de Expressões-Chave no seu próprio ambiente e são ótimos para os seus requisitos específicos de governação de dados e segurança. Os contentores de Extração de Expressões-Chave fornecem processamento avançado de linguagem natural em texto não processado e incluem três funções principais: análise de sentimentos, Extração de Expressões-Chave e deteção de idioma.

Pré-requisitos

• Se não tiver uma subscrição do Azure, crie uma conta gratuita.
• Docker instalado num computador anfitrião. O Docker tem de ser configurado para permitir que os contentores se liguem e enviem dados de faturação para o Azure.
  • No Windows, o Docker também tem de ser configurado para suportar contentores do Linux.
  • Deve ter uma compreensão básica dos conceitos do Docker.
• Um recurso Language com o escalão de preço gratuito (F0) ou standard (S).

Recolher os parâmetros necessários

São necessários três parâmetros principais para todos os contentores dos Serviços Cognitivos. Os Termos de Licenciamento para Software Microsoft têm de estar presentes com um valor de aceitação. Também é necessário um URI de Ponto Final e uma chave de API.

URI do ponto final

O {ENDPOINT_URI} valor está disponível na página descrição geral portal do Azure do recurso dos Serviços Cognitivos correspondente. Aceda à página Descrição geral , paire o cursor sobre o ponto final e é apresentado um ícone Copiar para a área de transferência . Copie e utilize o ponto final sempre que necessário.

Chaves

O {API_KEY} valor é utilizado para iniciar o contentor e está disponível na página Chaves do portal do Azure do recurso dos Serviços Cognitivos correspondente. Aceda à página Chaves e selecione o ícone Copiar para a área de transferência .

Importante

Estas chaves de subscrição são utilizadas para aceder à API dos Serviços Cognitivos. Não partilhe as suas chaves. Armazene-os de forma segura. Por exemplo, utilize o Azure Key Vault. Também recomendamos que volte a gerar estas chaves regularmente. Só é necessária uma chave para fazer uma chamada à API. Quando regenerar a primeira chave, pode utilizar a segunda chave para continuar a aceder ao serviço.

Requisitos e recomendações do computador anfitrião

O anfitrião é um computador baseado em x64 que executa o contentor do Docker. Pode ser um computador no local ou um serviço de alojamento do Docker no Azure, como:

• Azure Kubernetes Service.
• Azure Container Instances.
• Um cluster do Kubernetes implementado no Azure Stack. Para obter mais informações, veja Implementar o Kubernetes no Azure Stack.

A tabela seguinte descreve as especificações mínimas e recomendadas para os contentores de Extração de Expressões-Chave disponíveis. Cada núcleo de CPU tem de ter, pelo menos, 2,6 gigahertz (GHz) ou mais rápido. As Transações Permitidos Por Segundo (TPS) também estão listadas.

	Especificações mínimas do anfitrião	Especificações de anfitrião recomendadas	TPS Mínimo	TPS Máximo
Extração de Expressões-Chave	Memória de 1 núcleo e 2 GB	Memória de 1 núcleo e 4 GB	15	30

O núcleo e a memória da CPU correspondem às --cpus definições e --memory , que são utilizadas como parte do docker run comando .

Obter a imagem de contentor com docker pull

A imagem de contentor de extração de expressões-chave pode ser encontrada no sindicato do mcr.microsoft.com registo de contentor. Reside no azure-cognitive-services/textanalytics/ repositório e chama-se keyphrase. O nome da imagem de contentor completamente qualificado é . mcr.microsoft.com/azure-cognitive-services/textanalytics/keyphrase

Para utilizar a versão mais recente do contentor, pode utilizar a latest etiqueta . Também pode encontrar uma lista completa de etiquetas no MCR.

Utilize o docker pull comando para transferir uma imagem de contentor do Microsoft Container Registry.

docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/keyphrase:latest

Dica

Pode utilizar o comando docker images para listar as imagens de contentor transferidas. Por exemplo, o comando seguinte lista o ID, o repositório e a etiqueta de cada imagem de contentor transferida, formatada como uma tabela:

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

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

Executar o contentor com docker run

Quando o contentor estiver no computador anfitrião, utilize o comando docker run para executar os contentores. O contentor continuará a ser executado até o parar.

Importante

• Os comandos do Docker nas secções seguintes utilizam a barra anterior, \, como caráter de continuação de linha. Substitua ou remova-o com base nos requisitos do sistema operativo anfitrião.
• As Eulaopções , Billinge ApiKey têm de ser especificadas para executar o contentor; caso contrário, o contentor não será iniciado. Para obter mais informações, veja Faturação.
• Os contentores de análise de sentimentos e deteção de idioma utilizam v3 da API e estão geralmente disponíveis. O contentor Extração de Expressões-Chave utiliza v2 da API e está em pré-visualização.

Para executar o contentor Extração de Expressões-Chave , execute o seguinte docker run comando. Substitua os marcadores de posição abaixo pelos seus próprios valores:

Marcador de posição	Valor	Formato ou exemplo
{API_KEY}	A chave para o recurso de Extração de Expressões-Chave. Pode encontrá-lo na página Chave e ponto final do recurso, no portal do Azure.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{ENDPOINT_URI}	O ponto final para aceder à API de Extração de Expressões-Chave. Pode encontrá-lo na página Chave e ponto final do recurso, no portal do Azure.	https://<your-custom-subdomain>.cognitiveservices.azure.com

docker run --rm -it -p 5000:5000 --memory 4g --cpus 1 \
mcr.microsoft.com/azure-cognitive-services/textanalytics/keyphrase \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

Este comando:

• Executa um contentor de Extração de Expressões-Chave a partir da imagem de contentor
• Atribui um núcleo de CPU e 4 gigabytes (GB) de memória
• Expõe a porta TCP 5000 e aloca um pseudo-TTY para o contentor
• Remove automaticamente o contentor depois de sair. A imagem de contentor ainda está disponível no computador anfitrião.

Executar vários contentores no mesmo anfitrião

Se pretender executar vários contentores com portas expostas, certifique-se de que executa cada contentor com uma porta exposta diferente. Por exemplo, execute o primeiro contentor na porta 5000 e o segundo contentor na porta 5001.

Pode ter este contentor e um contentor dos Serviços Cognitivos do Azure diferente em execução no HOST em conjunto. Também pode ter vários contentores do mesmo contentor dos Serviços Cognitivos em execução.

Consultar o ponto final de predição do contentor

O contentor fornece APIs de ponto final de predição de consulta com base em REST.

Utilize o anfitrião, http://localhost:5000, para APIs de contentor.

Validar que um contentor está em execução

Existem várias formas de validar que o contentor está em execução. Localize o endereço IP externo e a porta exposta do contentor em questão e abra o browser favorito. Utilize os vários URLs de pedido que se seguem para validar que o contentor está em execução. Os URLs de pedido de exemplo listados aqui são http://localhost:5000, mas o contentor específico pode variar. Certifique-se de que depende do endereço IP externo do contentor e da porta exposta.

URL do Pedido	Objetivo
http://localhost:5000/	O contentor fornece uma home page.
http://localhost:5000/ready	Pedido com GET, este URL fornece uma verificação de que o contentor está pronto para aceitar uma consulta em relação ao modelo. Este pedido pode ser utilizado para pesquisas de disponibilidade e preparação do Kubernetes.
http://localhost:5000/status	Também solicitado com GET, este URL verifica se a chave de api utilizada para iniciar o contentor é válida sem causar uma consulta de ponto final. Este pedido pode ser utilizado para pesquisas de disponibilidade e preparação do Kubernetes.
http://localhost:5000/swagger	O contentor fornece um conjunto completo de documentação para os pontos finais e uma funcionalidade Experimentar. 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. Após a devolução da consulta, é fornecido um comando CURL de exemplo para demonstrar os cabeçalhos HTTP e o formato do corpo necessários.

Executar o contentor desligado da Internet

Para utilizar este contentor desligado da Internet, primeiro tem de pedir acesso preenchendo uma aplicação e comprando um plano de alocação. Consulte Utilizar contentores do Docker em ambientes desligados para obter mais informações.

Se tiver sido aprovado para executar o contentor desligado da Internet, utilize o exemplo seguinte que mostra a formatação do docker run comando que irá utilizar, com valores de marcador de posição. Substitua estes valores de marcador de posição pelos seus próprios valores.

O DownloadLicense=True parâmetro no comando docker run irá transferir um ficheiro de licença que irá permitir que o contentor do Docker seja executado quando não estiver ligado à Internet. Também contém uma data de expiração, após a qual o ficheiro de licença será inválido para executar o contentor. Só pode utilizar um ficheiro de licença com o contentor adequado para o qual foi aprovado. Por exemplo, não pode utilizar um ficheiro de licença para um contentor de conversão de voz em texto com um contentor de reconhecedor de formulários.

Marcador de posição	Valor	Formatar ou exemplo
{IMAGE}	A imagem de contentor que pretende utilizar.	mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice
{LICENSE_MOUNT}	O caminho onde a licença será transferida e montada.	/host/license:/path/to/license/directory
{ENDPOINT_URI}	O ponto final para autenticar o seu pedido de serviço. Pode encontrá-lo na página Chave e ponto final do recurso, no portal do Azure.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{API_KEY}	A chave para o recurso Análise de Texto. Pode encontrá-lo na página Chave e ponto final do recurso, no portal do Azure.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{CONTAINER_LICENSE_DIRECTORY}	Localização da pasta de licenças no sistema de ficheiros local do contentor.	/path/to/license/directory

docker run --rm -it -p 5000:5000 \ 
-v {LICENSE_MOUNT} \
{IMAGE} \
eula=accept \
billing={ENDPOINT_URI} \
apikey={API_KEY} \
DownloadLicense=True \
Mounts:License={CONTAINER_LICENSE_DIRECTORY} 

Assim que o ficheiro de licença tiver sido transferido, pode executar o contentor num ambiente desligado. O exemplo seguinte mostra a formatação do docker run comando que irá utilizar, com valores de marcador de posição. Substitua estes valores de marcador de posição pelos seus próprios valores.

Onde quer que o contentor seja executado, o ficheiro de licença tem de ser montado no contentor e a localização da pasta de licenças no sistema de ficheiros local do contentor tem de ser especificada com Mounts:License=. Também tem de ser especificada uma montagem de saída para que os registos de utilização da faturação possam ser escritos.

Marcador de posição	Valor	Formatar ou exemplo
{IMAGE}	A imagem de contentor que pretende utilizar.	mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice
{MEMORY_SIZE}	O tamanho adequado da memória a alocar ao contentor.	4g
{NUMBER_CPUS}	O número adequado de CPUs a alocar para o contentor.	4
{LICENSE_MOUNT}	O caminho onde a licença será localizada e montada.	/host/license:/path/to/license/directory
{OUTPUT_PATH}	O caminho de saída para registar registos de utilização.	/host/output:/path/to/output/directory
{CONTAINER_LICENSE_DIRECTORY}	Localização da pasta de licenças no sistema de ficheiros local do contentor.	/path/to/license/directory
{CONTAINER_OUTPUT_DIRECTORY}	Localização da pasta de saída no sistema de ficheiros local do contentor.	/path/to/output/directory

docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \ 
-v {LICENSE_MOUNT} \ 
-v {OUTPUT_PATH} \
{IMAGE} \
eula=accept \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}

Parar o contentor

Para encerrar o contentor, no ambiente da linha de comandos onde o contentor está em execução, selecione Ctrl+C.

Resolução de problemas

Se executar o contentor com uma montagem e registo de saída ativados, o contentor gera ficheiros de registo que são úteis para resolver problemas que ocorrem ao iniciar ou executar o contentor.

Dica

Para obter mais informações e orientações sobre a resolução de problemas, veja Perguntas mais frequentes (FAQ) sobre contentores dos Serviços Cognitivos.

Faturação

Os contentores de Extração de Expressões-Chave enviam informações de faturação para o Azure através de um recurso de Extração de Expressões-Chave na sua conta do Azure.

As consultas ao contentor são faturadas no escalão de preço do recurso do Azure que é utilizado para o ApiKey parâmetro.

Os contentores dos Serviços Cognitivos do Azure não estão licenciados para serem executados sem estarem ligados ao ponto final de medição ou faturação. Tem de ativar os contentores para comunicarem sempre informações de faturação com o ponto final de faturação. Os contentores dos Serviços Cognitivos não enviam dados de clientes, como a imagem ou texto que está a ser analisado, para a Microsoft.

Ligar ao Azure

O contentor precisa que os valores do argumento de faturação são executados. Estes valores permitem que o contentor se ligue ao ponto final de faturação. O contentor comunica a utilização a cada 10 a 15 minutos. Se o contentor não se ligar ao Azure dentro da janela de tempo permitida, o contentor continua a ser executado, mas não serve consultas até que o ponto final de faturação seja restaurado. A ligação é tentada 10 vezes ao mesmo intervalo de tempo de 10 a 15 minutos. Se não conseguir ligar ao ponto final de faturação nas 10 tentativas, o contentor deixa de fornecer pedidos. Veja as FAQ do contentor dos Serviços Cognitivos para obter um exemplo das informações enviadas à Microsoft para faturação.

Argumentos de faturação

O docker run comando iniciará o contentor quando as três opções seguintes forem fornecidas com valores válidos:

Opção	Descrição
ApiKey	A chave de API do recurso dos Serviços Cognitivos que é utilizado para controlar as informações de faturação. O valor desta opção tem de ser definido como uma chave de API para o recurso aprovisionado especificado em Billing.
Billing	O ponto final do recurso dos Serviços Cognitivos que é utilizado para controlar as informações de faturação. O valor desta opção tem de ser definido para o URI do ponto final de um recurso do Azure aprovisionado.
Eula	Indica que aceitou a licença do contentor. O valor desta opção tem de ser definido para aceitar.

\

Resumo

Neste artigo, aprendeu conceitos e fluxos de trabalho para transferir, instalar e executar contentores de Extração de Expressões-Chave. Em resumo:

• A Extração de Expressões-Chave fornece contentores do Linux para o Docker.
• As imagens de contentor são transferidas a partir do Microsoft Container Registry (MCR).
• As imagens de contentor são executadas no Docker.
• Pode utilizar a API REST ou o SDK para chamar operações em contentores de Extração de Expressões-Chave ao especificar o URI do anfitrião do contentor.
• Tem de especificar as informações de faturação ao instanciar um contentor.

Importante

Os contentores dos Serviços Cognitivos não estão licenciados para serem executados sem estarem ligados ao Azure para medição. Os clientes têm de permitir que os contentores comuniquem sempre informações de faturação com o serviço de medição. Os contentores dos Serviços Cognitivos não enviam dados de clientes (por exemplo, texto que está a ser analisado) para a Microsoft.

Passos seguintes

• Veja Configurar contentores para definições de configuração.