Installare ed eseguire i contenitori di Traduttore per Azure AI.

I contenitori consentono di ospitare l'API Traduttore per Azure AI nella propria infrastruttura. L'immagine del contenitore include tutte le librerie, gli strumenti e le dipendenze necessarie per eseguire un'applicazione in modo coerente in qualsiasi ambiente privato, pubblico o personale. Se i requisiti di sicurezza o governance dei dati non possono essere soddisfatti chiamando l'API Traduttore per Azure AI in modalità remota, i contenitori rappresentano un'ottima opzione.

Questo articolo illustra come installare ed eseguire il contenitore Traduttore online con l'API Docker. Il contenitore Traduttore per Azure AI supporta le operazioni seguenti:

• Traduzione testo. Tradurre il significato contestuale di parole o frasi dall’elemento source supportato alla lingua target supportata in tempo reale. Per altre informazioni, vedereContenitore: tradurre il testo.

• 🆕Traslitterazione del testo. Convertire il testo da uno script linguistico o un sistema di scrittura in un altro script di lingua o sistema di scrittura in tempo reale. Per altre informazioni, vedereContenitore: traslitterare il testo.

• 🆕Traduzione documenti. Tradurre in modo sincrono i documenti mantenendo in tempo reale la struttura e il formato. Per altre informazioni, vedereContenitore: tradurre i documenti.

Prerequisiti

Per iniziare, sono necessarie le risorse seguenti, l'approvazione dell'accesso controllato e gli strumenti:

Risorse di Azure

• Una sottoscrizione di Azure attiva. Se non ne hai uno, puoi creare un account gratuito di 12 mesi.

• Una richiesta di accesso approvata a un contenitore connesso al Traduttore o contenitore disconnesso da Traduttore.

• Una risorsa Traduttore per Azure AI (non una risorsa Servizi di Azure AI) creata con l'ID sottoscrizione approvato. Sono necessari la chiave API e l'URI dell'endpoint associati alla risorsa. Entrambi i valori sono necessari per avviare il contenitore e sono disponibili nella pagina di panoramica della risorsa nel portale di Azure.

  • Per i contenitori connessi a Traduttore selezionare il piano tariffario S1.

    

  • Per i contenitori disconnessi da Traduttore selezionare Commitment tier disconnected containers come piano tariffario. Se la richiesta di accesso al contenitore disconnesso è approvata, viene visualizzata solo l'opzione per acquistare un livello di impegno.

    

Strumenti di Docker

È opportuno avere una conoscenza di base dei concetti relativi a Docker, tra cui registri, repository, contenitori e immagini dei contenitori, nonché dei dockercomandi e della terminologia di base. Per una panoramica dei concetti fondamentali relativi a Docker e ai contenitori, vedere Docker overview (Panoramica di Docker).

Requisiti per il computer host

L'host è un computer basato su x64 che esegue il contenitore Docker. Può trattarsi di un computer locale o di uno di questi servizi di hosting Docker in Azure:

• 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).

Core CPU e memoria consigliati

La tabella seguente descrive le specifiche minime e consigliate e le transazioni consentite al secondo (TPS) per ogni contenitore.

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

• Per ogni coppia di lingue è consigliabile usare 2 GB di memoria.

• Oltre ai requisiti di base, 4 GB di memoria per ogni elaborazione simultanea dei documenti.

  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>
  

Input richiesto

Tutti i contenitori di Azure per intelligenza artificiale richiedono i valori di input seguenti:

• Impostazione di accettazione EULA. È necessario avere un contratto di licenza con l'utente finale impostato con il valore Eula=accept.

• Chiave API e URL dell'endpoint. La chiave API viene usata per avviare il contenitore. È possibile recuperare i valori della chiave API e dell'URL dell'endpoint passando alla risorsa della paginachiavi ed endpoint della Traduttore per Azure AI e selezionando l'icona Copy to clipboard .

• Se si stanno traducendo documenti, assicurarsi di usare l'endpoint di traduzione dei documenti.

Fatturazione

• Le query sul contenitore vengono fatturate secondo il piano tariffario della risorsa di Azure usata per l’API Key.

• Vengono addebitati costi per ogni istanza del contenitore usata per elaborare documenti e immagini.

• Il comando docker run scarica un'immagine dal Registro artefatti di Microsoft e avvia il contenitore quando vengono fornite tutte e tre le opzioni seguenti con valori validi:

Connessione ad Azure

• I valori dell'argomento di fatturazione del contenitore consentono al contenitore di connettersi all'endpoint di fatturazione ed effettuare l’esecuzione.

• 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 Azure AI.

Immagini e tag del contenitore

Le immagini del contenitore dei Servizi di Azure AI sono disponibili nel catalogo del Registro artefatti Microsoft. Il contenitore di Traduttore per Azure AI si trova all'interno del repository azure-cognitive-services/translator ed è denominato text-translation. Il nome completo dell'immagine del contenitore è mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest.

