ラベルと一般フィールド

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

ラベル

コメントには、0 個、1 個、または複数の予測ラベルを含めることができます。次の例は、予測された 2 つのラベル Order と Order > Missing を、その信頼度スコアとともに示します。ほとんどの API ルートではこの形式が使用されます。データセットのエクスポート ルートは例外です。このルートでは、ブラウザーでの CSV エクスポート時の一貫性を保つために、ラベル名をリストではなく文字列として書式設定します。

一部のルート (現在は [ルートを予測]) では、必要に応じて、ラベルの信頼度スコアが満たすしきい値名 (「high_recall」、「balanced」、「high_precision」など) のリストが返されます。これは、特に非常に大きなタクソノミーの場合に、しきい値を手動で選択する代わりに便利です。アプリケーションで、「high_recall」、「バランス」、または「high_precision」のどの結果に注目するかを決定し、選択した自動しきい値を持たないラベルをすべて破棄して、残りのラベルを以前と同様に処理します。

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

{
  "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 つずつ処理する場合は無視できます。

ラベル名は以下の条件を満たす必要があります。

• Unicode の単語文字 (非特定文字や句読点など) から始めます。
• 次の表に示す単語文字、スペース、または特殊文字を任意に組み合わせて使用できます。

たとえば、 Hello World! は有効で、 !Hello World は無効です。

特殊文字	名前
~	チルダ
!	感嘆符
@	サインで
#	ハッシュ記号
$	ドル記号
€	ユーロ記号
%	パーセント記号
^	キャレット
&	アンパサンド
*	アスタリスク
(	左括弧
)	右括弧
_	アンダースコア
+	正号
-	ハイフン
=	等号
[	左角括弧
]	右角括弧
{	左中括弧
}	右中括弧
;	セミコロン
'	アポストロフィー
\	バックスラッシュ
:	コロン
"	引用符
|	縦棒
,	コンマ
.	期間
/	スラッシュ
<	小なり記号
?	疑問符

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

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

重要:

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

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

分析でのラベルの使用

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

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

ラベルに関する FAQ

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

A: ラベルを提供するダウンロード方法は、Communications Mining、 CSV ダウンロード、Communications Mining コマンドライン ツールです。利用可能なダウンロード方法の概要については「 データのダウンロード 」ページ、詳細な比較については次のFAQ項目を確認してください。

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

A: ダウンロード方法の違いは、下表のとおりです。比較のために、Communications Mining の Web UI の [探索] ページのラベルの説明が表示されます。

非決定論的方法

[探索] ページ、CSV のダウンロード、Communications Mining のコマンドライン ツール、および Export API エンドポイントにより、利用可能な最新の予測が提供されます。

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

一般フィールド

コメントには、0 個、1 個、または複数個の一般フィールドが予測できます。次の例は、予測された order_number エンティティの 1 つを示しています。

メモ: 一般フィールドはラベルと異なり、信頼度スコアが関連付けられていません。

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

通貨の書式

各エンティティには span と formatted_valueがあります。範囲は、対応するコメント内のエンティティの境界を表します。この formatted_value は通常、その範囲に含まれるテキストに対応していますが、以降のセクションで説明する特定のインスタンスを除きます。

金額

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: Communications Mining および Communications Mining のコマンドライン ツールをダウンロードする方法で一般フィールドを利用できます。「データをダウンロードする」の概要を見て、ユースケースに適した方法を理解してください。CSV のダウンロードには一般フィールドは含まれません。

モデル

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

連携を使いやすくするために、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	モデルのバージョン。