Быстрый старт: Семантическое ранжирование

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

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

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно.

• Служба Поиск с использованием ИИ Azure.

• Индекс с описательными текстовыми полями, обозначенными как searchable и retrievable. В этом кратком руководстве предполагается индекс примера отелей.

• .NET 9 или более поздней версии.

• Git для клонирования примера репозитория.

• Azure CLI для аутентификации без использования ключа с Microsoft Entra ID.

Настройка доступа

Перед началом работы убедитесь, что у вас есть разрешения на доступ к содержимому и операциям в Поиск с использованием ИИ Azure. В этом кратком руководстве используется Microsoft Entra ID для проверки подлинности и доступа на основе ролей для авторизации. Для назначения ролей необходимо быть владельцем или администратором доступа пользователей . Если роли не применимы, используйте проверку подлинности на основе ключей.

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

1. Включите доступ на основе ролей для службы поиска.

2. Назначьте следующие роли учетной записи пользователя.

   • Участник службы поиска

   • Средство чтения индексов поиска

Получение конечной точки

Каждая служба Поиск с использованием ИИ Azure имеет endpoint, который является уникальным URL-адресом, определяющим и предоставляющим сетевой доступ к службе. В следующем разделе описано, как указать эту конечную точку для программного подключения к службе поиска.

Чтобы получить конечную точку, выполните следующие действия.

1. Перейдите в службу поиска на портале Azure.

2. В левой области выберите "Обзор".

3. Запишите конечную точку, которая должна выглядеть следующим https://my-service.search.windows.netобразом.

Начните с индекса

Это краткое руководство изменяет существующий индекс для включения семантической конфигурации. Мы рекомендуем индекс хотелов-пример, который можно создать за считанные минуты, используя мастер портала Azure.

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

Чтобы просмотреть и запросить индекс примера отелей до семантического ранжирования:

1. Перейдите в службу поиска на портале Azure.

2. В левой панели выберите управление поиском>индексы.

3. Выберите hotels-sample.

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

   

5. Выберите обозреватель поиска, а затем выберите Вид>JSON-вид.

6. Вставьте следующий код JSON в редактор запросов.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Выберите "Поиск", чтобы запустить запрос.

   Ответ должен быть похож на следующий пример. Это полнотекстовый запрос, ранжированный по BM25, поэтому результаты соответствуют отдельным условиям запроса и лингвистическим вариантам, а не общему значению запроса. Например, walking совпадает с walk, а live и music сопоставляются независимо, а не как фраза.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "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."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Совет

   В этом запросе показано, как выглядит ответ перед применением семантического ранжирования. После настройки семантической конфигурации добавьте "queryType": "semantic" и "semanticConfiguration": "semantic-config", чтобы увидеть, как один и тот же запрос ранжируется по-разному семантическим ранжированием.

Настройка среды

1. Используйте Git для клонирования примера репозитория.

   git clone https://github.com/Azure-Samples/azure-search-dotnet-samples
   

2. Перейдите в папку быстрого запуска.

   cd azure-search-dotnet-samples/quickstart-semantic-ranking
   

3. В BuildIndex/Program.csэтом случае замените значение endpoint заполнителя url-адресом, полученным в конечной точке Get.

4. Повторите предыдущий шаг для QueryIndex/Program.cs.

5. Для проверки подлинности без ключа с помощью Microsoft Entra ID войдите в учетную запись Azure. Если у вас несколько подписок, выберите тот, который содержит службу Поиск с использованием ИИ Azure.

   az login
   

Запуск кода

1. Запустите первый проект, чтобы обновить индекс с семантической конфигурацией.

   dotnet run --project BuildIndex
   

2. Запустите второй проект, чтобы запросить индекс. Нажмите клавишу ВВОД между запросами, чтобы увидеть прогрессию от простого запроса к семантическому запросу с заголовками и ответами.

   dotnet run --project QueryIndex
   

Выход

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

Here's a list of all indexes on the search service. You should see hotels-sample:
hotels-sample

Added new semantic configuration 'semantic-config' to the index definition.
Index updated successfully.
Here is the revised index definition:
{
  "Name": "hotels-sample",
  ... // Trimmed for brevity
  "SemanticSearch": {
    "DefaultConfigurationName": "semantic-config",
    "Configurations": [
      {
        "Name": "hotels-sample-semantic-configuration",
        ... // Trimmed for brevity
      },
      {
        "Name": "semantic-config",
        "PrioritizedFields": {
          "TitleField": {
            "FieldName": "HotelName"
          },
          "ContentFields": [
            {
              "FieldName": "Description"
            }
          ],
          "KeywordsFields": [
            {
              "FieldName": "Tags"
            }
          ]
        },
        "RankingOrder": {}
      }
    ]
  }
}

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

Query 1: Simple query using the search string 'walking distance to live music'.
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
----------------------------------------
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.
@search.score: 4.555706
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 2: Semantic query (no captions, no answers) for 'walking distance to live music'.
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.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
@search.rerankerScore: 2.271434783935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 3: Semantic query with captions.
Caption: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>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.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.
Extractive Answers:
  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<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
----------------------------------------
... // Trimmed for brevity

Общие сведения о коде

Теперь, когда вы выполнили код, давайте разберем ключевые шаги:

1. Настройка и проверка подлинности
2. Обновление индекса с помощью семантической конфигурации
3. Запрос индекса

Настройка и проверка подлинности

Оба проекта используют один и тот же шаблон конфигурации. Файлы Program.cs определяют конечную точку поиска и используются DefaultAzureCredential для проверки подлинности без ключа.

var endpoint = new Uri("PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE");
var credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(endpoint, credential);

Ключевые выносы:

• DefaultAzureCredential обеспечивает проверку подлинности без ключей с помощью Microsoft Entra ID. Он объединяет несколько типов учетных данных, включая учетные данные Azure CLI из az login.
• SearchIndexClient управляет операциями на уровне индекса, такими как обновление схемы индекса.
• SearchClient обрабатывает операции на уровне документа, такие как запрос индекса.

Обновление индекса с помощью семантической конфигурации

Следующий код в BuildIndex/Program.cs добавляет семантическую конфигурацию в существующий индекс. Эта операция не удаляет документы поиска, а индекс остается в эксплуатации после добавления конфигурации.

static void AddSemanticConfiguration(
    SearchIndex index,
    string semanticConfigName)
{
    if (index.SemanticSearch == null)
    {
        index.SemanticSearch = new SemanticSearch();
    }
    var configs = index.SemanticSearch.Configurations;
    if (!configs.Any(c => c.Name == semanticConfigName))
    {
        var prioritizedFields =
            new SemanticPrioritizedFields
        {
            TitleField = new SemanticField("HotelName"),
            ContentFields =
            {
                new SemanticField("Description")
            },
            KeywordsFields =
            {
                new SemanticField("Tags")
            }
        };

        configs.Add(
            new SemanticConfiguration(
                semanticConfigName,
                prioritizedFields
            )
        );
    }
    index.SemanticSearch.DefaultConfigurationName =
        semanticConfigName;
}

Ключевые выносы:

• Семантическая конфигурация задает поля, используемые для семантического ранжирования.
• Семантические конфигурации можно добавлять в существующие индексы без перестроения.
• TitleField задает поле, представляющее название документа.
• ContentFields задает поля, содержащие основное содержимое.
• KeywordsFields задает поля, содержащие ключевые слова или теги.

Выполнить запрос к индексу

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

Простой запрос

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

await RunQuery(client, searchText, new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Simple,
    IncludeTotalCount = true,
    Select = { "HotelId", "HotelName", "Description" }
});

Ключевые выносы:

• SearchQueryType.Simple использует алгоритм ранжирования по умолчанию BM25.
• Результаты оцениваются только по релевантности ключевых слов (@search.score).

Семантический запрос (без подписей, нет ответов)

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

var semanticOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config"
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
await RunQuery(client, searchText, semanticOptions);

Ключевые выносы:

