エンティティオプション

エンティティ一致とデータ抽出の動作を変更するエンティティオプションがいくつかあります。これらのオプションはシステムエンティティ向けに事前構成されているので、システムエンティティ向けには変更できません。ただし、独自のカスタムエンティティ向けに変更することは可能です。選択したオプションに応じて、さまざまな種類のエンティティを作成できます。

マップエンティティ
リストエンティティ
複合エンティティ（特別な種類のリストエンティティ）
正規表現エンティティ

また、他のオプションは、エンティティの種類を決定しませんが、エンティティ一致の動作に影響します。

自動拡張
ファジー一致
ログ内での秘匿化
エンティティの除外

このドキュメントでは、上記の各オプションについて説明します。

このデータがある場所

エージェントを作成する際は、Dialogflow CX コンソール（ドキュメントに移動、コンソールを開く）を使用するのが最も一般的です。コンソールの使用方法は次のとおりです。エンティティオプションのデータにアクセスするには、次の手順を行います。

Dialogflow CX Console を開きます。
ご自身の Google Cloud プロジェクトを選択します。
エージェントを選択します。
[Manage] タブを選択します。
[エンティティタイプ] をクリックします。
既存のエンティティには、次のオプションがあります（一部は [詳細オプション] を展開した後にのみ表示できます）。
- エンティティのみ（類義語なし）
- 正規表現エンティティ
- エンティティの自動追加
- ファジー一致
- ログ内での秘匿化
- エンティティの除外

コンソールではなく API を使用してエージェントをビルドする場合は、EntityType タイプをご覧ください。API のフィールド名はコンソールのフィールド名と同様です。以下の手順では、コンソールと API の間の重要な相違点に重点を置いて説明します。

EntityType リファレンスのプロトコルとバージョンを選択:

プロトコル	V3	V3beta1
REST	EntityType リソース	EntityType リソース
RPC	EntityType インターフェース	EntityType インターフェース
C++	EntityTypesClient	利用できません
C#	EntityTypesClient	利用できません
Go	EntityTypesClient	利用できません
Java	EntityTypesClient	EntityTypesClient
Node.js	EntityTypesClient	EntityTypesClient
PHP	利用不可	利用できません
Python	EntityTypesClient	EntityTypesClient
Ruby	利用不可	利用できません

マップエンティティ

マップエンティティは、参照値からそれぞれの参照値の類義語へのマップを提供します。マップエンティティの各エントリには、1 つの参照値と複数の類義語のリストが含まれます。必要に応じて、エンティティごとに DTMF パターンを設定することもできます。

たとえば、以下の各行は size エンティティタイプのエンティティエントリです。

エンティティ	類義語	DTMF パターン
S	S、small、tiny、little
M	M、medium、average
L	L、large、huge、big

上記の各エンティティエントリの類義語リストに、参照値が含まれていることに注意してください。参照値を一致させるには、参照値自体を同義語として含める必要があります。最初にコンソールで参照値を入力すると、それが自動的に類義語として追加されます。

いずれかの類義語がエンドユーザー入力の一部に一致する場合、関連する参照値が一致として抽出され、それを使って関連するパラメータ値が解決されます。

参照値を類義語リストから省略してもかまいません。その場合、参照値そのものはエンドユーザー入力の一部に一致しませんが、類義語のいずれかが一致した場合に抽出値として使用されます。これは、エンドユーザーによって入力 / 発話されない参照値として特殊な文字列を使用する場合に適しています。

システムエンティティの多くはマップエンティティです。たとえば、@sys.date システムエンティティは、「January 1, 2015」や「The first of January of 2015」といった一般的な日付参照に一致します。どちらの入力も ISO-8601 形式の参照値「2015-01-01T12:00:00-03:00」にマッピングされます。

マップエンティティを作成するには、次の手順を行います。

コンソールを使用して [Regexp entities] オプションをオフにし、[Entities only] オプションをオンにします。
API を使用して、[EntityType.kind] フィールドを KIND_MAP に設定します。

リストエンティティ

リストエンティティは、単一値のエンティティエントリからなるリストを提供します。参照値と類義語はありません。たとえば、以下の各行は material エンティティタイプのエンティティエントリです。

値
ファブリック
木材
金属

いずれかの値がエンドユーザー入力の一部に一致する場合、関連する値が一致として抽出され、それを使って関連するパラメータ値が解決されます。

多くのシステムエンティティはリストエンティティです。たとえば、@sys.color システムエンティティは、「red」や「blue」などの一般的な色の入力をマッチングします。色が一致した場合、抽出された値は参照値にマッピングされません。たとえば、「scarlet」や「crimson」などの赤の色調は、「red」にマッピングされずに元の値「scarlet」、「crimson」のまま抽出されます。

リストエンティティを作成するには、次の手順を行います。

コンソールを使用して [Regexp entities] オプションをオフにし、[Entities only] オプションをオンにします。
API を使用して、[EntityType.kind] フィールドを KIND_LIST に設定します。

