Добавление семантического ранжирования в запросы в Поиск с использованием ИИ Azure

Примечание

Поиск с использованием ИИ Azure доступна через портал Azure, REST API и Azure SDKs. Он также лежит в основе Foundry IQ — управляемого слоя знаний, который преобразует корпоративный контент в многократно используемые базы знаний с учетом разрешений доступа для агентов на портале Microsoft Foundry.

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

В этой статье объясняется, как вызвать семантический рангер для запросов. Предполагается, что вы используете самые последние стабильные или предварительные версии API. Дополнительные сведения о более ранних версиях см. в статье "Миграция семантического ранжирования кода".

Необходимые условия

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

Примечание

Заголовки и ответы извлекаются из текста в документе поиска. Семантическая подсистема использует понимание машинного чтения для распознавания содержимого с характеристиками заголовка или ответа, но не создает новые предложения или фразы, за исключением случаев перезаписи запроса (предварительная версия). По этой причине содержимое, включающее объяснения или определения, лучше всего подходит для семантического ранжирования. Если вы хотите взаимодействие в чате с генерированными ответами, см. статью "Агентическое извлечение" или "Извлечение дополненного поколения (RAG)".

Выбор клиента

Для создания запроса, использующего семантический ранжирование, можно использовать любой из следующих средств и пакетов SDK:

В портале Azure используйте конструктор индексов для добавления семантической конфигурации.
Visual Studio Code с клиентом REST
Azure SDK для .NET
Azure SDK для Python
Azure SDK для Java
Azure SDK для JavaScript

Избегайте функций, которые обходят оценку релевантности

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

Запрос с search=* или пустой строкой поиска, например, чистый запрос только для фильтра, не будет работать, так как нет ничего, чтобы измерять семантическую релевантность, и поэтому оценки поиска будут равны нулю. Запрос должен предоставлять термины или фразы, которые можно оценить во время обработки, и создает документы поиска, которые оцениваются по релевантности. Оценка результатов — это входные данные для семантического ранджера.
Сортировка (операторы orderBy) по конкретным полям переопределяет результаты поиска и семантические оценки. Учитывая, что семантическая оценка должна предоставлять рейтинг, добавление класса orderby приводит к ошибке HTTP 400 при применении семантического ранжирования по упорядоченным результатам.

Настройка запроса

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

Все семантические запросы, указанные через search плюс queryTypeили через semanticQuery, должны быть обычным текстом, и они не могут быть пустыми. Как видно из приведенной ниже таблицы, queryType-semantic параметр поддерживает подмножество форматов запросов.

Параметр	Поиск обычного текста	Простой синтаксис поиска текста	Синтаксис полнотекстового поиска	Векторный поиск	Гибридный поиск	Семантические ответы и субтитры
`queryType-semantic` ¹	✅	❌	❌	❌	✅	✅
`semanticQuery="<your plain text query>"` ²	✅	✅	✅	✅	✅	✅

¹queryType=semantic не поддерживает явные simple или full значения, так как queryType параметр используется для semantic. Эффективные настройки запросов — это значения по умолчанию простого парсера.

² Параметр semanticQuery можно использовать для всех типов запросов. Однако он не поддерживается в портале Azure Search Explorer.

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

Обозреватель поиска включает параметры семантического ранжирования. Помните, что нельзя задать параметр semanticQuery на портале Azure.

Перейдите в службу поиска на портале Azure.
Откройте индекс поиска и выберите обозреватель поиска.
Выберите параметры запроса. Если вы уже определили семантику конфигурации, она выбрана по умолчанию. Если у вас нет семантической конфигурации, создайте её для индекса.
Введите запрос, например "исторический отель с хорошей едой", и выберите "Поиск".
Кроме того, выберите представление JSON и вставьте определения в редактор запросов. Портал Azure не поддерживает использование semanticQuery, поэтому для параметра queryType значение "semantic" требуется:

Пример JSON для задания типа запроса семантикой, которую можно вставить в представление:
```
{
  "search": "funky or interesting hotel with good food on site",
  "count": true,
  "queryType": "semantic",
  "semanticConfiguration": "my-semantic-config",
  "captions": "extractive|highlight-true",
  "answers": "extractive|count-3",
  "highlightPreTag": "<strong>",
  "highlightPostTag": "</strong>",
  "select": "HotelId,HotelName,Description,Category"
}
```

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

Ответ автоматически включает @search.rerankerScore. Если вы хотите заголовок или ответы в ответе, включите семантический ранжирование, задав queryTypesemantic или установив semanticQuery и добавив подписи и ответы на запрос.

В следующих примерах в этом разделе используется индекс hotels-sample для демонстрации семантического ранжирования с семантическими ответами и подписями.

Используйте queryType=semantic