• SearchQueryType.Semantic включает семантический ранжирование в запросе.
• SemanticConfigurationName указывает, какую семантику конфигурации следует использовать.
• @search.rerankerScore указывает на степень семантической релевантности (чем выше, тем лучше).
• Первоначальные результаты запроса терминов перезаписываются с помощью семантических моделей ранжирования. Для этого набора данных и запроса эффекты семантического ранжирования более заметны в результатах более низкого ранга.

Семантический запрос с заголовками

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

var captionsOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config",
        QueryCaption =
            new QueryCaption(QueryCaptionType.Extractive)
        {
            HighlightEnabled = true
        }
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
captionsOptions.HighlightFields.Add("Description");
await RunQuery(
    client, searchText, captionsOptions, showCaptions: true
);

Ключевые выносы:

• QueryCaption включает извлечение подписей из полей содержимого.
• Заголовки отображают наиболее релевантные фрагменты и добавляют <em> теги вокруг важных терминов.

Семантический запрос с ответами

Последний запрос добавляет семантические ответы. Этот запрос использует другую строку поиска (searchText2), так как семантические ответы лучше всего работают при фразе запроса в качестве вопроса. Ответ представляет собой дословный отрывок, извлеченный из вашего индекса, а не сгенерированный ответ модели завершения чата.

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

var answersOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config",
        QueryAnswer =
            new QueryAnswer(QueryAnswerType.Extractive)
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
await RunQuery(
    client, searchText2, answersOptions, showAnswers: true
);

Ключевые выносы:

• QueryAnswer позволяет извлекать ответы на поисковые запросы, похожие на вопросы.
• Ответы — это подробный контент, извлеченный из индекса, а не созданный текст.

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

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

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно.

• Служба Поиск с использованием ИИ Azure.

• Индекс с описательными текстовыми полями, обозначенными как searchable и retrievable. В этом кратком руководстве предполагается индекс примера отелей.

• Java 21 (LTS) и Maven.

• Git для клонирования примера репозитория.

• Azure CLI для аутентификации без использования ключа с Microsoft Entra ID.

Настройка доступа

Перед началом работы убедитесь, что у вас есть разрешения на доступ к содержимому и операциям в Поиск с использованием ИИ Azure. В этом кратком руководстве используется Microsoft Entra ID для проверки подлинности и доступа на основе ролей для авторизации. Для назначения ролей необходимо быть владельцем или администратором доступа пользователей . Если роли не применимы, используйте проверку подлинности на основе ключей.

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

1. Включите доступ на основе ролей для службы поиска.

2. Назначьте следующие роли учетной записи пользователя.

   • Участник службы поиска

   • Средство чтения индексов поиска

Получение конечной точки

Каждая служба Поиск с использованием ИИ Azure имеет endpoint, который является уникальным URL-адресом, определяющим и предоставляющим сетевой доступ к службе. В следующем разделе описано, как указать эту конечную точку для программного подключения к службе поиска.

Чтобы получить конечную точку, выполните следующие действия.

1. Перейдите в службу поиска на портале Azure.

2. В левой области выберите "Обзор".

3. Запишите конечную точку, которая должна выглядеть следующим https://my-service.search.windows.netобразом.

Начните с индекса

Это краткое руководство изменяет существующий индекс для включения семантической конфигурации. Мы рекомендуем индекс хотелов-пример, который можно создать за считанные минуты, используя мастер портала Azure.

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

Чтобы просмотреть и запросить индекс примера отелей до семантического ранжирования:

1. Перейдите в службу поиска на портале Azure.

2. В левой панели выберите управление поиском>индексы.

3. Выберите hotels-sample.

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

   

5. Выберите обозреватель поиска, а затем выберите Вид>JSON-вид.

6. Вставьте следующий код JSON в редактор запросов.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Выберите "Поиск", чтобы запустить запрос.

   Ответ должен быть похож на следующий пример. Это полнотекстовый запрос, ранжированный по BM25, поэтому результаты соответствуют отдельным условиям запроса и лингвистическим вариантам, а не общему значению запроса. Например, walking совпадает с walk, а live и music сопоставляются независимо, а не как фраза.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "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."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Совет

   В этом запросе показано, как выглядит ответ перед применением семантического ранжирования. После настройки семантической конфигурации добавьте "queryType": "semantic" и "semanticConfiguration": "semantic-config", чтобы увидеть, как один и тот же запрос ранжируется по-разному семантическим ранжированием.

Настройка среды

1. Используйте Git для клонирования примера репозитория.

   git clone https://github.com/Azure-Samples/azure-search-java-samples
   

2. Перейдите в папку быстрого запуска.

   cd azure-search-java-samples/quickstart-semantic-ranking
   

3. В src/main/resources/application.propertiesэтом случае замените значение azure.search.endpoint заполнителя url-адресом, полученным в конечной точке Get.

4. Скомпилируйте проект, чтобы разрешить зависимости, включая azure-search-documents.

   mvn compile
   

   По завершении сборки убедитесь, что в выходных данных ошибки не отображаются.

5. Для проверки подлинности без ключа с помощью Microsoft Entra ID войдите в учетную запись Azure. Если у вас несколько подписок, выберите тот, который содержит службу Поиск с использованием ИИ Azure.

   az login
   

Запуск кода

1. Получите существующие параметры индекса.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.GetIndexSettings"
   

2. Обновите индекс с семантической конфигурацией.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.UpdateIndexSettings"
   

3. Запустите семантический запрос.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQuery"
   

4. Запустите семантический запрос с заголовками.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQueryWithCaptions"
   

5. Запустите семантический запрос с ответами.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticAnswer"
   

Выход

Выходные данные GetIndexSettings.java — это имя индекса, его поля и семантические конфигурации. Перед добавлением новой конфигурации индекс включает только конфигурацию по умолчанию.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic search configurations: 1
Configuration name: hotels-sample-semantic-configuration

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

// Trimmed for brevity
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

Результат работы SemanticQuery.java возвращает все соответствующие документы, упорядоченные по результатам повторного семантического ранжирования.

Search result #1:
  Re-ranker Score: 2.61
  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.

Search result #2:
  Re-ranker Score: 2.27
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

Search result #3:
  Re-ranker Score: 1.99
  HotelId: 4
  HotelName: Sublime Palace Hotel
  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
// Trimmed for brevity

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

Search result #1:
  Re-ranker Score: 2.61
  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.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.27
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
------------------------------------------------------------
// Trimmed for brevity

Выходные данные SemanticAnswer.java включают семантический ответ, полученный из одного из результатов, которые лучше всего соответствуют вопросу, а затем результаты поиска с заголовками.

Semantic answer result #1:
Semantic Answer: 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<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.98

Search Results:

Search result #1:
Re-ranker Score: 2.12
Hotel: Stay-Kay City Hotel
Description: This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.

Search result #2:
Re-ranker Score: 2.07
Hotel: Double Sanctuary Resort
Description: 5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
Caption: <em>5 star Luxury Hotel </em>-<em> Biggest </em>Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
// Trimmed for brevity

Общие сведения о коде

Теперь, когда вы выполнили код, давайте разберем ключевые шаги:

1. Настройка и проверка подлинности
2. Обновление индекса с помощью семантической конфигурации
3. Запрос индекса

Настройка и проверка подлинности

Класс SearchConfig.java загружает свойства из application.properties и создает DefaultAzureCredential для проверки подлинности без ключа.

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;

public class SearchConfig {
    private static final Properties properties =
        new Properties();

    static {
        try (InputStream input = SearchConfig.class
            .getClassLoader()
            .getResourceAsStream(
                "application.properties")) {
            properties.load(input);
        } catch (IOException e) {
            throw new RuntimeException(
                "Failed to load application.properties",
                e);
        }
    }

    public static final String SEARCH_ENDPOINT =
        properties.getProperty(
            "azure.search.endpoint");
    public static final String INDEX_NAME =
        properties.getProperty(
            "azure.search.index.name");
    public static final String SEMANTIC_CONFIG_NAME =
        properties.getProperty(
            "semantic.configuration.name");

    public static final DefaultAzureCredential
        CREDENTIAL = new DefaultAzureCredentialBuilder()
            .build();
}

Ключевые выносы:

