Azure AI Search インデックスの文字列フィールドにカスタム アナライザーを追加する

カスタム アナライザー は、1 つのトークナイザー、1 つ以上のトークン フィルター、および 1 つ以上の文字フィルターをユーザー定義で組み合わせたものです。 カスタム アナライザーは検索インデックス内で指定され、その後、カスタム分析を必要とするフィールド定義で名前によって参照されます。 カスタム アナライザーはフィールド単位で呼び出されます。 フィールドの属性によって、インデックス作成に使用されるか、クエリに使用されるか、それともその両方に使用されるかが決定されます。

カスタム アナライザーでは、トークナイザーによる処理の前に、文字フィルターによって入力テキストが準備されます (マークアップを削除するなど)。 その後、トークナイザーによってテキストがトークンに分割されます。 最後に、トークナイザーによって出力されたトークンがトークン フィルターによって変更されます。 概念と例については、「 Azure AI Search でのアナライザー」を参照してください。

カスタム アナライザーを使用する理由

カスタム アナライザーを使用すると、呼び出す分析またはフィルター処理の種類と、実行順序を選択できるので、テキストをインデックス可能で検索可能なトークンに変換するプロセスを制御できます。

既定 (Standard Lucence)、組み込み、または言語アナライザーではニーズが満たされない場合は、カスタム アナライザーを作成して割り当てる必要があります。 組み込みのアナライザーとカスタム オプションを使用する場合も、カスタム アナライザーを作成する場合があります。 たとえば、Standard の maxTokenLength を変更する場合は、そのオプションを設定するために、ユーザー定義の名前を持つカスタム アナライザーを作成します。

カスタム アナライザーが役に立つシナリオを次に示します。

• 文字フィルターを使用して、テキスト入力がトークン化される前に HTML マークアップを削除したり、特定の文字や記号を置き換えたりする場合。

• 音声検索。 発音フィルターを追加することによって、単語の綴りではなく発音に基づく検索に対応します。

• 字句解析の無効化。 解析の対象外とする検索可能なフィールドをキーワード アナライザーで作成します。

• 高速なプレフィックス/サフィックス検索。 Edge N-gram トークン フィルターを追加し、単語のプレフィックスをインデックス化することによって、高速なプレフィックス マッチングに対応します。 リバース トークン フィルターを組み合わせることで、サフィックス マッチングを行うことができます。

• カスタム トークン化。 たとえば空白文字を区切りとして文をトークンに分割するには、Whitespace トークナイザーを使用します

• ASCII フォールディング。 検索語句に含まれる ö や ê などの付加記号を正規化するための標準 ASCII フォールディング フィルターを追加します。

カスタム アナライザーを作成する

カスタム アナライザーを作成するには、デザイン時にインデックスの analyzers セクションでそれを指定してから、analyzer プロパティまたは indexAnalyzer と searchAnalyzer のペアのいずれかを使用して、検索可能な Edm.String フィールドでそれを参照します。

アナライザーの定義には、名前、種類、1 つ以上の文字フィルター、最大で 1 つのトークナイザー、トークン化後の処理のための 1 つ以上のトークン フィルターが含まれます。 文字フィルターは、トークン化の前に適用されます。 トークン フィルターと文字フィルターは、左から右に適用されます。

• 名前は、カスタム アナライザー内で一意である必要があり、組み込みのアナライザー、トークナイザー、トークン フィルター、または文字フィルターのいずれとも同じにすることはできません。 アルファベット、数字、空白、ダッシュ、アンダースコアのみを含める必要があります。また、最初と最後の文字は英数字にする必要があり、長さは 128 文字までに制限されています。

• 型は #Microsoft.Azure.Search.CustomAnalyzer にする必要があります。

• charFilters は、文字フィルターから 1 つ以上のフィルターを、指定された順序で、トークン化の前に処理できます。 一部の文字フィルターにはオプションがあり、charFilters セクションで設定できます。 文字フィルターは省略可能です。

