Tutorial de la API

Esta es una introducción de estilo tutorial a la API: vaya directamente a la referencia si sabe lo que está buscando.

Todos los datos, cuyas partes individuales se denominan mensajes, se agrupan en orígenes. Una fuente debe corresponder al origen de los datos, como un único buzón o un canal de comentarios en particular. Estos pueden combinarse para los propósitos de un único modelo de inferencia, por lo que es mejor pecar de múltiples fuentes diferentes que de un único monolito si tienes alguna duda.

Un conjunto de datos es una combinación de fuentes junto con las categorías de etiquetas asociadas. Por ejemplo, un conjunto de datos puede crearse a partir de una fuente de comentarios de un sitio web, con etiquetas como Facilidad de uso o Información disponible, mientras que un conjunto de datos diferente podría basarse en varias fuentes de respuesta a encuestas posteriores a la compra y aplicar etiquetas completamente diferentes sobre Empaquetado o Velocidad de entrega.

Así que antes de añadir cualquier comentario, debes crear una fuente para ponerlos.

Crear un ejemplo de origen

Bash

curl -X PUT 'https://<my_api_endpoint>/api/v1/sources/<project>/example' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "source": {
    "description": "An optional long form description.",
    "title": "An Example Source"
  }
}'

Nodo

const request = require("request");

