Contenitori in ambienti disconnessi (offline)

Il supporto per i contenitori è attualmente disponibile con la versione di Informazioni sui documenti 2022-08-31 (GA) per tutti i modelli e 2023-07-31 (GA) per i modelli lettura, layout, fattura, ricevuta e documento di identità:

• API REST2022-08-31 (GA)
• API REST2023-07-31 (GA)
• SDK con destinazione REST API 2022-08-31 (GA)
• SDK con destinazione REST API 2023-07-31 (GA)

✔️ Per la documentazione sui contenitori supportati, vedere Document Intelligence v3.0 containers in disconnected environments (Contenitori di Document Intelligence v3.0 in ambienti disconnessi).

Questo contenuto si applica a: v3.0 (disponibilità generale) v3.1 (disponibilità generale)

Che cosa sono i contenitori disconnessi?

I contenitori di Intelligenza artificiale di Azure offrono la flessibilità necessaria per eseguire alcuni servizi di Intelligence documenti in locale nei contenitori. I contenitori connessi vengono eseguiti localmente nell'ambiente e inviano informazioni sull'utilizzo al cloud per la fatturazione. I contenitori disconnessi sono destinati agli scenari in cui non è necessaria alcuna connettività con il cloud per l'esecuzione dei contenitori.

I contenitori di Document Intelligence per intelligenza artificiale di Azure consentono di usare le API di Document Intelligence con i vantaggi della containerizzazione. I contenitori disconnessi vengono offerti a prezzi scontati rispetto a quelli con pagamento in base al consumo mediante una tariffa di impegno. Con i prezzi del piano di impegno, è possibile impegnarsi a usare le funzionalità di Document Intelligence per una tariffa fissa, a un costo totale prevedibile, in base alle esigenze del carico di lavoro.

Operazioni preliminari

Prima di tentare di eseguire un contenitore Docker in un ambiente offline, assicurarsi di avere familiarità con i requisiti seguenti per scaricare e usare correttamente il contenitore:

• Requisiti e raccomandazioni del computer host.
• Comando Docker pull per scaricare il contenitore.
• Come verificare che un contenitore sia in esecuzione.
• Come inviare query all'endpoint del contenitore, dopo l'esecuzione.

Richiedere l'accesso per l'uso di contenitori in ambienti disconnessi

Prima di poter usare i contenitori di Document Intelligence in ambienti disconnessi, è necessario compilare e inviare un modulo di richiesta e acquistare un piano di impegno.

Creare una nuova risorsa nel portale di Azure

Per iniziare, effettuare il provisioning di una nuova risorsa nel portale.

• Assicurarsi di selezionare l'opzione Commitment tier disconnected containers DC0 Piano tariffario

• Selezionare il piano tariffario appropriato da almeno uno dei livelli di impegno personalizzati, letti o predefiniti

  

Raccogliere i parametri necessari

Esistono tre parametri obbligatori per tutti i contenitori dei Servizi di Azure AI:

• Il contratto di licenza con l'utente finale (EULA) deve essere presente con il valore accettare.
• URL dell'endpoint per la risorsa dal portale di Azure.
• Chiave API per la risorsa dal portale di Azure.

Sia l'URL dell'endpoint che la chiave API sono necessari quando si esegue per la prima volta il contenitore per configurarlo per l'utilizzo disconnesso. È possibile trovare la chiave e l'endpoint nella pagina Chiave ed endpoint per la risorsa nel portale di Azure:

Scaricare un contenitore Docker con docker pull

Scaricare il contenitore Docker approvato per l'esecuzione in un ambiente disconnesso. Ad esempio:

Esempio di comando docker pull

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

Configurare il contenitore da eseguire in un ambiente disconnesso

Le immagini dei contenitori disconnesse sono le stesse dei contenitori connessi. La differenza principale consiste nel fatto che i contenitori disconnessi richiedono un file di licenza. Questo file di licenza viene scaricato avviando il contenitore in modalità connessa con il parametro downloadLicense impostato su true.

Dopo aver scaricato il contenitore, è necessario eseguire il docker run comando con il parametro seguente:

