Instalar o contentor OCR de Leitura do Azure AI Vision 3.2 GA

  • Artigo

Os contentores permitem-lhe executar as APIs de Visão de IA do Azure no seu próprio ambiente. Os contentores são ótimos para requisitos específicos de governação de dados e segurança. Neste artigo, irá aprender a transferir, instalar e executar o contentor De Leitura (OCR).

O contentor Ler permite-lhe extrair texto impresso e manuscrito de imagens e documentos com suporte para formatos de ficheiro JPEG, PNG, BMP, PDF e TIFF. Para obter mais informações, veja o guia de procedimentos da API de Leitura.

Novidades

A 3.2-model-2022-04-30 versão GA do contentor de Leitura está disponível com suporte para 164 idiomas e outros melhoramentos. Se for um cliente existente, siga as instruções de transferência para começar.

O contentor OCR de Leitura 3.2 é o modelo de DISPONIBILIDADE mais recente e fornece:

  • Novos modelos para maior precisão.
  • Suporte para vários idiomas no mesmo documento.
  • Suporte para um total de 164 idiomas. Veja a lista completa de idiomas suportados pelo OCR.
  • Uma única operação para documentos e imagens.
  • Suporte para documentos e imagens maiores.
  • Classificações de confiança.
  • Suporte para documentos com texto impresso e manuscrito.
  • Capacidade de extrair texto de apenas páginas selecionadas num documento.
  • Escolha a ordem de saída da linha de texto da predefinição para uma ordem de leitura mais natural apenas para idiomas latinos.
  • Classificação de linhas de texto como estilo manuscrito ou não apenas para idiomas latinos.

Se estiver a utilizar contentores de Leitura 2.0 hoje, consulte o guia de migração para saber mais sobre as alterações nas novas versões.

Pré-requisitos

Tem de cumprir os seguintes pré-requisitos antes de utilizar os contentores:

Necessário Objetivo
Motor do Docker Precisa do Motor do Docker instalado num computador anfitrião. O Docker oferece pacotes que configuram o ambiente do Docker no macOS, no Windows e no Linux. Para um manual de noções básicas do Docker e do contentor, veja a descrição geral do Docker.

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 linux.
Familiaridade com o Docker Deve ter uma compreensão básica dos conceitos do Docker, como registos, repositórios, contentores e imagens de contentor, bem como conhecimentos de comandos básicos docker .
Imagem Digitalizada recurso Para utilizar o contentor, tem de ter:

Um recurso Imagem Digitalizada e a chave de API associada ao URI do ponto final. Ambos os valores estão disponíveis nas páginas Descrição Geral e Chaves do recurso e são necessários para iniciar o contentor.

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

{ENDPOINT_URI}: O ponto final, conforme fornecido na página Descrição geral

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

Recolher os parâmetros necessários

São necessários três parâmetros principais para todos os contentores de IA do Azure. 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 do portal do Azure do recurso correspondente dos serviços de IA do Azure. 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.

Captura de ecrã que mostra a recolha do URI do ponto final para utilização posterior.

Chaves

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

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

Importante

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

Requisitos do computador anfitrião

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

Suporte de Extensão de Vetor Avançada

O computador anfitrião é o computador que executa o contentor do docker. O anfitrião tem de suportarExtensões de Vetor Avançadas (AVX2). Pode procurar suporte AVX2 em anfitriões Linux com o seguinte comando:

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

Aviso

O computador anfitrião é necessário para suportar o AVX2. O contentor não funcionará corretamente sem suporte AVX2.

Requisitos e recomendações de contentor

Nota

Os requisitos e recomendações baseiam-se em referências com um único pedido por segundo, utilizando uma imagem de 523 KB de uma letra de negócio digitalizada que contém 29 linhas e um total de 803 carateres. A configuração recomendada resultou numa resposta aproximadamente 2x mais rápida em comparação com a configuração mínima.

A tabela seguinte descreve a alocação mínima e recomendada de recursos para cada contentor OCR de Leitura.

Contentor Mínimo Recomendado
Ler 3.2 2022-04-30 4 núcleos, memória de 8 GB 8 núcleos, memória de 16 GB
Ler 3.2 2021-04-12 4 núcleos, memória de 16 GB 8 núcleos, memória de 24 GB
  • Cada núcleo tem de ter, pelo menos, 2,6 gigahertz (GHz) ou mais rápido.

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

Obter a imagem do contentor

A imagem de contentor OCR de Leitura da Visão de IA do Azure pode ser encontrada no sindicato do mcr.microsoft.com registo de contentores. Reside no repositório e tem o azure-cognitive-services nome read. O nome da imagem de contentor completamente qualificado é . mcr.microsoft.com/azure-cognitive-services/vision/read

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.

Estão disponíveis as seguintes imagens de contentor para Leitura.

Contentor Container Registry/Repository/Image Name Etiquetas
Ler 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

Utilize o docker pull comando para transferir uma imagem de contentor.

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

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>

Como utilizar o contentor

Quando o contentor estiver no computador anfitrião, utilize o seguinte processo para trabalhar com o contentor.

  1. Execute o contentor, com as definições de faturação necessárias. Estão disponíveis mais exemplos do docker run comando.
  2. Consulte o ponto final de predição do contentor.

Executar o contentor

