Instalar contêineres de OCR de Leitura do Docker

Observação

A partir de 22 de setembro de 2020, a maioria dos contêineres restritos é hospedada no Microsoft Container Registry e o download deles não exige o uso do comando docker login. Ainda será necessário concluir uma solicitação online para executar o contêiner. Consulte a seção Solicitar aprovação para executar o contêiner posteriormente no artigo para obter mais informações.

Os contêineres permitem executar as APIs de Pesquisa Visual Computacional em seu próprio 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 contêineres da Pesquisa Visual Computacional.

O contêiner de OCR de Leitura permite extrair um texto impresso e manuscrito de imagens e documentos compatíveis com os formatos de arquivos JPEG, PNG, BMP, PDF e TIFF. Para obter mais informações, confira o Guia de instruções da API de Leitura.

Leitura do contêiner 3.2

O contêiner de OCR de Leitura 3.2 fornece:

  • Novos modelos para obter uma precisão aprimorada.
  • Suporte para vários idiomas no mesmo documento.
  • Suporte para 73 idiomas. Confira a lista completa de idiomas compatíveis com o OCR.
  • Uma operação única para documentos e imagens.
  • Suporte para documentos e imagens maiores.
  • Pontuações de confiança.
  • Suporte para documentos com texto impresso e manuscrito.
  • Capacidade de extrair textos somente de páginas selecionadas em um documento.
  • Escolha a ordem de saída da linha de texto da opção padrão para obter uma ordem de leitura que seja mais natural. Essa opção está disponível somente para idiomas latinos.
  • A classificação ou não de linha de texto no estilo manuscrito está disponível somente para idiomas latinos.

Caso esteja usando contêineres de leitura 2.0 no momento, confira o guia de migração para saber mais sobre alterações das novas versões.

Pré-requisitos

Será necessário atender aos seguintes pré-requisitos antes de usar os contêineres:

Obrigatório Finalidade
Mecanismo do Docker É necessário ter o Mecanismo Docker instalado em um computador host. O Docker fornece pacotes que configuram o ambiente do Docker no macOS, no Windows e no Linux. Para instruções sobre conceitos básicos do Docker e de contêiner, consulte a visão geral do Docker.

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.

Familiaridade com o Docker É necessário ter uma compreensão básica de conceitos do Docker, como registros, repositórios, contêineres e imagens de contêiner, bem como conhecimento dos comandos básicos do docker.
Recurso da Pesquisa Visual Computacional Para usar o contêiner, você precisará ter:

Um recurso da Pesquisa Visual Computacional do Azure, bem como a chave de API e o URI do ponto de extremidade associados. Os dois valores estão disponíveis nas páginas Visão geral e Chaves e são necessários para iniciar o contêiner.

{API_KEY} : uma das duas chaves de recurso disponíveis na página Chaves

{ENDPOINT_URI} : o ponto de extremidade fornecido na página Visão Geral

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

Solicitar aprovação para executar o contêiner

Preencha e envie o formulário de solicitação a fim de solicitar aprovação para executar o contêiner.

O formulário solicita informações sobre você, sua empresa e o cenário do usuário para o qual você usará o contêiner. Depois de enviar o formulário, a equipe dos Serviços Cognitivos do Azure o examinará e enviará uma decisão por email.

Importante

  • No formulário, você precisa usar um endereço de email associado a uma ID da assinatura do Azure.
  • O recurso do Azure usado para executar o contêiner precisa ter sido criado com a ID da assinatura do Azure aprovada.
  • Verifique seu email ( tanto na caixa de entrada e quanto nas pastas de lixo eletrônico) para obter atualizações sobre o status do seu aplicativo da Microsoft.

Após sua aprovação, você poderá executar o contêiner depois de baixá-lo do MCR (Microsoft Container Registry), o que será descrito posteriormente neste artigo.

Você não poderá executar o contêiner se a sua assinatura do Azure não for aprovada.

Como reunir os parâmetros necessários

Há três parâmetros principais para todos os contêineres de Serviços Cognitivos que são necessários. O EULA (contrato de licença de usuário final) deve estar presente com o valor accept. Além disso, uma URL de ponto de extremidade e uma chave de API são necessárias.

URI do ponto de extremidade {ENDPOINT_URI}

O valor do URI do ponto de extremidade está disponível na página Visão geral do portal do Azure do recurso de Serviço Cognitivo correspondente. Navegue até a página Visão geral, focalize o ponto de extremidade e um Copy to clipboard ícone será exibido. Copie e use onde for necessário.

Anote o URI do ponto de extremidade para uso posterior

Chaves {API_KEY}

Essa chave é usada para iniciar o contêiner e está disponível na página Chaves do portal do Azure do recurso de Serviço Cognitivo correspondente. Navegue até a página Chaves e clique no ícone Copy to clipboard .

Obter uma das duas chaves para uso posterior

Importante

Essas chaves de assinatura são usadas para acessar sua API do Serviço Cognitivo. Não compartilhe suas chaves. Armazene-as com segurança, por exemplo, usando o Azure Key Vault. Recomendamos a regeneração regular dessas chaves. Apenas uma chave é necessária para fazer uma chamada à API. Ao regenerar a primeira chave, você pode usar a segunda chave para obter acesso contínuo ao serviço.

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:

