Contêineres em ambientes desconectados (offline)

Artigo
11/19/2024

O Document Intelligence não oferece suporte a contêineres para v4.0. Atualmente, o suporte de contêineres está disponível na versão 2022-08-31 (GA) do Informação de Documentos para todos os modelos e 2023-07-31 (GA) nos modelos de documentos de leitura, layout, fatura, recibo e ID:

✔️ Consulte Contêineres do Document Intelligence v3.0 em ambientes desconectados ou Contêineres do Document Intelligence v3.1 em ambientes desconectados para obter versões com suporte da documentação do contêiner.

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

O que são contêineres desconectados?

Os Contêineres de IA do Azure oferecem a flexibilidade de executar alguns serviços de Informação de Documentos localmente em contêineres. Os contêineres conectados são executados localmente em seu ambiente e enviam informações de uso para a nuvem para cobrança. Os contêineres desconectados são destinados a cenários em que nenhuma conectividade com a nuvem é necessária para que os contêineres sejam executados.

Os contêineres da IA do Azure para Informação de Documentos permitem que você use as APIs da Informação de Documentos com os benefícios da conteinerização. Os contêineres desconectados são oferecidos por meio do preço do nível de compromisso oferecido a uma taxa com desconto, em comparação ao preço de pagamento conforme o uso. Com o nível de preços de compromisso, você pode se comprometer a usar os recursos de Informação de Documentos por um valor fixo, a um custo total previsível, com base nas necessidades de sua carga de trabalho.

Introdução

Antes de tentar executar um contêiner do Docker em um ambiente offline, verifique se você conhece os requisitos a seguir para baixar e usar o contêiner com êxito:

Recomendações e requisitos do computador host.
O comando pull do Docker para baixar o contêiner.
Como validar que um contêiner está em execução.
Como enviar consultas para o ponto de extremidade do contêiner, depois que ele estiver em execução.

Solicitar acesso para usar contêineres em ambientes desconectados

Antes de usar os contêineres de Informação de Documentos em ambientes desconectados, primeiro preencha e envie um formulário de solicitação e compre um plano de compromisso.

Crie um novo recurso no portal do Azure

Comece provisionando um novo recurso no portal.

Certifique-se de selecionar a opção Commitment tier disconnected containers DC0 para o Tipo de Preço
Selecione o tipo de preço apropriado em pelo menos um dos níveis de compromisso personalizados, de leitura ou predefinidos

Contêiner	Mínimo	Recomendadas	Plano de compromisso
`Read`	`8` núcleos, 10 GB de memória	`8` núcleos, 24 GB de memória	`OCR` (Leia)
`Layout`	`8` núcleos, 16 GB de memória	`8` núcleos, 24 GB de memória	Predefinida
`Business Card`	`8` núcleos, 16 GB de memória	`8` núcleos, 24 GB de memória	Predefinida
`General Document`	`8` núcleos, 12 GB de memória	`8` núcleos, 24 GB de memória	Predefinida
`ID Document`	`8` núcleos, 8 GB de memória	`8` núcleos, 24 GB de memória	Predefinida
`Invoice`	`8` núcleos, 16 GB de memória	`8` núcleos, 24 GB de memória	Predefinida
`Receipt`	`8` núcleos, 11 GB de memória	`8` núcleos, 24 GB de memória	Predefinida
`Custom Template`	`8` núcleos, 16 GB de memória	`8` núcleos, 24 GB de memória	API Personalizada

Reunir os parâmetros necessários

Há três parâmetros necessários para todos os contêineres dos serviços de IA do Azure:

Os termos de licença precisam estar disponíveis e terem um valor de aceito.
A URL do ponto de extremidade do recurso no portal do Azure.
A chave de API do recurso no portal do Azure.

A URL de ponto de extremidade e a chave de API são necessárias quando você executa o contêiner pela primeira vez, para configurá-lo para uso desconectado. Encontre a chave e o ponto de extremidade na página de Chave e ponto de extremidade do recurso no portal do Azure:

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

Importante

Você usará somente a chave e o ponto de extremidade para configurar o contêiner para ser executado em um ambiente desconectado. Depois de configurar o contêiner, você não precisará dos valores de chave e ponto de extremidade para enviar solicitações de API. Armazene-as com segurança, por exemplo, usando o Azure Key Vault. Apenas uma chave é necessária para esse processo.

