Microsoft Cognitive Services Translator V3 – Exploration des APIs – Translate (Part I)

Introduction

Dans cette série, nous allons approcher les APIs proposé par Microsoft Cognitive Services – Translator.

Ces APIs sont plutôt pratique si vous avez a jouer avec des langues différentes à analyser en même temps, car elles permettent de pouvoir faire des actions que les autres APIs concurrente ne permettent pas (Ex.: Google, ou autres). Pour clarifier, je ne travaille pas exclusivement avec les produits Microsoft et je n’ai pas aucun parti pris. C’est seulement qu’après une étude au niveau des coûts et des services offert. J’ai trouvé que celle de Microsoft était plus ouverte sur le format de configuration. On peut envoyer environ n’importe quoi et recevoir la traduction adéquate avec certains extras.

Le coût: 2,000,000 de caractères pour la modique somme de 0$. Pour plus d’informations, si vous voulez traiter plus de caractères, veuillez visiter le site officiel avec les prix du jour. À priori, au moment de l’écriture de cet article, le prix est d’environs 12$ par million de caractères supplémentaire.

Pré-requis

Les pré-requis, sont comme vous pouvez vous l’imaginer, les suivants:

• Souscription à Azure (Obligatoire, mais c’est gratuit!)
• .Net Core 2.1 (Pour cet article), mais a priori n’importe quoi fonctionnera
• Visual Studio normal/code peuvent être utilisé

Notez que les APIs sont accessible pour tous les languages et non seulement C#/.Net. Par vous donner une idée, tous les exemples sont faites à l’aide CURL.  Si l’on regarde le menu à gauche sur le site, vous trouverez toutes les références pour faire les appels API avec NodeJS, Ruby, etc..

API Translator/Translate (V3)

Commençons par les APIs de Translator Translate V3. La V2 fournissait d’autres API, mais ici nous allons nous attarder sur la V3.

Translator, pour ceux qui ne le savent pas encore, est le service de traduction de Microsoft (Bing translate? où si vous voulez tester, l’application Windows Store “Translator”). Cette API comporte plusieurs parties, dont:

• Languages: Vous offre la liste à jour des langages possible de traduire. C’est-à-dire, si je veux traduire l’anglais, quels sont les langues possible dans lesquels je peux traduire. Cet API permet de donner les possibilités de traduction pour toutes les autres API qui suivent. Donc, si vous faite un appel à cette API, vous pouvez garder en cache un bon moment, car ça ne changera pas souvent. Tout récemment Microsoft à ajouter de nouvelles langues.
• Translate: L’API le plus intéressant, à mon avis. Traduit le texte d’une langue donnée dans une autre langue. Le type de langue d’input n’est pas nécessaire, mais aide probablement à la rapidité et à l’exactitude du texte donnée. C’est sur ce point que nous allons nous attarder dans cet article.
• Transliterate: Très utile pour les langues tel que le Japonais. Cette API vous permet d’avoir une translittération du texte ainsi que son script (Latin, Japonais, …). Par exemple こんいちわ devient konnichiwa. Ça permet de faire des analyses plus simple dans un sens. Car dans certaines langues les espaces ne sont pas nécessaire et ça crée certains soucis lorsque l’ont veut filtrer ou autre.
• Detect: Identifie la langue utilisé dans le texte. Cet API, par exemple, peut être très utile si vous effectuer un chatbot et que la première intérraction vous ne trouvez pas de réponse à la question. Dans ce cas, vous vous assurez que la langue utilisé pour l’analyse était bien la bonne et si ce n’est pas le cas, renvoyer la question dans la bonne langue a votre analyseur et ensuite mettre à jour la session utilisateur afin de l’accomoder. Ceci n’est qu’une idée de ce que l’on pourrait faire avec cet API.
• BreakSentence: Comme son nom l’indique, cette API brisera vos phrases en morceaux. En fait, vous n’aurez pas les phrases renvoyé par l’API, mais seulement les longueurs de phrases et si demandé lors de la requête la langue ainsi que le score entre 0 et 1 (voir le site MSDN). Ce sera à vous de vous accomoder par la suite. À priori, je n’y vois aucuns problème, tout spécialement avec les nouveaux span en C#.
• Dictionary Lookup: Cet API vous donnera des alternative à ce qui a été traduit. Ceci peut être utile, si vous voulez que votre utilisateur corrige sa phrase avec des suggestions. Cet API vous donnera aussi le tagging des mots (Verbe, Adverbe, etc.). Sur ce point, je vous conseille fortement d’aller voir l’article MSDN où un exemple complet s’y trouve.
• Dictionary Example: Dans le même ordre d’idée que le point précédent. Vraiment spécialisé pour des cas très précis. À priori, je ne crois pas que vous utiliserez à l’exception de cas très spéciaux.

La section translate

Nous trouvons tous les paramètres possible pour les appels sur les APIs et leurs limites Commençons par discuter des limites:

• On peut transmettre 25 sections de document à traduire à la fois;
• Chaque section peut contenir au maximum 5,000 caractères;
• Accepte le HTML et le texte. Concernant la limite de caractères, je ne sais pas si le HTML en lui même est compté.
• Certaines langues ne se traduisent pas directement dans d’autres (et là ça dépend, mais pour anglais-français, aucuns problème);

