Named entity recognition API の使用

Sterling には、自然言語テキストを分析し、ドメイン固有のエンティティーを検出する Named entity recognition (NER) サービスが用意されています。このサービスは、 Supply Chain Intelligence Suite data platformと緊密に統合されています。

named entity recognition サービスは Supply Chain Intelligence Suite data platform を 1 次データ・ソースとして使用するため、 Control Tower内の名前付きエンティティーを認識するようにサービスをトレーニングする必要はありません。サービスは、以下のエンティティーを認識するように事前構成されています。

Supply Chain Intelligence Suite data platform データ・モデルへのエンティティー・タイプのマッピング

エンティティ・タイプ	Supply Chain Intelligence Suite data platform オブジェクト (object)	Supply Chain Intelligence Suite data platform 属性
`category_name`	カタログ	`code`
`location_locationIdentifier`	場所	`locationIdentifier`
`location_name`	場所	`locationName`
`location_group`	場所	`locationGroupName`
`product_name`	プロダクト	`name`
`part_number`	プロダクト	`partNumber`
`product_plannerCode`	プロダクト	`plannerCode`
`organization_name`	組織	`name`
`organization_identifier`	組織	`organizationIdentifier`
`order_orderIdentifier`	順序	`orderIdentifier`

方法

recognize メソッドは、自然言語テキストを入力として分析し、認識されたエンティティーを持つ JSON オブジェクトを返します。

curl -X POST https://api.ibm.com/scassistant/bluerun/named-entities/na/recognize \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --header 'X-IBM-Client-Id: <put Client-Id here>' \
   --header 'Authorization: Bearer <put JWT here>' \
   -d '{"text": "show me inventory for category pharma"}'

応答は、テキスト内で検出された名前付きエンティティーのすべての言及を含む JSON オブジェクトです。

{
  "category_name": {
    "value": "Pharma",
    "literal": "pharma",
    "confidence": 1,
    "location": [
      31,
      37
    ],
    "values": [
      "Pharma"
    ],
    "count": 1,
    "list": [
      {
        "value": "Pharma",
        "literal": "pharma",
        "confidence": 1,
        "location": [
          31,
          37
        ]
      }
    ]
  },
  "@category_name": "Pharma"
}

JSON オブジェクトのキーはエンティティー・タイプ (例えば、 category_name または location_city) に対応しますが、値は JSON オブジェクト自体であり、以下のフィールドが含まれます。

リテラル: 入力テキスト内で検出されたエンティティーの言及。
値: エンティティーの正規化された値 (例えば、 Pharma または San Francisco)。この値は、データを取得するために GraphQL 照会で使用できます。
ロケーション: センテンス内のエンティティーの位置。
信頼度: 信頼性レベルを表す 0 から 1 の範囲の数値。値 1 は 100% 確信しています。
価値: すべてのエンティティー値を含むストリングの配列。
数: 異なるエンティティー値の数。
リスト: すべてのエンティティー・メンションを含む配列。

values、 count、および list プロパティーは、入力テキストに同じエンティティー・タイプの複数のメンションが含まれている場合に役立ちます。複数の値が予期されない場合は、上記のすべての値にアクセスしたり、フォローアップの質問をしたりすることができます。

NER と Watson Assistant の統合

/recognize API は、 Watson Assistant スキルから直接使用できます。この API を呼び出すには、スキル内で Webhook を構成する必要があります。 Watson Assistantウェブフックの詳細については、ダイアログからのプログラムコールを参照してください。

Webhook の構成

Watson Assistantにログインします。
ダイアログ・スキルに移動し、「オプション」をクリックします。
Webhook URL を以下の recognize エンドポイントに設定します。
```
https://api.ibm.com/scassistant/bluerun/named-entities/na/recognize
```
以下のヘッダーを設定します。
Web フックのヘッダー
ヘッダー名ヘッダー値
承認以下の値を使用します。
Bearer $integrations.chat.private.jwt
X-IBM®-クライアント ID クライアント ID。

ヘッダー名	ヘッダー値
承認	以下の値を使用します。 `Bearer $integrations.chat.private.jwt`
X-IBM®-クライアント ID	クライアント ID。

Webhook の呼び出し

NER サービスを使用するダイアログ・ノードに移動します。
「カスタマイズ」をクリックします。
「Callout to webhooks/actions」のスキルを有効にし、「Call a webhook」を選択します。
「Then call to my webhook」で、ユーザーからの入力テキストを指定します。

キー値

テキスト "<? input.text ?>"
「戻り変数」の下で、結果を sterling_entitiesなどのコンテキスト変数に入れることができます。
Web フックを呼び出した後、「アシスタントが認識した場合」でコンテキスト変数を使用して、エンティティーがあるかどうかを確認できます。「スキル・インターフェースの実装」セクションで説明されている応答形式に準拠するには、 Watson Assistant の条件付き応答機能を使用して、 anything else 条件を追加することで、NER API の呼び出しが成功したか失敗したかを区別します。 Webhook 障害が発生すると、INTERNAL_ERROR 応答状況コードが返されます。
「試行する (Try it out)」オプションを使用してダイアログ・ノードをテストする場合、「コンテキストの管理」タブに移動して、ステップ 4 のコンテキスト変数を手動で作成し、JWT 資格情報を保管して NER API に渡すことができます。呼び出しが戻った後、ステップ 5 で定義した戻り変数値で、Webhook によって返された値を確認できます。

キー	値
テキスト	`"<? input.text ?>"`

明確化

入力に同じエンティティー・タイプの複数のメンションがある場合は、 values 配列と list 配列に複数の項目が表示されます。例えば、 What's available in San Francisco and New York? という文は、以下のエンティティーを含んでいると認識されます。

{
  "location_city": {
    "value": "San Francisco",
    "literal": "San Francisco",
    "confidence": 1,
    "location": [20, 33],
    "values": ["San Francisco", "New York"],
    "count": 2,
    "list": [
      {
        "value": "San Francisco",
        "literal": "San Francisco",
        "confidence": 1,
        "location": [20, 33]
      },
      {
        "value": "New York",
        "literal": "New York",
        "confidence": 1,
        "location": [38, 46]
      }
    ]
  },
  "@location_city": "San Francisco"
}

Sterling 接続アシスタントの推奨パターンは、ダイアログ・ツリーの開始時に他のダイアログ処理の前に実行される専用ダイアログ・ノードに NER 呼び出しを配置することです。その後、API 呼び出しから返された値がコンテキスト変数に配置されます。これにより、すべてのユーザー入力が認識のために名前付きエンティティー・サービスに提示され、スキル内の複数のダイアログ・ノードから名前付きエンティティー API を呼び出す必要がなくなります。