Libellés et champs généraux

Libellés et champs généraux dans les données Communications Mining téléchargées, y compris leur structure et leur interprétation dans des applications externes.

Cette page décrit comment interpréter les libellés et les champs généraux téléchargés à partir de la plate-forme Communications Mining™ pour les utiliser dans votre application. Cette page décrit les libellés et les champs généraux eux-mêmes : pour comprendre où les trouver dans les données téléchargées, assurez-vous de consulter la documentation de la méthode de téléchargement que vous avez choisie.

Libellés

Un commentaire peut avoir zéro, un ou plusieurs libellés prévus. L'exemple suivant montre deux libellés prévus, Ordre et Ordre > Manquant, ainsi que leurs scores de confiance. La plupart des routages d’API utilisent ce format. Une exception est la route d’ exportation d’ensembles de données , qui formate les noms de libellé sous forme de chaînes au lieu de listes, afin d’être compatible avec l’exportation CSV dans le navigateur.

Certaines routes, qui sont actuellement des routes de prévision, renverront éventuellement une liste de noms de seuils, tels que « High_recall », « Balanced », « High_precision », auquel le score de confiance du libellé correspond. Il s'agit d'une alternative utile aux seuils de sélection manuelle, en particulier pour les très grandes taxonomies.

Dans votre application, vous décidez si vous êtes intéressé par les résultats « High_recall », « Balanced » ou « High_precision », puis supprimez tous les libellés pour lesquels le seuil automatique n’a pas été choisi et traitez les libellés restants comme avant.

Tous les routages sauf l’exportation d’ensembles de données

{
  "labels": [
    {
      "name": ["Order"],
      "probability": 0.6598735451698303
    },
    {
      "name": ["Order", "Missing"],
      "probability": 0.6598735451698303
    }
  ]
}

Exportation d'ensemble de données

{
  "labels": [
    {
      "name": "Order",
      "probability": 0.6598735451698303
    },
    {
      "name": "Order > Missing",
      "probability": 0.6598735451698303
    }
  ]
}

Prédiction (seuilée automatique)

{
  "labels": [
    {
      "name": ["Order"],
      "probability": 0.6598735451698303,
      "auto_thresholds": ["high_recall", "balanced", "sampled_2"]
    },
    {
      "name": ["Order", "Missing"],
      "probability": 0.6598735451698303,
      "auto_thresholds": ["high_recall", "sampled_2"]
    }
  ]
}

L'objet Label a le format suivant :

Nom	Saisie de texte	Description
name	array<string> ou string	Tous les routages d'API, à l'exception de l' exportation d'ensembles de données : le nom du libellé prévu, au format de la liste de libellés hiérarchiques. Par exemple, le libellé Libellé parent > Libellé enfant aura le format ["Parent Label", "Child Label"]. Route API pour l'exportation de l'ensemble de données : le nom du libellé prévu, au format sous la forme d'une chaîne avec " > " séparant les libellés hiérarchiques.
probability	number	Score de confiance. Un nombre entre 0,0 et 1,0.
sentiment	number	Score de sentiment. Un nombre compris entre -1,0 et 1,0. Renvoyé uniquement si les sentiments sont activés dans l'ensemble de données.
auto_thresholds	array<string>	Liste de seuils calculés automatiquement que le score de confiance du libellé respecte. Les seuils sont renvoyés sous forme de noms descriptifs (plutôt que les valeurs comprises entre 0,0 et 1) qui peuvent être utilisés pour filtrer facilement les libellés qui ne répondent pas aux niveaux de confiance souhaités. Les noms de seuil "High_recall", "balanced" et "High_precision" correspondent à trois niveaux de confiance croissants. Les seuils supplémentaires « sampled_0 » ... « sampled_5 » fournissent un moyen plus avancé d’effectuer des agrégations pour les applications de science des données ; ils peuvent être ignorés si vous traitez les commentaires un par un.

Les noms de libellé doivent :

• Commencez par n'importe quel caractère de mot Unicode, par exemple les caractères non spéciaux ou les caractères de ponctuations.
• contenir toute combinaison de caractères de mots, d'espaces ou de l'un des caractères spéciaux répertoriés dans le tableau suivant.

