Compartilhar via

Instalar e executar o contêiner do Tradutor de IA do Azure

  • Artigo

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

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

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

  • 🆕 Transliteração de texto. Converta, em tempo real, o texto de um script de idioma ou sistema de escrita em outro script de idioma ou sistema de escrita. Para obter mais informações, confira Contêiner: transliterar textos.

  • 🆕 Tradução de documento. Traduza documentos em tempo real e de forma síncrona e ainda preservando a estrutura e o formato. Para obter mais informações, confira Contêiner: traduzir documentos.

Pré-requisitos

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

Recursos do Azure

  • Uma assinatura do Azure ativa. Se você não tiver uma, poderá criar uma conta gratuita por 12 meses.

  • Uma solicitação de acesso aprovada para um Contêiner conectado do Tradutor ou um Contêiner desconectado do tradutor.

  • Um recurso do Tradutor de IA do Azure (não um recurso de serviços de IA do Azure de vários serviços) criado na ID de assinatura aprovada. Você precisa da chave de API e do URI do ponto de extremidade associados ao seu recurso. Os dois 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 do Tradutor, selecione o tipo de preço S1.

      Captura de tela da seleção do tipo de preço para o contêiner conectado do Tradutor.

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

      Captura de tela mostrando a criação de recursos no portal do Azure.

Ferramentas do Docker

É necessário ter uma compreensão básica dos conceitos do Docker, como registros, repositórios, contêineres e imagens de contêiner, bem como conhecimento da terminologia e comandos básicos do docker. Para instruções sobre conceitos básicos do Docker e de contêiner, consulte a visão geral do Docker.

Dica

Cogite adicionar o Docker Desktop ao seu ambiente de computação. O Docker Desktop é uma GUI (interface gráfica do usuário) que permite criar, executar e compartilhar aplicativos em contêineres diretamente da área de trabalho.

O DockerDesktop inclui o Docker Engine, o cliente da CLI do Docker, o Docker Compose e fornece pacotes que configuram o Docker para seu sistema operacional de preferência:

Ferramenta Descrição Condição
Mecanismo do Docker O Docker Engine é o componente principal da plataforma de conteinerização do Docker. Ele deve ser instalado em um computador host para permitir que você compile, execute e gerencie seus contêineres. Necessário para todas as operações.
Docker Compose A ferramenta do Docker Compose é usada para definir e executar aplicativos de vários contêineres. Necessário para dar suporte a contêineres.
CLI do Docker A interface de linha de comando do Docker permite que você interaja com o Docker Engine e gerencie contêineres do Docker diretamente do computador local. Recomendado
Requisitos do computador host

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

Sistema operacional Requisitos do sistema
Windows • Windows 10 ou Windows 11 instalado
• Processador de 64 bits
• Um mínimo de 4 GB de RAM
• Recursos do Windows Hyper-V e de contêiner, além da virtualização de hardware no nível do BIOS
• Para obter mais informações, confira Instalar o Docker Desktop no Windows
Mac • Modelo de computador 2010 ou posterior
• OS 10.13 ou posterior
• Um mínimo de 4 GB de RAM
• Para obter mais informações, confira Instalar o Docker Desktop no Mac
Linux • Versão de 64 bits do Ubuntu [versão mais recente do LTS (suporte a longo prazo) ou versão atual não LTS], Debian 12, Fedora 38 ou Fedora 39
• Suporte à CPU para virtualização
• Um mínimo de 4 GB de RAM
• Para obter mais informações, confira Instalar o Docker Desktop no Linux

Observação

Os valores mínimos e recomendados se baseiam nos limites do Docker e não nos recursos do computador host.

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

