Installare ed eseguire contenitori di estrazione frasi chiave
I contenitori consentono di ospitare l'API Estrazione frasi chiave nella propria infrastruttura. Se si hanno requisiti di sicurezza o governance dei dati che non possono essere soddisfatti chiamando estrazione frasi chiave in modalità remota, i contenitori potrebbero essere un'opzione valida.
Nota
- L'account gratuito è limitato a 5.000 record di testo al mese e solo i piani tariffariGratuito e Standard sono validi per i contenitori. Per altre informazioni sulle tariffe delle richieste di transazione, vedere Limiti di dati e servizi.
I contenitori consentono di eseguire le API di estrazione frasi chiave nel proprio ambiente e sono ideali per i requisiti specifici di sicurezza e governance dei dati. I contenitori Estrazione frasi chiave offrono un'elaborazione avanzata del linguaggio naturale sul testo non elaborato e includono tre funzioni principali: analisi del sentiment, estrazione frasi chiave e rilevamento della lingua.
Prerequisiti
- Se non si ha una sottoscrizione di Azure, creare 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.
- lingua con il piano tariffario gratuito (F0) o standard (S).
Raccogliere i parametri obbligatori
Sono necessari tre parametri principali per tutti i contenitori di Intelligenza artificiale di Azure. Le Condizioni di licenza software Microsoft devono essere presenti con il valore accept. Sono necessari anche un URI endpoint e una chiave API.
URI endpoint
Il {ENDPOINT_URI} valore è disponibile nella pagina panoramica portale di Azure della risorsa dei servizi di intelligenza artificiale di Azure corrispondente. Passare alla pagina Panoramica , passare il puntatore del mouse sull'endpoint e visualizzare un'icona Copia negli Appunti. Copiare e usare l'endpoint, se necessario.
Chiavi
Il {API_KEY} valore viene usato per avviare il contenitore ed è disponibile nella pagina Chiavi di portale di Azure della risorsa dei servizi di intelligenza artificiale di Azure corrispondente. Passare alla pagina Chiavi e selezionare l'icona Copia negli Appunti .
Importante
Queste chiavi di sottoscrizione vengono usate per accedere all'API dei servizi di intelligenza artificiale di Azure. Non condividere le chiavi. Archiviarli in modo sicuro. Ad esempio, usare Azure Key Vault. È anche consigliabile rigenerare regolarmente queste chiavi. Per effettuare una chiamata API è necessaria una sola chiave. Quando si rigenera la prima chiave, è possibile usare la seconda chiave per l'accesso continuo al servizio.
Requisiti e consigli per i 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).
Nella tabella seguente vengono descritte le specifiche minime e consigliate per i contenitori di estrazione frasi chiave disponibili. Ogni core CPU deve essere almeno di 2,6 gigahertz (GHz) o superiore. Sono elencate anche le transazioni consentite al secondo (TPS).
| Specifiche host minime | Specifiche host consigliate | TPS minimo | Numero massimo di tps | |
|---|---|---|---|---|
| Estrazione frasi chiave | 1 core, 2 GB di memoria | 1 core, 4 GB di memoria | 15 | 30 |
Core CPU e memoria corrispondono alle --cpus impostazioni e --memory , usate come parte del docker run comando .
Ottenere l'immagine del contenitore con docker pull
L'immagine del contenitore di estrazione frasi chiave è disponibile nel sindacato del mcr.microsoft.com registro contenitori. Si trova all'interno del azure-cognitive-services/textanalytics/ repository ed è denominato keyphrase. Il nome completo dell'immagine del contenitore è , mcr.microsoft.com/azure-cognitive-services/textanalytics/keyphrase.
Per usare la versione più recente del contenitore, è possibile usare il latest tag . È anche possibile trovare un elenco completo dei tag in MCR.
Usare il docker pull comando per scaricare un'immagine del contenitore da Registro Azure Container.
docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/keyphrase:latest
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>
Eseguire il contenitore con docker run
Quando il contenitore si trova nel computer host, usare il comando docker run per eseguire i contenitori. Il contenitore continuerà a essere eseguito fino a quando non viene arrestato.
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,BillingeApiKeyper eseguire il contenitore. In caso contrario, il contenitore non si avvia. Per altre informazioni, vedereFatturazione. - I contenitori di analisi del sentiment e rilevamento della lingua usano la versione 3 dell'API e sono disponibili a livello generale. Il contenitore Estrazione frasi chiave usa la versione 2 dell'API ed è disponibile in anteprima.
Per eseguire il contenitore Estrazione frasi chiave , eseguire il comando seguente docker run . Sostituire i segnaposto seguenti con i propri valori:
| Segnaposto | Valore | Formato o esempio |
|---|---|---|
| {API_KEY} | Chiave per la risorsa Estrazione frasi chiave. È possibile trovarla nella pagina Chiave ed endpoint della risorsa, nella portale di Azure. | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| {ENDPOINT_URI} | Endpoint per l'accesso all'API Estrazione frasi chiave. È possibile trovarla nella pagina Chiave ed endpoint della risorsa, nella portale di Azure. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
docker run --rm -it -p 5000:5000 --memory 4g --cpus 1 \
mcr.microsoft.com/azure-cognitive-services/textanalytics/keyphrase \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}
Questo comando:
- Esegue un contenitore Estrazione frasi chiave 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 avere questo contenitore e un contenitore di servizi di intelligenza artificiale di Azure diverso in esecuzione nell'host insieme. È anche possibile disporre di più contenitori dello stesso contenitore di servizi di intelligenza artificiale di Azure in esecuzione.
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 e aprire il Web browser preferito. Usare i vari URL di richiesta che seguono per verificare che il contenitore sia in esecuzione. Gli URL della richiesta di esempio elencati di seguito sono http://localhost:5000, ma il contenitore specifico potrebbe variare. Assicurarsi di basarsi sull'indirizzo IP esterno del contenitore e sulla porta esposta.
| URL della richiesta | Scopo |
|---|---|
http://localhost:5000/ |
Il contenitore fornisce un home page. |
http://localhost:5000/ready |
Richiesto con GET, questo URL fornisce una 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 |
Richiesto anche con GET, questo URL verifica se la chiave API usata per avviare il contenitore è valida senza causare una query dell'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 necessario richiedere l'accesso tramite la compilazione di un'applicazione e l'acquisto di un piano di impegno. Per altre informazioni, vedere Usare contenitori Docker in ambienti disconnessi .
Se è stato approvato per eseguire il contenitore disconnesso da Internet, usare l'esempio seguente mostra la formattazione del docker run comando che si userà, con valori segnaposto. Sostituire questi valori segnaposto con i propri valori.
Il DownloadLicense=True parametro nel docker run comando scarica un file di licenza che consentirà all'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 eseguire il contenitore. È possibile usare solo un file di licenza con il contenitore appropriato per cui è stato approvato. Ad esempio, non è possibile usare un file di licenza per un contenitore di riconoscimento vocale con un contenitore di Document Intelligence.
| Segnaposto | Valore | Formato o esempio |
|---|---|---|
{IMAGE} |
Immagine del contenitore che si vuole usare. | mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice |
{LICENSE_MOUNT} |
Percorso in cui verrà scaricata la licenza e montata. | /host/license:/path/to/license/directory |
{ENDPOINT_URI} |
Endpoint per l'autenticazione della richiesta di servizio. È possibile trovarlo nella pagina Chiave ed endpoint della risorsa nella portale di Azure. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{API_KEY} |
Chiave per la risorsa Analisi del testo. È possibile trovarlo nella pagina Chiave ed endpoint della risorsa nella 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} \
{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 docker run comando che si userà, 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 di licenza nel file system locale del contenitore deve essere specificato con Mounts:License=. È necessario specificare anche un montaggio di output in modo che i record di utilizzo di fatturazione possano essere scritti.
| Segnaposto | Valore | Formato o esempio |
|---|---|---|
{IMAGE} |
Immagine del contenitore che si vuole usare. | mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice |
{MEMORY_SIZE} |
Dimensioni appropriate della memoria da allocare per il contenitore. | 4g |
{NUMBER_CPUS} |
Numero appropriato di CPU da allocare per il contenitore. | 4 |
{LICENSE_MOUNT} |
Percorso in cui si trova e montata la licenza. | /host/license:/path/to/license/directory |
{OUTPUT_PATH} |
Percorso di output per registrare i 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 {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 selezionare 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 indicazioni, vedere Domande frequenti sui contenitori di Intelligenza artificiale di Azure.
Fatturazione
I contenitori Estrazione frasi chiave inviano informazioni di fatturazione ad Azure usando una risorsa Estrazione frasi chiave nell'account Azure.
Le query al contenitore vengono fatturate al piano tariffario della risorsa di Azure usata per il ApiKey parametro.
I contenitori dei servizi di intelligenza artificiale di Azure non vengono concessi in licenza per l'esecuzione senza essere connessi all'endpoint di misurazione o fatturazione. È necessario consentire ai contenitori di comunicare sempre le informazioni di fatturazione all'endpoint di fatturazione. I contenitori dei servizi di intelligenza artificiale di Azure non inviano i dati dei clienti, ad esempio l'immagine o il testo analizzato, a Microsoft.
Connettersi ad 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 riesce a connettersi all'endpoint di fatturazione entro i 10 tentativi, il contenitore smette di gestire le richieste. Per un esempio delle informazioni inviate a Microsoft per la fatturazione, vedere le domande frequenti sul contenitore di servizi di intelligenza artificiale di Azure .
Argomenti di fatturazione
Il docker run comando avvierà il contenitore quando vengono fornite tutte e tre le opzioni seguenti con valori validi:
| Opzione | Descrizione |
|---|---|
ApiKey |
Chiave API della risorsa dei servizi di intelligenza artificiale di Azure 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 dei servizi di intelligenza artificiale di Azure 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. |
\
Riepilogo
In questo articolo sono stati appresi concetti e flussi di lavoro per il download, l'installazione e l'esecuzione di contenitori di estrazione frasi chiave. In sintesi:
- L'estrazione di frasi chiave fornisce contenitori Linux per Docker.
- Le immagini dei contenitori vengono scaricate da Registro Container Microsoft.
- Le immagini dei contenitori vengono eseguite in Docker.
- È possibile usare l'API REST o l'SDK per chiamare le operazioni nei contenitori Estrazione frasi chiave specificando l'URI host del contenitore.
- Quando si crea un'istanza di un contenitore, è necessario specificare le informazioni di fatturazione.
Importante
I contenitori di Intelligenza artificiale di Azure non vengono concessi in licenza per l'esecuzione senza essere connessi 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 Intelligenza artificiale di Azure non inviano i dati dei clienti (ad esempio testo analizzato) a Microsoft.
Passaggi successivi
- Vedere Configurare i contenitori per le impostazioni di configurazione.