Tutorial da API

Esta é uma introdução ao estilo tutorial para a API — vá direto para a referência se você souber o que estiver procurando.

Todos os dados, dos quais partes individuais são chamadas de mensagens, são agrupados em origens. Uma origem deve corresponder à origem dos dados, como uma única caixa de correio ou um canal de feedback específico. Eles podem ser combinados para fins de um único modelo de inferência; portanto, é melhor optar por várias fontes diferentes do que um único monitor se você tiver alguma dúvida.

Um conjunto de dados é uma combinação de origens junto com as categorias de rótulos associadas. Por exemplo, um conjunto de dados pode ser criado com base em uma fonte de feedback de um site, com rótulos como Facilidade de uso ou Informação disponível, enquanto um conjunto de dados diferente pode se basear em várias fontes de resposta de pesquisas pós-compra e aplicar rótulos completamente diferentes sobre Pacote ou Velocidade de entrega.

Portanto, antes de adicionar quaisquer comentários, você precisa criar uma origem para colocá-los.

Criar um exemplo de origem

• 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"
    }
  }'

• Nó

  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))

• Resposta

  {
    "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 criar uma origem, você precisa de quatro coisas:

1. Um projeto. Este é um projeto existente do qual você faz parte.
2. Um nome. Caracteres alfanuméricos, hifens e sublinhados estão todos OK (por exemplo, 'após-compra').
3. Um título. Um título curto, legível por humanos para que sua fonte seja exibido na interface gráfica (por exemplo, 'Respostas à pesquisa pós-compra').
4. Uma descrição. Opcionalmente, uma descrição de formulário mais longa da origem para exibir na página de visão geral das fontes.

Os dois primeiros formam o nome "totalmente qualificado" da sua origem, que é usado para se referir a ela programaticamente. Os dois últimos são destinados ao consumo humano na interface do usuário.

Vá em frente e crie uma origem example .

Você agora é o proprietário de uma origem! Verifique sua página de origens e depois volte.

Exemplo de fontes de lista

Vamos recuperar programaticamente as mesmas informações disponíveis na página fontes com todos os metadados para todas as fontes. Você deve ver sua origem.

• Bash

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

• Nó

  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))

• Resposta

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

Se você quiser apenas as fontes que pertencem a um projeto específico, você pode adicionar seu nome ao ponto de extremidade.

Excluir um exemplo de origem

Excluir uma origem consome todas as mensagens e outras informações associadas a ela de maneira irrecuperável. Quaisquer conjuntos de dados que usam essa origem também perderão os dados de treinamento fornecidos por quaisquer rótulos que foram adicionados a mensagens nesta origem. Portanto, esse ponto de extremidade deve ser usado com cuidado. Dito isso, deve ser seguro excluir a origem que criamos para o seu projeto na seção anterior.

• Bash

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

• Nó

  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))

• Resposta

  {
    "status": "ok"
  }

A resposta deve ser {"status": "ok"}. Para ter certeza de que tudo acabou, você pode solicitar todas as fontes novamente.

• Bash

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

• Nó

  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))

• Resposta

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

Exemplo de como adicionar comentários

As fontes seriam inúteis sem os comentários que vão nelas. Um comentário no Communications Mining é uma parte individual de texto ou vários itens de texto que são combinados em uma conversa. Exemplos do primeiro incluem respostas a pesquisas, tickets de suporte e avaliações de clientes, enquanto que exemplos do último incluem cadeias de e-mail.

Continuaremos e adicionaremos alguns comentários à fonte "exemplo" criada na seção anterior.

Adicionando emails

• 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"
        }
      }
    ]
  }'

• Nó

  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))

• Resposta

  null

Este exemplo mostra como adicionar um comentário que consiste em várias mensagens. É mais comumente usado para adicionar emails.

Os campos usados nas solicitações no código de acompanhamento devem ser autoexplicativos. Os únicos campos obrigatórios são id, timestamp e messages.body.text. Você pode saber mais sobre os campos disponíveis na Referência de comentários.

O campo ID deve ter um número hexadecimal, único entre comentários, com no máximo 256 dígitos. Caso contrário, é deixado para o usuário da API escolher, permitindo uma integração mais fácil com outros sistemas. Se seus IDs não forem hexadecimais, você pode convertê-los. Se você quiser reter adicionalmente os IDs originais, você pode colocá-los no campo user_properties que contém metadados arbitrários definidos pelo usuário.

O carimbo de data/hora deve estar em UTC e se referir à hora em que o comentário foi gravado (por exemplo, a pesquisa foi respondida), não à hora atual.

A resposta deve confirmar que dois novos comentários foram criados.

Adicionando comentários de mensagem única

• 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"
      }
    ]
  }'

• Nó

  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))

• Resposta

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

Este exemplo mostra como adicionar um comentário que contém uma única mensagem. Esse formato pode ser adequado para dados como respostas a pesquisas, avaliações de clientes etc.

Os campos obrigatórios e disponíveis são os mesmos que no exemplo de e-mails, com a única diferença que o campo messages deve conter uma única entrada. Você pode ignorar campos específicos de e-mail que não sejam compatíveis com seus dados, pois eles não são necessários.

A resposta deve confirmar que um novo comentário foi criado.

Exemplo de recuperação de comentários

Depois de adicionado, um comentário pode ser recuperado por seu ID. Você deve ver o comentário adicionado na seção anterior.

• Bash

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

• Nó

  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))

• Resposta

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

Criar um exemplo de conjunto de dados