Per usare la versione più recente del contenitore, utilizzare il tag più recente. È possibile visualizzare l'elenco completo dei tag di versione Traduzione testo Servizi di Azure AI in MCR.

Usare i contenitori

Selezionare una scheda per scegliere l'ambiente contenitore di Traduttore per Azure AI:

docker run --rm -it -p 5000:5000 --memory 12g --cpus 4 \
-v /mnt/d/TranslatorContainer:/usr/local/models \
-e apikey={API_KEY} \
-e eula=accept \
-e billing={ENDPOINT_URI} \
-e Languages=en,fr,es,ar,ru  \
mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest

  curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS" -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

docker run --rm -it -p 5000:5000 \

-v {MODEL_MOUNT_PATH} \

-v {LICENSE_MOUNT_PATH} \

-e Mounts:License={CONTAINER_LICENSE_DIRECTORY} \

-e DownloadLicense=true \

-e eula=accept \

-e billing={ENDPOINT_URI} \

-e apikey={API_KEY} \

-e Languages={LANGUAGES_LIST} \

[image]

    -e MODELS= usr/local/models/model1/, usr/local/models/model2/
    -e TRANSLATORSYSTEMCONFIG=/usr/local/models/Config/5a72fa7c-394b-45db-8c06-ecdfc98c0832

docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \

-v {MODEL_MOUNT_PATH} \

-v {LICENSE_MOUNT_PATH} \

-v {OUTPUT_MOUNT_PATH} \

-e Mounts:License={CONTAINER_LICENSE_DIRECTORY} \

-e Mounts:Output={CONTAINER_OUTPUT_DIRECTORY} \

-e MODELS={MODELS_DIRECTORY_LIST} \

-e TRANSLATORSYSTEMCONFIG={TRANSLATOR_CONFIG_JSON} \

-e eula=accept \

[image]

Verificare che il contenitore sia in esecuzione

Per verificare se il contenitore è in esecuzione, sono disponibili diverse opzioni:

• Il contenitore fornisce una home page all'indirizzo / come convalida visiva dell'esecuzione del contenitore.

• È possibile aprire il Web browser preferito e passare all'indirizzo IP esterno e alla porta esposta del contenitore in questione. Usare gli URL di richiesta seguenti per verificare che il contenitore sia in esecuzione. Gli URL di richiesta di esempio elencati puntano a http://localhost:5000, ma il contenitore specifico può variare. Tenere presente che si sta passando all'Indirizzo IP esterno del contenitore e alla porta esposta.

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 esegue il test della connettività di rete per l’endpoint di fatturazione.

Arrestare il contenitore

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

Casi d'uso per i contenitori di supporto

Alcune query di Traduttore richiedono i contenitori di supporto per completare correttamente le operazioni. Se si usano documenti di Office e non è necessario il rilevamento della lingua di origine, è necessario solo il contenitore Traduttore. Tuttavia, se è necessario il rilevamento della lingua di origine o si usano documenti PDF scansionati, sono necessari contenitori di supporto:

Nella tabella seguente sono elencati i contenitori di supporto necessari per le operazioni di traduzione di testo e documenti. Il contenitore Traduttore invia informazioni di fatturazione ad Azure tramite la risorsa Traduttore per Azure AI nell'account Azure.

Gestire i contenitori di supporto con docker compose

Docker compose è uno strumento che consente di configurare applicazioni multi-contenitore usando un singolo file YAML denominato tipicamente compose.yaml. Usare il comando docker compose up per avviare l'applicazione contenitore e il comando docker compose down per arrestare e rimuovere i contenitori.

Se è stata installata l'interfaccia della riga di comando di Docker Desktop, include Docker compose e i relativi prerequisiti. Se Docker Desktop non è disponibile, vedere la panoramica Installazione di Docker Compose.

Creare l'applicazione

1. Usando l'editor o l'IDE preferito, creare una nuova directory per l'app denominata container-environment o un nome di propria scelta.

2. Creare un nuovo file YAML denominato compose.yaml. Entrambe le estensioni .yml o yaml possono essere usate per il file compose.

3. Copiare e incollare il codice di esempio YAML seguente nel file compose.yaml. Sostituire {TRANSLATOR_KEY} e {TRANSLATOR_ENDPOINT_URI} con i valori di chiave ed endpoint dell'istanza Traduttore del portale di Azure. Se si stanno traducendo documenti, assicurarsi di usare document translation endpoint.

4. Il nome di primo livello (azure-ai-translator, azure-ai-language, azure-ai-read) è il parametro specificato.

