Instalar e executar o contêiner do Azure AI Translator

Os contêineres permitem que você hospede a API do Azure AI Translator em sua própria infraestrutura. A imagem de contêiner inclui todas as bibliotecas, ferramentas e dependências necessárias para executar um aplicativo consistentemente em qualquer ambiente de computação privado, público ou pessoal. Se seus requisitos de segurança ou governança de dados não puderem ser atendidos chamando a API do Azure AI Translator remotamente, os contêineres serão uma boa opção.

Neste artigo, saiba como instalar e executar o contêiner do Translator online com a API do Docker. O contêiner do Azure AI Translator dá suporte às seguintes operações:

• Tradução de Texto. Traduza o significado contextual de palavras ou frases do idioma suportado source para o idioma suportado target em tempo real. Para obter mais informações, consulte Contêiner: traduzir texto.

• 🆕 Transliteração de texto. Converta texto de um script de linguagem ou sistema de escrita para outro script de linguagem ou sistema de escrita em tempo real. Para obter mais informações, consulte Contêiner: texto transliterado.

• 🆕 Tradução de documentos. Traduza documentos de forma síncrona, preservando a estrutura e o formato em tempo real. Para obter mais informações, consulte Container:translate documents.

Pré-requisitos

Para começar, você precisa dos seguintes recursos, aprovação de acesso fechado e ferramentas:

Recursos do Azure

• Uma subscrição ativa do Azure. Se não tiver uma, pode criar uma conta gratuita de 12 meses.

• Uma solicitação de acesso aprovada para um contêiner conectado ao Translator ou a um contêiner desconectado do Translator.

• Um recurso do Azure AI Translator (não um recurso de serviços de IA do Azure multisserviços) criado sob a ID de assinatura aprovada. Você precisa da chave da API e do URI do ponto de extremidade associados ao seu recurso. Ambos os valores são necessários para iniciar o contêiner e podem ser encontrados na página de visão geral do recurso no portal do Azure.

  • Para contêineres conectados ao Translator, selecione o nível de S1 preço.

    

  • Para contêineres desconectados do Translator, selecione Commitment tier disconnected containers como seu nível de preço. Você só verá a opção de comprar uma camada de compromisso se sua solicitação de acesso ao contêiner desconectado for aprovada.

    

Ferramentas do Docker

Você deve ter uma compreensão básica dos conceitos do Docker, como registros, repositórios, contêineres e imagens de contêiner, bem como conhecimento de terminologia básica docker e comandos. Para um manual de noções básicas do Docker e do contentor, veja a descrição geral do Docker.

Requisitos do computador host

O host é um computador baseado em x64 que executa o contêiner do Docker. Pode ser um computador em suas instalações ou um destes serviços de hospedagem do Docker no Azure:

• Serviço Kubernetes do Azure.
• Instâncias de contêiner do Azure.
• Um cluster Kubernetes implantado no Azure Stack. Para obter mais informações, consulte Implantar o Kubernetes no Azure Stack.

Núcleos de CPU e memória recomendados

A tabela a seguir descreve as especificações mínimas e recomendadas e as transações por segundo (TPS) permitidas para cada contêiner.

• Cada núcleo deve ter pelo menos 2,6 gigahertz (GHz) ou mais rápido.

• Para cada par de idiomas, recomenda-se 2 GB de memória.

• Além dos requisitos de linha de base, 4 GB de memória para cada processamento simultâneo de documentos.

  Gorjeta

  Você pode usar o comando docker images para listar as imagens de contêiner baixadas. Por exemplo, o comando a seguir lista o ID, o repositório e a tag de cada imagem de contêiner baixada, formatada como uma tabela:

   docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
  
   IMAGE ID         REPOSITORY                TAG
   <image-id>       <repository-path/name>    <tag-name>
  

Entrada necessária

Todos os contêineres de IA do Azure exigem os seguintes valores de entrada:

• EULA aceitar configuração. Você deve ter um contrato de licença de usuário final (EULA) definido com um valor de Eula=accept.

• Chave de API e URL do ponto de extremidade. A chave da API é usada para iniciar o contêiner. Você pode recuperar a chave da API e os valores da URL do Ponto de Extremidade navegando até a página Chaves de recursos e Ponto de Extremidade do Azure AI Translator e selecionando o Copy to clipboard ícone.

• Se estiver a traduzir documentos, certifique-se de que utiliza o ponto de extremidade de tradução de documentos.

Faturação

• As consultas ao contêiner são cobradas na camada de preço do recurso do Azure usado para a API Key.

