L'API Cloud Natural Language vous permet d'extraire des entités à partir de texte, d'effectuer des analyses du sentiment et de la syntaxe et de classer du texte en catégories.
Dans cet atelier, vous allez découvrir comment utiliser l'API Natural Language pour analyser les entités, les sentiments et la syntaxe d'un texte.
Points abordés
- Créer une requête pour l'API Natural Language et appeler l'API avec curl
- Extraire les entités et exécuter l'analyse des sentiments sur une chaîne de texte avec l'API Natural Language
- Effectuer l'analyse linguistique d'un texte avec l'API Natural Language
- Créer une requête pour l'API Natural Language dans une autre langue
Vous avoir besoin
Comment allez-vous utiliser ce tutoriel ?
Quel est votre niveau d'expérience avec Google Cloud Platform ?
Configuration de l'environnement au rythme de chacun
Si vous n'avez pas encore de compte Google (Gmail ou Google Apps), vous devez en créer un. Connectez-vous à la console Google Cloud Platform (console.cloud.google.com) et créez un projet:
Mémorisez l'ID du projet. Il s'agit d'un nom unique permettant de différencier chaque projet Google Cloud (le nom ci-dessus est déjà pris ; vous devez en trouver un autre). Il sera désigné par le nom PROJECT_ID tout au long de cet atelier de programmation.
Vous devez ensuite activer la facturation dans Cloud Console afin d'utiliser les ressources Google Cloud.
Suivre cet atelier de programmation ne devrait pas vous coûter plus d'un euro. Cependant, cela peut s'avérer plus coûteux si vous décidez d'utiliser davantage de ressources ou si vous n'interrompez pas les ressources (voir la section "Effectuer un nettoyage" à la fin du présent document).
Les nouveaux utilisateurs de Google Cloud Platform peuvent bénéficier d'un essai offert de 300$.
Cliquez sur l'icône de menu en haut à gauche de l'écran.
Sélectionnez API et services dans la liste déroulante, puis cliquez sur "Tableau de bord".
Cliquez sur Enable APIs and services (Activer les API et les services).
Ensuite, recherchez "language" dans le champ de recherche. Cliquez sur Google Cloud Natural Language API (API Google Cloud Natural Language) :
Cliquez sur Enable (Activer) pour mettre en route l'API Cloud Natural Language :
Patientez quelques secondes. Vous verrez ce message s'afficher une fois l'option activée:
Google Cloud Shell est un environnement de ligne de commande fonctionnant dans le cloud. Cette machine virtuelle basée sur Debian contient tous les outils de développement dont vous aurez besoin (gcloud, bq, git, etc.). Elle offre un répertoire de base persistant de 5 Go. Nous utiliserons Cloud Shell pour créer notre requête auprès de l'API Natural Language.
Pour commencer à utiliser Cloud Shell, cliquez sur l'icône 
Activer Google Cloud Shell en haut à droite de la barre d'en-tête.
Une session Cloud Shell s'ouvre dans un nouveau cadre en bas de la console et affiche une invite de ligne de commande. Attendez que l'invite "user@project:~$" s'affiche.
Puisque nous utiliserons curl pour envoyer une requête à l'API Natural Language, nous devrons générer une clé API pour transmettre l'URL de la requête. Pour créer une clé API, accédez à la section "Identifiants" de la page "API et services" de Cloud Console:
Dans le menu déroulant, sélectionnez API key (Clé API) :
Ensuite, copiez la clé que vous venez de générer. Vous en aurez besoin plus tard dans l'atelier.
Vous disposez désormais d'une clé API. Enregistrez sa valeur dans une variable d'environnement afin d'éviter de l'insérer à chaque requête. Vous pouvez le faire dans Cloud Shell. Veillez à remplacer <your_api_key> par la clé que vous venez de copier.
export API_KEY=<YOUR_API_KEY>La première méthode de l'API Natural Language que nous allons utiliser est analyzeEntities. Grâce à cette méthode, l'API peut extraire des entités (telles que des personnes, des lieux et des événements) d'un texte. Pour tester l'analyse des entités de l'API, nous utiliserons la phrase suivante :
Joanne Rowling, qui écrit sous le nom de stylo J. K. Rowling et Robert Galbraith sont des scénaristes et scénaristes britanniques qui ont rédigé la série fantasy Harry Potter.
Nous allons créer notre requête auprès de l'API Natural Language dans un fichier request.json. Dans votre environnement Cloud Shell, créez le fichier request.json avec le code ci-dessous. Vous pouvez créer le fichier à l'aide de l'un de vos éditeurs de ligne de commande préférés (nano, vim, emacs) ou à l'aide de l'éditeur Orion intégré dans Cloud Shell:
json.json
{
"document":{
"type":"PLAIN_TEXT",
"content":"Joanne Rowling, who writes under the pen names J. K. Rowling and Robert Galbraith, is a British novelist and screenwriter who wrote the Harry Potter fantasy series."
},
"encodingType":"UTF8"
}Dans la requête, nous informons l'API Natural Language du texte envoyé. Les valeurs de type acceptées sont PLAIN_TEXT et HTML. Vous indiquez dans "content" la chaîne de texte à envoyer à l'API Natural Language pour analyse. L'API Natural Language permet également l'envoi de fichiers stockés dans Cloud Storage pour le traitement de texte. Si vous voulez envoyer un fichier à partir de Cloud Storage, vous devez remplacer content par gcsContentUri et lui attribuer une valeur de l'URI de notre fichier texte dans Cloud Storage. encodingType indique à l'API le type d'encodage de texte à utiliser lors du traitement de notre texte. L'API l'utilisera pour calculer l'emplacement d'entités spécifiques dans le texte.
Vous pouvez à présent transmettre le corps de votre requête, ainsi que la variable d'environnement de clé API que vous avez enregistrée précédemment, à l'API Natural Language à l'aide de la commande curl suivante (dans une seule ligne de commande):
curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
-s -X POST -H "Content-Type: application/json" --data-binary @request.jsonLe début de votre réponse doit se présenter comme suit:
{
"entities": [
{
"name": "Robert Galbraith",
"type": "PERSON",
"metadata": {
"mid": "/m/042xh",
"wikipedia_url": "https://en.wikipedia.org/wiki/J._K._Rowling"
},
"salience": 0.7980405,
"mentions": [
{
"text": {
"content": "Joanne Rowling",
"beginOffset": 0
},
"type": "PROPER"
},
{
"text": {
"content": "Rowling",
"beginOffset": 53
},
"type": "PROPER"
},
{
"text": {
"content": "novelist",
"beginOffset": 96
},
"type": "COMMON"
},
{
"text": {
"content": "Robert Galbraith",
"beginOffset": 65
},
"type": "PROPER"
}
]
},
...
]
}Pour chaque entité de la réponse, nous obtenons l'entité type, l'URL Wikipédia associée (s'il en existe une) et la liste salience, ainsi que les index des endroits où elle apparaît dans le texte. (la saillance est un chiffre compris dans la plage [0,1] et se rapportant à la centralité de l'entité par rapport au texte dans son ensemble) ; L'API Natural Language est également en mesure de reconnaître une même entité évoquée sous différentes formes. Examinez la liste mentions dans la réponse: l'API peut dire que Joanne Rowling", Ligne & Rowling"novelist" et "Robert Galbriath" ont tous le même sens.
Outre l'extraction d'entités, l'API Natural Language permet d'effectuer une analyse des sentiments dans une chaîne de texte. La requête JSON comprend les mêmes paramètres que la requête ci-dessus. Cependant, cette fois, nous allons modifier le texte pour y inclure un sentiment plus fort. Remplacez votre fichier request.json par le texte ci-dessous et n'hésitez pas à remplacer le content ci-dessous par votre propre texte:
json.json
{
"document":{
"type":"PLAIN_TEXT",
"content":"Harry Potter is the best book. I think everyone should read it."
},
"encodingType": "UTF8"
}Ensuite, nous enverrons la requête au point de terminaison analyzeSentiment de l'API:
curl "https://language.googleapis.com/v1/documents:analyzeSentiment?key=${API_KEY}" \
-s -X POST -H "Content-Type: application/json" --data-binary @request.json
La réponse doit se présenter comme suit :
{
"documentSentiment": {
"magnitude": 0.8,
"score": 0.4
},
"language": "en",
"sentences": [
{
"text": {
"content": "Harry Potter is the best book.",
"beginOffset": 0
},
"sentiment": {
"magnitude": 0.7,
"score": 0.7
}
},
{
"text": {
"content": "I think everyone should read it.",
"beginOffset": 31
},
"sentiment": {
"magnitude": 0.1,
"score": 0.1
}
}
]
}Notez que nous obtenons deux types de valeurs de sentiment: le sentiment dans son ensemble dans son ensemble et le sentiment ventilé par phrase. La méthode "Sentiment" renvoie deux valeurs: score et magnitude. score est un nombre compris entre -1,0 et 1,0 indiquant à quel point l'instruction est positive ou négative. magnitude est un nombre compris entre 0 et l'infini, représentant la pondération des sentiments exprimées dans l'instruction, qu'elle soit positive ou négative. Les longues chaînes de texte exprimant des sentiments intenses ont des valeurs de magnitude plus élevées. Le score de la première phrase est positif (0,7), tandis que le score de la deuxième phrase est neutre (0,1).
En plus de fournir des détails sur les sentiments dans l'ensemble du document texte que nous envoyons à l'API NL, il peut également répartir les sentiments par entités dans notre texte. Prenons l'exemple suivant:
I liked the sushi but the service was terrible.
Dans ce cas, obtenir un score de sentiment pour l'ensemble de la phrase, comme nous l'avons fait ci-dessus, ne sera peut-être pas très utile. S'il s'agit d'un avis sur un restaurant et que des centaines d'avis ont été publiés pour le même restaurant, nous aimerions savoir exactement ce qui a aimé et n'a pas aimé les internautes dans ses avis. Heureusement, l'API NL dispose d'une méthode appelée analyzeEntitySentiment, qui permet d'obtenir le sentiment de chaque entité dans notre texte. Mettez à jour votre fichier request.json avec la phrase ci-dessus pour essayer:
json.json
{
"document":{
"type":"PLAIN_TEXT",
"content":"I liked the sushi but the service was terrible."
},
"encodingType": "UTF8"
}Appelez ensuite le point de terminaison analyzeEntitySentiment à l'aide de la commande curl suivante:
curl "https://language.googleapis.com/v1/documents:analyzeEntitySentiment?key=${API_KEY}" \
-s -X POST -H "Content-Type: application/json" --data-binary @request.json
Dans la réponse, nous obtenons deux objets d'entité: un pour "sushi" et un pour le service. Voici la réponse JSON complète:
{
"entities": [
{
"name": "sushi",
"type": "CONSUMER_GOOD",
"metadata": {},
"salience": 0.52716845,
"mentions": [
{
"text": {
"content": "sushi",
"beginOffset": 12
},
"type": "COMMON",
"sentiment": {
"magnitude": 0.9,
"score": 0.9
}
}
],
"sentiment": {
"magnitude": 0.9,
"score": 0.9
}
},
{
"name": "service",
"type": "OTHER",
"metadata": {},
"salience": 0.47283158,
"mentions": [
{
"text": {
"content": "service",
"beginOffset": 26
},
"type": "COMMON",
"sentiment": {
"magnitude": 0.9,
"score": -0.9
}
}
],
"sentiment": {
"magnitude": 0.9,
"score": -0.9
}
}
],
"language": "en"
}
Nous constatons que le score de "sushi" était de 0,9, tandis que l'efficacité du service était de -0,9. Parfait ! Vous remarquerez également que deux objets de sentiment ont été attribués à chaque entité. Si l'un de ces deux termes avait été mentionné à plus d'une reprise, l'API aurait renvoyé un score de sentiment et de magnitude distinct pour chaque occurrence, ainsi qu'un sentiment global pour l'entité.
La troisième méthode de l'API Natural Language : l'annotation syntaxique nous permet d'examiner plus en détail les détails linguistiques de nos textes. analyzeSyntax est une méthode qui fournit un ensemble complet de détails sur les éléments sémantiques et syntaxiques du texte. Pour chaque mot du texte, l'API nous indique la partie du mot (nom, verbe, adjectif, etc.) et sa relation avec d'autres mots dans la phrase (est-ce que le verbe est-il racine ? d'un modificateur ?).
Faisons un essai avec une simple phrase. Notre requête JSON est semblable à celles ci-dessus, avec l'ajout d'une clé de fonctionnalité. qui indiquera à l'API que nous souhaitons effectuer une annotation syntaxique. Remplacez votre fichier request.json par le code suivant:
json.json
{
"document":{
"type":"PLAIN_TEXT",
"content": "Hermione often uses her quick wit, deft recall, and encyclopaedic knowledge to help Harry and Ron."
},
"encodingType": "UTF8"
}Appelez ensuite la méthode analyzeSyntax de l'API:
curl "https://language.googleapis.com/v1/documents:analyzeSyntax?key=${API_KEY}" \
-s -X POST -H "Content-Type: application/json" --data-binary @request.jsonLa réponse doit renvoyer un objet semblable à celui présenté ci-dessous pour chaque jeton de la phrase. Évaluons ici la réponse du mot "use"
{
"text": {
"content": "uses",
"beginOffset": 15
},
"partOfSpeech": {
"tag": "VERB",
"aspect": "ASPECT_UNKNOWN",
"case": "CASE_UNKNOWN",
"form": "FORM_UNKNOWN",
"gender": "GENDER_UNKNOWN",
"mood": "INDICATIVE",
"number": "SINGULAR",
"person": "THIRD",
"proper": "PROPER_UNKNOWN",
"reciprocity": "RECIPROCITY_UNKNOWN",
"tense": "PRESENT",
"voice": "VOICE_UNKNOWN"
},
"dependencyEdge": {
"headTokenIndex": 2,
"label": "ROOT"
},
"lemma": "use"
}Analysons la réponse obtenue. partOfSpeech nous fournit des informations linguistiques sur chaque mot (nombre d'entre eux inconnus, car ils ne s'appliquent pas à l'anglais ou à ce mot spécifique). tag fournit la partie du mot de ce mot, dans ce cas un verbe. Nous obtenons également des détails sur la modalité ainsi que sur le singulier ou le pluriel. lemma est la forme canonique du mot (pour "use", "it" et "use"). Par exemple, les mots run, runs, run et running ont tous un lemma run. La valeur du lemme est utile pour comptabiliser au fur et à mesure les occurrences d'un mot dans une longue chaîne de texte.
dependencyEdge inclut des données que vous pouvez utiliser pour créer une arborescence d'analyse de la dépendance du texte. Ce schéma schématise les relations entre les mots d'une phrase. L'arbre syntaxique de dépendance de la phrase ci-dessus ressemblerait à ceci :
L'élément headTokenIndex de notre réponse ci-dessus correspond à l'index du jeton dont l'arc pointe vers &use. Nous considérons chaque jeton de la phrase comme un mot d'un tableau, et la valeur headTokenIndex de 2 pour "utiles" fait référence au mot "souvent", souvent relié à l'arbre.
L'API Natural Language est également compatible avec d'autres langues que la version anglaise (voir la liste complète). Essayez d'exécuter la requête d'entité suivante en japonais:
json.json
{
"document":{
"type":"PLAIN_TEXT",
"content":"日本のグーグルのオフィスは、東京の六本木ヒルズにあります"
},
"encodingType": "UTF8"
}Notez que nous n'avons pas indiqué à l'API la langue de notre texte, mais elle peut la détecter automatiquement. Ensuite, nous l'enverrons au point de terminaison analyzeEntities:
curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
-s -X POST -H "Content-Type: application/json" --data-binary @request.jsonEt voici les deux premières entités de notre réponse:
{
"entities": [
{
"name": "日本",
"type": "LOCATION",
"metadata": {
"mid": "/m/03_3d",
"wikipedia_url": "https://en.wikipedia.org/wiki/Japan"
},
"salience": 0.23854347,
"mentions": [
{
"text": {
"content": "日本",
"beginOffset": 0
},
"type": "PROPER"
}
]
},
{
"name": "グーグル",
"type": "ORGANIZATION",
"metadata": {
"mid": "/m/045c7b",
"wikipedia_url": "https://en.wikipedia.org/wiki/Google"
},
"salience": 0.21155767,
"mentions": [
{
"text": {
"content": "グーグル",
"beginOffset": 9
},
"type": "PROPER"
}
]
},
...
]
"language": "ja"
}L'API extrait le Japon en tant qu'emplacement et Google en tant qu'organisation, ainsi que les pages Wikipédia pour chacun.
Vous avez appris à effectuer une analyse de texte avec l'API Cloud Natural Language en extrayant des entités, en analysant des sentiments et en réalisant des annotations syntaxiques.
Points abordés
- Créer une requête pour l'API Natural Language et appeler cette dernière avec curl
- extrait les entités et exécuté l'analyse des sentiments sur une chaîne de texte avec l'API Natural Language ;
- effectué des analyses linguistiques sur des chaînes de texte pour créer des arbres syntaxiques de dépendance ;
- créé une requête pour l'API Natural Language en japonais.
Étapes suivantes
- Consulter les tutoriels de l'API Natural Language dans la documentation.
- Essayez l'API Vision et l'API Speech !