Após adicionar com sucesso alguns dados brutos ao Communications Mining, agora podemos começar a adicionar conjuntos de dados. Um conjunto de dados corresponde a uma taxonomia de rótulos juntamente com os dados de treinamento fornecidos aplicando esses rótulos às mensagens em uma série de origens selecionadas. Você pode criar muitos conjuntos de dados que se referem à(s) mesma(s) origem(s) sem que o fato de rotular mensagens usando a taxonomia de um conjunto de dados tenha qualquer impacto sobre os outros conjuntos de dados (ou as origens subjacentes), permitindo que diferentes equipes usem o Communications Mining para coletar insights de forma independente.

• 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"
    }
  }'

• Nó

  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))

• Resposta

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

Após as origens terem sido criadas, os usuários com permissão adequada também podem criar conjuntos de dados na interface gráfica, o que pode ser mais conveniente.

Exemplo de conjuntos de dados de lista

• Bash

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

• Nó

  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))

• Resposta

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

Como as origens, os conjuntos de dados têm várias rotas GET correspondentes a:

• todos os conjuntos de dados aos quais o usuário tem acesso;
• conjuntos de dados pertencentes ao projeto especificado;
• um único conjunto de dados especificado por projeto e nome.

Fornecemos um exemplo deste último em ação.

Atualize um exemplo de conjunto de dados

Todos os campos permitidos usados para criar um conjunto de dados podem ser atualizados, com exceção de has_sentiment, que é fixo para um determinado conjunto de dados.

• 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."
    }
  }'

• Nó

  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))

• Resposta

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

Excluir um exemplo de conjunto de dados

A exclusão de um conjunto de dados removerá completamente a taxonomia associada, bem como todos os rótulos aplicados às origens. Você não poderá mais receber previsões com base nessa taxonomia e terá que começar o processo de treinamento de rotulagem de mensagens do início para reverter essa operação. Portanto, use-a com cuidado.

• Bash

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

• Nó

  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))

• Resposta

  {
    "status": "ok"
  }

Obter previsões de um exemplo de modelo fixado

• 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
  }'

• Nó

  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))

• Resposta

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

Depois de ter um modelo treinado, agora você pode usar esse modelo para prever rótulos em relação a outros tipos de dados. Para fazê-lo, basta fornecer o seguinte:

1. Documentos: esta é uma matriz de dados de mensagem para a qual o modelo preverá rótulos, e cada objeto de mensagem pode conter apenas uma mensagem junto com quaisquer propriedades opcionais. Para o desempenho ideal do modelo, os dados fornecidos precisam ser consistentes com os dados e o formato rotulados na plataforma, pois o modelo leva em consideração todos os dados e metadados disponíveis. Por exemplo, e-mails devem incluir assunto, campos de/bcc/cc, etc (se estes estiverem presentes nos dados do treinamento). Além disso, as propriedades do usuário no conjunto de dados de treinamento também devem ser incluídas no corpo da solicitação da API.
2. Rótulos: esta é uma matriz dos rótulos treinados do modelo que você deseja que o modelo preveja nos dados fornecidos. Além disso, para cada rótulo deve ser fornecido um limite de confiança para filtrar rótulos. O limite ideal pode ser definido com base em sua contrapartida de precisão versus recall. Mais informações sobre como escolher um limite podem ser encontradas no guia do usuário, na seção "Usando a validação".
3. Limite padrão (opcional): esse é um valor limite padrão que será aplicado a todos os rótulos fornecidos. Observe que, se os limites padrão e por rótulo forem fornecidos juntos em uma solicitação, os limites por rótulo substituirão o limite padrão. Como uma prática recomendada, os limites padrão podem ser usados para testar ou explorar dados. Para obter melhores resultados ao usar previsões para a tomada de decisões automatizadas, é altamente recomendável usar limites por rótulo.

Observação: um rótulo hierárquico será formatado como uma lista de rótulos. Por exemplo, o rótulo "Comercial > Setlements" terá o formato ["Trade", "Setlements"] na solicitação.

Dentro da URL da API, é importante passar os seguintes argumentos:

1. Nome do projeto: este é um projeto existente do qual você faz parte.
2. Nome do conjunto de dados: este é um conjunto de dados no qual o modelo foi treinado.
3. Versão do modelo: a versão do modelo é um número que pode ser encontrado na página "Modelos" do conjunto de dados escolhido.

Entendendo a resposta

Como uma versão específica do modelo está sendo usada, a resposta à mesma solicitação sempre retornará os mesmos resultados, mesmo que o modelo esteja sendo treinado adicionalmente. Depois de validar os resultados do novo modelo e desejar enviar uma solicitação para o novo modelo, você deve atualizar a versão do modelo em sua solicitação. Além disso, você também deve atualizar os limites de rótulo para se adequar ao novo modelo. Para cada novo modelo, você terá que iterar todas as etapas novamente.

Por padrão, a resposta sempre fornecerá uma lista de rótulos previstos para cada mensagem com uma confiança maior do que os níveis de limite fornecidos.

No entanto, a resposta a uma solicitação pode variar se o reconhecimento de entidade e os sentimentos estiverem habilitados para seu modelo:

1. Entidades habilitadas. A resposta também fornecerá uma lista de entidades que foram identificadas para cada rótulo (exemplo da primeira resposta)
2. Sentimentos Habilitados. A resposta também fornecerá uma pontuação de sentimento entre -1 (perfeitamente negativa) e 1 (perfeitamente positiva) para cada objeto de rótulo classificado acima do limite de confiança. (segundo exemplo de resposta)

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