Etiquetas y campos generales

Esta página describe cómo interpretar las etiquetas y los campos generales descargados de la plataforma Communications Mining™ para su uso en tu aplicación. En esta página se describen las etiquetas y los campos generales. Para entender dónde encontrarlos en los datos descargados, asegúrate de consultar la documentación del método de descarga elegido.

Etiquetas

Un comentario puede tener cero, una o varias etiquetas previstas. El siguiente ejemplo muestra dos etiquetas predichas, Orden y Orden > Falta, junto con sus puntuaciones de confianza. La mayoría de las rutas de la API utilizan este formato. Una excepción es la ruta de exportación del conjunto de datos , que da formato a los nombres de las etiquetas como cadenas en lugar de listas para ser coherentes con la exportación CSV en el navegador.

Algunas rutas, que actualmente son rutas Predecir, devolverán opcionalmente una lista de nombres de umbral, como "high_recall", "balanced", "high_precision" que cumple la puntuación de confianza de la etiqueta. Esta es una alternativa útil a la selección manual de umbrales, especialmente para taxonomías muy grandes. En tu aplicación, decides si te interesan los resultados "high_recall", "balanced" o "high_precision", luego descartas todas las etiquetas que carecen del umbral automático elegido y procesas las etiquetas restantes como antes.

Todas las rutas excepto la exportación de conjuntos de datos

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

Exportar conjunto de datos

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

Predecir (con umbral automático)

{
  "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"]
    }
  ]
}

El objeto Etiqueta tiene el siguiente formato:

Nombre	Tipo	Descripción
name	array<string> o string	Todas las rutas de la API excepto la exportación del conjunto de datos: el nombre de la etiqueta prevista, en formato de lista de etiquetas jerárquicas. Por ejemplo, la etiqueta Etiqueta principal > Etiqueta secundaria tendrá el formato ["Parent Label", "Child Label"]. Ruta de la API de exportación del conjunto de datos: el nombre de la etiqueta predicha, en formato de cadena con " > " etiquetas jerárquicas de separación.
probability	number	Puntuación de confianza. Un número entre 0.0 y 1.0.
sentiment	number	Puntuación de opinión. Un número entre -1.0 y 1.0. Solo se devuelve si los sentimientos están habilitados en el conjunto de datos.
auto_thresholds	array<string>	Una lista de umbrales calculados automáticamente que cumple la puntuación de confianza de la etiqueta. Los umbrales se devuelven como nombres descriptivos (en lugar de valores entre 0,0 y 1) que pueden utilizarse para filtrar fácilmente las etiquetas que no cumplen los niveles de confianza deseados. Los nombres de umbral "high_recall", "balanced" y "high_precision" corresponden a tres niveles de confianza crecientes. Los umbrales adicionales "sampled_0" ... "sampled_5" proporcionan una forma más avanzada de realizar agregaciones para aplicaciones de ciencia de datos, y pueden ignorarse si se procesan comentarios uno por uno.

Los nombres de las etiquetas deben:

• Comienza con cualquier carácter de palabra unicode, por ejemplo, caracteres no específicos o puntuación.
• Contener cualquier combinación de caracteres de palabras, espacios o cualquiera de los caracteres especiales enumerados en la siguiente tabla.

Por ejemplo, Hello World! es válido pero !Hello World no lo es.

Carácter especial	Nombre
~	Tilde
!	Signo de exclamación
@	En el signo
#	Signo de almohadilla
$	Signo de dólar
€	Símbolo del euro
%	Signo de porcentaje
^	Caret
&	Ampersand
*	Asterisk
(	Paréntesis izquierdo
)	Paréntesis derecho
_	Guión bajo
+	Signo más
-	Guión
=	signo igual
[	Corchete izquierdo
]	Corchete derecho
{	Llave izquierda
}	Llave derecha
;	Punto y coma
'	Apóstrofe
\	Barra invertida
:	Colon
"	Quotation mark
|	Barra vertical
,	Coma
.	Periodo
/	Barra diagonal
<	Less than sign
?	Question mark

Uso de etiquetas en la automatización

Al diseñar una aplicación que toma decisiones por mensaje, querrás convertir la puntuación de confianza de cada etiqueta en una respuesta Sí o No. Puedes hacerlo determinando la puntuación de confianza mínima en la que tratarás la predicción como diciendo "sí, se aplica la etiqueta". A este número lo llamamos umbral de puntuación de confianza.

Importante:

CÓMO ELEGIR UN UMBRAL DE PUNTUACIÓN DE CONFIANZA

Un error común es elegir el umbral para igualar la precisión que te gustaría obtener ("Quiero que las etiquetas sean correctas al menos el 70 % de las veces, así que elegiré etiquetas con puntuaciones de confianza superiores a 0,70"). Para entender los umbrales y cómo elegirlos, consulta Seleccionar umbrales de confianza de etiquetas.

Uso de etiquetas en análisis

