Premiers pas avec l’API Text Analytics sous Postman

Les services cognitifs Azure permettent de bénéficier d’algorithmes déjà entrainés pour répondre à des analyses de type « cognitives », c’est-à-dire simulant le fonctionnement du cerveau humain (raisonnement) et des sens comme la vue ou l’ouïe.

Plusieurs domaines sont couverts par ces services :

  • La décision
  • Le langage
  • La parole (« speech »)
  • La vision

Dans les domaines du texte et du langage, nous bénéficions, outre la traduction, de 4 principales fonctionnalités ;

  • La détection de la langue
  • La reconnaissance d’entités nommées
  • L’extraction de phrases clés
  • L’analyse de sentiments

Mais avant de nous lancer, il nous faut créer une ressource Azure qui fournira une clé d’authentification auprès de l’API. Cette ressource est aujourd’hui (janvier 2021) commune à la plupart des APIs des services cognitifs Azure, ce qui simplifie son usage. On veillera toutefois, dans un environnement de production, à segmenter les ressources selon les différents usages. QnA Maker, Speech Services, Translator et Custom Vision ne sont actuellement disponibles que sous forme d’API individuelles.

Nous pouvons bénéficier de la tarification Standard S0, décrite sur ce lien.

Cette tarification se base sur des tranches de 1000 enregistrements de texte, avec un tarif dégressif selon des paliers d’enregistrements.

A la page de la ressource, nous trouvons deux informations qui seront ensuite indispensables : point de terminaison ou endpoint (celui-ci dépend de la région Azure préalablement sélectionnée) et deux clés d’authentification. Disposer de deux clés permet d’assurer une rotation lors du renouvellement des clés.