Função Mínimo recomendado Observações
Tradução de texto 4 núcleos, 4 GB de memória
Transliteração de texto 4 núcleos, 2 GB de memória
Tradução de documentos 4 núcleos, 6 GB de memória O número de documentos que podem ser processados simultaneamente pode ser calculado com a seguinte fórmula: [mínimo de (n-2), (m-6)/4)].
• n é o número de núcleos de CPU.
• m é a quantidade de GB de memória.
• Exemplo: 8 núcleos e 32 GB de memória podem processar seis (6) documentos simultâneos [mínimo de (8-2), (36-6)/4)].

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

  • Para cada par de idiomas, é recomendável ter 2 GB de memória.

  • Além dos requisitos básicos, é preciso ter 4 GB de memória para cada processamento de documento simultâneo.

    Dica

    Você pode usar o comando imagens do estivador para listar as imagens do contêiner transferidas por download. Por exemplo, o comando a seguir lista o ID, o repositório e a tag de cada imagem do contêiner transferida por download, 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 Requerida

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

  • Configuração de aceitação do EULA. Você deve ter um EULA (contrato de licença de usuário final) em vigor e com um valor de Eula=accept.

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

  • Se estiver traduzindo documentos, lembre-se de usar o ponto de extremidade de tradução de documento.

Importante

  • As chaves são usadas para acessar seu recurso do IA do Azure. Não compartilhe suas chaves. Armazene-as com segurança, por exemplo, usando o Azure Key Vault.

  • Recomendamos a regeneração regular dessas chaves. Apenas uma chave é necessária para fazer uma chamada à API. Ao regenerar a primeira chave, você pode usar a segunda chave para obter acesso contínuo ao serviço.

Cobrança

  • Consultas para o contêiner são cobradas pelo tipo 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 de docker run baixa uma imagem do Registro de Artefato da Microsoft e inicia o contêiner quando todas as três opções a seguir são fornecidas com valores válidos:

Opção Descrição
ApiKey A chave do recurso dos serviços de IA do Azure utilizada para rastrear as informações de cobrança.
O valor dessa opção deve ser definido como uma chave para o recurso provisionado especificado em Billing.
Billing O ponto de extremidade do recurso dos serviços de IA do Azure usado para rastrear informações de cobrança.
O valor dessa opção deve ser definido como o URI do ponto de extremidade de um recurso do Azure provisionado.
Eula Indica que você aceitou a licença do contêiner.
O valor dessa opção deve ser definido como aceitar.

Como conectar-se ao Azure

  • Os valores do argumento de cobrança do contêiner permitem que o contêiner seja conectado ao ponto de extremidade de cobrança 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, ele continuará sendo executado, mas não atenderá a consultas até que o ponto de extremidade de cobrança seja restaurado.

  • Serão realizadas 10 tentativas de conexão no mesmo intervalo de tempo de 10 a 15 minutos. Se não for possível conectar-se ao ponto de extremidade de cobrança dentro das 10 tentativas, o contêiner interromperá as solicitações de serviço. Veja as Perguntas frequentes sobre a IA do Azure para obter um exemplo das informações enviadas à Microsoft para cobrança.

Imagens e marcas de contêiner

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

Para usar a versão mais recente do contêiner, use a marca mais recente. Você pode exibir a lista completa das marcas de versão da Tradução de texto dos serviços de IA do Azure no MCR.

Usar contêineres

Selecione uma guia para escolher seu ambiente de contêiner do Tradutor de IA do Azure:

Os contêineres do Tradutor de IA do Azure permitem que você execute o serviço de Tradutor de IA do Azure on-premise em seu próprio ambiente. Os contêineres conectados são executados localmente e enviam informações de uso para a nuvem para fins de cobrança.

Baixar e executar imagem de contêiner

O comando docker run baixa uma imagem do Registro de Artefato da Microsoft e inicia o contêiner.

Importante

  • os comandos do Docker nas seções a seguir usam a barra invertida, \, como um caractere de continuação de linha. Substitua ou remova essa barra com base nos requisitos do sistema operacional de seu computador host.
  • As opções EULA, Billing e ApiKey devem ser especificadas para executar o contêiner; caso contrário, o contêiner não será iniciado.
  • Se estiver traduzindo documentos, lembre-se de usar o ponto de extremidade de tradução de documento.
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

O comando do Docker:

  • Cria um contêiner do Tradutor em execução a partir de uma imagem de contêiner baixada.
  • Aloca 12 GB (gigabytes) de memória e quatro núcleos de CPU.
  • Expõe a porta TCP (protocolo TCP) 5000 e aloca um pseudo-TTY para o contêiner. Agora, o endereço localhost aponta para o contêiner em si, não para o computador host.
  • Aceita o EULA (contrato do usuário final).
  • Configura o ponto de extremidade de cobrança.
  • Baixa modelos de tradução para os idiomas inglês, francês, espanhol, árabe e russo.
  • Remove automaticamente o contêiner depois que ele sai. A imagem de contêiner ainda fica disponível no computador host.