Par exemple, Hello World! est valide, mais pas !Hello World .

Caractère spécial	Nom
~	Tilde
!	Point d'exclamation
@	Au niveau
#	Symbole Hash
$	Symbole Dollar
Euro	Symbole Euro
%	Signe du pourcentage
^	Point d’insertion
&	Ampère
*	Asterisk
(	Parenthèse de gauche
)	Parenthèse de droite
_	Trait de soulignement
+	Symbole Plus
-	Hyperfluence
=	signe égal
[	Support carré gauche
]	Support carré droit
{	Croisage gauche
}	Croisage droit
;	Point-virgule
'	Apostrophe
\	Barre oblique inverse
:	Colon
"	Quotation mark
,	Virgule
.	Période
/	Barre oblique
<	Less than sign
?	Question mark

Utilisation de libellés dans l'automatisation

Lors de la conception d'une application qui prend des décisions par message, vous souhaiterez convertir le score de confiance de chaque libellé en une réponse Oui ou Non. Vous pouvez le faire en déterminant le score de confiance minimum à partir duquel vous traiterez la prédiction comme suit : « oui, l'étiquette s'applique ». Nous appelons ce numéro le seuil du score de confiance.

Important :

Comment choisir un seuil de score de confiance

Une idée erronée consiste à choisir le seuil pour être égal à la précision que vous souhaitez obtenir « Je souhaite que les libellés soient corrects au moins 70 % du temps, je choisirai donc des libellés avec des scores de confiance supérieurs à 0,70 ». Pour comprendre les seuils et comment les choisir, consultez la section Sélectionner les seuils de confiance du libellé.

Utilisation de libellés dans les analyses

Si vous exportez des libellés destinés à être utilisés dans une application d'analyse, il est important de décider s'il faut exposer les scores de confiance aux utilisateurs. Pour les utilisateurs d'applications d'analyse métier, vous devez convertir les scores de confiance en présence ou en absence du libellé à l'aide de l'une des approches décrites dans la section Automatisation .

D’un autre côté, les utilisateurs d’applications de science des données capables de travailler avec des données probabilistes bénéficieront de l’accès aux scores de confiance bruts.

Une considération importante est de vous assurer que toutes les prédictions de votre application d'analyse proviennent de la même version de modèle. Si vous mettez à niveau votre intégration pour récupérer des prédictions à partir d'une nouvelle version de modèle, toutes les prédictions devront être réingérées pour que les données restent cohérentes.

FAQ sur les libellés

Q : Comment télécharger des libellés à partir de la plate-forme Communications Mining™ ?

A : les méthodes de téléchargement suivantes fournissent des libellés : Communications Mining, téléchargements CSV et outil de ligne de commande Communications Mining . Consultez la page Téléchargement de données pour obtenir un aperçu des méthodes de téléchargement disponibles, et l’élément FAQ suivant pour obtenir une comparaison détaillée.

Q : Toutes les méthodes de téléchargement fournissent-elles les mêmes informations ?

R : Les tableaux suivants expliquent les différences entre les méthodes de téléchargement. Une description des libellés sur la page Explorer de l'interface utilisateur Web de Communications Mining est fournie à des fins de comparaison.

Méthodes non déterministe

La page Explorer , le téléchargement CSV, l’outil de ligne de commande Communications Mining et le point de terminaison Exporter l’API fournissent les dernières prédictions disponibles.

Remarque :

Une fois qu’une nouvelle version de modèle a été entraînée, mais avant que toutes les prédictions n’aient été recalculées, vous remarquerez un mélange de prédictions provenant des versions de modèle les plus récentes et précédentes. Ces méthodes prennent en compte les libellés attribués et les afficheront comme attribués ou avec un score de confiance de 1.

