Compartilhar via

Instalar e executar contêineres

Este conteúdo se aplica a:checkmarkv3.0 (GA)checkmarkv3.1 (GA)checkmarkv4.0 (GA)

O Azure Document Intelligence nas Foundry Tools é uma ferramenta que permite criar software de processamento de dados automatizado usando a tecnologia de aprendizado de máquina. A Informação de Documentos habilita você a identificar e extrair texto, pares de chave-valor, marcas de seleção, dados de tabela e muito mais dos seus documentos. Os resultados são gerados em dados estruturados que ../incluem as relações no arquivo original. Os contêineres processam apenas os dados fornecidos a eles e utilizam exclusivamente os recursos que têm permissão para acessar. Os contêineres não podem processar dados de outras regiões.

Neste artigo, você aprenderá como fazer download, instalar e executar contêineres do Informação de Documentos. Os contêineres permitem a execução do serviço Informação de Documentos em seu próprio ambiente. Contêineres são excelentes para especificar requisitos de segurança e governança de dados.

  • O modelo de leitura e layout é compatível com contêineres da Informação de Documentos v4.0.

  • Os modelos de leitura, layout, documento de identificação, recibo e fatura são compatíveis com contêineres da Informação de Documentos v3.1.

  • Os modelos de leitura, layout, documento geral, cartão de visita e personalizado são compatíveis com contêineres da Informação de Documentos v3.0.

Suporte à versão

Atualmente, o suporte a contêineres está disponível nas seguintes versões da Informação de Documentos :v3.0: 2022-08-31 (GA) para todos os modelos,v3.1 2023-07-31 (GA) para os modelos de leitura, layout, fatura, recibo e documento de identificação e v4.0 2024-11-30 (GA) para os modelos de leitura e layout:

Pré-requisitos

Para começar, você precisa de uma conta do Azure ativa. Se você não tem uma, crie uma conta gratuita.

Você também precisa do seguinte para usar os contêineres do Document Intelligence:

Obrigatório Finalidade
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 básico de dockerterminologia e comandos.
Mecanismo do Docker instalado
  • É 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.
Recurso da Informação de Documentos Um recurso de serviço único de Informação de Documentos do Azure ou de vários serviços no portal do Azure. Para usar os contêineres, você deve ter a chave associada e o URI do ponto de extremidade. Ambos os valores estão disponíveis na página Document Intelligence Chaves e Ponto de extremidade do portal do Azure:
  • {FORM_RECOGNIZER_KEY} : uma das duas chaves de recursos disponíveis.
  • {FORM_RECOGNIZER_ENDPOINT_URI}: o ponto de extremidade para o recurso usado para rastrear informações de cobrança.
Opcional Finalidade
CLI do Azure (Interface de linha de comando do Azure) O CLI do Azure permite que você use um conjunto de comandos online para criar e gerenciar recursos do Azure. Ela está disponível para instalação em ambientes Windows, macOS e Linux e pode ser executada em um contêiner do Docker e no Azure Cloud Shell.

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:

Observação

O contêiner do Studio não pode ser implantado e executado no Serviço de Kubernetes do Azure. O contêiner do Studio só tem suporte para ser executado em computadores locais.

Recomendações e requisitos do contêiner

Contêineres de suporte são necessários

A tabela a seguir lista um ou mais contêineres com suporte para cada contêiner de Informação de Documentos que você baixar. Para saber mais, veja a seção Cobrança.

Contêiner de recursos Contêineres de suporte
Leitura Não obrigatório
Layout Não obrigatório
Cartão de visita Leitura
Documento geral Layout
Fatura Layout
Recibo Leitura ou Layout
Documento de identificação Leitura
Modelo personalizado Layout

Observação

Os valores mínimos e recomendados se baseiam nos limites do Docker e não nos recursos do computador host.

