Libellés et champs généraux

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.

Certains routages, qui sont actuellement des routages de prédiction, renverront éventuellement une liste de noms de seuil, tels que « High_recall », « équilibred » « High_precision » auquel correspond le score de confiance du libellé. Il s'agit d'une alternative utile aux seuils de sélection manuelle, en particulier pour les taxonomies très grandes. Dans votre application, vous décidez si vous êtes intéressé par les résultats « High_recall », « équilibred » ou « High_precision », puis supprimez tous les libellés qui ne possèdent pas le seuil automatique 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'ensemble de données : le nom du libellé prévu, formaté sous la forme d'une liste de libellés hiérarchisés. Par exemple, le libellé Libellé parent > Libellé enfant aura le format ["Parent Label", "Child Label"]. Route de l'API d'exportation de l'ensemble de données : le nom du libellé prévu, 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écifiques ou la ponctuation.
• 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
|	Barre verticale
,	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 courante consiste à choisir le seuil égal à la précision que vous souhaitez obtenir (« Je veux 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élection des seuils de confiance des libellés.

Utilisation de libellés dans les analyses

Si vous exportez des libellés à utiliser dans une application d'analyse, il est important de décider si vous souhaitez 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 absente du libellé à l'aide de l'une des approches décrites dans la section Automatisation . D'autre part, les utilisateurs d'applications de science des données Compétents dans le travail avec des données probabilistes bénéficieront d'un 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 : après 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	Étiquetages attribués	Libellés Prévoir
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. Notez que les libellés prédits peuvent également avoir 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	Étiquetages attribués	Libellés Prévoir
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
    },
    {
      "id": "0000000000000002",
      "name": "quality_of_service",
      "value": -3.006324252113699913
    }
  ]
}

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

Nom	Saisie de texte	DESCRIPTION
name	string	Nom de la propriété de libellé.
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 toutes les dates apparaissant dans un commentaire et les normalisera en utilisant le format standard ISO 8601, suivi de l'heure en UTC. Par exemple, « 25 janvier 2020 », « 25/01/2020 » et « maintenant » dans un e-mail envoyé le 25 janvier 2020 seront tous extraits en tant que « 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 textuelles via le téléchargement de fichiers 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. Notez que les téléchargements au format CSV n’incluront 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é épinglée.
version	Numérique	Version du modèle.