Instalar e executar contêineres de Extração de Frases-chave

Os contêineres permitem hospedar a API de Extração de Frases-chave em sua própria infraestrutura. Se você tiver requisitos de segurança ou governança de dados que não podem ser atendidos com a chamada de Extração de Frases-chave remota, os contêineres poderão ser uma boa opção.

Observação

• A conta gratuita é limitada a cinco mil registros de texto por mês, e apenas os tipos de preçoGratuito e Standard são válidos para contêineres. Veja mais informações sobre as taxas de solicitação de transação em Limites de dados e serviços.

Contêineres permitem executar APIs de Extração de Frases-chave no seu ambiente e são excelentes para seus requisitos específicos de segurança e governança de dados. Os contêineres da Extração de Frases-chave realizam processamento avançado em idioma natural sobre texto bruto, com três funções principais: análise de sentimento, extração de frases-chave e detecção de idioma.

Pré-requisitos

• Se você não tiver uma assinatura do Azure, crie uma conta gratuita.
• Docker instalado em um computador host. O Docker deve ser configurado para permitir que os contêineres conectem-se e enviem dados de cobrança para o Azure.
  • No Windows, o Docker também deve ser configurado para dar suporte a contêineres do Linux.
  • É preciso ter conhecimentos básicos sobre os conceitos do Docker.
• Um Recurso de linguagem com o tipo de preço Gratuito (F0) ou Standard (S).

Reunir os parâmetros necessários

São necessários três parâmetros principais para todos os contêineres de IA do Azure. O Termos de Licença para Software Microsoft precisam estar presentes com um valor igual a aceito. Um URI do ponto de extremidade e uma chave de API também são necessários.

URI do ponto de extremidade

O valor do {ENDPOINT_URI} está disponível na página Visão geral do portal do Azure do recurso dos serviços de IA do Azure correspondente. Acesse a página Visão geral, posicione o cursor sobre o ponto de extremidade, e um ícone Copiar para a área de transferência será exibido. Copie e use o ponto de extremidade quando necessário.

Teclas

O valor da {API_KEY} é usado para iniciar o contêiner e está disponível na página Chaves do portal do Azure do recurso dos serviços de IA do Azure correspondente. Acesse a página Chaves e selecione o ícone Copiar para a área de transferência.

Importante

Essas chaves de assinatura são usadas para acessar sua API dos serviços de IA do Azure. Não compartilhe suas chaves. Armazene-as com segurança. Por exemplo, use o Azure Key Vault. Também recomendamos que você regenere essas chaves regularmente. Apenas uma chave é necessária para fazer uma chamada à API. Ao regenerar a primeira chave, você pode usar a segunda chave para acesso contínuo ao serviço.

Recomendações e requisitos do computador host

O host é um computador baseado em x64 que executa o contêiner do Docker. Ele pode ser um computador local ou um serviço de hospedagem do Docker no Azure, como:

• Serviço de Kubernetes do Azure.
• Instâncias de Contêiner do Azure.
• Um cluster do Kubernetes implantado no Azure Stack. Para obter mais informações, consulte Implantar Kubernetes no Azure Stack.

A tabela a seguir descreve as especificações mínimas e recomendadas para os contêineres disponíveis de Extração de Frases-chave. Cada núcleo de CPU precisa ser de pelo menos 2,6 GHz (gigahertz) ou mais rápido. A lista também mostra as transações permitidas por seção (TPS).

	Especificações mínimas do host	Especificações recomendadas do host	TPS mínimo	TPS máximo
Extração de Frases-chave	1 núcleo, 2 GB de memória	1 núcleo, 4 GB de memória	15	30

Os núcleos de CPU e a memória correspondem às configurações --cpus e --memory, que são usadas como parte do comando docker run.

Obter a imagem de contêiner com docker pull

A imagem de contêiner da extração de frases-chave pode ser encontrada na agregação de registro de contêiner mcr.microsoft.com. Ela reside no repositório azure-cognitive-services/textanalytics/ e é chamada keyphrase. O nome da imagem de contêiner totalmente qualificado é mcr.microsoft.com/azure-cognitive-services/textanalytics/keyphrase.

Para usar a versão mais recente do contêiner, você pode usar a tag latest. Encontre também uma lista completa de marcas no MCR.

Use o comando docker pull para baixar uma imagem de contêiner do Microsoft Container Registry.

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

Dica

Você pode usar o comando imagens do estivador para listar as imagens do contêiner transferidas por download. Por exemplo, o comando a seguir lista o ID, o repositório e a tag de cada imagem do contêiner transferida por download, 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 contêiner com docker run

Quando o contêiner está no computador host, use o comando docker run para executar os contêineres. O contêiner continua a ser executado até que você o pare.

Importante

• os comandos do Docker nas seções a seguir usam a barra invertida, \, como um caractere de continuação de linha. Substitua ou remova essa barra com base nos requisitos do sistema operacional de seu computador host.
• As opções Eula, Billing e ApiKey devem ser especificadas para executar o contêiner; caso contrário, o contêiner não será iniciado. Para mais informações, consulte Faturamento.
• Os contêineres de análise de sentimento e de detecção de idioma usam a v3 da API e estão em disponibilidade geral. O contêiner de Extração de Frases-chave usa a v2 da API e está em versão prévia.

