Compartilhar via

Instalar o contêiner de OCR de leitura de GA do Visão de IA do Azure 3.2

  • Artigo

Contêineres permitem executar as APIs de Visão de IA do Azure no seu ambiente, o que pode ser útil para atender requisitos específicos de segurança e governança de dados. Neste artigo, você aprenderá a baixar, instalar e executar o contêiner de Leitura (OCR) da Visão de IA do Azure.

O contêiner de Leitura permite extrair textos impressos e manuscritos de imagens e documentos nos formatos JPEG, PNG, BMP, PDF e TIFF. Para mais informações sobre o serviço de Leitura, confira o Guia de instruções da API de Leitura.

Novidades

A versão de GA 3.2-model-2022-04-30 do contêiner de Leitura está disponível com suporte para 164 idiomas e outros aprimoramentos. Se você é um cliente existente, siga as instruções de download para começar.

O contêiner de OCR de Leitura 3.2 é o modelo de GA mais recente e fornece:

  • Novos modelos para obter uma precisão aprimorada.
  • Suporte para vários idiomas no mesmo documento.
  • Suporte para 164 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 já esteja usando o contêiner de Leitura 2.0, confira o guia de migração para saber mais sobre as mudanças nas 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, 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.

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.

Captura de tela que mostra a coleta do URI do ponto de extremidade para uso posterior.

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 .

Captura de tela que mostra a obtenção de uma das duas chaves para uso posterior.

Importante

Essas chaves de assinatura são usadas para acessar a 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.

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:

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
Leitura 3.2 2022-04-30 4 núcleos, 8 GB de memória 8 núcleos, 16 GB de memória
Leitura 3.2 2021-04-12 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

A imagem de contêiner do OCR de Leitura do Visão de IA do Azure pode ser encontrada na agregação do registro de contêiner mcr.microsoft.com. Ela reside no repositório azure-cognitive-services e é chamada read. O nome da imagem de contêiner totalmente qualificado é mcr.microsoft.com/azure-cognitive-services/vision/read.

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

As imagens de contêiner a seguir estão disponíveis para leitura.

Contêiner Registro de Contêiner/Repositório/Nome da Imagem Marcações
Leitura 3.2 GA mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30 mais recente, 3.2, 3.2-model-2022-04-30

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

docker pull mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30

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

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 16g --cpus 8 \
mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30 \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

O comando acima:

  • Executa o contêiner de GA mais recente de OCR de Leitura da imagem de contêiner.
  • Aloca oito núcleos de CPU e 16 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 16g --cpus 8 \
--env Eula=accept \
--env Billing={ENDPOINT_URI} \
--env ApiKey={API_KEY} \
mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30

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

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.

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

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 Visão de IA do Azure 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 Visão de IA do Azure.

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 comportamento é a ocorrência de um erro. Se ocorrer um erro, o seguinte JSON será retornado:

{
    "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.

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

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

Os contêineres da IA do Azure 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 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 usada 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 de serviços de IA do Azure que é utilizado para rastrear as 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 do Visão de IA do Azure. Em resumo:

  • O Visão de IA do Azure 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 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, a imagem ou o texto que está sendo analisado) para a Microsoft.

Próximas etapas