Get results from stream

Autorisations requises : utiliser des flux, afficher les libellés, afficher les sources.

Remarque :

La route /results est le nouveau moyen de récupérer les commentaires et leurs prédictions à partir d'un flux, remplaçant la route /fetch existante (Streams - Héritage). Nous conservons la route / fetch pour la prise en charge héritée, mais nous recommandons que tous les nouveaux cas d’utilisation utilisent la route /results , car elle prend en charge tous les cas d’utilisation possibles, y compris ceux utilisant l’extraction générative.

• Bash

  curl -X GET 'https://<my_api_endpoint>/api/preview/datasets/project1/collateral/streams/dispute/results?max_results=5&max_filtered=15' \
      -H "Authorization: Bearer $REINFER_TOKEN"

• Nœud

  const request = require("request");
  
  request.get(
    {
      url: "https://<my_api_endpoint>/api/preview/datasets/project1/collateral/streams/dispute/results?max_results=5&max_filtered=15",
      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/preview/datasets/project1/collateral/streams/dispute/results",
      headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
      params={"max_results": 5, "max_filtered": 15},
  )
  
  print(json.dumps(response.json(), indent=2, sort_keys=True))

• Réponse

  {
    "status": "ok",
    "results": [
      {
        "comment": {
          "uid": "18ba5ce699f8da1f.0123456789abcdef",
          "id": "0123456789abcdef",
          "timestamp": "2018-09-17T09:54:56.332000Z",
          "user_properties": {
            "number:Messages": 1,
            "string:Folder": "Sent (/ Sent)",
            "string:Has Signature": "Yes",
            "string:Message ID": "<[e-mail]>",
            "string:Sender": "[e-mail]",
            "string:Sender Domain": "company.com",
            "string:Thread": "<[e-mail]>"
          },
          "messages": [
            {
              "from": "[e-mail]",
              "to": [
                "[e-mail]"
              ],
              "sent_at": "2018-09-17T09:54:56.332000Z",
              "body": {
                "text": "Hi Bob,\n\nCould you send me today's figures?"
              },
              "subject": {
                "text": "Today's figures"
              },
              "signature": {
                "text": "Thanks,\nAlice"
              }
            }
          ],
          "text_format": "plain",
          "attachments": [],
          "source_id": "18ba5ce699f8da1f",
          "last_modified": "2024-07-03T13:30:53.991000Z",
          "created_at": "2020-12-14T15:07:03.718000Z",
          "context": "1",
          "has_annotations": true
        },
        "prediction": {
          "taxonomies": [
            {
              "name": "default",
              "labels": [
                {
                  "name": "Margin Call",
                  "occurrence_confidence": {
                    "value": 0.9905891418457031,
                    "thresholds": ["stream"]
                  },
                  "extraction_confidence": {
                    "value": 0.4712367373372217,
                    "thresholds": []
                  },
                  "fields": [
                    {
                      "name": "Notification Date",
                      "value": null
                    }
                  ]
                },
                {
                  "name": "Margin Call > Interest Accrual",
                  "occurrence_confidence": {
                    "value": 0.9905891418457031,
                    "thresholds": []
                  },
                  "extraction_confidence": {
                    "value": 0.9905891418457031,
                    "thresholds": []
                  },
                  "fields": [
                    {
                      "name": "Amount",
                      "value": {
                        "formatted": "636,000.00"
                      }
                    },
                    {
                      "name": "Broker number",
                      "value": null
                    },
                    {
                      "name": "Client name",
                      "value": null
                    },
                    {
                      "name": "Currency",
                      "value": {
                        "formatted": "AUD"
                      }
                    }
                  ]
                }
              ],
              "general_fields": [
                {
                  "name": "monetary-quantity",
                  "value": {
                    "formatted": "636,000.00 GBP"
                  }
                },
                {
                  "name": "MarginCallDateType",
                  "value": {
                    "formatted": "2018-09-21 00:00 UTC"
                  }
                },
                {
                  "name": "client-name",
                  "value": {
                    "formatted": "Big Client Example Bank"
                  }
                }
              ]
            }
          ]
        },
        "continuation": "pmjKYXYBAAADqHUvPkQf1ypNCZFR37vu"
      }
    ],
    "num_filtered": 0,
    "more_results": true,
    "continuation": "pmjKYXYBAAAsXghZ2niXPNP6tOIJtL_8"
  }

Une fois que vous avez créé un flux, vous pouvez l’interroger pour récupérer les commentaires et leurs prédictions. Cela inclut les libellés, les champs généraux et les extractions de libellés, contenant un ensemble de champs d’extraction pour chaque instance de ce libellé.

Vérifiez ces aspects lorsque vous récupérez des commentaires à partir d'un flux :

File d'attente de commentaires

Lorsque vous créez un flux, vous définissez sa position initiale pour qu'elle soit égale à son heure de création. Si nécessaire, vous pouvez définir le flux sur une position différente (soit vers l'avant, soit vers l'arrière dans le temps), à l'aide du point de terminaison réinitialisé. Le flux renvoie les commentaires à partir de sa position actuelle. Vous déterminez la position du commentaire dans la file d'attente de commentaires en fonction de l'ordre dans lequel vous avez téléchargé les commentaires.

Avancer votre position dans la file d'attente

Étant donné que le flux ne renvoie que des commentaires à partir de sa position actuelle, vous devez le faire passer à la position suivante après chaque demande d'extraction, en utilisant le point de terminaison avancé. De cette façon, l'API garantit au moins un traitement de tous les commentaires. Si votre application échoue lors du traitement d'un lot, elle récupérera le même lot au redémarrage.

Remarque : étant donné qu’une application peut traiter un commentaire avec succès mais échouer à l’étape avancée, un commentaire peut s’afficher plusieurs fois.

Selon la conception de votre application, vous pouvez choisir entre :

• faisant progresser le flux une seule fois, pour l'ensemble du lot. Utilisez le continuation du lot contenu dans la réponse.
• faire progresser le flux pour chaque commentaire individuel. Utilisez le continuation du commentaire contenu dans la réponse.

Filtre Commentaire (Commentaire)

Si vous spécifiez un comment_filter lors de la création du flux, les résultats n’incluent pas les commentaires ne correspondant pas au filtre, mais continuent d’être pris en compte dans le max_filtered demandé. Vous pouvez voir les réponses où tous les commentaires max_filtered sont filtrés, ce qui permet d'obtenir un tableau results vide. Dans l'exemple ci-dessous, vous demandez un lot de 8 commentaires, qui sont tous filtrés.

{
  "filtered": 8,
  "results": [],
  "sequence_id": "qs8QcHIBAADJ1p3W2FtmBB3QiOJsCJlR",
  "status": "ok"
}

Définissez le paramètre max_filtered facultatif pour empêcher les commentaires filtrés de compter vers le max_results demandé.

Seuils de prédiction

Remarque : l'itinéraire /fetch hérité ne renvoie pas de commentaires avec des prédictions qui n'ont pas respecté le seuil de confiance.

Dans ce nouvel itinéraire /results , vous renvoyez toutes les prédictions d'un commentaire, ainsi que le confidencevalue . Vous indiquez également le(s) type(s) de seuil qu'il remplit.

"occurrence_confidence": {
    "value": 0.9905891418457031,
    "thresholds": ["stream"]
  }

La valeur confidence d'une prédiction 0.9905.. et la valeur thresholds indiquent que la prédiction respecte le seuil configuré pour stream.

Lors de la création d'une automatisation, recherchez la valeur stream pour confirmer que la prédiction respecte le seuil que vous avez configuré dans le flux.

Pour plus d'informations sur les extractions générées et sur l'utilisation des seuils, consultez la page Comprendre la validation sur les extractions et les performances d'extraction .

Format de demande

Nom	Saisie de texte	Requis	DESCRIPTION
max_results	Numérique	non	Le nombre de commentaires à récupérer pour ce flux. Renvoie moins de commentaires s'il atteint la fin du lot, ou si vous filtrez les commentaires en fonction du filtre de commentaire. La valeur maximale est 32. Le nombre par défaut est 16.
max_filtered	Numérique	non	Paramètre de commodité pour les flux avec un filtre de commentaire. Lorsque vous les fournissez, jusqu’à max_filtered commentaires filtrés ne sont pas pris en compte dans le max_results demandé. Ceci est utile si vous vous attendez à ce qu'un grand nombre de commentaires ne correspondent pas au filtre. N’a aucun effet sur les flux sans filtre de commentaire. La valeur maximale est 1 024. La valeur par défaut est nulle.

Format de réponse

Nom	Saisie de texte	DESCRIPTION
status	string	ok si la requête a réussi, ou bien error, en cas d'erreur. Pour en savoir plus sur les réponses d'erreur, consultez la page Vue d'ensemble (Overview).
num_filtered	Numérique	Nombre de commentaires filtrés sur la base d'un filtre de commentaire. Si vous avez créé le flux sans filtre, ce nombre sera toujours 0.
continuation	string	Le jeton de poursuite du lot. Utilisez-le pour confirmer le traitement de ce lot et faire passer le flux au lot suivant.
more_results	Bool	« True » s'il n'y avait pas de résultats supplémentaires dans le flux, lorsque vous avez effectué la demande. False dans le cas contraire.
results	array<Result>	Tableau contenant les objets de résultat.

Où Result a le format suivant :

Nom	Saisie de texte	DESCRIPTION
comment	Commentaire (Comment)	Données de commentaires. Pour une explication détaillée, consultez la section Référence du commentaire (Comment Reference).
continuation	string	Le jeton de suite du commentaire. Utilisé pour confirmer le traitement de ce commentaire et faire passer le flux au commentaire suivant.
prediction	array<Prediction>	La prédiction de ce commentaire. Est disponible uniquement si le flux spécifie une version de modèle. Pour plus d'informations sur les prédictions génératives, consultez la page : Communications Mining - Comprendre la validation des extractions et des performances d'extraction .

Prediction a le format suivant :

Nom	Saisie de texte	DESCRIPTION
taxonomies	tableau<TaxonomyPrediction>	Liste des prédictions de taxonomie. Vous ne définissez actuellement qu’une seule taxonomie par jeu de données, mais vous la fournissez sous forme de liste, pour une compatibilité future.

TaxonomyPrediction a le format suivant :

Nom	Saisie de texte	DESCRIPTION
name	string	Nom de la taxonomie. La seule valeur est actuellement default.
labels	tableau<LabelPrediction>	Une liste des prédictions de libellés extraites avec leur occurrence_confidence, extraction_confidence et fields extrait. Pour plus d’informations sur les prédictions génératives, consultez la page Communications Mining - Comprendre la validation des extractions et des performances d’extraction .
general_fields	tableau<FieldPrediction>	Une liste de prédictions de champ général extraites avec leur name et leurs value extraites. Pour plus d’informations sur les prédictions génératives, consultez la page Communications Mining - Comprendre la validation des extractions et des performances d’extraction .