• Você é cobrado por cada instância de contêiner usada para processar seus documentos e imagens.

• O comando docker run baixa uma imagem do Microsoft Artifact Registry e inicia o contêiner quando todas as três opções a seguir são fornecidas com valores válidos:

Conectando-se ao Azure

• Os valores do argumento de faturamento do contêiner permitem que o contêiner se conecte ao ponto de extremidade de faturamento e seja executado.

• O contêiner relata o uso a cada 10 a 15 minutos. Se o contêiner não se conectar ao Azure dentro da janela de tempo permitida, o contêiner continuará a ser executado, mas não atenderá consultas até que o ponto de extremidade de cobrança seja restaurado.

• Uma conexão é tentada 10 vezes no mesmo intervalo de tempo de 10 a 15 minutos. Se ele não puder se conectar ao ponto de extremidade de faturamento dentro das 10 tentativas, o contêiner interromperá o atendimento de solicitações. Consulte as Perguntas frequentes sobre o contêiner do Azure AI para obter um exemplo das informações enviadas à Microsoft para cobrança.

Imagens e tags de contêiner

As imagens de contêiner de serviços de IA do Azure podem ser encontradas no catálogo do Registro de Artefato da Microsoft. O contêiner do Azure AI Translator reside no repositório azure-cognitive-services/translator e é chamado text-translation. O nome da imagem de contêiner totalmente qualificada é mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest.

Para usar a versão mais recente do contêiner, use a tag mais recente. Você pode exibir a lista completa de tags de versão de tradução de texto dos serviços de IA do Azure no MCR.

Utilizar contentores

Selecione uma guia para escolher seu ambiente de contêiner do Azure AI Translator:

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]

Validar se um contêiner está em execução

Há várias maneiras de validar se o contêiner está em execução:

• O contêiner fornece uma página inicial como / uma validação visual de que o contêiner está sendo executado.

• Você pode abrir seu navegador favorito e navegar até o endereço IP externo e a porta exposta do contêiner em questão. Use as seguintes URLs de solicitação para validar que o contêiner está em execução. Os URLs de solicitação de exemplo listados apontam para http://localhost:5000, mas seu contêiner específico pode variar. Lembre-se de que você está navegando para o endereço IP externo e a porta exposta do contêiner.

Se você estiver tendo problemas para executar um contêiner de serviços de IA do Azure, tente usar o contêiner de diagnóstico da Microsoft. Use esse contêiner para diagnosticar erros comuns em seu ambiente de implantação que podem impedir que os contêineres de IA do Azure funcionem conforme o esperado.

Para obter o contêiner, use o seguinte docker pull comando:

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

Em seguida, execute o contêiner. Substitua {ENDPOINT_URI} pelo ponto de extremidade e substitua {API_KEY} pela chave do recurso:

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

O contêiner testa a conectividade de rede com o ponto de extremidade de faturamento.

Parar o contentor

Para desligar o contêiner, no ambiente de linha de comando em que o contêiner está sendo executado, selecione Ctrl+C.

Casos de uso para suporte a contêineres

Algumas consultas do Translator exigem contêineres de suporte para concluir as operações com êxito. Se estiver a utilizar documentos do Office e não necessitar de deteção de idioma de origem, apenas é necessário o contentor Translator. No entanto, se a deteção do idioma de origem for necessária ou se você estiver usando documentos PDF digitalizados, os contêineres de suporte serão necessários:

A tabela a seguir lista os contêineres de suporte necessários para suas operações de tradução de texto e documentos. O contêiner Translator envia informações de cobrança para o Azure por meio do recurso Azure AI Translator em sua conta do Azure.

Opere contentores de suporte com docker compose

O Docker compose é uma ferramenta que permite configurar aplicativos de vários contêineres usando um único arquivo YAML normalmente chamado compose.yaml. Use o docker compose up comando para iniciar seu aplicativo de contêiner e o docker compose down comando para parar e remover seus contêineres.

Se você instalou a CLI do Docker Desktop, ela inclui a composição do Docker e seus pré-requisitos. Se você não tiver o Docker Desktop, consulte a Visão geral da instalação do Docker Compose.

Criar a sua aplicação

1. Usando seu editor ou IDE preferido, crie um novo diretório para seu aplicativo nomeado container-environment ou um nome de sua escolha.

2. Crie um novo arquivo YAML chamado compose.yaml. As extensões .yml ou .yaml podem ser usadas para o compose arquivo.