• DefaultAzureCredential обеспечивает проверку подлинности без ключей с помощью Microsoft Entra ID. Он объединяет несколько типов учетных данных, включая учетные данные Azure CLI из az login.
• Свойства загружаются из application.properties файла в classpath.
• Статические поля (SEARCH_ENDPOINT, INDEX_NAME, SEMANTIC_CONFIG_NAME, CREDENTIAL) совместно используются во всех классах проекта.

Обновление индекса с помощью семантической конфигурации

Класс UpdateIndexSettings.java добавляет семантическую конфигурацию в существующий hotels-sample индекс. Эта операция не удаляет документы поиска, а индекс остается в эксплуатации после добавления конфигурации.

import com.azure.search.documents.indexes
    .SearchIndexClientBuilder;
import com.azure.search.documents.indexes.models
    .SearchIndex;
import com.azure.search.documents.indexes.models
    .SemanticConfiguration;
import com.azure.search.documents.indexes.models
    .SemanticField;
import com.azure.search.documents.indexes.models
    .SemanticPrioritizedFields;
import com.azure.search.documents.indexes.models
    .SemanticSearch;

import java.util.ArrayList;
import java.util.List;

var indexClient = new SearchIndexClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

SearchIndex existingIndex =
    indexClient.getIndex(SearchConfig.INDEX_NAME);

var prioritizedFields =
    new SemanticPrioritizedFields()
        .setTitleField(
            new SemanticField("HotelName"))
        .setKeywordsFields(
            List.of(new SemanticField("Tags")))
        .setContentFields(
            List.of(
                new SemanticField("Description")));

var newSemanticConfiguration =
    new SemanticConfiguration(
        SearchConfig.SEMANTIC_CONFIG_NAME,
        prioritizedFields);

SemanticSearch semanticSearch =
    existingIndex.getSemanticSearch();
if (semanticSearch == null) {
    semanticSearch = new SemanticSearch();
    existingIndex.setSemanticSearch(semanticSearch);
}

List<SemanticConfiguration> configurations =
    semanticSearch.getConfigurations();
if (configurations == null) {
    configurations = new ArrayList<>();
    semanticSearch.setConfigurations(configurations);
}

configurations.add(newSemanticConfiguration);

indexClient.createOrUpdateIndex(existingIndex);

Ключевые выносы:

• SemanticPrioritizedFields определяет поля, которые вычисляет семантический рангировщик. setTitleField задает название документа, setContentFields задает основное содержимое и setKeywordsFields задает поля ключевого слова или тега.
• SemanticConfiguration связывает имя с приоритетными полями, определяя семантику конфигурации, которую следует использовать во время запроса.
• createOrUpdateIndex отправляет обновленную схему в службу поиска без перестроения индекса или удаления документов.

Выполнить запрос к индексу

Следующие три класса поочерёдно запрашивают индекс, начиная с базового семантического поиска и переходя к семантическому ранжированию с подписями и ответами.

Семантический запрос (без подписей, нет ответов)

Первый запрос добавляет семантический рейтинг без подписей или ответов. Класс SemanticQuery.java показывает минимальное требование для вызова семантического ранжирования.

import com.azure.search.documents
    .SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryType;
import com.azure.search.documents.models.SearchOptions;
import com.azure.search.documents.models.SearchResult;
import com.azure.search.documents.models
    .SemanticSearchOptions;
import com.azure.search.documents.util
    .SearchPagedIterable;

var searchClient = new SearchClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .indexName(SearchConfig.INDEX_NAME)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME))
    .setSelect("HotelId", "HotelName", "Description");

SearchPagedIterable results = searchClient.search(
    "walking distance to live music",
    searchOptions, null);

for (SearchResult result : results) {
    var document = result.getDocument(
        SearchDocument.class);
    double rerankerScore = result
        .getSemanticSearch().getRerankerScore();

    System.out.printf("Re-ranker Score: %.2f%n",
        rerankerScore);
    System.out.printf("HotelName: %s%n",
        document.get("HotelName"));
    System.out.printf("Description: %s%n%n",
        document.get("Description"));
}

Ключевые выносы:

• QueryType.SEMANTIC включает семантический ранжирование в запросе.
• setSemanticConfigurationName указывает, какую семантику конфигурации следует использовать.
• SearchPagedIterable предоставляет итерируемый доступ к повторно ранжированным результатам. Каждый SearchResult содержит getSemanticSearch() метод доступа для результата ранжировщика.

Семантический запрос с заголовками

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

import com.azure.search.documents.models
    .QueryCaption;
import com.azure.search.documents.models
    .QueryCaptionResult;
import com.azure.search.documents.models
    .QueryCaptionType;

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME)
            .setQueryCaption(
                new QueryCaption(
                    QueryCaptionType.EXTRACTIVE)
                    .setHighlightEnabled(true)))
    .setSelect(
        "HotelId", "HotelName", "Description");

SearchPagedIterable results = searchClient.search(
    "walking distance to live music",
    searchOptions, null);

for (SearchResult result : results) {
    List<QueryCaptionResult> captions =
        result.getSemanticSearch()
            .getQueryCaptions();
    if (captions != null && !captions.isEmpty()) {
        QueryCaptionResult caption = captions.get(0);
        if (caption.getHighlights() != null) {
            System.out.printf(
                "Caption: %s%n",
                caption.getHighlights());
        }
    }
}

Ключевые выносы:

• QueryCaption(QueryCaptionType.EXTRACTIVE) включает извлечение подписей из полей содержимого.
• setHighlightEnabled(true) добавляет <em> теги вокруг важных терминов в заголовках.
• Каждый SearchResult предоставляет getQueryCaptions() для аксессора семантического поиска.

Семантический запрос с ответами

Класс SemanticAnswer.java добавляет семантические ответы. Этот класс использует вопрос в качестве текста поиска, так как семантические ответы лучше всего работают, когда запрос фразируется как вопрос. Ответ представляет собой дословный отрывок, извлеченный из вашего индекса, а не сгенерированный ответ модели завершения чата.

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

import com.azure.search.documents.models
    .QueryAnswer;
import com.azure.search.documents.models
    .QueryAnswerResult;
import com.azure.search.documents.models
    .QueryAnswerType;

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME)
            .setQueryCaption(
                new QueryCaption(
                    QueryCaptionType.EXTRACTIVE))
            .setQueryAnswer(
                new QueryAnswer(
                    QueryAnswerType.EXTRACTIVE)))
    .setSelect(
        "HotelName", "Description", "Category");

SearchPagedIterable results = searchClient.search(
    "What's a good hotel for people who like to read",
    searchOptions, null);

List<QueryAnswerResult> semanticAnswers =
    results.getSemanticResults().getQueryAnswers();

for (QueryAnswerResult answer :
    semanticAnswers != null ? semanticAnswers
        : List.<QueryAnswerResult>of()) {
    if (answer.getHighlights() != null) {
        System.out.printf(
            "Semantic Answer: %s%n",
            answer.getHighlights());
    } else {
        System.out.printf(
            "Semantic Answer: %s%n",
            answer.getText());
    }
    System.out.printf(
        "Semantic Answer Score: %.2f%n",
        answer.getScore());
}

Ключевые выносы:

• QueryAnswer(QueryAnswerType.EXTRACTIVE) позволяет извлекать ответы на поисковые запросы, похожие на вопросы.
• Ответы — это подробный контент, извлеченный из индекса, а не созданный текст.
• results.getSemanticResults().getQueryAnswers() извлекает объекты ответов отдельно от результатов поиска.

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

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

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно.

• Служба Поиск с использованием ИИ Azure.

• Индекс с описательными текстовыми полями, обозначенными как searchable и retrievable. В этом кратком руководстве предполагается индекс примера отелей.

• Node.js 20 LTS или более поздней версии.

• Git для клонирования примера репозитория.

• Azure CLI для аутентификации без использования ключа с Microsoft Entra ID.

Настройка доступа

Перед началом работы убедитесь, что у вас есть разрешения на доступ к содержимому и операциям в Поиск с использованием ИИ Azure. В этом кратком руководстве используется Microsoft Entra ID для проверки подлинности и доступа на основе ролей для авторизации. Для назначения ролей необходимо быть владельцем или администратором доступа пользователей . Если роли не применимы, используйте проверку подлинности на основе ключей.

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