Contêineres da Informação de Documentos
Contêiner Mínimo Recomendadas
Read 8 núcleos, 10 GB de memória 8 núcleos, 24 GB de memória
Layout 8 núcleos, 16 GB de memória 8 núcleos, 24 GB de memória
Business Card 8 núcleos, 16 GB de memória 8 núcleos, 24 GB de memória
General Document 8 núcleos, 12 GB de memória 8 núcleos, 24 GB de memória
ID Document 8 núcleos, 8 GB de memória 8 núcleos, 24 GB de memória
Invoice 8 núcleos, 16 GB de memória 8 núcleos, 24 GB de memória
Receipt 8 núcleos, 11 GB de memória 8 núcleos, 24 GB de memória
Custom Template 8 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 compose ou docker run.

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>

Execute o contêiner com o comando docker-compose up

  • Substitua os valores {ENDPOINT_URI} e {API_KEY} pelo URI do ponto de extremidade do recurso e pela chave da página de recursos do Azure.

    Captura de tela das chaves do portal do Azure e da página do ponto de extremidade.

  • Verifique se o valor EULA está definido como accept.

  • Os valores EULA, Billing, e ApiKey devem ser especificados; caso contrário, o contêiner não poderá iniciar.

Importante

As chaves são utilizadas para acessar o recurso da Informação de Documentos. 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 exemplo de código a seguir é um exemplo independente docker compose para executar o contêiner Document Intelligence Layout. Com docker compose, um arquivo YAML é usado para configurar os serviços do aplicativo. Em seguida, você cria e inicia todos os serviços com base na sua configuração com o comando docker-compose up. Insira os valores DE {FORM_RECOGNIZER_ENDPOINT_URI} e {FORM_recognizer_KEY} na sua instância de contêiner de Layout.

version: "3.9"
services:
  azure-form-recognizer-layout:
    container_name: azure-form-recognizer-layout
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-4.0
    environment:
      - EULA=accept
      - billing={FORM_RECOGNIZER_ENDPOINT_URI}
      - apiKey={FORM_RECOGNIZER_KEY}
    ports:
      - "5000:5000"
    networks:
      - ocrvnet
networks:
  ocrvnet:
    driver: bridge

Agora, você pode iniciar o serviço com o comando docker compose:

docker-compose up

Execute o contêiner com o comando docker-compose up

  • Substitua os valores {ENDPOINT_URI} e {API_KEY} pelo URI do ponto de extremidade do recurso e pela chave da página de recursos do Azure.

    Captura de tela das chaves do portal do Azure e da página do ponto de extremidade.

  • Verifique se o valor EULA está definido como accept.

  • Os valores EULA, Billing, e ApiKey devem ser especificados; caso contrário, o contêiner não poderá iniciar.

Importante

As chaves são utilizadas para acessar o recurso da Informação de Documentos. 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 exemplo de código a seguir é um exemplo independente docker compose para executar o contêiner Document Intelligence Layout. Com docker compose, um arquivo YAML é usado para configurar os serviços do aplicativo. Em seguida, você cria e inicia todos os serviços com base na sua configuração com o comando docker-compose up. Insira os valores DE {FORM_RECOGNIZER_ENDPOINT_URI} e {FORM_recognizer_KEY} na sua instância de contêiner de Layout.

version: "3.9"
services:
  azure-form-recognizer-layout:
    container_name: azure-form-recognizer-layout
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.1
    environment:
      - EULA=accept
      - billing={FORM_RECOGNIZER_ENDPOINT_URI}
      - apiKey={FORM_RECOGNIZER_KEY}
    ports:
      - "5000:5000"
    networks:
      - ocrvnet
networks:
  ocrvnet:
    driver: bridge

Agora, você pode iniciar o serviço com o comando docker compose:

docker-compose up

Criar um arquivo docker compose

  1. Nomeie esse arquivo como docker-compose.yml

  2. O exemplo de código a seguir é um exemplo independente docker compose para executar os contêineres de modelo Document Intelligence Layout, Studio e Custom juntos. Com docker compose, um arquivo YAML é usado para configurar os serviços do aplicativo. Em seguida, você cria e inicia todos os serviços com base na sua configuração com o comando docker-compose up.

