Instalar e executar contêineres do Docker para o LUIS

Os contêineres permitem usar o LUIS em seu ambiente. Contêineres são excelentes para especificar requisitos de segurança e governança de dados. Neste artigo, você aprenderá a baixar, instalar e executar um contêiner do LUIS.

O contêiner do LUIS (reconhecimento vocal) carrega seu modelo de Reconhecimento Vocal treinado ou publicado. Do mesmo modo que um aplicativo LUIS, o contêiner do Docker fornece acesso às previsões de consulta de pontos de extremidade da API do contêiner. Você pode coletar logs de consulta do contêiner e carregá-los novamente no aplicativo de Reconhecimento vocal para aumentar a precisão da previsão do aplicativo.

O vídeo a seguir demonstra como usar esse contêiner.

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

Veja os seguintes pré-requisitos para executar o contêiner do LUIS:

• 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 do LUIS com o tipo de preço Gratuito (F0) ou Standard (S).
• Um aplicativo treinado ou publicado empacotado como uma entrada montada no contêiner com a respectiva ID do Aplicativo associada. É possível obter o arquivo empacotado no portal do LUIS ou nas APIs de Criação. Caso esteja obtendo um aplicativo empacotado do LUIS nas APIs de Criação, também será preciso obter uma Chave de Criação.

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 .

ID do Aplicativo {APP_ID}

Essa ID é usada para selecionar o aplicativo. Encontre a ID do aplicativo no portal do LUIS clicando em Gerenciar na parte superior da tela do seu aplicativo e em Configurações.

Chave de criação {AUTHORING_KEY}

Essa chave é usada para obter o aplicativo empacotado do serviço de LUIS na nuvem e carregar os logs de consulta novamente na nuvem. Você precisará da sua chave de criação se exportar seu aplicativo usando a API REST, descrito mais adiante neste artigo.

Obtenha a chave de criação no portal do LUIS clicando em Gerenciar na parte superior da tela do seu aplicativo e em Recursos do Azure.

Criação de APIs para um arquivo de pacote

Criação de APIs para aplicativos empacotados:

• API do pacote publicado
• API do pacote somente treinado e não publicado

O 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.

Recomendações e requisitos do contêiner

A tabela abaixo listará os valores mínimos e recomendados para o host de contêiner. Seus requisitos poderão mudar de acordo com o volume de tráfego.

• Cada núcleo precisa ser de pelo menos 2,6 GHz (gigahertz) ou mais rápido.
• TPS – transações por segundo

Memória e núcleo 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 do LUIS pode ser encontrada na agregação do registro de contêiner mcr.microsoft.com. Ela reside no repositório azure-cognitive-services/language e é chamada luis. O nome da imagem de contêiner totalmente qualificado é mcr.microsoft.com/azure-cognitive-services/language/luis.

Para usar a última versão do contêiner, use a marca latest. Encontre também uma lista completa de marcas no MCR.

Use o comando docker pull para fazer download de uma imagem de contêiner do repositório mcr.microsoft.com/azure-cognitive-services/language/luis:

docker pull mcr.microsoft.com/azure-cognitive-services/language/luis:latest

Para obter uma descrição completa das marcas disponíveis, como as latest usadas no comando anterior, confira LUIS no Hub do Docker.

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

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

Como usar o contêiner

Depois que o contêiner estiver no computador host, use o processo a seguir para trabalhar com o contêiner.

1. Exporte o pacote para o contêiner no portal do LUIS ou nas APIs de LUIS.
2. Mova o arquivo de pacote para o diretório de entrada exigido no computador host. Não renomeie, altere, substitua nem descompacte o arquivo de pacote do LUIS.
3. Execute o contêiner, com a montagem de entrada e as configurações de cobrança necessárias. Há outros exemplos do comando docker run disponíveis.
4. Consultar o ponto de extremidade de previsão do contêiner.
5. Quando você terminar de usar o contêiner importe os logs do ponto de extremidade da montagem de saída no portal do LUIS e pare o contêiner.
6. Use o aprendizado ativo do portal do LUIS na página Examinar declarações do ponto de extremidade para aprimorar o aplicativo.

O aplicativo em execução no contêiner não pode ser alterado. Para alterar o aplicativo no contêiner, será preciso alterá-lo no serviço do LUIS usando o portal do LUIS ou as APIs de Criação do LUIS. Treine e/ou publique e, em seguida, baixe um novo pacote e execute novamente o contêiner.

O aplicativo LUIS dentro do contêiner não pode ser exportado novamente para o serviço de LUIS. Somente os logs de consulta podem ser carregados.