1. Включите доступ на основе ролей для службы поиска.

2. Назначьте следующие роли учетной записи пользователя.

   • Участник службы поиска

   • Средство чтения индексов поиска

Получение конечной точки

Каждая служба Поиск с использованием ИИ Azure имеет endpoint, который является уникальным URL-адресом, определяющим и предоставляющим сетевой доступ к службе. В следующем разделе описано, как указать эту конечную точку для программного подключения к службе поиска.

Чтобы получить конечную точку, выполните следующие действия.

1. Перейдите в службу поиска на портале Azure.

2. В левой области выберите "Обзор".

3. Запишите конечную точку, которая должна выглядеть следующим https://my-service.search.windows.netобразом.

Начните с индекса

Это краткое руководство изменяет существующий индекс для включения семантической конфигурации. Мы рекомендуем индекс хотелов-пример, который можно создать за считанные минуты, используя мастер портала Azure.

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

Чтобы просмотреть и запросить индекс примера отелей до семантического ранжирования:

1. Перейдите в службу поиска на портале Azure.

2. В левой панели выберите управление поиском>индексы.

3. Выберите hotels-sample.

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

   

5. Выберите обозреватель поиска, а затем выберите Вид>JSON-вид.

6. Вставьте следующий код JSON в редактор запросов.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Выберите "Поиск", чтобы запустить запрос.

   Ответ должен быть похож на следующий пример. Это полнотекстовый запрос, ранжированный по BM25, поэтому результаты соответствуют отдельным условиям запроса и лингвистическим вариантам, а не общему значению запроса. Например, walking совпадает с walk, а live и music сопоставляются независимо, а не как фраза.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "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."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Совет

   В этом запросе показано, как выглядит ответ перед применением семантического ранжирования. После настройки семантической конфигурации добавьте "queryType": "semantic" и "semanticConfiguration": "semantic-config", чтобы увидеть, как один и тот же запрос ранжируется по-разному семантическим ранжированием.

Настройка среды

1. Используйте Git для клонирования примера репозитория.

   git clone https://github.com/Azure-Samples/azure-search-javascript-samples
   

2. Перейдите в папку быстрого запуска.

   cd azure-search-javascript-samples/quickstart-semantic-ranking-js
   

3. В sample.envэтом случае замените значение AZURE_SEARCH_ENDPOINT заполнителя url-адресом, полученным в конечной точке Get.

4. Переименуйте sample.env на .env.

   mv sample.env .env
   

5. Установите зависимости.

   npm install
   

   После завершения установки в каталоге проекта должна появиться node_modules папка.

6. Для проверки подлинности без ключа с помощью Microsoft Entra ID войдите в учетную запись Azure. Если у вас несколько подписок, выберите тот, который содержит службу Поиск с использованием ИИ Azure.

   az login
   

Запуск кода

1. Получите существующие параметры индекса.

   node -r dotenv/config src/getIndexSettings.js
   

2. Обновите индекс с семантической конфигурацией.

   node -r dotenv/config src/updateIndexSettings.js
   

3. Запустите семантический запрос.

   node -r dotenv/config src/semanticQuery.js
   

4. Запустите семантический запрос с заголовками.

   node -r dotenv/config src/semanticQueryReturnCaptions.js
   

5. Запустите семантический запрос с ответами.

   node -r dotenv/config src/semanticAnswer.js
   

Выход

Скрипт getIndexSettings.js возвращает имя индекса, его поля и все существующие семантические конфигурации.

Getting semantic ranking index settings...
Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
Field: Description_fr, Type: Edm.String, Searchable: true
Field: Category, Type: Edm.String, Searchable: true
Field: Tags, Type: Collection(Edm.String), Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

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

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

Скрипт semanticQuery.js возвращает все соответствующие документы, упорядоченные по оценкам семантического повторного ранжирования.

Search result #1:
  Re-ranker Score: 2.613231658935547
  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.

Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

Search result #3:
  Re-ranker Score: 1.9861756563186646
  HotelId: 4
  HotelName: Sublime Palace Hotel
  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
// Trimmed for brevity

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

Search result #1:
  Re-ranker Score: 2.613231658935547
  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.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
------------------------------------------------------------
// Trimmed for brevity

Сценарий semanticAnswer.js возвращает семантический ответ, полученный из одного из результатов, которые лучше всего соответствуют вопросу, а затем результаты поиска с заголовками.

Answers:

Semantic answer result #1:
Semantic Answer: 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<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
// Trimmed for brevity

Общие сведения о коде

Теперь, когда вы выполнили код, давайте разберем ключевые шаги:

1. Настройка и проверка подлинности
2. Обновление индекса с помощью семантической конфигурации
3. Запрос индекса

Настройка и проверка подлинности

Файл config.js загружает переменные среды и создает DefaultAzureCredential для проверки подлинности.

import { DefaultAzureCredential }
    from "@azure/identity";

export const searchEndpoint =
    process.env.AZURE_SEARCH_ENDPOINT
    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName =
    process.env.AZURE_SEARCH_INDEX_NAME
    || "hotels-sample";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

Ключевые выносы:

• DefaultAzureCredential обеспечивает проверку подлинности без ключей с помощью Microsoft Entra ID. Он объединяет несколько типов учетных данных, включая учетные данные Azure CLI из az login.
• Переменные среды загружаются из файла .env с помощью dotenv.

Обновление индекса с помощью семантической конфигурации

Файл updateIndexSettings.js добавляет семантическую конфигурацию в существующий индекс hotels-sample. Эта операция не удаляет документы поиска, а индекс остается в эксплуатации после добавления конфигурации.

import { SearchIndexClient }
    from "@azure/search-documents";
import {
    searchEndpoint, indexName,
    credential, semanticConfigurationName
} from "./config.js";

const indexClient = new SearchIndexClient(
    searchEndpoint, credential
);
const existingIndex =
    await indexClient.getIndex(indexName);

const fields = {
    titleField: { name: "HotelName" },
    keywordsFields: [{ name: "Tags" }],
    contentFields: [{ name: "Description" }]
};

const newSemanticConfiguration = {
    name: semanticConfigurationName,
    prioritizedFields: fields
};

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

Ключевые выносы:

• Семантическая конфигурация задает поля, используемые для семантического ранжирования. titleField определяет название документа, contentFields определяет основное содержимое и keywordsFields определяет поля ключевого слова или тега.
• Вы создаете объект конфигурации и отправляете его в массив существующего индекса semanticSearch.configurations .
• createOrUpdateIndex отправляет обновленную схему в службу поиска без перестроения индекса или удаления документов.

Выполнить запрос к индексу

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

Семантический запрос (без подписей, нет ответов)

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

import { SearchClient }
    from "@azure/search-documents";
import {
    credential, searchEndpoint,
    indexName, semanticConfigurationName
} from "./config.js";

const searchClient = new SearchClient(
    searchEndpoint, indexName, credential
);

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

Ключевые выносы:

• queryType: "semantic" включает семантический ранжирование в запросе.
• semanticSearchOptions.configurationName указывает, какую семантику конфигурации следует использовать.
• В rerankerScore результатах указывается семантическая релевантность (чем выше, тем лучше).

Семантический запрос с заголовками

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

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive",
                highlight: true
            }
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

Ключевые выносы:

• captions.captionType: "extractive" включает извлечение подписей из полей содержимого.
• Заголовки отображают наиболее релевантные фрагменты и добавляют <em> теги вокруг важных терминов.

Семантический запрос с ответами

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

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

const results = await searchClient.search(
    "What's a good hotel for people who "
    + "like to read",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive"
            },
            answers: {
                answerType: "extractive"
            }
        },
        select: [
            "HotelName", "Description", "Category"
        ]
    }
);

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

Ключевые выносы:

• answers.answerType: "extractive" позволяет извлекать ответы на поисковые запросы, похожие на вопросы.
• Ответы — это подробный контент, извлеченный из индекса, а не созданный текст.
• results.answers извлекает объекты ответов отдельно от результатов поиска.

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

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

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно.

