Obtener resultados de la transmisión

Permisos necesarios: Consumir transmisiones, Ver etiquetas, Ver fuentes.

Nota:

La ruta /results es la nueva forma de obtener comentarios y sus predicciones de una transmisión, reemplazando la ruta /fetch existente (Transmisiones - heredadas). Mantenemos la ruta /fetch para la compatibilidad heredada, pero recomendamos que todos los nuevos casos de uso utilicen la ruta /results , ya que admite todos los casos de uso posibles, incluidos los que utilizan la extracción generativa.

• Bash

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

• Nodo

  const request = require("request");
  
  request.get(
    {
      url: "https://<my_api_endpoint>/api/v1/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/v1/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))

• Respuesta

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

Una vez que creas una transmisión, puedes consultarla para obtener comentarios y sus predicciones. Esto incluye etiquetas, campos generales y extracciones de etiquetas, que contienen un conjunto de campos de extracción para cada instancia de esa etiqueta que se produce.

Cola de comentarios

Cuando creas una transmisión, estableces su posición inicial para que sea igual a su hora de creación. Si es necesario, puedes establecer la transmisión en una posición diferente (ya sea hacia adelante o hacia atrás en el tiempo), utilizando el punto final de restablecimiento. La transmisión devuelve comentarios a partir de su posición actual. La posición del comentario en la cola de comentarios se determina por el orden en el que se cargan los comentarios.

Avanzar en su posición en la cola

Como la transmisión solo devuelve comentarios desde su posición actual, debes avanzar a la siguiente posición después de cada solicitud de recuperación, utilizando el punto final de avance. De esta manera, la API garantiza al menos un procesamiento de todos los comentarios. Si tu aplicación falla al procesar un lote, recogerá el mismo lote al reiniciar.

Nota: Dado que una aplicación puede procesar correctamente un comentario pero fallar en el paso de avance, puedes observar que un comentario aparece varias veces.

Dependiendo del diseño de tu aplicación, puedes elegir entre:

• avanzando la transmisión una vez, para todo el lote. Utiliza el continuation del lote contenido en la respuesta.
• avanzar la transmisión para cada comentario individual. Utiliza el continuation del comentario, contenido en la respuesta.

Filtro de comentarios

If you specify a comment_filter when creating the stream, the results don't include comments not matching the filter, but still count towards the requested max_filtered. You can notice responses where all of max_filtered comments are filtered out, leading to an empty results array. In the following example, you request a batch of 8 comments, all of which are filtered out.

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

Pase el parámetro max_filtered opcional, para evitar que los comentarios filtrados cuenten para el max_results solicitado.

Umbrales de predicción

Nota: la ruta /fetch heredada no devuelve comentarios con predicciones que no alcanzan el umbral de confianza.

En esta nueva ruta /results , devuelves todas las predicciones para un comentario, y también confidencevalue . También indicas qué tipo(s) de umbral cumple.

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

El confidence para una predicción 0.9905.. y el valor thresholds indican que la predicción cumple con el umbral configurado para el stream.

Al crear una automatización, busca el valor stream para confirmar que la predicción cumple con el umbral que configuraste en la transmisión. Además, se pueden devolver umbrales automáticos , y los valores esperados para estos son: high_recall, high_precision y balanced.

Para obtener más información sobre las extracciones generadas y cómo trabajar con umbrales, consulta la página Comprender la validación en las extracciones y el rendimiento de la extracción .

Formato de solicitud

Nombre	Tipo	Obligatorio	Descripción
max_results	Número	No	El número de comentarios a recuperar para esta transmisión. Devuelve menos comentarios si llega al final del lote, o si filtra los comentarios según el filtro de comentarios. El valor máximo es 32. El valor predeterminado es 16.
max_filtered	Número	No	Parámetro de conveniencia para transmisiones con un filtro de comentarios. Cuando los proporciona, hasta max_filtered comentarios filtrados no cuentan para el max_results solicitado. Esto es útil si esperas que un gran número de comentarios no coincidan con el filtro. No tiene efecto en las transmisiones sin un filtro de comentarios. El valor máximo es 1024. El valor predeterminado es nulo.

Formato de respuesta

Nombre	Tipo	Descripción
status	String	ok si la solicitud tiene éxito, o error, en caso de error. Para obtener más información sobre las respuestas de error, consulta la página Información general .
num_filtered	Número	Número de comentarios que se filtraron en función de un filtro de comentarios. Si creaste la transmisión sin un filtro, este número siempre es 0.
continuation	String	El token de continuación del lote. Úselo para confirmar el procesamiento de este lote y avanzar la transmisión al siguiente lote.
more_results	Booleano	Verdadero si no hubo resultados adicionales en la transmisión, cuando realizó la solicitud. Falso en caso contrario.
results	array<Result>	Una matriz que contiene objetos de resultado.

Donde Result tiene el siguiente formato:

Nombre	Tipo	Descripción
comment	Comentario	Comentar datos. Para obtener una explicación detallada, consulta Referencia de comentarios.
continuation	String	El token de continuación del comentario. Se utiliza para reconocer el procesamiento de este comentario y avanzar al siguiente comentario.
prediction	array<Prediction>	La predicción para este comentario. Solo está disponible si la transmisión especifica una versión del modelo. Para obtener más información sobre las predicciones generativas, consulta la página Communications Mining™: comprensión de la validación en las extracciones y rendimiento de las extracciones .

Prediction tiene el siguiente formato:

Nombre	Tipo	Descripción
taxonomies	matriz<PredicciónDeTaxonomía><TaxonomyPrediction>	Lista de predicciones de taxonomía. Actualmente solo defines una taxonomía por conjunto de datos, pero la proporcionas como una lista, para futura compatibilidad.

TaxonomyPrediction tiene el siguiente formato:

Nombre	Tipo	Descripción
name	String	Nombre de la taxonomía. El único valor es actualmente default.
labels	array<LabelPrediction>	Una lista de predicciones de etiquetas extraídas con sus occurrence_confidence, extraction_confidence y fields extraídas. Para obtener más información sobre las predicciones generativas, consulta la página Communications Mining: comprensión de la validación en extracciones y rendimiento de extracción .
general_fields	matriz<PredicciónDeCampo><FieldPrediction>	Una lista de predicciones de campo generales extraídas con sus name y value extraídas. Para obtener más información sobre las predicciones generativas, consulta la página Communications Mining: comprensión de la validación en extracciones y rendimiento de extracción .