API-Tutorial

Dies ist eine Tutorial-Einführung in die API – springen Sie direkt zur Referenz, wenn Sie wissen, wonach Sie suchen.

Alle Daten, von denen einzelne Teile als Nachrichten bezeichnet werden, werden in Quellen gruppiert. Eine Quelle sollte dem Ursprung der Daten entsprechen, z. B. ein einzelnes Postfach oder ein bestimmter Feedbackkanal. Diese können zu einem einzigen Inferenzmodell kombiniert werden, sodass es besser ist, sich auf die Seite mehrerer verschiedener Quellen zu entscheiden, anstatt auf der Seite eines einzelnen Mon lesen, wenn Sie sich unsicher sind.

Ein Dataset ist eine Kombination von Quellen und den zugehörigen Beschriftungskategorien. Beispielsweise kann ein Dataset auf einer Website-Feedbackquelle mit Beschriftungen wie Benutzerfreundlichkeit oder Verfügbare Informationen aufbauen, während ein anderes Dataset auf verschiedenen Quellen für Umfragen nach dem Kauf basieren und völlig unterschiedliche Beschriftungen über Verpackung oder Liefergeschwindigkeit anwenden könnte.

Bevor Sie also Kommentare hinzufügen, müssen Sie eine Quelle erstellen, in der Sie die Kommentare einfügen können.

Erstellen Sie ein Quellbeispiel

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

Knoten

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

Antwort

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

Zum Erstellen einer Quelle benötigen Sie Folgendes:

1. Ein Projekt – Ein bestehendes Projekt, an dem Sie gehören.
2. Ein Name – alphanumerische Zeichen, Bindestriche und Unterstriche sind alle OK (z. B nach dem Kauf).
3. Ein Titel – Ein kurzer, visuell lesbarer Titel für Ihre Quelle, der in der Benutzeroberfläche angezeigt werden soll, z. B. Umfrageantworten nach dem Kauf.
4. Eine Beschreibung – Optional eine längere Formbeschreibung der Quelle, die auf der Übersichtsseite der Quellen angezeigt werden soll.

Die ersten beiden bilden den vollqualifizierten Namen Ihrer Quelle, mit dem programmatisch darauf verwiesen wird. Die beiden letzteren sind für den menschlichen Gebrauch in der Benutzeroberfläche gedacht.

Fahren Sie mit dem Erstellen einer Beispielquelle fort.

Sehen Sie sich Ihre Quellenseite an und kommen Sie dann zurück.

Beispiel für das Auflisten von Quellen

Rufen wir nun programmatisch dieselben Informationen ab, die auf der Seite „Quellen“ mit allen Metadaten für alle Quellen verfügbar sind. Sie sollten Ihre Quelle sehen.

Bash

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

Knoten

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

Antwort

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

Wenn Sie nur möchten, dass die Quellen zu einem bestimmten Projekt gehören, können Sie deren Namen zum Endpunkt hinzufügen.

Löschen Sie ein Quellbeispiel

Durch das Löschen einer Quelle werden alle Nachrichten und alle anderen damit verbundenen Informationen unwiederbringlich vernichtet. Alle Datasets, die diese Quelle verwenden, verlieren auch die Trainingsdaten, die von allen Beschriftungen bereitgestellt werden, die Nachrichten in dieser Quelle hinzugefügt wurden. Daher sollte dieser Endpunkt mit Vorsicht verwendet werden. Das heißt, es sollte sicher sein, dass Sie die Quelle, die wir im vorherigen Abschnitt für Ihr Projekt erstellt haben, löschen.

Bash

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

Knoten

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

Antwort

{
  "status": "ok"
}

Die Antwort sollte {"status": "ok"} sein. Um sicherzugehen, dass es weg ist, können Sie alle Quellen erneut anfordern.

Bash

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

Knoten

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

Antwort

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

Beispiel für Kommentare hinzufügen

Quellen wären nutzlos ohne die Kommentare, die in ihnen enthalten sind. Ein Kommentar in Communications Mining™ ist entweder ein einzelnes Textteil oder mehrere Textelemente, die zu einer Konversation kombiniert werden. Beispiele für erstere sind Umfrageantworten, Support-Tickets und Kundenrezensionen, während zu letzteren E-Mail-Kketten gehören.

Wir fügen der im vorherigen Abschnitt erstellten Beispielquelle einige Kommentare hinzu:

Hinzufügen von E-Mails

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

Knoten

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

Antwort

null

Dieses Beispiel zeigt, wie ein Kommentar hinzugefügt wird, der aus mehreren Meldungen besteht. Dies wird am häufigsten zum Hinzufügen von E-Mails verwendet.

