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 de correo o un canal de comentarios concreto. Estos pueden combinarse a efectos de un único modelo de inferencia, por lo que es mejor errar por el lado de varias fuentes diferentes que por un solo 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 una fuente necesitas cuatro cosas:

1. Un proyecto. Este es un proyecto existente del que forma 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 agradable, corto y legible para que su fuente se muestre en la interfaz de usuario (p. ej. 'Respuestas a la encuesta posterior a la compra').
4. Una descripción. Opcionalmente, una descripción de formulario más larga de la fuente para mostrar en la página de resumen de fuentes.

Los dos primeros forman el nombre "totalmente cualificado" de tu fuente, que se utiliza para referirse a ella mediante programación. Los dos últimos están destinados al consumo humano en la interfaz de usuario.

Continúe y cree una fuente example .

¡Ahora debería ser el orgulloso propietario de una fuente! Consulta tu página de fuentes y vuelve.

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.

Seguiremos adelante y añadiremos un par de comentarios a la fuente de "ejemplo" creada 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 messages 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ía ver 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 se refieran a las mismas fuentes sin que el acto de etiquetar los mensajes utilizando la taxonomía de un conjunto de datos tenga ningún impacto en los otros conjuntos de datos (o 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: se trata de una matriz de datos de mensajes 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 el asunto, los campos 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: se trata de 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 "Uso de la validación".
3. Umbral predeterminado (opcional): este es un valor de umbral predeterminado que se aplicará a 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: este es un proyecto existente del que forma parte.
2. Nombre del conjunto de datos: este es 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 Habilitado. 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 opinión entre -1 (perfectamente negativa) y 1 (perfectamente 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"
}