Instalar o contêiner do Azure AI Vision 3.2 GA Read OCR

Os contêineres permitem executar as APIs do Azure AI Vision em seu próprio ambiente e podem ajudá-lo a atender a requisitos específicos de segurança e governança de dados. Neste artigo, você aprenderá a baixar, instalar e executar o contêiner Azure AI Vision Read (OCR).

O recipiente Read permite extrair texto impresso e manuscrito de imagens e documentos nos formatos de arquivo JPEG, PNG, BMP, PDF e TIFF. Para obter mais informações sobre o serviço de leitura, consulte o guia de instruções da API de leitura.

Novidades

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

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

• Novos modelos para maior precisão.
• Suporte para vários idiomas dentro do mesmo documento.
• Suporte para um total de 164 idiomas. Consulte a lista completa de idiomas suportados por OCR.
• Uma única operação para documentos e imagens.
• Suporte para documentos e imagens maiores.
• Escores de confiança.
• Suporte para documentos com texto impresso e manuscrito.
• Capacidade de extrair texto apenas de página(s) selecionada(s) em um documento.
• Escolha a ordem de saída da linha de texto do padrão para uma ordem de leitura mais natural apenas para idiomas latinos.
• Classificação da linha de texto como estilo manuscrito ou não apenas para idiomas latinos.

Se você estiver usando o contêiner Read 2.0 hoje, consulte o guia de migração para saber mais sobre as alterações nas novas versões.

Pré-requisitos

Você deve atender aos seguintes pré-requisitos antes de usar os contêineres:

Necessário	Propósito
Motor do Docker	Você precisa do Docker Engine instalado em um computador host. 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 deve ser configurado para permitir que os contêineres se conectem e enviem dados de cobrança para o Azure. No Windows, o Docker também deve ser configurado para suportar contêineres Linux.
Familiaridade com o Docker	Você deve ter uma compreensão básica dos conceitos do Docker, como registros, repositórios, contêineres e imagens de contêiner, bem como conhecimento de comandos básicos docker .
Recurso de Visão por Computador	Para utilizar o contentor, deve ter: Um recurso de Visão Computacional e a chave de API associada o URI do ponto de extremidade. Ambos os valores estão disponíveis nas páginas Visão geral e Chaves do recurso 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 conforme fornecido na página Visão geral

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

Reúna os parâmetros necessários

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

URI do ponto de extremidade

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

Chaves

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

Importante

Essas chaves de assinatura são usadas para acessar sua API de serviços de IA do Azure. Não partilhe as suas chaves. Armazene-os de forma segura. Por exemplo, use o Azure Key Vault. Também recomendamos que regenere essas chaves regularmente. Só é necessária uma chave 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. Pode ser um computador em suas instalações ou um serviço de hospedagem do Docker no Azure, como:

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

Suporte avançado de extensão vetorial

O computador host é o computador que executa o contêiner do docker. O host deve suportar Advanced Vetor Extensions (AVX2). Você pode verificar o suporte a AVX2 em hosts Linux com o seguinte comando:

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

Aviso

O computador host é necessário para suportar AVX2. O contêiner não funcionará corretamente sem suporte a AVX2.

Requisitos e recomendações de contêineres

Nota

Os requisitos e recomendações são baseados em benchmarks com uma única solicitação por segundo, usando uma imagem de 523 KB de uma carta comercial digitalizada que contém 29 linhas e um total de 803 caracteres. A configuração recomendada resultou em uma resposta aproximadamente 2x mais rápida em comparação com a configuração mínima.

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

Contentor	Mínimo	Recomendado
Ler 3.2 2022-04-30	4 núcleos, 8 GB de memória	8 núcleos, 16 GB de memória
Ler 3.2 2021-04-12	4 núcleos, 16 GB de memória	8 núcleos, 24 GB de memória

• Cada núcleo deve ter pelo menos 2,6 gigahertz (GHz) ou mais rápido.

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

Obter a imagem do contêiner

A imagem do contêiner do Azure AI Vision Read OCR pode ser encontrada no sindicato do registro do mcr.microsoft.com contêiner. Ele reside dentro do azure-cognitive-services repositório e é chamado readde . O nome da imagem de contêiner totalmente qualificada é, mcr.microsoft.com/azure-cognitive-services/vision/read.

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

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

Contentor	Registro de contêiner / repositório / nome da imagem	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

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

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

---

Gorjeta

Você pode usar o comando docker images para listar as imagens de contêiner baixadas. Por exemplo, o comando a seguir lista o ID, o repositório e a tag de cada imagem de contêiner baixada, 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 recipiente

Quando o contêiner estiver no computador host, use o seguinte processo para trabalhar com o contêiner.

1. Execute o contêiner, com as configurações de faturamento necessárias. Mais exemplos do docker run comando estão 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. Consulte reunir os parâmetros necessários para obter detalhes sobre como obter os {ENDPOINT_URI} valores e {API_KEY} .

