Note
現在、この機能はパブリック プレビュー段階にあります。 このプレビュー版はサービス レベル アグリーメントなしで提供されています。運用環境のワークロードに使用することはお勧めできません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。 詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。
クエリの書き換えとは、ユーザーのクエリをより効果的なクエリに変換し、追加の用語を加えて検索結果を絞り込むプロセスです。 Search Service は、検索クエリ (またはそのバリエーション) を、代替クエリを生成する生成モデルに送信します。
クエリの書き換えにより、ユーザー クエリの入力ミスやスペル ミスを修正し、類似語を使用してクエリを拡張することで、セマンティック ランク付けの結果を改善します。
クエリの書き換えを使う検索は、次のように機能します。
- ユーザー クエリは、要求の
searchプロパティを使って送信されます。 - Search Service は、検索クエリ (またはそのバリエーション) を、代替クエリを生成する生成モデルに送信します。
- Search Service は、元のクエリと書き換えられたクエリを使って検索結果を取得します。
クエリの書き換えはオプション機能です。 クエリの書き換えを使わないと、Search Service は元のクエリだけを使って検索結果を取得します。
Note
書き換えられたクエリには、元のクエリの正確な用語がすべて含まれていない場合があります。 これは、クエリが非常に具体的で、一意識別子または製品コードに完全に一致する必要がある場合に、検索結果に影響を与える可能性があります。
前提条件
北ヨーロッパまたは東南アジアの検索サービス (Basic レベル以上)。
セマンティック ランカーを有効にする必要があります。 新しい検索サービスでは、既定で有効になっています。 機能の概要情報が必要な場合は、セマンティック ランク付けを確認してください。
セマンティック構成 とリッチ テキスト コンテンツを使用する既存の検索インデックス。 このガイドの例では、hotels-sample-index サンプル データを使って、クエリの書き換えを見ていきます。 独自のデータとインデックスを使って、クエリの書き換えをテストできます。
この記事の手順に従うには、REST API 要求をサポートする Web クライアントが必要です。 このガイドの例は、Visual Studio Code と REST Client 拡張機能を使ってテストされました。
ヒント
セマンティック ランク付けには、説明または定義を含むコンテンツが最も適しています。
クエリの書き換えを使用して検索要求を行う
この REST API の例では、 ドキュメントの検索 (プレビュー) を使用して要求を作成します。
次の要求をテンプレートとして Web クライアントに貼り付けます。
POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2025-03-01-preview { "search": "newer hotel near the water with a great restaurant", "semanticConfiguration":"en-semantic-config", "queryType":"semantic", "queryRewrites":"generative|count-5", "queryLanguage":"en-US", "debug":"queryRewrites", "top": 1 }search-service-nameを検索サービス名に置き換えます。hotels-sample-indexを、異なる場合はインデックス名に置き換えてください。"search" をフルテキスト検索クエリに設定します。 ベクトル クエリを指定するのでない限り、クエリの書き換えには検索プロパティが必要です。 ベクトル クエリを指定する場合は、"search" のテキストは
"text"オブジェクトの"vectorQueries"プロパティと一致する必要があります。 検索文字列は、simple 構文または完全な Lucene 構文をサポートできます。"semanticConfiguration" を、インデックスに埋め込まれた 定義済みのセマンティック構成 に設定します。
"queryType" を "semantic" に設定します。 "queryType" を "semantic" に設定するか、要求に空でない "semanticQuery" プロパティを含める必要があります。 クエリの書き換えにはセマンティック ランク付けが必要です。
最大 5 つのクエリ書き換えを取得するには、"queryRewrites" を "generative|count-5" に設定します。 カウントは、1 から 10 の任意の値に設定できます。
"queryRewrites" プロパティを設定してクエリの書き換えを要求したので、"queryLanguage" を検索テキスト言語に設定する必要があります。 検索サービスは、クエリの書き換えに同じ言語を使用します。 この例では、"en-US" を使用します。 次のロケールがサポートされています:
en-AU、en-CA、en-GB、en-IN、en-US、ar-EG、ar-JO、ar-KW、ar-MA、ar-SA、bg-BG、bn-IN、ca-ES、cs-CZ、da-DK、de-DE、el-GR、es-ES、es-MX、et-EE、eu-ES、fa-AE、fi-FI、fr-CA、fr-FR、ga-IE、gl-ES、gu-IN、he-IL、hi-IN、hr-BA、hr-HR、hu-HU、hy-AM、id-ID、is-IS、it-IT、ja-JP、kn-IN、ko-KR、lt-LT、lv-LV、ml-IN、mr-IN、ms-BN、ms-MY、nb-NO、nl-BE、nl-NL、no-NO、pa-IN、pl-PL、pt-BR、pt-PT、ro-RO、ru-RU、sk-SK、sl-SL、sr-BA、sr-ME、sr-RS、sv-SE、ta-IN、te-IN、th-TH、tr-TR、uk-UA、ur-PK、vi-VN、zh-CN、zh-TW。応答でクエリの書き換えを取得するには、"debug" を "queryRewrites" に設定します。
ヒント
テスト目的でのみ
"debug": "queryRewrites"を設定します。 パフォーマンスを向上させるため、運用環境ではデバッグを使わないでください。上位の検索結果のみを返すには、"top" を 1 に設定します。
クエリを実行して結果を返す要求を送信します。
次に、クエリの書き換えを使用して検索結果を評価します。
応答を評価する
クエリの書き換えを含む応答の例を次に示します。
"@search.debug": {
"semantic": null,
"queryRewrites": {
"text": {
"inputQuery": "newer hotel near the water with a great restaurant",
"rewrites": [
"new waterfront hotels with top-rated eateries",
"new waterfront hotels with top-rated restaurants",
"new waterfront hotels with excellent dining",
"new waterfront hotels with top-rated dining",
"new water-side hotels with top-rated restaurants"
]
},
"vectors": []
}
},
"value": [
{
"@search.score": 58.992092,
"@search.rerankerScore": 2.815633535385132,
"HotelId": "18",
"HotelName": "Ocean Water Resort & Spa",
"Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, ___location near the pier, rooftop pool, waterfront dining & more.",
"Description_fr": "Nouvel h\u00f4tel de luxe pour des vacances inoubliables. Vue sur la baie depuis chaque chambre, emplacement pr\u00e8s de la jet\u00e9e, piscine sur le toit, restaurant au bord de l'eau et plus encore.",
"Category": "Luxury",
"Tags": [
"view",
"pool",
"restaurant"
],
"ParkingIncluded": true,
"LastRenovationDate": "2020-11-14T00:00:00Z",
"Rating": 4.2,
"Location": {
"type": "Point",
"coordinates": [
-82.537735,
27.943701
],
"crs": {
"type": "name",
"properties": {
"name": "EPSG:4326"
}
}
},
//... more properties redacted for brevity
}
]
注意すべき重要なポイントがいくつかあります。
- テスト用に "debug" プロパティを "queryRewrites" に設定しているため、応答にはテキスト入力クエリとクエリ書き換えを含む
@search.debugオブジェクトが含まれます。 - "queryRewrites" プロパティを "generative|count-5" に設定しているため、応答には最大 5 つのクエリ書き換えが含まれます。
-
"inputQuery"の値は、クエリの書き換えのために生成モデルに送られたクエリです。 入力クエリは、ユーザーの"search"クエリと常に同じとは限りません。
クエリの書き換えを行わない応答の例を次に示します。
"@search.debug": {
"semantic": null,
"queryRewrites": {
"text": {
"inputQuery": "",
"rewrites": []
},
"vectors": []
}
},
"value": [
{
"@search.score": 7.774868,
"@search.rerankerScore": 2.815633535385132,
"HotelId": "18",
"HotelName": "Ocean Water Resort & Spa",
"Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, ___location near the pier, rooftop pool, waterfront dining & more.",
"Description_fr": "Nouvel h\u00f4tel de luxe pour des vacances inoubliables. Vue sur la baie depuis chaque chambre, emplacement pr\u00e8s de la jet\u00e9e, piscine sur le toit, restaurant au bord de l'eau et plus encore.",
"Category": "Luxury",
"Tags": [
"view",
"pool",
"restaurant"
],
"ParkingIncluded": true,
"LastRenovationDate": "2020-11-14T00:00:00Z",
"Rating": 4.2,
"Location": {
"type": "Point",
"coordinates": [
-82.537735,
27.943701
],
"crs": {
"type": "name",
"properties": {
"name": "EPSG:4326"
}
}
},
//... more properties redacted for brevity
}
]
クエリの書き換えを行うベクトル クエリ
検索要求にベクトル クエリを含めて、キーワード検索とベクトル検索を 1 つの要求と統合された応答に組み合わせることができます。
クエリの書き換えを行うベクトル クエリを含むクエリの例を次に示します。 ベクター クエリを含むように 前の例 を変更します。
- "vectorQueries" オブジェクトを要求に追加します。 このオブジェクトには、"kind" が "text" に設定されたベクトル クエリが含まれます。
- "text" の値は "search" の値と同じです。 クエリの書き換えが機能するためには、これらの値を同じにする必要があります。
POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2025-03-01-preview
{
"search": "newer hotel near the water with a great restaurant",
"vectorQueries": [
{
"kind": "text",
"text": "newer hotel near the water with a great restaurant",
"k": 50,
"fields": "Description",
"queryRewrites": "generative|count-3"
}
],
"semanticConfiguration":"en-semantic-config",
"queryType":"semantic",
"queryRewrites":"generative|count-5",
"queryLanguage":"en-US",
"top": 1
}
応答には、テキスト クエリとベクトル クエリの両方に対するクエリの書き換えが含まれます。
デバッグを使用してクエリの書き換えをテストする
クエリの書き換えをテストして、意図したとおりに動作することを確認する必要があります。 応答でクエリの書き換えを取得するには、クエリ要求で "debug": "queryRewrites" プロパティを設定します。
"debug" の設定は、テスト目的では省略可能です。 パフォーマンスを向上させるため、運用環境ではこのプロパティを設定しないでください。
部分的な応答の理由
デバッグ (テスト) 応答には、text.rewrites と vectors プロパティに空の配列が含まれる場合があります。
{
"@odata.context": "https://demo-search-svc.search.windows.net/indexes('hotels-sample-index')/$metadata#docs(*)",
"@search.debug": {
"semantic": null,
"queryRewrites": {
"text": {
"rewrites": []
},
"vectors": []
}
},
"@search.semanticPartialResponseReason": "Transient",
"@search.semanticQueryRewriteResultType": "OriginalQueryOnly",
//... more properties redacted for brevity
}
前の例の場合:
- 応答には、"Transient" という値の
@search.semanticPartialResponseReasonプロパティが含まれます。 このメッセージは、少なくとも 1 つのクエリが完了しなかったことを意味します。 - 応答には、値が "OriginalQueryOnly" の
@search.semanticQueryRewriteResultTypeプロパティも含まれます。 このメッセージは、クエリの書き換えを使用できないことを意味します。 検索結果の取得には、元のクエリのみが使われます。
次のステップ
セマンティックの順位付けは、キーワード検索とベクトル検索を 1 つの要求と統合された応答に結合するハイブリッド クエリで使用できます。