テキストの分類（Categorize text）

テキスト集約の分類

半構造化テキストをバケットにグループ化するマルチバケット集約です。各 text フィールドはカスタムアナライザーを使用して再分析されます。結果として得られたトークンは、類似の形式のテキスト値のバケットを作成するために分類されます。この集約は、システムログのような機械生成テキストに最適です。テキストを分類するために使用されるのは、最初の100個の分析されたトークンのみです。

JVMにかなりのメモリが割り当てられている場合でも、この集約から回路ブレーカー例外が発生する場合は、分類に適さない形式のテキストを分類しようとしている可能性があります。categorization_filtersを追加するか、サンプラー、多様化サンプラー、またはランダムサンプラーの下で実行して、作成されたカテゴリを探索することを検討してください。

分類に使用されるアルゴリズムは、バージョン8.3.0で完全に変更されました。その結果、この集約は、ノードの一部がバージョン8.3.0以上で、他のノードが8.3.0未満の混合バージョンクラスターでは機能しません。この変更に関連するエラーが発生した場合は、クラスター内のすべてのノードを同じバージョンにアップグレードしてください。

パラメータ

• categorization_analyzer
• (オプション、オブジェクトまたは文字列) 分類アナライザーは、テキストが分類される前にどのように分析され、トークン化されるかを指定します。構文は、Analyzeエンドポイントでanalyzerを定義するために使用されるものと非常に似ています。このプロパティは、categorization_filtersと同時に使用することはできません。
  categorization_analyzer フィールドは、文字列またはオブジェクトとして指定できます。文字列の場合は、組み込みアナライザーまたは他のプラグインによって追加されたものを参照する必要があります。オブジェクトの場合は、次のプロパティを持ちます:

  -   `````char_filter

  • (文字列またはオブジェクトの配列) 1つ以上の文字フィルター。組み込みの文字フィルターに加えて、他のプラグインがさらに多くの文字フィルターを提供できます。このプロパティはオプションです。指定されていない場合、分類の前に文字フィルターは適用されません。アナライザーの他の側面をカスタマイズしている場合、categorization_filtersの同等物を達成する必要がある場合は、ここにパターン置換文字フィルターとして追加してください。
  • tokenizer
  • (文字列またはオブジェクト) 文字フィルターが適用された後に使用するトークナイザーの名前または定義。このプロパティは、categorization_analyzerがオブジェクトとして指定されている場合は必須です。機械学習は、英語のログファイル形式で良好な分類結果を生成することが決定された方法でトークン化するml_standardというトークナイザーを提供します。そのトークナイザーを使用したいが、文字またはトークンフィルターを変更したい場合は、"tokenizer": "ml_standard"をcategorization_analyzerに指定してください。さらに、ml_classicトークナイザーも利用可能で、製品の古いバージョン（6.2以前）のカスタマイズ不可能なトークナイザーと同じ方法でトークン化します。ml_classicは、バージョン6.2から7.13までのデフォルトの分類トークナイザーであったため、これらのバージョンで作成されたジョブのデフォルトと同じ分類が必要な場合は、"tokenizer": "ml_classic"をcategorization_analyzerに指定してください。
    Elasticsearch 8.10.0以降、新しいバージョン番号が機械学習プラグインの構成と状態の変更を追跡するために使用されます。この新しいバージョン番号は、製品バージョンから切り離されており、独立して増加します。
  • filter
  • (文字列またはオブジェクトの配列) 1つ以上のトークンフィルター。組み込みのトークンフィルターに加えて、他のプラグインがさらに多くのトークンフィルターを提供できます。このプロパティはオプションです。指定されていない場合、分類の前にトークンフィルターは適用されません。
• categorization_filters
• (オプション、文字列の配列) このプロパティは正規表現の配列を期待します。これらの式は、分類フィールド値から一致するシーケンスをフィルタリングするために使用されます。この機能を使用して、カテゴリが定義される際に考慮されるシーケンスを除外することで、分類を微調整できます。たとえば、ログファイルに表示されるSQLステートメントを除外できます。このプロパティは、categorization_analyzerと同時に使用することはできません。トークン化の前に適用される単純な正規表現フィルターを定義したい場合は、このプロパティを設定するのが最も簡単な方法です。トークナイザーやトークン化後のフィルタリングをカスタマイズしたい場合は、categorization_analyzerプロパティを代わりに使用し、フィルターをpattern_replace文字フィルターとして含めてください。
• field
• (必須、文字列) 分類する半構造化テキストフィールド。
• max_matched_tokens
• (オプション、整数) このパラメータは現在何もしませんが、元の8.3.0以前の実装との互換性のために許可されています。
• max_unique_tokens
• (オプション、整数) このパラメータは現在何もしませんが、元の8.3.0以前の実装との互換性のために許可されています。
• min_doc_count
• (オプション、整数) 結果に返されるバケットの最小ドキュメント数。
• shard_min_doc_count
• (オプション、整数) マージ前にシャードから返されるバケットの最小ドキュメント数。
• shard_size
• (オプション、整数) すべての結果をマージする前に、各シャードから返される分類バケットの数。
• similarity_threshold
• (オプション、整数、デフォルト: 70) テキストがカテゴリバケットに追加されるために一致する必要があるトークン重みの最小パーセンテージ。1から100の間でなければなりません。値が大きいほど、カテゴリは狭くなります。大きな値はメモリ使用量を増加させ、より狭いカテゴリを作成します。
• size
• (オプション、整数、デフォルト: 10) 返されるバケットの数。

レスポンスボディ

• key
• (文字列) カテゴリに含まれる入力フィールドのすべての値に共通するトークン（categorization_analyzerによって抽出されたもの）で構成されます。
• doc_count
• (整数) カテゴリに一致するドキュメントの数。
• max_matching_length
• (整数) トークンが少ない短いメッセージからのカテゴリも、はるかに長いメッセージから派生した多くのトークンを含むカテゴリに一致する場合があります。max_matching_lengthは、カテゴリに属すると見なされるべきメッセージの最大長の指標です。カテゴリに一致するメッセージを検索する際、max_matching_lengthより長いメッセージは除外されるべきです。このフィールドを使用して、短いメッセージのカテゴリのメンバーを検索する際に、はるかに長いメッセージと一致しないようにします。
• regex
• (文字列) カテゴリに含まれる入力フィールドのすべての値に一致する正規表現です。regexがkeyに含まれるすべての用語を組み込んでいない可能性がありますが、カテゴリに含まれる値間で順序が異なる場合があります。ただし、単純なケースでは、regexは、間に任意のセクションを許可する正規表現に連結された順序付きの用語になります。元の文書を検索するための主要なメカニズムとしてregexを使用することは推奨されません。正規表現を使用した検索は非常に遅いです。代わりに、keyフィールドの用語を使用して一致するドキュメントを検索するべきです。用語検索は逆インデックスを使用できるため、はるかに高速です。ただし、インデックスされていない小さなメッセージセットがカテゴリに一致するかどうかをテストするためにregexフィールドを使用することが有用な場合や、keyの用語がすべての一致したドキュメントで正しい順序で発生することを確認するために使用することが有用な場合があります。

基本的な使用法

大きな 結果セットを再分析するには、多くの時間とメモリが必要です。この集約は、非同期検索と併用して使用する必要があります。さらに、集約をサンプラーまたは多様化サンプラー集約の子として使用することを検討してください。これにより、通常、速度とメモリ使用量が改善されます。

例:

Python

resp = client.search(
   index="log-messages",
   filter_path="aggregations",
   aggs={
   "categories": {
   "categorize_text": {
   "field": "message"
   }
   }
   },
)
print(resp)

Js

const response = await client.search({
  index: "log-messages",
  filter_path: "aggregations",
  aggs: {
   categories: {
   categorize_text: {
   field: "message",
   },
   },
  },
});
console.log(response);

コンソール

POST log-messages/_search?filter_path=aggregations
{
  "aggs": {
   "categories": {
   "categorize_text": {
   "field": "message"
   }
   }
  }
}

レスポンス:

コンソール-結果

{
  "aggregations" : {
   "categories" : {
   "buckets" : [
   {
   "doc_count" : 3,
   "key" : "Node shutting down",
   "regex" : ".*?Node.+?shutting.+?down.*?",
   "max_matching_length" : 49
   },
   {
   "doc_count" : 1,
   "key" : "Node starting up",
   "regex" : ".*?Node.+?starting.+?up.*?",
   "max_matching_length" : 47
   },
   {
   "doc_count" : 1,
   "key" : "User foo_325 logging on",
   "regex" : ".*?User.+?foo_325.+?logging.+?on.*?",
   "max_matching_length" : 52
   },
   {
   "doc_count" : 1,
   "key" : "User foo_864 logged off",
   "regex" : ".*?User.+?foo_864.+?logged.+?off.*?",
   "max_matching_length" : 52
   }
   ]
   }
  }
}

#### Python
``````python
resp = client.search(
   index="log-messages",
   filter_path="aggregations",
   aggs={
   "categories": {
   "categorize_text": {
   "field": "message",
   "categorization_filters": [
   "\\w+\\_\\d{3}"
   ]
   }
   }
   },
)
print(resp)
`

