はじめに

Watson Discovery には文書から意味を抽出してタグ付けをする機能が豊富にあります。最近ではwebhookを利用して文書にアノテーションを付けるための外部エンリッチ機能が提供されています。
これにより、watsonx.ai などの基盤モデルを利用して、文書にタグ付けができるようになります。付与されたタグは文書検索の絞り込みや分析条件に利用できます。
ここでは、watsonx.aiの基盤モデルを利用して、Eメールからエンティティ（人名,会社名,場所など）を抽出する手順を紹介します。
基盤モデルとしては、IBMのGraniteを利用しています。

準備

実行環境

IBM Cloud で提供している以下のサービスを利用します。これらのサービスをIBM Cloudで利用できるように作成します。

Discoveryは30日間の無料トライアル、watsonx.aiとCodeEngineは無料枠で試すことができます。

エンリッチアプリケーションを Code Engineにデプロイ

今回のサンプルは、Webhook エンリッチを適用するための環境として IBM Cloud Code Engine を使用しています。他の環境にアプリケーションをデプロイすることもできます。

IBM Cloud Code Engine でプロジェクトを作成

Code Engine コンソールの「プロジェクト」ページから、作成をクリックします。

情報を入力
ロケーション を選択
作成するプロジェクトの名前を入力
リソースグループ　を選択
「作成」をクリック

プロジェクト内にシークレットを作成します

作成したプロジェクトで「シークレット及び configmap」を選択

「作成」をクリック

オプションの選択で 「シークレット」 を選択
名前：「任意の名前」　（後で利用します）
「キーと値のペアを追加」をクリック

WD_API_URL: Discoveryインスタンスの資格情報にある URL
WD_API_KEY: Discoveryインスタンスの資格情報にある API鍵
WEBHOOK_SECRET: アプリケーションの認証に使用する任意の文字列 （DiscoveryのWebhook登録時に使用）
IBM_CLOUD_API_KEY: IBM Cloudの API キー
WML_ENDPOINT_URL: Watson Machine Learningの API エンドポイントURL。watsonx.aiがダラスの場合は https://us-south.ml.cloud.ibm.com です。詳細はマニュアルを参照
WML_INSTANCE_CRN: Watson Machine Learning のインスタンスの ID。 IBM Cloudのリソースリストから確認できます。（crn:で始まる文字列）

サンプルリポジトリーのソースコードからアプリケーションをデプロイ

プロジェクトで「概要」を選択

「アプリケーション作成」をクリック

名前： [任意の名前]
実行するコードの選択： ソース・コード
ソース・コード URL： https://github.com/watson-developer-cloud/doc-tutorial-downloads

「ビルド詳細の指定」をクリック

コード・リポジトリURL： https://github.com/watson-developer-cloud/doc-tutorial-downloads
コード・リポジトリー・アクセス： なし
ブランチ名： master
コンテキスト・ディレクトリー： discovery-data/webhook-enrichment-sample/granite
戦略： 「Dockerfile」　を選択

下にスクロールして、「環境変数（オプション）」を選択

「追加」をクリック

定義タイプ：　「シークレット全体の参照」を選択
シークレット： [前のステップでプロジェクトに作成したシークレットの名前]を入力

アプリケーションの作成

「作成」をクリックしてアプリケーションを作成します

Watson DiscovryでWebhook エンリッチメントの構成

Webhook エンリッチメントの登録

Discovery API を使用して Webhook エンリッチを作成します。

Webhookエンリッチメントの登録は、以下のフォーマットです

curl -X POST {auth} \
--header 'Content-Type: multipart/form-data' \
--form 'enrichment={"name":"my-first-webhook-enrichment", \
"type":"webhook", \
"options":{"url":"{your_code_engine_app_domain}/webhook", \
    "secret":"{your_webhook_secret}", \
    "location_encoding":"utf-32"}}' \
'{url}/v2/projects/{project_id}/enrichments?version=2023-03-31'

{auth}: apikey:[IBM Cloudの APIキー]
{your_code_engine_app_domain}：Code Engine のアプリケーション > ドメイン・マッピングで確認
{your_webhook_secret}：　前のステップで登録した WEBHOOK_SECRET の値
{url}：　Discoveryインスタンスの資格情報にある URL
{project_id}： Discoveryの「Integrate and deploy」>「API Information」タブの Project ID

実際に登録した時のコマンドはこのようなイメージです

curl -X POST -u "apikey:abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqr" \
--header 'Content-Type: multipart/form-data' \
--form 'enrichment={"name":"watsonx", \
"type":"webhook", \
"options":{"url":"https://watsonx-entity.1abc2defg3h4.us-south.codeengine.appdomain.cloud/webhook",\
    "secret":"hooksecret", \
    "location_encoding":"utf-32"}}' \
'https://api.us-south.discovery.watson.cloud.ibm.com/instances/1234567c-d123-456d-bad7-5e50d920cc5e/v2/projects/d12345fa-ef67-8cbd-ace9-0a6e123a45c6/enrichments?version=2023-03-31'

Discoveryでエンリッチメントの構成

コレクションにサンプルファイルの登録

Discovery doc-tutorial-downloads から email.txt ダウンロードして、Discoveryのコレクションに登録（アップロード）します。

コレクションにエンリッチメントの指定

Discoveryの管理ツールで、Webhookで登録したエンリッチメントを指定します

文書に付与されたエンリッチメントの確認

Discoveryで文書のメタ情報を見ると、webhookエンリッチメントで情報が抽出されているのを確認できます

終わりに

Watson Discoveryの特徴的な機能であるエンリッチメントで、汎用的なwebhookが利用できるようになりました。
今回は watsonx.ai の Griniteモデルを利用してエンティティ抽出を行いました。
サンプルテンプレートは granite-13b-instruct-v1 モデルで英語のプロンプトを使用していますが、以下の model_id や Input のプロンプトを変更して、別の結果を試すことができます。

main.py

def extract_entities(text):
    global IAM_TOKEN
    if IAM_TOKEN is None:
        IAM_TOKEN = get_iam_token()
    # Prompt
    payload = {
        'model_id': 'ibm/granite-13b-instruct-v1',
        'input': f'''Act as a webmaster who must extract structured information from emails. Read the below email and extract and categorize each entity. If no entity is found, output "None".

Input:
"Golden Bank is a competitor of Silver Bank in the US" said John Doe.

Named Entities:
Golden Bank: company, Silver Bank: company, US: country, John Doe: person

Input:
{text}

参考情報

Watson Discovery 製品マニュアル：Discoveryで外部Webhookエンリッチを作成
https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-tutorial-external-enrichment#configure-webhook-enrichment

Watson Discovdery 外部エンリッチ API
https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-external-enrichment

watsonx.aiの基盤モデルをWatson Discoveryのエンティティ抽出で利用する