Azure Search on @johtaniの日記 3rd

インデックスエイリアス - Azure Cognitive Searchの新機能

Wed, 18 May 2022 15:54:17 +0900

Azure Cognitive Searchで2月に新しい機能が公開されました。「Index Alias」（インデックスの別名）です。まだ、パブリックプレビューの段階ですが、ドキュメントなどが公開されていたのでどんな機能かを調べてみました。なお、本ブログの内容は2022/05/18時点での内容となります、ご注意ください。

公式ドキュメント

まずは公式ドキュメントです。1つ目の「インデックスの別名を作成する」の冒頭で別名（エイリアス）がどんなものかを説明しています。

REST APIのドキュメント（2022/05/18現在、日本語のページだと左のメニューが壊れているため、どんなAPIがあるかがわかりにくいため、Alias Operationsのページは英語のリンクになっています）

インデックスエイリアスってどんなもの？

文字通り、インデックスにエイリアス（別名）をつけることができるようになります。 Azure Cognitive Searchでは残念ながらインデックスを作成するタイミング以外ではインデックスの名前を変更できません。このため、インデックスのスキーマ（Analyzerの設定変更など）を変更したい場合、新しいインデックスを作成します。新しいインデックスの名前はこれまでのものとは別の名前になってしまうため、アプリケーションで指定しているインデックス名も書き換える必要が出てきます。利用しているアプリが複数ある場合は、すべて変更が必要です。

今回出てきたエイリアスを利用することで、アプリケーションではエイリアスを指定することで、アプリケーション側の変更なくインデックスを入れ替えることができるようになります。

エイリアスの操作方法

公式ドキュメントにAPIの一覧や利用方法の記載があるので詳細はそちらをご覧ください。本ブログでは、いくつか利用するときに気になった点を書き残しておきます。

作成

aliasesというエンドポイントにエイリアスの名前とインデックス名をPOSTすることで作成できます。以下のサンプルは公式ドキュメントの例です。

POST /aliases?api-version=2021-04-30-preview
{
    "name": "my-alias",
    "indexes": ["hotel-samples-index"]
}

ちなみに、インデックスの指定がindexesで配列になっていますが、公式ドキュメントに以下の記述があり、複数の指定はできないです（エラーが返ってきます）。

indexes 配列に指定できるインデックスの名前は 1 つだけです。

また、1つのインデックスに対して複数のエイリアスをつけることは問題ありません。

確認

エイリアスのリストも取得できます。

GET /aliases?api-version=2021-04-30-preview

現在どんなエイリアスが、どのインデックスに対して付与されているかがリストで取得できます。きちんと作成されたかどうかなどの確認にも使えるかと思います（もちろんエイリアス名を指定したGETも可能です）

検索での利用

検索のREST APIでインデックス名を指定していた部分をエイリアス名に置き換えるだけです。