5. container_name è un parametro facoltativo che imposta un nome per il contenitore durante l'esecuzione, anziché consentire a docker compose la generazione di un nome.

   services:
     azure-ai-translator:
       container_name: azure-ai-translator
       image: mcr.microsoft.com/azure-cognitive-services/translator/text-translation::latest
       environment:
           - EULA=accept
           - billing={TRANSLATOR_ENDPOINT_URI}
           - apiKey={TRANSLATOR_KEY}
           - ladurl=http://azure-ai-language:5000
           - VISIONURL=http://azure-ai-read:5000
       ports:
             - "5000:5000"
       volumes:
             - {your local folder}:/usr/local/models
       azure-ai-language:
         container_name: azure-ai-language
         image:  mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
         environment:
             - EULA=accept
             - billing={LANGUAGE_RESOURCE_ENDPOINT_URI}
             - apiKey={LANGUAGE_RESOURCE_KEY}
             - Languages=en,es
             - LADINCLUSTER=true 
       azure-ai-read:
         container_name: azure-ai-read
         image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
         environment:
             - EULA=accept
             - billing={COMPUTER_VISION_ENDPOINT_URI}
             - apiKey={COMPUTER_VISION_KEY}
   

6. Aprire un terminale passare alla cartella container-environment e avviare i contenitori con il comando docker-compose seguente:

   docker compose up
   

7. Per arrestare il contenitore, usare il comando seguente:

   docker compose down
   

   Suggerimento

   Comandi Docker utili:

   • docker compose pause sospende i contenitori in esecuzione.
   • docker compose unpause {your-container-name} rimette in esecuzione i contenitori in pausa.
   • docker compose restart riavvia tutti i contenitori arrestati e in esecuzione con tutte le modifiche precedenti intatte. Se si apportano modifiche alla configurazione compose.yaml, queste modifiche non vengono aggiornate con il comando docker compose restart. È necessario usare il comando docker compose up per riflettere gli aggiornamenti e le modifiche nel file compose.yaml.
   • docker compose ps -a elenca tutti i contenitori, inclusi quelli arrestati.
   • docker compose exec consente di eseguire comandi per rimuovere o impostare variabili di ambiente in un contenitore in esecuzione.

   Per altre informazioni, vedere leinformazioni di riferimento sull'interfaccia della riga di comando di Docker.

Traduttore e immagini e tag dei contenitori di supporto

Le immagini del contenitore dei Servizi di Azure AI sono disponibili nel catalogo del Registro artefatti Microsoft. La tabella seguente elenca il percorso completo dell'immagine per la traduzione di testi e documenti:

Altri parametri e comandi

Ecco alcuni altri parametri e comandi che è possibile usare 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:

Comando docker run di esempio

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

Nomi di variabili di ambiente nelle distribuzioni kubernetes

• Alcuni contenitori di Azure per intelligenza artificiale, ad esempio Traduttore, richiedono agli utenti di passare nomi di variabili ambientali che includono i due punti (:) durante l'esecuzione del contenitore.

• Kubernetes non accetta i due punti nei nomi delle variabili di ambiente. Per risolvere il problema, è possibile sostituire i due punti con due caratteri di sottolineatura (__) durante la distribuzione in Kubernetes. Vedere l'esempio seguente di un formato accettabile per i nomi delle variabili ambientali:

        env:
        - name: Mounts__License
          value: "/license"
        - name: Mounts__Output
          value: "/output"

In questo esempio viene sostituito il formato predefinito con i nomi delle variabili di ambiente Mounts:License e Mounts:Output nel comando di esecuzione docker.

Ottenere i record di utilizzo 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 per recuperare tutti i record

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

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}

Endpoint HTTPS di esempio per recuperare i record per un mese e un anno specifici

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

Gli endpoint usage-logs restituiscono una risposta JSON simile all'esempio seguente:

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

      {
    "type": "CommerceUsageResponse",
    "meters": [
      {
        "name": "CognitiveServices.TextTranslation.Container.OneDocumentTranslatedCharacters",
        "quantity": 1250000,
        "billedUnit": 1875000
      },
      {
        "name": "CognitiveServices.TextTranslation.Container.TranslatedCharacters",
        "quantity": 1250000,
        "billedUnit": 1250000
      }
    ],
    "apiType": "texttranslation",
    "serviceName": "texttranslation"
   }

Riepilogo

In questo articolo sono stati appresi concetti e flussi di lavoro per il download, l'installazione e l'esecuzione di un contenitore di Traduttore per Azure AI:

• Il contenitore di Traduttore per Azure AI supporta la traduzione testuale, la traduzione sincrona dei documenti e la traslitterazione di testo.

• Le immagini del contenitore vengono scaricate dal registro contenitori ed eseguite in Docker.

• Le informazioni di fatturazione devono essere specificate quando si crea un'istanza di un contenitore.

Passaggi successivi