• DownloadLicense=True. Questo parametro scarica un file di licenza che consente l'esecuzione del contenitore Docker quando non è connesso a Internet. Contiene anche una data di scadenza dopo la quale il file di licenza non sarà valido per l’esecuzione del contenitore. È possibile usare il file di licenza solo nel contenitore approvato corrispondente.

Nell'esempio seguente viene illustrata la formattazione del docker run comando da usare con i valori segnaposto. Sostituire questi valori segnaposto con i propri valori.

Comando docker run di esempio

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}

Nel comando seguente sostituire i segnaposto per il percorso della cartella, l'endpoint di fatturazione e la chiave API per scaricare un file di licenza per il contenitore di 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

Dopo aver configurato il contenitore, usare la sezione successiva per eseguire il contenitore nell'ambiente con la licenza e le allocazioni di memoria e CPU appropriate.

Modelli di contenitore e configurazione di Document Intelligence

Dopo aver configurato il contenitore, i valori per i modelli di Document Intelligence scaricati e la configurazione del contenitore verranno generati e visualizzati nell'output del contenitore.

Eseguire il contenitore in un ambiente disconnesso

Dopo aver scaricato il file di licenza, è possibile eseguire il contenitore in un ambiente disconnesso con la licenza, la memoria appropriata e le allocazioni di CPU appropriate. Nell'esempio seguente viene illustrata la formattazione del comando docker run da usare, con valori segnaposto. Sostituire questi valori segnaposto con i propri valori.

Ogni volta che viene eseguito il contenitore, il file di licenza deve essere montato nel contenitore e il percorso della cartella di licenza nel file system locale del contenitore deve essere specificato con Mounts:License=. Inoltre, è necessario specificare un montaggio di output in modo che i record di utilizzo della fatturazione possano essere scritti.

Comando docker run di esempio

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}

L'avvio di un contenitore disconnesso è simile all'avvio di un contenitore connesso. I contenitori disconnessi richiedono un parametro di licenza aggiunto. Ecco un file di esempio docker-compose.yml per avviare un contenitore personalizzato in modalità disconnessa. Aggiungere la variabile di ambiente CUSTOM_LICENSE_MOUNT_PATH con un valore impostato sulla cartella contenente il file di licenza scaricato e la OUTPUT_MOUNT_PATH variabile di ambiente con un valore impostato sulla cartella contenente i log di utilizzo.

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)

Altri parametri e comandi

Ecco alcuni altri parametri e comandi necessari per eseguire il contenitore.

Record di utilizzo

Quando si usano contenitori Docker in un ambiente disconnesso, il contenitore scriverà i record di utilizzo in un volume in cui vengono raccolti nel tempo. È anche possibile chiamare un endpoint DELL'API REST per generare un report sull'utilizzo del servizio.

Argomenti per l'archiviazione dei log

Quando viene eseguito in un ambiente disconnesso, un montaggio di output deve essere disponibile per il contenitore per archiviare i log di utilizzo. Ad esempio, è necessario includere -v /host/output:{OUTPUT_PATH} e Mounts:Output={OUTPUT_PATH} nell'esempio seguente, sostituendo {OUTPUT_PATH} con il percorso in cui sono archiviati i log:

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

Ottenere record usando gli endpoint del contenitore

Il contenitore fornisce due endpoint per la restituzione di record relativi all'utilizzo.

Ottenere tutti i record

L'endpoint seguente fornisce un report che riepiloga tutti gli utilizzi raccolti nella directory dei record di fatturazione montata.

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

Endpoint HTTPS di esempio

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

L'endpoint usage-log restituisce una risposta JSON simile all'esempio seguente:

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

Ottenere record per un mese specifico

L'endpoint seguente fornisce un report che riepiloga l'utilizzo in un mese e un anno specifici.

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

Questo endpoint usage-logs restituisce una risposta JSON simile all'esempio seguente:

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

Risoluzione dei problemi

Eseguire il contenitore con un montaggio di output e la registrazione abilitati. Queste impostazioni abilitano il contenitore genera file di log utili per la risoluzione dei problemi che si verificano durante l'avvio o l'esecuzione del contenitore.

Passaggi successivi

• Distribuire lo Strumento di etichettatura campioni in un'istanza di Azure Container
• Modificare o terminare un piano di impegno