Ces limites semble petite ou grande, dépendant de ce que vous voulez traduire. Personellement, je vous conseille d’optimiser vos appels pour faire le moins d’appels possible au service. D’après des commentaires vu par le passé, il y aurait aussi une limite sur le nombre d’appel répétés dans un cours délais. Du coup, si vous prévoyer traduire une page de texte, je vous recommenderais d’éviter de traduire:

• Des phrases en doublons;
• De petites phrases seules; Le mieux est de joindre plusieurs parties de phrases ensemble;

À priori, je vous dirais de:

• Créer une cache (Mémoire, Redis, autre) pour éviter de retraduire ce qui est déjà traduit.
• Utiliser le positionnement des mots si vous désirez éventuellement faire du machine learning et de traduire à un certain moment avec vos propre algorithmes.
• Joindre les phrases dans une même section;
• Tenter d’arriver le plus près de toutes les limites afin de faire le plus petit nombre de requête sur les serveurs de Microsoft Cognitive Service.

Let’s go! Coding time! ☆ou presque

Avant de commencer à coder, si vous n’avez pas encore créer dans votre portail Azure un service Cognitive, veuillez procéder.

1. Créer une nouvelle resource et sélectionner “Cognitive Services”
2. Remplir tous les points et ça devrait être ok.
3. Et voilà, vous avez obtenus vos clées (Primaire et secondaire).

Ces clées peuvent fonctionner par rotation et vous pouvez mettre à jour la clée précédente pour obtenir une nouvelle clée. Ce système vous permettra d’être sécure et d’éviter que les gens qui auraient eu connaissance d’une de vos clés utilise votre compte “Cognitive”.

Créons notre projet

Visual Studio 2017 (Dernière update si possible avec Core 2.1):

1. Fichier
2. Nouveau projet
3. Asp .Net Core Web Application
   • Donnez un nom et choisissez votre emplacement favoris (ex.: c:\temp\MyProject
4. MVC/Web Application (Pour cette demo)
5. Mettre les packages NuGet à jour (Click droit sur la solution et ensuite gérer les packets pour la solution)
6. Ajouter un nouveau package CognitiveServices.Translator.Client

Ce package vous évite de faire tous les appels à la mitaine. Grosso modo c’est un Proxy.

7. Compiler
8. Executez l’application histoire de valider que ça démarre avant de faire les changements.

Configuration de Cognitive Services (Avec NuGet)

Dans votre fichier AppSettings.json ou AppSettings.Development.json, ajouter la section suivante:

{
  // Some logging stuff
  // New things
  "CognitiveServices": {
    "Name": "Doc_Transl_demo (This is for personal reference only)",
    "SubscriptionKey": "[Insert Key here]"
  }
}

Cette configuration sera automatiquement utilisée par la librairie importée au point précédent.

Injection des dépendences (Dependency Injection ou encore DI)

Comme vous vous l’imaginiez, il faudra aussi injecter les dépendances du packet importé. Dans votre fichier Startup.cs, ajoutez ce qui suit:

// startup.cs
public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)
{
    // some code here...
    // ...

    // Add the cognitive service (in case you want to use DI using the appsettings.json)
    services.AddCognitiveServicesTranslator(Configuration);
}

Ceci vous permettra de recevoir une injection avec l’interface ITranslateClient. Cette interface est injecté pour le “Scope” courant. Donc pour la durée de la requête, ce sera le même objet qui sera utilisé. Si jamais ça pose problème, merci d’ouvrir un bug dans Github.

Exemple d’injection dans un contrôleur (TranslateController.cs):

[Route("api/[controller]")]
public class TranslateController : Controller
{
    private readonly ITranslateClient _translateClient;

    public TranslateController(ITranslateClient translateClient)
    {
        _translateClient = translateClient;
    }

    [HttpPut("withDI")]
    public async Task<IList<ResponseBody>> WithDependencyInjection([FromBody] TranslateRequest translate)
    {
        return await _translateClient.TranslateAsync(translate.RequestContents, translate.Options);
    }

    [HttpPut()]
    public async Task<IList<ResponseBody>> Index([FromBody] TranslateRequest translate)
    {
        // Créer un appel avec une configuration custom à chaque appel.
        var translateClient = new TranslateClient(translate.CognitiveServicesConfig);

        return await translateClient.TranslateAsync(translate.RequestContents, translate.Options);
    }
}

Utilisation de l’API

Maintenant qu’on est capable de faire le minimum. C’est le temps de faire un appel complet à l’API en utilisant certaines options. En fait pour ça je vous dirais de jouer avec l’exemple fourni avec la librairie. Vous y trouverez toutes les options. L’exemple live est disponible à partir d’un site Azure en mode demo (Todo, je dois republier avec le nouveau code).

Important: Je vous assure qu’aucunes capture des clés d’APIs est fait sur le site demo.

Point intéressant de l’API

• Possibilité de connaître la position de ce qui est traduit par rapport à l’original. C’est-à-dire que vous pouvez comprendre comment la traduction s’est effectuée.
• Performances
• Qualité
• Langues disponibles (dont le Japonais)
• Possibilité de retirer les “méchant” mots du vocabulaire et de les remplacer par des ***
• Peut traduire le texte qui contient du HTML

Utilisation de l’API sans NuGet

Dans ce cas, vous aurez à appeler les API manuellement. Le packet Nuget vous permet tout simplement d’éviter à avoir a ré-écrire les classes de bases et marche comme un véritable proxy. Dans la documentation Microsoft, les exemples sont fournis avec CURL, mais le transfert vers C# est simple.