Obter resultados do stream

Permissões necessárias: Consumir fluxos, Exibir rótulos, Exibir origens.

Observação:

A rota /results é a nova maneira de buscar comentários e suas previsões de um stream, substituindo a rota /fetch existente (Streams - legado). Mantemos a rota /fetch para suporte legado, mas recomendamos que todos os novos casos de uso usem a rota /results , pois ela é compatível com todos os casos de uso possíveis, incluindo aqueles que usam a extração 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"

• Nó

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

• Resposta

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

Depois de criar um stream, você pode consulte-lo para buscar comentários e suas previsões. Isso inclui rótulos, campos gerais e extrações de rótulos, contendo um conjunto de campos de extração para cada instância da ocorrência desse rótulo.

Fila de Comentários

Ao criar um stream, você define sua posição inicial para ser igual a seu tempo de criação. Se necessário, você pode definir o stream para uma posição diferente (para frente ou para trás no tempo), usando o ponto de extremidade de redefinição. O stream retorna comentários a partir de sua posição atual. Você determina a posição do comentário na fila de comentários pela ordem em que você carregou os comentários.

Avançando sua posição na fila

Como o stream só retorna comentários de sua posição atual, você deve avançar para a próxima posição após cada solicitação de busca, usando o endpoint avançado. Dessa forma, a API garante pelo menos uma vez o processamento de todos os comentários. Se o aplicativo falhar ao processar um lote, ele retomará o mesmo lote ao reiniciar.

Observação: como um aplicativo pode processar com sucesso um comentário, mas falhar na etapa avançar, você pode observar que um comentário aparece várias vezes.

Dependendo do design do seu aplicativo, você pode escolher entre:

• avançando o stream uma vez, para todo o lote. Use o continuation do lote contido na resposta.
• avançar o fluxo para cada comentário individual. Use o continuation do comentário, contido na resposta.

Filtro do Comentário

Se você especificar um comment_filter ao criar o stream, os resultados não incluirão comentários que não correspondam ao filtro, mas ainda contarão para o max_filtered solicitado. Você pode observar respostas em que todos os comentários max_filtered são filtrados, levando a uma matriz results vazia. No exemplo abaixo, você solicita um lote de 8 comentários, todos os quais são filtrados.

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

Passe o parâmetro opcional max_filtered , para evitar que os comentários filtrados sejam contados no max_results solicitado.

Limites de previsão

Observação: a rota /fetch legada não retorna comentários com previsões que não atenderam ao limite de confiança.

Nessa nova rota /results , você retorna todas as previsões para um comentário e o confidencevalue também. Você também indica quais tipos de limite ele atende.

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

O confidence para uma previsão 0.9905.. e o valor thresholds indica que a previsão atende ao limite configurado para o stream.

Ao criar uma automação, procure o valor stream para confirmar se a previsão atende ao limite que você configurou no stream. Além disso, os limites automáticos podem ser retornados, e os valores esperados para eles são: high_recall, high_precision e balanced.

Para obter mais informações sobre as extrações geradas e como trabalhar com limites, consulte a página Compreensão da validação das extrações e do desempenho da extração .

Formato de solicitação

Nome	Tipo	Required	Descrição
max_results	Número	não	O número de comentários a serem buscados para este fluxo. Retorna menos comentários se atingir o fim do lote ou se você filtrar os comentários de acordo com o filtro de comentários. O valor máximo é 32. O padrão é 16.
max_filtered	Número	não	Parâmetro de conveniência para transmissões com um filtro de comentários. Quando você os fornece, até max_filtered comentários filtrados não são contabilizados para os max_results solicitados. Isso é útil se você espera que um grande número de comentários não corresponda ao filtro. Não tem efeito em transmissões sem um filtro de comentários. O valor máximo é 1024. O padrão é nulo.

Formato da Resposta

Nome	Tipo	Descrição
status	String	ok se a solicitação for bem-sucedida ou error, em caso de erro. Para saber mais sobre respostas de erro, consulte a página Visão geral .
num_filtered	Número	Número de comentários que foram filtrados com base em um filtro de comentários. Se você criou o stream sem um filtro, esse número é sempre 0.
continuation	String	O token de continuação de lote. Use-o para confirmar o processamento desse lote e avançar o stream para o próximo lote.
more_results	Bool	Verdadeiro se não houvesse resultados adicionais no fluxo, quando você fez a solicitação. Caso contrário, falso.
results	array<Result>	Uma matriz que contém objetos de resultado.

Onde Result tem o seguinte formato:

Nome	Tipo	Descrição
comment	Comentar	Dados do comentário. Para uma explicação detalhada, consulte a Referência de comentário.
continuation	String	O token de continuação do comentário. Usado para confirmar o processamento deste comentário e avançar para o próximo comentário.
prediction	array<Prediction>	A previsão para este comentário. Está disponível apenas se o fluxo especificar uma versão do modelo. Para obter mais informações sobre previsões generativas, consulte a página: Communications Mining™ - Entendendo a validação em extrações e a página desempenho de extração .

Prediction tem o seguinte formato:

Nome	Tipo	Descrição
taxonomies	array<TaxonomyPrevisão><TaxonomyPrediction>	Lista de previsões de taxonomia. Atualmente, você define apenas uma taxonomia por conjunto de dados, mas a fornece como uma lista, para compatibilidade futura.

TaxonomyPrediction tem o seguinte formato:

Nome	Tipo	Descrição
name	String	Nome da taxonomia. O único valor no momento é default.
labels	matriz<LabelPrediction>	Uma lista de previsões de rótulos extraídas com seus occurrence_confidence, extraction_confidence e fields extraídos. Para obter mais informações sobre previsões generativas, consulte a página Communications Mining - Validação de compreensão sobre extrações e desempenho de extração .
general_fields	matriz<FieldPrediction>	Uma lista de previsões de campo geral extraídas com seus name e value extraídos. Para obter mais informações sobre previsões generativas, consulte a página Communications Mining - Validação de compreensão sobre extrações e desempenho de extração .