Libellés et champs généraux

This page describes how to interpret labels and general fields downloaded from the Communications Mining™ platform for use in your application. This page describes the labels and general fields themselves - to understand where to find them in the downloaded data, be sure to check the documentation for your chosen download method.

Libellés

A comment can have zero, one, or multiple predicted labels. The following example shows two predicted labels, Order and Order > Missing, together with their confidence scores. Most API routes use this format. An exception is the Dataset Export route, which formats label names as strings instead of lists to be consistent with the CSV export in the browser.

Some routes, which are currently Predict routes, will optionally return a list of threshold names, such as "high_recall", "balanced", "high_precision" that the label confidence score meets. This is a useful alternative to hand-picking thresholds, especially for very large taxonomies. In your application, you decide whether you are interested in "high_recall", "balanced", or "high_precision" results, then discard all labels that lack your chosen auto-threshold, and process the remaining labels as before.

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.

Label names must:

• Start with any unicode word character, for example, non-specical characters or punctuation.
• Contain any combination of word characters, spaces, or any of the special characters listed in the following table.

For example Hello World! is valid but !Hello World is not.

Special character	Nom
~	Tilde
!	Exclamation mark
@	At sign
#	Hash sign
$	Dollar sign
€	Euro sign
%	Percent sign
^	Caret
&	Ampersand
*	Asterisk
(	Left parenthesis
)	Right parenthesis
_	Underscore
+	Plus sign
-	Hyphen
=	Equals sign
[	Left square bracket
]	Right square bracket
{	Left curly brace
}	Right curly brace
;	Semicolon
'	Apostrophe
\	Barre oblique inverse
:	Colon
"	Quotation mark
|	Barre verticale
,	Comma
.	Période
/	Forward slash
<	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

If you are exporting labels for use in an analytics application, it's important to decide whether to expose confidence scores to users. For users of business analytics applications, you should convert the confidence scores into presence or absence of the label using one of the approaches described in the Automation section. On the other hand, users of data science applications proficient in working with probabilistic data will benefit from access to raw confidence scores.

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: The following download methods provide labels: Communications Mining , CSV downloads, and Communications Mining command-line tool. Check the Downloading Data page for an overview of the available download methods, and the following FAQ item for a detailed comparison.

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

A: The following tables explain the differences between the download methods. A description of labels in the Explore page in the Communications Mining web UI is provided for comparison.

Méthodes non déterministe

The Explore page, CSV download, Communications Mining command-line tool, and the Export API endpoint provide the latest available predictions.

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

A comment can have zero, one, or multiple predicted general fields. The following example shows one predicted order_number entity.

Note: Unlike labels, general fields do not have associated confidence scores.

"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>	The capture IDs of the groups to which an entity belongs.

Formatting

Each entity has a span and a formatted_value. The span represents the boundaries of the entity in the corresponding comment. The formatted_value typically corresponds to the text covered by that span, except in some specific instances that we describe in the sections that follow.

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: The following download methods provide general fields: Communications Mining and Communications Mining command-line tool. Please take a look at the Downloading Data overview to understand which method is suitable for your use-case. Note that CSV downloads will not include general fields.

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

Details about a specific model version can be fetched using the Validation API endpoint.

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.