• tokenizer は 1 つの トークナイザーだけです。 値は必須です。 複数のトークナイザーが必要な場合は、複数のカスタム アナライザーを作成し、インデックス スキーマのフィールドごとに割り当てます。

• tokenFilters は、トークン フィルターから 1 つ以上のフィルターを、指定された順序で、トークン化後に処理できます。 オプションがあるトークン フィルターについては、tokenFilter セクションを追加して構成を指定します。 トークン フィルターは省略可能です。

アナライザーで 300 文字を超えるトークンを生成しないでください。インデックス作成が失敗します。 長いトークンをトリミングするには、TruncateTokenFilter を、またはそれらを無視するには、LengthTokenFilter をそれぞれ使用します。 参考として、「トークン フィルター」を参照してください。

"analyzers":(optional)[
   {
      "name":"name of analyzer",
      "@odata.type":"#Microsoft.Azure.Search.CustomAnalyzer",
      "charFilters":[
         "char_filter_name_1",
         "char_filter_name_2"
      ],
      "tokenizer":"tokenizer_name",
      "tokenFilters":[
         "token_filter_name_1",
         "token_filter_name_2"
      ]
   },
   {
      "name":"name of analyzer",
      "@odata.type":"#analyzer_type",
      "option1":value1,
      "option2":value2,
      ...
   }
],
"charFilters":(optional)[
   {
      "name":"char_filter_name",
      "@odata.type":"#char_filter_type",
      "option1":value1,
      "option2":value2,
      ...
   }
],
"tokenizers":(optional)[
   {
      "name":"tokenizer_name",
      "@odata.type":"#tokenizer_type",
      "option1":value1,
      "option2":value2,
      ...
   }
],
"tokenFilters":(optional)[
   {
      "name":"token_filter_name",
      "@odata.type":"#token_filter_type",
      "option1":value1,
      "option2":value2,
      ...
   }
]

インデックス定義内で、インデックス作成要求本文内のどこにでも次のセクションを配置できますが、通常は末尾に置きます。

{
  "name": "name_of_index",
  "fields": [ ],
  "suggesters": [ ],
  "scoringProfiles": [ ],
  "defaultScoringProfile": (optional) "...",
  "corsOptions": (optional) { },
  "analyzers":(optional)[ ],
  "charFilters":(optional)[ ],
  "tokenizers":(optional)[ ],
  "tokenFilters":(optional)[ ]
}

アナライザーの定義は、より大きなインデックスの一部です。 文字フィルター、トークナイザー、トークン フィルターの定義は、カスタム オプションを設定する場合にのみ、インデックスに追加されます。 既存のフィルターまたはトークナイザーをそのまま使用するには、アナライザーの定義内で名前を使用して指定します。 詳細については、インデックスの作成 (REST) に関する記事をご覧ください。 その他の例については、「 Azure AI Search でアナライザーを追加する」を参照してください。

カスタム アナライザーのテスト

テスト アナライザー (REST) を使用して、指定したテキストがアナライザーによってどのようにトークンに分割されるかを確認できます。

Request

  POST https://[search service name].search.windows.net/indexes/[index name]/analyze?api-version=[api-version]
    Content-Type: application/json
    api-key: [admin key]

  {
     "analyzer":"my_analyzer",
     "text": "Vis-à-vis means Opposite"
  }

回答

  {
    "tokens": [
      {
        "token": "vis_a_vis",
        "startOffset": 0,
        "endOffset": 9,
        "position": 0
      },
      {
        "token": "vis_à_vis",
        "startOffset": 0,
        "endOffset": 9,
        "position": 0
      },
      {
        "token": "means",
        "startOffset": 10,
        "endOffset": 15,
        "position": 1
      },
      {
        "token": "opposite",
        "startOffset": 16,
        "endOffset": 24,
        "position": 2
      }
    ]
  }

カスタム アナライザーの更新

