Communications Mining - ストリーム

ストリームからコメントを取得する

必要なアクセス許可: ストリームの使用、ラベルの表示、ソースの表示。

注:

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

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

ノード

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

レスポンス

{
  "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": "<abcdef@abc.company.com>",
          "string:Sender": "alice@company.com",
          "string:Sender Domain": "company.com",
          "string:Thread": "<abcdef@abc.company.com>"
        },
        "messages": [
          {
            "from": "alice@company.com",
            "to": [
              "bob@organisation.org"
            ],
            "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"
}{
  "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": "<abcdef@abc.company.com>",
          "string:Sender": "alice@company.com",
          "string:Sender Domain": "company.com",
          "string:Thread": "<abcdef@abc.company.com>"
        },
        "messages": [
          {
            "from": "alice@company.com",
            "to": [
              "bob@organisation.org"
            ],
            "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"
}{
  "filtered": 8,
  "results": [],
  "sequence_id": "qs8QcHIBAADJ1p3W2FtmBB3QiOJsCJlR",
  "status": "ok"
}

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

予測しきい値

手記：従来の /fetch ルートでは、信頼度のしきい値を満たさなかった予測を含むコメントは返されません。

この新しい/resultsルートでは、コメントのすべての予測とconfidencevalueも返します。また、どのタイプのしきい値を満たすかも示します。

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

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

オートメーションを構築するときは、予測がストリームで設定したしきい値を満たしていることを確認するために、 stream 値を探します。

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

要求の形式

名前	型	必須	説明
`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>	このコメントの予測。ストリームでモデルバージョンが指定されている場合にのみ使用できます。生成的予測について詳しくは、「 Communications Mining - 抽出の検証について」および「抽出のパフォーマンス」をご覧ください。

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

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

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

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

ストリーム