Para executar o contêiner e Extração de Frases-chave, execute o comando a seguir docker run. Substitua os espaços reservados abaixo por seus próprios valores:

Espaço reservado	Valor	Formato ou exemplo
{API_KEY}	A chave para o recurso de Extração de Frases-chave. É possível encontrá-lo na página de Chave e ponto de extremidade do recurso, no portal do Azure.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{ENDPOINT_URI}	O ponto de extremidade para acessar a API de Extração de Frases-chave. É possível encontrá-lo na página de Chave e ponto de extremidade 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}

Esse comando:

• Executa um contêiner de Extração de Frases-chave na imagem de contêiner
• Aloca 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 contêiner
• Remove automaticamente o contêiner depois que ele sai. A imagem de contêiner ainda fica disponível no computador host.

Executar vários contêineres no mesmo host

Se você pretende executar vários contêineres com portas expostas, execute cada um deles com uma porta exposta diferente. Por exemplo, execute o primeiro contêiner na porta 5000 e o segundo contêiner na porta 5001.

É possível ter esse contêiner e um contêiner dos serviços de IA do Azure em execução no HOST juntos. Também é possível ter vários contêineres do mesmo contêiner dos serviços de IA do Azure em execução.

Consultar o ponto de extremidade de previsão do contêiner

O contêiner fornece APIs de ponto de extremidade de previsão de consulta baseadas em REST.

Use o host, http://localhost:5000, para as APIs do contêiner.

Validar se um contêiner está em execução

Há várias maneiras de validar se um contêiner está em execução. Localize o endereço IP externo e a porta exposta do contêiner em questão e abra seu navegador da Web favorito. Use as várias URLs de solicitação a seguir para validar se o contêiner está em execução. Os exemplos de URLs de solicitação listados aqui são http://localhost:5000, mas seu contêiner específico poderá variar. Dependa do endereço IP externo do seu contêiner e da porta exposta.

URL de Solicitação	Finalidade
http://localhost:5000/	O contêiner fornece uma home page.
http://localhost:5000/ready	Solicitada com GET, essa URL fornece uma verificação que indica que o contêiner está pronto para aceitar uma consulta no modelo. Essa solicitação pode ser usada para testes de preparação e de execução do Kubernetes.
http://localhost:5000/status	Também solicitada com GET, essa URL verifica se a chave API usada para iniciar o contêiner é válida sem causar uma consulta de ponto de extremidade. Essa solicitação pode ser usada para testes de preparação e de execução do Kubernetes.
http://localhost:5000/swagger	O contêiner fornece um conjunto completo de documentação para os pontos de extremidade e um recurso Experimentar. Com esse recurso, é possível inserir suas configurações em um formulário HTML baseado na Web e realizar a consulta sem precisar escrever nenhum código. Após a consulta ser retornada, um exemplo de comando CURL será fornecido para demonstrar o formato do corpo e dos cabeçalhos HTTP exigidos.

Executar o contêiner desconectado da Internet

Para usar esse contêiner desconectado da internet, primeiro você deve solicitar acesso preenchendo um aplicativo e comprando um plano de compromisso. Confira Usar contêineres do Docker em ambientes desconectados para obter mais informações.

Se você foi aprovado para executar o contêiner desconectado da internet, usar o exemplo a seguir mostra a formatação do comando docker run que você usará, com valores de espaço reservado. Substitua os valores do espaço reservado pelos seus.

O parâmetro DownloadLicense=True no comando docker run fará o download de um arquivo de licença que permitirá que o contêiner do Docker seja executado quando não estiver conectado à Internet. Ele também contém uma data de validade, após a qual o arquivo de licença será inválido para executar o contêiner. Você só pode usar um arquivo de licença com o contêiner apropriado para o qual foi aprovado. Por exemplo, não é possível usar um arquivo de licença para um contêiner de conversão de fala em texto com um contêiner de Informação de Documentos.

Espaço reservado	Valor	Formato ou exemplo
{IMAGE}	A imagem de contêiner que você deseja usar.	mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice
{LICENSE_MOUNT}	O caminho em que a licença será baixada e montada.	/host/license:/path/to/license/directory
{ENDPOINT_URI}	O ponto de extremidade para autenticação da sua solicitação de serviço. É possível encontrá-lo na página de Chave e ponto de extremidade do recurso, no portal do Azure.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{API_KEY}	A chave para o recurso de Análise de Texto. É possível encontrá-lo na página de Chave e ponto de extremidade do recurso, no portal do Azure.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{CONTAINER_LICENSE_DIRECTORY}	Local da pasta de licença no sistema de arquivos local do contêiner.	/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} 

Depois que o arquivo de licença tiver sido baixado, você poderá executar o contêiner em um ambiente desconectado. O exemplo a seguir mostra a formatação do comando docker run que você usará, com os valores de espaço reservado. Substitua os valores do espaço reservado pelos seus.

