ストリームから結果を取得する

必要な権限: ストリームの使用、ラベルの表示、ソースの表示

注:

/results ルートは、ストリームからコメントとその予測を取得する新しい方法であり、既存の /fetch ルート (ストリーム - レガシ) を置き換えます。レガシ サポートのために /fetch ルートを維持していますが、生成抽出を使用するユース ケースを含め、考えられるすべてのユース ケースをサポートするため、新しいユース ケースはすべて /results ルートを使用することをお勧めします。

• 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"

• ノードの割り当て

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

ストリームを作成したら、クエリを実行してコメントとその予測を取得できます。 これには、ラベル、全般フィールド、ラベル抽出が含まれ、そのラベルの発生インスタンスごとに一連の抽出フィールドが含まれます。

コメントキュー

ストリームを作成するときは、その初期位置が作成時刻と同じになるように設定します。必要に応じて、 リセット エンドポイントを使用して、ストリームを別の位置 (前方または後方) に設定できます。ストリームは、現在の位置から開始するコメントを返します。コメントキュー内のコメントの位置は、コメントをアップロードした順序で決定されます。

キューでの位置を上げる

ストリームは現在の位置からのコメントのみを返すため、 advance エンドポイントを使用して、各フェッチ要求の後にストリームを次の位置に進める必要があります。これにより、API はすべてのコメントが少なくとも 1 回は処理されることを保証します。バッチの処理中にアプリケーションが失敗した場合、再起動時に同じバッチが取得されます。

注:

アプリケーションは、コメントを正常に処理できるのに前進の手順で失敗することがあります。そのため、コメントが複数回出現することがあります。

アプリケーションの設計に応じて、次のいずれかを選択できます。

• バッチ全体に対して、ストリームを一度進めます。 応答に含まれるバッチの continuation を使用します。
• 個々のコメントごとにストリームを進めます。 応答に含まれるコメントの continuationを使用します。

コメントフィルター

ストリームの作成時に comment_filter を指定した場合、フィルターに一致しないコメントは結果に含まれませんが、リクエストされた max_filteredにカウントされます。すべてのコメント max_filtered フィルターで除外され、空の results 配列が表示される応答を確認できます。次の例では、8 つのコメントのバッチをリクエストしますが、すべてフィルターで除外されます。

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

フィルターされたコメントが要求されたmax_resultsにカウントされないようにするには、オプションの max_filtered 引数を渡します。

予測しきい値

注:

従来の /fetch ルートでは、信頼度のしきい値を満たさない予測を含むコメントは返されません。この新しい /results ルートでは、コメントのすべての予測と confidence``value も返します。また、満たすしきい値のタイプも指定します。

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

予測0.9905..のconfidenceとthresholds値は、予測がstreamに設定されたしきい値を満たしていることを示します。

オートメーションを構築するときは、 stream 値を探して、予測がストリームで設定したしきい値を満たしていることを確認します。また、 auto しきい値 が返される場合があり、これらの期待値は high_recall、 high_precisionおよび balancedです。

生成される抽出データの詳細と、しきい値の操作方法については、「 抽出データの検証について」および「抽出パフォーマンス」 をご覧ください。

要求の形式

名前	型	必須	説明
max_results	Number	×	このストリームに対してフェッチするコメントの数。 バッチの最後に到達した場合、またはコメント フィルターに従ってコメントを除外した場合、返されるコメントの数が少なくなります。最大値は 32 です。 デフォルトは 16 です。
max_filtered	Number	×	コメントフィルターを持つストリームの便利なパラメーター。 これらを指定すると、最大 max_filtered 件のフィルタリングされたコメントは、要求された max_resultsにカウントされません。 これは、多数のコメントがフィルターに一致しないと予想される場合に便利です。 コメント フィルターのないストリームには影響しません。 最大値は 1024 です。 デフォルトは null です。

応答の形式

名前	型	説明
status	string	ok 要求が成功したか、エラーの場合は errorです。エラー応答について詳しくは、「 概要 」ページをご覧ください。
num_filtered	Number	コメント フィルターに基づいて除外されたコメントの数。 フィルターなしでストリームを作成した場合、この数は常に 0です。
continuation	string	バッチ継続トークン。 これを使用して、このバッチの処理を確認し、ストリームを次のバッチに進めます。
more_results	Bool	要求を行ったときに、ストリームに追加の結果がなかった場合は true。 それ以外の場合は False です。
results	array<Result>	結果オブジェクトを含む配列。

ここで Result の形式は次のとおりです。

名前	型	説明
comment	コメント	コメント データ。詳しくは、「 コメントの参照」をご覧ください。
continuation	string	コメントの継続トークン。 このコメントの処理を確認し、ストリームを次のコメントに進めるために使用します。
prediction	array<Prediction>	このコメントの予測です。ストリームでモデル バージョンが指定されている場合にのみ使用できます。生成 AI による予測について詳しくは、「 Communications Mining™ - 抽出データの検証について」および「抽出パフォーマンス 」をご覧ください。

Prediction の形式は次のとおりです。

名前	型	説明
taxonomies	array<TaxonomyPrediction>	タクソノミー予測のリスト。 現在、データセットごとに定義する分類は 1 つだけですが、将来の互換性のためにリストとして指定します。

TaxonomyPrediction の形式は次のとおりです。

名前	型	説明
name	string	タクソノミーの名前。 現在、唯一の値は defaultです。
labels	array<LabelPrediction>	抽出されたラベル予測と、その occurrence_confidence、 extraction_confidence 、および抽出された fieldsのリストです。生成 AI による予測について詳しくは、「 Communications Mining - 抽出データの検証と抽出パフォーマンスについて 」をご覧ください。
general_fields	array<FieldPrediction>	抽出された一般フィールドの予測とその name および抽出された valueのリストです。生成 AI による予測について詳しくは、「 Communications Mining - 抽出データの検証と抽出パフォーマンスについて 」をご覧ください。