Installare il contenitore Lettura OCR 3.2 con disponibilità generale di Visione di Azure AI

I contenitori consentono di eseguire le API di Visione di Azure AI nell'ambiente in uso e possono aiutare a soddisfare i requisiti di sicurezza e governance dei dati specifici. In questo articolo si apprenderà come scaricare, installare ed eseguire il contenitore Lettura (OCR) di Visione di Azure AI.

Il contenitore Lettura consente di estrarre testo stampato e scritto a mano da immagini e documenti nei formati di file JPEG, PNG, BMP, PDF e TIFF. Per informazioni dettagliate sul servizio Lettura, vedere la Guida pratica dell'API Lettura.

Novità

La versione 3.2-model-2022-04-30 disponibile a livello generale del contenitore Lettura include il supporto per 164 lingue e altri miglioramenti. Per iniziare, i clienti esistenti possono seguire le istruzioni di download.

Il contenitore Lettura OCR 3.2 è il modello disponibile a livello generale più recente e fornisce:

• Nuovi modelli per maggiore accuratezza.
• Supporto per più lingue all'interno dello stesso documento.
• Supporto per un totale di 164 lingue. Vedere l'elenco completo delle lingue supportate dal riconoscimento ottico dei caratteri (OCR).
• Singola operazione per documenti e immagini.
• Supporto per documenti e immagini di dimensioni maggiori.
• Punteggi di attendibilità.
• Supporto per documenti con testo stampato e scritto a mano.
• Possibilità di estrarre testo solo da pagine selezionate in un documento.
• Possibilità di cambiare l'ordine di output delle righe di testo predefinito con un ordine di lettura più naturale solo per le lingue latine.
• Classificazione delle righe di testo come stile scritto a mano o meno solo per le lingue latine.

Se attualmente si stanno usando i contenitori Lettura 2.0, vedere la guida alla migrazione per informazioni sulle modifiche introdotte nelle nuove versioni.

Prerequisiti

Prima di usare i contenitori, è necessario soddisfare i prerequisiti seguenti:

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Raccogliere i parametri necessari

Sono necessari tre parametri principali per tutti i contenitori di Intelligenza artificiale di Azure. Le condizioni di licenza per il software Microsoft devono essere presenti con un valore di accettazione. Sono necessari anche un URI dell’endpoint e una chiave API.

URI endpoint

Il valore {ENDPOINT_URI} è disponibile nella pagina Panoramica del portale di Azure della risorsa di Servizi di Azure AI corrispondente. Accedere alla pagina Panoramica e passare il puntatore del mouse sull'endpoint. Verrà visualizzata un'icona Copia negli Appunti . Copiare e usare l'endpoint se necessario.

Chiavi

Il valore {API_KEY} viene usato per avviare il contenitore ed è disponibile nella pagina Chiavi del portale di Azure della risorsa di Servizi di Azure AI corrispondente. Accedere alla pagina Chiavi e selezionare l'icona Copia negli Appunti .

Requisiti per il computer host

L'host è un computer basato su x64 che esegue il contenitore Docker. Può essere un computer dell'ambiente locale o un servizio di hosting Docker in Azure, tra cui:

• Servizio Azure Kubernetes.
• Istanze di Azure Container.
• Cluster Kubernetes distribuito in Azure Stack. Per altre informazioni, vedere Deploy Kubernetes to Azure Stack (Distribuire Kubernetes in Azure Stack).

Supporto per Advanced Vector Extension

Il computer host è il computer che esegue il contenitore Docker. L'host deve supportare Advanced Vector Extensions (AVX2). È possibile verificare se AVX2 è supportato negli host Linux con il comando seguente:

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

Indicazioni e requisiti per i contenitori

La tabella seguente descrive l'allocazione minima e consigliata di risorse per ogni contenitore Lettura OCR.

• Ogni core deve essere di almeno 2,6 gigahertz (GHz) o superiore.

Core e memoria corrispondono alle impostazioni --cpus e --memory che vengono usate come parte del comando docker run.

Ottenere l'immagine del contenitore

L'immagine del contenitore Lettura OCR di Visione di Azure AI è disponibile nel registro contenitori mcr.microsoft.com. Si trova all'interno del repository azure-cognitive-services ed è denominata read. Il nome completo dell'immagine del contenitore è mcr.microsoft.com/azure-cognitive-services/vision/read.

Per usare la versione più recente del contenitore, è possibile usare il tag latest. È anche possibile trovare un elenco completo dei tag in Microsoft Container Registry.

Sono disponibili le immagini del contenitore seguenti per Lettura.

Usare il comando docker pull per scaricare un'immagine del contenitore.

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

docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

IMAGE ID         REPOSITORY                TAG
<image-id>       <repository-path/name>    <tag-name>

Come usare il contenitore

Dopo aver aggiunto il contenitore nel computer host, seguire questa procedura per usare il contenitore.