Die in den Anforderungen verwendeten Felder im zugehörigen Code müssen selbsterklärend sein. Die einzigen Pflichtfelder sind id, timestamp und messages.body.text. Weitere Informationen zu verfügbaren Feldern finden Sie in der Kommentarreferenz.

Das ID-Feld muss eine hexadezimale Zahl von höchstens 256 Ziffern sein, die unter Kommentaren eindeutig ist. Andernfalls wird die Auswahl dem Benutzer der API überlassen, was eine einfachere Integration in andere Systeme ermöglicht. Wenn Ihre IDs nicht hexadezimal sind, können Sie sie konvertieren. Wenn Sie zusätzlich die ursprünglichen IDs beibehalten möchten, können Sie sie in das Feld user_properties einfügen, das beliebige benutzerdefinierte Metadaten enthält.

Der Zeitstempel muss in UTC angegeben sein und sich auf die Zeit beziehen, zu der der Kommentar aufgezeichnet wurde, z. B. die Umfrage wurde beantwortet, nicht auf die aktuelle Zeit.

Die Antwort sollte bestätigen, dass zwei neue Kommentare erstellt wurden.

Hinzufügen von Kommentaren zu einzelnen Nachrichten

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

Knoten

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

Antwort

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

Dieses Beispiel zeigt, wie Sie einen Kommentar hinzufügen, der eine einzelne Nachricht enthält. Dieses Format eignet sich für Daten wie Umfrageantworten, Kundenrezensionen usw.

Die erforderlichen und verfügbaren Felder sind die gleichen wie im E-Mail-Beispiel, mit dem einzigen Unterschied, dass das Feld Nachrichten einen einzelnen Eintrag enthalten muss. Sie können E-Mail-spezifische Felder, die nicht zu Ihren Daten passen, überspringen, da sie nicht erforderlich sind.

Die Antwort sollte bestätigen, dass ein neuer Kommentar erstellt wurde.

Beispiel für das Abrufen von Kommentaren

Nach dem Hinzufügen kann ein Kommentar anhand seiner ID abgerufen werden. Sie sollten den im vorherigen Abschnitt hinzugefügten Kommentar sehen.

Bash

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

Knoten

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

Antwort

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

Erstellen Sie ein Beispiel für ein Dataset

Nachdem wir Communications Mining™ erfolgreich einige Rohdaten hinzugefügt haben, können wir jetzt mit dem Hinzufügen von Datasets beginnen. Ein Dataset entspricht einer Taxonomie von Beschriftungen zusammen mit den bereitgestellten Trainingsdaten, indem diese Beschriftungen auf die Nachrichten in einer Reihe ausgewählter Quellen angewendet werden. Sie können viele Datasets erstellen, die auf dieselbe Quelle verweisen, ohne dass das Beschriften von Nachrichten mit der Taxonomie eines Datasets Auswirkungen auf die anderen Datasets oder die zugrunde liegenden Quellen hat, sodass verschiedene Teams Communications Mining verwenden können, um Erkenntnisse unabhängig zu sammeln.

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

Knoten

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

Antwort

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

Sobald Quellen erstellt wurden, können Benutzer mit entsprechenden Berechtigungen auch Datasets auf der Benutzeroberfläche erstellen, was möglicherweise bequemer ist.

Beispiel für das Auflisten von Datasets

Bash

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

Knoten

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

Antwort

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

Wie Quellen haben Datasets mehrere GET-Routen, um:

• alle Datasets, auf die der Benutzer Zugriff hat;
• Datasets, die zum angegebenen Projekt gehören;
• ein einzelnes Dataset, das durch Projekt und Name angegeben wird.

Wir haben ein Beispiel für Letzteres in Aktion.

Aktualisieren Sie ein Dataset-Beispiel

Alle zulässigen Felder, die zum Erstellen eines Datasets verwendet werden, können aktualisiert werden, mit Ausnahme von has_sentiment, das für ein bestimmtes Dataset festgelegt ist.

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

Knoten

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

Antwort

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

Beispiel für das Löschen eines Datasets

Wenn Sie ein Dataset löschen, werden die zugehörige Taxonomie sowie alle Beschriftungen, die auf seine Quellen angewendet wurden, vollständig entfernt. Sie können keine Vorhersagen basierend auf dieser Taxonomie mehr abrufen und müssten den Trainingsprozess mit Anmerkungen von Anfang an starten, um diesen Vorgang rückgängig zu machen. Verwenden Sie ihn also mit Vorsicht.

Bash

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

Knoten

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

