- Documentos de la API
- Introducción
- Información general
- Comentarios
- Etiquetas y campos generales
- Tenants
- Uso de la API
- Tutorial de la API
- Resumen
- Fuentes
- Conjuntos de datos
- Comentarios
- Archivos adjuntos
- Predictions
- Crear una transmisión
- Actualizar una transmisión
- Obtener una transmisión por nombre
- Obtener todas las transmisiones
- Eliminar una transmisión
- Obtener resultados de la transmisión
- Obtener comentarios de una transmisión (heredado)
- Avanzar una transmisión
- Restablecer una transmisión
- Etiquetar una excepción
- Desetiquetar una excepción
- Eventos de auditoría
- Obtener todos los usuarios
- CLI
- Guías de integración
- Blog
- Cómo aprenden las máquinas a entender palabras: una guía para las incrustaciones en PNL
- Aprendizaje basado en solicitudes con Transformers
- Efficient Transformers II: destilación de conocimientos y ajuste
- Transformadores eficientes I: mecanismos de atención
- Modelado de intenciones jerárquico profundo no supervisado: obtener valor sin datos de entrenamiento
- Corrección del sesgo de anotación con Communications Mining
- Aprendizaje activo: mejores modelos ML en menos tiempo
- Todo está en los números: evaluar el rendimiento del modelo con métricas
- Por qué es importante la validación del modelo
- Comparación de Communications Mining y Google AutoML para la inteligencia de datos conversacional
Etiquetas y campos generales
En esta página se 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.
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. Este formato es utilizado por la mayoría de las rutas API. Una excepción es la ruta de exportación de conjuntos 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 (actualmente Predecir rutas) devolverán opcionalmente una lista de nombres de umbral ("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 } ] }
{ "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 } ] }
{ "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"] } ] }
{ "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 | matriz<string> o cadena |
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 | Número | Puntuación de confianza. Un número entre 0.0 y 1.0. |
sentiment | Número | 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. |
P: ¿Cómo puedo descargar etiquetas desde la plataforma Communications Mining?
R: Los siguientes métodos de descarga proporcionan etiquetas: API de Communications Mining, descargas de CSV y 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 elemento de preguntas frecuentes a continuación para obtener 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 comparar.
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 de la API de exportación proporcionan las últimas predicciones disponibles. Ten en cuenta que después de que se haya entrenado una nueva versión del modelo, pero antes de que se hayan vuelto a calcular todas las predicciones, verás una combinación 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 Stream API y Predict API 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 en una versión específica del modelo, y no tuvieran en cuenta 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). |
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.
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 la sección Umbrales de confianza de la guía de integración.
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.
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
}
]
}
{
"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. |
order_number
predicha. Ten en cuenta que, 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": []
}
]
"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. |
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 intervalo, excepto en algunos casos específicos que describimos a continuación.
Cantidad monetaria
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.
$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
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".
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.
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.
capture_ids
contendrá exactamente un ID. En el futuro, la API puede devolver varios ID.
capture_id
será una lista vacía.
P: ¿Cómo puedo descargar campos generales de la plataforma Communications Mining?
R: Los siguientes métodos de descarga proporcionan campos generales: API de Communications Mining y herramienta de línea de comandos de Communications Mining. Consulta la descripción general de Descarga de datos para entender qué método es el adecuado para tu caso de uso. Ten en cuenta que las descargas de CSV no incluirán campos generales.
staging
o live
en la interfaz de usuario de Communications Mining. Esta etiqueta se puede proporcionar a las solicitudes de la API Predict 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.
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"
}
"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. |