Exportar aplicativo empacotado do LUIS

O contêiner de LUIS requer um aplicativo LUIS treinado ou publicado para responder a consultas de previsão das declarações dos usuários. Para obter o aplicativo LUIS, use a API do pacote publicado ou treinado.

O local padrão é o subdiretório input do local em que você executa o comando docker run.

Coloque o arquivo de pacote em um diretório e faça referência a esse diretório como a montagem de entrada quando você executar o contêiner do Docker.

Tipos de pacote

O diretório de montagem de entrada pode conter modelos de Produção, Preparo e com Controle de Versão do aplicativo de modo simultâneo. Todos os pacotes são montados.

Pré-requisitos de empacotamento

Antes de empacotar um aplicativo LUIS, você deverá ter o seguinte:

Exportar pacote de aplicativo do portal do LUIS

O portal do Azure do LUIS permite exportar o pacote do aplicativo publicado ou treinado.

Exportar o pacote do aplicativo publicado do portal do LUIS

O pacote do aplicativo publicado está disponível na página da lista Meus aplicativos.

1. Entre no novo portal do Azure do LUIS.
2. Marque a caixa de seleção à esquerda do nome do aplicativo na lista.
3. Selecione o item Exportar na barra de ferramentas contextual acima da lista.
4. Selecione Exportar para o contêiner (GZIP).
5. Selecione o ambiente do Slot de produção ou do Slot de preparo.
6. O download do pacote é feito do navegador.

Exportar o pacote do aplicativo com controle de versão do portal do LUIS

O pacote do aplicativo com controle com versão está disponível na página da lista de Versões.

1. Entre no novo portal do Azure do LUIS.
2. Selecione o aplicativo na lista.
3. Selecione Gerenciar na barra de navegação do aplicativo.
4. Selecione Versões na barra de navegação à esquerda.
5. Marque a caixa de seleção à esquerda do nome da versão na lista.
6. Selecione o item Exportar na barra de ferramentas contextual acima da lista.
7. Selecione Exportar para o contêiner (GZIP).
8. O download do pacote é feito do navegador.

Exportar o pacote do aplicativo publicado da API

Use o método de API REST a seguir para empacotar um aplicativo LUIS que você já publicou. Substitua os espaços reservados por seus próprios valores apropriados na chamada à API, usando a tabela abaixo da especificação de HTTP.

GET /luis/api/v2.0/package/{APP_ID}/slot/{SLOT_NAME}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}

Para baixar o pacote publicado, confira a documentação da API clicando aqui. Caso ele seja baixado com êxito, a resposta será um arquivo de pacote do LUIS. Salve o arquivo no local de armazenamento especificado para a montagem de entrada do contêiner.

Exportar o pacote do aplicativo com controle de versão da API

Use o método de API REST a seguir para empacotar um aplicativo LUIS que você já treinou. Substitua os espaços reservados por seus próprios valores apropriados na chamada à API, usando a tabela abaixo da especificação de HTTP.

GET /luis/api/v2.0/package/{APP_ID}/versions/{APP_VERSION}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}

Para baixar o pacote com controle de versão, confira a documentação da API clicando aqui. Caso ele seja baixado com êxito, a resposta será um arquivo de pacote do LUIS. Salve o arquivo no local de armazenamento especificado para a montagem de entrada do contêiner.

Executar o contêiner com docker run

Use o comando docker run para executar o contêiner. Veja Coletar os parâmetros necessários para ver detalhes sobre como obter os valores {ENDPOINT_URI} e {API_KEY}.

Exemplos do comando docker run estão disponíveis.

docker run --rm -it -p 5000:5000 ^
--memory 4g ^
--cpus 2 ^
--mount type=bind,src=c:\input,target=/input ^
--mount type=bind,src=c:\output\,target=/output ^
mcr.microsoft.com/azure-cognitive-services/language/luis ^
Eula=accept ^
Billing={ENDPOINT_URI} ^
ApiKey={API_KEY}

• Este exemplo usa o diretório fora da unidade C: para evitar conflitos de permissão no Windows. Se você precisar usar um diretório específico como o diretório de entrada, talvez seja necessário conceder ao Docker permissão de serviço.
• Não altere a ordem dos argumentos, a menos que esteja familiarizado com contêineres do docker.
• Caso esteja usando um sistema operacional diferente, use o console/terminal, a sintaxe de pasta para executar montagens e o caractere de continuação de linha adequados para seu sistema. Esses exemplos pressupõem que você tem um console do Windows com um caractere de continuação de linha ^. Como o contêiner é um sistema operacional Linux, a montagem de destino usa uma sintaxe de pasta em estilo Linux.