Si exportas etiquetas para su uso en una aplicación de análisis, es importante decidir si exponer las puntuaciones de confianza a los usuarios. Para los usuarios de aplicaciones de análisis empresarial, debes convertir las puntuaciones de confianza en presencia o ausencia de la etiqueta utilizando uno de los enfoques descritos en la sección Automatización . Por otro lado, los usuarios de aplicaciones de ciencia de datos competentes en el trabajo con datos probabilísticos se beneficiarán del acceso a puntuaciones de confianza sin procesar.

Una consideración importante es asegurarse de que todas las predicciones en tu aplicación de análisis sean de la misma versión del modelo. Si actualizas tu integración para obtener predicciones de una nueva versión del modelo, será necesario volver a incorporar todas las predicciones para que los datos sean coherentes.

Preguntas frecuentes sobre etiquetas

P: ¿Cómo puedo descargar etiquetas de la plataforma Communications Mining™?

R: Los siguientes métodos de descarga proporcionan etiquetas: Communications Mining , descargas de CSV y la herramienta de línea de comandos de Communications Mining . Consulta la página Descarga de datos para obtener una descripción general de los métodos de descarga disponibles, y el siguiente elemento de Preguntas frecuentes para una comparación detallada.

P: ¿Todos los métodos de descarga proporcionan la misma información?

R: Las siguientes tablas explican las diferencias entre los métodos de descarga. Se proporciona una descripción de las etiquetas en la página Explorar en la interfaz de usuario web de Communications Mining para su comparación.

Métodos no deterministas

La página Explorar , la descarga de CSV, la herramienta de línea de comandos de Communications Mining y el punto final Exportar API proporcionan las últimas predicciones disponibles.

Nota: Después de entrenar una nueva versión del modelo, pero antes de que se hayan vuelto a calcular todas las predicciones, notarás una mezcla de predicciones de las versiones más recientes y anteriores del modelo. Estos métodos son conscientes de las etiquetas asignadas y las mostrarán como asignadas o con una puntuación de confianza de 1.

Método	ETIQUETAS ASIGNADAS	ETIQUETAS PREVISTAS
Explorar página	La página Explorar diferencia visualmente las etiquetas asignadas de las etiquetas previstas. No informa de las puntuaciones de confianza para las etiquetas asignadas.	La página Explorar está diseñada para admitir el flujo de trabajo de entrenamiento del modelo, por lo que muestra las etiquetas predichas seleccionadas que el usuario puede querer anclar. Mostrará preferentemente las etiquetas que cumplan un umbral equilibrado (derivado de la puntuación F para esa etiqueta), pero también puede mostrar etiquetas con menor probabilidad como sugerencia, si es probable que el usuario quiera fijarlas.
Exportar API	Devuelve las etiquetas asignadas.	Devuelve todas las etiquetas previstas (no se aplica ningún umbral).
Descargar CSV	Devuelve una puntuación de confianza de 1 para las etiquetas asignadas. Ten en cuenta que las etiquetas predichas también pueden tener una puntuación de 1 si el modelo es muy seguro.	Devuelve todas las etiquetas previstas (no se aplica ningún umbral).
CLI de Communications Mining	Si un comentario tiene etiquetas asignadas, devolverá tanto las etiquetas asignadas como las previstas para ese comentario.	Devuelve todas las etiquetas previstas (no se aplica ningún umbral).

Métodos deterministas

A diferencia de los métodos no deterministas anteriores, las rutas de la API de transmisión y la API de predicción devolverán predicciones de una versión específica del modelo. Como tales, estas rutas API se comportan como si descargaras un comentario de la plataforma y luego lo enviaras para su predicción contra una versión específica del modelo, y no son conscientes de las etiquetas asignadas.

Método	ETIQUETAS ASIGNADAS	ETIQUETAS PREVISTAS
API de transmisión y API de predicción	Desconocimiento de las etiquetas asignadas.	Devolver etiquetas previstas con una puntuación de confianza superior a los umbrales de etiqueta proporcionados (o superior al valor predeterminado de 0,25 si no se proporcionan umbrales).

propiedades de etiquetas

Si se han añadido etiquetas de calidad de servicio al conjunto de datos, la respuesta de predicción contendrá una puntuación de calidad de servicio para cada comentario. Si se ha habilitado Tono en un conjunto de datos, la respuesta de predicción contendrá una puntuación de tono para cada comentario. Ambas puntuaciones se pueden encontrar en la parte label_properties de la respuesta.

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

El objeto de propiedad de la etiqueta tiene el siguiente formato:

Nombre	Tipo	Descripción
name	String	Nombre de la propiedad de la etiqueta.
id	String	ID interno de la propiedad de la etiqueta.
value	Número	Valor de la propiedad de la etiqueta. Un valor entre -10 y 10.

Campos generales

Un comentario puede tener cero, uno o varios campos generales previstos. El siguiente ejemplo muestra una entidad order_number predicha.

