ラベルと一般フィールド

このページでは、 Communications Mining™ プラットフォームからダウンロードした ラベルと一般フィールドを、アプリケーションで使用するために解釈する方法について説明します。このページでは、ラベルと一般フィールド自体について説明します。ダウンロードしたデータのどこにラベルと一般フィールドがあるかを理解するには、選択したダウンロード方法のドキュメントを確認してください。

ラベル

A comment can have zero, one, or multiple predicted labels. The following example shows two predicted labels, Order and Order > Missing, together with their confidence scores. Most API routes use this format. An exception is the Dataset Export route, which formats label names as strings instead of lists to be consistent with the CSV export in the browser.

Some routes, which are currently Predict routes, will optionally return a list of threshold names, such as "high_recall", "balanced", "high_precision" that the label confidence score meets. This is a useful alternative to hand-picking thresholds, especially for very large taxonomies. In your application, you decide whether you are interested in "high_recall", "balanced", or "high_precision" results, then discard all labels that lack your chosen auto-threshold, and process the remaining labels as before.

データセットのエクスポートを除くすべてのルート

{
  "labels": [
    {
      "name": ["Order"],
      "probability": 0.6598735451698303
    },
    {
      "name": ["Order", "Missing"],
      "probability": 0.6598735451698303
    }
  ]
}

データセットのエクスポート

{
  "labels": [
    {
      "name": "Order",
      "probability": 0.6598735451698303
    },
    {
      "name": "Order > Missing",
      "probability": 0.6598735451698303
    }
  ]
}

予測 (自動しきい値)

{
  "labels": [
    {
      "name": ["Order"],
      "probability": 0.6598735451698303,
      "auto_thresholds": ["high_recall", "balanced", "sampled_2"]
    },
    {
      "name": ["Order", "Missing"],
      "probability": 0.6598735451698303,
      "auto_thresholds": ["high_recall", "sampled_2"]
    }
  ]
}

Label オブジェクトの形式は次のとおりです。

名前	入力	説明
name	array<string> または string	データセットのエクスポートを除くすべての API ルート: 階層ラベルのリストとして書式設定された、予測されたラベルの名前。 たとえば、[ 親ラベル] > [子ラベル ] というラベルの形式は、 ["Parent Label", "Child Label"]になります。 データセットのエクスポート API ルート: 階層ラベルを " > " 区切りた文字列として書式設定された、予測されたラベルの名前。
probability	number	信頼度スコア。 0.0 から 1.0 までの数値。
sentiment	number	センチメント スコア。 -1.0 から 1.0 までの数値。 データセットでセンチメントが有効になっている場合にのみ返されます。
auto_thresholds	array<string>	ラベルの信頼度スコアが満たす、自動的に計算されるしきい値のリストです。 しきい値は、(0.0 から 1 の間の値ではなく) わかりやすい名前として返されます。これを使用して、目的の信頼レベルを満たさないラベルを簡単に除外できます。 しきい値名 "high_recall"、"バランス"、および "high_precision" は、3 つの増加する信頼レベルに対応します。 追加の「sampled_0」..."sampled_5" しきい値は、データ サイエンス アプリケーションの集計を実行するためのより高度な方法を提供し、コメントを 1 つずつ処理する場合は無視できます。

Label names must:

• Start with any unicode word character, for example, non-specical characters or punctuation.
• Contain any combination of word characters, spaces, or any of the special characters listed in the following table.

For example Hello World! is valid but !Hello World is not.

Special character	名前
~	Tilde
!	Exclamation mark
@	At sign
#	Hash sign
$	Dollar sign
€	Euro sign
%	Percent sign
^	Caret
&	Ampersand
*	アスタリスク
(	Left parenthesis
)	Right parenthesis
_	Underscore
+	Plus sign
-	Hyphen
=	Equals sign
[	Left square bracket
]	Right square bracket
{	Left curly brace
}	Right curly brace
;	Semicolon
'	Apostrophe
\	バックスラッシュ
:	コロン
"	引用符
|	縦棒
,	Comma
.	期間
/	Forward slash
<	小なり記号
?	疑問符

オートメーションでラベルを使用する

メッセージごとに判断を下すアプリケーションを設計する場合は、各ラベルの信頼度スコアを「はい」または「いいえ」の回答に変換する必要があります。そのためには、予測が「はい、ラベルが適用されます」を意味していると見なす、最小信頼度スコアを決定します。この数値を信頼度スコアのしきい値と呼びます。

重要:

信頼度スコアのしきい値を選択する方法

よくある誤解は、実現したい精度と同じ値にしきい値を設定することです (「ラベルの正解率を 70% 以上にするため、信頼度スコアが 0.70 を超えるラベルを選択する」)。しきい値とその選択方法については、「 ラベルの信頼度のしきい値を選択する」をご覧ください。