Baixar um contêiner do Docker com `docker pull`

Baixe o contêiner do Docker aprovado para ser executado em um ambiente desconectado. Por exemplo:

Comando do docker pull	Valor	Formatar
`docker pull [image]` ● ●`docker pull [image]latest`	A imagem de contêiner mais recente.	`mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest` ● ● `mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice-3.0:latest`

Exemplo do comando docker pull

docker pull mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice:latest

Configurar o contêiner a ser executado em um ambiente desconectado

As imagens de contêiner desconectado são iguais às imagens de contêineres conectados. A principal diferença é que os contêineres desconectados exigem um arquivo de licença. O download desse arquivo de licença é feito ao iniciar o contêiner em um modo conectado com o parâmetro downloadLicense definido como true.

Agora que o contêiner foi baixado, você precisa executar o comando docker run com o seguinte parâmetro:

DownloadLicense=True. Esse parâmetro baixa um arquivo de licença que permite 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 ficará inválido para executar o contêiner. Você só pode usar o arquivo de licença no contêiner aprovado correspondente.

Importante

O comando docker run gerará um modelo que você pode usar para executar o contêiner. O modelo contém os parâmetros necessários para os modelos baixados e o arquivo de configuração. Lembre-se de salvar este modelo.

O exemplo a seguir mostra a formatação do comando docker run a ser usado com os valores de espaço reservado. Substitua os valores do espaço reservado pelos seus.

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 é 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 seu recurso da Informação de Documentos. É possível encontrá-lo na página de Chave e ponto de extremidade do recurso, no portal do Azure.	`{string}`
`{CONTAINER_LICENSE_DIRECTORY}`	Local da pasta de licença no sistema de arquivos local do contêiner.	`/path/to/license/directory`

Exemplo do comando docker run


docker run --rm -it -p 5000:5050 \

-v {LICENSE_MOUNT} \

{IMAGE} \

eula=accept \

billing={ENDPOINT_URI} \

apikey={API_KEY} \

DownloadLicense=True \

Mounts:License={CONTAINER_LICENSE_DIRECTORY}

No comando a seguir, substitua os espaços reservados para o caminho da pasta, o ponto de extremidade de cobrança e a chave de API para baixar um arquivo de licença para o contêiner de layout.

docker run -v {folder path}:/license --env Mounts:License=/license --env DownloadLicense=True --env Eula=accept --env Billing={billing endpoint} --env ApiKey={api key} mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest

Depois que o contêiner for configurado, use a próxima seção para executar o contêiner em seu ambiente com a licença e as alocações apropriadas de memória e CPU.

Modelos e configurações de contêineres de Informação de Documentos

Depois de configurar o contêiner, os valores para os modelos de Informação de Documentos baixados e a configuração de contêiner serão gerados e exibidos na saída do contêiner.

Executar o contêiner em um ambiente desconectado

