Installer et exécuter des conteneurs Translator (préversion)

Les conteneurs vous permettent d’exécuter plusieurs des fonctionnalités du service Translator dans votre propre environnement. Les conteneurs conviennent particulièrement bien à certaines exigences de sécurité et de gouvernance des données. Cet article explique comment télécharger, installer et exécuter un conteneur Translator.

Les conteneurs Translator vous permettent de créer une architecture d’application Translator optimisée pour tirer parti des fonctionnalités robustes du cloud et de la localité en périphérie.

Lors de l’utilisation de conteneurs Translator, consultez la liste des langues prises en charge.

Important

  • Le conteneur Translator est disponible en préversion contrôlée. Pour l’utiliser, vous devez envoyer une demande en ligne et obtenir une approbation. Pour plus d’informations, consultez la section Demande d’approbation pour l’exécution du conteneur, plus loin dans cet article.
  • Le conteneur Translator prend en charge des fonctionnalités limitées par rapport aux offres cloud. Consultez Méthodes de traduction de conteneurs pour plus d’informations.

Prérequis

Pour commencer, vous avez besoin d’un compte Azure actif. Si vous n’en avez pas, vous pouvez créer un compte gratuit.

Vous devez également disposer des éléments suivants :

Obligatoire Objectif
Bonne connaissance de Docker
  • Vous devez comprendre les concepts de base liés à Docker (comme les registres, les référentiels, les conteneurs et les images conteneur), et connaître les principaux dockertermes et commandes.
Moteur Docker
  • Vous avez besoin d’un moteur Docker installé sur un ordinateur hôte. Docker fournit des packages qui configurent l’environnement Docker sur macOS, Windows et Linux. Pour apprendre les principes de base de Docker et des conteneurs, consultez la vue d’ensemble de Docker.
  • Vous devez configurer Docker pour permettre aux conteneurs de se connecter à Azure et de lui envoyer des données de facturation.
  • Sur Windows, vous devez également configurer Docker pour la prise en charge des conteneurs Linux.
Ressource Translator
  • Une ressource Azure Translator avec une région autre que « global », avec une clé API et un URI de point de terminaison associés. Les deux valeurs sont requises pour démarrer le conteneur ; elles sont indiquées dans la page de vue d’ensemble de la ressource.
Facultatif Objectif
Azure CLI (interface de ligne de commande)
  • L’interface Azure CLI vous permet d’utiliser un ensemble de commandes en ligne pour créer et gérer des ressources Azure. Elle peut s’installer dans les environnements Windows, macOS et Linux, et s’exécuter dans un conteneur Docker et Azure Cloud Shell.

Éléments obligatoires

Tous les conteneurs Cognitive Services nécessitent trois éléments principaux :

  • Un paramètre d’acceptation du CLUF. Un contrat de licence utilisateur final (CLUF) défini avec la valeur Eula=accept.

  • Une clé API et une URL de point de terminaison. La clé API sert à démarrer le conteneur. Vous pouvez obtenir les valeurs de la clé API et de l’URL de point de terminaison en accédant à la page Clés et point de terminaison de la ressource Translator, puis en sélectionnant l’icône Copy to clipboard.

Important

  • Vous utilisez des clés pour accéder à votre API Cognitive Service. Ne partagez pas vos clés. Stockez-les en toute sécurité, par exemple, à l’aide de Azure Key Vault. Nous vous recommandons également de régénérer ces clés régulièrement. Une seule clé est nécessaire pour effectuer un appel d’API. Lors de la régénération de la première clé, vous pouvez utiliser la deuxième clé pour un accès continu au service.

Ordinateur hôte

L’hôte est un ordinateur x64 qui exécute le conteneur Docker. Il peut s’agir d’un ordinateur local ou d’un service d’hébergement Docker dans Azure, comme :

Exigences et suggestions relatives au conteneur

Le tableau suivant décrit les spécifications minimales et recommandées pour les conteneurs Translator. Au moins 2 gigaoctets (Go) de mémoire sont requis, et chaque CPU doit être cadencé à au moins 2,6 gigahertz (GHz). Plus 8 gigaoctets (Go) de mémoire à allouer pour chaque conteneur Translator. Le tableau suivant décrit l’allocation de ressources minimale et recommandée pour chaque conteneur Translator.

Conteneur Minimum Recommandé Paire de langues
Translator connecté 2 cœurs, 2 Go de mémoire 4 cœurs, 8 Go de mémoire 4

Pour chaque paire de langues, il est recommandé d’avoir 2 Go de mémoire. Par défaut, le conteneur Translator hors connexion a quatre paires de langues. Le nombre de cœurs et la quantité de mémoire correspondent aux paramètres --cpus et --memory qui sont utilisés dans le cadre de la commande docker run.