3. Copie e cole o seguinte exemplo de código YAML em seu compose.yaml arquivo. Substitua {TRANSLATOR_KEY} e {TRANSLATOR_ENDPOINT_URI} pelos valores de chave e ponto de extremidade da sua instância do Tradutor do portal do Azure. Se estiver a traduzir documentos, certifique-se de que utiliza o document translation endpoint.

4. O nome de nível superior (azure-ai-translator, azure-ai-language, azure-ai-read) é o parâmetro que você especifica.

5. O container_name é um parâmetro opcional que define um nome para o contêiner quando ele é executado, em vez de permitir gerar docker compose um 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. Abra um terminal Navegue até a container-environment pasta e inicie os contêineres com o seguinte docker-compose comando:

   docker compose up
   

7. Para parar os contêineres, use o seguinte comando:

   docker compose down
   

   Gorjeta

   Comandos úteis do Docker:

   • docker compose pause Pausa a execução de contêineres.
   • docker compose unpause {your-container-name} unpausa recipientes pausados.
   • docker compose restart Reinicia todo o contêiner parado e em execução com todas as suas alterações anteriores intactas. Se você fizer alterações na configuração compose.yaml , essas alterações não serão atualizadas com o docker compose restart comando. Você precisa usar o docker compose up comando para refletir atualizações e alterações no compose.yaml arquivo.
   • docker compose ps -a Lista todos os contêineres, incluindo aqueles que estão parados.
   • docker compose exec Permite executar comandos para desanexar ou definir variáveis de ambiente em um contêiner em execução.

   Para obter mais informações, consulte Referência da CLI do docker.

Tradutor e suporte a imagens e tags de contêiner

As imagens de contêiner de serviços de IA do Azure podem ser encontradas no catálogo do Registro de Artefato da Microsoft. A tabela a seguir lista o local de imagem totalmente qualificado para tradução de texto e documento:

Outros parâmetros e comandos

Aqui estão mais alguns parâmetros e comandos que você pode usar para executar o contêiner:

Registos de utilização

Ao operar contêineres do Docker em um ambiente desconectado, o contêiner gravará registros de uso em um volume onde eles serão coletados ao longo do tempo. Você também pode chamar um ponto de extremidade da API REST para gerar um relatório sobre o uso do serviço.

Argumentos para armazenar logs

Quando executado em um ambiente desconectado, uma montagem de saída deve estar disponível para o contêiner para armazenar logs de uso. Por exemplo, você incluiria -v /host/output:{OUTPUT_PATH} e Mounts:Output={OUTPUT_PATH} , no exemplo a seguir, substituiria {OUTPUT_PATH} pelo caminho onde os logs são armazenados:

Exemplo docker run de comando

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

Nomes de variáveis de ambiente em implantações do Kubernetes

• Alguns Contêineres de IA do Azure, por exemplo o Translator, exigem que os usuários passem nomes de variáveis ambientais que incluam dois pontos (:) ao executar o contêiner.

• O Kubernetes não aceita dois pontos em nomes de variáveis ambientais. Para resolver, você pode substituir dois pontos por dois caracteres de sublinhado (__) ao implantar no Kubernetes. Veja o seguinte exemplo de um formato aceitável para nomes de variáveis ambientais:

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

Este exemplo substitui o formato padrão para os nomes das Mounts:License variáveis e Mounts:Output de ambiente no comando docker run.

Obter registros de uso usando os pontos de extremidade do contêiner

O contêiner fornece dois pontos de extremidade para retornar registros em relação ao seu uso.

Obter todos os registos

O ponto de extremidade a seguir fornece um relatório resumindo todo o uso coletado no diretório de registro de faturamento montado.

https://<service>/records/usage-logs/

Exemplo de ponto de extremidade HTTPS para recuperar todos os registros

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

Obter registos para um mês específico

O ponto de extremidade a seguir fornece um relatório resumindo o uso em um mês e ano específicos:

https://<service>/records/usage-logs/{MONTH}/{YEAR}

Exemplo de ponto de extremidade HTTPS para recuperar registros de um mês e ano específicos

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

Os pontos de extremidade de logs de uso retornam uma resposta JSON semelhante ao exemplo a seguir:

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

Resumo

Neste artigo, você aprendeu conceitos e fluxos de trabalho para baixar, instalar e executar um contêiner do Azure AI Translator:

• O contêiner do Azure AI Translator dá suporte à tradução de texto, tradução síncrona de documentos e transliteração de texto.

• As imagens de contêiner são baixadas do registro de contêiner e executadas no Docker.

• As informações de faturamento devem ser especificadas quando você instanciar um contêiner.

Próximos passos