Method	Libellés attribués	Libellés prévus
Explorer la page	La page Explorer (Explore) différencie visuellement les libellés attribués des libellés prédits. Il ne signale pas les scores de confiance pour les libellés attribués.	La page Explorer (Explore) est conçue pour prendre en charge le workflow d'entraînement du modèle, elle affiche donc les libellés prédits sélectionnés que l'utilisateur pourra épingler. Il affichera prioritairement les libellés qui respectent un seuil équilibré (dérivé du score F pour ce libellé), mais pourra également afficher les libellés avec une probabilité plus faible sous forme de suggestion, si l'utilisateur est susceptible de les épingler.
Exporter l'API	Renvoie les libellés attribués.	Renvoie tous les libellés prévus (aucun seuil n'est appliqué).
Téléchargement du fichier CSV	Renvoie un score de confiance de 1 pour les libellés attribués. Remarque : les libellés prévus peuvent également afficher un score de 1 si le modèle est très fiable.	Renvoie tous les libellés prévus (aucun seuil n'est appliqué).
CLI Communications Mining	Si un commentaire comprend des libellés attribués, renverra à la fois les libellés attribués et prédits pour ce commentaire.	Renvoie tous les libellés prévus (aucun seuil n'est appliqué).

Méthodes déterminiques

Contrairement aux méthodes non déterministes précédentes, les routages de l'API de flux et de l'API de prédiction renverront les prédictions d'une version de modèle spécifique. Par exemple, ces routages d'API se comportent comme si vous aviez téléchargé un commentaire à partir de la plate-forme, puis l'avoir envoyé pour la prédiction par rapport à une version de modèle spécifique, et que vous n'avez pas connaissance des libellés attribués.

Method	Libellés attribués	Libellés prévus
API de flux et API de prédiction	Ignore des libellés attribués.	Renvoyez les libellés prédits avec un score de confiance supérieur aux seuils de libellé fournis (ou supérieur à la valeur par défaut de 0,25 si aucun seuil n'est fourni).

propriétés du libellé

Si des libellés de qualité de service ont été ajoutés à l'ensemble de données, la réponse de prédiction contiendra un score de qualité de service pour chaque commentaire. Si Tone a été activé sur un ensemble de données, la réponse de prédiction contiendra un score Tone pour chaque commentaire. Les deux scores se trouvent dans la partie label_properties de la réponse.

{
  "label_properties": [
    {
      "property_id": "0000000000000001",
      "property_name": "tone",
      "value": -1.8130283355712891
    },
    {
      "property_id": "0000000000000002",
      "property_name": "quality_of_service",
      "value": -3.006324252113699913
    }
  ]
}

L'objet de propriété de libellé a le format suivant :

Nom	Saisie de texte	Description
property_name	string	Nom de la propriété de libellé.
property_id	string	ID interne de la propriété du libellé.
value	Numérique	Valeur de la propriété du libellé. Une valeur comprise entre -10 et 10.

Champs généraux

Un commentaire peut comporter zéro, un ou plusieurs champs généraux prévus. L'exemple suivant montre une entité order_number prévue.

Remarque :

Contrairement aux libellés, les champs généraux ne sont pas associés à des scores de confiance.

"entities": [
    {
        "id": "0abe5b728ee17811",
        "name": "order_number",
        "span": {
            "content_part": "body",
            "message_index": 0,
            "utf16_byte_start": 58,
            "utf16_byte_end": 76,
            "char_start": 29,
            "char_end": 38
        },
        "name": "order_number",
        "kind": "order_number", # deprecated
        "formatted_value": "ABC-123456",
        "capture_ids": []
    }
]

L'API renvoie des entités au format suivant :

Nom	Saisie de texte	Description
id	string	ID d'entité.
name	string	Nom de l'entité.
kind	string	(Obsolète) Type d’entité.
formatted_value	string	Valeur de l'entité.
span	Span	Objet contenant l'emplacement de l'entité dans le commentaire.
capture_ids	array<int>	Les ID de capture des groupes auxquels appartient une entité.

Formatting

Chaque entité dispose d’un identifiant span et d’un formatted_value. L'étendue représente les limites de l'entité dans le commentaire correspondant. Le formatted_value correspond généralement au texte couvert par cette période, sauf dans certains cas spécifiques que nous décrivent dans les sections qui suivent.

Quantité monétaire

L'entité Monetary Quantity extraira une grande variété de montants monétaires et appliquera un formatage commun. Par exemple, « 1M USD », « USD 1000000 » et « 1 000 000 usd » seront tous extraits en tant que 1,000,000.00 USD. Étant donné que la valeur extraite est formatée de manière cohérente, vous pouvez facilement obtenir la devise et le montant en fractionnant sur les espaces.

Cependant, si la devise est ambiguë, la valeur extraite conservera la devise ambiguë. Par exemple, « $1M » et « $1 000 000 » seront extraits en tant que $1,000,000.00 plutôt qu’en 1,000,000.00 USD, car un signe « $ » peut faire référence à un dollar américain ou australien.

Date

L'entité Date extraira toute date apparaissant dans un commentaire et la normalisera à l'aide du format standard ISO 8601, suivi de l'heure indiquée par l'heure UTC. Par exemple, « 25/01-2020 », « 25/01/2020 » et « Now » dans un e-mail envoyé le 25 janvier 2020 seront tous extraits sous la forme « 2020-01-25 00:00 UTC ».

Ce formatage sera appliqué à toute entité dont le type correspond à une date, par exemple les dates d'annulation, les dates de valeur ou tout type de dates ayant été entraînées par l'utilisateur.

Si certaines parties de la date sont manquantes, l'horodatage du commentaire sera utilisé comme ancre ; la date « à 16 h le 5 du mois » dans un message envoyé le 1 er mai 2020 sera extraite en tant que « 2020-05-05 16 h 00 UTC ». Si aucun fuseau horaire n'est fourni, le fuseau horaire du commentaire est utilisé, mais la date extraite sera toujours renvoyée dans le fuseau horaire UTC.

Pays

Les noms de pays sont normalisés par rapport à une valeur commune ; par exemple, les chaînes "Royaume-Uni" et "Royaume-Uni" auront la valeur formatée "Royaume-Uni".

ID de capture

Si un commentaire a été traité comme du texte enrichi, contient une table et qu'une entité a été mise en correspondance dans cette table, la propriété capture_ids de cette entité contiendra un ID de capture. Les entités correspondantes dans la même ligne du tableau auront le même ID de capture, leur permettant d'être regroupées.

Par exemple, un Order ID peut être associé à un Order Date. Dans un commentaire où plusieurs commandes sont référencées, il est possible de distinguer les différents détails de commande en regroupant les entités par leurs ID de capture.

Aujourd'hui, les entités correspondantes dans une table appartiendront à exactement un groupe, c'est-à-dire que leur propriété capture_ids contiendra exactement un ID. À l'avenir, l'API est susceptible de renvoyer plusieurs ID.

Dans tous les autres cas, la propriété capture_id sera une liste vide.

Remarque :

Les entités seront désormais conservées lors des mises à jour de texte via le téléchargement CSV ou l'API.

FAQ sur les champs généraux

Q : Comment télécharger des champs généraux à partir de la plate-forme Communications Mining™ ?

A : Les méthodes de téléchargement suivantes fournissent des champs généraux : Communications Mining et Outil de ligne de commande Communications Mining . Consultez la vue d’ensemble de la vue Téléchargement de données pour comprendre la méthode adaptée à votre cas d’utilisation.

Remarque :

Les téléchargements au format CSV n’incluent pas les champs généraux.

Modèles

Balises Staging et Live

Pour faciliter l’utilisation des intégrations, une version de modèle peut être balisée comme staging ou live dans l’interface utilisateur Communications Mining™. Cette balise peut être fournie dans les requêtes d’API de prédiction à la place du numéro de version du modèle. Cela permet à votre intégration d’extraire des prédictions à partir de n’importe quelle version de modèle vers laquelle la balise Organisation ou En production pointe, que les utilisateurs de la plate-forme peuvent facilement gérer à partir de l’interface utilisateur Communications Mining.

Détails de la version du modèle

Les détails d’une version de modèle spécifique peuvent être récupérés à l’aide du point de terminaison de l’API de validation.

De plus, les réponses aux demandes de prédiction contiennent des informations sur le modèle utilisé pour faire les prédictions.

"model": {
    "version": 2,
    "time": "2021-02-17T12:56:13.444000Z"
}

Nom	Saisie de texte	Description
time	Horodatage	Lorsque la version du modèle a été publiée.
version	Numérique	Version du modèle.