アナライザー、トークナイザー、トークン フィルター、文字フィルターは、いったん定義すると変更できません。 インデックスの更新要求で allowIndexDowntime フラグが true に設定されている場合に限り、既存のインデックスに新しい定義を追加できます。

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

この操作を行うと、インデックスは少なくとも数秒間オフラインになるため、インデックス付けとクエリの要求は失敗します。 インデックスを更新した後の数分間、インデックスが非常に大きい場合はさらに長く、インデックスのパフォーマンスと書き込み可用性が損なわれる場合がありますが、これらの影響は一時的であり、しばらくすると自動的に解決します。

組み込みアナライザー

組み込みアナライザーをカスタム オプションと共に使用する場合、カスタム アナライザーの作成は、これらのオプションを指定するためのメカニズムです。 これに対して、組み込みのアナライザーをそのまま使用する場合は、フィールド定義でそれを名前で参照するだけで済みます。

¹ アナライザーの型は、PatternAnalyzer が実際には #Microsoft.Azure.Search.PatternAnalyzerとして指定されるように、コード内で常に #Microsoft.Azure.Search というプリフィックスが付けられます。 簡潔にするためプレフィックスを省略しましたが、コードではプレフィックスが必要です。

analyzer_type は、カスタマイズ可能なアナライザーに対してのみ提供されます。 keyword アナライザーのようにオプションがない場合は、関連付けられる #Microsoft.Azure.Search の種類はありません。

文字フィルター

文字列がトークナイザーに到達する前に、文字フィルターによる処理が追加されます。

Azure AI Search では、次の一覧の文字フィルターがサポートされます。 それぞれの詳細については、Lucene API リファレンスを参照してください。

¹ 文字フィルターの型は、MappingCharFilter が実際には #Microsoft.Azure.Search.MappingCharFilterとして指定されるように、コード内で常に #Microsoft.Azure.Search というプリフィックスが付けられます。 テーブルの幅を小さくするためプレフィックスを削除しましたが、コードには忘れずに含めてください。 char_filter_type は、カスタマイズ可能なフィルターに対してのみ提供されることに注意してください。 html_strip のようにオプションがない場合は、関連付けられる #Microsoft.Azure.Search の種類はありません。

Tokenizer

トークナイザーでは、連続するテキストが一連のトークンに分割されます (文を単語に分割したり、単語を原型にしたりします)。

Azure AI Search では、次の一覧のトークナイザーがサポートされます。 それぞれの詳細については、Lucene API リファレンスを参照してください。

¹ トークナイザーの型は、ClassicTokenizer が実際には #Microsoft.Azure.Search.ClassicTokenizerとして指定されるように、コード内で常に #Microsoft.Azure.Search というプリフィックスが付けられます。 テーブルの幅を小さくするためプレフィックスを削除しましたが、コードには忘れずに含めてください。 tokenizer_type は、カスタマイズ可能なトークナイザーに対してのみ提供されることに注意してください。 letter トークナイザーのようにオプションがない場合は、関連付けられる #Microsoft.Azure.Search の種類はありません。

トークン フィルター

トークン フィルターは、トークナイザーによって生成されたトークンを除外したり加工したりする目的で使用されます。 たとえば、すべての文字を小文字に変換する lowercase フィルターを指定することができます。 トークン フィルターは、カスタム アナライザーの中で複数割り当てることができます。 トークン フィルターは、その指定順に実行されます。

次の表で、Apache Lucene を使用して実装されているトークン フィルターについては、Lucene の API ドキュメントへのリンクを示してあります。

¹ トークン フィルターの型は、ArabicNormalizationTokenFilter が実際には #Microsoft.Azure.Search.ArabicNormalizationTokenFilterとして指定されるように、コード内で常に #Microsoft.Azure.Search というプリフィックスが付けられます。 テーブルの幅を小さくするためプレフィックスを削除しましたが、コードには忘れずに含めてください。

関連項目

• Azure AI Search REST APIs
• Azure AI Search でのアナライザー (例)
• インデックスを作成する (REST)