Analyse des données à la demande à l'aide de l'API Analyze
Utilisez l'API Analyze pour traiter des documents texte via le pipeline d'enrichissement du service Discovery sans stocker de données provenant des documents source.
L'API Analyze est prise en charge par les déploiements de plan Enterprise et les déploiements installés uniquement.
Cette approche est idéale à des fins d'automatisation métier. Par exemple, si vous souhaitez classifier des e-mails, vous pouvez utiliser l'API Analyze pour appeler de manière synchrone Discovery afin d'obtenir une classification de l'e-mail. Vous pouvez ensuite utiliser la sortie de cette classification dans votre logique métier.
L'API Analyze ne prend en charge que les documents JSON.
Lorsque vous analysez un document avec l'API, vous indiquez comment vous souhaitez que le document soit traité en spécifiant la collection à associer à l'analyse. Le document n'est pas stocké dans la collection. A la place, les paramètres de configuration de la collection sont appliqués au document. Par exemple, si vous souhaitez rechercher des références d'entité dans un document, exécutez l'API Analyze sur une collection dans laquelle l'enrichissement Entities est appliqué. L'analyse de document obtenue identifie les mentions d'entité dans le document.
Soumettez une demande d'analyse pour une seule collection configurée avec les enrichissements que vous souhaitez utiliser pour analyser votre document à la demande. N'oubliez pas que les documents de la collection ne sont pas significatifs. Il s'agit des enrichissements définis pour la collection qui importe. Si vous soumettez des demandes à plusieurs collections, plusieurs modèles sont lancés en même temps, ce qui peut entraîner des échecs de demande.
Les enrichissements suivants sont pris en charge dans l'API Analyze :
- Modèles de règles avancés
- Contrats
- Entités personnalisées
- Dictionnaire
- Discriminant de document
- Entités(NLP)
- Mots clés(NLP)
- Machine Learning et modèles Watson Explorer Content Analytics Studio
- Expressions régulières
- Patterns (plan Enterprise uniquement)
- Sentiment of documents
- Table de compréhension[1]
- Discriminant de texte
Pour obtenir la liste complète des enrichissements pris en charge dans chaque langue, voir Prise en charge des langues.
Pour plus d'informations, voir la référence d'API Discovery.
Exemple d'analyse
Les données que vous soumettez pour analyse doivent être au format JSON. Le texte doit être spécifié sous la forme d'une chaîne ; il ne peut pas être spécifié sous la forme d'un tableau. Par exemple, le fichier JSON suivant contient un guillemet
dans la zone Quote que vous souhaitez analyser pour trouver des mentions de mot clé dans le texte.
{
"Author": "Jane Austen",
"Book": "Pride and Prejudice",
"Quote": "From this day you must be a stranger to one of your parents. Your mother will never see you again if you do not marry Mr. Collins, and I will never see you again if you do.",
"Year": "1813/01/01",
"Subject":"Parental love",
"Speaker": "Mr. Bennett",
"url": "https://www.gutenberg.org/files/1342/1342-h/1342-h.htm#link2HCH0020"
}
Vous connaissez le nom d'une collection dans votre projet où l'enrichissement Mots-clés est configuré pour être appliqué aux documents de la collection. Vous pouvez utiliser l'API pour répertorier vos collections afin de trouver l'ID associé à la collection que vous recherchez par nom.
Après avoir obtenu l'ID de collection, incluez-le dans la demande POST que vous soumettez pour appliquer les paramètres de configuration de la collection à votre fichier JSON. Par exemple, la demande suivante soumet le fragment JSON dans un
fichier nommé favorites2.json pour l'analyse des mots clés.
curl --location --request POST \
'https://my-cloud-pak-for-data-cluster/discovery/zen-wd/instances/{instance-id}/api/v2/ \
projects/{project-id}/collections/{collection-id}/analyze?version=2020-08-30' \
--header 'Authorization: Bearer ...' \
--form 'file=@"/quotations/favorites2.json"'
Le résultat contient une liste de mots clés qui ont été reconnus dans le devis.
{
"result": {
"enriched_Quote": [
{
"keywords": [
{
"text": "day",
"mentions": [
{
"text": "day",
"location": {
"begin": 10,
"end": 13
}
}
],
"relevance": 0.673739
},
{
"text": "stranger",
"mentions": [
{
"text": "stranger",
"location": {
"begin": 28,
"end": 36
}
}
],
"relevance": 0.596757
},
{
"text": "parents",
"mentions": [
{
"text": "parents",
"location": {
"begin": 52,
"end": 59
}
}
],
"relevance": 0.568336
},
{
"text": "mother",
"mentions": [
{
"text": "mother",
"location": {
"begin": 66,
"end": 72
}
}
],
"relevance": 0.755562
},
{
"text": "Mr. Collins",
"mentions": [
{
"text": "Mr. Collins",
"location": {
"begin": 118,
"end": 129
}
}
],
"relevance": 0.945891
}
]
}
],
"url": "https://www.gutenberg.org/files/1342/1342-h/1342-h.htm#link2HCH0020",
"Subject": "Parental love",
"Year": "1813/01/01",
"Book": "Pride and Prejudice",
"Author": "Jane Austen",
"Quote": [
"From this day you must be a stranger to one of your parents. Your mother will never see you again if you do not marry Mr. Collins, and I will never see you again if you do."
],
"metadata": {
"name": "favorites2.json"
},
"Speaker": "Mr. Bennett"
},
"notices": []
}
Vous ne pouvez pas soumettre un tableau d'objets en tant qu'entrée. Par exemple, vous pouvez vouloir analyser plusieurs citations, de sorte que votre source se présente comme suit:
{
"quotations":[
{
"Author": "Jane Austen",
"Book": "Sense and Sensibility",
"Quote": "Is there a felicity in the world superior to this?",
"Year": "1811/01/01",
"Subject": "Nature",
"Speaker": "Marianne Dashwood",
"url": "https://www.gutenberg.org/files/1342/1342-h/1342-h.htm#link2HCH0059"
},
{
"Author": "Jane Austen",
"Book": "Persuasion",
"Quote": "A man does not recover from such a devotion of the heart to such a woman. He ought not; he does not.",
"Subject": "Romantic love",
"Year": "1818/01/01",
"Speaker": "Captain Wentworth",
"url": "https://www.gutenberg.org/files/105/105-h/105-h.htm#chap20"
}
]
}
Si tel est le cas, scinder chaque objet en un fichier distinct et analyser chaque fichier individuellement.
Analyse d'un fragment de texte
Vous pouvez soumettre du texte pour analyse lorsque vous spécifiez le texte au format JSON en utilisant une syntaxe telle que celle-ci:
{
"text":"The text that you want to analyze."
}
L'exemple de demande suivant montre comment analyser le texte que vous spécifiez dans la demande, et non pas que vous transmettez dans un fichier physique.
curl --location --request POST \
'https://my-cloud-pak-for-data-cluster/discovery/zen-wd/instances/{instance-id}/api/v2/ \
projects/{project-id}/collections/{collection-id}/analyze?version=2020-08-30' \
--header 'Authorization: Bearer ...' \
--form 'file={"text": "ISO 9000 is a standard."}'
La réponse peut être la suivante.
{
"result" : {
"enriched_text" : [ {
"entities" : [ {
"text" : "ISO 9000",
"type" : "my_iso_pattern",
"mentions" : [ {
"text" : "ISO 9000",
"confidence" : 1.0,
"location" : {
"begin" : 0,
"end" : 8
}
} ],
"model_name" : "My ISO Pattern"
}, {
"text" : "9000",
"type" : "Number",
"mentions" : [ {
"text" : "9000",
"confidence" : 0.8,
"location" : {
"begin" : 4,
"end" : 8
}
} ],
"model_name" : "natural_language_understanding"
} ]
} ],
"metadata" : { },
"text" : [ "ISO 9000 is a standard." ]
},
"notices" : [ ]
}
Analyse du contenu HTML
Vous pouvez analyser le code HTML lorsque vous soumettez le code HTML au format JSON en utilisant la syntaxe suivante:
{
"html":"<p>My html content.</p>"
}
L'exemple de demande suivant montre comment analyser le texte que vous spécifiez dans la demande, et non pas que vous transmettez dans un fichier physique.
La collection à laquelle la demande est adressée utilise les enrichissements suivants, ce qui signifie que ces enrichissements sont appliqués au contenu que vous soumettez avec la demande d'API:
- Entités
- Des mots clés
- Enrichissement Table Understanding
Exemple de demande
Le corps de la demande contient form-data avec le nom file. La valeur est le contenu JSON à analyser.
curl --location --request POST \
'https://cpd-abc.example.com/discovery/abc-wd/instances/1671204318684041/api/v2/projects/d457fcd9-a4ce-4637-a340-33123b5cbe2c/collections/2d47dbcc-64c7-84e9-0000-01851bb9d998/analyze?version=2020-08-30' \
--header 'Authorization: Bearer ...' \
--form 'file={
"html":"<html><head>This is my html file</head><body><p>My file contains a table.</p><table><tbody><tr><th>Holiday</th><th>Popular greeting</th></tr><tr><td>Christmas</td><td>Merry Christma!s</td></tr></tbody></table></body></html>",
"text":"This is a sentence that contains key words, such as George Washington and Boston, MA."
}'
Résultats
Les résultats affichent la sortie des enrichissements Entities, Mots-clés et Table Understanding sur les zones text et html qui ont été soumises.
{
"result": {
"text": [
"This is a sentence that contains key words, such as George Washington and Boston, MA."
],
"enriched_text": [
{
"keywords": [
{
"text": "George Washington",
"mentions": [
{
"text": "George Washington",
"location": {
"begin": 52,
"end": 69
}
}
],
"relevance": 0.952591
},
{
"text": "Boston",
"mentions": [
{
"text": "Boston",
"location": {
"begin": 74,
"end": 80
}
}
],
"relevance": 0.578079
},
{
"text": "MA",
"mentions": [
{
"text": "MA",
"location": {
"begin": 82,
"end": 84
}
}
],
"relevance": 0.146905
}
],
"entities": [
{
"text": "George Washington",
"type": "Location",
"mentions": [
{
"text": "George Washington",
"confidence": 0.54922265,
"location": {
"begin": 52,
"end": 69
}
}
],
"model_name": "natural_language_understanding"
},
{
"text": "Boston, MA",
"type": "Location",
"mentions": [
{
"text": "Boston, MA",
"confidence": 0.66049105,
"location": {
"begin": 74,
"end": 84
}
}
],
"model_name": "natural_language_understanding"
}
]
}
],
"metadata": {},
"enriched_html": [
{
"tables": [
{
"body_cells": [
{}
],
"location": {
"begin": 99,
"end": 183
},
"row_headers": [],
"key_value_pairs": [],
"section_title": {},
"contexts": [],
"text": "Holiday Popular greeting Christmas Merry Christmas!",
"table_headers": [],
"title": {},
"column_headers": []
}
]
}
],
"html": [
"<html><head>This is my html file</head><body><p>My file contains a table.</p><table><tbody><tr><th>Holiday</th><th>Popular greeting</th></tr><tr><td>Christmas</td><td>Merry Christmas!</td></tr></tbody></table></body></html>"
]
},
"notices": []
}
Analyser les limites d'API
Le tableau suivant présente la taille de fichier et les limites d'utilisation de l'API Analyze.
| Type de déploiement | Limite de taille de fichier | Limite de collectes simultanées | Nombre maximal de requêtes simultanées par collection |
|---|---|---|---|
| Déploiement installé de Cloud Pak for Data | Illimité | Illimité | Illimité |
| Déploiement géré du plan Enterprise | 50 Ko | 5 | 5 |
L'utilisation de l'API d'analyse à partir de Discovery Cartridge for IBM Cloud Pak for Data affecte l'utilisation des licences. Pour plus d'informations, voir les informations sur les licences.
Contrôle de l'utilisation IBM Cloud Pak for DataIBM Software Hub
Vous pouvez surveiller l'utilisation de l'API Analyze à partir de la page Utilisation de l'API.
La page Utilisation de l'API est disponible uniquement à partir des déploiements installés. Pour les plans Enterprise, les informations d'appel de méthode d'analyse sont combinées avec les informations d'appel de méthode de requête et sont signalées comme faisant partie des métriques de requête.
Pour accéder à la page d'utilisation de l'API, ouvrez la page Projets, sélectionnez Utilisation des données, puis Utilisation de l'API.
- Date de début
- Date de début de la période de surveillance des appels API.
- Date de fin
- Date de fin de la période de surveillance de l'appel API.
- Total des appels de trente jours
- Nombre d'appels à l'API Analyze dans l'intervalle de temps de 30 jours indiqué par la date de début et la date de fin. L'intervalle de temps est déterminé en calculant la période consécutive avec le plus grand nombre d'appels API. La fenêtre de 30 jours est mise à jour lorsque l'intervalle de temps avec le plus grand nombre d'appels API change.
L'utilisation de l'API n'est pas affichée avant un certain temps après le début de la surveillance de l'utilisation de l'API. Un retard dans l'affichage du nombre total final du nombre total d'appels de 30 jours peut se produire, même si la période de 30 jours répertoriée inclut la date en cours.
-
Pour que l'enrichissement de compréhension de table génère des résultats, l'entrée doit contenir un élément HTML
<table>à analyser. ↩︎