Sempre que o contêiner é executado, o arquivo de licença precisa ser montado no contêiner e a localização da pasta de licença no sistema de arquivos local do contêiner precisa ser especificada com Mounts:License=. Uma montagem de saída também precisa ser especificada para que os registros de uso de cobrança possam ser gravados.

Espaço reservado	Valor	Formato ou exemplo
{IMAGE}	A imagem de contêiner que você deseja usar.	mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice
{MEMORY_SIZE}	O tamanho apropriado da memória a ser alocada para o contêiner.	4g
{NUMBER_CPUS}	O número apropriado de CPUs a serem alocadas para o contêiner.	4
{LICENSE_MOUNT}	O caminho em que a licença estará localizada e será montada.	/host/license:/path/to/license/directory
{OUTPUT_PATH}	O caminho de saída para registrar em log os registros de uso.	/host/output:/path/to/output/directory
{CONTAINER_LICENSE_DIRECTORY}	Local da pasta de licença no sistema de arquivos local do contêiner.	/path/to/license/directory
{CONTAINER_OUTPUT_DIRECTORY}	Local da pasta de saída no sistema de arquivos local do contêiner.	/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 contêiner

Para desligar o contêiner, no ambiente de linha de comando em que o contêiner estiver em execução, selecione Ctrl+C.

Solução de problemas

Se você executar o contêiner com uma montagem de saída e o registro em log habilitado, o contêiner gerará arquivos de log que são úteis para solucionar problemas que ocorrem durante a inicialização ou execução do contêiner.

Dica

Para obter mais informações e orientações sobre solução de problemas, veja Perguntas frequentes (FAQ) sobre contêineres do IA do Azure.

Cobrança

Os contêineres de Extração de Frases-chave enviam informações de cobrança para o Azure, usando um recurso de Extração de Frases-chave em sua conta do Azure.

Consultas ao contêiner são cobradas pelo tipo de preço do recurso do Azure usado para o parâmetro ApiKey.

Os contêineres dos serviços de IA do Azure não estão licenciados para execução sem estarem conectados ao ponto de extremidade de medição ou cobrança. Você precisa permitir que os contêineres comuniquem as informações de cobrança com o ponto de extremidade de cobrança em todos os momentos. Os contêineres dos serviços de IA do Azure não enviam dados do cliente, como imagem ou texto que está sendo analisado, para a Microsoft.

Conectar-se ao Azure

O contêiner precisa dos valores de argumento de cobrança para ser executado. Esses valores permitem que o contêiner se conecte ao ponto de extremidade de cobrança. O contêiner relata o uso a cada 10 a 15 minutos. Se o contêiner não se conectar ao Azure dentro da janela de tempo permitida, ele continuará sendo executado, mas não atenderá a consultas até que o ponto de extremidade de cobrança seja restaurado. Serão realizadas 10 tentativas de conexão no mesmo intervalo de tempo de 10 a 15 minutos. Se não for possível conectar-se ao ponto de extremidade de cobrança dentro das 10 tentativas, o contêiner interromperá as solicitações de serviço. Veja as Perguntas frequentes sobre contêineres dos serviços de IA do Azure para obter um exemplo das informações enviadas à Microsoft para cobrança.

Argumentos de cobrança

O comando docker run iniciará o contêiner quando todas as três opções a seguir forem fornecidas com valores válidos:

Opção	Descrição
ApiKey	A chave de API do recurso dos serviços de IA do Azure usado para rastrear informações de cobrança. O valor dessa opção deve ser definido como uma chave de API para o recurso provisionado especificado em Billing.
Billing	O ponto de extremidade do recurso dos serviços de IA do Azure usado para rastrear informações de cobrança. O valor dessa opção deve ser definido como o URI do ponto de extremidade de um recurso do Azure provisionado.
Eula	Indica que você aceitou a licença do contêiner. O valor dessa opção deve ser definido como aceitar.

\

Resumo

Neste artigo, você aprendeu conceitos e fluxo de trabalho para baixar, instalar e executar os contêineres de Extração de Frases-chave. Em resumo:

• A Extração de Frases-chave fornece contêineres do Linux para o Docker.
• Imagens de contêiner são baixadas do Registro de Contêiner da Microsoft (MCR).
• Imagens de contêiner são executadas no Docker.
• Você pode usar a API REST ou o SDK para chamar as operações em contêineres de Extração de Frases-chave especificando o URI do host do contêiner.
• Você deve especificar informações de faturamento ao instanciar um contêiner.

Importante

Os contêineres dos serviços de IA do Azure não estão licenciados para serem executados sem uma conexão ao Azure para medição. Os clientes precisam ativar os contêineres para comunicar informações de cobrança com o serviço de medição em todos os momentos. Os contêineres de IA do Azure não enviam dados do cliente (por exemplo, o texto que está sendo analisado) para a Microsoft.

Próximas etapas

• Confira Configurar contêineres para definições de configuração.