Tutoriel API

Il s'agit d'une introduction de style tutoriel à l'API. Passez directement à la référence si vous savez ce que vous cherchez.

Toutes les données, dont les éléments individuels sont appelés messages, sont regroupées en sources. Une source doit correspondre à l'origine des données, comme une boîte aux lettres unique ou un canal de retour d'information particulier. Celles-ci peuvent être combinées aux fins d'un seul modèle d'inférence. Il est donc préférable d'opter pour plusieurs sources différentes plutôt que pour un seul monobloc en cas de doute.

Un jeu de données est une combinaison de sources avec les catégories d'étiquettes associées. Par exemple, un ensemble de données peut être construit sur une source de commentaires de site Web, avec des libellés tels que Facilité d'utilisation ou informations disponibles, tandis qu'un ensemble de données différent peut se baser sur diverses sources de réponses aux enquêtes post-achat et appliquer des libellés complètement différents sur l' empaquetage ou la vitesse de livraison.

Ainsi, avant d'ajouter des commentaires, vous devez créer une source dans laquelle les intégrer.

Créer un exemple de source

• 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œud

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

• Réponse

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

Pour créer une source, vous avez besoin de quatre choses :

1. Un projet. Ce projet est un projet existant dont vous faites partie.
2. Un nom. Les caractères alphanumériques, les traits d'union et les traits de soulignement sont tous OK (par ex. « post-achat »).
3. Un titre. Un titre court et lisible par un humain que votre source affichera dans l’interface utilisateur (par exemple « Réponses aux enquêtes sur les achats »).
4. Une description. En option, une description plus longue de la source à afficher sur la page de vue d’ensemble des sources.

Les deux premiers forment le nom « complet » de votre source, qui est utilisé pour y faire référence de manière programmatique. Les deux derniers sont destinés à la consommation humaine dans l'interface utilisateur.

Allez-y et créez une source example .

Vous devriez maintenant être l'heureux propriétaire d'une source! Consultez votre page sources, puis revenez.

Lister des exemples de sources

Récupérons de manière programmatique les mêmes informations disponibles sur la page des sources, avec toutes les métadonnées de toutes les sources. Vous devriez voir votre source.

• Bash

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

• Nœud

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