1. Eseguire il contenitore, con le impostazioni di fatturazione necessarie. Sono disponibili altri esempi del comando docker run.
2. Eseguire le query sull'endpoint di stima del contenitore.

Eseguire il contenitore

Usare il comando docker run per eseguire il contenitore. Per dettagli su come ottenere i valori di {ENDPOINT_URI} e {API_KEY}, vedere Raccogliere i parametri obbligatori.

Sono disponibili esempi del comando docker run.

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}

Il comando precedente:

• Esegue il contenitore Lettura OCR disponibile a livello generale più recente dall'immagine del contenitore.
• Alloca 8 core CPU e 16 GB di memoria.
• Espone la porta TCP 5000 e alloca un pseudo terminale TTY per il contenitore.
• Rimuove automaticamente il contenitore dopo la chiusura. L'immagine del contenitore rimane disponibile nel computer host.

In alternativa, è possibile eseguire il contenitore usando le variabili di 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

Sono disponibili altri esempi del comando docker run.

Se si usa Archiviazione di Azure per archiviare le immagini per l'elaborazione, è possibile creare una stringa di connessione da usare quando si chiama il contenitore.

Per trovare la stringa di connessione:

1. Passare ad Account di archiviazione nel portale di Azure e individuare l'account.
2. Nell'elenco di spostamento a sinistra fare clic su Chiavi di accesso.
3. La stringa di connessione si trova sotto Stringa di connessione

Eseguire più contenitori nello stesso host

Se si intende eseguire più contenitori con porte esposte, assicurarsi di eseguire ogni contenitore con una porta esposta diversa. Eseguire ad esempio il primo contenitore sulla porta 5000 e il secondo sulla porta 5001.

È possibile eseguire questo contenitore e un contenitore di Servizi di Azure AI diverso contemporaneamente sull'HOST. È anche possibile eseguire più contenitori dello stesso contenitore di Servizi di Azure AI.

Verificare che il contenitore sia in esecuzione

Per verificare se il contenitore è in esecuzione, sono disponibili diverse opzioni. Individuare l'indirizzo IP esterno e la porta esposta del contenitore in questione, quindi aprire il Web browser di scelta. Usare i vari URL di richiesta seguenti per verificare che il contenitore sia in esecuzione. Gli URL di richiesta di esempio elencati di seguito sono http://localhost:5000, ma il proprio contenitore specifico potrebbe variare. Assicurarsi di usare l'indirizzo IP esterno e la porta esposta del contenitore.

Eseguire una query sull'endpoint di stima del contenitore

Il contenitore fornisce le API dell'endpoint di stima della query basata su REST.

Usare l'host http://localhost:5000 per le API del contenitore. È possibile visualizzare il percorso Swagger in: http://localhost:5000/swagger/.

Lettura asincrona

È possibile usare le operazioni POST /vision/v3.2/read/analyze e GET /vision/v3.2/read/operations/{operationId} in parallelo per eseguire la lettura asincrona di un'immagine, analogamente al modo in cui il servizio Visione di Azure AI usa le operazioni REST corrispondenti. Il metodo POST asincrono restituirà un operationId usato come identificatore per la richiesta HTTP GET.

Nell'interfaccia utente di Swagger selezionare Analyze per espanderlo nel browser. Selezionare quindi Prova>Scegli file. In questo esempio si userà l'immagine seguente:

Al termine dell'esecuzione del metodo POST asincrono, viene restituito un codice di stato HTTP 202. Come parte della risposta, è presente un'intestazione operation-location che contiene l'endpoint del risultato per la richiesta.

 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

operation-location è l'URL completo ed è accessibile tramite una richiesta HTTP GET. Ecco la risposta JSON generata dall'esecuzione dell'URL operation-location dall'immagine precedente:

{
  "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
              }
            ]
          }
        ]
      }
    ]
  }
}

Lettura sincrona

È possibile usare l'operazione seguente per eseguire la lettura di un'immagine in modo sincrono.

POST /vision/v3.2/read/syncAnalyze

L'immagine viene letta per intero e solo in quel momento l'API restituisce una risposta JSON. L'unica eccezione a questo comportamento è se si verifica un errore. In tal caso, viene restituito il codice JSON seguente:

{
    "status": "Failed"
}

L'oggetto risposta JSON ha lo stesso grafico di oggetti della versione asincrona. Per gli utenti di JavaScript che desiderano l'indipendenza dai tipi, è consigliabile usare TypeScript per eseguire il cast della risposta JSON.

Per un esempio di caso d'uso, vedere l'ambiente sandbox TypeScript qui e selezionare Esegui per visualizzarne la facilità di utilizzo.

Eseguire il contenitore disconnesso da Internet

Per usare questo contenitore disconnesso da Internet, è prima di tutto necessario richiedere l'accesso compilando una richiesta e acquistando un piano di impegno. Per ulteriori informazioni, vedere Usare contenitori Docker in ambienti disconnessi.