version: '3.3'
services:
  nginx:
    image: nginx:alpine
    container_name: reverseproxy
    depends_on:
      - layout
      - custom-template
    volumes:
      - ${NGINX_CONF_FILE}:/etc/nginx/nginx.conf
    ports:
      - "5000:5000"
  layout:
    container_name: azure-cognitive-service-layout
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest
    environment:
      eula: accept
      apikey: ${FORM_RECOGNIZER_KEY}
      billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
      Logging:Console:LogLevel:Default: Information
      SharedRootFolder: /share
      Mounts:Shared: /share
      Mounts:Output: /logs
    volumes:
      - type: bind
        source: ${SHARED_MOUNT_PATH}
        target: /share
      - type: bind
        source: ${OUTPUT_MOUNT_PATH}
        target: /logs
    expose:
      - "5000"

  custom-template:
    container_name: azure-cognitive-service-custom-template
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/custom-template-3.0:latest
    restart: always
    depends_on:
      - layout
    environment:
      AzureCognitiveServiceLayoutHost: http://azure-cognitive-service-layout:5000
      eula: accept
      apikey: ${FORM_RECOGNIZER_KEY}
      billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
      Logging:Console:LogLevel:Default: Information
      SharedRootFolder: /share
      Mounts:Shared: /share
      Mounts:Output: /logs
    volumes:
      - type: bind
        source: ${SHARED_MOUNT_PATH}
        target: /share
      - type: bind
        source: ${OUTPUT_MOUNT_PATH}
        target: /logs
    expose:
      - "5000"

  studio:
    container_name: form-recognizer-studio
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/studio:3.0
    environment:
      ONPREM_LOCALFILE_BASEPATH: /onprem_folder
      STORAGE_DATABASE_CONNECTION_STRING: /onprem_db/Application.db
    volumes:
      - type: bind
        source: ${FILE_MOUNT_PATH} # path to your local folder
        target: /onprem_folder
      - type: bind
        source: ${DB_MOUNT_PATH} # path to your local folder
        target: /onprem_db
    ports:
      - "5001:5001"
    user: "1000:1000" # echo $(id -u):$(id -g)

Criar um arquivo docker compose

  1. Nomeie esse arquivo como docker-compose.yml

  2. O exemplo de código a seguir é um exemplo independente docker compose para executar os contêineres de modelo Document Intelligence Layout, Studio e Custom juntos. Com docker compose, um arquivo YAML é usado para configurar os serviços do aplicativo. Em seguida, você cria e inicia todos os serviços com base na sua configuração com o comando docker-compose up.

version: '3.3'
services:
  nginx:
    image: nginx:alpine
    container_name: reverseproxy
    depends_on:
      - layout
      - custom-template
    volumes:
      - ${NGINX_CONF_FILE}:/etc/nginx/nginx.conf
    ports:
      - "5000:5000"
  layout:
    container_name: azure-cognitive-service-layout
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.1:latest
    environment:
      eula: accept
      apikey: ${FORM_RECOGNIZER_KEY}
      billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
      Logging:Console:LogLevel:Default: Information
      SharedRootFolder: /share
      Mounts:Shared: /share
      Mounts:Output: /logs
    volumes:
      - type: bind
        source: ${SHARED_MOUNT_PATH}
        target: /share
      - type: bind
        source: ${OUTPUT_MOUNT_PATH}
        target: /logs
    expose:
      - "5000"

  custom-template:
    container_name: azure-cognitive-service-custom-template
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/custom-template-3.1:latest
    restart: always
    depends_on:
      - layout
    environment:
      AzureCognitiveServiceLayoutHost: http://azure-cognitive-service-layout:5000
      eula: accept
      apikey: ${FORM_RECOGNIZER_KEY}
      billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
      Logging:Console:LogLevel:Default: Information
      SharedRootFolder: /share
      Mounts:Shared: /share
      Mounts:Output: /logs
    volumes:
      - type: bind
        source: ${SHARED_MOUNT_PATH}
        target: /share
      - type: bind
        source: ${OUTPUT_MOUNT_PATH}
        target: /logs
    expose:
      - "5000"

  studio:
    container_name: form-recognizer-studio
    image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/studio:3.1
    environment:
      ONPREM_LOCALFILE_BASEPATH: /onprem_folder
      STORAGE_DATABASE_CONNECTION_STRING: /onprem_db/Application.db
    volumes:
      - type: bind
        source: ${FILE_MOUNT_PATH} # path to your local folder
        target: /onprem_folder
      - type: bind
        source: ${DB_MOUNT_PATH} # path to your local folder
        target: /onprem_db
    ports:
      - "5001:5001"
    user: "1000:1000" # echo $(id -u):$(id -g)