• Служба Поиск с использованием ИИ Azure.

• Индекс с описательными текстовыми полями, обозначенными как searchable и retrievable. В этом кратком руководстве предполагается индекс примера отелей.

• Python 3.10 или более поздней версии.

• Visual Studio Code с расширением Python.

• Git для клонирования примера репозитория.

• Azure CLI для аутентификации без использования ключа с Microsoft Entra ID.

Настройка доступа

Перед началом работы убедитесь, что у вас есть разрешения на доступ к содержимому и операциям в Поиск с использованием ИИ Azure. В этом кратком руководстве используется Microsoft Entra ID для проверки подлинности и доступа на основе ролей для авторизации. Для назначения ролей необходимо быть владельцем или администратором доступа пользователей . Если роли не применимы, используйте проверку подлинности на основе ключей.

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

1. Включите доступ на основе ролей для службы поиска.

2. Назначьте следующие роли учетной записи пользователя.

   • Участник службы поиска

   • Средство чтения индексов поиска

Получение конечной точки

Каждая служба Поиск с использованием ИИ Azure имеет endpoint, который является уникальным URL-адресом, определяющим и предоставляющим сетевой доступ к службе. В следующем разделе описано, как указать эту конечную точку для программного подключения к службе поиска.

Чтобы получить конечную точку, выполните следующие действия.

1. Перейдите в службу поиска на портале Azure.

2. В левой области выберите "Обзор".

3. Запишите конечную точку, которая должна выглядеть следующим https://my-service.search.windows.netобразом.

Начните с индекса

Это краткое руководство изменяет существующий индекс для включения семантической конфигурации. Мы рекомендуем индекс хотелов-пример, который можно создать за считанные минуты, используя мастер портала Azure.

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

Чтобы просмотреть и запросить индекс примера отелей до семантического ранжирования:

1. Перейдите в службу поиска на портале Azure.

2. В левой панели выберите управление поиском>индексы.

3. Выберите hotels-sample.

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

   

5. Выберите обозреватель поиска, а затем выберите Вид>JSON-вид.

6. Вставьте следующий код JSON в редактор запросов.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Выберите "Поиск", чтобы запустить запрос.

   Ответ должен быть похож на следующий пример. Это полнотекстовый запрос, ранжированный по BM25, поэтому результаты соответствуют отдельным условиям запроса и лингвистическим вариантам, а не общему значению запроса. Например, walking совпадает с walk, а live и music сопоставляются независимо, а не как фраза.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "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."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Совет

   В этом запросе показано, как выглядит ответ перед применением семантического ранжирования. После настройки семантической конфигурации добавьте "queryType": "semantic" и "semanticConfiguration": "semantic-config", чтобы увидеть, как один и тот же запрос ранжируется по-разному семантическим ранжированием.

Настройка среды

1. Используйте Git для клонирования примера репозитория.

   git clone https://github.com/Azure-Samples/azure-search-python-samples
   

2. Перейдите в папку быстрого запуска и откройте ее в Visual Studio Code.

   cd azure-search-python-samples/Quickstart-Semantic-Ranking
   code .
   

3. В sample.envэтом случае замените значение AZURE_SEARCH_ENDPOINT заполнителя url-адресом, полученным в конечной точке Get.

4. Переименуйте sample.env на .env.

   mv sample.env .env
   

5. Откройте semantic-ranking-quickstart.ipynb.

6. Нажмите клавиши CTRL+SHIFT+P, выберите записную книжку: выберите ядро записной книжки и следуйте инструкциям по созданию виртуальной среды. Выберите requirements.txt для зависимостей.

   По завершении вы увидите папку .venv в каталоге проекта.

7. Для проверки подлинности без ключа с помощью Microsoft Entra ID войдите в учетную запись Azure. Если у вас несколько подписок, выберите тот, который содержит службу Поиск с использованием ИИ Azure.

   az login
   

Запуск кода

1. Запустите ячейки, чтобы установить необходимые Install packages and set variables пакеты и загрузить переменные среды.

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

Выход

Выходные данные Get the index definition ячейки — это имя индекса, его полей и любые существующие семантические конфигурации.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: True
Field: HotelName, Type: Edm.String, Searchable: True
Field: Description, Type: Edm.String, Searchable: True
Field: Description_fr, Type: Edm.String, Searchable: True
Field: Category, Type: Edm.String, Searchable: True
Field: Tags, Type: Collection(Edm.String), Searchable: True
// Trimmed for brevity
Semantic config: hotels-sample-semantic-configuration
Title field: HotelName

Выходные данные Add a semantic configuration to the index ячейки перечисляют все семантические конфигурации на индексе, включая ту, которую добавил код, за чем следует сообщение о успешном выполнении.

Semantic configurations:
----------------------------------------
  Configuration: hotels-sample-semantic-configuration
    Title field: HotelName
    Keywords fields: Category
    Content fields: Description

  Configuration: semantic-config
    Title field: HotelName
    Keywords fields: Tags
    Content fields: Description

✅ Semantic configuration successfully added!

Выходные данные ячейки Run a term query возвращают все соответствующие документы, упорядоченные по оценке BM25. Этот базовый запрос не использует семантический ранжирование.

5.360838
4
Sublime Palace Hotel
Description: Sublime Cliff Hotel is located in the heart of the
historic center of Sublime in an extremely vibrant and lively area
within short walking distance to the sites and landmarks of the city
and is surrounded by the extraordinary beauty of churches, buildings,
shops and monuments. Sublime Cliff is part of a lovingly restored
19th century resort, updated for every modern convenience.
4.691083
2
Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza,
which has been expanded and renovated to the highest architectural
standards to create a modern, functional and first-class hotel in
which art and unique historical elements coexist with the most
modern comforts. The hotel also regularly hosts events like wine
tastings, beer dinners, and live music.
// Trimmed for brevity

Выходные данные ячейки Run a semantic query возвращают все соответствующие документы, упорядоченные семантической оценкой повторного ранжирования.

2.613231658935547
24
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.
2.271434783935547
2
Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza,
which has been expanded and renovated to the highest architectural
standards to create a modern, functional and first-class hotel in
which art and unique historical elements coexist with the most
modern comforts. The hotel also regularly hosts events like wine
tastings, beer dinners, and live music.
// Trimmed for brevity

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

2.613231658935547
24
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.
Caption: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to<em> theaters, </em>art galleries,
restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and
then head over to<em> Benaroya Hall </em>to catch the evening's
concert performance.
// Trimmed for brevity

Выходные данные ячейки Return semantic answers включают семантический ответ, полученный из одного из результатов, которые лучше всего соответствуют вопросу, а затем результаты поиска с заголовками.

Semantic Answer: 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<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Общие сведения о коде

Теперь, когда вы выполнили код, давайте разберем ключевые шаги:

1. Настройка и проверка подлинности
2. Обновление индекса с помощью семантической конфигурации
3. Запрос индекса

Настройка и проверка подлинности

Ячейка Install packages and set variables загружает переменные среды и создает DefaultAzureCredential для проверки подлинности.

from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.identity import get_bearer_token_provider
import os

load_dotenv(override=True)

search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
index_name = os.getenv(
    "AZURE_SEARCH_INDEX", "hotels-sample"
)

Ключевые выносы:

• DefaultAzureCredential обеспечивает проверку подлинности без ключей с помощью Microsoft Entra ID. Он объединяет несколько типов учетных данных, включая учетные данные Azure CLI из az login.
• Переменные среды загружаются из файла .env с помощью python-dotenv.

Обновление индекса с помощью семантической конфигурации

Ячейка Add a semantic configuration to the index добавляет семантическую конфигурацию в существующий hotels-sample индекс. Эта операция не удаляет документы поиска, а индекс остается в эксплуатации после добавления конфигурации.

from azure.search.documents.indexes.models import (
    SemanticConfiguration,
    SemanticField,
    SemanticPrioritizedFields,
    SemanticSearch
)