分析でのラベルの使用

分析アプリケーションで使用するためにラベルをエクスポートする場合は、信頼度スコアをユーザーに公開するかどうかを決定することが重要です。 ビジネス分析アプリケーションのユーザーの場合は、「 自動化 」セクションで説明されているアプローチのいずれかを使用して、信頼度スコアをラベルの有無に変換する必要があります。 一方、確率的データの操作に習熟しているデータサイエンスアプリケーションのユーザーは、生の信頼度スコアにアクセスできるというメリットがあります。

重要な考慮事項は、分析アプリケーションのすべての予測が同じモデル バージョンからのものであることを確認することです。 新しいモデルバージョンから予測を取得するように統合をアップグレードする場合、データの一貫性を維持するために、すべての予測を再取り込みする必要があります。

ラベルに関する FAQ

Q: Communications Mining™ プラットフォームからラベルをダウンロードするにはどうすればよいですか?

A: The following download methods provide labels: Communications Mining , CSV downloads, and Communications Mining command-line tool. Check the Downloading Data page for an overview of the available download methods, and the following FAQ item for a detailed comparison.

Q: すべてのダウンロード方法で同じ情報が提供されますか?

A: The following tables explain the differences between the download methods. A description of labels in the Explore page in the Communications Mining web UI is provided for comparison.

非決定論的方法

The Explore page, CSV download, Communications Mining command-line tool, and the Export API endpoint provide the latest available predictions.

手記： 新しいモデル バージョンをトレーニングした後、すべての予測が再計算される前に、最新のモデル バージョンと以前のモデル バージョンが混在する予測に気付くでしょう。これらのメソッドは、割り当てられたラベルを認識し、そのラベルを割り当て済みとして、または信頼度スコアが 1 で表示します。

方式	割り当てられたラベル	予測ラベル
探索ページ	[検索] ページでは、割り当てられたラベルと予測されたラベルが視覚的に区別されます。 割り当てられたラベルの信頼度スコアは報告されません。	[検索] ページは、モデルのトレーニング ワークフローをサポートするように設計されているため、ユーザーがピン留めできる予測ラベルが選択されて表示されます。 バランスのとれたしきい値 (そのラベルの F スコアから派生) を満たすラベルが優先的に表示されますが、ユーザーがピン留めする可能性がある場合は、提案として確率の低いラベルを表示することもできます。
エクスポート API	割り当てられたラベルを返します。	予測されたすべてのラベルを返します (しきい値は適用されません)。
CSV をダウンロードする	割り当てられたラベルの信頼度スコア 1 を返します。 モデルの信頼度が高い場合、予測ラベルのスコアも 1 になることがあります。	予測されたすべてのラベルを返します (しきい値は適用されません)。
Communications Mining の CLI	コメントにラベルが割り当てられている場合は、そのコメントに割り当てられたラベルと予測されたラベルの両方を返します。	予測されたすべてのラベルを返します (しきい値は適用されません)。

決定論的方法

以前の非決定論的な方法とは対照的に、Stream API ルートと Predict API ルートは特定のモデル バージョンからの予測を返します。したがって、これらの API ルートは、プラットフォームからコメントをダウンロードし、特定のモデル バージョンに対する予測のためにコメントを送信した場合と同様に動作し、割り当てられたラベルを認識しません。

方式	割り当てられたラベル	予測ラベル
ストリーム API と予測 API	割り当てられたラベルを認識しません。	信頼度スコアが指定されたラベルしきい値を超える (しきい値が指定されていない場合は既定値の 0.25 を上回る) 予測ラベルを返します。

ラベルのプロパティ

データセットにサービス品質 (QoS) ラベルが追加されている場合は、予測の応答に各コメントのサービス品質 (QoS) スコアが含まれます。データセットでトーンが有効化されている場合は、予測の応答に各コメントのトーン スコアが含まれます。どちらのスコアも、応答の label_properties の部分にあります。

{
  "label_properties": [
    {
      "property_id": "0000000000000001",
      "property_name": "tone",
      "value": -1.8130283355712891
    },
    {
      "id": "0000000000000002",
      "name": "quality_of_service",
      "value": -3.006324252113699913
    }
  ]
}

ラベル プロパティ オブジェクトの形式は次のとおりです。

名前	型	説明
name	string	ラベル プロパティの名前。
id	string	ラベル プロパティの内部 ID。
value	Number	ラベル プロパティの値。 -10 から 10 までの値。

一般フィールド

A comment can have zero, one, or multiple predicted general fields. The following example shows one predicted order_number entity.

Note: Unlike labels, general fields do not have associated confidence scores.