Notes

  • Le nombre de cœurs et la quantité de mémoire CPU correspondent aux paramètres --cpus et --memory qui sont utilisés dans la commande « docker run ».

  • Les spécifications minimale et recommandée sont basées sur les limites de Docker, pas sur les ressources de la machine hôte.

Demande d’approbation pour l’exécution d’un conteneur

Complétez et envoyez le formulaire des services contrôlés Azure Cognitive Services pour demander l’accès au conteneur.

Le formulaire demande des informations sur vous, votre entreprise et le scénario d’utilisateur pour lequel vous allez utiliser le conteneur. Une fois le formulaire envoyé, l’équipe Azure Cognitive Services l’examinera et vous informera de sa décision par e-mail dans les 10 jours ouvrables.

Important

  • Dans le formulaire, vous devez utiliser une adresse e-mail associée à un ID d’abonnement Azure.
  • La ressource Azure que vous utilisez pour exécuter le conteneur doit avoir été créée avec l’ID d’abonnement Azure approuvé.
  • Vérifiez votre adresse e-mail (boîtes de réception et dossiers de courrier indésirable) pour obtenir des mises à jour sur l’état de votre application auprès de Microsoft.

Une fois l’approbation obtenue, vous pourrez exécuter le conteneur après l’avoir téléchargé à partir de Microsoft Container Registry, décrit plus loin dans cet article.

Vous ne pourrez pas exécuter le conteneur si votre abonnement Azure n’a pas été approuvé.

Obtenir des images conteneurs en utilisant les commandes docker

Important

  • les commandes docker dans les sections suivantes utilisent la barre oblique inverse, \, comme caractère de continuation de ligne. Remplacez-la ou supprimez-la en fonction des exigences de votre système d’exploitation hôte.
  • Vous devez spécifier les options EULA, Billing et ApiKey pour exécuter le conteneur, sinon il ne démarrera pas.

Utilisez la commande docker run pour télécharger une image conteneur du registre de conteneurs Microsoft et l’exécuter.

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:1.0.019410001-amd64-preview

La commande ci-dessus :

  • Télécharge et exécute un conteneur Translator à partir de l’image conteneur.
  • Alloue 12 gigaoctets (Go) de mémoire et quatre cœurs CPU.
  • Expose le port TCP 5000 et alloue un pseudo-TTY pour le conteneur
  • Accepte le contrat de licence utilisateur final (CLUF).
  • Configure le point de terminaison de facturation.
  • Télécharge des modèles de traduction pour certaines langues (anglais, français, espagnol, arabe et russe).
  • Supprime automatiquement le conteneur après sa fermeture. L’image conteneur est toujours disponible sur l’ordinateur hôte.

Exécuter plusieurs conteneurs sur le même hôte

Si vous envisagez d’exécuter plusieurs conteneurs avec les ports exposés, veillez à exécuter chaque conteneur avec un port exposé différent. Par exemple, exécutez le premier conteneur sur le port 5000 et le second conteneur sur le port 5001.

Vous pouvez avoir ce conteneur, et un autre conteneur Azure Cognitive Services qui s’exécutent ensemble sur l’hôte. Vous pouvez également disposer de plusieurs conteneurs du même conteneur Cognitive Services en cours d’exécution.

Interroger le point de terminaison Translator du conteneur

Le conteneur fournit une API de point de terminaison REST pour Translator. Voici un exemple de requête :

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

Notes

Si vous tentez la requête cURL POST avant que le conteneur soit prêt, vous obtenez en réponse un message Le service est temporairement indisponible. Attendez que le conteneur soit prêt, puis réessayez.

Arrêter le conteneur

Pour arrêter le conteneur, dans l’environnement de ligne de commande où le conteneur est en cours d’exécution, sélectionnez Ctrl+C.

Dépanner

Valider l’exécution d’un conteneur

Il existe plusieurs façons de vérifier que le conteneur est exécuté :

  • Le conteneur fournit une page d’accueil au niveau \, qui est une validation visuelle que le conteneur est en cours d’exécution.

  • Vous pouvez ouvrir votre navigateur web habituel, puis accéder à l’adresse IP externe et au port exposé du conteneur en question. Utilisez les différentes URL de requête ci-dessous pour vérifier que le conteneur est en cours d’exécution. Les exemples d’URL de requête listés ci-dessous sont http://localhost:5000, mais votre conteneur spécifique peut varier. N’oubliez pas que vous accédez à l’adresse IP externe et au port exposé de votre conteneur.