new_semantic_config = SemanticConfiguration(
    name="semantic-config",
    prioritized_fields=SemanticPrioritizedFields(
        title_field=SemanticField(field_name="HotelName"),
        keywords_fields=[
            SemanticField(field_name="Tags")
        ],
        content_fields=[
            SemanticField(field_name="Description")
        ]
    )
)

if existing_index.semantic_search is None:
    existing_index.semantic_search = SemanticSearch(
        configurations=[new_semantic_config]
    )
else:
    existing_index.semantic_search.configurations.append(
        new_semantic_config
    )

result = index_client.create_or_update_index(existing_index)

Ключевые выносы:

• Семантическая конфигурация задает поля, используемые для семантического ранжирования. title_field задает название документа, content_fields задает основное содержимое и keywords_fields задает поля ключевого слова или тега.
• Вы создаете конфигурацию с SemanticConfiguration и связанной с ней моделью SemanticPrioritizedFields, а затем добавляете её в существующий индекс.
• create_or_update_index отправляет обновленную схему в службу поиска без перестроения индекса или удаления документов.

Выполнить запрос к индексу

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

Запрос терминов (базовый уровень)

Ячейка Run a term query выполняет поиск ключевых слов с помощью оценки BM25. Этот базовый запрос не использует семантический ранжирование и служит точкой сравнения.

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='simple',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    include_total_count=True
)

Ключевые выносы:

• query_type='simple' задает поиск ключевых слов, используя ранжирование BM25.
• В @search.score результатах указывается оценка релевантности BM25.

Семантический запрос (без подписей, нет ответов)

В ячейке Run a semantic query отображается минимальное требование для вызова семантического ранжирования.

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    query_caption='extractive'
)

Ключевые выносы:

• query_type='semantic' включает семантический ранжирование в запросе.
• semantic_configuration_name указывает, какую семантику конфигурации следует использовать.
• В @search.reranker_score результатах указывается семантическая релевантность (чем выше, тем лучше).

Семантический запрос с заголовками

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

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="walking distance to live music",
    select='HotelName,HotelId,Description',
    query_caption='extractive'
)

for result in results:
    captions = result["@search.captions"]
    if captions:
        caption = captions[0]
        if caption.highlights:
            print(f"Caption: {caption.highlights}\n")

Ключевые выносы:

• query_caption='extractive' включает извлечение подписей из полей содержимого.
• Заголовки отображают наиболее релевантные фрагменты и добавляют <em> теги вокруг важных терминов.

Семантический запрос с ответами

Ячейка Return semantic answers добавляет семантические ответы. Этот запрос использует вопрос в качестве текста поиска, так как семантические ответы лучше всего работают, когда запрос фразируется как вопрос. Ответ представляет собой дословный отрывок, извлеченный из вашего индекса, а не сгенерированный ответ модели завершения чата.

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

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="what's a good hotel for people who "
                "like to read",
    select='HotelName,Description,Category',
    query_caption='extractive',
    query_answer="extractive",
)

semantic_answers = results.get_answers()
for answer in semantic_answers:
    if answer.highlights:
        print(f"Semantic Answer: {answer.highlights}")
    else:
        print(f"Semantic Answer: {answer.text}")
    print(f"Semantic Answer Score: {answer.score}\n")

Ключевые выносы:

• query_answer="extractive" позволяет извлекать ответы на поисковые запросы, похожие на вопросы.
• Ответы — это подробный контент, извлеченный из индекса, а не созданный текст.
• results.get_answers() извлекает объекты ответов отдельно от результатов поиска.

В этом кратком руководстве вы используете клиентскую библиотеку Поиск с использованием ИИ Azure для JavaScript (совместимую с TypeScript), для добавления семантического ранжирования в существующий индекс поиска и выполнения запросов к индексу.

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

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно.

• Служба Поиск с использованием ИИ Azure.

• Индекс с описательными текстовыми полями, обозначенными как searchable и retrievable. В этом кратком руководстве предполагается индекс примера отелей.

• Node.js 20 LTS или более поздней версии для запуска скомпилированного кода.

• TypeScript для компиляции TypeScript в JavaScript.

• Git для клонирования примера репозитория.

• Azure CLI для аутентификации без использования ключа с Microsoft Entra ID.

Настройка доступа

Перед началом работы убедитесь, что у вас есть разрешения на доступ к содержимому и операциям в Поиск с использованием ИИ Azure. В этом кратком руководстве используется Microsoft Entra ID для проверки подлинности и доступа на основе ролей для авторизации. Для назначения ролей необходимо быть владельцем или администратором доступа пользователей . Если роли не применимы, используйте проверку подлинности на основе ключей.

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

1. Включите доступ на основе ролей для службы поиска.

2. Назначьте следующие роли учетной записи пользователя.

   • Участник службы поиска

   • Средство чтения индексов поиска

Получение конечной точки

Каждая служба Поиск с использованием ИИ Azure имеет endpoint, который является уникальным URL-адресом, определяющим и предоставляющим сетевой доступ к службе. В следующем разделе описано, как указать эту конечную точку для программного подключения к службе поиска.

Чтобы получить конечную точку, выполните следующие действия.

1. Перейдите в службу поиска на портале Azure.

2. В левой области выберите "Обзор".

3. Запишите конечную точку, которая должна выглядеть следующим https://my-service.search.windows.netобразом.

Начните с индекса

Это краткое руководство изменяет существующий индекс для включения семантической конфигурации. Мы рекомендуем индекс хотелов-пример, который можно создать за считанные минуты, используя мастер портала Azure.

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

Чтобы просмотреть и запросить индекс примера отелей до семантического ранжирования:

1. Перейдите в службу поиска на портале Azure.

2. В левой панели выберите управление поиском>индексы.

3. Выберите hotels-sample.

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

   

5. Выберите обозреватель поиска, а затем выберите Вид>JSON-вид.

6. Вставьте следующий код JSON в редактор запросов.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Выберите "Поиск", чтобы запустить запрос.

   Ответ должен быть похож на следующий пример. Это полнотекстовый запрос, ранжированный по BM25, поэтому результаты соответствуют отдельным условиям запроса и лингвистическим вариантам, а не общему значению запроса. Например, walking совпадает с walk, а live и music сопоставляются независимо, а не как фраза.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "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."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Совет

   В этом запросе показано, как выглядит ответ перед применением семантического ранжирования. После настройки семантической конфигурации добавьте "queryType": "semantic" и "semanticConfiguration": "semantic-config", чтобы увидеть, как один и тот же запрос ранжируется по-разному семантическим ранжированием.

Настройка среды

1. Используйте Git для клонирования примера репозитория.

   git clone https://github.com/Azure-Samples/azure-search-javascript-samples
   

2. Перейдите в папку быстрого запуска.

   cd azure-search-javascript-samples/quickstart-semantic-ranking-ts
   

3. В sample.envэтом случае замените значение AZURE_SEARCH_ENDPOINT заполнителя url-адресом, полученным в конечной точке Get.

4. Переименуйте sample.env на .env.

   mv sample.env .env
   

5. Установите зависимости.

   npm install
   

   После завершения установки в каталоге проекта должна появиться node_modules папка.

6. Скомпилируйте файлы TypeScript в JavaScript.

   npm run build
   

7. Для проверки подлинности без ключа с помощью Microsoft Entra ID войдите в учетную запись Azure. Если у вас несколько подписок, выберите тот, который содержит службу Поиск с использованием ИИ Azure.

   az login
   

Запуск кода

1. Получите существующие параметры индекса.

   node -r dotenv/config dist/getIndexSettings.js
   

2. Обновите индекс с семантической конфигурацией.

   node -r dotenv/config dist/updateIndexSettings.js
   

3. Запустите семантический запрос.

   node -r dotenv/config dist/semanticQuery.js
   

4. Запустите семантический запрос с заголовками.

   node -r dotenv/config dist/semanticQueryReturnCaptions.js
   

5. Запустите семантический запрос с ответами.

   node -r dotenv/config dist/semanticAnswer.js
   

   Примечание

   Эти команды выполняют скомпилированные .js файлы из dist папки. Код TypeScript должен быть транспилирован в JavaScript, прежде чем Node.js его может выполнить, поэтому ранее вы выполнили npm run build.