Nota: a diferencia de las etiquetas, los campos generales no tienen puntuaciones de confianza asociadas.

"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": []
    }
]

La API devuelve entidades en el siguiente formato:

Nombre	Tipo	Descripción
id	String	ID de entidad.
name	String	Nombre de la entidad.
kind	String	(Obsoleto) Tipo de entidad.
formatted_value	String	Valor de la entidad.
span	Span	Un objeto que contiene la ubicación de la entidad en el comentario.
capture_ids	array<int>	Los ID de captura de los grupos a los que pertenece una entidad.

Formatting

Cada entidad tiene un span y un formatted_value. El intervalo representa los límites de la entidad en el comentario correspondiente. El formatted_value normalmente corresponde al texto cubierto por ese lapso, excepto en algunos casos específicos que describimos en las secciones siguientes.

Cantidad monetaria

La entidad Monetary Quantity extraerá una amplia variedad de importes monetarios y aplicará un formato común. Por ejemplo, "1M USD", "USD 1000000" y "1 000 000 usd" se extraerán como 1,000,000.00 USD. Dado que el valor extraído tiene un formato coherente, puedes obtener fácilmente la moneda y el importe dividiendo en espacios en blanco.

Sin embargo, si la moneda es ambigua, el valor extraído conservará la moneda ambigua. Por ejemplo, "$1M" y "$1,000,000" se extraerán como $1,000,000.00 en lugar de 1,000,000.00 USD, ya que un signo "$" podría referirse a un dólar canadiense o australiano, así como a un dólar estadounidense.

Fecha

La entidad Date extraerá cualquier fecha que aparezca en un comentario y la normalizará utilizando el formato estándar ISO 8601, seguido de la hora en UTC. Por ejemplo, "25 de enero de 2020", "25/01/2020" y "ahora" en un correo electrónico enviado el 25 de enero de 2020 se extraerán como "2020-01-25 00:00 UTC".

Este formato se aplicará a cualquier entidad que tenga un tipo correspondiente a una fecha, como fechas de cancelación, fechas de valor o cualquier tipo de fecha que haya sido entrenada por el usuario.

Si faltan algunas partes de la fecha, la marca de tiempo del comentario se utilizará como anclaje; la fecha "a las 16:00 del día cinco del mes" en un mensaje enviado el 1 de mayo de 2020 se extraerá como "2020-05-05 16:00 UTC". Si no se proporciona ninguna zona horaria, se utiliza la zona horaria del comentario, pero la fecha extraída siempre se devolverá en la zona horaria UTC.

País

Los nombres de países se normalizan a un valor común; por ejemplo, ambas cadenas "Reino Unido" y "Reino Unido" tendrán el valor en formato "Reino Unido".

Capturar ID

Si un comentario se procesó como texto enriquecido, contiene una tabla y una entidad coincidía en esa tabla, la propiedad capture_ids de esa entidad contendrá un ID de captura. Las entidades que coincidan en la misma fila de la tabla tendrán el mismo ID de captura, lo que les permitirá agruparse.

Por ejemplo, un Order ID podría estar asociado a un Order Date. En un comentario en el que se hace referencia a varias órdenes, se pueden distinguir los diferentes detalles de la orden agrupando las entidades por sus ID de captura.

Hoy en día, las entidades que coinciden en una tabla pertenecerán exactamente a un grupo, es decir, su propiedad capture_ids contendrá exactamente un ID. En el futuro, la API puede devolver varios ID.

En todos los demás casos, la propiedad capture_id será una lista vacía.

Nota: Las entidades ahora se conservarán al realizar actualizaciones de texto a través de la carga de CSV o la API.

Preguntas frecuentes sobre los campos generales

P: ¿Cómo puedo descargar campos generales de la plataforma Communications Mining™?

R: Los siguientes métodos de descarga proporcionan campos generales: Communications Mining y la herramienta de línea de comandos de Communications Mining . Consulta la descripción general de Descarga de datos para comprender qué método es el adecuado para tu caso de uso. Tenga en cuenta que las descargas de CSV no incluirán campos generales.

Modelos

Etiquetas provisionales y activas

Para facilitar el uso con integraciones, una versión del modelo puede etiquetarse como staging o live en la interfaz de usuario de Communications Mining™. Esta etiqueta se puede proporcionar a las solicitudes de la API Predecir en lugar del número de versión del modelo. Esto permite que tu integración obtenga predicciones de cualquier versión del modelo a la que apunte la etiqueta Staging o Live, que los usuarios de la plataforma pueden gestionar fácilmente desde la interfaz de usuario de Communications Mining.

Detalles de la versión del modelo

Los detalles sobre una versión de modelo específica se pueden obtener utilizando el punto final de la API de validación.

Además, las respuestas a las solicitudes de predicción contienen información sobre el modelo que se utilizó para realizar las predicciones.

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

Nombre	Tipo	Descripción
time	Marca de tiempo	Cuándo se fijó la versión del modelo.
version	Número	Versión del modelo.