Analyze API を使用したオンデマンドでのデータ分析
分析 API を使用して、ソース文書からのデータを保管せずに、 Discovery サービスのエンリッチ・パイプラインを介してテキスト文書を処理します。
分析 API は、エンタープライズ・プラン・デプロイメントおよびインストール済みデプロイメントでのみサポートされます。
このアプローチは、ビジネス自動化の目的に理想的です。 例えば、E メールを分類する場合は、分析 API を使用して Discovery を同期的に呼び出して、E メールの分類を取得できます。 その後、その分類の出力をビジネス・ロジックで使用できます。
分析 API は、JSON 文書のみをサポートしています。
API を使用して文書を分析する場合は、分析に関連付けるコレクションを指定することにより、文書の処理方法を指定します。 文書はコレクションに保管されません。 代わりに、コレクションの構成設定が文書に適用されます。 例えば、文書内のエンティティー参照を検索する場合は、 「エンティティー」 エンリッチメントが適用されているコレクションに対して分析 API を実行します。 結果の文書分析により、文書内のエンティティー・メンションが識別されます。
文書をオンデマンドで分析するために使用するエンリッチメントで構成された 1 つのコレクションに対してのみ、分析の要求を送信します。 コレクション内の文書は重要ではないことに注意してください。 重要なのは、コレクションに定義されているエンリッチメントです。 複数のコレクションに要求を送信すると、複数のモデルが同時に開始されるため、要求が失敗する可能性があります。
分析 API では、以下のエンリッチメントがサポートされています。
- 拡張ルール・モデル
- 契約
- カスタム・エンティティー
- 辞書
- 文書分類器
- エンティティー(NLP)
- キーワード(NLP)
- 機械学習および Watson Explorer Content Analytics Studio のモデル
- 正規表現
- Patterns (エンタープライズ・プランのみ)
- 文書のセンチメント
- 表の理解[1]
- テキスト分類器
各言語でサポートされている拡張機能の一覧については 、「言語サポート」 をご覧ください。
詳しくは、 Discovery API リファレンスを参照してください。
分析の例
分析のために送信するデータは JSON 形式でなければなりません。 テキストはストリングとして指定する必要があります。配列として指定することはできません。 例えば、以下の JSON ファイルでは、テキスト内のキーワード言及を検出するために分析する Quote フィールドに引用符が含まれています。
{
"Author": "Jane Austen",
"Book": "Pride and Prejudice",
"Quote": "From this day you must be a stranger to one of your parents. Your mother will never see you again if you do not marry Mr. Collins, and I will never see you again if you do.",
"Year": "1813/01/01",
"Subject":"Parental love",
"Speaker": "Mr. Bennett",
"url": "https://www.gutenberg.org/files/1342/1342-h/1342-h.htm#link2HCH0020"
}
コレクション内の文書に適用されるように 「キーワード」 エンリッチメントが構成されている、プロジェクト内のコレクションの名前が分かっている。 この API を使用して コレクションをリスト し、探しているコレクションに関連付けられた ID を名前で見つけることができます。
コレクション ID を取得したら、コレクションから JSON ファイルに構成設定を適用するために送信する POST 要求にその ID を含めます。 例えば、以下の要求は、キーワード分析のために favorites2.json という名前のファイルに JSON スニペットを送信します。
curl --location --request POST \
'https://my-cloud-pak-for-data-cluster/discovery/zen-wd/instances/{instance-id}/api/v2/ \
projects/{project-id}/collections/{collection-id}/analyze?version=2020-08-30' \
--header 'Authorization: Bearer ...' \
--form 'file=@"/quotations/favorites2.json"'
結果には、引用符内で認識されたキーワードのリストが含まれます。
{
"result": {
"enriched_Quote": [
{
"keywords": [
{
"text": "day",
"mentions": [
{
"text": "day",
"location": {
"begin": 10,
"end": 13
}
}
],
"relevance": 0.673739
},
{
"text": "stranger",
"mentions": [
{
"text": "stranger",
"location": {
"begin": 28,
"end": 36
}
}
],
"relevance": 0.596757
},
{
"text": "parents",
"mentions": [
{
"text": "parents",
"location": {
"begin": 52,
"end": 59
}
}
],
"relevance": 0.568336
},
{
"text": "mother",
"mentions": [
{
"text": "mother",
"location": {
"begin": 66,
"end": 72
}
}
],
"relevance": 0.755562
},
{
"text": "Mr. Collins",
"mentions": [
{
"text": "Mr. Collins",
"location": {
"begin": 118,
"end": 129
}
}
],
"relevance": 0.945891
}
]
}
],
"url": "https://www.gutenberg.org/files/1342/1342-h/1342-h.htm#link2HCH0020",
"Subject": "Parental love",
"Year": "1813/01/01",
"Book": "Pride and Prejudice",
"Author": "Jane Austen",
"Quote": [
"From this day you must be a stranger to one of your parents. Your mother will never see you again if you do not marry Mr. Collins, and I will never see you again if you do."
],
"metadata": {
"name": "favorites2.json"
},
"Speaker": "Mr. Bennett"
},
"notices": []
}
オブジェクトの配列を入力としてサブミットすることはできません。 例えば、複数の引用符を分析する場合、ソースは次のようになります。
{
"quotations":[
{
"Author": "Jane Austen",
"Book": "Sense and Sensibility",
"Quote": "Is there a felicity in the world superior to this?",
"Year": "1811/01/01",
"Subject": "Nature",
"Speaker": "Marianne Dashwood",
"url": "https://www.gutenberg.org/files/1342/1342-h/1342-h.htm#link2HCH0059"
},
{
"Author": "Jane Austen",
"Book": "Persuasion",
"Quote": "A man does not recover from such a devotion of the heart to such a woman. He ought not; he does not.",
"Subject": "Romantic love",
"Year": "1818/01/01",
"Speaker": "Captain Wentworth",
"url": "https://www.gutenberg.org/files/105/105-h/105-h.htm#chap20"
}
]
}
その場合は、各オブジェクトを別々のファイルに分割し、各ファイルを個別に分析します。
テキスト・スニペットの分析
以下のような構文を使用して JSON 形式でテキストを指定すると、分析のためにテキストを送信できます。
{
"text":"The text that you want to analyze."
}
以下の要求例は、物理ファイルで渡されたテキストではなく、要求で指定したテキストを分析する方法を示しています。
curl --location --request POST \
'https://my-cloud-pak-for-data-cluster/discovery/zen-wd/instances/{instance-id}/api/v2/ \
projects/{project-id}/collections/{collection-id}/analyze?version=2020-08-30' \
--header 'Authorization: Bearer ...' \
--form 'file={"text": "ISO 9000 is a standard."}'
応答は以下のようになります。
{
"result" : {
"enriched_text" : [ {
"entities" : [ {
"text" : "ISO 9000",
"type" : "my_iso_pattern",
"mentions" : [ {
"text" : "ISO 9000",
"confidence" : 1.0,
"location" : {
"begin" : 0,
"end" : 8
}
} ],
"model_name" : "My ISO Pattern"
}, {
"text" : "9000",
"type" : "Number",
"mentions" : [ {
"text" : "9000",
"confidence" : 0.8,
"location" : {
"begin" : 4,
"end" : 8
}
} ],
"model_name" : "natural_language_understanding"
} ]
} ],
"metadata" : { },
"text" : [ "ISO 9000 is a standard." ]
},
"notices" : [ ]
}
HTML コンテンツの分析
以下のような構文を使用して JSON 形式で HTML を送信すると、HTML を分析できます。
{
"html":"<p>My html content.</p>"
}
以下の要求例は、物理ファイルで渡されたテキストではなく、要求で指定したテキストを分析する方法を示しています。
要求が行われるコレクションでは、以下のエンリッチメントが使用されます。つまり、これらのエンリッチメントは、API 要求で送信するコンテンツに適用されます。
- エンティティー
- キーワード
- 表の理解
要求の例
要求の本体には、 file という名前の form-data が含まれています。 値は、分析対象の JSON コンテンツです。
curl --location --request POST \
'https://cpd-abc.example.com/discovery/abc-wd/instances/1671204318684041/api/v2/projects/d457fcd9-a4ce-4637-a340-33123b5cbe2c/collections/2d47dbcc-64c7-84e9-0000-01851bb9d998/analyze?version=2020-08-30' \
--header 'Authorization: Bearer ...' \
--form 'file={
"html":"<html><head>This is my html file</head><body><p>My file contains a table.</p><table><tbody><tr><th>Holiday</th><th>Popular greeting</th></tr><tr><td>Christmas</td><td>Merry Christma!s</td></tr></tbody></table></body></html>",
"text":"This is a sentence that contains key words, such as George Washington and Boston, MA."
}'
結果
結果には、送信された text フィールドと html フィールドのエンティティー、キーワード、および表の理解エンリッチメントの出力が表示されます。
{
"result": {
"text": [
"This is a sentence that contains key words, such as George Washington and Boston, MA."
],
"enriched_text": [
{
"keywords": [
{
"text": "George Washington",
"mentions": [
{
"text": "George Washington",
"location": {
"begin": 52,
"end": 69
}
}
],
"relevance": 0.952591
},
{
"text": "Boston",
"mentions": [
{
"text": "Boston",
"location": {
"begin": 74,
"end": 80
}
}
],
"relevance": 0.578079
},
{
"text": "MA",
"mentions": [
{
"text": "MA",
"location": {
"begin": 82,
"end": 84
}
}
],
"relevance": 0.146905
}
],
"entities": [
{
"text": "George Washington",
"type": "Location",
"mentions": [
{
"text": "George Washington",
"confidence": 0.54922265,
"location": {
"begin": 52,
"end": 69
}
}
],
"model_name": "natural_language_understanding"
},
{
"text": "Boston, MA",
"type": "Location",
"mentions": [
{
"text": "Boston, MA",
"confidence": 0.66049105,
"location": {
"begin": 74,
"end": 84
}
}
],
"model_name": "natural_language_understanding"
}
]
}
],
"metadata": {},
"enriched_html": [
{
"tables": [
{
"body_cells": [
{}
],
"location": {
"begin": 99,
"end": 183
},
"row_headers": [],
"key_value_pairs": [],
"section_title": {},
"contexts": [],
"text": "Holiday Popular greeting Christmas Merry Christmas!",
"table_headers": [],
"title": {},
"column_headers": []
}
]
}
],
"html": [
"<html><head>This is my html file</head><body><p>My file contains a table.</p><table><tbody><tr><th>Holiday</th><th>Popular greeting</th></tr><tr><td>Christmas</td><td>Merry Christmas!</td></tr></tbody></table></body></html>"
]
},
"notices": []
}
API 制限の分析
以下の表に、Analyze API のファイル・サイズと使用制限を示します。
| デプロイメント・タイプ | ファイル・サイズの制限 | 同時収集の制限 | コレクションごとの同時照会の制限 |
|---|---|---|---|
| Cloud Pak for Data のインストール済みデプロイメント | Unlimited | Unlimited | Unlimited |
| エンタープライズ・プランの管理対象デプロイメント | 50 KB | 5 | 5 |
Discovery から分析 API を使用すると、 IBM Cloud Pak for Data のカートリッジがライセンス使用に影響します。 詳しくは、 ライセンス情報を参照してください。
使用状況のモニタリング IBM Cloud Pak for DataIBM Software Hub
分析 API の使用状況は、 「API 使用状況」 ページからモニターできます。
「API 使用状況」 ページは、インストール済みのデプロイメントからのみ使用できます。 エンタープライズ・プランの場合、分析メソッド呼び出し情報は照会メソッド呼び出し情報と結合され、照会メトリックの一部として報告されます。
API利用ページにアクセスするには、 プロジェクトページを開き 、「データ利用」 を選択し、次に 「API利用」 を選択します。
- 開始日
- API 呼び出し-モニター期間の開始日。
- 終了日
- API 呼び出し・モニター期間の終了日。
- 30 日間の通話合計
- 「開始日」 と 「終了日」 で示される 30 日の時間間隔での分析 API の呼び出し回数。 時間間隔は、APIコールの数が最も多い連続した時間期間を計算することで決定されます。 30日間のウィンドウは、APIコールの変更数が最も多い時間間隔に合わせて更新されます。
APIの利用状況は、APIの利用状況の監視が開始されてからしばらく経たないと表示されません。 リストされている 30 日間の期間に現在日付が含まれている場合でも、 30 日間の呼び出し合計 の最終合計数を表示する際に遅延が発生する可能性があります。
-
表の理解エンリッチメントによって結果を生成するには、分析する
<table>HTML エレメントが入力に含まれている必要があります。 ↩︎