Suporte à extensão avançada do vetor

Host é o computador que executa o contêiner do Docker. O host deverá ser compatível com Extensões Avançadas do Vetor (AVX2). É possível verificar o suporte para AVX2 em hosts Linux usando o seguinte comando:

grep -q avx2 /proc/cpuinfo && echo AVX2 supported || echo No AVX2 support detected

Aviso

O computador host será necessário para dar suporte ao AVX2. O contêiner não funcionará de modo adequado sem o suporte ao AVX2.

Recomendações e requisitos do contêiner

Observação

Os requisitos e as recomendações são baseados em parâmetros de comparação com uma solicitação por segundo, usando uma imagem de 523 MB de uma carta empresarial digitalizada que contém 29 linhas e 803 caracteres no total. A configuração recomendada resultou em uma resposta aproximadamente duas vezes mais rápida em comparação com a configuração mínima.

A tabela a seguir descreverá a alocação mínima e recomendada de recursos para cada contêiner de OCR de Leitura.

Contêiner Mínimo Recomendadas
Versão prévia de leitura 2.0 1 núcleo, 8 GB de memória 8 núcleos, 16 GB de memória
Leitura 3.2 4 núcleos, 16 GB de memória 8 núcleos, 24 GB de memória
  • Cada núcleo precisa ser de pelo menos 2,6 GHz (gigahertz) ou mais rápido.

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

Imagens de contêiner estão disponíveis para leitura.

Contêiner Registro de Contêiner/Repositório/Nome da Imagem
Leitura 2.0 – versão prévia mcr.microsoft.com/azure-cognitive-services/vision/read:2.0-preview
Leitura 3.2 mcr.microsoft.com/azure-cognitive-services/vision/read:3.2

Use o comando docker pull para baixar uma imagem de contêiner.

Executar o comando docker pull para o contêiner de OCR de Leitura

docker pull mcr.microsoft.com/azure-cognitive-services/vision/read:3.2

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>

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. Execute o contêiner com as configurações de cobrança necessárias. Há outros exemplos do comando docker run disponíveis.
  2. Consulte o ponto de extremidade de previsão do contêiner.

Executar o contêiner com docker run

Use o comando docker run para executar o contêiner. Confira como coletar parâmetros necessários para obter detalhes sobre de que modo 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 18g --cpus 8 \
mcr.microsoft.com/azure-cognitive-services/vision/read:3.2 \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

Esse comando:

  • Executa o contêiner de OCR de Leitura da imagem de contêiner.
  • Aloca oito núcleos de CPU e 18 GB (gigabytes) 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.

Como alternativa, você pode executar o contêiner usando variáveis de ambiente:

docker run --rm -it -p 5000:5000 --memory 18g --cpus 8 \
--env Eula=accept \
--env Billing={ENDPOINT_URI} \
--env ApiKey={API_KEY} \
mcr.microsoft.com/azure-cognitive-services/vision/read:3.2

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

Importante

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.

Caso precise de uma taxa de transferência mais alta (ao processar arquivos de várias páginas, por exemplo), considere implantar vários contêineres em um cluster do Kubernetes usando o Armazenamento do Azure e a Fila do Azure.

Caso esteja usando o Armazenamento do Azure para armazenar imagens a fim de executar um processamento, será possível criar uma cadeia de conexão para ser usada durante uma chamada ao contêiner.

Para localizar a cadeia de conexão:

  1. Acesse a opção Contas de armazenamento no portal do Azure e localize sua conta.
  2. Clique em Chaves de acesso na lista de navegação esquerda.
  3. A cadeia de conexão estará localizada abaixo da Cadeia de conexão

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 Cognitivos do Azure em execução no HOST juntos. Também é possível ter vários contêineres do mesmo contêiner dos Serviços Cognitivos em execução.

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 abaixo para validar se o contêiner está em execução. As URLs de solicitação de exemplo listadas abaixo são http://localhost:5000, mas o seu contêiner específico pode variar. Tenha em mente que você depende 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 Solicitado com GET, fornece uma verificação de que o contêiner está pronto para aceitar uma consulta em relação ao modelo. Essa solicitação pode ser usada para testes de preparação e de execução do Kubernetes.
http://localhost:5000/status Também solicitado com GET, verifica se a chave API usada para iniciar o contêiner é válida sem causar uma consulta de terminal. 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.

Home page do 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.

Use o host, http://localhost:5000, para as APIs do contêiner. Será possível ver o caminho do Swagger em: http://localhost:5000/swagger/vision-v3.2-read/swagger.json.

Leitura assíncrona

É possível usar as operações POST /vision/v3.2/read/analyze e GET /vision/v3.2/read/operations/{operationId} em conjunto para ler uma imagem de modo assíncrono, do mesmo modo que o serviço de Pesquisa Visual Computacional usa operações REST correspondentes. O método POST assíncrono retornará um operationId, usado como identificador para a solicitação HTTP GET.

