Libellés et champs généraux

Cette page explique 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 savoir où les trouver dans les données téléchargées, consultez 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édits. L'exemple ci-dessous montre deux libellés prédits ( Ordre (Order ) et Ordre (Order) > Manquant (Missing) ) avec leurs scores de confiance. Ce format est utilisé par la plupart des routages d'API. Une exception est l' itinérairet de l'exportation de jeu de données qui formate les noms de libellés sous forme de chaînes au lieu de listes (pour être cohérent avec l'exportation CSV dans le navigateur).

Certains routages (actuellement des routages de prédiction) renverront éventuellement une liste de noms de seuil (« High_recall », « équilibred », « High_precision ») que le score de confiance du libellé respecte. Il s'agit d'une alternative utile à la sélection manuelle des seuils, en particulier pour les taxonomies très volumineuses. 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 qui ne disposent pas du seuil automatique choisi et traitez les libellés restants comme auparavant.

• 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	<string> tableau<chaîne> ou chaîne	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	Numérique	Score de confiance. Un nombre entre 0,0 et 1,0.
sentiment	Numérique	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.

FAQ sur les libellés

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

R : Les méthodes de téléchargement suivantes fournissent des libellés : API Communications Mining , Téléchargements de fichiers CSV et outil de ligne de commande Communications Mining . Consultez la page Téléchargement de données (Downloading Data) pour avoir un aperçu des méthodes de téléchargement disponibles, et consultez la FAQ ci-dessous 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 ci-dessous expliquent les différences entre les méthodes de téléchargement. Une description des libellés de la page Explorer (Explore) de l'interface utilisateur Web de Communications Mining est fournie à des fins de comparaison.

Méthodes non déterministe

La page Explorer (Explore), le téléchargement au format CSV, l'outil de ligne de commande Communications Mining et le point de terminaison de l'API d'exportation (Export API) fournissent les dernières prédictions disponibles. Notez qu'après l'entraînement d'une nouvelle version de modèle, mais avant que toutes les prédictions aient été recalculées, vous verrez un mélange de prédictions des versions la plus récente et précédente du modèle. 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éterministe ci-dessus, les routages de l'API de flux (Stream API) et de l'API de prédiction (Predict API) renverront les prédictions d'une version de modèle spécifique. En tant que tels, ces routages d'API se comportent comme si vous avez téléchargé un commentaire à partir de la plate-forme, puis l'avez envoyé pour prédiction par rapport à une version de modèle spécifique, et ne sont pas conscients 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).

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 égaler la précision que vous souhaitez obtenir (« Je veux que les libellés soient corrects au moins 70 % du temps, donc je choisirai les libellés avec des scores de confiance supérieurs à 0,70 »). Pour comprendre les seuils et comment les sélectionner, consultez la section Seuils de confiance du guide d'intégration.

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.

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 avoir zéro, un ou plusieurs champs généraux prédits. L'exemple ci-dessous montre une entité order_number prévue. Notez que contrairement aux libellés, les champs généraux n'ont pas de scores de confiance associés.

"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é a un span et 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 couverts par cette étendue, sauf dans certains cas spécifiques que nous décrivent ci-dessous.

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 puis-je télécharger les champs généraux à partir de la plate-forme Communications Mining ?

R : Les méthodes de téléchargement suivantes fournissent des champs généraux : API Communications Mining et outil de ligne de commande Communications Mining. Veuillez consulter la vue d’ensemble Téléchargement de données (Downloading Data) pour savoir quelle méthode convient le mieux à 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 les intégrations, une version de modèle peut être balisée en tant que staging ou live dans l'interface utilisateur de Communications Mining. Cette balise peut être fournie aux requêtes API de prédiction (Predict API) à 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 Staging ou Live pointe, que les utilisateurs de la plate-forme peuvent facilement gérer à partir de l'interface utilisateur de 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.