Exemplos do docker run comando 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 GA mais recente do OCR Read a partir da imagem do contêiner.
• Aloca 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 contêiner.
• Remove automaticamente o recipiente depois que ele sai. A imagem do contêiner ainda está 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

Mais exemplos do docker run comando estão disponíveis.

Importante

As Eulaopções , Billinge devem ApiKey ser especificadas para executar o contêiner, caso contrário, o contêiner não será iniciado. Para obter mais informações, consulte Faturamento.

Se você estiver usando o Armazenamento do Azure para armazenar imagens para processamento, poderá criar uma cadeia de conexão para usar ao chamar o contêiner.

Para encontrar sua cadeia de conexão:

1. Navegue até Contas de armazenamento no portal do Azure e localize sua conta.
2. Selecione as teclas de acesso na lista de navegação à esquerda.
3. Sua cadeia de conexão estará localizada abaixo de Cadeia de conexão

Executar vários contêineres no mesmo host

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

Você pode ter esse contêiner e um contêiner de serviços de IA do Azure diferente em execução no HOST juntos. Você também pode ter vários contêineres do mesmo contêiner de 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 o 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 que o contêiner está em execução. Os URLs de solicitação de exemplo listados aqui são http://localhost:5000, mas seu contêiner específico pode variar. Certifique-se de confiar no endereço IP externo e na porta exposta do contêiner.

URL do Pedido	Propósito
http://localhost:5000/	O contentor fornece uma home page.
http://localhost:5000/ready	Solicitada com GET, essa URL fornece uma verificação de que o contêiner está pronto para aceitar uma consulta no modelo. Essa solicitação pode ser usada para sondas de vivacidade e prontidão do Kubernetes.
http://localhost:5000/status	Também solicitada com GET, essa URL verifica se a chave de api usada para iniciar o contêiner é válida sem causar uma consulta de ponto de extremidade. Essa solicitação pode ser usada para sondas de vivacidade e prontidã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 esse recurso, você pode inserir suas configurações em um formulário HTML baseado na Web e fazer a consulta sem ter que escrever nenhum código. Depois que a consulta retorna, um comando CURL de exemplo é fornecido para demonstrar os cabeçalhos HTTP e o formato de corpo necessários.

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. Você pode visualizar o caminho Swagger em: http://localhost:5000/swagger/.

Leitura assíncrona

Você pode usar as operações e GET /vision/v3.2/read/operations/{operationId} em conjunto para ler uma imagem de forma assíncronaPOST /vision/v3.2/read/analyze, semelhante à forma como o serviço Azure AI Vision usa as operações REST correspondentes. O método POST assíncrono retornará um operationId que é usado como identificador para a solicitação HTTP GET.

Na interface do usuário swagger, selecione a Analyze opção para expandi-la no navegador. Em seguida, selecione Experimentar>Escolher arquivo. Neste exemplo, usaremos a seguinte imagem:

Quando o POST assíncrono é executado com êxito, ele retorna um código de status HTTP 202 . Como parte da resposta, há um operation-location cabeçalho que contém o ponto de extremidade de resultado para 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 é o URL totalmente qualificado e é acessado através de um HTTP GET. Aqui está a resposta JSON da execução do operation-location URL 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 você implantar vários contêineres de OCR de leitura atrás de um balanceador de carga, por exemplo, em Docker Compose ou Kubernetes, deverá ter um cache externo. Como o contêiner de processamento e o contêiner de solicitação GET podem não ser os mesmos, um cache externo armazena os resultados e os compartilha entre contêineres. Para obter detalhes sobre as configurações de cache, consulte Configurar contêineres do Azure AI Vision Docker.

Leitura síncrona

Você pode usar a operação a seguir para ler uma imagem de forma síncrona.

POST /vision/v3.2/read/syncAnalyze

Quando a imagem é lida em sua totalidade, então e só então a API retorna uma resposta JSON. A única exceção a esse comportamento é se ocorrer um erro. Se ocorrer um erro, o seguinte JSON será retornado:

{
    "status": "Failed"
}

O objeto de resposta JSON tem o mesmo gráfico de objeto que a versão assíncrona. Se você for um usuário de JavaScript e quiser segurança de tipo, considere usar o TypeScript para transmitir a resposta JSON.

Para obter um exemplo de caso de uso, consulte a sandbox TypeScript aqui e selecione Executar para visualizar sua facilidade de uso.

Execute o contêiner desconectado da Internet

Para usar este recipiente desconectado da internet, você deve primeiro solicitar o acesso preenchendo um requerimento e adquirindo um plano de compromisso. Consulte Usar contêineres do Docker em ambientes desconectados para obter mais informações.

Se você tiver sido aprovado para executar o contêiner desconectado da Internet, use o exemplo a seguir mostra a formatação do comando que você usará, com valores de docker run espaço reservado. Substitua esses valores de espaço reservado por seus próprios valores.

O DownloadLicense=True parâmetro em seu docker run comando baixará um arquivo de licença que permitirá que seu 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, você não pode usar um arquivo de licença para um contêiner de fala para texto com um contêiner de Inteligência de Documento.

