从流中获取结果

用于使用推荐的 /results 路由从 Communications Mining 流中获取注释和预测的 API 端点，取代了旧的 /fetch 路由。

所需权限：使用流、查看标签、查看来源。

备注：

/results路由是从流中获取注释及其预测的新方法，以替换现有的/fetch路由（流 - 旧版）。 我们维护 /获取路由以实现旧版支持，但建议所有新用例使用/results路由，因为它支持所有可能的用例，包括使用生成式提取的用例。

• 重击

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"

• 节点

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

• 响应

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

创建流后，您可以查询该流以获取注释及其预测。 这包括标签、通用字段和标签提取，其中包含该标签的每个实例的一组提取字段。

注释队列

创建流时，请将其初始位置设置为等于其创建时间。如果需要，您可以使用重置端点将流设置到不同位置（在时间上向前或向后）。流将从其当前位置开始返回注释。您可以根据注释的上传顺序来确定注释在注释队列中的位置。

推进您在队列中的位置

由于流仅从其当前位置返回注释，因此您应该在每个提取请求后使用推进端点将其推进到下一个位置 。这样，API 可保证至少处理一次所有注释。如果应用程序在处理批处理时失败，则它将在重新启动时选取同一个批次。

备注：

由于应用程序可以成功处理注释，但在高级步骤中失败，因此您可以注意到注释出现多次。

根据应用程序设计，您可以选择：

• 为整个批处理推进一次流。 使用响应中包含的批次的continuation 。
• 为每个单独的注释推进流。 使用响应中包含的注释的continuation 。

注释筛选器

如果在创建流时指定了comment_filter ，则结果不包含不与筛选器匹配的注释，但仍计入请求的max_filtered中。您可以注意到，所有max_filtered注释都被筛选出的响应，从而导致空的results数组。在以下示例中，您请求一批 8 个注释，这些注释都被筛选掉。

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

传递可选的max_filtered参数，以防止将筛选的注释计入请求的max_results中。

预测阈值

备注：

The legacy /fetch route does not return comments with predictions that did not meet the confidence threshold. In this new /results route, you return all the predictions for a comment, and the confidence value as well. You also indicate which type(s) of threshold it meets.

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

The confidence for the prediction is 0.9905.., and the thresholds value indicates that the prediction meets the configured threshold for the stream.

备注：

您配置的流阈值的默认名称为stream 。当标签预测符合此阈值时， stream将包含在流结果中的标签阈值列表中。

构建自动化时，请查找stream值，以确认预测符合您在流中配置的阈值。此外，可能会返回“自动”阈值，这些阈值的预期值为： high_recall 、 high_precision和balanced 。

有关生成的提取以及如何使用阈值的更多信息，请查看了解提取的验证和提取性能页面。

请求格式

名称	类型	必填	说明
max_results	数字	否	The number of comments to fetch for this stream. Returns fewer comments if it reaches the end of the batch, or if you filter out comments according to the comment filter. Max value is 32. Default is 16.
max_filtered	数字	否	Convenience parameter for streams with a comment filter. When you provide it, up to max_filtered filtered comments do not count towards the requested max_results. This is useful if you expect a large number of comments to not match the filter. Has no effect on streams without a comment filter. Max value is 1024. Default is null.

响应格式

名称	类型	说明
status	字符串	ok 如果请求成功，则使用error ，如果发生错误。要了解有关错误响应的更多信息，请查看概述页面。
num_filtered	数字	根据注释筛选器筛选出的注释数量。 如果您在创建流时不使用筛选器，则此数字始终为0 。
continuation	字符串	批次继续令牌。 使用它来确认此批次的处理，并将流推进到下一个批次。
more_results	Bool	当发出请求时，如果流中没有其他结果，则返回 True 否则返回 false。
results	array<Result>	包含结果对象的数组。

其中Result具有以下格式：

名称	类型	说明
comment	注释	注释数据。有关详细说明，请查看“注释参考” 。
continuation	字符串	注释的继续令牌。 用于确认处理此注释并将流推进到下一条注释。
prediction	array<Prediction>	The prediction for this comment. Is available only if the stream specifies a model version. For more information about generative predictions, check the UiPath Communications Mining™ - Understanding validation on extractions and extraction performance page.

Prediction具有以下格式：

名称	类型	说明
taxonomies	array<TaxonomyPrediction>	分类预测列表。 您目前仅为每个数据集定义一个分类，但您可将其以列表的形式提供，以供日后使用。

TaxonomyPrediction具有以下格式：

名称	类型	说明
name	字符串	分类名称。 当前唯一的值为default 。
labels	array<LabelPrediction>	提取的标签预测及其occurrence_confidence 、 extraction_confidence和提取的fields的列表。有关生成式预测的更多信息，请查看Communications Mining - Understanding 提取验证和提取性能页面。
general_fields	array<FieldPrediction>	提取的通用字段预测及其name和提取的value的列表。有关生成式预测的更多信息，请查看Communications Mining - Understanding 提取验证和提取性能页面。