Usare contenitori Docker di riepilogo in locale

I contenitori consentono di ospitare l'API di riepilogo nella propria infrastruttura. Se esistono requisiti di sicurezza o governance dei dati che non possono essere soddisfatti richiamando il riepilogo da remoto, i contenitori potrebbero essere un'opzione valida.

Prerequisiti

• Se non hai una sottoscrizione di Azure, crea un account gratuito.
• Docker installato in un computer host. Docker deve essere configurato per consentire ai contenitori di connettersi ai dati di fatturazione e inviarli ad Azure.
  • In Windows, è anche necessario configurare Docker per supportare i contenitori Linux.
  • È necessario avere una conoscenza di base dei concetti di Docker.
• Una risorsa linguistica con il piano tariffario gratuito (F0) o standard (S). Per i contenitori disconnessi, è necessario il livello DC0.

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 .

Importante

Queste chiavi di sottoscrizione vengono usate per accedere all'API Servizi di Azure AI. Non condividere le chiavi. Archiviarle in modo sicuro. Usare, ad esempio, Azure Key Vault. È anche consigliabile rigenerare queste chiavi regolarmente. Per effettuare una chiamata API è necessaria una sola chiave. Quando si rigenera la prima chiave, è possibile usare la seconda chiave per mantenere l'accesso al servizio.

Requisiti e consigli per i computer host

L'host è un computer con architettura 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).