POST /indexes/my-alias/docs/search?api-version=2021-04-30-preview
{
    "search": "pool spa +airport",
    "searchMode": any,
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

更新

エイリアスの更新（インデックスの入れ替え）は作成と同じリクエストです。更新が成功すれば204のステータスコードが返ってきます（エイリアス初回作成時は201）なお、ドキュメントには以下のような記述があります。入れ替え時の注意点になるかと（入れ替えのタイミングをきちんと制御したい場合は、少しだけアプリケーションを停止するなどが必要かと思います）。

別名に対する更新がシステムに反映されるまでに最大 10 秒かかります。以前その別名が対応付けられていたインデックスを削除するのは、10 秒以上待ってからにしてください。

削除

もちろん削除もできます。

DELETE /aliases/my-alias

エイリアスを利用する場合の注意点

便利なエイリアスですが、エイリアスが使用できない場合もあるので注意が必要です。

データ登録のAPIと検索のAPIでのみエイリアス名を利用可能
- インデックスの設定変更やAnalyze Text APIではこれまで通りインデックス名を指定します。
- また、エイリアス名はインデクサー機能でtargetIndexNameにも指定できません。
エイリアス名がついているインデックスは削除不可
- エイリアスがついているインデックスを削除しようとした場合はエラーが出るようになっています。
- まずはエイリアスを削除してからインデックスを削除するという手順になります。

まとめ

簡単ですが、インデックスのエイリアスに関しての紹介でした。まだパブリックプレビューなので正式リリース時点では利用方法が変わっている可能性もあります。こちらは注意してください。

正式公開されればですが、今後Azure Cognitive Searchを使ったアプリを開発する場合はインデックスエイリアスを利用することを基本にするのがいいかもなと思います（ちなみに、Elasticsearchにもインデックスエイリアスの機能がありますが、異なる点が多いので同じものとは思わないほうがよさそうです）。

Azure Cognitive SearchのIndex Schema JSONをCSVで見たくなる

Wed, 22 Dec 2021 11:54:31 +0900

Azure Cognitive Searchのスキーマの確認をするときに、Azureのポータルでは次のようにフィールドの一覧として見ることができます。

ただ、実際のインデックス定義はJSON形式でやり取りする形になっています（JSONの例：Create Index | Microsoft Docs）。上記のスクリーンショットのようにフィールド数が少ない場合はそれほど気にならないのですが、フィールド数が大きくなると一覧で見たくなることがあります。また、ポータルを自分で確認できない場合にJSONファイルを受け取って確認することもあります。こういう時は、Excel（CSV）って便利ですよね？

ということで、サクッと確認するときには、次のようなjqコマンドをWSL2上で利用して、CSVに変換して確認しています。

echo "Name", "Type", "Searchable", "Facetable", "Filterable", "Retrievable", "Sortable", "Analyzer", "IndexAnalyzer", "SearchAnalyzer" > index_schema.csv
cat index_schema.json | jq -r '.fields[]|[.name, .type, .searchable, .facetable, .filterable, .retrievable, .sortable, .analyzer, .indexAnalyzer, .searchAnalyzer]|@csv' >> index_schema.csv

例えばこんな感じになります（上記のポータルのスクショとは別のスキーマですが。。。）。

どんなフィールドオプションが利用されているか？などをExcelで開いてフィルターなどを活用してチェックするのには便利かなと。 jqコマンドをもっとうまく使うと、ヘッダ行ももっとスマートに出せるかもしれないんですが。。。

ちなみに、上記のコマンドでは残念ながらEdm.ComplexType（参考：複合データ型をモデル化する方法 - Azure Cognitive Search | Microsoft Docs）には対応していません。必要になった時に考えるかな。。。

Azure Cognitive Searchの新機能、Semantic Searchを試してみた

Thu, 01 Jul 2021 18:09:43 +0900

Azure Cognitive Searchで新機能「Semantic Search（セマンティック検索）」という機能の日本語対応が発表されました。実際にはPublic Previewという状態ではありますが、どんな機能か気になったので調べてみました。なお、本ブログは2021年6月時点での内容となります。

公式ドキュメント

公式ドキュメントでいろいろと説明されています。まずは公式ドキュメントを見ていただくのが良いかなと。最初のドキュメントには10分ちょっとの紹介ビデオもあります。ピックアップしたのは概要、クエリ、レスポンスの構造、紹介ブログになります。ブログ以外は日本語（たぶん機械翻訳？）になっています(新機能の紹介の日本語ページにはまだ記載がありません)。

簡単にですがデータを入れて試してみたので、どんな仕組みなのかどういう挙動なのかを紹介します。

Semantic Searchとは？

言語理解、セマンティック関連性などを提供する機能です。BingとMSリサーチにより開発されて、Azure Cognitive Searchに導入されました。クエリの書き方を少し変更する必要がありますが、再インデックスや設定変更などは必要ないという仕組みになっています。

検索クエリからコンテキストを読み取って、検索し、リランクするアルゴリズム(Semantic Ranker)
関連する一節を強調表示（Semantic Caption）
クエリに対するセマンティック回答(Semantic Answer)
スペルチェック機能

言語によって利用できる機能が異なります。

Semantic Searchの利点は先ほどの紹介にも書きましたが、インデキシング時に特殊処理をする必要がないことかなと。すでに登録してあるデータ（制限がありますが）でもすぐに試すことができます。

仕組み

https://docs.microsoft.com/ja-jp/azure/search/media/semantic-search-overview/semantic-query-architecture.png

スペル修正機能
クエリパース
スコアリング
上位50件に対してSemantic Rankerにより再評価（検索ヒットが50件以上の場合でも上位50件のみがリランクの対象）
- 言語表現モデルを利用
- 結果の要約として最適な部分をキャプションとして抽出。
- クエリが質問形式の場合は一番よさそうな場所を回答として選択

1および4番目の処理が今回新しく使えるSemantic Searchの機能になります。スペルチェックは日本語がまだ対象外なので、4番目の機能について紹介します。

利用できる環境と制限

冒頭でも書きましたが、Public Previewの段階です。実際に利用するにはリクエストページから申し込みが必要になっています。

利用リクエスト時に利用するAzure Cognitive Searchのサービス名が必要になるので、あらかじめ起動しておかなければいけません。また、利用できるリージョンが限定されているのでサービス起動時のリージョンには気を付けてください。

利用できるリージョン
- 米国中北部、米国西部、米国西部 2、米国東部 2、北ヨーロッパ、西ヨーロッパ
利用できるTier
- セマンティック検索はStandardレベル
- スペルチェックはレベル制限なし
価格（セマンティック検索のみ）
- 7月初旬までは25万クエリで500ドル
Analyzerの制限
- Azure Cognitive Searchが提供する言語アナライザーが対象（Custom Analyzerでは利用不可）

サービス起動後にプレビュープログラムを申請すると、利用できるようになるとメールが届きます。そこから利用ができるようになります。

今回は日本語のWikipediaのデータをいれてどんな機能なのかを確認してみました。

Wikipediaのデータを入れて試してみた

日本語のWikipedia（あとで英語も入れました）を一部（10万件程度）登録してSemantic Search（主にRanker）の動きを確認してみました。

データの登録には自作ツールを利用。

JSONデータ生成ツール：https://github.com/johtani/wiki-extractor-rs
JSONデータ登録ツール：https://github.com/johtani/wiki-json-loader

日本語Wikipediaの2020年6月のデータ、英語Wikipediaの2021年6月のデータを利用。上記ツールで生成したもののうち約10万件をAzure Cognitive Searchに登録して動作確認をしました（英語のデータでJSONデータ生成ツールでバグがあるのですが修正していません。。。）。また、クエリの実行にはVisual Studio CodeのREST Client拡張(どんなものかは以前のブログをご覧ください)を使いました。簡単にREST APIを呼び出せるのはすばらしい。

日本語のWikipedia

日本語のWikipediaのデータを「96,344件」登録し実験しました。スキーマは次のような形です（説明に必要なものだけ抽出してあります）。自然分が入っているtitle、contents、headingsの3つのフィールドを今回はSemantic Searchの対象にしてみるので、AnalyzerをLuceneベースの日本語Analyzerであるja.luceneを設定しました。

フィールド名 : タイプ / Analyzer
id : Edm.String / keyword
categories : Collection(Edm.String) / keyword
title : Edm.String / ja.lucene
contents : Edm.String / ja.lucene
headings : Edm.String / ja.lucene

Analyzerに言語Analyzerを設定するくらいで、他の設定は特に必要ありません。

クエリとデータの確認

デモの動画や説明のサンプルを見たところ英語で「Where was Alan Turing born?」や「What’s the capital of France?」のような自然文のクエリが出てきたので、次のようなクエリで試してみました。

フランスの首都はどこですか？

実際にパリのページがインデックスに存在していることは以下のクエリで確認しました。

パリ：3047件

POST https://{{host}}/indexes/{{index-name}}/docs/search?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: {{api-key}}

{
    "count": true,
    "search": "パリ",
    "top": 10,
    "searchFields": "title, categories, contents",
    "select": "title, id, contents"
}

※ここで{{host}}などはREST Client拡張で変数として定義したものです。

host : Azure Cognitive Searchのサービス名
index-name : インデックス名
api-key : 接続のためのAPIキー

URLパラメータのapi-version=2020-06-30-PreviewがPreview機能を呼び出すための指定になっています。

3047件の1件目が「パリ」のページで以下のようなWikipediaの文章をセクションごとに文字列としてページ全体を配列に入れてcontentsに登録してあります。

"パリ（、巴里）は、フランス北部、イル＝ド＝フランス地域圏にある都市。フランスの首都であり、イル＝ド＝フランス地域圏の首府である。\nフランス最大の都市であり、同国の政治、経済、文化などの中心である。ロンドンと共に欧州を代表する世界都市。行政上では、1コミューン単独で県を構成する特別市であり、ルーヴル美術館を含む1区を中心に、時計回りに20の行政区が並ぶ（エスカルゴと形容される）。",

このインデックスに対して「フランスの首都はどこですか？」というクエリを、セマンティック検索のクエリと通常のクエリの2パターンで検索をしてみました。

これまでのクエリ（セマンティックではない検索）

まずは通常のクエリです。 searchがクエリ文字列、searchFieldsが検索対象フィールドになります。

POST https://{{host}}/indexes/{{index-name}}/docs/search?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: {{api-key}}

{
    "top": 100,
    "count": true,
    "search": "フランスの首都はどこですか？",
    "searchFields": "title, contents",
    "select": "title,  id"

}

クエリを実行するとヒット件数が'13996’件で、トップ5件のデータは次のようになりました。

  "@odata.count": 13996,
  "value": [
    {
      "@search.score": 17.059355,
      "id": "462",
      "title": "首都"
    },
    {
      "@search.score": 16.086372,
      "id": "21053",
      "title": "首都圏"
    },
    {
      "@search.score": 15.059893,
      "id": "71414",
      "title": "どこでもドア"
    },
    {
      "@search.score": 14.086605,
      "id": "51972",
      "title": "首都機能移転"
    },
    {
      "@search.score": 12.996841,
      "id": "3877",
      "title": "首都の一覧"
    },

見るとわかりますが、「首都」「どこ」といった単語を含むデータが上位に入っています。「フランス」を含むデータは8件目と10件目に「フランス植民地帝国」、「ラ・フランス」といったデータが出てきます。

    {
      "@search.score": 12.705561,
      "id": "129279",
      "title": "フランス植民地帝国"
    },
    ...
    {
      "@search.score": 12.036648,
      "id": "3173",
      "title": "ラ・フランス"
    },

残念ながら望んでいる結果にはほど遠いかと。

どんな検索になっているのでしょうか？まずは、クエリの解釈から。デフォルトで、Azure Cognitive Searchはデフォルトでは、入力された文字列をtype=simple、mode=anyで検索します（クエリパラメータ参照）。対象となるフィールドはsearchFieldsで今回は指定してあるので、これらのフィールドに対して、入力された文字列を渡してAnalyzerで単語分割し（今回はsimpleクエリ用の特殊文字が入っていないため文字列として扱われる）、出てきた単語で（mode=anyだから）OR検索します。 ja.luceneのAnalyzerが出力する単語列がどんなものかは以下のリクエストを実行するとわかります。

POST https://{{host}}/indexes/{{index-name}}/analyze?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: {{api-key}}

{
   "analyzer":"ja.lucene",
   "text": "フランスの首都はどこですか？"

}

結果は以下の通りです。

  "tokens": [
    {
      "token": "フランス",
      "startOffset": 0,
      "endOffset": 4,
      "position": 0
    },
    {
      "token": "首都",
      "startOffset": 5,
      "endOffset": 7,
      "position": 2
    },
    {
      "token": "どこ",
      "startOffset": 8,
      "endOffset": 10,
      "position": 4
    }
  ]

これで、どのような単語が出てきているかがわかりました。それぞれのフィールドでどのようなスコアになっているかまではわからないですが、検索結果には上記3つの単語のいずれかがsearchFieldsにヒットすれば出てきます。おそらく、ヒットした単語数が多い、短い文字列のフィールドがより高いスコアになるというような動きになっていると思われます（BM25になってるはず）。

セマンティック検索

では、セマンティック検索のクエリに変更してみましょう。

POST https://{{host}}/indexes/{{index-name}}/docs/search?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: {{api-key}}

{
    "top": 100,
    "count": true,
    "search": "フランスの首都はどこですか？",
    "searchFields": "title, contents",
    "select": "title,  id",
    "queryType": "semantic",
    "queryLanguage": "ja-jp"
}

queryType、queryLanguageがセマンティック検索のクエリを実行するためのパラメータになります（公式ガイド参照）。今回は日本語のデータであるため、日本語のモデルを利用するようにqueryLanguageを指定します（許可されていない文字列を渡すとエラーになる）。この2つを追加するだけです。簡単ですね。

結果は次のようになります（上位5件抜粋）。

  "@odata.count": 13996,
  "value": [
    {
      "@search.score": 12.036648,
      "@search.rerankerScore": 2.3456064984202385,
      "@search.captions": [
        {
          "text": "ラ・フランス",
          "highlights": "<em>ラ・フランス</em>"
        }
      ],
      "id": "3173",
      "title": "ラ・フランス"
    },
    {
      "@search.score": 11.144733,
      "@search.rerankerScore": 2.3173404783010483,
      "@search.captions": [
        {
          "text": "ラン (フランス)",
          "highlights": "<em>ラン</em> (<em>フランス)</em>"
        }
      ],
      "id": "108094",
      "title": "ラン (フランス)"
    },
    {
      "@search.score": 11.144793,
      "@search.rerankerScore": 2.1937477812170982,
      "@search.captions": [
        {
          "text": "ブレスト (フランス)",
          "highlights": "<em>ブレスト</em> (<em>フランス)</em>"
        }
      ],
      "id": "116154",
      "title": "ブレスト (フランス)"
    },
    {
      "@search.score": 10.199907,
      "@search.rerankerScore": 2.1590753793716431,
      "@search.captions": [
        {
          "text": "フランス・ハルス",
          "highlights": "<em>フランス・ハルス</em>"
        }
      ],
      "id": "81566",
      "title": "フランス・ハルス"
    },
    {
      "@search.score": 11.273148,
      "@search.rerankerScore": 2.1434053033590317,
      "@search.captions": [
        {
          "text": "バカロレア (フランス)",
          "highlights": "<em>バカロレア</em> (<em>フランス</em>)"
        }
      ],
      "id": "54514",
      "title": "バカロレア (フランス)"
    },

検索結果数を見ると、通常のクエリと同じ値です。これは、公式ドキュメントのセマンティック検索に説明があるように、セマンティック検索が通常のクエリで実行した後の検索結果に対して、上位50件のデータだけに対してsemantic rankerによってスコアを再計算するという仕様のためです（ドキュメントからの推測）。

実際に検索結果の50件目、51件目は次のようになっていました。50件目までのデータには@search.rerankerScoreというスコア（と@search.captions）が追加されています。 51件目のデータについては、前の通常のクエリの51件目のデータと同じデータでした。

    {
      "@search.score": 10.909212,
      "@search.rerankerScore": 0.07321979058906436,
      "@search.captions": [
        {
          "text": "首都高速埼玉大宮線",
          "highlights": null
        }
      ],
      "id": "67667",
      "title": "首都高速埼玉大宮線"
    },
    {
      "@search.score": 10.049902,
      "id": "68569",
      "title": "スタッド・ド・フランス"
    },

上位5件のデータに戻ります。これらは、通常のクエリとは異なる結果となりました。見ると@search.captionsというところにハイライトされた項目が表示されています。検索クエリをもとにそれっぽい部分がキャプションという形で返ってくる仕組みです。

結果を見るとわかりますが、残念ながら「パリ」のページは返ってきませんでした。もともと通常のクエリを実行したときの「326」番目の結果として返ってきているため、セマンティック検索の対象とはならなかったためです。ただ、「首都」「どこ」といった単語よりも「フランス」に関するドキュメントが通常の検索よりも上位に来ています。クエリに存在する単語で「フランス」がより重要であると判断されているようです。

Semantic Rankerに処理させてみる

ちなみに、今回登録したデータにはWikipediaのカテゴリも登録してあります。「ヨーロッパの首都」というカテゴリで絞り込んでから検索してみるとどうなるかもやってみました。 filterのパラメータが絞り込み条件です。

POST https://{{host}}/indexes/{{index-name}}/docs/search?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: {{api-key}}

{
    "top": 100,
    "count": true,
    "search": "フランスの首都はどこですか？",
    "searchFields": "title, contents",
    "select": "title,  id",
    "queryType": "semantic",
    "queryLanguage": "ja-jp",
    "filter": "search.ismatch('ヨーロッパの首都', 'categories')"
}

結果は次の通りです。カテゴリで絞り込みをしているので検索結果数は39件となります。このため、すべてのデータがSemantic Rankerの対象です。ですが、「パリ」のページは11件目に出てきました。

  "@odata.count": 39,
  "value": [
    {
      "@search.score": 3.8405614,
      "@search.rerankerScore": 2.0472740978002548,
      "@search.captions": [
        {
          "text": "ウィーン",
          "highlights": null
        }
      ],
      "id": "9465",
      "title": "ウィーン"
    },
...
    {
      "@search.score": 4.8915977,
      "@search.rerankerScore": 1.8480307757854462,
      "@search.captions": [
        {
          "text": "レイキャヴィーク",
          "highlights": "<em>レイキャヴィーク</em>"
        }
      ],
      "id": "112253",
      "title": "レイキャヴィーク"
    },
...
    {
      "@search.score": 7.277628,
      "@search.rerankerScore": 1.7982495501637459,
      "@search.captions": [
        {
          "text": "パリ",
          "highlights": "<em>パリ</em>"
        }
      ],
      "id": "31",
      "title": "パリ"
    },

キャプションは入力された単語だけではなく、クエリが持っている単語をもとにした何かしらの基準（おそらく言語モデルで近い単語？）で選択されていると思われます。首都というカテゴリーで絞り込んでしまったので、ヒットした文章が似たようなものが多くなったせいか、残念ながらそこまでSemantic Rankerが意図を汲み取るところまでは行きませんでした。

フランスの歴史

視点を変えてみましょう。質問そのものの答えではなく、クエリの意図に近いものが出てくるかを見てみましょう。ここまでのクエリでフランスに関するクエリを投げていました。今回のインデックスに「フランスの歴史」で検索すると「30820」件のドキュメントがヒットし、上位にはフランスには関係ない「歴史」のページや「フランス」の文学、都市など「フランスの歴史」とは少し離れた意味のものが上位に来ています。

  "@odata.count": 30820,
  "value": [
    {
      "@search.score": 12.888079,
      "id": "17875",
      "title": "スコットランドの歴史"
    },
    {
      "@search.score": 12.718105,
      "id": "10665",
      "title": "世界の歴史"
    },
    {
      "@search.score": 12.701981,
      "id": "31397",
      "title": "ベトナムの歴史"
    },
    {
      "@search.score": 12.579847,
      "id": "22433",
      "title": "フランス文学"
    },
    {
      "@search.score": 12.524254,
      "id": "34667",
      "title": "フランスの国旗"
    },
    {
      "@search.score": 12.52136,
      "id": "108094",
      "title": "ラン (フランス)"
    },
    {
      "@search.score": 12.41088,
      "id": "20717",
      "title": "歴史小説"
    },
    {
      "@search.score": 12.388911,
      "id": "56229",
      "title": "演劇の歴史"
    },
    {
      "@search.score": 12.343941,
      "id": "39669",
      "title": "イギリスの歴史"
    },

このクエリをセマンティッククエリで検索すると次のようになりました。

  "@odata.count": 30820,
  "value": [
    {
      "@search.score": 12.274498,
      "@search.rerankerScore": 1.482184374704957,
      "@search.captions": [
        {
          "text": "自由フランス",
          "highlights": "<em>自由フランス</em>"
        }
      ],
      "id": "96475",
      "title": "自由フランス"
    },
    {
      "@search.score": 11.446766,
      "@search.rerankerScore": 1.3535655084997416,
      "@search.captions": [
        {
          "text": "フランスの地域圏",
          "highlights": "<em>フランスの地域圏</em>"
        }
      ],
      "id": "51845",
      "title": "フランスの地域圏"
    },
    {
      "@search.score": 10.926437,
      "@search.rerankerScore": 1.3261859538033605,
      "@search.captions": [
        {
          "text": "フランス第一帝政",
          "highlights": "<em>フランス第一帝政</em>"
        }
      ],
      "id": "57573",
      "title": "フランス第一帝政"
    },

上位には「フランスの歴史」に関連しそうなタイトルが上がってきています。また、先ほど「歴史」という単語でヒットして上位に来ていた「スコットランドの歴史」は@search.rerankerScoreの値が低くなっていました（31件目に出現）。


    {
      "@search.score": 12.888079,
      "@search.rerankerScore": 0.42768346797674894,
      "@search.captions": [
        {
          "text": "スコットランドの歴史",
          "highlights": null
        }
      ],
      "id": "17875",
      "title": "スコットランドの歴史"
    },

考察

日本語のWikipediaを約10万件入れたインデックスでセマンティック検索を試してみました。デモや説明などでクエリが自然文の質問だったこともあり、質問の回答になりそうなページが上に来るかと期待しましたが、期待しすぎました。

これは、Azure Cognitive Searchのセマンティック検索の仕組みを考えると納得のいくものです。説明を読んだ時にも感じたのですが、入力された文字列でまず検索をし、上位50件をセマンティック検索の対象としています。

ですので、そもそもクエリの文章に出てくる単語が含まれたデータだけが対象となります。このため、クエリに出てこない単語のみで構成されているものは残念ながら対象とできません。また、上位50件だけがSemantic Rankerの対象となっているため、検索にヒットしたとしても上位に食い込まなければ言語モデルによるランキングの対象にもなりません。セマンティック検索といっても、残念ながらドキュメントに出てこない単語（似た単語、質問に対するそのものの回答）まで読み取る機能はありません。

ただ、「フランスの歴史」の検索で見たようにそれぞれの単語だけで検索をしていた場合とは異なり、クエリの意味に沿ったスコアづけにより、通常の検索よりも意図したものに近いデータが出ていることが確認できました。複数の単語で構成されるクエリの場合に、単語だけでスコアを計算した場合よりもよさそうな結果が上位に出てくることがわかりました。

ただし、重要なのは「上位50件」までしかSemantic Rankerの対象にはならない点です。

英語のWikipedia

セマンティックは英語対応が一番最初にリリースされているので、英語のWikipediaについてもデータを登録してみました。

英語のWikipediaのデータを「111,649件」登録しました。スキーマは以下の通り（今回の調査に利用していないものは省略）です。日本語と異なる点はAnalyzerがen.luceneになっていることぐらいです。

フィールド名 : タイプ / Analyzer
id : Edm.String / keyword
categories : Collection(Edm.String) / keyword
title : Edm.String / en.lucene
contents : Edm.String / en.lucene
headings : Edm.String / en.lucene

クエリとデータの確認

日本語同様に首都に関する質問形式にしてみました。

What’s the capital of Italy?

実際にRomeのページがインデックスに存在していることは以下のクエリで確認済みです。

Rome：2302件

POST https://{{host}}/indexes/{{index-name}}/docs/search?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: {{api-key}}

{
    "count": true,
    "search": "Rome",
    "top": 10,
    "searchFields": "title, contents",
    "select": "title, id, contents"
}

以下のようなWikipediaの文章をセクションごとに文字列としてページ全体を配列に入れてcontentsに登録してあります（これも日本語と同じです）。

""\n\nRome (Italian and Latin: Roma ) is the capital city and a special comune of Italy (named Comune di Roma Capitale), as well as the capital of the Lazio region. The city has been a major human settlement for almost three millennia. With 2,860,009 residents in , it is also the country's most populated comune...",

このデータ群に対して「What’s the capital of Italy?」というクエリを、Semantic Searchのクエリと通常のクエリの2パターンで検索をしてみる。

これまでのクエリ（セマンティックではない検索）

まずは、Semantic Searchではないクエリです。

POST https://{{host}}/indexes/{{index-name}}/docs/search?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: {{api-key}}

{
    "top": 100,
    "count": true,
    "search": "What's the capital of Italy?",
    "searchFields": "title, contents",
    "select": "title,  id"

}

ヒット件数は18049件で、トップ5件は次のような形です。

  "@odata.count": 18049,
  "value": [
    {
      "@search.score": 17.870815,
      "id": "14532",
      "title": "Italy"
    },
    {
      "@search.score": 16.596167,
      "id": "14702",
      "title": "Economy of Italy"
    },
    {
      "@search.score": 16.180624,
      "id": "183878",
      "title": "Louis II of Italy"
    },
    {
      "@search.score": 15.917025,
      "id": "29665",
      "title": "State capitalism"
    },
    {
      "@search.score": 15.88901,
      "id": "215741",
      "title": "Capitalization"
    },

日本語の場合よりもItalyに関連するものが上位に多く含まれます。ただ、Rome自体のページは上位50件には出てきていませんでした。また、capitalとは意味の異なるcapitalizationやcapitalismが上位に来ています。日本語の場合と同様にクエリがどのように解釈されているのか？も見てみます。

POST https://{{host}}/indexes/{{index-name}}/analyze?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: {{api-key}}

{
   "analyzer":"en.lucene",
   "text": "What's the capital of Italy?"

}

結果は以下の通りです。

  "tokens": [
    {
      "token": "what",
      "startOffset": 0,
      "endOffset": 6,
      "position": 0
    },
    {
      "token": "capit",
      "startOffset": 11,
      "endOffset": 18,
      "position": 2
    },
    {
      "token": "itali",
      "startOffset": 22,
      "endOffset": 27,
      "position": 4
    }
  ]

日本語とあまり変わってはいません。ただ、単語が入力されたものとは少し変わっています。これは、en.luceneの処理で、stemmingが行われているためだと思われます。たとえば、「capital」の場合、Stemmingにより「capital」「capitalize」などの単語が元になりますが、動詞、名詞などの違いなく検索できるようにするためにこのようなStemmingの処理が行われます。ということで、これらの単語を含むドキュメントがヒットしています。Italyが一番上に来ているのはItalyという単語が多く含まれるからのようです。

Semantic Searchクエリ

では、Semantic Searchのクエリに変更してみましょう。

POST https://{{host}}/indexes/{{index-name}}/docs/search?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: {{api-key}}

{
    "top": 100,
    "count": true,
    "search": "What's the capital of Italy?",
    "searchFields": "title, contents",
    "select": "title,  id",
    "queryType": "semantic",
    "queryLanguage": "en_us"
}

queryType、queryLanguageがsemantic searchのクエリを実行するためのパラメータになります（公式ガイド参照）。今回は英語のデータであるため、英語のモデルを利用するようにqueryLanguageを指定します（許可されていない文字列を渡すとエラーになる）。

結果は次のようになります（上位5件抜粋）。

  "@odata.count": 18049,
  "value": [
    {
      "@search.score": 17.870815,
      "@search.rerankerScore": 1.9688458815217018,
      "@search.captions": [
        {
          "text": "Italy",
          "highlights": null
        }
      ],
      "id": "14532",
      "title": "Italy"
    },
    {
      "@search.score": 14.239678,
      "@search.rerankerScore": 1.9419755563139915,
      "@search.captions": [
        {
          "text": "Capital city",
          "highlights": null
        }
      ],
      "id": "181337",
      "title": "Capital city"
    },
    {
      "@search.score": 10.181764,
      "@search.rerankerScore": 1.8902588561177254,
      "@search.captions": [
        {
          "text": "Lepontii",
          "highlights": null
        }
      ],
      "id": "325133",
      "title": "Lepontii"
    },
    {
      "@search.score": 10.865718,
      "@search.rerankerScore": 1.875102698802948,
      "@search.captions": [
        {
          "text": "ItalY",
          "highlights": null
        }
      ],
      "id": "14482",
      "title": "ItalY"
    },
    {
      "@search.score": 11.689348,
      "@search.rerankerScore": 1.8201303631067276,
      "@search.captions": [
        {
          "text": "Savoy",
          "highlights": null
        }
      ],
      "id": "27885",
      "title": "Savoy"
    },

日本語で見てきたように、検索結果数を見ると、通常のクエリと同じ値で、残念ながら50件までにRomeは入っていないため、Semantic Rankerによるブーストもかかりませんでした。ただし、「Capitalization」や「State capitalism」といった別の意味（地理に関するものではない単語）のものが上位に出てこなくなっています。これは、capitalという単語が地理に関する意味を持っていると判断された結果のように見えます。 Capitalizationの@search.rerankerScoreは上位のスコアに比べて小さいものとなっています。

    {
      "@search.score": 15.88901,
      "@search.rerankerScore": 0.93921028636395931,
      "@search.captions": [
        {
          "text": "Capitalization",
          "highlights": null
        }
      ],
      "id": "215741",
      "title": "Capitalization"
    },

What’s the capital of Finland?

上位50件以内(20件目)に「Helsinki」のページが出てくるクエリでセマンティック検索をしてみました。


POST https://{{host}}/indexes/{{index-name}}/docs/search?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: {{api-key}}

{
    "top": 100,
    "count": true,
    "search": "What's the captial of Finland?",
    "searchFields": "title, contents",
    "select": "title,  id",
    "queryType": "semantic",
    "queryLanguage": "en-us"
}

結果としては、2件目にHelsinkiが返ってきていたので、Semantic Rankerがによる並び替えがうまくいきました。（下記の結果は上位3件を抜粋したものです）。

  "@odata.count": 16673,
  "value": [
    {
      "@search.score": 14.026371,
      "@search.rerankerScore": 2.42378556355834,
      "@search.captions": [
        {
          "text": "Vanaja (Finland)",
          "highlights": null
        }
      ],
      "id": "7132102",
      "title": "Vanaja (Finland)"
    },
    {
      "@search.score": 12.434971,
      "@search.rerankerScore": 2.383675143122673,
      "@search.captions": [
        {
          "text": "Helsinki",
          "highlights": null
        }
      ],
      "id": "13696",
      "title": "Helsinki"
    },
    {
      "@search.score": 13.380153,
      "@search.rerankerScore": 2.2026549801230431,
      "@search.captions": [
        {
          "text": "Rauma, Finland",
          "highlights": null
        }
      ],
      "id": "178635",
      "title": "Rauma, Finland"
    },

考察

今回の英語のクエリではSemantic Rankerがある程度の役割をはたしていそうだということはわかりました。 Capitalがいくつもの意味を持っていることもあり、文章をもとにより意味の近いドキュメントが上位に来たということです。ただ、英語の場合も基本的には上位50件以内のデータに対して処理が行われるので上位50件以内にデータが入らなければうまくいかないようです。

まとめ

Azure Cognitive Searchの新機能であるセマンティック検索について調べてみました。まだPublic Previewですが、簡単に使えるような仕組み（データの再登録なし、クエリでパラメータを追加するだけ）が用意されているのは便利でした。ただ、最初に想像していたもの（私の早とちりもありますが）ほどのセマンティック検索とは行きませんでした。似たような言葉の意味を持ったものを探してくれたり、答えそのもののページのスコアがすごく高くなるといったものではありませんでした。

仕組み上、クエリに含まれる単語で検索し、上位50件以内のデータだけが対象になる(残念ながら現時点ではこの件数の変更はできません。)ため、これまでの検索とは劇的に変化するものではないことはわかりました（銀の弾丸はないんですけどね）。

ある程度の挙動をわかっていれば、Wikipediaのようなデータでもそれなりの結果は取得できそうだということはわかりました。

「言語モデル」でクエリとヒットしたデータをもとにスコア計算をし直しているようですが、この部分がどのようなデータ・クエリだと有効活用できるのか？というのをもう少しいろいろな角度で試してみる必要がある気がします（適材適所が何なのか？）。あとは、上位50件までが対象なので、それ以上の件数のデータの並びに関してはこれまでと同様の結果となる点は注意しないといけません。また、今回試していないほかの機能（スペルチェック、Semantic Answerなど）にメリットがあるのかもしれません。

ざっくりですがセマンティック検索について調べてみました。こんなデータだとどうなの？ここの考え方が間違ってるのでは？などの指摘がありましたら、コメント欄またはTwitter（@johtani）でコメントを頂けたらと。

OData式と日本語の検索(NGram)とフレーズ検索

Wed, 03 Mar 2021 16:23:33 +0900

Azure Cognitive SearchにはOData式という書式で条件が書ける仕組みがあります。 ODataは検索条件（$filter）やソート条件（$orderby）、取得する項目名の指定（$select）です。

私は、Luceneの構文に慣れているので、普通のsearchパラメータを利用しようとします。が、OData式として特殊な書き方がいくつかあるようなのでこちらの利用方法も調べてみました。その時、N-Gram（よくやるのはN=2）で陥る問題の話もあるのでこちらについても言及します。

OData式で検索

次のような3件のドキュメント(フィールド名はbodyとします)をN-Gramで登録していたとします。

ミルクティを飲みたいです。
マティーニはカクテルですが、ミルクセーキは？
風呂上がりのミルクは最高です。

この時、OData式でミルクティという単語で検索してみましょう。

検索条件は$filterで指定します。フルテキスト検索用に関数が用意されており、こちらに単語を指定します。

$filter=search.ismatchscoring('ミルクティ')

こんな感じ。フィールドの指定がない場合、対象のフィールドは検索可能なフィールドすべてが検索対象になります（公式ガイドのクエリパラメータのqueryTypeに説明あり）。

では、実行してみましょう。で返ってくるのは？1だけかな？と思う人が多いかもしれません。が、結果は3件とも帰ってきます。

問題点は？

では問題点はどこでしょう？ ismatchscoringのオプションなどを見る前に、転置インデックスを用いた検索エンジンの挙動をおさらいしましょう。転置インデックスの仕組みを理解することで、なぜそんな挙動になるのか？というのがわかりやすくなります。おさらいにはElasticsearchをベースに話をしますが、Azure Cognitive Searchでも同じような挙動になります。

転置インデックスとトークナイザー（アナライザー）の関係（おさらい）

昨年、オンラインで開催されたOSC広島で発表した資料（録画あり）でもざっくりと説明しています。

View 本当にその検索は自分が想像している検索になってますか？ on Notist.

ざっくりですが、おさらいです。

検索エンジンでは、入力された文章を、ある規則（アナライザー）で単語に分割し、その単語ごとにどのドキュメントに出現したのか？というリストが作られます。このリストが転置インデックスです。書籍の後ろにある索引を想像するとどんなものかがわかりやすいです。単語に対してその単語が出てくるページ番号がわかるという仕組みです（下図は本の索引の一例）。

書籍の索引は著者や編集の方により厳選された単語のみが採用されています。が、検索エンジンでは文章を単語に区切る機能が存在します。この「ある規則」で単語を区切る仕組みが「アナライザー（トークナイザー）」と呼ばれる機能です。例えば英語用のアナライザーに英語の文章が入力されたとき、文章はこのように単語に区切られたもの（単語列）を出力します（下図）。

今回はNGramの話なので、NGramのAnalyzerを利用してみるとこんな感じになります。

実際に出来上がる転置インデックスは次のような形になります。

検索の仕組み（おさらい）

出来上がっている転置インデックスに対して検索をする場合、入力文字列（検索条件）に対して、転置インデックス作成時と同様にAnalyzerが動作します。処理としては、

クエリのパース
フィールドのAnalyzerで処理
転置インデックスを検索

という形です。例えばこんな感じ。

同じAnalyzerの処理が入ることで、転置インデックスに採用されているのと同じ単語が出てくるため、検索がきちんとできるということになります。

英語と日本語（NGram）の違い

英語と日本語の違いは、スペースの意味になります。英語の場合は、スペースが単語の区切りになりますが、日本語の場合スペースでは区切られていません。

ですので、検索窓に入力された文字列は、英語の場合、クエリのパースの時点で単語に区切られます。そのあとにAnalyzerになるので、基本的には単語単位でAnalyzerの処理が動きます。そのあと、転置インデックスへの検索となります。なので、多くの場合はAnalyzerの出力は1単語です（類義語などを利用していたりする場合は異なりますが）。

日本語の場合、スペースでは区切られていないので、クエリのパースの時点で入力された文字列がそのままAnalyzerにわたります。今回はAnalyzer（NGram）が単語に分割し、それをもとに検索処理が実行されます。

ismatchscoringの問題点は？（やっと帰ってきました）

さて、回り道をし、簡単ですが転置インデックスやAnalyzerについて説明しました。では本題です。

$filter=search.ismatchscoring('ミルクティ')

このismatchscoring関数ですが、そのほかにも引数の指定が可能で、省略した場合にデフォルトで採用される値がいくつかあります。公式のドキュメントにパラメータの意味が掲載されています。

今回は、第4引数のsearchModeの値が問題点です。デフォルトでは、anyが指定されます。この、anyは検索語（今回はミルクティ）の任意の検索語句が一致する必要があることになります。「検索語句」？なんでしょう？これが、ここまで回り道をして説明してきた、Analyzerの出力した単語になります。「ミルクティ」はNGram（N=2）のAnalyzerを通すと、

「ミル」「ルク」「クテ」「ティ」

という4つの単語が出力されます。これが、「検索語句」です。「任意の」とあるので、上記4つの2文字のどれか？が出現すれば検索条件にヒットしたこととなります。

ですので、以下のように（一部のみ色を変えてます）3つの文章にはそれぞれの文字が含まれているため、先ほどの条件では3件の結果が返ってくることになります。

ミルクティを飲みたいです。
マティーニはカクテルですが、ミルクセーキは？
風呂上がりのミルクは最高です。

NGramで一部分の単語だけで一致したものがヒットしてしまうと違和感があるので、allに変更します。

$filter=search.ismatchscoring('ミルクティ', 'body', 'simple', 'all')

今度はどうなるでしょう？

ミルクティを飲みたいです。
マティーニはカクテルですが、ミルクセーキは？

先ほどよりもマシになりました。 3がヒットしなくなっています。3の文章には「ティ」などが出てこないためです。ただ、感覚的に2番目がヒットするのは少し違和感がありますよね？確かに4つの単語がすべて出てきていますが、「ミルクティ」とは少し遠いです。

さらに「ミルクティ」にヒットさせるにはフレーズ検索にする必要があります。 Elastic社のブログの日本語の検索に関する記事でも出てきますが、フレーズで検索することで「ミルクティ」だけにヒットさせることができます。

「フレーズ検索＝語順を保証する検索」となります。ですので、

「ミル」「ルク」「クテ」「ティ」

この順序で出てきた場合のみ、検索にヒットしたことになります。 OData式でフレーズ検索する場合は、単語をダブルクォート"でくくる必要があります（公式ドキュメントの例に記載あり）。

$filter=search.ismatchscoring('"ミルクティ"', 'body', 'simple', 'all')

これで結果は以下の1件だけとなります。

ミルクティを飲みたいです。

これでNGramで部分一致のような挙動で日本語の検索ができるようになりました。

ちなみに、フレーズにした場合は第4引数はanyに変更しても1件だけの検索結果となります。フレーズ検索には「すべての語が含まれる」、「すべての語が順番に現れる」という2つの条件が含まれるためです。

$filter=search.ismatchscoring('"ミルクティ"', 'body', 'simple', 'any')

この例の引数をミルクティを"ミルク" "最高"のような検索条件に変えた場合、「“ミルク”」「“最高”」の2つの条件をanyで扱うため、「“ミルク”」「“最高”」のどちらかが出てくれば良い結果となり、3件の結果が返ってきます。第4引数をallに変更すると、「“ミルク”」「“最高”」の両方が出てこなければならないため、3件目のデータのみが返ってきます。

$filter=search.ismatchscoring('"ミルクティ" "最高"', 'body', 'simple', 'all')

これは、

$filter=search.ismatchscoring('"ミルクティ"', 'body', 'simple', 'any') and search.ismatchscoring('"最高"', 'body', 'simple', 'any')

と同じ意味となります。少し長くはなりますが、後者の書き方をプログラムで書くと思います、私の場合は。検索窓に入力された単語に必ず"を追加する処理を書くために、画面入力の文字列を一旦パースをすることになるからです。

まとめ

簡単？にですが、OData式でのフルテキスト検索と、NGramでのフレーズ検索について説明しました。英語の場合、もともとスペースで区切られているので、フレーズといわれてピンときますが、日本語の場合はAnalyzerの挙動をわかっていないと「？」となるかと思います。なぜフレーズ検索が必要なのか？というのが少しでもわかっていただければと。ちなみに、NGramのTokenizerには別の落とし穴もありますが、その話はまた後日にでも。

参考として日本語関連の検索に関する記事のリンクを残しておきます。

参考

Elasticsearch日本語でフレーズ検索が必要なわけ
NGramも含め、Elasticsearchでの日本語の検索の設定やクエリについては、Elastic社のブログで日本語で書かれた記事が詳しいのでこちらをご覧いただくのがいいです。

Azure Cognitive Searchでオートコンプリートやサジェストをしてみる

Fri, 05 Feb 2021 17:52:00 +0900

Azure Cognitive SearchにSuggestやAutocompleteの機能があるのを見つけたので、どんな挙動なのかを調べてログとして残しておきます。

公式ドキュメント

日本語で公式ドキュメントが公開されています。使い方や流れについてはこちらをまずは見れば使えると思います。

本ブログでは、ざっくりとした機能の紹介と内部がどんな挙動をしていそうか？、日本語だとどういう感じになるのか？という点を紹介しようと思います。

どんな機能？

検索窓でよく、キーワードを入力しているときに検索キーワードの候補が表示されることがあります。このキーワードの候補を表示するための機能が今回紹介するSuggesterと呼ばれる機能です（日本語の公式ドキュメントでは「先行入力エクスペリエンス」）。 Suggesterには、以下の2つの機能が用意されています。

Autocomplete：キー入力しているときに、入力されている文字列で始まる単語で、検索できるもの（転置インデックスに登録されている単語）をリストで返す機能
Suggestion：入力した文字列で始まるキーワードを含む、元のデータを返す機能

利用方法

Suggesterの機能を利用するにはインデックスに設定を追加する必要があります（新規、既存どちらでも可）。ただ、既存のインデックスに設定を追加した場合、内部にすでに存在するドキュメント（データ）については、このSuggesterのデータは作られません。ですので、既存データを再度登録しなおすといった作業が必要となるので注意が必要です。

本ブログでは、いくつかAzure Cognitive Searchのサンプルのリクエストが出てきます。Visual Studio CodeのREST Client Extensionの書式となります。拡張機能の簡単な紹介は昨年のブログをご覧ください。

設定編

Suggesterの設定では、主に以下の2つを設定する必要があります。

name: suggesterの名称。クエリ時に指定します。
sourceFields: 入力データのもととなるフィールド名。
- String型のみ指定可能。また、Azureで用意されたアナライザーだけが利用可能です。自分で用意するカスタムアナライザーは利用できないので注意が必要です（制限についてはこちら）。

今回使用するサンプルのインデックス設定は次の通りです。

インデックス作成のリクエスト（@host、@api-keyはご自身のものに置き換えてください。）

## 設定
@host = 名前.search.windows.netと記載
@api-key = APIキーを入力

### Create index with suggester
POST https://{{host}}/indexes/?api-version=2020-06-30
Content-Type: application/json
api-key: {{api-key}}

{
    "name":"suggester-test",
    "fields":[
       {
          "name":"id",
          "type":"Edm.String",
          "key":true,
          "searchable":false
       },
       {
          "name":"name",
          "type":"Edm.String",
          "searchable":true,
          "analyzer":"ngram_analyzer"
       },       
       {
          "name":"category",
          "type":"Edm.String",
          "filterable":true,
          "facetable": true
       }
    ],
    "suggesters": [
       {
          "name": "name_suggester",
          "searchMode": "analyzingInfixMatching",
          "sourceFields": [
             "name"
          ]
       }
    ]
}

公式ドキュメントのサンプルでは日本語がないので、日本語のデータも入力しています。

データ登録リクエスト

### Index data
POST https://{{host}}/indexes/suggester-test/docs/index?api-version=2020-06-30
Content-Type: application/json
api-key: {{api-key}}

{
  "value": [
    {          
      "@search.action": "upload",  
      "id": "1",
      "name": "Microsoft Office",
      "category": "microsoft"
    },
    {          
      "@search.action": "upload",  
      "id": "2",
      "name": "Microsoft Azure",
      "category": "microsoft"
    },
    {          
      "@search.action": "upload",  
      "id": "3",
      "name": "GitHub Enterprise",
      "category": "github"
    },
    {          
      "@search.action": "upload",  
      "id": "4",
      "name": "GitHub dot com",
      "category": "github"
    },
    {          
      "@search.action": "upload",  
      "id": "5",
      "name": "Bluetooth Mic",
      "category": "hardware"
    },
    {          
      "@search.action": "upload",  
      "id": "6",
      "name": "東京スカイツリー",
      "category": "japanese"
    },
    {          
      "@search.action": "upload",  
      "id": "7",
      "name": "東京タワー",
      "category": "japanese"
    },
    {          
      "@search.action": "upload",  
      "id": "8",
      "name": "東京特許許可局",
      "category": "japanese"
    },
    {          
      "@search.action": "upload",  
      "id": "9",
      "name": "グランメゾン東京",
      "category": "japanese"

    },
    {          
      "@search.action": "upload",  
      "id": "10",
      "name": "東京都庁",
      "category": "japanese"
    }
  ]
}

以上が事前準備です。データ登録時に内部でSuggester用のデータを内部で生成しているようです（公式ドキュメント）。

クエリ編

最初に説明しましたが、Suggesterの中ではAutocompleteとSuggestionという2種類の機能が用意されています。それぞれについて例をもとに説明していきます。

Autocomplete API

検索窓に入力された文字を元に、前方一致でどのような単語で検索できるか？という候補を表示するための機能です（2単語も対応していますが今回は省略。APIの仕様はこちら）。

たとえば、micという文字が入力されているところでAutocomplete APIを呼び出す時は、次のようなリクエストです。searchというパラメータに入力値を与えます。suggesterNameはインデックス作成時につけた名前になります。

POST https://{{host}}/indexes/suggester-test/docs/autocomplete?api-version=2020-06-30
Content-Type: application/json
api-key: {{api-key}}

{
   "search": "mic",
   "suggesterName": "name_suggester"
}

レスポンスとして、次のようなJSONが返ってきます。

{
  "@odata.context": "...",
  "value": [
    {
      "text": "microsoft",
      "queryPlusText": "microsoft"
    },
    {
      "text": "mic",
      "queryPlusText": "mic"
    }
  ]
}

サンプルデータとして登録したデータにcategoryというフィールドを入れていました。 Autocompleteは条件を絞り込んで結果を返すこともできます。 filterにODataの書式で条件を書けます。 categoryフィールドにmicrosoftが設定されているデータだけを取得するということができます。

### Autocomplete with filter
POST https://{{host}}/indexes/suggester-test/docs/autocomplete?api-version=2020-06-30
Content-Type: application/json
api-key: {{api-key}}

{
   "search": "mic",
   "suggesterName": "name_suggester",
   "filter": "category eq 'microsoft'"
}

レスポンスはこちら。先ほどとは違い、micというデータは返ってきていません。

{
  "@odata.context": "...",
  "value": [
    {
      "text": "microsoft",
      "queryPlusText": "microsoft"
    }
  ]
}

英語の場合、「単語」の単位は字面の通りです。スペースで単語が区切られているのでわかりやすいです。日本語の場合は普通の人には少し想像しにくいです。 東京という文字を入力してみます。

### Autocomplete in Japanese
POST https://{{host}}/indexes/suggester-test/docs/autocomplete?api-version=2020-06-30
Content-Type: application/json
api-key: {{api-key}}

{
   "search": "東京",
   "suggesterName": "name_suggester"
}

すると返ってくるのは以下の通り「東京」だけになります。

{
  "@odata.context": "...",
  "value": [
    {
      "text": "東京",
      "queryPlusText": "東京"
    }
  ]
}

入っているデータは「東京スカイツリー」、「東京タワー」などです。普通に考えると、これらがそのまま返ってくると思うかもしれませんが、違います。

これは、Suggesterの元となるフィールドのAnalyzerの挙動によります。今回のインデックスのnameフィールドのanalyzerにはja.luceneです。これは、日本語用のアナライザー（Kuromoji）になります。いわゆる形態素解析器で日本語の文字列を「単語」に分割します。英語についてはスペース区切りで分割しますが、日本語についてはKuromojiが内部の辞書とアルゴリズムに基づいて単語に分割してくれます。 Azure Cognitive Searchでは、Analyzerの挙動を確認するためのAPIも用意してあるので実行しみると、

### Autocomplete in Japanese
POST https://{{host}}/indexes/suggester-test/analyze?api-version=2020-06-30
Content-Type: application/json
api-key: {{api-key}}

{
   "text": "東京スカイツリー",
   "analyzer": "ja.lucene"
}

このような結果が返ってきます。

{
  "@odata.context": "...",
  "tokens": [
    {
      "token": "東京",
      "startOffset": 0,
      "endOffset": 2,
      "position": 0
    },
    {
      "token": "スカイ",
      "startOffset": 2,
      "endOffset": 5,
      "position": 1
    },
    {
      "token": "ツリー",
      "startOffset": 5,
      "endOffset": 8,
      "position": 2
    }
  ]
}

ja.luceneのAnalyzerによって、3つの単語に分割されているのがわかります。 Autocomplete APIの実行結果も、このAnalyzerによって分割された単語をもとに、候補となる単語を前方一致で検索して結果を返しているのです。ですので、「東」と入れても「東京」が返ってくるのがわかります。一方で、「東京ス」と入力した場合は次のような結果となります。

{
  "@odata.context": "...",
  "value": [
    {
      "text": "スカイ",
      "queryPlusText": "東京スカイ"
    }
  ]
}

これは、autocompleteModeと呼ばれるパラメータの挙動となります。デフォルトでは、oneTermという設定で、最後の単語（例の「東京ス」の場合は「東京」「ス」と区切られるので「ス」という文字を単語とみなす）にマッチする単語（例では「スカイ」）が返ってきます。 queryPlusTextについては、入力された文字にtextで返ってきた単語をくっつけたものが取得できます。

英語であれば、スペースで区切られており、単語が切れているのが簡単にイメージできますが、日本語の場合は少し違和感が出るかと。

このように、入力された文字が含まれる「単語」を基本的に返す動作をするのがAutocomplete APIです。

Suggest API

では、もうひとつのSuggest APIはどういったものでしょうか？ autocomplete APIに似ていますが、返ってくるデータが登録されたデータそのものになります。

たとえば、micという文字列を入力とした場合、

POST https://{{host}}/indexes/suggester-test/docs/suggest?api-version=2020-06-30
Content-Type: application/json
api-key: {{api-key}}

{
   "search": "mic",
   "suggesterName": "name_suggester"
}

次のような結果が返ってきます。Autocompleteの時は単語でしたが、こちらは入力データがそのまま返ってきています。入力データの中にmicで始まる単語が含まれたものが候補となっています。

{
  "@odata.context": "...",
  "value": [
    {
      "@search.text": "Bluetooth Mic",
      "id": "5"
    },
    {
      "@search.text": "Microsoft Office",
      "id": "1"
    },
    {
      "@search.text": "Microsoft Azure",
      "id": "2"
    }
  ]
}

日本語の場合、Autocompleteとは異なり、その単語を含むものがサジェストされるので、「東京」をsearchに指定すると「東京」を含むデータが出てきます。

### Suggest in Japanese
POST https://{{host}}/indexes/suggester-test/docs/suggest?api-version=2020-06-30
Content-Type: application/json
api-key: {{api-key}}

{
   "search": "東京",
   "suggesterName": "name_suggester"
}

レスポンスはこちら。単語を含む元の文字列が返ってきます。ここまでは違和感はありません。

{
  "@odata.context": "...",
  "value": [
    {
      "@search.text": "東京タワー",
      "id": "7"
    },
    {
      "@search.text": "グランメゾン東京",
      "id": "9"
    },
    {
      "@search.text": "東京都庁",
      "id": "10"
    },
    {
      "@search.text": "東京スカイツリー",
      "id": "6"
    },
    {
      "@search.text": "東京特許許可局",
      "id": "8"
    }
  ]
}

では、「東京」「特許」という2つの単語をスペースで区切ったものが入力されたとするとどうでしょう？

### Suggest in Japanese
POST https://{{host}}/indexes/suggester-test/docs/suggest?api-version=2020-06-30
Content-Type: application/json
api-key: {{api-key}}

{
   "search": "東京 特許",
   "suggesterName": "name_suggester"
}

スペースがありますが、内部処理では形態素解析器が分割した後でこの単語の順番で出てくるものを探しているので、出てくることになります。

{
  "@odata.context": "...",
  "value": [
    {
      "@search.text": "東京特許許可局",
      "id": "8"
    }
  ]
}

なお、このSuggestのAPIは、単語の語順を気を付ける必要があります。「特許」「東京」と順序を入れ替えたスペース区切りの場合は、

### Suggest in Japanese
POST https://{{host}}/indexes/suggester-test/docs/suggest?api-version=2020-06-30
Content-Type: application/json
api-key: {{api-key}}

{
   "search": "特許 東京",
   "suggesterName": "name_suggester"
}

結果は返ってこないです。おそらく内部では、フレーズクエリで、最後の単語だけを前方一致で検索するような仕組みが動いているのだと思われます。スペースで区切られてはいるが、順序があるので少し違和感を感じるかもしれません。英語だとフレーズの部分のイメージは沸きやすいのですが。

短い文章のデータ（例：本のタイトルやランドマーク名など）では、このSuggestAPIを利用するとデータそのものが返却されるので、便利かもしれません。

まとめ

ということで、Azure Cognitive SearchのSuggesterの簡単な紹介でした。APIのページにはそのほかのパラメータについても説明があるので、使ってみようと思う方は目を通していただくのがよいかと。

今回のブログは裏の仕組みがどんな感じなのか？を想像しながらAPIについて調べた形になります。日本語の場合に、少し違和感を覚える人もいそうだろうなということでブログを書いてみました。今回は書いていませんが日本語でAutocompleteをやりたい場合は、読み仮名でも漢字が表示されるほうがよいという場合もあると思います。その場合は、用意されている機能では難しいので、独自実装するといった方法になりそうです。英語や、読みを利用しない場合は、挙動を理解していれば役に立つ場面もありそうです。

TerraformでAzure Cognitive Searchのクラスターを起動

Tue, 18 Aug 2020 18:26:47 +0900

負荷を計測するために、数回、Azure Cognitive Searchのクラスターを起動したり、停止したりしてました。これは、Terraformでやると楽できるのでは?と思ったので、やってみました。 1パーティションのクラスターなので、全然大したことはないのですが、メモを残しておくためにブログに書いておきます。

基本的にはTerraformの公式ドキュメントにあったものを自分用に変数を抽出しただけです。

ファイルたち

単にクラスターを起動するためだけなので、2種類のファイルだけ作成しました(1個でもいいかも)。

variables.tf - 変数用のファイル。いくつかの設定を変数として定義しました。
terraform.tf - Terraform本体のファイル。

`variables.tf`

まずはvariables.tfです(ファイル内の並びは異なりますが。。。)。terraform.tfで利用する5つの変数です。

resource_group - リソースグループ名。既存とは異なるリソースグループ名にしました(変に壊してもいいので)。
machine_type - 価格レベル(SKU)。公式ドキュメントに設定できる値の一覧があります。今回はWikipediaのデータを登録していたのでそれが入るサイズにしています。
region - 場所(リージョン)。リージョンの一覧はどこにあるんだろう?これを参考にしましたが。
partition_size - パーティションのサイズ(=Elasticsearchでのシャードかな?)です。今回は1つでの性能を計測したかったので1にしてあります。
search_cluster_name - Azure Cognitive Searchのサービス名。search.windows.net名前空間で一意である必要があったので、他の人が使わなそうな名前をつけています。

variable "machine_type" {
  default = "standard"
}

variable "region" {
  default = "East Asia"
}

variable "resource_group" {
  default = "johtani-wiki-test"
}

variable "search_cluster_name" {
  default = "johtani-wikipedia"
}

variable "partition_size" {
  default = 1
}

`terraform.tf`

terraform.tfは以下の通り。Terraformの公式ドキュメントにある例にproviderを追加しただけのものになります。

provider - プロバイダーの設定。Azureを利用するという宣言です。features {}がないとエラーになります。空でも必ず指定が必要です。認証周りについては、azure-cli経由で認証する方式を採用しました。azure-cliはHomebrewでインストールしています。
azurerm_resource_group - リソースグループの設定。variables.tfのresource_groupとregionを利用しています。必須項目はこの2種類だけです。
azurerm_search_service - Azure Cognitive Searchの設定。partition_count以外は必須項目です。variables.tfとazurerm_resource_groupの設定を利用しています。今回は利用していませんが、レプリカ数なども指定できるようになっています。

# Azureのproviderを指定。
provider "azurerm" {
  features {}
}

# リソースグループの設定
resource "azurerm_resource_group" "wiki-test" {
  name     = var.resource_group
  location = var.region
}

# Azure Cognitive Searchの設定
resource "azurerm_search_service" "search_service" {
  name                = var.search_cluster_name
  resource_group_name = azurerm_resource_group.wiki-test.name
  location            = azurerm_resource_group.wiki-test.location
  sku                 = var.machine_type
  partition_count     = var.partition_size
}

以上がファイルです。ほぼ公式ドキュメントのサンプル通りですねw

デプロイとか

ファイルの準備ができたら実際にデプロイします。 Azureの環境への認証にはAzure CLIを利用して、事前にログインした状態にします。実際にデプロイするまでの手順は次のようになります。

az login - Azureの認証。ブラウザが起動してログイン画面が表示されます。無事認証がOKなら、azコマンドでAzure Cloudの情報が取得できます。
terraform init - 初回だけです。Terraformのワーキングディレクトリの初期化処理を実行します。
terraform plan - Terraform < 0.12の場合は実行。最新版だともういらないみたいだ。
terraform apply - 実際にAzure上にクラスターを起動します。Terraformが隠蔽してくれているので、実際にどんなことをやっているかはわかってないですが。

以上で、Azure Cognitive Searchのクラスターが起動します。すごく簡単です。Webコンソールでチェックすれば、起動していることも確認できます。

この状態では、クラスターが起動しただけなので、あとは必要に応じてデータをロードしたり、アプリから検索したりと行ったことが可能になります。そのへんの話はまた機会があれば。

Destroy

今回は負荷テスト用にクラスターを起動していましたので、必要なくなれば、クラスターを削除します。Terraformを導入したもう一つの理由がこの簡略化です。 terraform destroyを実行するだけで、Azure Cognitive Searchのクラスターおよび、リソースグループが削除されます。

まとめ

ということで、ほぼ公式ドキュメントのままですが、TerraformでAzure Cognitive Searchのクラスターを起動する方法の紹介でした。ブログを書いていて、1点気になったのは、ロケーション(リージョン)の一覧はどこにあるんだろう?という点です。azコマンドとかで出てくるのかなぁ?

Azure Cognitive Searchでの日本語向けAnalyzerの違い

Tue, 09 Jun 2020 17:44:00 +0900

Azure Cognitive Searchで日本語を扱うときに、形態素解析器を使いたい場合、2種類のAnalyzerが用意されています。今回はこれらの違いがどんなものかを見ていくことにします。

Analyzerとは?

まずは、その前にAnalyzerとは何者か?というのを少しだけ。 Azure Cognitive Searchは転置インデックスを内部で作成して、検索を行っています。この、転置インデックスは、「単語」がどのドキュメントに入っているか?を素早く見つけることができるデータ構造となっています。

Azure Cognitive Searchは、この「単語」を入力された文章から生成するときに、Analyzerというものを利用します。 Analyzerは入力された文章をある規則に則って単語に分割する機能です。この「ある規則」が、各種言語や用途によって様々に用意されています。今回はこの中のja.luceneとja.microsoftという2種類のAnalyzerについて違いを見ていきます。

2種類のAnalyzerの違いはどんなもの?

このAnalyzerの挙動を見るためのエンドポイントとしてanalyzeというAPIがあります(詳細は昔のブログを参照)。

このAPIを利用して、Wikipediaのいくつかの文章を単語に区切って見て、 ja.microsoftがどんな動きをしているのか想像してみます(残念ながらja.microsoftの仕様?や挙動についてはページが見つからないため)。

もとの文章と解析結果(一部抜粋)

文章は、手元のElasticsearchに登録したjawikiのデータからランダムに抽出しています。また、自前のツールで生成したWikipediaのデータなので、まだ一部、見苦しい文字列になっています(そっちもなおさないと)。

1. 砂川（熊本県）

thumb|250px|right|上砂川橋より上流方砂川（すながわ）は、熊本県宇城市・八代郡氷川町を流れる二級河川。

この文字列から抽出された単語で特徴的なものを一部抜粋しました。

`ja.microsoft`	`ja.lucene`
250px	250
	px
上砂	上, 上砂川
川橋	砂川
	橋
宇城	宇
市	城市
二級	二
^	級

まず、最初の250pxですが、ja.microsoftでは、pxが単位であると判定しているのか、数値と合わせた単語として抽出されています。この場合、250で検索しても、この文字列はヒットしない形になるので、ノイズが減ることが考えられるかと。

上砂川橋という文字は、分割の仕方が別れました。 ja.luceneでは、上砂川という単語が地名として辞書に存在するために、このような分割になっています。ja.microsoftのデータは品詞の情報が取れないのですが、上砂、川橋ともに、名詞として辞書に存在しているのではないかなと。ja.luceneには川橋という単語は存在していないようでした。

宇城市(うきし)については、2005年に合併でできた市のようで、ja.luceneが利用している辞書には存在しない可能性があり、宇城という文字が抽出できてないと思われます。

最後は二級です。ja.luceneでは、数字と助数詞として分割されています。こちらも何かしらのロジックにより、二級という1単語でヒットできるように数字と単位?が合わせた単語で出てくる仕組みがja.microsoftなのかなと。

2. UEFA U-18女子選手権2000

UEFA U-18女子選手権2000は第3回目のUEFA U-18女子選手権である。決勝トーナメントは2000年7月27日から8月4日までフランスで行われ、ドイツが初優勝を果たした。

この文字列から抽出された単語で特徴的なものを一部抜粋しました。

`ja.microsoft`	`ja.lucene`
u-18, u	u
18, nn18	18
第3回目	第
	3
	回
	目
トーナメント, トナメント	トーナメント
2000年	2000
	年
7月	7
	月
27日	27
	日

数字を含む単語第3回目や2000年、7月などは、ja.microsoftは先程と同様、数字と単位の組み合わせを1単語として出力しています。

また、トーナメントという単語をトナメントという形で、長音を除去した形で出力しています。今回の文字列ではないですが、この他に、センターをセンターとセンタの2パターンの単語で出力するといったことを行っています。 ja.luceneの場合、単語の最後に長音がある場合だけセンタとして、長音を除去した単語が出力されます。これは、長音の表記ゆれに対応するためではないかなと。たとえば、インターフェースとインタフェース、インターフェイスのように、人や文章によって、間にでてくる長音を使ったり使わなかったりという表記ゆれに対応するためだと思われます。その他にも、イプロゥヴェトをイプロゥベトに、ネクストをネキストに、バラエティをバラエチにも変換するなどといった処理をしてくれるようです。カタカナの表記ゆれには強そうですね(これどうやってるんだろう?)。

ja.microsoftでは、nn18というちょっと変わった単語も出てきていました。純粋な数字の場合はnnと入力してくれるようで、数字だけで検索したい場合に利用できるのかな?これはドキュメントに書いておいてほしいかも?

共通点

ja.lucene、ja.microsoftともに、共通している動作として、「てにをは」といった単語は除去されていました。違いがあるものとしては、「より」(助詞-格助詞-一般)、「されている」(動詞-自立、動詞-接尾、助詞-接続助詞、動詞-非自立)、「ある」(助動詞)といったものはja.microsoftでは除去されずに出てきていました。ストップワード的に「てにをは」あたりを除去をしている感じでしょうか?

アルファベットで構成されている単語についても、基本はそのまま出力される挙動のようでした。

じゃあどっちがいいの?

残念ながらどちらがいいかは、一長一短かなぁと。 ja.luceneに関しては、Luceneの仕組みを利用しているので、Elasticsearchなどを使えば、個別の単語についてより詳細の情報を取得することが可能です(品詞、読みなど)。ja.microsoftについては、残念ながら手の入れようがないので、そういう動きのものだという割り切った使い方になるでしょうか? ただ、長音の除去による表記ゆれなどについては、便利な機能なので、そのあたりの問題に対応したい場合は、ja.microsoftを活用するのも良いかと思います。

個人的には、より細かい単語としてインデックスに登録できるもののほうが、柔軟な検索には対応できるのではないかなぁと考えています(Kuromojiの辞書をUniDicにするとか?も考えますが、これはAzure Searchではできないですが)。

まとめ

Wikipediaのデータをいくつか使って、ja.microsoftとja.luceneの違いについて、考察してみました。何かの役に立てばと。他に、これはどんな感じになるの?などありましたら、コメントいただければと。

Azure Cognitive Searchのリクエストのロギング

Tue, 26 May 2020 17:22:47 +0900

今回はAzure Cognitive SearchのSDKを利用したアプリケーションが、実際にAzure Cognitive Searchに対して送信しているリクエストのパラメータとボディをログに保存する方法について紹介します。

動機

アプリケーションでリクエストを組み立てて、SDK経由で送信していると、最終的にAzure Cognitive Searchに対して送信されているリクエストのパラメータや検索条件などをひと目で見たいことがあります。アプリケーションでは、ソート条件や、クエリ文字列の組み立てなどの処理は異なる場所で行われたりしますので。

また、公式リファレンスでは、機能の説明はRest APIの使い方と組み合わせで説明されることが多いです。

ということで、SDKを利用しているアプリからAzure Searchへ送信されているリクエストをログに保存する方法を調べてみました。

方法

調べてみるといくつかの手段を取ることができそうだとわかりました。実際に調べて実装する方法を4種類ほど試してみたのでブログに残しておきます。なお、2020年4月時点でのSDKとAzureの仕組みに基づいたブログになります。最新版ではお手軽な方法があるかもしれません。

DelegatingHandlerを利用する
ServiceClientTracingの機能を利用する
Azure Application Insightsを活用する
Azure Cognitive Searchのコンソールにある診断情報の機能を利用する

1、2はAzure Cognitive SearchのSDKのリファレンスから当たりを付けて見つけた方法です。 3はApplication Insights、4はAzure Cognitive Searchの機能になります。これらの方法について個別に説明していきます。

1. DelegatingHandleを利用する

まずは、SDKでロギングの機能がないかを調べて見つけた機能がこちらです。 SDKのSearchServiceClientのコンストラクタの引数にDelegatingHandlerというものが渡せることを発見しました。

これは、.NET FrameworkのHttpのAPIに存在するクラスで、HTTPのクライアントがHTTPの送受信時に、処理を挟むことができる機能です。フレームワーク側で、LoggingHttpMessaggeHandlerというクラスを用意してくれていましたが、残念ながらこちらは、リクエストとレスポンスのヘッダのみをロギングするクラスでした。ということで、リクエストボディをログに出力したい場合は独自に拡張してやる必要があります。なお、ロギングにはMicrosoft.Extensions.LoggingのILoggerを使用します。

また、Azure Cognitive SearchのSDK側に違う問題点もありました。チュートリアルにあるように、検索するときには、SDKは次のような使い方を想定しています。

        // Create a service and index client.
        _serviceClient = new SearchServiceClient(searchServiceName, new SearchCredentials(queryApiKey));
        _indexClient = _serviceClient.Indexes.GetClient("hotels");

インデックス用のクライアントを取得するために、GetClient(インデックス名)というメソッドを使用します。このGetClientメソッドのバリエーションとして、DelegatingHandlerを受け取るメソッドがないのです。。。

ということで、DelegationHandlerを活用する方法としては、以下の2つを実装する必要があります。

CustomなLoggingHttpMessageHandlerクラスを実装
GetClientと同等の処理をDelegatingHandlerを引数にしたものを実装する

以上の2つを実装し、アプリケーション側から2で作成したGetClientを呼び出すことで、リクエストをボディも含めてログ出力することが可能になります。以下は実装例です。

CustomHttpMessageHandlerクラス。

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

namespace AzureSearchSample
{
    public class CustomLoggingHttpMessageHandler : DelegatingHandler
    {
        private readonly ILogger _logger;
        private readonly bool _logContent = false;

        public CustomLoggingHttpMessageHandler(ILogger logger, bool logContent)
        {
            if (logger == null)
            {
                throw new ArgumentNullException(nameof(logger));
            }

            this._logger = logger;
            this._logContent = logContent;
        }


        protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
        {
            if (request == null)
            {
                throw new ArgumentNullException(nameof(request));
            } 
            await Log.RequestStart(this._logger, request, this._logContent);
            var stopwatch = new Stopwatch();
            HttpResponseMessage response = await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
            stopwatch.Stop();
            await Log.RequestEnd(this._logger, response, stopwatch.Elapsed);

            return response;
        }

        private static class Log
        {
            private static class EventIds
            {
                public static readonly EventId RequestStart = new EventId(100, "RequestStart");
                public static readonly EventId RequestEnd = new EventId(101, "RequestEnd");
            }

            public static async Task RequestStart(ILogger logger, HttpRequestMessage request, bool logContent)
            {
                StringBuilder message = new StringBuilder();
                message.AppendLine($"Sending HTTP request {request.Method} {request.RequestUri}");
                if (logger.IsEnabled(LogLevel.Trace))
                {
                    LogHttpHeaders(message, request.Headers);
                    await LogHttpContent(message, request.Content, logContent);
                    logger.Log(
                        LogLevel.Trace,
                        EventIds.RequestStart,
                        message,
                        null,
                        (state, ex) => state.ToString());
                }
            }

            public static async Task RequestEnd(ILogger logger, HttpResponseMessage response, TimeSpan duration)
            {
                StringBuilder message = new StringBuilder();
                message.AppendLine(
                    $"Recieving HTTP response after {duration.TotalMilliseconds}ms - {response.StatusCode}");
                if (logger.IsEnabled(LogLevel.Trace))
                {
                    LogHttpHeaders(message, response.Headers);
                    await LogHttpContent(message, response.Content, false);
                    logger.Log(
                        LogLevel.Trace,
                        EventIds.RequestEnd,
                        message,
                        null,
                        (state, ex) => state.ToString()
                        );
                }
            }

            private static void LogHttpHeaders(StringBuilder message, HttpHeaders headers)
            {
                if (headers == null) throw new ArgumentNullException(nameof(headers));
                foreach (KeyValuePair<string, IEnumerable<string>> header in headers)
                {
                    foreach (string value in header.Value)
                    {
                        message.AppendLine($"{header.Key}: {value}");
                    }
                }
            }

            private static async Task LogHttpContent(StringBuilder message, HttpContent content,
                bool logContent)
            {
                if (content != null)
                {
                    foreach (KeyValuePair<string,IEnumerable<string>> header in content.Headers)
                    {
                        foreach (string value in header.Value)
                        {
                            message.AppendLine($"{header.Key}: {value}");
                        }
                    }

                    if (logContent)
                    {
                        string contentBody = await content.ReadAsStringAsync();
                        message.AppendLine(contentBody);
                    }
                }
            }
        }
    }
}

GetClientの実装


        private ISearchIndexClient GetClient(string indexName, params DelegatingHandler[] handlers)
        {
            var rootHandler = _searchServiceClient.HttpMessageHandlers.OfType<HttpClientHandler>().SingleOrDefault();
            var indexClient =
                new SearchIndexClient(_searchServiceClient.SearchServiceName, indexName,
                    _searchServiceClient.SearchCredentials, rootHandler, handlers)
                {
                    SearchDnsSuffix = _searchServiceClient.SearchDnsSuffix
                };

            indexClient.HttpClient.Timeout = _searchServiceClient.HttpClient.Timeout;
            return indexClient;
        }

出力されるログ例

2020/04/14 19:17:53.591|TRACE|Sending HTTP request POST https://サービス名.search.windows.net/indexes('インデックス名')/docs/search.post.search?api-version=2019-05-06
client-request-id: be02140f-3a07-48cc-b018-d8aa5e819bc3
Accept-Language: en-US
Accept: application/json; odata.metadata=none
api-key: APIキー
User-Agent: FxVersion/4.700.20.11803
User-Agent: OSName/MacOs
User-Agent: OSVersion/Darwin.19.4.0.Darwin.Kernel.Version.19.4.0.Wed.Mar.4.22.28.40.PST.2020.root.xnu.6153.101.6.15RELEASE.X86.64
User-Agent: Microsoft.Azure.Search.SearchIndexClient/10.100.19.52907
Content-Type: application/json; charset=utf-8
{
  "count": false,
  "facets": [],
  "queryType": "simple",
  "scoringParameters": [],
  "search": "azure",
  "searchMode": "any"
}
 |AzureSearchSample.SearchService|EventId_Id=100, EventId_Name=RequestStart, EventId=RequestStart

メリット、デメリット

Azure Cognitive Searchの検索の処理だけを対象にリクエストのログを出力することが可能です。また、影響範囲はアプリケーションだけに閉じていますので、デバッグ目的などでログ出力したい場合に、自分だけの手元でログの確認が可能になります。

デメリットとしては、独自に実装しなければいけない範囲が広いことです。

2. ServiceClientTracingの機能を利用する

Microsoft.Rest.ClientRuntimeというライブラリをAzure Cognitive Searchは利用しています。このライブラリにServiceClientTracingというクラスが存在します。なにやら、クライアントの処理のトレースができそうです。

Azure Cognitive SearchのSDKの実装がGitHubに公開されており、検索リクエストの処理を投げる直前に、このトレースの仕組がONになっていると、ServiceClientTracing.SendRequestメソッドを呼び出していました。

実際にSendRequestメソッドに送られたものに対して何かしらの処理を行うのは、IServiceClientTracingIntercepterインターフェースを実装したクラスになります。このインターフェースの実装がLog4Netに存在します。Log4Netを利用している場合は、これを活用すれば楽ができます。

実際にServiceClientTracingを有効にするには、以下の2行を呼び出すだけです。

ServiceClientTracing.IsEnabled = true;
ServiceClientTracing.AddTracingInterceptor(new Log4NetTracingInterceptor());

あとは、Rest.ClientRuntimeがよしなにやってくれます。 1とは異なり、トレースログなので、リクエストのボディについても出力してくれます。

2020-05-26 19:09:04,058 [1] DEBUG Microsoft.Rest.Tracing.Log4Net.Log4NetTracingInterceptor [(null)] - invocationId: 1
instance: Microsoft.Azure.Search.DocumentsProxyOperations
method: SearchPost
parameters: {searchRequest=Microsoft.Azure.Search.Models.SearchRequest,clientRequestId=,cancellationToken=System.Threading.CancellationToken}
2020-05-26 19:09:04,164 [1] DEBUG Microsoft.Rest.Tracing.Log4Net.Log4NetTracingInterceptor [(null)] - invocationId: 1
request: Method: POST, RequestUri: 'https://サービス名.search.windows.net/indexes('インデックス名')/docs/search.post.search?api-version=2019-05-06', Version: 2.0, Content: System.Net.Http.StringContent, Headers:
{
  client-request-id: 591cb14f-e5c2-4a85-977d-01d1f6431ddc
  Accept-Language: en-US
  Accept: application/json; odata.metadata=none
  api-key: APIキー
  Content-Type: application/json; charset=utf-8
}

Body:
{
{
  "count": false,
  "facets": [],
  "queryType": "simple",
  "scoringParameters": [],
  "search": "azure",
  "searchMode": "any"
}
}

2020-05-26 19:09:04,459 [Thread Pool Worker] DEBUG Microsoft.Rest.Tracing.Log4Net.Log4NetTracingInterceptor [(null)] - invocationId: 1
response: StatusCode: 200, ReasonPhrase: 'OK', Version: 1.1, Content: System.Net.Http.StreamContent, Headers:
{
  Cache-Control: no-cache
  Pragma: no-cache
  request-id: 591cb14f-e5c2-4a85-977d-01d1f6431ddc
  elapsed-time: 72
  OData-Version: 4.0
  Preference-Applied: odata.include-annotations="*"
  Strict-Transport-Security: max-age=15724800; includeSubDomains
  Date: Tue, 26 May 2020 10:09:04 GMT
  Content-Type: application/json; odata.metadata=none
  Expires: -1
  Content-Length: 376
}

メリット、デメリット

Log4Netを利用しているアプリの場合、2行だけを追加することで実装が完了するのがお手軽な点です。

難点としては、Rest Client全てにたいしてトレース処理が入ってしまうので、Azure Cognitive Search以外にもRestクライアントを利用しているものが存在した場合、ログの量が増えてしまいます。また、検索以外の処理でもトレースされてしまうのもデメリットになります。

Log4Net以外のログ機構を使用している場合は、自分でIServiceClientTracingInterceptorを実装する必要も出てきます(参考:StackOverflow)。

3. Azure Application Insightsを活用する

ここから紹介する3と4については、ログの出力先がAzure上になります。

AzureのApplication Insightsを利用する方法です。 Azure?.NET?のアプリケーションパフォーマンスモニタリングのサービスです。

Application Insightsを自分のアプリケーションに設定することで、アプリケーションのパフォーマンス監視に関する情報がAzure上のApplication Insightsリソースに送信されるようになります。

ただ、Application Insightsのデフォルトの機能では、URL程度の情報だけが送信されます(参考:しばやんさんのブログ)

こちらも拡張機能が用意されており、ITelemetryInitializerのインターフェースを実装したクラスを用意することで、独自の情報をApplication Insightsに出力することが可能となります。詳細についてはしばやんさんのブログを参考にしてもらうのが良いかと。

Httpリクエストを出力する実装例は次のとおりです。ただ、ちょっとうまく行かないパターンがあったので、コメントアウトとして残してあったりします(なんでだろう?)

using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;

namespace AzureSearchWebSample.ApplicationInsights
{
    public class HttpRequestInitializer : ITelemetryInitializer
    {
        public void Initialize(ITelemetry telemetry)
        {

            if (!(telemetry is DependencyTelemetry dependency))
            {
                return;
            }

            HttpRequestMessage requestMessage = null;
            HttpRequestHeaders requestHeaders;
            if (dependency.TryGetOperationDetail("HttpRequest", out var details) &&
                details is HttpRequestMessage request)
            {
                requestMessage = request;
                requestHeaders = request.Headers;            
                if (requestMessage.Method == HttpMethod.Post)
                {
                    string contentBody = requestMessage.Content.ReadAsStringAsync().GetAwaiter().GetResult();
                    dependency.Properties.Add("RequestBody",contentBody);
                }
            }
            else if (dependency.TryGetOperationDetail("HttpRequestHeaders", out details) &&
                     details is HttpRequestHeaders headers)
            {
                requestHeaders = headers;
            }
            else
            {
                return;
            }

            foreach (KeyValuePair<string,IEnumerable<string>> header in requestHeaders)
            {
                foreach (string value in header.Value)
                {
                    dependency.Properties.Add(header.Key, value);
                }
            }
            //この実装の場合は出力されなかった。なぜ?
            // if (requestMessage != null && requestMessage.Method == HttpMethod.Post)
            // {
            //     string contentBody = requestMessage.Content.ReadAsStringAsync().GetAwaiter().GetResult();
            //     dependency.Properties.Add("RequestBody",contentBody);
            // }
        }
    }
}

メリット、デメリット

すでにApplication Insightsを利用している場合はついでに情報が出力されるので便利です。かつ、常にリクエストログを見れるようにしておく場合はとても便利だと思います。

Application Insightsを利用していない場合は、そこから導入しなければならなくなるので、手間が増えるかもしれないです。

4. Azure Cognitive Searchのコンソールにある診断情報の機能を利用する。

最後はAzure Cognitive Searchの診断ログを有効にする方法です。ここまで説明してきた方法の中で、一番お手軽な方法です。。。

これまでは、リクエストボディを出力する方法を考えていましたが、Azure Cognitive Search側の診断ログを有効にすると、リクエストボディで送信したものが、Azure Cognitive Search側で、クエリパラーメータとして、診断ログに出力されます(診断ログのQuery_s)。

あとは、Azureのコンソールで当該時間のログを見ればよいだけです。以下は出力されたログの一部です。Description_sにはURLのパスが記載されています。

診断ログ例(一部)

Description_s      POST /indexes('multi-field-test')/docs/search.post.search
Query_s            ?api-version=2019-05-06&searchMode=Any&search=azure&queryType=Simple&$count=false

メリット、デメリット

アプリケーション側に手を入れる必要がなのでお手軽です。一度設定しておけばコンソール側でログをいつでも見れるので便利です。

リクエスト量が多くなってしまうと、ログの量も多くなり、費用がかさむ恐れがあります。また、複数の人が触る環境の場合は自分で送信したリクエストがどれだったのか?といった状況に陥る可能性はあります。

その他は?

Azureに対してではないですが、昔似たようなことをやるときにやっていた方法として、ローカルにプロキシサーバーを起動し、そのプロキシサーバー経由でアプリケーションから、Azureに接続することで、リクエストを保存する方法もあります。ざんねんながら、未調査ですがアプリなどにはそれほど手を入れる必要はないかと思います。

まとめ

ちょっと送信リクエストの内容が見てみたいという話でしたが、いろいろな手段が存在しました。自分の状況、環境に合わせて手段を選択肢てみるのがいいかと思います。まずは、簡単な診断ログあたりからでしょうか?

Microsoft Build(2020)のAzure Cognirive Searchのセッションを見たのでメモ

Fri, 22 May 2020 12:10:41 +0900

Mircosoft Buildというイベントが今週ありました(MSの方やお客さんに教えてもらった)。

そこで、Azure Cognitive Searchのセッション(MyBuild - Cognitive Search： The pocket-knife for knowledge mining)があったので、見てみました。内容がどんなものかをメモっておきます。最初はCognitive Searchがどんなものよという説明でした。

ビルトインスキルの拡充の話

データソースからデータを取り出し、エンリッチし、検索エンジンに保存するという、パイプラインが組めるようになっています。

このパイプラインで利用できる処理のことがスキルと呼ばれています。ここで利用できるビルトインスキルが拡充されますよという話でした。ちょっとだけ抜き出すと以下のとおりです。

Azure Machine Learning
Text translation
Brand detection
Object detection

スキルのリファレンスには載ってるものと載ってないものがあるので、今後追加されてくのかな? Brand detectionがどんなものなんだろう?ってのがちょっと気になりました。どっかにデモとかあるかなぁ?

スキルセットのための新機能 : Debug Sessionのデモ

上記のスキルを組み合わせてパイプラインを組んで、データソースから取り出したデータをエンリッチしてから、検索エンジンに入れる処理をかけるのですが、その処理のデバッグ用に新しいGUIの機能が追加されてますよという紹介とデモでした。

Tutorial： Use Debug sessions to diagnose, fix, and commit changes to your skillset - Azure Cognitive Search | Microsoft Docs

Manage Identityの話

Azure Cognitive Searchにデータを登録するパイプランの最初の段階で、各種データソースにアクセスが必要です。このアクセス時にコネクションの設定にアカウントキーなども含めてましたが、これをコネクション設定ではなく、専用の管理機能が用意されましたよという話でした。

Set up a connection to a data source using a managed identity (preview) - Azure Cognitive Search | Microsoft Docs

QA

Similarityとかの話
- BM25になってるよとか
SDKの話とか
ほかにRelevancyの話
- Analyzerをデフォルトのままじゃなくてちゃんと考えて使いましょう(例:各言語用のAnalyzerがいっぱいあるよとか)

こんな感じでした。

Visual Studio Codeのプラグインを作ってみた(Azure Search Analyze Client)

Thu, 19 Mar 2020 10:50:15 +0900

動機

Azure Cognitive Searchを検索エンジンに使っているお客さんを手伝っています。そこで、検索の基本的な話をさせていただきました(もともとJJUGナイトセミナーでしゃべる予定だったスライドがベース)。

で、Elasticsearchなどの転置インデックスを利用している検索エンジンで検索の基本的な動作がどうなっているかを理解するのに、個人的には一番重要だと思っているのがAnalysis(Analyze)の機能です。転置インデックスの単語の切り出し方がどうなっているかによって、望んだ単語でうまく検索できているかいないかなどがわかります。

Azure Cognitive SearchもAnalyze TextというAPIを提供してくれています(内部的にはElasticsearchだし)。 APIはあるのですが、返ってくる結果はJSONです。また、他のAnalyzerの設定との違いなどをみたくなったりもします。やはり、普段使っているツールなどで簡単にどういう単語が出てくるかがわかるとうれしんじゃないかなぁ?と。

ということで、最初はPythonでちょっとAPI呼び出して、カンマ区切りで出力するものを作ってみたのですが、GUIとかあると便利かなぁという話になりました。最近、ブログ書いたりするのにVisual Studio Codeを使い始めているので、これなら使いやすいかなと。ということで、Visual Studio Codeの拡張機能(プラグイン?)としてインストールできるツールを作ってみました。 Azure Cognitive Searchを使っている人向けなので、ニッチなツールですが。。。

余談

Elastic Stack(Elasticsearch)向けにはKibanaのプラグインでAnalyze APIを可視化するツールを作ってます。 analyze-api-ui-pluginです。Elastic Stack、特にKibanaを必ず利用する方はこちらを使うと便利かもです。

概要と機能

Marketplaceに公開しているので、johtaniやAzure Search Analyze Clientなどで検索してもらえれば出てきてインストールができます。

機能としては、以下の2つです。

テンプレートから入力値設定用のドキュメントを作成(Untitled-1というドキュメントをエディタに新しく開く)
Azure Cognitive SearchのAnalyze Text APIを呼び出して、結果をHTMLのテーブル形式で表示

入力値設定用のドキュメント作成

APIの呼び出しに必要な情報を記入してもらうのに、いくつか案を考えました。

プラグインの設定に記入してもらう
環境変数とかを読み出す
テキストとして保存したファイルを使う

設定や環境変数だと、異なる環境に接続したりするときに、わざわざ設定し直すのがめんどくさいかもと。で、愛用していたREST API Clientを真似するのが良いかもという結論になり、.analyzeという拡張子のファイルから必要な項目を読み出して、APIを呼び出す形にしてあります。

Command Palette(左下の歯車マークもしくは、メニューのViewから開ける)からAzure Search Analyze Client: Create Azure Search Analyze Requestというコマンドを選びます。

すると、以下のようなファイルがエディタに開きます。

これらの項目をまずは埋めていきます。それぞれの値がどういったものかはGitHubのREADMEを御覧ください。

入力値エラー(存在チェックしかしていない)がある場合は、ダイアログが表示されます。

結果表示

値を入力したら、設定値と###の間に表示されているAnalyze text with analyzersというグレーの文字をクリックします。すると、APIにリクエストを送信し、結果が返ってきて、別のパネルとして表示されます。

複数のAnalyzerを入力値に設定すると、それぞれがどのような区切り方をするかがわかります。文字の下にある[0:2]は、その単語がもとの文章の何文字目から何文字目までに出現しているかというオフセットの表示になります。

もし、Analyzer名の設定ミスなどで指定されたAnalyzerがない場合は、結果画面にエラーが表示されるようにしています。

以上が簡単な機能の説明です。簡単なと言いつつ、これだけしか機能がありませんが。

Visual Studio Codeのプラグインの作り方

プラグイン自体の作り方に関してはVisual Studio CodeのGetting Startedがわかりやすかったです。 APIや機能が豊富なので、最初はちょっと戸惑いましたが、サンプルもGitHubで多数公開されています。

あとは、REST API Clientを参考にさせていただきました。

Getting Startedを一通り読むことで、なんとなくプラグインの作成からMarketplaceへのリリースまでが完了できました。 (TypeScriptに慣れていないのがあるので、プログラミング自体は手間取りましたが。。。)

今後の対応?

いまのところ、こんなところを考えていますが、こんな機能がほしい、バグが有るなどあれば、GitHubにIssueを上げていただければと(使う人すくないだろうけど)。

いろいろなエラーに関する対応
Readmeに画像をアップ
アイコン作成?
自動補完機能?

まとめ

Visual Studio Codeの拡張機能を作ってみました。 Yeomanによるプロジェクトテンプレートが用意されているので、とりあえず、Hello worldを作るのは簡単でした。試行錯誤しつつTypeScriptを書いたので、TypeScriptっぽくないところなどもあるかもですが、誰かの役に立つツールになってくれれば良いなぁと。

Azure Cognitive Searchでインデックスを作って検索

Wed, 19 Feb 2020 11:48:01 +0900

お手伝いしているお客さんがAzure Cognitive Searchを利用してます。検索周り=Azure Cognitive Searchに関する手伝いをする形で入っており、いくつか触った感触をブログにまとめてみようかと(お客さんからはOKいただいてます)。

Azure Cognitive Searchとは？

公式サイト

「AIを活用した」クラウド検索サービスと紹介されています。

昔はAzure Searchと呼ばれていましたが、ここ最近はAzure Cognitive Searchと呼ばれているみたいです(Microsoft Igniteで発表された話がまとまっているページもあります)。もともと、検索エンジンのSaaSサービス(キーワード検索、あいまい検索、オートサジェスト、スコアリングなどの機能)として作られていた部分に、データの登録パイプラインにCognitive Serviceの便利な機能を簡単に使えるようにしたものというイメージでしょうか。

バックエンドはElasticsearchのはずです。変わってなければ。昔、Elastic社主催のユーザーカンファレンスでMSの方が公演された資料が公開されていたりします。ちなみに質問が多いのでしょうか、Azure Cognitive SearchとElasticsearchの違いはなんですか?というページがよくある質問のページに用意されていました。参考までに。

今回はちょっとしたインデックスをつくって検索する部分を紹介してみようかと思います (Cognitiveなところは機会があればまた)。

普通の使い方については、Azureのドキュメントなどを読んで頂く形にします。ポータルと呼ばれるブラウザ上でAzureのサービスを触ることができる画面が用意されています。ここで、簡単な操作(インデックス作成、フィールドの追加)

APIを使ってインデックス(特にAnalyzer)の設定をしたり、データをいれて、クエリしてみるというところをサクッと紹介しようと思います。

インデックスの作り方

インデックス作成に関するドキュメントも用意されています。最初はポータル(GUI)でインデックスを作成する方法が紹介されています。ですが、今回はn-gram(n=2)のAnalyzerを利用したかったので、GUIではなくAPIでインデックスを作成しました。カスタムアナライザーを利用する場合、REST APIを利用しなければ行けないということになっています。 n-gramのAnalyzerを含むインデックス生成のREST APIは以下のとおりです。こちらを実行することで、インデックスが作成されます(JSONの記述ミスなどがある場合はエラーが返ってきます)。

@host = <サーチのサービス名>.search.windows.net
@api-key = <APIキー>

###

POST https://{{host}}/indexes/?api-version=2019-05-06
Content-Type: application/json
api-key: {{api-key}}

{
    "name":"ngram-test",
    "fields":[
       {
          "name":"id",
          "type":"Edm.String",
          "key":true,
          "searchable":false
       },
       {
          "name":"ngram",
          "type":"Edm.String",
          "searchable":true,
          "analyzer":"bi_gram_analyzer"
       }
    ],
    "analyzers":[
      {
         "name":"bi_gram_analyzer",
         "@odata.type":"#Microsoft.Azure.Search.CustomAnalyzer",
         "tokenizer":"bi_gram_tokenizer",
         "tokenFilters":[
            "lowercase"
         ]
      }
    ],
    "tokenizers":[
       {
          "name":"bi_gram_tokenizer",
          "@odata.type":"#Microsoft.Azure.Search.NGramTokenizer",
          "minGram":2,
          "maxGram":2
       }
    ]
 }

なんだかどこかで見たことのある記述のようなそうでないような。。。 Analyzerは、charFilters(0以上複数可)、tokenizer(1つ必須)、tokenFilters(0以上複数可)から構成されます。フィールドで指定するのはAnalyzerなので、まずanalyzersにCustomAnalyzerの設定を行います。名前はbi_gram_analyzerにしました(好きに付けてください)。 tokenizerにはこのあと設定するtokenizerの名前を設定します。ここでは、bi_gram_tokenizerという名前にしています。また、大文字小文字を気にせずに検索したいため、tokenFiltersにlowercaseを指定しています。こちらはすでに定義済みのため、定義済みの名前で呼び出すだけで使用できます。

次が、bi_gram_tokenizerの設定です。 n=2としたいので、tokenizers配下にTokenizerの設定をします。 @odata.type":"#Microsoft.Azure.Search.NGramTokenizerがTokenizerの名前です(ちょっと独特な名前ですね)。 Tokenizerごとにオプションがあり、NGramTokenizerの場合は、minGram、maxGramがオプションに相当します。今回は2文字ごとにトークンを出力したいので、minとmaxをそれぞれ2としています。

これで、あとは、フィールドでanalyzerという設定にbi_gram_analyzerを指定すればそのフィールドはbi_gram_analyzerを使用してアナライズされるようになります(このへんはElasticsearchといっしょですね)。フィールドは文字列を扱うので、Edm.Stringというタイプにしてあります。データ型については、フィールドコレクションとフィールド属性というドキュメントを参考に設定しましょう。

閑話休題 - REST Client Exstension for Visual Studio Code

なお、今回のサンプルはREST Clinet Extention for Visual Studio Codeを利用する想定の記述になっています。

Visual Studio Codeで.restもしくは.httpというファイルに以下のAPIを記述すると、Send RequestというリンクがURLの上部に出てくるような拡張機能です。REST APIにリクエストするときに便利なツールになっています。変数も使えるので、APIのキーやURLの一部をこのように共通化して、他の環境でも使いやすくできるのは素晴らしいなと。

アナライザーの挙動の確認

設定したAnalyzerがきちんと機能しているかというのを確認する必要があります。入力した文字列がきちんと想定している単語として切り出されて、転置インデックスの見出し語に使われるかというのが重要になるからです。

Azure Cognitive Searchでもアナライザーのテスト用APIが用意されています。使い方はこちら。 APIの仕様のページもありました。「アナライザーの挙動はどんな感じ？」という文字列が、作成したインデックスの定義したアナライザーbi_gram_analyzerにより、どのように分割されるかを確認するAPIの呼び出しは以下のとおりです。

###
POST https://{{host}}/indexes/ngram-test/analyze?api-version=2019-05-06
Content-Type: application/json
api-key: {{api-key}}

{
   "analyzer":"bi_gram_analyzer",
   "text": "アナライザーの挙動はどんな感じ？"
}

レスポンスはこんな形です。ヘッダ部分は省略してあります。

{
  "@odata.context": "https://{{host}}.search.windows.net/$metadata#Microsoft.Azure.Search.V2019_05_06.AnalyzeResult",
  "tokens": [
    {
      "token": "アナ",
      "startOffset": 0,
      "endOffset": 2,
      "position": 0
    },
    {
      "token": "ナラ",
      "startOffset": 1,
      "endOffset": 3,
      "position": 1
    },
    {
      "token": "ライ",
      "startOffset": 2,
      "endOffset": 4,
      "position": 2
    },
    {
      "token": "イザ",
      "startOffset": 3,
      "endOffset": 5,
      "position": 3
    },
    {
      "token": "ザー",
      "startOffset": 4,
      "endOffset": 6,
      "position": 4
    },
    {
      "token": "ーの",
      "startOffset": 5,
      "endOffset": 7,
      "position": 5
    },
    {
      "token": "の挙",
      "startOffset": 6,
      "endOffset": 8,
      "position": 6
    },
    {
      "token": "挙動",
      "startOffset": 7,
      "endOffset": 9,
      "position": 7
    },
    {
      "token": "動は",
      "startOffset": 8,
      "endOffset": 10,
      "position": 8
    },
    {
      "token": "はど",
      "startOffset": 9,
      "endOffset": 11,
      "position": 9
    },
    {
      "token": "どん",
      "startOffset": 10,
      "endOffset": 12,
      "position": 10
    },
    {
      "token": "んな",
      "startOffset": 11,
      "endOffset": 13,
      "position": 11
    },
    {
      "token": "な感",
      "startOffset": 12,
      "endOffset": 14,
      "position": 12
    },
    {
      "token": "感じ",
      "startOffset": 13,
      "endOffset": 15,
      "position": 13
    },
    {
      "token": "じ？",
      "startOffset": 14,
      "endOffset": 16,
      "position": 14
    }
  ]
}

このAzure SearchのAnalyze API、使用できるオプションはすくないですが、ElasticsearchのAnalyze APIと似ています。

データの登録の仕方

データ登録もAPIからできます(あたりまえですね)。 APIは1件ずつではなく、バルクで登録できる形で提供されています。

サンプルとしては、以下のような形です。 @search.actionの部分(searchがあるとわかりにくい気がするけど。。。)が、ドキュメントの登録、更新、削除の命令を書き込むところになります。今回は単純に登録するだけなので、uploadを指定しました。ほかにもいくつかアクションが用意されています。用途に合わせて指定する感じになります。 id、ngramはそれぞれフィールド名です。ドキュメントに登録したい値を記述します。


POST https://{{host}}/indexes/ngram-test/docs/index?api-version=2019-05-06
Content-Type: application/json
api-key: {{api-key}}

{
  "value": [
    {          
      "@search.action": "upload",  
      "id": "1",
      "ngram": "新しいAzure Searchの使い方"
    },
    {          
      "@search.action": "upload",  
      "id": "2",
      "ngram": "Elasticsearchの紹介"
    }
  ]
}

検索クエリ

最後は検索クエリです。検索クエリはいくつかのオプションがあります。ざっくりだと、queryTypeがsimpleとfullという2種類が用意されており、ちょっとした検索を作る場合はsimpleで事足りそうという感じです。入力された単語(スペース区切りで複数扱い)をフィールド(複数可)に対していずれかの単語を含むもしくは、すべての単語を含むという検索に行くというパターンですね。このときの、「いずれか」か「すべて」の設定がsearchModeというパラメータになります。 anyの場合、Googleの検索と同様に、どれかの単語が入っているドキュメントが対象に、allの場合すべての単語が含まれるドキュメントだけがたいしょうになるといった形です。

queryType=fullの場合はLuceneの構文でクエリがかけます。ElasticsearchのQuery String Queryみたいな形です。

簡単なサンプルは次のような感じです。このサンプル


POST https://{{host}}/indexes/multi-field-test/docs/search?api-version=2019-05-06
Content-Type: application/json
api-key: {{api-key}}

{
   "search": 'ngram:"使い方" ngram:"紹介"',
   "queryType": "full",
   "searchMode": "any"
}

すこしだけクエリの補足を。 searchに入力された単語をダブルクォートで囲んでいます。これは、「使い方」という文字がbi_gram_analyzerにより「使い」「い方」に分割されるのですが、必ずこの順序で出現したものだけを検索対象にしたい(フレーズ検索)という意味になります(*bi_*gramなので、「紹介」に関してはダブルクォートは厳密には必要ないです)。

あと、レスポンスは今回記載していませんが、@search.scoreという項目で、スコアが返ってきます。デフォルトのスコア計算には何を使ってるんだろう?ドキュメントにはTF-IDFとの記述があるのですが。。。カスタマイズもできそうです。

少しオモシロイと思ったのは、スキーマ(インデックスの設定)に定義されているが、ドキュメントとしては登録していない項目についても、 Azure Cognitive Searchはドキュメントのフィールドがnullという形で返ってくるようでした。そもそもフィールドが存在しないドキュメントとフィールドの値がnullのものの違いは無いようです。

簡単ですが、インデックスの設定、ドキュメントの登録、検索の方法の紹介でした。

ちょっと触った感想

一番売りである、Cognitiveの部分はまだ触っていないです、すみません(こっちが売りな気もするんですが)。検索エンジンの部分としては、Elasticsearchを知っていると、「あー、そんな感じね」という気持ちになれるサービスです。個々のAPIやデータの形式は異なるので、きちんとAPIのリファレンスなどを確認しつつという形になりますが、なんとなくこういうAPIなどがありそうだな?と予測しつつ使えるかなと。内部的にはElasticsearchだと思いますが、独自のAPIでラップされているおかげで、バージョンの違いなどを意識せずに使えるのではないかと思います。

また、今回は紹介していませんが、マイクロソフト独自の各言語のアナライザー(日本語も含む)があります。 Luceneのアナライザーとマイクロソフトのアナライザーのどちらも利用できますので、ここの違いを見てみるのも面白そうだなと思いました。緯度経度を利用した検索、フィルター検索(スコア計算対象にならない)、ファセット、スコア調整の機能なども備えているようです。

なんにせよ、利用する場合やドキュメントを読む場合に、全文検索の仕組みをなんとなく知っておいたほうが読みやすいんじゃないかなというのが感想です。

ここ数年はElasticsearchがメインでほかはほぼ触っていない状況だったので新しい製品に触れるのは面白いですね。時間があったら、アナライザーの違いなども調べてみたいなと思います。