Partilhar via

Instalar e executar o contêiner do Azure AI Translator

  • Artigo

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

Importante

Seu recurso de tradutor deve atender aos seguintes requisitos:

  • Sua instância do Translator deve ser um recurso do Translator (não um recurso de serviços de IA do Azure multisserviços).

  • Sua instância do Translator deve ser um recurso regional (não um recurso global do Azure AI Translator) dentro da região geográfica do Azure disponível. Para obter mais informações, consulte Opções de preços de região do Azure AI Translator.

  • 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 regional do Azure AI Translator criado sob sua 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.

      Captura de tela da seleção da camada de preços para o contêiner conectado ao Translator.

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

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

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.

Gorjeta

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

O DockerDesktop inclui o Docker Engine, o cliente Docker CLI, o Docker Compose e fornece pacotes que configuram o Docker para o seu sistema operacional preferido:

Ferramenta Description 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ê crie, execute e gerencie seus contêineres. Necessário para todas as operações.
Docker Compose A ferramenta Docker Compose é usada para definir e executar aplicativos de vários contêineres. Necessário para suportar contentores.
Docker CLI A interface de linha de comando do Docker permite que você interaja com o Docker Engine e gerencie contêineres do Docker diretamente de sua máquina local. Recomendadas
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:

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

Nota

As especificações mínimas e recomendadas são baseadas nos limites do Docker, não nos recursos da máquina host.

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

Function Mínimo recomendado Notas
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• é GB de memória.
• Exemplo: 8 núcleos, 32 GB de memória podem processar seis (6) documentos simultâneos [mínimo de (8-2), (36-6)/4)].

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

Importante

  • As chaves são usadas para acessar seu recurso de IA do Azure. Não partilhe as chaves. Armazene-os de forma segura, por exemplo, usando o Azure Key Vault.

  • Recomendamos também que gere novas chaves regularmente. Só é necessária uma chave para fazer uma chamada à API. Ao gerar novamente a primeira chave, pode utilizar a segunda chave para o acesso continuado ao serviço.

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:

Opção Description
ApiKey A chave do recurso de serviços de IA do Azure usada para rastrear 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 de 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 provisionado do Azure.
Eula Indica que você aceitou a licença para o contêiner.
O valor desta opção deve ser definido como accept.

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:

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

Baixar e executar imagem de contêiner

O comando docker run baixa uma imagem do Microsoft Artifact Registry e inicia o contêiner.

Importante

  • Os comandos docker nas seções a seguir usam a barra invertida, \, como um caractere de continuação de linha. Substitua ou remova isso com base nos requisitos do sistema operacional do host.
  • As EULAopções , Billinge devem ApiKey ser especificadas para executar o contêiner, caso contrário, o contêiner não será iniciado.
  • Se estiver a traduzir documentos, certifique-se de que utiliza o ponto de extremidade de tradução de documentos.
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 Docker:

  • Cria um contêiner do Translator em execução a partir de uma imagem de contêiner baixada.
  • Aloca 12 gigabytes (GB) de memória e quatro núcleos de CPU.
  • Expõe a porta TCP (transmission control protocol) 5000 e aloca um pseudo-TTY para o contêiner. Agora, o localhost endereço aponta para o contêiner em si, não para sua máquina host.
  • Aceita o contrato de utilizador final (EULA).
  • Configura o ponto de extremidade de faturamento.
  • Downloads de modelos de tradução para idiomas Inglês, Francês, Espanhol, Árabe e Russo.
  • Remove automaticamente o recipiente depois que ele sai. A imagem do contêiner ainda está disponível no computador host.

Gorjeta

Comando Docker adicional:

  • 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} Interrompe um recipiente pausado.
  • docker restart {your-container-name} Reinicia um contêiner em execução.
  • docker exec Permite executar comandos LTO 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.

Executar vários contêineres no mesmo host

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

Você pode ter esse contêiner e um contêiner de IA do Azure diferente em execução no HOST juntos. Você também pode ter vários contêineres do mesmo contêiner do Azure AI em execução.

Consultar o ponto de extremidade do contêiner do Translator

O contêiner fornece uma API de ponto de extremidade do Translator baseada em REST. Aqui está um exemplo de solicitação 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?'}]"

Nota

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

  • Se a solicitação cURL POST retornar uma Service is temporarily unavailable resposta, 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 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.

URL do Pedido Propósito
http://localhost:5000/ O contentor 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 sondas de vivacidade e prontidão do Kubernetes.
http://localhost:5000/status Solicitado com GET. Verifica se a chave de api usada para iniciar o contêiner é válida sem causar uma consulta de ponto de extremidade. Essa solicitação pode ser usada para sondas de vivacidade e prontidão do Kubernetes.
http://localhost:5000/swagger O contentor fornece um conjunto completo de documentação para os pontos finais e uma funcionalidade Experimentar. Com esse recurso, você pode inserir suas configurações em um formulário HTML baseado na Web e fazer a consulta sem ter que escrever nenhum código. Depois que a consulta retorna, um comando CURL de exemplo é fornecido para demonstrar os cabeçalhos HTTP necessários e o formato do corpo.

Captura de tela da página inicial 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.

Operação Solicitar consulta Document type Contentores de suporte
•Tradução de texto
• Tradução de documentos		 from especificado. Documentos do Office Nenhuma
•Tradução de texto
• Tradução de documentos		 from não especificado. Requer deteçã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 documentos		 from especificado. Documentos PDF digitalizados ✔️ Visão:recipiente de leitura
•Tradução de texto
• Tradução de documentos		 from não especificado exigindo deteção automática de idioma para determinar o idioma de origem. Documentos PDF digitalizados ✔️ Análise de texto:contêiner de idioma

✔️ Visão:recipiente de leitura

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:

Contentor Localização da imagem Notas
Tradutor: Tradução de textos e documentos mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest 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.
Análise de texto: idioma mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest Você pode exibir a lista completa de tags de versão de linguagem de análise de texto dos serviços de IA do Azure no MCR.
Visão: ler mcr.microsoft.com/azure-cognitive-services/vision/read:latest Você pode exibir a lista completa de tags de versão de leitura de visão computacional dos serviços de IA OCR do Azure 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:

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:

Contentor ligado

As taxas de utilização são calculadas com base no quantity valor.

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

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

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