Dica

Comando adicional do Docker:

  • docker ps lista contêineres em execução.
  • docker pause {your-container name} pausa um contêiner em execução.
  • docker unpause {your-container-name} retoma um contêiner pausado.
  • docker restart {your-container-name} reinicia um contêiner em execução.
  • docker exec permite executar comandos para desanexar ou definir variáveis de ambiente em um contêiner em execução.

Para obter mais informações, confira Referência da CLI do Docker.

Executar vários contêineres no mesmo host

Se você pretende executar vários contêineres com portas expostas, execute cada um deles com uma porta exposta diferente. Por exemplo, execute o primeiro contêiner na porta 5000 e o segundo contêiner na porta 5001.

É possível ter esse contêiner e um contêiner do IA do Azure em execução no HOST juntos. Também é possível ter vários contêineres do mesmo contêiner de IA do Azure em execução.

Consultar o ponto de extremidade de contêiner do Tradutor

O contêiner fornece uma API de ponto de extremidade do Tradutor baseada em REST. Aqui está uma solicitação de exemplo com o idioma de origem (from=en) especificado:

  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?'}]"

Observação

  • A detecção do idioma de origem requer um contêiner adicional. Para obter mais informações, confira Suporte a contêineres

  • Se a solicitação cURL POST retornar uma resposta Service is temporarily unavailable, o contêiner não estará pronto. Aguarde alguns minutos e tente novamente.

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

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

  • O contêiner fornece uma home page em / como uma validação visual de que o contêiner está em execução.

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

URL de Solicitação Finalidade
http://localhost:5000/ O contêiner fornece uma home page.
http://localhost:5000/ready Solicitado com GET. Fornece uma verificação de que o contêiner está pronto para aceitar uma consulta em relação ao modelo. Essa solicitação pode ser usada para testes de preparação e de execução do Kubernetes.
http://localhost:5000/status Solicitado com GET. Verifica se a chave API usada para iniciar o contêiner é válida sem causar uma consulta de terminal. Essa solicitação pode ser usada para testes de preparação e de execução do Kubernetes.
http://localhost:5000/swagger O contêiner fornece um conjunto completo de documentação para os pontos de extremidade e um recurso Experimentar. Com esse recurso, é possível inserir suas configurações em um formulário HTML baseado na Web e realizar a consulta sem precisar escrever nenhum código. Depois que a consulta é retornada, um exemplo de comando CURL é fornecido para demonstrar o formato do corpo e dos cabeçalhos HTTP exigidos.

Captura de tela da página inicial do contêiner.

Se você estiver tendo problemas para executar um contêiner dos serviços de IA do Azure, tente usar o contêiner de diagnóstico da Microsoft. Use esse contêiner para diagnosticar erros comuns no 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 comando docker pull:

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