Marcador de Posição	Value	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 onde a licença será baixada e montada.	/host/license:/path/to/license/directory
{ENDPOINT_URI}	O ponto de extremidade para autenticar sua solicitação de serviço. Você pode encontrá-lo na página Chave e ponto de extremidade do seu recurso, no portal do Azure.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{API_KEY}	A chave para o seu recurso de Análise de Texto. Você pode encontrá-lo na página Chave e ponto de extremidade do seu recurso, no portal do Azure.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{CONTAINER_LICENSE_DIRECTORY}	Localização 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 for baixado, você poderá executar o contêiner em um ambiente desconectado. O exemplo a seguir mostra a docker run formatação do comando que você usará, com valores de espaço reservado. Substitua esses valores de espaço reservado por seus próprios valores.

Onde quer que o contêiner seja executado, o arquivo de licença deve ser montado no contêiner e o local da pasta de licença no sistema de arquivos local do contêiner deve ser especificado com Mounts:License=. Uma montagem de saída também deve ser especificada para que os registros de uso de faturamento possam ser gravados.

Marcador de Posição	Value	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 seu contêiner.	4g
{NUMBER_CPUS}	O número apropriado de CPUs a serem alocadas para seu contêiner.	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 registrar registros de uso.	/host/output:/path/to/output/directory
{CONTAINER_LICENSE_DIRECTORY}	Localização da pasta de licença no sistema de arquivos local do contêiner.	/path/to/license/directory
{CONTAINER_OUTPUT_DIRECTORY}	Localização 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 contentor

Para desligar o contêiner, no ambiente de linha de comando em que o contêiner está sendo executado, selecione Ctrl+C.

Resolução de Problemas

Se você executar o contêiner com uma montagem de saída e registro em log habilitados, o contêiner gerará arquivos de log que serão úteis para solucionar problemas que acontecem ao iniciar ou executar o contêiner.

Gorjeta

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

Se você estiver tendo problemas para executar um contêiner de serviços de IA do Azure, tente usar o contêiner de diagnóstico da Microsoft. Use esse contêiner para diagnosticar erros comuns em seu 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 docker pull comando:

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

Em seguida, execute o contêiner. Substitua {ENDPOINT_URI} pelo ponto de extremidade 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 contêiner testará a conectividade de rede com o ponto de extremidade de faturamento.

Faturação

Os contêineres de IA do Azure enviam informações de cobrança para o Azure, usando o recurso correspondente em sua conta do Azure.

As consultas ao contêiner são cobradas na camada de preço do recurso do Azure usado para o ApiKey parâmetro.

Os contêineres de serviços de IA do Azure não são licenciados para serem executados sem estarem conectados ao ponto de extremidade de medição ou cobrança. Você deve habilitar os contêineres para comunicar informações de faturamento com o ponto de extremidade de faturamento em todos os momentos. Os contêineres de serviços de IA do Azure não enviam dados do cliente, como a imagem ou o texto que está sendo analisado, para a Microsoft.

Ligar ao Azure

O contêiner precisa dos valores do argumento de faturamento para ser executado. Esses valores permitem que o contêiner se conecte ao ponto de extremidade de faturamento. 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, o contêiner continuará a ser executado, mas não atenderá consultas até que o ponto de extremidade de cobrança seja restaurado. A conexão é tentada 10 vezes no mesmo intervalo de tempo de 10 a 15 minutos. Se ele não puder se conectar ao ponto de extremidade de faturamento dentro das 10 tentativas, o contêiner interromperá o atendimento de solicitações. Consulte as Perguntas frequentes sobre o contêiner de serviços de IA do Azure para obter um exemplo das informações enviadas à Microsoft para cobrança.

Argumentos de faturação

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

Opção	Description
ApiKey	A chave de API do recurso de serviços de IA do Azure que é 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 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 provisionado do Azure.
Eula	Indica que você aceitou a licença para o contêiner. O valor desta opção deve ser definido como accept.

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 contêineres do Azure AI Vision. Em resumo:

• O Azure AI Vision fornece um contêiner Linux para o Docker, encapsulando a Leitura.
• A imagem de contêiner de leitura requer um aplicativo para executá-la.
• As imagens de contêiner são executadas no Docker.
• Você pode usar a API REST ou o SDK para chamar operações em contêineres de OCR de leitura especificando o URI do host do contêiner.
• Você deve especificar informações de faturamento ao instanciar um contêiner.

Importante

Os contêineres de IA do Azure não são licenciados para serem executados sem estarem conectados ao Azure para medição. Os clientes precisam permitir que os contêineres comuniquem informações de faturamento 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óximos passos

• Revise Configurar contêineres para definições de configuração
• Revise a visão geral do OCR para saber mais sobre como reconhecer texto impresso e manuscrito
• Consulte a API de leitura para obter detalhes sobre os métodos suportados pelo contêiner.
• Consulte Perguntas frequentes para resolver problemas relacionados à funcionalidade do Azure AI Vision.
• Usar mais contêineres de IA do Azure