O contêiner de modelo personalizado e o contêiner de layout podem usar filas do Armazenamento do Microsoft Azure ou filas na memória. As variáveis de ambiente Storage:ObjectStore:AzureBlob:ConnectionString e queue:azure:connectionstring só precisam ser definidas se você estiver usando as filas de Armazenamento do Microsoft Azure. Ao executar localmente, exclua essas variáveis.

Certifique-se que o serviço esteja em execução

Para garantir que o serviço está em execução. Execute esses comandos em um shell do Ubuntu.

$cd <folder containing the docker-compose file>

$source .env

$docker-compose up

Os contêineres de modelo personalizados exigem algumas configurações diferentes e dão suporte a outras configurações opcionais.

Configuração Obrigatório Descrição
EULA Sim Exemplo de aceitação de licença: Eula=accept
Cobrança Sim URI do ponto de extremidade de cobrança do recurso FR
ApiKey Sim A chave de ponto final do recurso FR
Queue:Azure:ConnectionString Não Cadeia de conexão da fila do Azure
Storage:ObjectStore:AzureBlob:ConnectionString Não Cadeia de conexão do Blob do Azure
Verificação de Saúde:Limite Superior de Memória em MB Não Limite de memória para relatar problemas de integridade à atividade. Padrão: o mesmo que a memória recomendada
StorageTimeToLiveInMinutes Não TTL duração para remover todos os arquivos intermediários e finais. Padrão: dois dias, o TTL pode ser definido entre cinco minutos e sete dias
Task:MaxRunningTimeSpanInMinutes Não Tempo máximo de execução para tratar a solicitação como timeout. Padrão: 60 minutos
HTTP_PROXY_BYPASS_URLS Não Exemplo de especificação de URLs para ignorar o proxy: HTTP_PROXY_BYPASS_URLS = abc.com, xyz.com
AzureCognitiveServiceReadHost (somente contêineres Receipt e IdDocument) Sim Exemplo de especificação de URI do contêiner de leitura: AzureCognitiveServiceReadHost=http://onprem-frread:5000
AzureCognitiveServiceLayoutHost (apenas contêineres de documentos e faturas) Sim Exemplo de especificação de URI do contêiner: AzureCognitiveServiceLayoutHost=http://onprem-frlayout:5000