Antwort

{
  "status": "ok"
}

Rufen Sie Vorhersagen aus einem angehefteten Modellbeispiel ab

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

Knoten

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

Antwort

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

Sobald Sie über ein trainiertes Modell verfügen, können Sie dieses Modell jetzt verwenden, um Beschriftungen anhand anderer Datenelemente vorherzusagen. Dazu müssen Sie lediglich Folgendes angeben:

1. Dokumente – Ein Array von Nachrichtendaten, für die das Modell Beschriftungen vorhersagt, und jedes Nachrichtenobjekt darf nur eine Nachricht zusammen mit optionalen Eigenschaften enthalten. Für eine optimale Modellleistung müssen die bereitgestellten Daten mit den Daten und dem Format übereinstimmen, die auf der Plattform mit Anmerkungen versehen wurden, da das Modell alle verfügbaren Daten und Metadaten berücksichtigt. Beispielsweise sollten E-Mails die Felder „Betreff“, „Von“, „Bcc“, „Cc“ usw. enthalten, wenn diese in den Trainingsdaten vorhanden waren. Darüber hinaus sollten Benutzereigenschaften im Trainings-Dataset auch im API-Anforderungstext enthalten sein.
2. Labels – Ein Array der modelltrainierten Beschriftungen, die das Modell in den bereitgestellten Daten vorhersagen soll. Darüber hinaus muss für jede Beschriftung ein Konfidenzschwellenwert angegeben werden, nach dem Beschriftungen gefiltert werden. Der optimale Schwellenwert kann basierend auf Ihrem Kompromiss zwischen Genauigkeit und Erinnerung entschieden werden. Weitere Informationen zur Auswahl eines Schwellenwerts finden Sie im Benutzerhandbuch im Abschnitt Verwenden der Validierung.
3. Standardschwellenwert (Optional) – Ein Standardschwellenwert, der auf alle bereitgestellten Beschriftungen angewendet wird. Hinweis: Wenn Standard- und Schwellenwerte pro Beschriftung zusammen in einer Anforderung angegeben werden, überschreiben die Schwellenwerte pro Beschriftung den Standardschwellenwert. Als bewährte Methode können Standardschwellenwerte zum Testen oder Erkunden von Daten verwendet werden. Für optimale Ergebnisse bei der Verwendung von Vorhersagen für die automatisierte Entscheidungsfindung wird dringend empfohlen, Schwellenwerte pro Beschriftung zu verwenden.

Hinweis: Eine hierarchische Beschriftung wird als Liste von Beschriftungen formatiert. Beispielsweise hat die Beschriftung „Handel > Abrechnungen“ in der Anforderung das Format ["Handel", "Abrechnungen"].

Innerhalb der API-URL ist es wichtig, die folgenden Argumente zu übergeben:

1. Projektname – Ein bestehendes Projekt, dem Sie angehören.
2. Dataset-Name – Ein Dataset, auf dem das Modell trainiert wurde.
3. Modellversion – Die Modellversion ist eine Zahl, die auf der Seite Modelle für das von Ihnen gewählte Dataset zu finden ist.

Verstehen der Antwort

Da eine bestimmte Modellversion verwendet wird, wird die Antwort auf dieselbe Anforderung immer die gleichen Ergebnisse zurückgeben, auch wenn das Modell weiter trainiert wird. Nachdem Sie die Ergebnisse des neuen Modells validiert haben und eine Anforderung für das neue Modell einreichen möchten, sollten Sie die Modellversion in Ihrer Anforderung aktualisieren. Darüber hinaus sollten Sie auch die Beschriftungsschwellenwerte aktualisieren, um sie an das neue Modell anzupassen. Für jedes neue Modell müssen Sie die Schritte erneut durchlaufen.

Standardmäßig enthält die Antwort immer eine Liste der vorhergesagten Bezeichnungen für jede Nachricht mit einer Konfidenz, die größer ist als die angegebenen Schwellenwerte.

Die Antwort einer Anforderung kann jedoch variieren, wenn Entitätserkennung und Stimmungen für Ihr Modell aktiviert sind:

1. Allgemeine Felder aktiviert – Die Antwort enthält auch eine Liste der allgemeinen Felder, die für jede Beschriftung identifiziert wurden (Beispiel für die erste Antwort).
2. Stimmungen aktiviert – Die Antwort liefert außerdem eine Stimmungsbewertung zwischen -1 (vollständig negativ) und 1 (vollständig positiv) für jedes Beschriftungsobjekt, das über dem Konfidenzschwellenwert klassifiziert wird. (Beispiel für die zweite Antwort)

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