Depois de baixar o arquivo de licença, você pode executar o contêiner em um ambiente desconectado com sua licença, memória apropriada e alocações de CPU adequadas. O exemplo a seguir mostra a formatação do comando docker run, com os valores de espaço reservado. Substitua os valores dos espaços reservados 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=. Além disso, uma montagem de saída 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 está localizada e 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`

Exemplo do comando docker run

docker run --rm -it -p 5000:5050 --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}

Iniciar um contêiner desconectado é semelhante a iniciar um contêiner conectado. Os contêineres desconectados exigem um parâmetro de licença adicional. Aqui está uma amostra de arquivo docker-compose.yml para iniciar um contêiner personalizado no modo desconectado. Adicione a variável de ambiente CUSTOM_LICENSE_MOUNT_PATH com um valor definido para a pasta que contém o arquivo de licença baixado e a variável de ambiente OUTPUT_MOUNT_PATH com um valor definido para a pasta que contém os logs de uso.

version: '3.3'
services:
 nginx:
  image: nginx:alpine
  container_name: reverseproxy
  volumes:
    - ${NGINX_CONF_FILE}:/etc/nginx/nginx.conf
  ports:
    - "5000:5050"
 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: /shared
    Mounts:Shared: /shared
    Mounts:Output: /logs
    Mounts:License: /license
  volumes:
    - type: bind
      source: ${SHARED_MOUNT_PATH}
      target: /shared
    - type: bind
      source: ${OUTPUT_MOUNT_PATH}
      target: /logs
    - type: bind
      source: ${LAYOUT_LICENSE_MOUNT_PATH}
      target: /license
  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: /shared
    Mounts:Shared: /shared
    Mounts:Output: /logs
    Mounts:License: /license
  volumes:
    - type: bind
      source: ${SHARED_MOUNT_PATH}
      target: /shared
    - type: bind
      source: ${OUTPUT_MOUNT_PATH}
      target: /logs
    - type: bind
      source: ${CUSTOM_LICENSE_MOUNT_PATH}
      target: /license
  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)

Outros parâmetros e comandos

Aqui estão mais alguns parâmetros e comandos necessários para executar o contêiner.

Registros de uso

Ao operar os contêineres do Docker em um ambiente desconectado, o contêiner gravará os registros de uso em um volume no qual eles são coletados ao longo do tempo. Você também pode chamar um ponto de extremidade da API REST para gerar um relatório sobre a utilização do serviço.

Argumentos para armazenar logs

Quando executado em um ambiente desconectado, uma montagem de saída precisa estar disponível para o contêiner para armazenar os logs de uso. Por exemplo, você incluiria -v /host/output:{OUTPUT_PATH} e Mounts:Output={OUTPUT_PATH} no exemplo a seguir, substituindo {OUTPUT_PATH} pelo caminho em que os logs são armazenados:

docker run -v /host/output:{OUTPUT_PATH} ... <image> ... Mounts:Output={OUTPUT_PATH}

Obter registros usando os pontos de extremidade do contêiner

O contêiner fornece dois pontos de extremidade para retornar registros sobre o uso.

Obter todos os registros

O ponto de extremidade a seguir fornece um relatório com o resumo de todo o uso coletado no diretório de registro de cobrança montado.

https://<service>/records/usage-logs/

Exemplo de ponto de extremidade HTTPS

http://localhost:5000/records/usage-logs

O ponto de extremidade de usage-log retorna uma resposta JSON semelhante ao seguinte exemplo:

{
  "apiType": "string",
  "serviceName": "string",
  "meters": [
    {
      "name": "string",
      "quantity": 256345435
    }
  ]
}

Obter registros de um mês específico

O ponto de extremidade a seguir fornece um relatório com o resumo do uso em um mês e ano específicos.

https://<service>/records/usage-logs/{MONTH}/{YEAR}

Esse ponto de extremidade de logs de uso retorna uma resposta JSON semelhante ao seguinte exemplo:

{
  "apiType": "string",
  "serviceName": "string",
  "meters": [
    {
      "name": "string",
      "quantity": 56097
    }
  ]
}

Solução de problemas

Execute o contêiner com uma montagem de saída e o registro habilitados. Essas configurações permitem que o contêiner gere arquivos de log ú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 solução de problemas, confira Perguntas frequentes sobre os contêineres dos desconectados.

Compartilhar via

Contêineres em ambientes desconectados (offline)

O que são contêineres desconectados?

Introdução

Solicitar acesso para usar contêineres em ambientes desconectados

Crie um novo recurso no portal do Azure

Reunir os parâmetros necessários

Baixar um contêiner do Docker com `docker pull`

Configurar o contêiner a ser executado em um ambiente desconectado

Modelos e configurações de contêineres de Informação de Documentos

Executar o contêiner em um ambiente desconectado

Outros parâmetros e comandos

Registros de uso

Argumentos para armazenar logs

Obter registros usando os pontos de extremidade do contêiner

Obter todos os registros

Obter registros de um mês específico

Solução de problemas

Próximas etapas

Comentários

Recursos adicionais

Compartilhar via

Contêineres em ambientes desconectados (offline)

O que são contêineres desconectados?

Introdução

Solicitar acesso para usar contêineres em ambientes desconectados

Crie um novo recurso no portal do Azure

Reunir os parâmetros necessários

Baixar um contêiner do Docker com docker pull

Configurar o contêiner a ser executado em um ambiente desconectado

Modelos e configurações de contêineres de Informação de Documentos

Executar o contêiner em um ambiente desconectado

Outros parâmetros e comandos

Registros de uso

Argumentos para armazenar logs

Obter registros usando os pontos de extremidade do contêiner

Obter todos os registros

Obter registros de um mês específico

Solução de problemas

Próximas etapas

Comentários

Recursos adicionais

Baixar um contêiner do Docker com `docker pull`