Выход

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

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

Скрипт updateIndexSettings.js возвращает все семантические конфигурации, включая ту, которую вы добавили.

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

Скрипт semanticQuery.js возвращает результаты, упорядоченные по оценке повторного ранжирования.

Search result #1:
  Re-ranker Score: 2.613231658935547
  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.

Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza...
  // Trimmed for brevity

Скрипт semanticQueryReturnCaptions.js возвращает извлекаемые субтитры с выделением совпадений. Заголовки являются наиболее актуальными фрагментами результатов поиска.

Search result #1:
  Re-ranker Score: 2.613231658935547
  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.

  Caption with highlights: Chic hotel near the city. High-rise hotel
  in downtown, within walking distance to<em> theaters, </em>art
  galleries, restaurants and shops. Visit<em> Seattle Art Museum
  </em>by day, and then head over to<em> Benaroya Hall </em>to catch
  the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  // Trimmed for brevity

Скрипт semanticAnswer.js возвращает семантический ответ (подробное содержимое), извлекаемый из результата, который лучше всего соответствует вопросу.

Semantic answer result #1:
Semantic Answer: 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<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the
main commercial artery of the city in the heart of New York...
Caption: This classic hotel is<em> fully-refurbished </em>and
ideally located on the main commercial artery of the city...
// Trimmed for brevity

Общие сведения о коде

Теперь, когда вы выполнили код, давайте разберем ключевые шаги:

1. Настройка и проверка подлинности
2. Обновление индекса с помощью семантической конфигурации
3. Запрос индекса

Настройка и проверка подлинности

Файл config.ts загружает переменные среды, создает DefaultAzureCredential для проверки подлинности и определяет HotelDocument интерфейс для безопасности типов.

import { DefaultAzureCredential }
    from "@azure/identity";

export const searchEndpoint =
    process.env.AZURE_SEARCH_ENDPOINT
    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName =
    process.env.AZURE_SEARCH_INDEX_NAME
    || "hotels-sample";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

export interface HotelDocument {
    HotelId: string;
    HotelName: string;
    Description: string;
    Category: string;
    Tags: string[];
}

Ключевые выносы:

• DefaultAzureCredential обеспечивает проверку подлинности без ключей с помощью Microsoft Entra ID. Он объединяет несколько типов учетных данных, включая учетные данные Azure CLI из az login.
• Интерфейс HotelDocument обеспечивает проверку типа во время компиляции для результатов поиска, обеспечивая безопасный доступ к полям документов.
• Переменные среды загружаются из файла .env с помощью dotenv.

Обновление индекса с помощью семантической конфигурации

Файл updateIndexSettings.ts добавляет семантическую конфигурацию в существующий индекс hotels-sample. Эта операция не удаляет документы поиска, а индекс остается в эксплуатации после добавления конфигурации. Заметки типов TypeScript гарантируют соответствие конфигурации ожидаемой схеме.

import {
    SearchIndexClient,
    SemanticConfiguration,
    SemanticPrioritizedFields,
    SemanticField
} from "@azure/search-documents";
import {
    searchEndpoint, indexName,
    credential, semanticConfigurationName
} from "./config.js";

const indexClient = new SearchIndexClient(
    searchEndpoint, credential
);
const existingIndex =
    await indexClient.getIndex(indexName);

const fields: SemanticPrioritizedFields = {
    titleField: { name: "HotelName" },
    keywordsFields: [
        { name: "Tags" }
    ] as SemanticField[],
    contentFields: [
        { name: "Description" }
    ] as SemanticField[]
};

const newSemanticConfiguration:
    SemanticConfiguration = {
    name: semanticConfigurationName,
    prioritizedFields: fields
};

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

Ключевые выносы:

• Типы TypeScript, например SemanticPrioritizedFields, SemanticConfiguration и SemanticField, предоставляют проверку структуры конфигурации на этапе компиляции.
• titleField задает название документа, contentFields задает основное содержимое и keywordsFields задает поля ключевого слова или тега.
• createOrUpdateIndex отправляет обновленную схему в службу поиска без перестроения индекса или удаления документов.

Выполнить запрос к индексу

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

Семантический запрос (без подписей, нет ответов)

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

import { SearchClient }
    from "@azure/search-documents";
import {
    HotelDocument, credential,
    searchEndpoint, indexName,
    semanticConfigurationName
} from "./config.js";

const searchClient =
    new SearchClient<HotelDocument>(
        searchEndpoint, indexName, credential
    );

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

Ключевые выносы:

• SearchClient<HotelDocument> предоставляет типобезопасный доступ к полям документа в результатах поиска с автодополнением для имен полей в select и result.document.
• queryType: "semantic" включает семантический ранжирование в запросе.
• semanticSearchOptions.configurationName указывает, какую семантику конфигурации следует использовать.

Семантический запрос с заголовками

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

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive",
                highlight: true
            }
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

Ключевые выносы:

• captions.captionType: "extractive" включает извлечение подписей из полей содержимого.
• Заголовки отображают наиболее релевантные фрагменты и добавляют <em> теги вокруг важных терминов.

Семантический запрос с ответами

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

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

const results = await searchClient.search(
    "What's a good hotel for people who "
    + "like to read",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive"
            },
            answers: {
                answerType: "extractive"
            }
        },
        select: [
            "HotelName", "Description", "Category"
        ]
    }
);

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

Ключевые выносы:

• answers.answerType: "extractive" позволяет извлекать ответы на поисковые запросы, похожие на вопросы.
• Ответы — это подробный контент, извлеченный из индекса, а не созданный текст.
• results.answers извлекает объекты ответов отдельно от результатов поиска.

В этом кратком руководстве вы используете REST API Поиск с использованием ИИ Azure для добавления семантического ранжирования в существующий индекс поиска и запроса индекса.

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

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно.

• Служба Поиск с использованием ИИ Azure.

• Индекс с описательными текстовыми полями, обозначенными как searchable и retrievable. В этом кратком руководстве предполагается индекс примера отелей.

• Visual Studio Code с расширением клиента REST.

• Git для клонирования примера репозитория.

• Azure CLI для аутентификации без использования ключа с Microsoft Entra ID.

Настройка доступа

Перед началом работы убедитесь, что у вас есть разрешения на доступ к содержимому и операциям в Поиск с использованием ИИ Azure. В этом кратком руководстве используется Microsoft Entra ID для проверки подлинности и доступа на основе ролей для авторизации. Для назначения ролей необходимо быть владельцем или администратором доступа пользователей . Если роли не применимы, используйте проверку подлинности на основе ключей.

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

1. Включите доступ на основе ролей для службы поиска.

2. Назначьте следующие роли учетной записи пользователя.

   • Участник службы поиска

   • Средство чтения индексов поиска

Получение конечной точки

Каждая служба Поиск с использованием ИИ Azure имеет endpoint, который является уникальным URL-адресом, определяющим и предоставляющим сетевой доступ к службе. В следующем разделе описано, как указать эту конечную точку для программного подключения к службе поиска.

Чтобы получить конечную точку, выполните следующие действия.

1. Перейдите в службу поиска на портале Azure.

2. В левой области выберите "Обзор".

3. Запишите конечную точку, которая должна выглядеть следующим https://my-service.search.windows.netобразом.

Начните с индекса

Это краткое руководство изменяет существующий индекс для включения семантической конфигурации. Мы рекомендуем индекс хотелов-пример, который можно создать за считанные минуты, используя мастер портала Azure.

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

Чтобы просмотреть и запросить индекс примера отелей до семантического ранжирования:

1. Перейдите в службу поиска на портале Azure.

2. В левой панели выберите управление поиском>индексы.

3. Выберите hotels-sample.

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

   

5. Выберите обозреватель поиска, а затем выберите Вид>JSON-вид.