Em seguida, execute o contêiner. Substitua {ENDPOINT_URI} pelo ponto de extremidade e {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 cobrança.

Parar o contêiner

Para desligar o contêiner, no ambiente de linha de comando em que o contêiner estiver em execução, selecione Ctrl+C.

Casos de uso para dar suporte a contêineres

Algumas consultas do Tradutor exigem o suporte a contêineres para concluir as operações com êxito. Se você estiver usando documentos do Office e não precisar da detecção do idioma de origem, somente o contêiner do Tradutor será necessário. No entanto, se a detecção do idioma de origem for necessária ou se você estiver usando documentos PDF verificados, 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 documento. O contêiner do Tradutor envia informações de cobrança para o Azure por meio do recurso do Tradutor de IA do Azure na sua conta do Azure.

Operação Solicitação consulta Tipo de documento Contêineres de suporte
• Tradução de texto
• Tradução de documento		 from especificado. Documentos do Office Nenhum
• Tradução de texto
• Tradução de documento		 from não especificado. Requer a detecção automática de idioma para determinar o idioma de origem. Documentos do Office ✔️ Análise de texto:contêiner de idioma
• Tradução de texto
• Tradução de documento		 from especificado. Documentos PDF verificados ✔️ Vision: ler contêiner
• Tradução de texto
• Tradução de documento		 from não especificado, exigindo a detecção automática do idioma para determinar o idioma de origem. Documentos PDF verificados ✔️ Análise de texto:contêiner de idioma

✔️ Vision: ler contêiner

Operar contêineres 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 comando docker compose up para iniciar seu aplicativo de contêiner e o comando docker compose down para parar e remover seus contêineres.

Caso tenha instalado a CLI do Docker Desktop, ela inclui o Docker Compose e seus pré-requisitos. Caso não tenha o Docker Desktop, confira a Visão geral da instalação do Docker Compose.

Criar o aplicativo

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

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

  3. Copie e cole o exemplo de código YAML a seguir em seu arquivo compose.yaml. Substitua {TRANSLATOR_KEY} e {TRANSLATOR_ENDPOINT_URI} pelos valores da chave e do ponto de extremidade da instância do Tradutor do portal do Azure. Se você estiver traduzindo documentos, lembre-se de usar 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 deixar docker compose gerar 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 pasta container-environment e inicie os contêineres com o seguinte comando docker-compose:

    docker compose up

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

    docker compose down

    Dica

    Comandos úteis do Docker:

    • docker compose pause pausa a execução de contêineres.
    • docker compose unpause {your-container-name} retoma os contêineres pausados.
    • docker compose restart reinicia todos os contêineres parados e em execução com todas as alterações anteriores intactas. Se você fizer alterações na configuração compose.yaml, elas não serão atualizadas com o comando docker compose restart. Você precisa usar o comando docker compose up para refletir atualizações e alterações no arquivo compose.yaml.
    • 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, confira Referência da CLI do Docker.

Imagens e marcas do Tradutor e do contêiner de suporte

As imagens de contêiner dos 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 a tradução de texto e documento:

Contêiner Local da imagem Observações
Tradutor: tradução de texto e documento mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest Você pode exibir a lista completa das marcas de versão da Tradução de texto dos serviços de IA do Azure no MCR.
Análise de texto: idioma mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest Você pode exibir a lista completa das marcas de versão do Idioma da Análise de Texto de serviços de IA do Azure no MCR.
Visão: leitura mcr.microsoft.com/azure-cognitive-services/vision/read:latest Você pode exibir a lista completa das marcas de versão da Leitura da Pesquisa Visual Computacional dos serviços de IA do Azure OCR no MCR.

Outros parâmetros e comandos

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

Registros de uso

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

Argumentos para armazenar logs

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

Exemplo do comando docker run

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, como por exemplo o Tradutor, exigem que os usuários passem nomes de variáveis ambientais que incluem dois-pontos (:) ao executar o contêiner.

  • O Kubernetes não aceita dois-pontos em nomes de variáveis de ambiente. Para resolver isso, você pode substituir dois-pontos por caracteres de sublinhado duplo (__) ao implantar no Kubernetes. Consulte 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 de variáveis de ambiente Mounts:License e Mounts:Output no comando de execução do docker.

Obter registros de uso por meio dos pontos de extremidade do contêiner

O contêiner fornece dois pontos de extremidade para retornar os registros sobre seu uso.

Obter todos os registros

O ponto de extremidade a seguir fornece um relatório com o resumo de todo o uso coletado no diretório de registro de cobrança montado.

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

Exemplo de ponto de extremidade do HTTPS para recuperar todos os registros

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

Obter registros de 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 para 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 seguinte exemplo:

Contêiner conectado

Os preços de uso são calculados com base no valor de quantity.

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

Resumo

Neste artigo, você aprendeu informações sobre o fluxo de trabalho e conceitos usados para baixar, instalar e executar um contêiner do Tradutor de IA do Azure:

  • O contêiner do Tradutor de IA do Azure dá suporte para tradução de texto, tradução de documento síncrona e transliteração de texto.

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

  • A informações de cobrança devem ser especificadas quando você instanciar um contêiner.

Próximas etapas

Saiba mais sobre a configuração de contêiner de IA do Azure Saiba mais sobre o suporte ao idioma do contêiner.