Na interface do usuário do Swagger, selecione Analyze para expandi-lo no navegador. Depois, clique em Experimentar > Escolher arquivo. Neste exemplo, usaremos a seguinte imagem:

Guias versus espaços

Após a execução com êxito do método POST assíncrono, ele retornará um código de status HTTP 202. Como parte da resposta, há um cabeçalho operation-location que contém o ponto de extremidade do resultado para executar a solicitação.

 content-length: 0
 date: Fri, 04 Sep 2020 16:23:01 GMT
 operation-location: http://localhost:5000/vision/v3.2/read/operations/a527d445-8a74-4482-8cb3-c98a65ec7ef9
 server: Kestrel

O operation-location é uma URL totalmente qualificada. Além disso, é possível acessá-lo por meio de um HTTP GET. Veja a resposta JSON da execução da URL operation-location da imagem anterior:

{
  "status": "succeeded",
  "createdDateTime": "2021-02-04T06:32:08.2752706+00:00",
  "lastUpdatedDateTime": "2021-02-04T06:32:08.7706172+00:00",
  "analyzeResult": {
    "version": "3.2.0",
    "readResults": [
      {
        "page": 1,
        "angle": 2.1243,
        "width": 502,
        "height": 252,
        "unit": "pixel",
        "lines": [
          {
            "boundingBox": [
              58,
              42,
              314,
              59,
              311,
              123,
              56,
              121
            ],
            "text": "Tabs vs",
            "appearance": {
              "style": {
                "name": "handwriting",
                "confidence": 0.96
              }
            },
            "words": [
              {
                "boundingBox": [
                  68,
                  44,
                  225,
                  59,
                  224,
                  122,
                  66,
                  123
                ],
                "text": "Tabs",
                "confidence": 0.933
              },
              {
                "boundingBox": [
                  241,
                  61,
                  314,
                  72,
                  314,
                  123,
                  239,
                  122
                ],
                "text": "vs",
                "confidence": 0.977
              }
            ]
          },
          {
            "boundingBox": [
              286,
              171,
              415,
              165,
              417,
              197,
              287,
              201
            ],
            "text": "paces",
            "appearance": {
              "style": {
                "name": "handwriting",
                "confidence": 0.746
              }
            },
            "words": [
              {
                "boundingBox": [
                  286,
                  179,
                  404,
                  166,
                  405,
                  198,
                  290,
                  201
                ],
                "text": "paces",
                "confidence": 0.938
              }
            ]
          }
        ]
      }
    ]
  }
}

Importante

Caso implante vários contêineres de OCR de Leitura atrás de um balanceador de carga, como no Docker Compose ou no Kubernetes, será necessário obter um cache externo. Como o contêiner de processamento e o contêiner de solicitação GET podem não ser o mesmo, um cache externo armazena os resultados e compartilha-os entre os contêineres. Para obter detalhes sobre as configurações de cache, confira Configurar contêineres do Docker da Pesquisa Visual Computacional.

Leitura síncrona

É possível usar a operação a seguir para ler uma imagem de modo síncrono.

POST /vision/v3.2/read/syncAnalyze

Somente após ler uma imagem por completo, uma API retornará determinada resposta JSON. A única exceção para esse cenário é a ocorrência de um erro. Após a ocorrência de um erro, a seguinte resposta JSON retornará:

{
    "status": "Failed"
}

O objeto de resposta JSON tem o mesmo grafo de objetos da versão assíncrona. Caso seja um usuário do JavaScript e queira executar a segurança de tipos, considere usar o TypeScript para converter a resposta JSON.

Para obter um exemplo de caso de uso, confira uma área restrita do TypeScript aqui, depois clique em Executar para visualizar a facilidade de uso.

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 diretrizes para a solução de problemas, confira Perguntas frequentes sobre os contêineres dos Serviços Cognitivos do Azure.

Cobrança

Os contêineres dos Serviços Cognitivos enviam informações de cobrança do Azure usando um recurso correspondente em sua conta do Azure.

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

Os contêineres dos Serviços Cognitivos do Azure não estão licenciados para execução sem estarem conectados com o ponto de extremidade de medição/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 Cognitivos 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 do contêiner de Serviços Cognitivos 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 Cognitivos 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 Cognitivos 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.

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 de Pesquisa Visual Computacional. Em resumo:

  • A Pesquisa Visual Computacional fornece um contêiner do Linux para o Docker, encapsulando a Leitura.
  • A imagem de contêiner de leitura requer um aplicativo para executá-lo.
  • Imagens de contêiner são executadas no Docker.
  • É possível usar a API REST ou o SDK para executar uma chamada às operações em contêineres de OCR de Leitura especificando o URI host do contêiner.
  • Você deve especificar informações de faturamento ao instanciar um contêiner.

Importante

Os contêineres dos Serviços Cognitivos não estão licenciados para execução sem estarem conectados 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 Serviços Cognitivos não enviam dados do cliente (por exemplo, a imagem ou o texto que está sendo analisado) para a Microsoft.

Próximas etapas