Utilize o Estúdio de Informação de Documentos para treinar um modelo

  • Reúna um conjunto de pelo menos cinco formas do mesmo tipo. Você usará esses dados para treinar o modelo e testar um formulário. Você usar um conjunto de dados de exemplo (baixar e extrair sample_data.zip).

  • Uma vez confirmado que os contêineres estão em execução, abra um navegador e navegue até o ponto de extremidade em que os contêineres estão implantados. Se esta implantação for seu computador local, o ponto de extremidade será [http://localhost:5001](http://localhost:5001).

  • Selecione o bloco do modelo de extração personalizada.

  • Selecione a opção Create project.

  • Forneça um nome de projeto e, opcionalmente, uma descrição

  • Na etapa "configurar seu recurso", forneça o ponto de extremidade para seu modelo de modelo personalizado. Se você implantou os contêineres no seu computador local, use esta URL [http://localhost:5000](http://localhost:5000).

  • Forneça uma subpasta na qual os dados de treinamento estejam localizados na pasta de arquivos.

  • Finalmente, crie o projeto

Neste momento, você deve ter um projeto criado, pronto para rotulagem. Faça upload de seus dados de treinamento e comece a rotular. Se você é novo na rotulagem, consulte criar e treinar um modelo personalizado.

Usando a API para treinar

Se você planeja chamar as APIs diretamente para treinar um modelo, a API de treinamento de modelo do modelo personalizado requer um arquivo ZIP codificado em base64 que é o conteúdo do seu projeto de rotulagem. Você pode omitir os arquivos PDF ou de imagem e enviar somente os arquivos JSON.

Depois de ter seu conjunto de dados rotulado e arquivos * .ocr.json, * .labels.json e fields.json adicionados a um ZIP, use os comandos do PowerShell para gerar a cadeia de caracteres codificada em base64.

$bytes = [System.IO.File]::ReadAllBytes("<your_zip_file>.zip")
$b64String = [System.Convert]::ToBase64String($bytes, [System.Base64FormattingOptions]::None)

Use a API do modelo de compilação para postar a solicitação.


  POST http://localhost:5000/formrecognizer/documentModels:build?api-version=2023-07-31

  {
      "modelId": "mymodel",
      "description": "test model",
      "buildMode": "template",

      "base64Source": "<Your base64 encoded string>",
      "tags": {
         "additionalProp1": "string",
         "additionalProp2": "string",
         "additionalProp3": "string"
       }
  }

Confirme se o servidor está em execução

Há várias maneiras de validar se um contêiner está em execução:

  • O contêiner fornece uma home page em \ como uma validação visual de que o contêiner está em execução.

  • Você pode abrir seu navegador da Web favorito e navegar até o endereço IP externo e a porta exposta do contêiner em questão. Use as URLs de solicitação listadas para validar se o contêiner está em execução. As URLs de solicitação de exemplo listadas são http://localhost:5000, mas o seu contêiner específico pode variar. Tenha em mente que você está navegando para o Endereço IP externo do seu contêiner e para a porta exposta.

    URL de Solicitação Finalidade
    http:// localhost:5000/ O contêiner oferece uma home page.
    http:// localhost:5000/ready Solicitado com GET, essa solicitação 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 sondagens de atividade e prontidão do Kubernetes.
    http:// localhost:5000/status Solicitado com GET, essa solicitação 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 sondagens de atividade e prontidã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 "Experimente". 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. Depois que a consulta é retornada, um exemplo de comando CURL é fornecido para demonstrar o formato do corpo e dos cabeçalhos HTTP exigidos.

Captura de tela da página de boas-vindas dos contêineres do Azure.

Parar os contêineres

Para parar o contêiner, use o seguinte comando:

docker-compose down

Cobrança

Os contêineres de Informação de Documentos enviam informações de cobrança para o Azure utilizando um recurso de Informação de Documentos na sua conta do Azure.

Consultas para o contêiner são cobradas pelo tipo de preço do recurso do Azure usado para a API Key. A cobrança é calculada por cada instância de contêiner usada para processar seus documentos e imagens.

Se você receber este erro: O contêiner não está em um estado válido. Falha na validação da assinatura com o status "OutOfQuota". A chave de API excedeu a cota. É um indicador de que seus contêineres não estão se comunicando com o endpoint de faturamento.

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. Consulte as perguntas frequentes sobre o contêiner do Azure para obter um exemplo das informações enviadas à Microsoft para cobrança.

Argumentos de cobrança

O comando docker-compose up 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 do recurso de Serviços de IA usada para acompanhar as informações de cobrança.
O valor dessa opção deve ser definido como uma chave para o recurso provisionado especificado em Billing.
Billing O ponto de extremidade do recurso de serviços de IA 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

É isso! Neste artigo, você aprendeu conceitos e fluxos de trabalho para baixar, instalar e executar os contêineres da Informação de Documentos. Em resumo:

  • A Informação de Documentos fornece sete contêineres Linux para o Docker.
  • As imagens de contêiner são baixadas do mcr.
  • Imagens de contêiner são executadas no Docker.
  • A informações de cobrança devem ser especificadas quando você instanciar um contêiner.

Importante

Os contêineres do Azure não são licenciados para execução sem serem conectados ao Azure para medição. Os clientes precisam permitir que os contêineres sempre comuniquem as informações de cobrança com o serviço de medição. Os contêineres 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

  • Last updated on