Если вы хотите задать значение queryTypesemantic, вставьте следующий запрос в веб-клиент в качестве шаблона. Замените search-service-name на имя вашей службы поиска, а hotels-sample замените, если у вас другое имя индекса.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
      "search": "interesting hotel with restaurant on site and cozy lobby or shared area",
      "count": true,
      "queryType": "semantic",
      "semanticConfiguration": "semantic-config",
      "captions": "extractive|highlight-true",
      "answers": "extractive|count-3",
      "highlightPreTag": "<strong>",
      "highlightPostTag": "</strong>",
      "select": "HotelId,HotelName,Description,Category"
}

Установите queryType на semantic. Это повышает точность результатов поиска, переранжируя первые 50 совпадений, используя модель ранжирования, обученную на корпусе Bing для запросов, выраженных на естественном языке, а не ключевых слов. Если вы установите тип запроса на семантический, вы также должны задать семантическуюКонфигурацию. При необходимости можно задать ответы, если вы хотите также вернуть первые 3 ответа, если входные данные запроса были разработаны на естественном языке ("что такое ...), и вы можете при необходимости задать заголовки для извлечения ключевых фрагментов из документов с наивысшим рейтингом.
Задайте search простой текстовый запрос.
Поскольку установлено значение , простой синтаксис или полный синтаксис Lucene не поддерживаются. Использование * или пустой строки не приводит к применению семантического ранжирования к запросу.
Задайте semanticConfiguration на предопределенную семантическую конфигурацию, внедренную в ваш индекс.
Установите answers для указания, включены ли в результат семантические ответы. Допустимые значения для этого параметра: extractive и none. Этот параметр действителен только в том случае, если тип запроса имеет значение "семантика". Если задано значение "extractive", запрос будет сформулирован и вернет ответы из ключевых частей в документах, которые занимают наивысшие позиции по семантической значимости. Значение по умолчанию — один ответ, но можно указать до 10, добавив число. Например, "answers": "extractive|count-3" возвращает три ответа. Чтобы ответ был возвращен, в целевом поле должно быть подробное содержимое, которое выглядит как ответ. Языковые модели, используемые для ответов, обучены распознавать ответы, а не создавать их. Кроме того, сам запрос должен выглядеть как вопрос.
Задайте значение captions , чтобы указать, включены ли семантические заголовки в результат. Допустимые значения: "none" и "extractive". Значение по умолчанию — «нет». Этот параметр действителен только в том случае, если тип запроса имеет значение "семантика". Если задано значение "extractive", запрос возвращает аннотации, извлеченные из ключевых отрывков в документах с наивысшим рейтингом.

Если для надписей задано значение "extractive", выделение включено по умолчанию и может быть настроено путем добавления символа '|' за которым следует параметр highlight-<true/false>, например extractive|highlight-true. В этом примере возвращаются заголовки без выделения: extractive|highlight-false

Подписи и ответы основываются на полях, указанных в "semanticConfiguration". Эти поля подчинены объединенному ограничению в пределах 2000 маркеров или около 20 000 символов. Если ожидается, что количество маркеров превышает это ограничение, рассмотрите шаг фрагментирования данных с помощью навыка разделения текста. Этот подход представляет зависимость от конвейера обогащения ИИ и индексаторов.
Задайте highlightPreTag и highlightPostTag если вы хотите переопределить форматирование выделения по умолчанию, которое применяется к подписям.

Заголовки применяют подсветку ключевых фрагментов в документе, который суммирует ответ. Значение по умолчанию — <em>. Если вы хотите указать тип форматирования (например, желтый фон), можно задать highlightPreTag и highlightPostTag.
Установите select для указания, какие поля возвращаются в ответе, и используйте "count", чтобы вернуть количество совпадений в индексе. Эти параметры повышают качество запроса и удобочитаемости ответа.
Отправьте запрос для выполнения запроса и возврата результатов.

Использование semanticQuery

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

Измените запрос в следующий формат JSON, чтобы использовать semanticQuery.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
    "search": "Description:breakfast",
    "semanticQuery": "interesting hotel with restaurant on site and cozy lobby or shared area",
    "count": true,
    "queryType": "full",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true",
    "answers": "extractive|count-3",
    "highlightPreTag": "<strong>",
    "highlightPostTag": "</strong>",
    "select": "HotelId,HotelName,Description,Category"
}

Задайте queryType синтаксис поиска, который вы используете, либо простой , либо полный.
Задайте semanticQuery для простого текстового запроса, который вы хотите использовать для семантического ранжирования. Пустые запросы не поддерживаются. Избегайте операторов или любого синтаксиса запроса внутри самой строки.

Используйте QueryType или SemanticQuery для вызова семантического ранджера в семантическом запросе. Пример следующий от команды Azure SDK.

SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
    "interesting hotel with restaurant on site and cozy lobby or shared area",
    new SearchOptions
    {
        SemanticSearch = new()
        {
            SemanticConfigurationName = "my-semantic-config",
            QueryCaption = new(QueryCaptionType.Extractive),
            QueryAnswer = new(QueryAnswerType.Extractive)
        },
        QueryType = SearchQueryType.Semantic
    });

int count = 0;
Console.WriteLine($"Semantic Search Results:");