De nombreux langages de programmation permettent d’appeler les APIs des services cognitifs (C#, Python, node.js, Go, Ruby…) mais pour simplifier le propos et aller directement à l’essentiel, nous utiliserons ici le client Postman, téléchargeable sur ce lien, qui permettra d’interroger le point de terminaison et de bien détailler le rôle de chaque élément.

La page de documentation la plus utile sera certainement celle-ci. Nous y trouvons les différents endpoints régionaux, et dans le menu de gauche, les quatre actions possibles à partir du service cognitif Text Analytics.

Interrogation sous Postman

Le premier élément nécessaire sera l’URL de l’API, de la forme :

https://{endpoint}/text/analytics/vX.X/languages[?showStats]

Le endpoint, visible dans le portail Azure, s’écrit :

<nom-de-la -ressource>.cognitiveservices.azure.com

Nous adaptons cette URL à notre région, en retirant le paramètres ?showStats et en positionnant la boîte de dialogue de Postman sur POST. La version de l’API doit être précisée. A ce jour, nous utilisons la version 2.1 ou 3.0 voire la préversion 3.1 qui apporte de nouvelles fonctionnalités. Celles-ci sont détaillées dans cette documentation officielle.

Deux informations d’entêtes sont requises, sous forme de couple clé-valeur et nous les renseignons dans le menu Headers :

  • Le type de contenu
  • La clé d’authentification

En basculant sur le contenu brut (bouton « bulk edit » de l’interface), nous obtenons le script suivant :

Content-Type:application/json
Ocp-Apim-Subscription-Key:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Pour renseigner le corps de la requête (« Body »), il est également possible de basculer sur l’affichage « raw », pour un contenu de type JSON.

Le schéma attendu nous est à nouveau donné par la page de documentation de l’API.

Pour la détection du langage, chaque document est attendu, au sein d’une liste marquée par des crochets, sous la forme de trois éléments :

  • countryHint (facultatif)
  • id
  • text

Pour une seule phrase, le contenu minimal de ce corps est le suivant :

{documents:[{"id":0, "text": "dans quelle langue cette phrase est-elle écrite ?"}]}

La réponse obtenue, de statut 200 OK, prend alors la forme ci-dessous :

Le score donne un indicateur de confiance, entre 0 et 1, de la prévision réalisée. En pratique, un doute sera émis dès que le score sera inférieur à 1.

L’information countryHint peut être renseignée par un code sur deux lettres représentant le pays d’où est issu le texte, ce qui permet de retirer d’éventuelles ambiguités lorsqu’un même mot est utilisé dans plusieurs langues. Le champ peut être soit omis, soit renseigné comme une chaîne vide countryHint = “”.

Lorsqu’il n’est pas possible d’identifier un langage, la réponse otenue sera le mot « (Unknown) ».

Le schéma ci-dessous résume les principales syntaxes d’interrogation de l’API Text Analytics.

L’API Translator

Dans la foulée de la reconnaissance de la langue, il est logique de rechercher à traduire le texte. Nous appelons ici une autre API : Translator, réalisant ci-dessous une traduction en français.

https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=fr

Le body de la requête s’écrit de la sorte :

[{"Text":"Azure Cognitive Services are cloud-based services with REST APIs and client library SDKs available
to help you build cognitive intelligence into your applications.
You can add cognitive features to your applications without having artificial intelligence (AI) or data science skills."}]

Nous obtenons la sortie suivante.

Si besoin, la langue d’origine peut être précisée et ce n’est pas le mécanisme d’auto-détection qui est mis en œuvre.

https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr

La documentation détaillée de l’API est disponible sur ce GitHub et un extrait est illustré ci-dessous.

Un niveau de tarification supérieur à S0 est nécessaire, sinon le message suivant apparaît :

The Translate Operation under Translator Text API v3.0 is not supported with the current subscription key
and pricing tier CognitiveServices.S0.

Les méthodes l’API Text Analytics

Voyons maintenant les trois autres méthodes disponibles avec l’API Text Analytics.

Celles-ci ne seront pas toujours disponibles en français, ou dans d’autres langues que l’anglais. La vérification peut être faite, en fonction de la version de l’API, sur cette page.

L’analyse de sentiments évalue un texte dans sa totalité en se basant sur le poids des mots utilisés, pour attribuer trois scores : positif, neutre, négatif. Un sentiment global est donné sous forme de texte : positive, mixed, negative ou neutral si aucun des trois cas précédents n’est vérifié.

https:// <nom-de-la-ressouce>.cognitiveservices.azure.com/text/analytics/v3.1-preview.3/sentiment

Pour obtenir l’exploration des opinions, uniquement en anglais à ce jour, nous ajoutons à la fin de l’URL : ?opinionMining=true

{documents:[{"language": "en", "id":0, "text": "Very welcome and advice from the guests. Very clean accommodation. We recommend it!"}]}

Nous obtenons alors, lorsqu’une relation de type opinion est détectée, un groupe d’informations supplémentaires intitulé « opinions », disposant de deux scores, positif et négatif.

L’extraction de phrases clés permet d’identifier des éléments (mots ou groupes de mots) les plus importants au sein d’un texte (phrase ou ensemble de phrases). On pourrait voir cela comme une extension d’un preprocessing visant à retirer les mots outils (« stop words »).

https://< nom-de-la-ressouce>.cognitiveservices.azure.com/text/analytics/v3.0/keyPhrases

Nous obtenons le résultat suivant avec la première phrase du roman de Marcel Proust, A la Recherche du Temps Perdu.

La reconnaissance d’entités nommées se fait avec la syntaxe :

recognition/general

Nous retrouvons certains éléments ressortant dans les phrases clés, pour lesquels une catégorie et sous-catégorie sont données, associées à un score de confiance. A ce jour (février 2021), c’est la version 2.1 de l’API qui est utilisée en langue française, même si la version 3.0 est indiquée dans l’URL.

La liaison d’entités (non disponible pour l’instant en français) ajoute une information supplémentaire à la reconnaissance générale d’entité en spécifiant l’URL d’une page Wikipedia dédiée à cette entité.

https://<nom-de-la -ressource>.cognitiveservices.azure.com/text/analytics/v3.0/entities/linking

Les Informations d’identification personnelle (PII) sont des patterns correspondant à différents éléments : numéro de téléphone, adresse e-mail, adresse postale, numéro de passeport.

https://<nom-de-la -ressource>.cognitiveservices.azure.com/text/analytics/ v3.1-preview.3/entities/recognition/pii

Nous remarquons que la sortie donne un élément redactedText qui remplace les éléments reconnus comme informations personnelles par des étoiles (*).

Un domaine (optionnel) peut être précisé pour obtenir les informations (personnelles) médicales mais il n’existe à ce jour pas de documentation explicitant les éléments pouvant être identifiés.

https://<nom-de-la -ressource>.cognitiveservices.azure.com/text/analytics/v3.1-preview.3/entities/recognition/pii?domain=phi

Que vaut la détection d’anomalies dans Power BI ?

Pour des données établissant une série temporelle (mesure numérique à intervalles de temps régulier), la première étape de mise en qualité des données sera bien souvent de corriger les données dites aberrantes, c’est-à-dire trop éloignées de la réalité.

Rappelons les différents cas pouvant amener à ce type de données :
– erreur de mesure ou de saisie (maintenant plutôt lié à une erreur “informatique”)
– dérive réelle et ponctuelle (souvent non souhaitée, correspondant à un défaut de qualité)
– hasard (événement assez peu probable mais pouvant néanmoins se produire exceptionnellement!)

Avec la version de novembre 2020 de Power BI Desktop, nous découvrons une nouvelle fonctionnalité en préversion (donc à activer depuis le menu Options) qui ajoute une entrée dans le menu Analytique des graphiques en courbe (“line chart“).

Tout d’abord, regardons les limites d’utilisation précisées à cette page. Si 12 points sont le minimum requis (ou 4 patterns saisonniers), il sera beaucoup plus pertinent d’en avoir en plus grand nombre ! Ensuite, de nombreuses fonctionnalités ne sont pas (encore ?) compatibles avec la détection d’anomalies : légende, axe secondaire, prévision (forecast), live connection, drill down

Fonctionnement théorique

Le papier de recherche qui décrit l’algorithme utilisé, nommé unsupervised SR-CNN, est disponible ici. Nous allons essayer de le vulgariser sans trop d’approximations.

Cet algorithme d’apprentissage automatique fait partie de la catégorie des méthodes non-supervisées, c’est-à-dire qu’il n’est pas nécessaire de disposer a priori d’un échantillon de données d’apprentissage où les anomalies seraient déjà identifiées (approche supervisée).

Les deux premières lettres du nom de cette approche correspondent à la méthode dite Spectral Residual, basée sur des transformées de Fourier, qui met en valeur des éléments “saillants” (salient) de la série temporelle.

Issus du domaine du Deep Learning, les réseaux de neurones à convolution (CNN) ont émergé dans le domaine du traitement d’images en deux dimensions. Pour autant, il est tout-à-fait possible de les utiliser dans le cadre d’une série temporelle à une dimension. Au lieu d’analyser des fragments d’images, la série des données transformées va être reformulée comme plusieurs successions de valeurs.

Ainsi, la série {10, 20, 30, 40, 50, 60} pourra donner des séries comme {10, 20, 30}, {20, 30, 40} ou encore {40, 50, 60} (voir ce très bon article pour aller plus loin dans le code).

Le rôle de la couche de convolution est d’extraire les features (caractéristiques) de la série temporelle. Ce sont elles qui permettront ensuite de décider si une valeur est ou non une anomalie.

D’un point de vue de l’architecture du réseau, la couche de convolution à une dimension est suivi d’une couche “fully connected” qui fait le lien entre le résultat de la convolution et le label de sortie (anomalie ou non).

Allons maintenant à la recherche d’un jeu de données pour expérimenter cette fonctionnalité !

Test sur un jeu de données

Il existe des jeux de données de référence pour évaluer la performance de la détection d’anomalies, et plus spécifiquement dans le cadre des séries temporelles. Vous en trouverez par exemple sur cette page.

Nous travaillerons ici avec un jeu de données de trafic réseau.

Ce dataset contient environ 4,5 millions de lignes.

La détection d’anomalies se déclenche dans le menu Analytique du visuel.

Un seul paramètre est disponible pour régler le niveau de détection, entre 0 et 100% : sensitivity.

Plus la valeur est élevée, plus “l’intervalle de confiance” en dehors duquel sera détectée une anomalie est fin. Autrement dit, plus la valeur approche des 100%, plus vous apercevrez de points mis en évidence. Difficile de dire sur quoi joue ce paramètre d’un point de vue mathématique, il n’est pas évoqué dans le papier de recherche cité précédemment.

En cliquant sur un point, s’ouvre un nouveau volet latéral donnant les valeurs de la plage attendue, reprises également dans l’infobulle.

En plaçant d’autres champs de la table dans la case “explain by“, on peut espérer mettre une évidence un facteur explicatif de cette anomalie.

Attention, il n’est pas envisageable de “zoomer” sur un portion du graphique contenant une anomalie car cela modifiera la plage de données servant à évaluer l’algorithme et fera donc apparaître ou disparaître des points identifiés comme aberrants !

Zoom sur une journée contenant initialement une détection d’anomalies

On pourra plutôt profiter de l’affichage du visuel en tant que table de données qui dispose d’une colonne “anomaly” valant 0 ou 1. On s’aperçoit ici que plusieurs points consécutifs sont identifiés comme des anomalies, ce qui était difficilement identifiable sur le graphique.

En conclusion

Malheureusement, les informations obtenues au travers de ce visuel ne peuvent pas réellement être exploitées : pas d’indicateur créé dans la table, pas d’export au delà de 30000 points (soit un peu plus de 8h pour des données à la seconde), un modèle perpétuellement recalculé et ne pouvant être arrêté sur une période. Alors, que faire lorsque des anomalies apparaissent ? Rien hormis prévenir le propriétaire des données…

Comme pour les autres services touchant (de loin) à l’IA sous Power BI, je suis sceptique quant au moment où cette fonctionnalité est mise en œuvre. La détection d’anomalies est une étape de préparation de la donnée et hormis à effectuer un reporting sur ces anomalies elles-mêmes, nous sommes en droit d’attendre qu’elles soient déjà retirées des données avant exposition. Il serait donc beaucoup plus opportun d’utiliser le service cognitif Azure dans un dataflow (Premium ou maintenant en licence Premium Per User) afin de mettre la donnée en qualité lors de la constitution de donnée. Pour une détection sur un flux de streaming, on se tournera avec intérêt vers les possibilités offertes par Azure Databricks, comme exposé dans ce tutoriel.

A l’inverse, les algorithmes prédictifs qui ne peuvent être utilisés que dans les dataflows seraient beaucoup plus à leur place dans un visuel qui permettrait de tester différents scénarios et d’observer les prévisions associées.

En résumé, les ingrédients de la recette sont les bons, encore faut-il les ajouter dans l’ordre pour obtenir un plat satisfaisant !

L’algorithme choisi (SR-CNN) ne doit pour autant pas être remis en cause car il semble aujourd’hui représenter l’état de l’art de la détection d’anomalies;

Vos remarques sur cet outil peuvent être déposées sur cette page communautaire.