URL de la demande Objectif
http://localhost:5000/ Le conteneur fournit une page d’hébergement.
http://localhost:5000/ready Obligatoire avec GET. Vérifie si le conteneur est prêt à accepter une requête sur le modèle. Cette requête peut être utilisée pour les probes liveness et readiness de Kubernetes.
http://localhost:5000/status Obligatoire avec GET. Vérifie si la clé API servant à démarrer le conteneur est valide sans provoquer de requête de point de terminaison. Cette requête peut être utilisée pour les probes liveness et readiness de Kubernetes.
http://localhost:5000/swagger Le conteneur fournit un ensemble complet de documentation pour les points de terminaison et une fonctionnalité Essayer. Avec cette fonctionnalité, vous pouvez entrer vos paramètres dans un formulaire HTML basé sur le web, et constituer la requête sans avoir à écrire du code. Une fois la requête retournée, un exemple de commande CURL est fourni pour illustrer les en-têtes HTTP, et le format du corps qui est nécessaire.

Container home page

Si vous rencontrez des problèmes lors de l’exécution d’un conteneur Cognitive Services, essayez d’utiliser le conteneur de diagnostics Microsoft. Utilisez ce conteneur pour diagnostiquer dans votre environnement de déploiement les erreurs courantes pouvant nuire au bon fonctionnement des conteneurs Cognitive Services.

Pour obtenir le conteneur, utilisez la commande docker pull suivante :

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

Exécutez ensuite le conteneur. Remplacez {ENDPOINT_URI} par votre point de terminaison et {API_KEY} par la clé de votre ressource :

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

Le conteneur teste la connectivité réseau avec le point de terminaison de facturation.

Exemples de code de traduction de texte

Traduire du texte avec Swagger

Anglais ↔ Allemand

Accédez à la page Swagger : http://localhost:5000/swagger/index.html

  1. Sélectionnez POST /translate
  2. Sélectionnez Faites un essai.
  3. Entrez le paramètre De comme en
  4. Entrez le paramètre À comme de
  5. Entrez le paramètre api-version comme 3.0
  6. Sous texts, remplacez string par le code JSON suivant
  [
        {
            "text": "hello, how are you"
        }
  ]

Sélectionnez Exécuter, les traductions obtenues sont générées dans le corps de la réponse. Vous devez voir un texte semblable à cette réponse :

"translations": [
      {
          "text": "hallo, wie geht es dir",
          "to": "de"
      }
    ]

Traduire du texte avec Python

import requests, json

url = 'http://localhost:5000/translate?api-version=3.0&from=en&to=fr'
headers = { 'Content-Type': 'application/json' }
body = [{ 'text': 'Hello, how are you' }]

request = requests.post(url, headers=headers, json=body)
response = request.json()

print(json.dumps(
    response,
    sort_keys=True,
     indent=4,
     ensure_ascii=False,
     separators=(',', ': ')))

Traduire du texte avec une application console C#/.NET

Ouvrez Visual Studio et créez une nouvelle application de console. Modifiez le fichier *.csproj pour ajouter le nœud <LangVersion>7.1</LangVersion>, qui spécifie la version 7.1 de C#. Ajoutez le package NuGet Newtoonsoft.Json, version 11.0.2.

Dans le fichier Program.cs, remplacez tout le code existant par ce qui suit :

using Newtonsoft.Json;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace TranslateContainer
{
    class Program
    {
        const string ApiHostEndpoint = "http://localhost:5000";
        const string TranslateApi = "/translate?api-version=3.0&from=en&to=de";

        static async Task Main(string[] args)
        {
            var textToTranslate = "Sunny day in Seattle";
            var result = await TranslateTextAsync(textToTranslate);

            Console.WriteLine(result);
            Console.ReadLine();
        }

        static async Task<string> TranslateTextAsync(string textToTranslate)
        {
            var body = new object[] { new { Text = textToTranslate } };
            var requestBody = JsonConvert.SerializeObject(body);

            var client = new HttpClient();
            using (var request =
                new HttpRequestMessage
                {
                    Method = HttpMethod.Post,
                    RequestUri = new Uri($"{ApiHostEndpoint}{TranslateApi}"),
                    Content = new StringContent(requestBody, Encoding.UTF8, "application/json")
                })
            {
                // Send the request and await a response.
                var response = await client.SendAsync(request);

                return await response.Content.ReadAsStringAsync();
            }
        }
    }
}

Récapitulatif

Dans cet article, vous avez découvert les concepts et les workflows utilisés pour le téléchargement, l’installation et l’exécution d’un conteneur Translator. Vous savez à présent que :

  • Translator fournit des conteneurs Linux pour Docker.
  • Les images conteneurs sont téléchargées du registre de conteneurs, puis sont exécutées dans Docker.
  • Vous pouvez utiliser l’API REST pour appeler l’opération « translate » dans le conteneur Translator en spécifiant l’URI hôte du conteneur.

Étapes suivantes