Console.WriteLine($"\nQuery Answer:");
foreach (QueryAnswerResult result in response.SemanticSearch.Answers)
{
    Console.WriteLine($"Answer Highlights: {result.Highlights}");
    Console.WriteLine($"Answer Text: {result.Text}");
}

await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
{
    count++;
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.HotelId}: {doc.HotelName}");

    if (result.SemanticSearch.Captions != null)
    {
        var caption = result.SemanticSearch.Captions.FirstOrDefault();
        if (caption.Highlights != null && caption.Highlights != "")
        {
            Console.WriteLine($"Caption Highlights: {caption.Highlights}");
        }
        else
        {
            Console.WriteLine($"Caption Text: {caption.Text}");
        }
    }
}
Console.WriteLine($"Total number of search results:{count}");

Чтобы использовать semanticQuery вместо параметра queryTypesemantic, фрагмент кода поиска можно заменить следующим фрагментом кода:

SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
    "Luxury hotel",
    new SearchOptions
    {
        SemanticSearch = new()
        {
            SemanticConfigurationName = "my-semantic-config",
            QueryCaption = new(QueryCaptionType.Extractive),
            QueryAnswer = new(QueryAnswerType.Extractive),
            SemanticQuery = "Is there any hotel located on the main commercial artery of the city in the heart of New York?"
        }
    });

Оценка ответа

Только первые 50 совпадений из начальных результатов могут быть семантически ранжированы. Как и во всех запросах, ответ состоит из всех полей, помеченных как извлекаемые, или только эти поля, перечисленные в параметре select . Ответ включает исходную оценку релевантности, а также может включать количество или пакетные результаты в зависимости от того, как вы сформулировали запрос.

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

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

Ответ на приведенный выше пример запроса ("интересный отель с рестораном на сайте и уютный лобби или общий район") возвращает три ответа ("answers": "extractive|count-e"). Заголовки возвращаются, так как свойство "субтитры" задано с обычным текстом и выделенными версиями. Если не удается определить ответ, он опущен из ответа. Для краткости в этом примере показаны только три ответа и три самых высоких результата оценки из запроса.

{
  "@odata.count": 29,
  "@search.answers": [
    {
      "key": "24",
      "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "highlights": "Chic hotel near the city. <strong>High-rise hotel in downtown, </strong>within<strong> walking distance to </strong>theaters, art<strong> galleries, restaurants and shops.</strong> Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "score": 0.9340000152587891
    },
    {
      "key": "40",
      "text": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport.",
      "highlights": "Only 8 miles from Downtown. <strong>On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, </strong>All non-smoking<strong> hotel.</strong> Only 15 miles from airport.",
      "score": 0.9210000038146973
    },
    {
      "key": "38",
      "text": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our<strong> shared living space </strong>to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "score": 0.9200000166893005
    }
  ],
  "value": [
    {
      "@search.score": 3.2328331,
      "@search.rerankerScore": 2.575303316116333,
      "@search.captions": [
        {
          "text": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
          "highlights": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our<strong> penthouse </strong>suites offer views for miles and the rooftop<strong> plaza </strong>is open to all guests from sunset to 10 p.m. Enjoy a<strong> complimentary continental breakfast in the lobby, </strong>and free Wi-Fi<strong> throughout </strong>the hotel."
        }
      ],
      "HotelId": "50",
      "HotelName": "Head Wind Resort",
      "Description": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
      "Category": "Suite"
    },
    {
      "@search.score": 0.632956,
      "@search.rerankerScore": 2.5425150394439697,
      "@search.captions": [
        {
          "text": "Every stay starts with a warm cookie. Amenities like the Counting Sheep sleep experience, our Wake-up glorious breakfast buffet and spacious workout facilities await.",
          "highlights": "Every stay starts with a warm cookie. Amenities like the<strong> Counting Sheep sleep experience, </strong>our<strong> Wake-up glorious breakfast buffet and spacious workout facilities </strong>await."
        }
      ],
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Description": "Every stay starts with a warm cookie. Amenities like the Counting Sheep sleep experience, our Wake-up glorious breakfast buffet and spacious workout facilities await.",
      "Category": "Budget"
    },
    {
      "@search.score": 3.7076726,
      "@search.rerankerScore": 2.4554927349090576,
      "@search.captions": [
        {
          "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
          "highlights": "Chic hotel near the city. <strong>High-rise hotel in downtown, </strong>within<strong> walking distance to </strong>theaters, art<strong> galleries, restaurants and shops.</strong> Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "Category": "Suite"
    },
   . . .
  ]
}

Ожидаемые рабочие нагрузки

Для семантического ранжирования следует ожидать, что служба поиска поддерживает до 10 одновременных запросов на реплику.

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

Error in search query: Operation returned an invalid status 'Partial Content'`
@search.semanticPartialResponseReason`
CapacityOverloaded

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

Дальнейшие действия

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

Гибридный запрос с семантическим рангером

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-04-24