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

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

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

Предварительные условия

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

• Служба поиска Azure AI с включенным семантическим ранжировщиком.

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

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

• Git, чтобы клонировать тестовый репозиторий.

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

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

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

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

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

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

   • Вкладчик Поисковой Службы

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

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

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

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

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

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

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

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

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

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

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

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

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

3. Выберите пример отелей.

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

   

5. Выберите Search explorer и затем выберите Просмотр>в формате JSON.

6. Вставьте следующий код JSON в query editor.

   {
     "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 endpoint.

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

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

   az login
   

Запустите код

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

   dotnet run --project BuildIndex
   

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

   dotnet run --project QueryIndex
   

Выходные данные

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

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 обрабатывает операции на уровне документа, такие как запрос индекса.

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

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

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 project выполняет четыре запроса в последовательности, переходя от простого поиска ключевых слов к семантическому ранжированию, включая заголовки и ответы.

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

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

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 AI Search для Java для добавления семантического ранжирования в существующий индекс поиска и выполнения запросов к индексу.

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

Предварительные условия

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

• Служба поиска Azure AI с включенным семантическим ранжировщиком.

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

• Java 21 (LTS) и Maven.

• Git, чтобы клонировать тестовый репозиторий.

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

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

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

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

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

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

   • Вкладчик Поисковой Службы

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

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

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

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

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

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

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

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

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

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

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

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

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

3. Выберите пример отелей.

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

   

5. Выберите Search explorer и затем выберите Просмотр>в формате JSON.

6. Вставьте следующий код JSON в query editor.

   {
     "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 endpoint.

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

   mvn compile
   

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

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

   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) являются общими для всех классов в project.

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

Класс 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 отправляет обновленную схему в search service без перестроения индекса или удаления документов.

Запрос индекса

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

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

Первый запрос добавляет семантический рейтинг без подписей или ответов. Класс 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 AI Search для JavaScript для добавления семантического ранжирования в существующий индекс поиска и запроса индекса.

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

Предварительные условия

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

• Служба поиска Azure AI с включенным семантическим ранжировщиком.

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

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

• Git, чтобы клонировать тестовый репозиторий.

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

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

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

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

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

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

   • Вкладчик Поисковой Службы

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

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

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

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

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

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

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

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

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

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

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

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

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

3. Выберите пример отелей.

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

   

5. Выберите Search explorer и затем выберите Просмотр>в формате JSON.

6. Вставьте следующий код JSON в query editor.

   {
     "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 endpoint.

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

   mv sample.env .env
   

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

   npm install
   

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

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

   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 отправляет обновленную схему в search service без перестроения индекса или удаления документов.

Запрос индекса

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

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

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

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 AI Search для Python, чтобы добавить семантическое ранжирование в существующий индекс поиска и выполнять запросы к индексу.

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

Предварительные условия

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

• Служба поиска Azure AI с включенным семантическим ранжировщиком.

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

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

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

• Git, чтобы клонировать тестовый репозиторий.

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

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

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

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

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

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

   • Вкладчик Поисковой Службы

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

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

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

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

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

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

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

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

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

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

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

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

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

3. Выберите пример отелей.

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

   

5. Выберите Search explorer и затем выберите Просмотр>в формате JSON.

6. Вставьте следующий код JSON в query editor.

   {
     "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 endpoint.

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

   mv sample.env .env
   

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

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

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

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

   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 отправляет обновленную схему в search service без перестроения индекса или удаления документов.

Запрос индекса

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

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

Ячейка 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 AI Search для JavaScript (совместимую с TypeScript), чтобы добавить семантическое ранжирование в существующий индекс поиска и выполнять запросы к индексу.

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

Предварительные условия

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

• Служба поиска Azure AI с включенным семантическим ранжировщиком.

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

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

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

• Git, чтобы клонировать тестовый репозиторий.

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

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

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

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

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

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

   • Вкладчик Поисковой Службы

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

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

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

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

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

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

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

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

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

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

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

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

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

3. Выберите пример отелей.

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

   

5. Выберите Search explorer и затем выберите Просмотр>в формате JSON.

6. Вставьте следующий код JSON в query editor.

   {
     "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 endpoint.

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

   mv sample.env .env
   

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

   npm install
   

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

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

   npm run build
   

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

   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 отправляет обновленную схему в search service без перестроения индекса или удаления документов.

Запрос индекса

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

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

Сценарий 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 AI Search для добавления семантического ранжирования в существующий индекс поиска и выполнения запросов к этому индексу.

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

Предварительные условия

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

• Служба поиска Azure AI с включенным семантическим ранжировщиком.

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

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

• Git, чтобы клонировать тестовый репозиторий.

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

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

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

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

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

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

   • Вкладчик Поисковой Службы

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

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

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

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

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

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

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

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

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

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

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

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

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

3. Выберите пример отелей.

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

   

5. Выберите Search explorer и затем выберите Просмотр>в формате JSON.

6. Вставьте следующий код JSON в query editor.

   {
     "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 endpoint.

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

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

   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 ответа, добавьте semantic раздел из исходного кода в JSON и замените тело 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 = 2025-09-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 , отдельно от отдельных результатов.
• Ответы — это подробный контент, извлеченный из индекса, а не созданный текст.