Перезапись запросов с помощью семантического рангера в службе "Поиск ИИ Azure" (предварительная версия)

Перезапись запросов — это процесс преобразования запроса пользователя в более эффективный, добавление дополнительных терминов и уточнение результатов поиска. Служба поиска отправляет поисковый запрос (или вариант) в созданную модель, которая создает альтернативные запросы.

Перезапись запросов улучшает результаты семантического ранжирования , исправляя опечатки или ошибки орфографии в запросах пользователей и расширяя запросы синонимами.

Поиск с переписыванием запросов функционирует следующим образом:

• Запрос пользователя отправляется через свойство search в запросе.
• Служба поиска отправляет поисковый запрос (или вариант) в созданную модель, которая создает альтернативные запросы.
• Служба поиска использует исходный запрос и перезаписанные запросы для получения результатов поиска.

Перезапись запросов является необязательной функцией. Без перезаписи запросов служба поиска просто использует исходный запрос для получения результатов поиска.

Prerequisites

• Поиск ИИ Azure в любом регионе, который предоставляет переформулировку запросов, с включенным семантическим ранжировщиком.

• Существующий индекс поиска с семантической конфигурацией и содержимым форматированного текста. Примеры в этом руководстве используют образец данных hotels-sample-index для демонстрации перезаписи запросов.

• Чтобы следовать инструкциям в этой статье, вам потребуется веб-клиент, поддерживающий запросы REST API. Примеры, приведенные в этой статье, были протестированы с помощью Visual Studio Code и расширения КЛИЕНТА REST .

Создание поискового запроса с перезаписями запросов

В этом примере REST API используйте документы поиска (предварительная версия) для формирования запроса.

1. Вставьте следующий запрос в веб-клиент в качестве шаблона.

   POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2025-11-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" должен соответствовать "text" свойству "vectorQueries" объекта. Строка поиска может поддерживать простой синтаксис или полный синтаксис Lucene.

   • Задайте для параметра "semanticConfiguration" предопределённую семантическую конфигурацию, внедрённую в индекс.

   • Задайте для "queryType" значение "семантика". Необходимо задать для queryType значение "семантика" или включить свойство nonempty "semanticQuery" в запрос. Для перезаписи запросов требуется семантическое ранжирование.

   • Задайте для параметра 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, чтобы в ответе получить перезаписи запроса.

     Tip

     Задано "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", ответ включает до пяти перезаписей запросов.
• Значением "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
  }
]

Векторные запросы с переопределением запросов

В запросе поиска можно включить векторные запросы для объединения поиска ключевых слов и векторного поиска в один запрос и унифицированный ответ.

Ниже приведен пример запроса, который включает векторный запрос с перезаписями запросов. Измените предыдущий пример , чтобы включить векторный запрос.

• Добавьте объект vectorQueries в запрос. Этот объект содержит векторный запрос с типом, равным "text".
• Значение "text" совпадает со значением "search". Для работы перезаписи запросов эти значения должны быть идентичными.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2025-11-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
}

В предыдущем примере:

• Ответ содержит @search.semanticPartialResponseReason свойство со значением "Временный". Это сообщение означает, что не удалось завершить хотя бы один из запросов.
• Ответ также содержит @search.semanticQueryRewriteResultType свойство со значением OriginalQueryOnly. Это сообщение означает, что перезаписи запросов недоступны. Для получения результатов поиска используется только исходный запрос.

Дальнейшие шаги

Семантический ранжирование можно использовать в гибридных запросах, которые объединяют поиск по ключевым словам и векторный поиск в одном запросе и унифицированном ответе.