複合エンティティ

複合エンティティは特別な種類のリストエンティティです。通常、リストエンティティのエンティティエントリに含まれるのは簡単な単語やフレーズですが、他のエンティティタイプが含まれることもあります。あるエンティティタイプが他のエンティティタイプで参照されている場合、その参照はエイリアスと呼ばれます。他のエンティティタイプへのエイリアスを含むリストエンティティは、複合エンティティと呼ばれます。

エイリアスを作成するときは、参照されるエンティティタイプの名前と、選択したプロパティ名を指定します。実行時に複合エンティティが一致すると、抽出された値は JSON オブジェクトとして返され、エイリアスプロパティ名が JSON プロパティ名として使用されます。エイリアスの入力形式は次のとおりです。

@entity-name:property-name

たとえば、次のエンティティエントリを含む、市または州に一致する place エンティティタイプを作成できます。

値
@sys.geo-city:city
@sys.geo-state:state

エンドユーザー入力の一部に「Nashville」が含まれている場合、place エンティティタイプが一致します。抽出された値は {"city": "Nashville"} のように返されます。

1 つのエンティティエントリに複数のエンティティエイリアスを使用することもできます。direction エンティティタイプと @sys.number システムエンティティタイプのエイリアスをそれぞれ含む以下の move カスタムエンティティタイプを指定したとします。

方向カスタムマップエンティティタイプ:

参照値	類義語
進む	forward、forwards
戻る	back、backward、backwards

移動カスタムリストエンティティタイプ:

値
@sys.number:steps steps @direction:direction

move エンティティが「five steps backward」を含むエンドユーザー入力に一致する場合、move エンティティが一致します。抽出された値は {"steps": 5, "direction": "back"} のように返されます。

システムエンティティの多くは複合エンティティです。たとえば、@sys.unit-currency システムエンティティは、通貨の名前で示された金額のマッチングに使用されます。「50 euros」や「twenty dollars and five cents」などのエンドユーザー入力を照合します。抽出された値は、{"amount": 50, "currency": "EUR"} のような JSON オブジェクトとして返されます。

正規表現エンティティ

正規表現エンティティを使用すると、正規表現のマッチングを行うことができます。詳細については、正規表現エンティティをご覧ください。

正規表現エンティティを作成するには、次の手順を行います。

コンソールを使用して [Regexp entities] オプションにチェックを入れます。
API を使用して、[EntityType.kind] フィールドを KIND_REGEXP に設定します。

自動拡張（エンティティの自動追加）

カスタムエンティティタイプ向けの自動拡張機能を有効にできます。有効にすると、エージェントは明示的に提供されていない値を認識できるようになります。たとえば、ショッピングリストのエンティティタイプを次のように指定したとします。

値
パン
butter
milk
apple
アイスクリーム

「ニンジンを買う必要がある」というエンドユーザー入力の場合、「ニンジン」が含まれていなくても、このエンティティタイプに一致します。エージェントは、「ニンジン」が他の値と文脈上類似していることを認識します。

自動拡張を検討する際は、次のおすすめの方法に従ってください。

自動拡張を有効にしても、エンティティの抽出は保証されません。有限なリストの場合、リストの一部を指定して自動拡張を有効にするのではなく、完全なリストを指定してください。
複数のエンティティで自動拡張を有効にすると、競合や予期しない分類結果が生じる可能性があります。
パラメータの抽出品質を向上させるには、予想されるエージェントのトラフィックで特定のエンティティが見つかるすべてのユースケースを網羅する多様なトレーニングデータを提供することが重要になります。サンプルが不十分な場合、エンティティの自動拡張が想定どおりに機能しない可能性があります。

自動拡張を有効にするには、次の手順を行います。

コンソールを使用して、[Automatically add entities] オプションをオンにします。
API を使用して、[EntityType.autoExpansionMode] フィールドを AUTO_EXPANSION_MODE_DEFAULT に設定します。

ファジー一致

カスタムエンティティのファジー一致を有効にできます。ファジー一致が有効な場合、値または類義語における単語の順序は関係ありません。詳細については、ファジー一致をご覧ください。

ファジー一致を有効にするには、次の手順を行います。

コンソールを使用して [Fuzzy matching] オプションをオンにします。
API を使用して、[EntityType.enableFuzzyExtraction] フィールドを true に設定します。

ログ内での秘匿化

エンティティ秘匿化を有効にすると、ロギング時に、エンティティタイプのランタイム抽出パラメータ値がすべて秘匿化されます。

代わりに、個々のパラメータを秘匿化することもできます。

エンティティの除外

エンティティの除外を追加できます。これは、一致することを回避する必要があるフレーズです。たとえば、サイズエンティティタイプに巨大な（形容詞）のエンティティがある場合は、巨人（名詞）を除外することを検討してください。

エンティティ

システムエンティティ

エンティティ オプション