Contenitori in ambienti disconnessi (offline)

Articolo
09/01/2024

Il supporto per i contenitori è attualmente disponibile con la versione 2022-08-31 (GA) di Document Intelligence per tutti i modelli e 2023-07-31 (GA) per i modelli lettura, layout, fattura, ricevuta e documento ID:

✔️ 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

Contenitore	Requisiti minimi	Requisiti consigliati	Piano di impegno
`Read`	`8` core, 10 GB di memoria	`8` core, 24 GB di memoria	`OCR` (Lettura)
`Layout`	`8` core, 16 GB di memoria	`8` core, 24 GB di memoria	Predefinito
`Business Card`	`8` core, 16 GB di memoria	`8` core, 24 GB di memoria	Predefinito
`General Document`	`8` core, 12 GB di memoria	`8` core, 24 GB di memoria	Predefinito
`ID Document`	`8` core, 8 GB di memoria	`8` core, 24 GB di memoria	Predefinito
`Invoice`	`8` core, 16 GB di memoria	`8` core, 24 GB di memoria	Predefinito
`Receipt`	`8` core, 11 GB di memoria	`8` core, 24 GB di memoria	Predefinito
`Custom Template`	`8` core, 16 GB di memoria	`8` core, 24 GB di memoria	API personalizzata

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:

Screenshot della pagina delle chiavi e dell'endpoint del portale di Azure.

Importante

Si userà solo la chiave e l'endpoint per configurare il contenitore per l'esecuzione in un ambiente disconnesso. Dopo aver configurato il contenitore, non saranno necessari i valori della chiave e dell'endpoint per inviare richieste API. Archiviarle in una posizione sicura, ad esempio usando Azure Key Vault. Per questo processo è necessaria una sola chiave.

Scaricare un contenitore Docker con `docker pull`

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

Comando docker pull	Valore	Formato
● ● ● `docker pull [image]` `docker pull [image]latest`	Immagine del contenitore più 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`

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.

Importante

Il comando docker run genererà un modello che è possibile usare per eseguire il contenitore. Il modello contiene i parametri necessari per i modelli e il file di configurazione scaricati. Assicurarsi di salvare questo modello.

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.

Segnaposto	Valore	Formato o esempio
`{IMAGE}`	L’immagine del contenitore da usare.	`mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice`
`{LICENSE_MOUNT}`	Il percorso in cui viene scaricata e montata la licenza.	`/host/license:/path/to/license/directory`
`{ENDPOINT_URI}`	L’endpoint per l'autenticazione della richiesta di servizio. È disponibile nella pagina Chiave ed endpoint della risorsa nel portale di Azure.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{API_KEY}`	Chiave per la risorsa di Document Intelligence. È disponibile nella pagina Chiave ed endpoint della risorsa nel portale di Azure.	`{string}`
`{CONTAINER_LICENSE_DIRECTORY}`	Percorso della cartella di licenza nel file system locale del contenitore.	`/path/to/license/directory`

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.

Segnaposto	Valore	Formato o esempio
`{IMAGE}`	L’immagine del contenitore da usare.	`mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice`
`{MEMORY_SIZE}`	Dimensioni appropriate della memoria da allocare per il contenitore.	`4g`
`{NUMBER_CPUS}`	Il numero appropriato di CPU da allocare per il contenitore.	`4`
`{LICENSE_MOUNT}`	Il percorso in cui viene collocata e montata la licenza.	`/host/license:/path/to/license/directory`
`{OUTPUT_PATH}`	Percorso di output per la registrazione dei record di utilizzo.	`/host/output:/path/to/output/directory`
`{CONTAINER_LICENSE_DIRECTORY}`	Percorso della cartella di licenza nel file system locale del contenitore.	`/path/to/license/directory`
`{CONTAINER_OUTPUT_DIRECTORY}`	Percorso della cartella di output nel file system locale del contenitore.	`/path/to/output/directory`

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.

Suggerimento

Per altre informazioni sulla risoluzione dei problemi e indicazioni, vedere Domande frequenti sui contenitori disconnessi.

Condividi tramite

Contenitori in ambienti disconnessi (offline)

Che cosa sono i contenitori disconnessi?

Operazioni preliminari

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

Creare una nuova risorsa nel portale di Azure

Raccogliere i parametri necessari

Scaricare un contenitore Docker con `docker pull`

Configurare il contenitore da eseguire in un ambiente disconnesso

Modelli di contenitore e configurazione di Document Intelligence

Eseguire il contenitore in un ambiente disconnesso

Altri parametri e comandi

Record di utilizzo

Argomenti per l'archiviazione dei log

Ottenere record usando gli endpoint del contenitore

Ottenere tutti i record

Ottenere record per un mese specifico

Risoluzione dei problemi

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Contenitori in ambienti disconnessi (offline)

Che cosa sono i contenitori disconnessi?

Operazioni preliminari

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

Creare una nuova risorsa nel portale di Azure

Raccogliere i parametri necessari

Scaricare un contenitore Docker con docker pull

Configurare il contenitore da eseguire in un ambiente disconnesso

Modelli di contenitore e configurazione di Document Intelligence

Eseguire il contenitore in un ambiente disconnesso

Altri parametri e comandi

Record di utilizzo

Argomenti per l'archiviazione dei log

Ottenere record usando gli endpoint del contenitore

Ottenere tutti i record

Ottenere record per un mese specifico

Risoluzione dei problemi

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Scaricare un contenitore Docker con `docker pull`