Esse comando:

• Executa um contêiner da imagem de contêiner do LUIS
• Carrega o aplicativo LUIS da montagem de entrada em C:\input, localizado no host de contêiner
• Aloca dois núcleos de CPU e 4 GB (gigabytes) de memória
• Expõe a porta TCP 5000 e aloca um pseudo-TTY para o contêiner
• Salva logs de contêiner e do LUIS na montagem de saída em C:\output, localizado no host de contêiner
• Remove automaticamente o contêiner depois que ele sai. A imagem de contêiner ainda fica disponível no computador host.

Há outros exemplos do comando docker run disponíveis.

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.

APIs de ponto de extremidade compatíveis com o contêiner

As versões V2 e V3 da API estão disponíveis juntamente com o contêiner.

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. Os pontos de extremidade para aplicativos publicados (de preparo ou produção) têm uma rota diferente dos pontos de extremidade para aplicativos com controle de versão.

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

Os parâmetros de consulta configuram como e o que é retornado na resposta da consulta:

Executar uma consulta no aplicativo LUIS

Um exemplo de comando CURL para consultar o contêiner em relação a um aplicativo publicado é:

curl -G \
-d verbose=false \
-d log=true \
--data-urlencode "query=turn the lights on" \
"http://localhost:5000/luis/v3.0/apps/{APP_ID}/slots/production/predict"

curl -G \
-d verbose=false \
-d log=false \
--data-urlencode "query=turn the lights on" \
"http://localhost:5000/luis/v3.0/apps/{APP_ID}/versions/{APP_VERSION}/predict"

curl -X GET \
"http://localhost:5000/luis/v2.0/apps/{APP_ID}?q=turn%20on%20the%20lights&staging=false&timezoneOffset=0&verbose=false&log=true" \
-H "accept: application/json"

curl -X GET \
"http://localhost:5000/luis/v2.0/apps/{APP_ID}/versions/{APP_VERSION}?q=turn%20on%20the%20lights&timezoneOffset=0&verbose=false&log=true" \
-H "accept: application/json"

Importar os logs de ponto de extremidade para aprendizado ativo

Caso uma montagem de saída seja especificada para o contêiner do LUIS, os arquivos de log da consulta do aplicativo serão salvos no diretório de saída em que {INSTANCE_ID} representa a ID do contêiner. O log de consulta do aplicativo contém a consulta, a resposta e os carimbos de data/hora para cada consulta de previsão enviada para o contêiner de LUIS.

O local a seguir mostra a estrutura de diretórios aninhados para os arquivos de log do contêiner.

/output/luis/{INSTANCE_ID}/

No portal do LUIS, selecione seu aplicativo e selecione Importar logs de ponto de extremidade para carregá-los.

Depois que o log é carregado, examine as declarações do ponto de extremidade no portal do LUIS.

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.

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.

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.

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, pressione 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.

Se você estiver tendo problemas para executar um contêiner dos serviços de IA do Azure, tente usar o contêiner de diagnóstico da Microsoft. Use esse contêiner para diagnosticar erros comuns no ambiente de implantação que podem impedir que os contêineres de IA do Azure funcionem conforme o esperado.

Para obter o contêiner, use o seguinte comando docker pull:

docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic

Em seguida, execute o contêiner. Substitua {ENDPOINT_URI} pelo ponto de extremidade e {API_KEY} pela chave do recurso:

docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

O contêiner testará a conectividade de rede com o ponto de extremidade de cobrança.

Cobrança

O contêiner do LUIS envia informações de cobrança ao Azure usando um recurso dos serviços de IA do Azure 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:

Para obter mais informações sobre essas opções, consulte Configurar contêineres.

Resumo

Neste artigo, você aprendeu conceitos e fluxo de trabalho para baixar, instalar e executar os contêineres do Serviço Inteligente de Reconhecimento Vocal (LUIS). Em resumo:

• O Serviço Inteligente de Reconhecimento Vocal (LUIS) oferece um contêiner do Linux para Docker que fornece previsões de declarações de consultas a pontos de extremidade.
• 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 para consultar os pontos de extremidade do contêiner especificando o URI de host do contêiner.
• Você deve especificar informações de faturamento ao instanciar um contêiner.

Próximas etapas

• Revise Configurar contêineres para configurações.
• Confira as limitações de contêiner do LUIS para obter restrições de capacidade conhecidas.
• Consulte a Solução de problemas para resolver problemas relacionados à funcionalidade LUIS.
• Usar mais contêineres de IA do Azure