Azure AI 検索でセマンティック ランカーを使用してクエリを書き換える (プレビュー)

メモ

Azure AI 検索は、Azure ポータル、REST API、およびAzure SDKから使用できます。 また、Foundry IQ は、エンタープライズ コンテンツを、Microsoft Foundry ポータルのエージェントの再利用可能なアクセス許可に対応したナレッジ ベースに変換するマネージド ナレッジ レイヤーです。

Important

機能、またはマークされたプロパティ (プレビュー) は、サービス レベル アグリーメントの対象ではなく、運用環境のワークロードには推奨されず、一般公開される前に変更または制約される可能性があります。 Azure AI 検索 プレビューの用語は、スタンドアロンでも一般公開されている機能の一部でも、すべてのプレビュー機能に適用されます。

クエリの書き換え (プレビュー) は、ユーザーのクエリをより効果的なクエリに変換し、用語を追加して検索結果を絞り込むプロセスです。 検索サービスは、検索クエリ (またはそのバリエーション) を、代替クエリを生成する生成モデルに送信します。

クエリの書き換えでは、ユーザー クエリの入力ミスやスペル ミスを修正し、シノニムを使用してクエリを拡張することで、 セマンティックランク付 けの結果が向上します。

クエリの書き換えによる検索は、次のように機能します。

  • ユーザー クエリは、要求の search プロパティを介して送信されます。
  • 検索サービスは、検索クエリ (またはそのバリエーション) を、代替クエリを生成する生成モデルに送信します。
  • 検索サービスは、元のクエリと書き換えられたクエリを使用して検索結果を取得します。

クエリの書き換えは省略可能な機能です。 クエリの書き換えなしで、検索サービスは元のクエリを使用して検索結果を取得するだけです。

メモ

書き換えられたクエリには、元のクエリの正確な用語がすべて含まれていない場合があります。 これは、クエリが非常に具体的で、一意の識別子または製品コードに完全に一致する必要がある場合に、検索結果に影響を与える可能性があります。

前提 条件

ヒント

説明または定義を含むコンテンツは、セマンティックランク付けに最適です。

クエリの書き換えを使用して検索要求を行う

この REST API の例では、 ドキュメントの検索 (プレビュー) を使用して要求を作成します。

  1. 次の要求をテンプレートとして Web クライアントに貼り付けます。

    POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-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 を異なる場合は、独自のインデックス名に置き換えてください。

    • "search" をフルテキスト検索クエリに設定します。 ベクター クエリを指定しない限り、クエリの書き換えには検索プロパティが必要です。 ベクター クエリを指定する場合、"検索" テキストは、"text" オブジェクトの"vectorQueries"プロパティと一致する必要があります。 検索文字列は、 単純な構文 または 完全な 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 に設定します。

  2. クエリを実行して結果を返す要求を送信します。

次に、クエリの書き換えを使用して検索結果を評価します。

応答を評価する

クエリの書き換えを含む応答の例を次に示します。

"@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/docs/search?api-version=2026-08-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')/$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 つの要求と統合された応答に結合するハイブリッド クエリで使用できます。

セマンティック ランカーを使用したハイブリッド クエリ

  • Last updated on