request.put(
  {
    url: "https://<my_api_endpoint>/api/v1/sources/<project>/example",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
    json: true,
    body: {
      source: {
        description: "An optional long form description.",
        title: "An Example Source",
      },
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.put(
    "https://<my_api_endpoint>/api/v1/sources/<project>/example",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
    json={
        "source": {
            "title": "An Example Source",
            "description": "An optional long form description.",
        }
    },
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Respuesta

{
  "source": {
    "created_at": "2018-10-16T10:43:56.463000Z",
    "description": "An optional long form description.",
    "id": "22f0f76e82fd8867",
    "language": "en",
    "last_modified": "2018-10-16T10:43:56.463000Z",
    "name": "example",
    "owner": "<project>",
    "sensitive_properties": [],
    "should_translate": false,
    "title": "An Example Source",
    "updated_at": "2018-10-16T10:43:56.463000Z"
  },
  "status": "ok"
}

Para crear un origen necesitas lo siguiente:

1. Un proyecto : un proyecto existente del que formas parte.
2. Un nombre : los caracteres alfanuméricos, los guiones y los guiones bajos están bien (p. ej. 'post-compra').
3. Un título : un título corto legible por humanos para que tu fuente se muestre en la interfaz de usuario, por ejemplo, Respuestas a la encuesta posteriores a la compra.
4. Una descripción : opcionalmente, una descripción de formulario más larga del origen para mostrar en la página de descripción general de los orígenes.

Los dos primeros forman el nombre completo de tu origen, que se utiliza para referirse a él mediante programación. Los dos últimos están destinados al consumo humano en la interfaz de usuario.

Continúa con la creación de un origen de ejemplo.

Consulte su página de fuentes y luego vuelva.

Ejemplo de lista de fuentes

Recuperemos mediante programación la misma información disponible en la página de fuentes con todos los metadatos para todas las fuentes. Deberías ver tu origen.

Bash

curl -X GET 'https://<my_api_endpoint>/api/v1/sources' \
    -H "Authorization: Bearer $REINFER_TOKEN"

Nodo

const request = require("request");

request.get(
  {
    url: "https://<my_api_endpoint>/api/v1/sources",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.get(
    "https://<my_api_endpoint>/api/v1/sources",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Respuesta

{
  "sources": [
    {
      "created_at": "2018-10-16T10:43:56.463000Z",
      "description": "An optional long form description.",
      "id": "22f0f76e82fd8867",
      "language": "en",
      "last_modified": "2018-10-16T10:43:56.463000Z",
      "name": "example",
      "owner": "<project>",
      "sensitive_properties": [],
      "should_translate": false,
      "title": "An Example Source",
      "updated_at": "2018-10-16T10:43:56.463000Z"
    }
  ],
  "status": "ok"
}

Si solo quieres que las fuentes pertenezcan a un proyecto específico, puedes añadir su nombre al punto final.

Eliminar un ejemplo de origen

Al eliminar una fuente, se destruyen irremediablemente todos los mensajes y cualquier otra información asociada a ella. Cualquier conjunto de datos que utilice esta fuente también perderá los datos de entrenamiento proporcionados por cualquier etiqueta que se haya añadido a los mensajes en esta fuente, por lo que este punto final debe utilizarse con precaución. Dicho esto, debería ser seguro eliminar la fuente que creamos para tu proyecto en la sección anterior.

Bash

curl -X DELETE 'https://<my_api_endpoint>/api/v1/sources/id:22f0f76e82fd8867' \
    -H "Authorization: Bearer $REINFER_TOKEN"

Nodo

const request = require("request");

request.delete(
  {
    url: "https://<my_api_endpoint>/api/v1/sources/id:22f0f76e82fd8867",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.delete(
    "https://<my_api_endpoint>/api/v1/sources/id:22f0f76e82fd8867",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Respuesta

{
  "status": "ok"
}

La respuesta debe ser {"status": "ok"}. Para asegurarse de que haya desaparecido, puede volver a solicitar todas las fuentes.

Bash

curl -X GET 'https://<my_api_endpoint>/api/v1/sources' \
    -H "Authorization: Bearer $REINFER_TOKEN"

Nodo

const request = require("request");

request.get(
  {
    url: "https://<my_api_endpoint>/api/v1/sources",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.get(
    "https://<my_api_endpoint>/api/v1/sources",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Respuesta

{
  "sources": [],
  "status": "ok"
}

Ejemplo de añadir comentarios

Las fuentes serían inútiles sin los comentarios que van en ellas. Un comentario en Communications Mining™ es un fragmento de texto individual o varios elementos de texto que se combinan en una conversación. Ejemplos de lo primero incluyen respuestas a encuestas, tickets de soporte y reseñas de clientes, mientras que ejemplos de lo segundo incluyen cadenas de correo electrónico.

Añadiremos un par de comentarios al origen de ejemplo creado en la sección anterior:

Añadir correos electrónicos

Bash

curl -X POST 'https://<my_api_endpoint>/api/v1/sources/<project>/example/sync' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "comments": [
    {
      "id": "0123456789abcdef",
      "messages": [
        {
          "body": {
            "text": "Hi Bob,\n\nCould you send me today'"'"'s figures?\n\nThanks,\nAlice"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-11T11:02:03.000000+00:00",
          "to": [
            "[e-mail]"
          ]
        },
        {
          "body": {
            "text": "Alice,\n\nHere are the figures for today.\n\nRegards,\nBob"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-11T11:05:10.000000+00:00",
          "to": [
            "[e-mail]"
          ]
        },
        {
          "body": {
            "text": "Hi Bob,\n\nI think these are the wrong numbers - could you check?\n\nThanks again,\nAlice"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-11T11:18:43.000000+00:00",
          "to": [
            "[e-mail]"
          ]
        }
      ],
      "timestamp": "2011-12-11T01:02:03.000000+00:00"
    },
    {
      "id": "abcdef0123456789",
      "messages": [
        {
          "body": {
            "text": "All,\n\nJust to let you know that processing is running late today.\n\nRegards,\nBob"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-12T10:04:30.000000+00:00",
          "to": [
            "[e-mail]",
            "[e-mail]"
          ]
        },
        {
          "body": {
            "text": "Hi Bob,\n\nCould you estimate when you'"'"'ll be finished?\n\nThanks,\nCarol"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-12T10:06:22.000000+00:00",
          "to": [
            "[e-mail]",
            "[e-mail]"
          ]
        },
        {
          "body": {
            "text": "Carol,\n\nWe should be done by 12pm. Sorry about the delay.\n\nBest,\nBob"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-11T10:09:40.000000+00:00",
          "to": [
            "[e-mail]",
            "[e-mail]"
          ]
        }
      ],
      "timestamp": "2011-12-11T02:03:04.000000+00:00",
      "user_properties": {
        "number:severity": 3,
        "string:Recipient Domain": "company.com",
        "string:Sender Domain": "organisation.org"
      }
    }
  ]
}'

Nodo

const request = require("request");

request.post(
  {
    url: "https://<my_api_endpoint>/api/v1/sources/<project>/example/sync",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
    json: true,
    body: {
      comments: [
        {
          id: "0123456789abcdef",
          messages: [
            {
              body: {
                text: "Hi Bob,\n\nCould you send me today's figures?\n\nThanks,\nAlice",
              },
              from: "[e-mail]",
              sent_at: "2011-12-11T11:02:03.000000+00:00",
              to: ["[e-mail]"],
            },
            {
              body: {
                text: "Alice,\n\nHere are the figures for today.\n\nRegards,\nBob",
              },
              from: "[e-mail]",
              sent_at: "2011-12-11T11:05:10.000000+00:00",
              to: ["[e-mail]"],
            },
            {
              body: {
                text: "Hi Bob,\n\nI think these are the wrong numbers - could you check?\n\nThanks again,\nAlice",
              },
              from: "[e-mail]",
              sent_at: "2011-12-11T11:18:43.000000+00:00",
              to: ["[e-mail]"],
            },
          ],
          timestamp: "2011-12-11T01:02:03.000000+00:00",
        },
        {
          id: "abcdef0123456789",
          messages: [
            {
              body: {
                text: "All,\n\nJust to let you know that processing is running late today.\n\nRegards,\nBob",
              },
              from: "[e-mail]",
              sent_at: "2011-12-12T10:04:30.000000+00:00",
              to: ["[e-mail]", "[e-mail]"],
            },
            {
              body: {
                text: "Hi Bob,\n\nCould you estimate when you'll be finished?\n\nThanks,\nCarol",
              },
              from: "[e-mail]",
              sent_at: "2011-12-12T10:06:22.000000+00:00",
              to: ["[e-mail]", "[e-mail]"],
            },
            {
              body: {
                text: "Carol,\n\nWe should be done by 12pm. Sorry about the delay.\n\nBest,\nBob",
              },
              from: "[e-mail]",
              sent_at: "2011-12-11T10:09:40.000000+00:00",
              to: ["[e-mail]", "[e-mail]"],
            },
          ],
          timestamp: "2011-12-11T02:03:04.000000+00:00",
          user_properties: {
            "number:severity": 3,
            "string:Recipient Domain": "company.com",
            "string:Sender Domain": "organisation.org",
          },
        },
      ],
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.post(
    "https://<my_api_endpoint>/api/v1/sources/<project>/example/sync",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
    json={
        "comments": [
            {
                "id": "0123456789abcdef",
                "timestamp": "2011-12-11T01:02:03.000000+00:00",
                "messages": [
                    {
                        "from": "[e-mail]",
                        "to": ["[e-mail]"],
                        "sent_at": "2011-12-11T11:02:03.000000+00:00",
                        "body": {
                            "text": "Hi Bob,\n\nCould you send me today's figures?\n\nThanks,\nAlice"
                        },
                    },
                    {
                        "from": "[e-mail]",
                        "to": ["[e-mail]"],
                        "sent_at": "2011-12-11T11:05:10.000000+00:00",
                        "body": {
                            "text": "Alice,\n\nHere are the figures for today.\n\nRegards,\nBob"
                        },
                    },
                    {
                        "from": "[e-mail]",
                        "to": ["[e-mail]"],
                        "sent_at": "2011-12-11T11:18:43.000000+00:00",
                        "body": {
                            "text": "Hi Bob,\n\nI think these are the wrong numbers - could you check?\n\nThanks again,\nAlice"
                        },
                    },
                ],
            },
            {
                "id": "abcdef0123456789",
                "timestamp": "2011-12-11T02:03:04.000000+00:00",
                "messages": [
                    {
                        "from": "[e-mail]",
                        "to": ["[e-mail]", "[e-mail]"],
                        "sent_at": "2011-12-12T10:04:30.000000+00:00",
                        "body": {
                            "text": "All,\n\nJust to let you know that processing is running late today.\n\nRegards,\nBob"
                        },
                    },
                    {
                        "from": "[e-mail]",
                        "to": ["[e-mail]", "[e-mail]"],
                        "sent_at": "2011-12-12T10:06:22.000000+00:00",
                        "body": {
                            "text": "Hi Bob,\n\nCould you estimate when you'll be finished?\n\nThanks,\nCarol"
                        },
                    },
                    {
                        "from": "[e-mail]",
                        "to": ["[e-mail]", "[e-mail]"],
                        "sent_at": "2011-12-11T10:09:40.000000+00:00",
                        "body": {
                            "text": "Carol,\n\nWe should be done by 12pm. Sorry about the delay.\n\nBest,\nBob"
                        },
                    },
                ],
                "user_properties": {
                    "string:Sender Domain": "organisation.org",
                    "string:Recipient Domain": "company.com",
                    "number:severity": 3,
                },
            },
        ]
    },
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Respuesta

null

Este ejemplo muestra cómo añadir un comentario que consta de varios mensajes. Esto se usa más comúnmente para agregar correos electrónicos.

Los campos utilizados en las solicitudes en el código adjunto deben explicarse por sí mismos. Los únicos campos obligatorios son id, timestamp y messages.body.text. Puedes obtener más información sobre los campos disponibles en la Referencia de comentarios.

El campo ID debe ser un número hexadecimal, único entre los comentarios, de 256 dígitos como máximo. De lo contrario, se deja que el usuario de la API elija, lo que permite una integración más fácil con otros sistemas. Si tus ID no son hexadecimales, puedes convertirlos. Si además quieres conservar los ID originales, puedes ponerlos en el campo user_properties que contiene metadatos arbitrarios definidos por el usuario.

La marca de tiempo debe estar en UTC y referirse a la hora en que se grabó el comentario, por ejemplo, se respondió a la encuesta, no a la hora actual.

La respuesta debe confirmar que se han creado dos nuevos comentarios.

Añadir comentarios de un solo mensaje

Bash

curl -X POST 'https://<my_api_endpoint>/api/v1/sources/<project>/example/sync' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "comments": [
    {
      "id": "fedcba098765",
      "messages": [
        {
          "body": {
            "text": "I was impressed with the speed of your service, but the price is quite high.",
            "translated_from": "J'"'"'ai \u00e9t\u00e9 impressionn\u00e9 par la rapidit\u00e9 de votre service, mais le prix est assez \u00e9lev\u00e9."
          },
          "language": "fr"
        }
      ],
      "timestamp": "2011-12-12T20:00:00.000000+00:00"
    }
  ]
}'

Nodo

const request = require("request");

request.post(
  {
    url: "https://<my_api_endpoint>/api/v1/sources/<project>/example/sync",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
    json: true,
    body: {
      comments: [
        {
          id: "fedcba098765",
          messages: [
            {
              body: {
                text: "I was impressed with the speed of your service, but the price is quite high.",
                translated_from:
                  "J'ai \u00e9t\u00e9 impressionn\u00e9 par la rapidit\u00e9 de votre service, mais le prix est assez \u00e9lev\u00e9.",
              },
              language: "fr",
            },
          ],
          timestamp: "2011-12-12T20:00:00.000000+00:00",
        },
      ],
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.post(
    "https://<my_api_endpoint>/api/v1/sources/<project>/example/sync",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
    json={
        "comments": [
            {
                "id": "fedcba098765",
                "timestamp": "2011-12-12T20:00:00.000000+00:00",
                "messages": [
                    {
                        "language": "fr",
                        "body": {
                            "text": "I was impressed with the speed of your service, but the price is quite high.",
                            "translated_from": "J'ai été impressionné par la rapidité de votre service, mais le prix est assez élevé.",
                        },
                    }
                ],
            }
        ]
    },
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Respuesta

{
  "new": 1,
  "status": "ok",
  "unchanged": 0,
  "updated": 0
}

Este ejemplo muestra cómo añadir un comentario que contiene un solo mensaje. Este formato puede adaptarse a datos como respuestas a encuestas, reseñas de clientes, etc.

Los campos obligatorios y disponibles son los mismos que en el ejemplo de los correos electrónicos, con la única diferencia de que el campo Mensajes debe contener una sola entrada. Puedes omitir los campos específicos del correo electrónico que no se ajusten a tus datos, ya que no son obligatorios.

La respuesta debe confirmar que se ha creado un nuevo comentario.

Ejemplo de recuperación de comentarios

Una vez añadido, un comentario puede recuperarse por su ID. Deberías fijarte en el comentario añadido en la sección anterior.

Bash

curl -X GET 'https://<my_api_endpoint>/api/v1/sources/<project>/example/comments/0123456789abcdef' \
    -H "Authorization: Bearer $REINFER_TOKEN"

Nodo

const request = require("request");

request.get(
  {
    url: "https://<my_api_endpoint>/api/v1/sources/<project>/example/comments/0123456789abcdef",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.get(
    "https://<my_api_endpoint>/api/v1/sources/<project>/example/comments/0123456789abcdef",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Respuesta

{
  "comment": {
    "context": "0",
    "id": "0123456789abcdef",
    "last_modified": "2018-10-16T10:51:46.247000Z",
    "messages": [
      {
        "body": {
          "text": "Hi Bob,\n\nCould you send me today's figures?\n\nThanks,\nAlice"
        },
        "from": "[e-mail]",
        "sent_at": "2011-12-11T11:02:03.000000+00:00",
        "to": ["[e-mail]"]
      },
      {
        "body": {
          "text": "Alice,\n\nHere are the figures for today.\n\nRegards,\nBob"
        },
        "from": "[e-mail]",
        "sent_at": "2011-12-11T11:05:10.000000+00:00",
        "to": ["[e-mail]"]
      },
      {
        "body": {
          "text": "Hi Bob,\n\nI think these are the wrong numbers - could you check?\n\nThanks again,\nAlice"
        },
        "from": "[e-mail]",
        "sent_at": "2011-12-11T11:18:43.000000+00:00",
        "to": ["[e-mail]"]
      }
    ],
    "source_id": "22f0f76e82fd8867",
    "text_format": "plain",
    "timestamp": "2011-12-11T01:02:03Z",
    "uid": "22f0f76e82fd8867.0123456789abcdef",
    "user_properties": {}
  },
  "status": "ok"
}

Crear un ejemplo de conjunto de datos

Después de haber añadido con éxito algunos datos sin procesar a Communications Mining™, ahora podemos empezar a añadir conjuntos de datos. Un conjunto de datos corresponde a una taxonomía de etiquetas junto con los datos de entrenamiento proporcionados al aplicar esas etiquetas a los mensajes en una serie de fuentes seleccionadas. Puedes crear muchos conjuntos de datos que hagan referencia a la misma fuente sin que el acto de etiquetar mensajes utilizando la taxonomía de un conjunto de datos tenga ningún impacto en los otros conjuntos de datos, o en las fuentes subyacentes, lo que permite que diferentes equipos utilicen Communications Mining para recopilar información de forma independiente.

Bash

curl -X PUT 'https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "dataset": {
    "description": "An optional long form description.",
    "source_ids": [
      "22f0f76e82fd8867"
    ],
    "title": "An Example Dataset"
  }
}'

Nodo

const request = require("request");

request.put(
  {
    url: "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
    json: true,
    body: {
      dataset: {
        description: "An optional long form description.",
        source_ids: ["22f0f76e82fd8867"],
        title: "An Example Dataset",
      },
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.put(
    "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
    json={
        "dataset": {
            "title": "An Example Dataset",
            "description": "An optional long form description.",
            "source_ids": ["22f0f76e82fd8867"],
        }
    },
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Respuesta

{
  "dataset": {
    "created": "2018-10-16T10:57:44.667000Z",
    "description": "An optional long form description.",
    "has_sentiment": true,
    "id": "b2ad67f9dfd2e76b",
    "last_modified": "2018-10-16T10:57:44.667000Z",
    "limited_access": false,
    "model_family": "english",
    "name": "my-dataset",
    "owner": "<project>",
    "source_ids": ["22f0f76e82fd8867"],
    "title": "An Example Dataset"
  },
  "status": "ok"
}

Una vez creadas las fuentes, los usuarios con los permisos adecuados también pueden crear conjuntos de datos en la IU, lo que puede resultar más cómodo.

Ejemplo de enumerar conjuntos de datos

Bash

curl -X GET 'https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset' \
    -H "Authorization: Bearer $REINFER_TOKEN"

Nodo

const request = require("request");

request.get(
  {
    url: "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.get(
    "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Respuesta

{
  "dataset": {
    "created": "2018-10-16T10:57:44.667000Z",
    "description": "An optional long form description.",
    "has_sentiment": true,
    "id": "b2ad67f9dfd2e76b",
    "last_modified": "2018-10-16T10:57:44.667000Z",
    "limited_access": false,
    "model_family": "random",
    "name": "my-dataset",
    "owner": "<project>",
    "source_ids": ["22f0f76e82fd8867"],
    "title": "An Example Dataset"
  },
  "status": "ok"
}

Al igual que las fuentes, los conjuntos de datos tienen varias rutas GET correspondientes a:

• todos los conjuntos de datos a los que el usuario tiene acceso;
• conjuntos de datos pertenecientes al proyecto especificado;
• un único conjunto de datos especificado por proyecto y nombre.

Proporcionamos un ejemplo de esto último en acción.

Actualizar un ejemplo de conjunto de datos

Todos los campos permitidos utilizados para crear un conjunto de datos pueden actualizarse, con la excepción de has_sentiment, que es fijo para un conjunto de datos determinado.

Bash

curl -X POST 'https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "dataset": {
    "description": "An updated description."
  }
}'

Nodo

const request = require("request");

request.post(
  {
    url: "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
    json: true,
    body: { dataset: { description: "An updated description." } },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.post(
    "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
    json={"dataset": {"description": "An updated description."}},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Respuesta

{
  "dataset": {
    "created": "2018-10-16T10:57:44.667000Z",
    "description": "An updated description.",
    "has_sentiment": true,
    "id": "b2ad67f9dfd2e76b",
    "last_modified": "2018-10-16T10:57:44.667000Z",
    "limited_access": false,
    "model_family": "random",
    "name": "my-dataset",
    "owner": "<project>",
    "source_ids": ["22f0f76e82fd8867"],
    "title": "An Example Dataset"
  },
  "status": "ok"
}

Ejemplo de eliminación de un conjunto de datos

Al eliminar un conjunto de datos, se eliminará por completo la taxonomía asociada, así como todas las etiquetas que se hayan aplicado a sus orígenes. Ya no podrás obtener predicciones basadas en esta taxonomía y tendrás que iniciar el proceso de entrenamiento de anotar mensajes desde el principio para revertir esta operación, así que utilízalo con cuidado.

Bash

curl -X DELETE 'https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset' \
    -H "Authorization: Bearer $REINFER_TOKEN"

Nodo

const request = require("request");

request.delete(
  {
    url: "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.delete(
    "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Respuesta

{
  "status": "ok"
}

Ejemplo de obtener predicciones de un modelo anclado

Bash

curl -X POST 'https://<my_api_endpoint>/api/v1/datasets/<project>/<dataset>/labellers/<model_version>/predict' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "documents": [
    {
      "messages": [
        {
          "body": {
            "text": "Hi Bob, has my trade settled yet? Thanks, Alice"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-11T11:02:03.000000+00:00",
          "subject": {
            "text": "Trade Ref: 8726387 Settlement"
          },
          "to": [
            "[e-mail]"
          ]
        }
      ],
      "user_properties": {
        "number:Deal Value": 12000,
        "string:City": "London"
      }
    },
    {
      "messages": [
        {
          "body": {
            "text": "All, just to let you know that processing is running late today. Regards, Bob"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-12T10:04:30.000000+00:00",
          "subject": {
            "text": "Trade Processing Delay"
          },
          "to": [
            "[e-mail]",
            "[e-mail]"
          ]
        }
      ],
      "user_properties": {
        "number:Deal Value": 4.9,
        "string:City": "Luton"
      }
    }
  ],
  "labels": [
    {
      "name": [
        "Trade",
        "Settlement"
      ],
      "threshold": 0.8
    },
    {
      "name": [
        "Delay"
      ],
      "threshold": 0.75
    }
  ],
  "threshold": 0
}'

Nodo

const request = require("request");

request.post(
  {
    url: "https://<my_api_endpoint>/api/v1/datasets/<project>/<dataset>/labellers/<model_version>/predict",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
    json: true,
    body: {
      documents: [
        {
          messages: [
            {
              body: { text: "Hi Bob, has my trade settled yet? Thanks, Alice" },
              from: "[e-mail]",
              sent_at: "2011-12-11T11:02:03.000000+00:00",
              subject: { text: "Trade Ref: 8726387 Settlement" },
              to: ["[e-mail]"],
            },
          ],
          user_properties: {
            "number:Deal Value": 12000,
            "string:City": "London",
          },
        },
        {
          messages: [
            {
              body: {
                text: "All, just to let you know that processing is running late today. Regards, Bob",
              },
              from: "[e-mail]",
              sent_at: "2011-12-12T10:04:30.000000+00:00",
              subject: { text: "Trade Processing Delay" },
              to: ["[e-mail]", "[e-mail]"],
            },
          ],
          user_properties: { "number:Deal Value": 4.9, "string:City": "Luton" },
        },
      ],
      labels: [
        { name: ["Trade", "Settlement"], threshold: 0.8 },
        { name: ["Delay"], threshold: 0.75 },
      ],
      threshold: 0,
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.post(
    "https://<my_api_endpoint>/api/v1/datasets/<project>/<dataset>/labellers/<model_version>/predict",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
    json={
        "documents": [
            {
                "messages": [
                    {
                        "body": {
                            "text": "Hi Bob, has my trade settled yet? Thanks, Alice"
                        },
                        "subject": {"text": "Trade Ref: 8726387 Settlement"},
                        "from": "[e-mail]",
                        "sent_at": "2011-12-11T11:02:03.000000+00:00",
                        "to": ["[e-mail]"],
                    }
                ],
                "user_properties": {
                    "number:Deal Value": 12000,
                    "string:City": "London",
                },
            },
            {
                "messages": [
                    {
                        "body": {
                            "text": "All, just to let you know that processing is running late today. Regards, Bob"
                        },
                        "subject": {"text": "Trade Processing Delay"},
                        "from": "[e-mail]",
                        "sent_at": "2011-12-12T10:04:30.000000+00:00",
                        "to": ["[e-mail]", "[e-mail]"],
                    }
                ],
                "user_properties": {
                    "number:Deal Value": 4.9,
                    "string:City": "Luton",
                },
            },
        ],
        "labels": [
            {"name": ["Trade", "Settlement"], "threshold": 0.8},
            {"name": ["Delay"], "threshold": 0.75},
        ],
        "threshold": 0,
    },
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Respuesta

{
  "entities": [
    [
      {
        "formatted_value": "2019-01-01 00:00 UTC",
        "kind": "date",
        "span": {
          "content_part": "body",
          "message_index": 0,
          "utf16_byte_end": 120,
          "utf16_byte_start": 94
        }
      },
      {
        "formatted_value": "Bob",
        "kind": "person",
        "span": {
          "content_part": "body",
          "message_index": 0,
          "utf16_byte_end": 6,
          "utf16_byte_start": 12
        }
      }
    ],
    []
  ],
  "model": {
    "time": "2018-12-20T15:05:43.906000Z",
    "version": "1"
  },
  "predictions": [
    [
      {
        "name": ["Trade", "Settlement"],
        "probability": 0.8668700814247131
      }
    ],
    [
      {
        "name": ["Delay"],
        "probability": 0.26687008142471313
      }
    ]
  ],
  "status": "ok"
}

Una vez que tengas un modelo entrenado, puedes utilizar este modelo para predecir etiquetas con respecto a otros datos. Para ello, solo tienes que proporcionar lo siguiente:

1. Documentos : una matriz de datos de mensaje para los que el modelo predecirá etiquetas y cada objeto de mensaje solo puede contener un mensaje junto con cualquier propiedad opcional. Para un rendimiento óptimo del modelo, los datos proporcionados deben ser coherentes con los datos y el formato que se anotó en la plataforma, ya que el modelo tiene en cuenta todos los datos y metadatos disponibles. Por ejemplo, los correos electrónicos deben incluir los campos Asunto, De, Bcc, Cc, etc., si estuvieran presentes en los datos de entrenamiento. Además, las propiedades del usuario en el conjunto de datos de entrenamiento también deben incluirse en el cuerpo de la solicitud de la API.
2. Etiquetas : una matriz de las etiquetas entrenadas del modelo que quieres que el modelo prediga en los datos proporcionados. Además, para cada etiqueta se debe proporcionar un umbral de confianza por el que filtrar las etiquetas. El umbral óptimo puede decidirse en función del equilibrio entre precisión y recuperación. Puedes encontrar más información sobre cómo elegir un umbral en la guía del usuario, en la sección Usar validación.
3. Umbral predeterminado (opcional) : un valor de umbral predeterminado que se aplicará en todas las etiquetas proporcionadas. Ten en cuenta que si los umbrales predeterminados y por etiqueta se proporcionan juntos en una solicitud, los umbrales por etiqueta anularán el umbral predeterminado. Como práctica recomendada, los umbrales predeterminados pueden utilizarse para probar o explorar datos. Para obtener resultados óptimos al utilizar predicciones para la toma de decisiones automatizada, se recomienda encarecidamente utilizar umbrales por etiqueta.

Nota: Una etiqueta jerárquica tendrá el formato de una lista de etiquetas. Por ejemplo, la etiqueta "Trade > Settlements" tendrá el formato ["Trade", "Settlements"] en la solicitud.

Dentro de la URL de la API es importante pasar los siguientes argumentos:

1. Nombre del proyecto : un proyecto existente del que formas parte.
2. Nombre del conjunto de datos : un conjunto de datos en el que se ha entrenado el modelo.
3. Versión del modelo : la versión del modelo es un número que se puede encontrar en la página Modelos para el conjunto de datos elegido.

Comprender la respuesta

Como se está utilizando una versión de modelo específica, la respuesta a la misma solicitud siempre devolverá los mismos resultados, incluso si el modelo se sigue entrenando. Una vez que haya validado los resultados del nuevo modelo y desee enviar una solicitud contra el nuevo modelo, debe actualizar la versión del modelo en su solicitud. Además, también debes actualizar los umbrales de la etiqueta para que se ajusten al nuevo modelo. Para cada nuevo modelo tendrás que iterar los pasos de nuevo.

De forma predeterminada, la respuesta siempre proporcionará una lista de etiquetas previstas para cada mensaje con una confianza superior a los niveles de umbral proporcionados.

Sin embargo, la respuesta de una solicitud puede variar si el reconocimiento de entidades y los sentimientos están habilitados para tu modelo:

1. Campos generales habilitados : la respuesta también proporcionará una lista de campos generales que se han identificado para cada etiqueta (ejemplo de primera respuesta)
2. Sentimientos habilitados : la respuesta también proporcionará una puntuación de sentimiento entre -1 (completamente negativa) y 1 (completamente positiva) a cada objeto de etiqueta clasificado por encima del umbral de confianza. (segundo ejemplo de respuesta)

{
  "model": { "time": "2018-12-20T15:05:43.906000Z", "version": "1" },
  "predictions": [
    [
      {
        "name": ["Trade", "Settlement"],
        "probability": 0.86687008142471313,
        "sentiment": 0.8762539502232571
      }
    ],
    [
      {
        "name": ["Delay"],
        "probability": 0.26687008142471313,
        "sentiment": 0.8762539502232571
      }
    ]
  ],
  "status": "ok"
}