Se è stata ricevuta l'approvazione per eseguire il contenitore disconnesso da Internet, seguire l'esempio seguente che mostra la formattazione del comando docker run da usare, con valori segnaposto. Sostituire questi valori segnaposto con i propri valori.

Il parametro DownloadLicense=True nel comando docker run scaricherà un file di licenza che consentirà 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 un file di licenza solo con il contenitore appropriato per cui è stata ricevuta l'approvazione. Ad esempio, non è possibile usare un file di licenza per un contenitore di Riconoscimento vocale con un contenitore di Informazioni sui documenti.

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} 

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

Ovunque venga eseguito il contenitore, il file di licenza deve essere montato nel contenitore e il percorso della cartella della licenza nel file system locale del contenitore deve essere specificato con Mounts:License=. È necessario specificare anche un montaggio di output in modo che sia possibile scrivere i record di utilizzo per la fatturazione.

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}

Arrestare il contenitore

Per arrestare il contenitore, nell'ambiente della riga di comando in cui è in esecuzione il contenitore premere CTRL+C.

Risoluzione dei problemi

Se si esegue il contenitore con un punto di montaggio di output e la registrazione attivata, il contenitore genera file di log utili per risolvere i problemi che si verificano durante l'avvio o l'esecuzione del contenitore.

Se si verificano problemi durante l'esecuzione di un contenitore di Servizi di Azure AI, è possibile provare a usare il contenitore per la diagnostica di Microsoft. Usare questo contenitore per diagnosticare gli errori comuni nell'ambiente di distribuzione che potrebbero impedire il funzionamento previsto dei contenitori di Azure per intelligenza artificiale.

Per ottenere il contenitore, usare il comando docker pull seguente:

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

Quindi, eseguire il contenitore. Sostituire {ENDPOINT_URI} con l'endpoint e {API_KEY} con la chiave per la risorsa:

docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

Il contenitore eseguirà il test della connettività di rete per l'endpoint di fatturazione.

Fatturazione

I contenitori di Azure per intelligenza artificiale inviano le informazioni di fatturazione ad Azure usando la risorsa corrispondente nell'account Azure.

Le query sul contenitore vengono fatturate secondo il piano tariffario della risorsa di Azure usata per il parametro ApiKey.

I contenitori di Servizi di Azure AI non possiedono la licenza per l'esecuzione senza connessione all'endpoint di misurazione o fatturazione. È necessario consentire ai contenitori di comunicare sempre le informazioni di fatturazione all'endpoint di fatturazione. I contenitori di Servizi di Azure AI non inviano a Microsoft i dati dei clienti, ad esempio l'immagine o il testo analizzato.

Connect to Azure

Per eseguire il contenitore, sono necessari i valori dell'argomento di fatturazione. Questi valori consentono al contenitore di connettersi all'endpoint di fatturazione. Il contenitore segnala l'utilizzo ogni 10-15 minuti. Se il contenitore non si connette ad Azure entro la finestra temporale consentita, continuerà a essere eseguito ma non fornirà query finché l'endpoint di fatturazione non verrà ripristinato. Il tentativo di connessione viene effettuato 10 volte nello stesso intervallo di tempo di 10-15 minuti. Se non è possibile stabilire la connessione con l'endpoint di fatturazione dopo 10 tentativi, il contenitore non potrà più gestire le richieste. Per un esempio di informazioni inviate a Microsoft per la fatturazione, vedere le Domande frequenti sui contenitori di Servizi di Azure AI.

Argomenti di fatturazione

Il comando docker run avvierà il contenitore quando vengono forniti valori validi per tutte e tre le opzioni seguenti:

Per altre informazioni su queste opzioni, vedere Configurare i contenitori.

Riepilogo

In questo articolo sono stati descritti i concetti e il flusso di lavoro per scaricare, installare ed eseguire i contenitori di Visione di Azure AI. Riepilogo:

• Visione di Azure AI fornisce un contenitore Linux per Docker, che incapsula la lettura.
• L'immagine del contenitore di lettura richiede l'esecuzione di un'applicazione.
• Le immagini dei contenitori vengono eseguite in Docker.
• È possibile usare l'API REST o l'SDK per chiamare le operazioni nei contenitori Lettura OCR specificando l'URI dell'host del contenitore.
• Quando si crea un'istanza di un contenitore, è necessario specificare le informazioni di fatturazione.

Passaggi successivi

• Rivedere Configurare i contenitori per informazioni sulle impostazioni di configurazione.
• Rivedere Panoramica di Riconoscimento ottico dei caratteri (OCR) per altre informazioni sul riconoscimento di testo scritto a mano e stampato
• Vedere l'API Lettura per informazioni dettagliate sui metodi supportati dal contenitore.
• Fare riferimento alle domande frequenti per risolvere i problemi correlati alle funzionalità di Visione di Azure AI.
• Usare altri contenitori Azure per intelligenza artificiale