• Réponse

  {
    "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 vous souhaitez uniquement que les sources appartiennent à un projet spécifique, vous pouvez ajouter son nom au point de terminaison.

Supprimer un exemple de source

La suppression d'une source irrécupère tous les messages et toute autre information qui lui est associée. Tous les ensembles de données qui utilisent cette source perdront également les données d'entraînement fournies par les libellés qui ont été ajoutés aux messages de cette source. Par conséquent, ce point de terminaison doit être utilisé avec prudence. Cela dit, vous pouvez supprimer, en toute sécurité, la source que nous avons créée pour votre projet dans la section précédente.

• Bash

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

• Nœud

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

• Réponse

  {
    "status": "ok"
  }

La réponse doit être {"status": "ok"}. Pour être sûr, vous pouvez à nouveau demander toutes les sources.

• Bash

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

• Nœud

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

• Réponse

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

Ajouter un exemple de commentaires

Les sources seraient inutiles sans les commentaires qui y sont contenus. Un commentaire dans Communications Mining est soit un texte individuel, soit plusieurs éléments de texte combinés dans une conversation. Il s'agit par exemple des réponses aux enquêtes, des tickets d'assistance et des avis des clients, tandis que les chaînes d'e-mails sont des exemples de ces derniers.

Nous allons continuer et ajouter quelques commentaires à l'« exemple » source créé dans la section précédente.

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

• Nœud

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

• Réponse

  null

Cet exemple montre comment ajouter un commentaire composé de plusieurs messages. Cette fonction est le plus souvent utilisée pour l'ajout d'e-mails.

Les champs utilisés dans les requêtes du code d'accompagnement doivent être auto-explicatifs. Les seuls champs requis sont id, timestamp et messages.body.text. Vous pouvez en savoir plus sur les champs disponibles dans la référence du commentaire.

Le champ ID doit être un nombre hexadécimal, unique parmi les commentaires, ne dépassant pas 256 chiffres. Sinon, le choix est laissé à l'utilisateur de l'API, ce qui permet une intégration plus facile avec d'autres systèmes. Si vos ID ne sont pas hexadécimaux, vous pouvez les convertir. Si vous souhaitez conserver davantage les ID d'origine, vous pouvez les placer dans le champ user_properties qui contient des métadonnées arbitraires définies par l'utilisateur.

L'horodatage doit être en UTC et faire référence à l'heure à laquelle le commentaire a été enregistré (par ex. l'enquête a été répondue), pas l'heure actuelle.

La réponse doit confirmer que deux nouveaux commentaires ont été créés.

Ajout de commentaires à message unique

• 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œud

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

• Réponse

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

Cet exemple montre comment ajouter un commentaire contenant un seul message. Ce format peut convenir à des données telles que les réponses aux enquêtes, les avis des clients, etc.

Les champs obligatoires et disponibles sont les mêmes que dans l'exemple des e-mails, à la seule différence que le champ messages doit contenir une seule entrée. Vous pouvez ignorer les champs spécifiques à l'e-mail qui ne correspondent pas à vos données, car ils ne sont pas obligatoires.

La réponse doit confirmer qu'un nouveau commentaire a été créé.

Récupérer l'exemple de commentaires

Une fois ajouté, un commentaire peut être récupéré par son ID. Le commentaire devrait s’ajouter à la section précédente.

• Bash

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

• Nœud

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

• Réponse

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

Créer un exemple d'ensemble de données

Après avoir ajouté avec succès des données brutes à Communications Mining, nous pouvons maintenant commencer à ajouter des ensembles de données. Un ensemble de données correspond à une taxonomie de libellés ainsi que les données d'apprentissage fournies en appliquant ces libellés aux messages dans une série de sources sélectionnées. Vous pouvez créer de nombreux ensembles de données qui font référence à la même source sans que la labellisation des messages à l'aide de la taxonomie d'un ensemble de données ait un impact sur les autres ensembles de données (ou les sources sous-jacentes), permettant à différentes équipes d'utiliser Communications Mining pour recueillir des informations indépendamment.

• 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œud

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

• Réponse

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

Une fois les sources créées, les utilisateurs disposant des autorisations appropriées peuvent également créer des jeux de données dans l'interface utilisateur, ce qui peut être plus pratique.

Lister des exemples de jeux de données

• Bash

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

• Nœud

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

• Réponse

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

Comme les sources, les ensembles de données ont plusieurs routages GET correspondant à :

• tous les jeux de données auxquels l’utilisateur a accès ;
• les jeux de données appartenant au projet spécifié ;
• un jeu de données unique spécifié par projet et par nom.

Nous fournissons un exemple de ce dernier en action.

Mettre à jour un exemple d'ensemble de données

Tous les champs autorisés utilisés pour créer un ensemble de données peuvent être mis à jour, à l'exception de has_sentiment, qui est fixe pour un ensemble de données donné.

• 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œud

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

• Réponse

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

Supprimer un exemple de jeu de données

La suppression d'un ensemble de données supprimera complètement la taxonomie associée ainsi que tous les libellés qui ont été appliqués à ses sources. Vous ne pourrez plus obtenir de prédictions basées sur cette taxonomie et devrez démarrer le processus d'apprentissage des messages d'annotation depuis le début afin d'annuler cette opération. Utilisez-la donc avec précaution.

• Bash

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

• Nœud

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

• Réponse

  {
    "status": "ok"
  }

Obtenir des prédictions à partir d'un exemple de modèle épinglé

• 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œud

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

• Réponse

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

Une fois que vous avez un modèle entraîné, vous pouvez maintenant utiliser ce modèle pour prédire les libellés par rapport à d'autres données. Pour ce faire, il vous suffit de fournir les éléments suivants :

1. Documents: il s'agit d'un tableau de données de message pour lequel le modèle prédit les libellés, et chaque objet de message ne peut contenir qu'un seul message avec toutes les propriétés facultatives. Pour des performances optimales du modèle, les données fournies doivent être cohérentes avec les données et le format qui ont été annotés sur la plate-forme, car le modèle prend en compte toutes les données et métadonnées disponibles. Par exemple, les e-mails doivent inclure les champs objet, source/bcc/cc, etc. (si ceux-ci étaient présents dans les données d’entraînement). De plus, les propriétés utilisateur de l'ensemble de données d'entraînement doivent également être incluses dans le corps de la requête d'API.
2. Libellés: il s'agit d'un tableau des libellés entraînés par le modèle que vous souhaitez que le modèle prédit dans les données fournies. De plus, pour chaque libellé, un seuil de confiance par lequel filtrer les libellés doit être fourni. Le seuil optimal peut être décidé en fonction de votre compromis précision vs rappel. De plus amples informations concernant le choix d'un seuil sont disponibles dans le Manuel utilisateur, dans la section "Utilisation de la validation".
3. Seuil par défaut (facultatif): il s'agit d'une valeur de seuil par défaut qui sera appliquée à tous les libellés fournis. Veuillez noter que si les seuils par défaut et par libellé sont fournis ensemble dans une requête, les seuils par libellé remplaceront le seuil par défaut. En règle générale, des seuils par défaut peuvent être utilisés pour tester ou explorer des données. Pour optimiser les résultats lors de l'utilisation de prédictions destinées à la prise de décision automatisée, il est fortement recommandé d'utiliser des seuils par libellé.

Remarque : un libellé hiérarchique sera formaté sous la forme d'une liste de libellés. Par exemple, le libellé « Trade > Settlements » aura le format [« Trade », « Settlements »] dans la requête.

Dans l'URL de l'API, il est important de transmettre les arguments suivants :

1. Nom du projet: il s'agit d'un projet existant dont vous faites partie.
2. Nom de l'ensemble de données : il s'agit d'un ensemble de données sur lequel le modèle a été entraîné.
3. Version du modèle: la version du modèle est un numéro qui se trouve sur la page « Modèles » du jeu de données choisi.

Comprendre la réponse

Comme une version de modèle spécifique est utilisée, la réponse à la même requête renverra toujours les mêmes résultats, même si le modèle est entraîné davantage. Une fois que vous avez validé les résultats du nouveau modèle et que vous souhaitez soumettre une demande contre le nouveau modèle, vous devez mettre à jour la version du modèle dans votre demande. De plus, vous devez également mettre à jour les seuils de libellé pour qu'ils s'adaptent au nouveau modèle. Pour chaque nouveau modèle, vous devrez à nouveau parcourir les étapes.

Par défaut, la réponse fournira toujours une liste de libellés prédits pour chaque message avec une confiance supérieure aux niveaux de seuil fournis.

Cependant, la réponse à une requête peut varier si la reconnaissance d'entité et les sentiments sont activés pour votre modèle :

1. Champs généraux Activé. La réponse fournira également une liste de champs généraux qui ont été identifiés pour chaque libellé (premier exemple de réponse)
2. Sentiments activés. La réponse fournira également un score de sentiment compris entre -1 (parfaitement négatif) et 1 (parfaitement positif) pour chaque objet de libellé classé au-dessus du seuil de confiance. (deuxième exemple de réponse)

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