Js

const response = await client.search({
  index: "log-messages",
  filter_path: "aggregations",
  aggs: {
   categories: {
   categorize_text: {
   field: "message",
   categorization_filters: ["\\w+\\_\\d{3}"],
   },
   },
  },
});
console.log(response);

コンソール

POST log-messages/_search?filter_path=aggregations
{
  "aggs": {
   "categories": {
   "categorize_text": {
   "field": "message",
   "categorization_filters": ["\\w+\\_\\d{3}"]
   }
   }
  }
}

 [](#547973e7d5ba9f5b775211fbb3574cf8)
#### コンソール-結果
``````console-result
{
  "aggregations" : {
   "categories" : {
   "buckets" : [
   {
   "doc_count" : 3,
   "key" : "Node shutting down",
   "regex" : ".*?Node.+?shutting.+?down.*?",
   "max_matching_length" : 49
   },
   {
   "doc_count" : 1,
   "key" : "Node starting up",
   "regex" : ".*?Node.+?starting.+?up.*?",
   "max_matching_length" : 47
   },
   {
   "doc_count" : 1,
   "key" : "User logged off",
   "regex" : ".*?User.+?logged.+?off.*?",
   "max_matching_length" : 52
   },
   {
   "doc_count" : 1,
   "key" : "User logging on",
   "regex" : ".*?User.+?logging.+?on.*?",
   "max_matching_length" : 52
   }
   ]
   }
  }
}
`

#### Python
``````python
resp = client.search(
   index="log-messages",
   filter_path="aggregations",
   aggs={
   "categories": {
   "categorize_text": {
   "field": "message",
   "categorization_filters": [
   "\\w+\\_\\d{3}"
   ],
   "similarity_threshold": 11
   }
   }
   },
)
print(resp)
`

Js

const response = await client.search({
  index: "log-messages",
  filter_path: "aggregations",
  aggs: {
   categories: {
   categorize_text: {
   field: "message",
   categorization_filters: ["\\w+\\_\\d{3}"],
   similarity_threshold: 11,
   },
   },
  },
});
console.log(response);

コンソール

POST log-messages/_search?filter_path=aggregations
{
  "aggs": {
   "categories": {
   "categorize_text": {
   "field": "message",
   "categorization_filters": ["\\w+\\_\\d{3}"],
   "similarity_threshold": 11
   }
   }
  }
}

結果として得られるカテゴリは非常に広範で、ロググループを統合しています。（11%のsimilarity_thresholdは一般的に低すぎます。50%以上の設定が通常は良好です。）

コンソール-結果

{
  "aggregations" : {
   "categories" : {
   "buckets" : [
   {
   "doc_count" : 4,
   "key" : "Node",
   "regex" : ".*?Node.*?",
   "max_matching_length" : 49
   },
   {
   "doc_count" : 2,
   "key" : "User",
   "regex" : ".*?User.*?",
   "max_matching_length" : 52
   }
   ]
   }
  }
}

この集約は、サブ集約を持つことができ、サブ集約としても機能します。これにより、以下のように、トップの日次カテゴリとトップのサンプルドキュメントを収集できます。

Python

resp = client.search(
   index="log-messages",
   filter_path="aggregations",
   aggs={
   "daily": {
   "date_histogram": {
   "field": "time",
   "fixed_interval": "1d"
   },
   "aggs": {
   "categories": {
   "categorize_text": {
   "field": "message",
   "categorization_filters": [
   "\\w+\\_\\d{3}"
   ]
   },
   "aggs": {
   "hit": {
   "top_hits": {
   "size": 1,
   "sort": [
   "time"
   ],
   "_source": "message"
   }
   }
   }
   }
   }
   }
   },
)
print(resp)

Js

const response = await client.search({
  index: "log-messages",
  filter_path: "aggregations",
  aggs: {
   daily: {
   date_histogram: {
   field: "time",
   fixed_interval: "1d",
   },
   aggs: {
   categories: {
   categorize_text: {
   field: "message",
   categorization_filters: ["\\w+\\_\\d{3}"],
   },
   aggs: {
   hit: {
   top_hits: {
   size: 1,
   sort: ["time"],
   _source: "message",
   },
   },
   },
   },
   },
   },
  },
});
console.log(response);

コンソール

POST log-messages/_search?filter_path=aggregations
{
  "aggs": {
   "daily": {
   "date_histogram": {
   "field": "time",
   "fixed_interval": "1d"
   },
   "aggs": {
   "categories": {
   "categorize_text": {
   "field": "message",
   "categorization_filters": ["\\w+\\_\\d{3}"]
   },
   "aggs": {
   "hit": {
   "top_hits": {
   "size": 1,
   "sort": ["time"],
   "_source": "message"
   }
   }
   }
   }
   }
   }
  }
}

コンソール-結果

{
  "aggregations" : {
   "daily" : {
   "buckets" : [
   {
   "key_as_string" : "2016-02-07T00:00:00.000Z",
   "key" : 1454803200000,
   "doc_count" : 3,
   "categories" : {
   "buckets" : [
   {
   "doc_count" : 2,
   "key" : "Node shutting down",
   "regex" : ".*?Node.+?shutting.+?down.*?",
   "max_matching_length" : 49,
   "hit" : {
   "hits" : {
   "total" : {
   "value" : 2,
   "relation" : "eq"
   },
   "max_score" : null,
   "hits" : [
   {
   "_index" : "log-messages",
   "_id" : "1",
   "_score" : null,
   "_source" : {
   "message" : "2016-02-07T00:00:00+0000 Node 3 shutting down"
   },
   "sort" : [
   1454803260000
   ]
   }
   ]
   }
   }
   },
   {
   "doc_count" : 1,
   "key" : "Node starting up",
   "regex" : ".*?Node.+?starting.+?up.*?",
   "max_matching_length" : 47,
   "hit" : {
   "hits" : {
   "total" : {
   "value" : 1,
   "relation" : "eq"
   },
   "max_score" : null,
   "hits" : [
   {
   "_index" : "log-messages",
   "_id" : "2",
   "_score" : null,
   "_source" : {
   "message" : "2016-02-07T00:00:00+0000 Node 5 starting up"
   },
   "sort" : [
   1454803320000
   ]
   }
   ]
   }
   }
   }
   ]
   }
   },
   {
   "key_as_string" : "2016-02-08T00:00:00.000Z",
   "key" : 1454889600000,
   "doc_count" : 3,
   "categories" : {
   "buckets" : [
   {
   "doc_count" : 1,
   "key" : "Node shutting down",
   "regex" : ".*?Node.+?shutting.+?down.*?",
   "max_matching_length" : 49,
   "hit" : {
   "hits" : {
   "total" : {
   "value" : 1,
   "relation" : "eq"
   },
   "max_score" : null,
   "hits" : [
   {
   "_index" : "log-messages",
   "_id" : "4",
   "_score" : null,
   "_source" : {
   "message" : "2016-02-08T00:00:00+0000 Node 5 shutting down"
   },
   "sort" : [
   1454889660000
   ]
   }
   ]
   }
   }
   },
   {
   "doc_count" : 1,
   "key" : "User logged off",
   "regex" : ".*?User.+?logged.+?off.*?",
   "max_matching_length" : 52,
   "hit" : {
   "hits" : {
   "total" : {
   "value" : 1,
   "relation" : "eq"
   },
   "max_score" : null,
   "hits" : [
   {
   "_index" : "log-messages",
   "_id" : "6",
   "_score" : null,
   "_source" : {
   "message" : "2016-02-08T00:00:00+0000 User foo_864 logged off"
   },
   "sort" : [
   1454889840000
   ]
   }
   ]
   }
   }
   },
   {
   "doc_count" : 1,
   "key" : "User logging on",
   "regex" : ".*?User.+?logging.+?on.*?",
   "max_matching_length" : 52,
   "hit" : {
   "hits" : {
   "total" : {
   "value" : 1,
   "relation" : "eq"
   },
   "max_score" : null,
   "hits" : [
   {
   "_index" : "log-messages",
   "_id" : "5",
   "_score" : null,
   "_source" : {
   "message" : "2016-02-08T00:00:00+0000 User foo_325 logging on"
   },
   "sort" : [
   1454889720000
   ]
   }
   ]
   }
   }
   }
   ]
   }
   }
   ]
   }
  }
}