"entities": [
    {
        "id": "0abe5b728ee17811",
        "name": "order_number",
        "span": {
            "content_part": "body",
            "message_index": 0,
            "utf16_byte_start": 58,
            "utf16_byte_end": 76,
            "char_start": 29,
            "char_end": 38
        },
        "name": "order_number",
        "kind": "order_number", # deprecated
        "formatted_value": "ABC-123456",
        "capture_ids": []
    }
]

API は、次の形式でエンティティを返します。

名前	型	説明
id	string	エンティティ ID。
name	string	エンティティ名。
kind	string	(非推奨)エンティティの種類。
formatted_value	string	エンティティ値。
span	Span	コメント内のエンティティの場所を格納するオブジェクト。
capture_ids	array<int>	エンティティが属するグループの キャプチャ ID 。

通貨の書式

Each entity has a span and a formatted_value. The span represents the boundaries of the entity in the corresponding comment. The formatted_value typically corresponds to the text covered by that span, except in some specific instances that we describe in the sections that follow.

金額

Monetary Quantityエンティティは、さまざまな金額を抽出し、共通の書式設定を適用します。たとえば、"1M USD"、"USD 1000000"、"1,000,000 usd" はすべて 1,000,000.00 USDとして抽出されます。 抽出された値は一貫した方法でフォーマットされるため、空白で分割することで通貨と金額を簡単に取得できます。

ただし、通貨があいまいな場合、抽出された値ではあいまいな通貨が保持されます。 たとえば、「$1M」と「$1,000,000」は、米ドルだけでなくカナダドルまたはオーストラリアドルも指す可能性があるため、「$1M」と「$1,000,000」は1,000,000.00 USDではなく$1,000,000.00として抽出されます。

日付

Date エンティティは、コメントに表示される任意の日付を抽出し、標準の ISO 8601 形式を使用して正規化し、その後に UTC の時刻を正規化します。たとえば、2020 年 1 月 25 日に送信されたメールの「Jan 25 2020」、「25/01/2020」、「now」はすべて「2020-01-25 00:00 UTC」として抽出されます。

この書式設定は、キャンセル日、起算日、またはユーザーがトレーニングした任意の種類の日付など、日付に対応する型を持つすべてのエンティティに適用されます。

日付の一部が欠落している場合、コメントのタイムスタンプがアンカーとして使用されます。2020 年 5 月 1 日に送信されたメッセージの「毎月 5 日の午後 4 時」の日付は、「2020-05-05 16:00 UTC」として抽出されます。 タイムゾーンが指定されていない場合、コメントのタイムゾーンが使用されますが、抽出された日付は常にUTCタイムゾーンで返されます。

Country (国)

国名は共通の値に正規化されます。たとえば、文字列 "UK" と "United Kingdom" はどちらも、"United Kingdom" という書式設定された値を持ちます。

ID のキャプチャ

コメントがリッチ テキストとして処理され、テーブルが含まれ、そのテーブルでエンティティが一致した場合、そのエンティティの capture_ids プロパティにはキャプチャ ID が含まれます。 テーブルの同じ行で一致したエンティティは同じキャプチャ ID を持つため、グループ化できます。

たとえば、 Order ID を Order Dateに関連付けることができます。 複数の注文が参照されているコメントでは、キャプチャ ID でエンティティをグループ化することで、異なる注文の詳細を区別できます。

現在、テーブルで一致したエンティティは正確に 1 つのグループに属します。つまり、それらの capture_ids プロパティには ID が 1 つだけ含まれます。 将来、API は複数の ID を返す可能性があります。

それ以外の場合、 capture_id プロパティは空のリストになります。

手記： CSV アップロードまたは API を使用してテキストを更新する際にエンティティが保持されるようになりました。

一般フィールドに関する FAQ

Q: Communications Mining™ プラットフォームから一般フィールドをダウンロードするにはどうすればよいですか?

A: The following download methods provide general fields: Communications Mining and Communications Mining command-line tool. Please take a look at the Downloading Data overview to understand which method is suitable for your use-case. Note that CSV downloads will not include general fields.

モデル

ステージングタグとライブタグ

連携を使いやすくするために、Communications Mining™ の UI でモデル バージョンを staging または [ live ] としてタグ付けできます。このタグは、モデルのバージョン番号の代わりに Predict API 要求に指定できます。これにより、連携では [ステージング] または [ライブ] タグが指すモデル バージョンから予測を取得できます。これらのバージョンは、Communications Mining の UI から簡単に管理できます。

モデル バージョンの詳細

特定のモデル バージョンの詳細は、検証 API エンドポイントを使用して取得できます。

さらに、予測要求への応答には、予測の作成に使用されたモデルに関する情報が含まれます。

"model": {
    "version": 2,
    "time": "2021-02-17T12:56:13.444000Z"
}

名前	型	説明
time	Timestamp	モデルのバージョンがピン留めされた日時。
version	Number	モデルのバージョン。