Utilize o comando docker run para executar o contentor. Veja recolher os parâmetros necessários para obter detalhes sobre como obter os {ENDPOINT_URI} valores e {API_KEY} .

Estão disponíveis exemplos do docker run comando.

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 contentor leia o OCR mais recente ga a partir da imagem de contentor.
  • Atribui 8 núcleos de CPU e 16 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.

Em alternativa, pode executar o contentor com 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

Estão disponíveis mais exemplos do docker run comando.

Importante

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.

Se precisar de um débito mais elevado (por exemplo, ao processar ficheiros de várias páginas), considere implementar vários contentores num cluster do Kubernetes com o Armazenamento do Azure e a Fila do Azure.

Se estiver a utilizar o Armazenamento do Azure para armazenar imagens para processamento, pode criar uma cadeia de ligação para utilizar ao chamar o contentor.

Para localizar a cadeia de ligação:

  1. Navegue para Contas de armazenamento no portal do Azure e localize a sua conta.
  2. Selecione em Teclas de acesso na lista de navegação à esquerda.
  3. A cadeia de ligação estará localizada abaixo da Cadeia de ligaçã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 de serviços do Azure AI diferente em execução no HOST em conjunto. Também pode ter vários contentores do mesmo contentor de serviços de IA do Azure em execução.

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

Home page do contentor

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. Pode ver o caminho do Swagger em: http://localhost:5000/swagger/.

Leitura Assíncrona

Pode utilizar as POST /vision/v3.2/read/analyze operações e GET /vision/v3.2/read/operations/{operationId} em conjunto para ler de forma assíncrona uma imagem, semelhante à forma como o serviço Azure AI Vision utiliza essas operações REST correspondentes. O método POST assíncrono devolverá um operationId que é utilizado como o identificador para o pedido HTTP GET.

Na IU do swagger, selecione o Analyze para expandi-lo no browser. Em seguida, selecione Experimentar>Escolher ficheiro. Neste exemplo, vamos utilizar a seguinte imagem:

separadores vs. espaços

Quando o POST assíncrono for executado com êxito, devolve um código de estado HTTP 202 . Como parte da resposta, existe um operation-location cabeçalho que contém o ponto final de resultado do pedido.

 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 é o URL completamente qualificado e é acedido através de um HTTP GET. Eis a resposta JSON da execução do operation-location URL a partir 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

Se implementar vários contentores OCR de Leitura atrás de um balanceador de carga, por exemplo, em Docker Compose ou Kubernetes, tem de ter uma cache externa. Uma vez que o contentor de processamento e o contentor de pedidos GET podem não ser os mesmos, uma cache externa armazena os resultados e partilha-os entre contentores. Para obter detalhes sobre as definições de cache, veja Configurar contentores do Docker do Azure AI Vision.

Leitura síncrona

Pode utilizar a seguinte operação para ler uma imagem de forma síncrona.

POST /vision/v3.2/read/syncAnalyze

Quando a imagem é lida na sua totalidade, e só então a API devolve uma resposta JSON. A única exceção a este comportamento é se ocorrer um erro. Se ocorrer um erro, é devolvido o seguinte JSON:

{
    "status": "Failed"
}

O objeto de resposta JSON tem o mesmo grafo de objeto que a versão assíncrona. Se for um utilizador de JavaScript e quiser ter segurança de tipo, considere utilizar o TypeScript para transmitir a resposta JSON.

Para obter um exemplo de caso de utilização, veja o sandbox TypeScript aqui e selecione Executar para visualizar a facilidade de utilização.

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. Veja 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 para mostrar 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 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 do Document Intelligence.

Marcador de posição Valor Formato ou exemplo
{IMAGE} A imagem de contentor que pretende utilizar. mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice
{LICENSE_MOUNT} O caminho para 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 de IA do Azure.

Se estiver a ter problemas ao executar um contentor dos serviços de IA do Azure, pode tentar utilizar o contentor de diagnósticos da Microsoft. Utilize este contentor para diagnosticar erros comuns no seu ambiente de implementação que possam impedir que os contentores de IA do Azure funcionem conforme esperado.

Para obter o contentor, utilize o seguinte docker pull comando:

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

Em seguida, execute o contentor. Substitua {ENDPOINT_URI} pelo ponto final e substitua {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 contentor irá testar a conectividade de rede ao ponto final de faturação.

Faturação

Os contentores de IA do Azure enviam informações de faturação para o Azure com o recurso correspondente 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 de IA 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 de IA do Azure 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 sobre o contentor dos serviços de IA do Azure 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 de IA do Azure 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 de IA do Azure 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.

Para obter mais informações sobre estas opções, veja Configurar contentores.

Resumo

Neste artigo, aprendeu conceitos e fluxos de trabalho para transferir, instalar e executar contentores do Azure AI Vision. Em resumo:

  • O Azure AI Vision fornece um contentor do Linux para o Docker, encapsulando a leitura.
  • A imagem de contentor de leitura requer que uma aplicação a execute.
  • As imagens de contentor são executadas no Docker.
  • Pode utilizar a API REST ou o SDK para chamar operações em Contentores OCR de Leitura 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 de IA do Azure 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 de IA do Azure não enviam dados do cliente (por exemplo, a imagem ou texto que está a ser analisado) para a Microsoft.

Passos seguintes