6. Вставьте следующий код JSON в редактор запросов.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Выберите "Поиск", чтобы запустить запрос.

   Ответ должен быть похож на следующий пример. Это полнотекстовый запрос, ранжированный по BM25, поэтому результаты соответствуют отдельным условиям запроса и лингвистическим вариантам, а не общему значению запроса. Например, walking совпадает с walk, а live и music сопоставляются независимо, а не как фраза.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "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."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Совет

   В этом запросе показано, как выглядит ответ перед применением семантического ранжирования. После настройки семантической конфигурации добавьте "queryType": "semantic" и "semanticConfiguration": "semantic-config", чтобы увидеть, как один и тот же запрос ранжируется по-разному семантическим ранжированием.

Настройка среды

1. Используйте Git для клонирования примера репозитория.

   git clone https://github.com/Azure-Samples/azure-search-rest-samples
   

2. Перейдите в папку быстрого запуска и откройте ее в Visual Studio Code.

   cd azure-search-rest-samples/Quickstart-semantic-ranking
   code .
   

3. В semantic-index-update.restэтом случае замените значение @searchUrl заполнителя url-адресом, полученным в конечной точке Get.

4. Повторите предыдущий шаг для semantic-query.rest.

5. Для проверки подлинности без ключа с помощью Microsoft Entra ID войдите в учетную запись Azure. Если у вас несколько подписок, выберите тот, который содержит службу Поиск с использованием ИИ Azure.

   az login
   

6. Для проверки подлинности без ключа с помощью Microsoft Entra ID создайте маркер доступа.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

7. В обоих .rest файлах замените значение @personalAccessToken заполнителя маркером из предыдущего шага.

Запуск кода

1. Откройте semantic-index-update.rest.

2. Выберите "Отправить запрос" в первом запросе GET, чтобы проверить подключение.

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

3. Отправьте запрос ### Update the hotels-sample index to include a semantic configuration, чтобы добавить семантическую конфигурацию в индекс.

   При возникновении 400 Bad Request ошибки схема индекса отличается от примера. Отправьте запрос ### Get the schema of the index, скопируйте JSON ответа, добавьте в JSON раздел semantic из исходного кода и замените тело запроса PUT вашей объединённой схемой.

4. semantic-query.rest Переключитесь и отправьте запросы последовательно: простой запрос для сравнения базовых показателей, а затем семантические запросы с ранжированием, заголовками и ответами.

Выход

Запрос Send a search query to the hotels-sample index возвращает результаты, ранжированные по релевантности BM25, которая указывается полем @search.score .

{
  "@odata.count": 30,
  "value": [
    {
      "@search.score": 5.004435,
      "HotelId": "2",
      "HotelName": "Old Century Hotel",
      "Description": "The hotel is situated in a nineteenth century plaza..."
    },
    // Trimmed for brevity
  ]
}

Запрос Send a search query to the hotels-sample index with semantic ranking добавляет @search.rerankerScore. Обратите внимание, что порядок изменяется из простого запроса.

{
  "@odata.count": 30,
  "@search.answers": [],
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown..."
    },
    // Trimmed for brevity
  ]
}

Запрос Return captions in the query добавляет @search.captions с извлеченным текстом и выделениями.

{
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "@search.captions": [
        {
          "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops...",
          "highlights": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops..."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel"
    },
    // Trimmed for brevity
  ]
}

Запрос Return semantic answers in the query возвращает извлекаемый ответ в @search.answers, когда запрос сформулирован как вопрос.

{
  "@odata.count": 46,
  "@search.answers": [
    {
      "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...",
      "highlights": "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<em> library </em>by night...",
      "score": 0.9829999804496765
    }
  ],
  "value": [
    {
      "@search.score": 2.060124,
      "@search.rerankerScore": 2.124817371368408,
      "@search.captions": [
        {
          "text": "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city...",
          "highlights": "This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city..."
        }
      ],
      "HotelId": "1",
      "HotelName": "Stay-Kay City Hotel"
    },
    // Trimmed for brevity
  ]
}

Общие сведения о коде

Теперь, когда вы выполнили код, давайте разберем ключевые шаги:

1. Настройка и проверка подлинности
2. Обновление индекса с помощью семантической конфигурации
3. Запрос индекса

Настройка и проверка подлинности

Оба .rest файла определяют переменные в верхней части для повторного использования во всех запросах.

@searchUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@personalAccessToken = PUT-YOUR-PERSONAL-ACCESS-TOKEN-HERE
@api-version = 2026-04-01

Ключевые выносы:

• @searchUrl — это конечная точка службы поиска.
• @personalAccessToken — это маркер Microsoft Entra ID, полученный из Azure CLI. Это заменяет ключи API безключевой аутентификацией.
• Authorization: Bearer {{personalAccessToken}} включается в каждый заголовок запроса для проверки подлинности.

Обновление индекса с помощью семантической конфигурации

Запрос ### Update the hotels-sample index to include a semantic configuration в semantic-index-update.rest отправляет полную схему индекса вместе с новым разделом semantic. REST API требует полной схемы для любой операции обновления, поэтому вы не можете отправлять только семантику конфигурации.

Ключевое дополнение — это semantic раздел:

"semantic": {
    "configurations": [
        {
            "name": "semantic-config",
            "rankingOrder":
                "BoostedRerankerScore",
            "prioritizedFields": {
                "titleField": {
                    "fieldName": "HotelName"
                },
                "prioritizedContentFields": [
                    {
                        "fieldName": "Description"
                    }
                ],
                "prioritizedKeywordsFields": [
                    {
                        "fieldName": "Tags"
                    }
                ]
            }
        }
    ]
}

Ключевые выносы:

• titleField определяет, какое поле содержит заголовок документа для семантической оценки.
• prioritizedContentFields определяет основные поля содержимого. Семантический рангировщик оценивает эти первые при оценке релевантности.
• prioritizedKeywordsFields определяет поля ключевых слов или тегов для дополнительного контекста.
• rankingOrder: BoostedRerankerScore объединяет оценку BM25 с семантической оценкой повторного ранжирования.
• REST API требует полной схемы для операций PUT. Только раздел semantic является новым; все остальные поля не изменяются.

Выполнить запрос к индексу

Запросы semantic-query.rest переходят от простого поиска ключевых слов к семантическому ранжированию, включая создание заголовков и ответов. Все запросы — POST-запросы к Documents - Search Post (REST API).

Простой запрос

Запрос ### Send a search query to the hotels-sample index — это простой поиск ключевых слов, который не использует семантический ранжирование. Он служит базовым показателем для сравнения результатов с семантической перенастройкой и без неё.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "simple"
}

Ключевые выносы:

• queryType: "simple" использует алгоритм ранжирования по умолчанию BM25.
• Результаты оцениваются только по релевантности ключевых слов (@search.score).

Семантический запрос (без подписей, нет ответов)

Запрос ### Send a search query to the hotels-sample index with semantic ranking добавляет семантический рейтинг. В следующем формате JSON показано минимальное требование для вызова семантического ранжирования.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config"
}

Ключевые выносы:

• queryType: "semantic" включает семантический ранжирование в запросе.
• semanticConfiguration указывает, какую семантику конфигурации следует использовать.

Семантический запрос с заголовками

Запрос ### Return captions in the query добавляет субтитры для извлечения наиболее релевантных фрагментов из каждого результата, с выделением совпадений, применяемым к важным терминам и фразам.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true"
}

Ключевые выносы:

• captions: "extractive|highlight-true" активирует экстрактивные подписи с <em> тегами вокруг важных терминов.
• Заголовки отображаются в массиве @search.captions для каждого результата.

Семантический запрос с ответами

Запрос ### Return semantic answers in the query добавляет семантические ответы. Он использует вопрос в качестве текста поиска, так как семантические ответы лучше всего работают, когда запрос фразируется как вопрос. Ответ представляет собой дословный отрывок, извлеченный из вашего индекса, а не сгенерированный ответ модели завершения чата.

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

{
    "search":
        "what's a good hotel for people who like to read",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true",
    "answers": "extractive"
}

Ключевые выносы:

• answers: "extractive" позволяет извлекать ответы на поисковые запросы, похожие на вопросы.
• Ответы отображаются в массиве верхнего уровня @search.answers , отдельно от отдельных результатов.
• Ответы — это подробный контент, извлеченный из индекса, а не созданный текст.