La tabella seguente riporta le specifiche minime e consigliate per le competenze del contenitore di riepilogo. Le combinazioni di CPU/memoria elencate sono per un input di 4000 token (l'utilizzo della conversazione è per tutti gli aspetti della stessa richiesta).

Tipo di contenitore	Numero consigliato di core CPU	Memoria consigliata	Note
Contenitore CPU di riepilogo	16	48 GB
Contenitore GPU di riepilogo	2	24 GB	Richiede una GPU Nvidia che supporta Cuda 11.8 con 16 GB di VRAM.

La memoria e il core CPU corrispondono alle impostazioni --cpus e --memory, che vengono usate come parte del comando docker run.

Ottenere l'immagine del contenitore con docker pull

L'immagine del contenitore di riepilogo è disponibile nel syndicate del registro contenitori mcr.microsoft.com. Si trova all'interno del repository azure-cognitive-services/textanalytics/ ed è denominata summarization. Il nome completo dell'immagine del contenitore è mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization.

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

Usare il comando docker pull per scaricare un'immagine del contenitore dal Registro Container di Microsoft.

docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu

per i contenitori CPU,

docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:gpu

per i contenitori GPU.

Suggerimento

È possibile usare il comando docker images per visualizzare l'elenco delle immagini dei contenitori scaricate. Ad esempio, il comando seguente visualizza l'ID, il repository e il tag di ogni immagine del contenitore scaricata, in formato tabella:

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

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

Scaricare i modelli di contenitore di riepilogo

Un prerequisito per l'esecuzione del contenitore di riepilogo consiste nello scaricare prima i modelli. A tale scopo, eseguire uno dei comandi seguenti usando un'immagine del contenitore CPU come esempio:

docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=ExtractiveSummarization billing={ENDPOINT_URI} apikey={API_KEY}
docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=AbstractiveSummarization billing={ENDPOINT_URI} apikey={API_KEY}
docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=ConversationSummarization billing={ENDPOINT_URI} apikey={API_KEY}

Non è consigliabile scaricare modelli per tutte le competenze all'interno dello stesso HOST_MODELS_PATH, perché il contenitore carica tutti i modelli all'interno di HOST_MODELS_PATH. In questo modo si userebbe una grande quantità di memoria. È consigliabile scaricare solo il modello per la competenza necessaria in un determinato HOST_MODELS_PATH.

Per garantire la compatibilità tra i modelli e il contenitore, scaricare nuovamente i modelli utilizzati ogni volta che si crea un contenitore usando una nuova versione dell'immagine. Quando si usa un contenitore disconnesso, la licenza deve essere scaricata nuovamente dopo il download dei modelli.

Eseguire il contenitore con docker run

Quando il contenitore di riepilogo si trova nel computer host, usare il comando docker run seguente per eseguire i contenitori. Il contenitore continuerà a essere eseguito fino a quando non viene arrestato. Sostituire i segnaposto seguenti con i propri valori:

Segnaposto	Valore	Formato o esempio
{HOST_MODELS_PATH}	Montaggio del volume del computer host, usato da Docker per rendere persistente il modello.	Ne è un esempio c:\SummarizationModel, dove l'unità c:\ si trova nel computer host.
{ENDPOINT_URI}	Endpoint per l'accesso all'API di riepilogo. È 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 Lingua. È disponibile nella pagina Chiave ed endpoint della risorsa nel portale di Azure.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

docker run -p 5000:5000 -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu eula=accept rai_terms=accept billing={ENDPOINT_URI} apikey={API_KEY}

In alternativa, se si esegue un contenitore GPU, usare questo comando.

docker run -p 5000:5000 --gpus all -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:gpu eula=accept rai_terms=accept billing={ENDPOINT_URI} apikey={API_KEY}

Se nel computer sono presenti più GPU, sostituire --gpus all con --gpus device={DEVICE_ID}.

Importante

• I comandi di Docker nelle sezioni seguenti usano la barra rovesciata, \, come carattere di continuazione di riga. Sostituirla o rimuoverla in base ai requisiti del sistema operativo host.
• È necessario specificare le opzioni Eula, Billing, rai_terms e ApiKey per eseguire il contenitore. In caso contrario, il contenitore non si avvia. Per altre informazioni, vedereFatturazione.

Questo comando:

• Esegue un contenitore di riepilogo dall'immagine del contenitore
• Alloca un core CPU e 4 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.

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.

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.

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.

Richiesta URL	Scopo
http://localhost:5000/	Il contenitore fornisce un home page.
http://localhost:5000/ready	Questo URL, richiesto con un'operazione GET, verifica che il contenitore sia pronto per accettare una query sul modello. Questa richiesta può essere usata per i probe di attività e di idoneità di Kubernetes.
http://localhost:5000/status	Questo URL, anch'esso richiesto con un'operazione GET, verifica se la chiave API usata per avviare il contenitore sia valida senza che sia necessaria una query sull'endpoint. Questa richiesta può essere usata per i probe di attività e di idoneità di Kubernetes.
http://localhost:5000/swagger	Il contenitore fornisce un set completo di documentazione per gli endpoint e una funzionalità Prova. Con questa funzionalità, è possibile immettere le impostazioni in un modulo HTML basato sul Web ed eseguire la query senza scrivere codice. Dopo che la query restituisce il risultato, viene fornito un comando CURL di esempio per illustrare il formato richiesto per il corpo e le intestazioni HTTP.

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 servizi di linguaggio.

Scaricare i modelli di contenitore di riepilogo disconnessi

Un prerequisito per l'esecuzione del contenitore di riepilogo consiste nello scaricare prima i modelli. A tale scopo, eseguire uno dei comandi seguenti usando un'immagine del contenitore CPU come esempio:

docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=ExtractiveSummarization billing={ENDPOINT_URI} apikey={API_KEY}
docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=AbstractiveSummarization billing={ENDPOINT_URI} apikey={API_KEY}
docker run -v {HOST_MODELS_PATH}:/models mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu downloadModels=ConversationSummarization billing={ENDPOINT_URI} apikey={API_KEY}

Non è consigliabile scaricare modelli per tutte le competenze all'interno dello stesso HOST_MODELS_PATH, perché il contenitore carica tutti i modelli all'interno di HOST_MODELS_PATH. In questo modo si userebbe una grande quantità di memoria. È consigliabile scaricare solo il modello per la competenza necessaria in un determinato HOST_MODELS_PATH.

Per garantire la compatibilità tra i modelli e il contenitore, scaricare nuovamente i modelli utilizzati ogni volta che si crea un contenitore usando una nuova versione dell'immagine. Quando si usa un contenitore disconnesso, la licenza deve essere scaricata nuovamente dopo il download dei modelli.

Eseguire il contenitore disconnesso con docker run

Segnaposto	Valore	Formato o esempio
{IMAGE}	L’immagine del contenitore da usare.	mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu
{LICENSE_MOUNT}	Il percorso in cui verrà scaricata e montata la licenza.	/host/license:/path/to/license/directory
{HOST_MODELS_PATH}	Percorso in cui i modelli sono stati scaricati e montati.	/host/models:/models
{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}	La chiave per la risorsa Analisi del testo. È disponibile nella pagina Chiave ed endpoint della risorsa nel portale di Azure.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{CONTAINER_LICENSE_DIRECTORY}	Percorso della cartella di licenza nel file system locale del contenitore.	/path/to/license/directory

docker run --rm -it -p 5000:5000 \ 
-v {LICENSE_MOUNT} \
-v {HOST_MODELS_PATH} \
{IMAGE} \
eula=accept \
rai_terms=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.

Segnaposto	Valore	Formato o esempio
{IMAGE}	L’immagine del contenitore da usare.	mcr.microsoft.com/azure-cognitive-services/textanalytics/summarization:cpu
{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}	Percorso in cui risiederà e verrà montata la licenza.	/host/license:/path/to/license/directory
{HOST_MODELS_PATH}	Percorso in cui i modelli sono stati scaricati e montati.	/host/models:/models
{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

docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \ 
-v {LICENSE_MOUNT} \ 
-v {HOST_MODELS_PATH} \
-v {OUTPUT_PATH} \
{IMAGE} \
eula=accept \
rai_terms=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.

Suggerimento

Per altre informazioni sulla risoluzione dei problemi e per indicazioni, vedere Domande frequenti sui contenitori di Azure per intelligenza artificiale.

Fatturazione

I contenitori di riepilogo inviano informazioni di fatturazione ad Azure usando una risorsa Lingua nell'account di 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:

Opzione	Descrizione
ApiKey	Chiave API della risorsa di Servizi di Azure AI usata per tenere traccia delle informazioni di fatturazione. Il valore di questa opzione deve essere impostato su una chiave API per la risorsa di cui è stato effettuato il provisioning specificata in Billing.
Billing	Endpoint della risorsa di Servizi di Azure AI usata per tenere traccia delle informazioni di fatturazione. Il valore di questa opzione deve essere impostato sull'URI dell'endpoint di una risorsa di Azure di cui è stato effettuato il provisioning.
Eula	Indica che è la licenza per il contenitore è stata accettata. Il valore di questa opzione deve essere impostato su accept.

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 riepilogo. Riepilogo:

• Il riepilogo fornisce contenitori Linux per Docker
• Le immagini dei contenitori vengono scaricate da Registro Container Microsoft.
• Le immagini dei contenitori vengono eseguite in Docker.
• Quando si crea un'istanza di un contenitore, è necessario specificare le informazioni di fatturazione.

Importante

Questo contenitore non è concesso in licenza per l'esecuzione senza una connessione ad Azure per la misurazione. I clienti devono consentire ai contenitori di comunicare sempre le informazioni di fatturazione al servizio di misurazione. I contenitori di Azure per intelligenza artificiale non inviano dati dei clienti (ad esempio il testo analizzato) a Microsoft.

Passaggi successivi

• Vedere Configurare i contenitori per informazioni sulle impostazioni di configurazione.