Szybki start: klasyfikacja semantyczna

W tym szybkim przewodniku użyjesz biblioteki klienta Wyszukiwanie AI platformy Azure dla .NET, aby dodać semantyczne pozycjonowanie do istniejącego indeksu wyszukiwania i wykonywanie zapytań na indeksie.

Ranking semantyczny to funkcjonalność po stronie zapytania, która używa maszynowego zrozumienia tekstu do przeskalowania wyników wyszukiwania, promując najbardziej semantycznie istotne dopasowania na początku listy. Możesz dodać konfigurację semantyczną do istniejącego indeksu bez konieczności ponownego kompilowania. Klasyfikacja semantyczna jest najbardziej skuteczna w przypadku tekstu informacyjnego lub opisowego.

Wymagania wstępne

• Konto Azure z aktywną subskrypcją. Utwórz bezpłatne konto.

• Usługa Wyszukiwanie AI platformy Azure.

• Indeks z opisowymi polami tekstowymi przypisanymi jako searchable i retrievable. Przyjmuje się, że w tym szybkim starcie używany jest indeks hotels-sample.

• .NET 9 lub nowszy.

• Narzędzie Git do sklonowania przykładowego repozytorium.

• Azure CLI na potrzeby uwierzytelniania bez klucza za pomocą Microsoft Entra ID.

Konfigurowanie dostępu

Przed rozpoczęciem upewnij się, że masz uprawnienia dostępu do zawartości i operacji w Wyszukiwanie AI platformy Azure. W tym przewodniku szybkiego startu użyto Microsoft Entra ID do uwierzytelniania oraz dostępu opartego na rolach w celu autoryzacji. Aby przypisać role, musisz być właścicielem lub administratorem dostępu użytkowników . Jeśli role nie są możliwe, zamiast tego użyj uwierzytelniania opartego na kluczach .

Aby skonfigurować zalecany dostęp oparty na rolach:

1. Włącz dostęp oparty na rolach dla usługi wyszukiwania.

2. Przypisz następujące role do konta użytkownika.

   • Współautor usługi wyszukiwania

   • Czytnik danych indeksu wyszukiwania

Pobierz punkt końcowy

Każda usługa Wyszukiwanie AI platformy Azure ma endpoint, który jest unikatowym adresem URL, który identyfikuje i zapewnia dostęp sieciowy do usługi. W późniejszej sekcji określisz ten punkt końcowy, aby programowo nawiązać połączenie z usługą wyszukiwania.

Aby uzyskać punkt końcowy:

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. W okienku po lewej stronie wybierz pozycję Przegląd.

3. Zanotuj punkt końcowy, który powinien wyglądać następująco: https://my-service.search.windows.net.

Rozpoczynanie od indeksu

Ten przewodnik modyfikuje istniejący indeks, aby uwzględnić konfigurację semantyczną. Zalecamy indeks hotels-sample, który można utworzyć w ciągu kilku minut za pomocą kreatora portalu Azure.

Aby użyć innego indeksu, zastąp nazwę indeksu, nazwy pól w konfiguracji semantycznej i nazwy pól w instrukcjach zapytania select w całym przykładowym kodzie. Indeks powinien zawierać opisowe pola tekstowe, które są przypisywane jako searchable i retrievable.

Aby przejrzeć i wysłać zapytanie do indeksu hotels-sample przed klasyfikacją semantyczną:

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. Na panelu po lewej stronie wybierz Zarządzanie wyszukiwaniem>Indeksy.

3. Wybierz hotels-sample.

4. Wybierz pozycję Konfiguracje semantyczne , aby wyświetlić wszystkie istniejące konfiguracje. Jeśli podczas procesu tworzenia kreatora włączono klasyfikację semantyczną, powinna istnieć konfiguracja domyślna.

   

5. Wybierz pozycję Eksplorator wyszukiwania, a następnie wybierz pozycję Wyświetl>widok JSON.

6. Wklej następujący kod JSON do edytora zapytań.

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

7. Wybierz pozycję Wyszukaj , aby uruchomić zapytanie.

   Odpowiedź powinna być podobna do poniższego przykładu. Jest to zapytanie pełnotekstowe sklasyfikowane przez BM25, więc wyniki są zgodne z poszczególnymi terminami zapytania i wariantami językowymi, a nie ogólnym znaczeniem zapytania. Na przykład walking i walk dopasowują się, a live i music dopasowują się niezależnie, zamiast jako frazę.

   "@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
   ]
   

   Wskazówka

   To zapytanie pokazuje, jak wygląda odpowiedź przed zastosowaniem klasyfikacji semantycznej. Po skonfigurowaniu konfiguracji semantycznej dodaj "queryType": "semantic" i "semanticConfiguration": "semantic-config" , aby zobaczyć, jak to samo zapytanie jest klasyfikowane inaczej według klasyfikacji semantycznej.

Konfigurowanie środowiska

1. Użyj narzędzia Git, aby sklonować przykładowe repozytorium.

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

2. Przejdź do folderu Szybki start.

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

3. W BuildIndex/Program.cs zastąp wartość endpoint symbolu zastępczego adresem URL uzyskanym w Uzyskiwanie punktu końcowego.

4. Powtórz poprzedni krok dla QueryIndex/Program.cselementu .

5. W przypadku uwierzytelniania bez klucza przy użyciu Microsoft Entra ID zaloguj się do konta Azure. Jeśli masz wiele subskrypcji, wybierz tę, która zawiera usługę Wyszukiwanie AI platformy Azure.

   az login
   

Uruchamianie kodu

1. Uruchom pierwszy projekt, aby zaktualizować indeks przy użyciu konfiguracji semantycznej.

   dotnet run --project BuildIndex
   

2. Uruchom drugi projekt, aby wykonać zapytanie dotyczące indeksu. Naciśnij klawisz Enter między zapytaniami, aby zobaczyć postęp od prostego zapytania do semantycznego zapytania z podpisami i odpowiedziami.

   dotnet run --project QueryIndex
   

Wyjście

Pierwszy projekt aktualizuje indeks hotels-sample z konfiguracją semantyczną. Dane wyjściowe zawierają potwierdzenie konfiguracji semantycznej.

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": {}
      }
    ]
  }
}

Drugi projekt wykonuje cztery zapytania. Dane wyjściowe zawierają wyniki wyszukiwania z ocenami trafności, podpisami i odpowiedziami.

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

Omówienie kodu

Teraz, po uruchomieniu kodu, podzielmy kluczowe kroki:

1. Konfiguracja i uwierzytelnianie
2. Aktualizowanie indeksu przy użyciu konfiguracji semantycznej
3. Wykonywanie zapytań względem indeksu

Konfiguracja i uwierzytelnianie

Oba projekty mają ten sam wzorzec konfiguracji. Pliki Program.cs definiują punkt końcowy wyszukiwania i wykorzystują DefaultAzureCredential do uwierzytelniania bez klucza.

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

Najważniejsze wnioski:

• DefaultAzureCredential zapewnia uwierzytelnianie bez klucza przy użyciu Microsoft Entra ID. Łączy wiele typów poświadczeń, w tym poświadczenie Azure CLI z az login.
• SearchIndexClient zarządza operacjami na poziomie indeksu, takimi jak aktualizowanie schematu indeksu.
• SearchClient obsługuje operacje na poziomie dokumentu, takie jak wykonywanie zapytań względem indeksu.

Aktualizowanie indeksu przy użyciu konfiguracji semantycznej

Poniższy kod w pliku BuildIndex/Program.cs dodaje konfigurację semantyczną do istniejącego indeksu. Ta operacja nie usuwa żadnych dokumentów wyszukiwania, a indeks pozostaje operacyjny po dodaniu konfiguracji.

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;
}

Najważniejsze wnioski:

• Konfiguracja semantyczna określa pola używane do klasyfikacji semantycznej.
• Konfiguracje semantyczne można dodać do istniejących indeksów bez ponownego kompilowania.
• TitleField Ustawia pole reprezentujące tytuł dokumentu.
• ContentFields Ustawia pola zawierające zawartość główną.
• KeywordsFields Ustawia pola zawierające słowa kluczowe lub tagi.

Wykonywanie zapytań względem indeksu

Projekt QueryIndex uruchamia cztery zapytania w sekwencji, przechodząc od prostego wyszukiwania słów kluczowych do semantycznego rankingowania wraz z podpisami i odpowiedziami.

Proste zapytanie

Pierwsze zapytanie to proste wyszukiwanie słów kluczowych, które nie używa klasyfikacji semantycznej. To zapytanie służy jako punkt odniesienia do porównywania wyników z i bez semantycznego ponownego korbowania.

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

Najważniejsze wnioski:

• SearchQueryType.Simple używa domyślnego algorytmu klasyfikacji BM25.
• Wyniki są klasyfikowane tylko według istotności słowa kluczowego (@search.score).

Zapytanie semantyczne (brak podpisów, brak odpowiedzi)

Następne zapytanie dodaje semantyczną klasyfikację bez podpisów ani odpowiedzi. Poniższy kod przedstawia minimalne wymaganie dotyczące wywoływania klasyfikacji semantycznej.

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);

Najważniejsze wnioski:

• SearchQueryType.Semantic umożliwia semantyczne klasyfikowanie w zapytaniu.
• SemanticConfigurationName określa, która konfiguracja semantyczna ma być używana.
• @search.rerankerScore wskazuje istotność semantyczną (wyższa jest lepsza).
• Początkowe wyniki zapytania są ponownie oceniane przy użyciu semantycznych modeli rankingowych. W przypadku tego zestawu danych i zapytania efekty klasyfikacji semantycznej są bardziej widoczne w wynikach o niższej klasyfikacji.

Semantyczne zapytanie z podpisami

Poniższy kod dodaje etykiety w celu wyodrębnienia najbardziej odpowiednich fragmentów z każdego wyniku, z podkreśleniem ważnych terminów i fraz.

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
);

Najważniejsze wnioski:

• QueryCaption umożliwia wyodrębnianie podpisów z pól zawartości.
• Podpisy wyświetlają najbardziej odpowiednie fragmenty i dodają <em> tagi wokół ważnych terminów.

Semantyczne zapytanie z odpowiedziami

Ostatnie zapytanie dodaje semantyczne odpowiedzi. To zapytanie używa innego ciągu wyszukiwania (searchText2), ponieważ odpowiedzi semantyczne działają najlepiej, gdy zapytanie jest frazowane jako pytanie. Odpowiedź to fragment dosłowny wyodrębniony z indeksu, a nie stworzona odpowiedź z modelu generowania czatu.

Zapytanie i indeksowana zawartość muszą być ściśle dopasowane, aby odpowiedź została zwrócona. Jeśli żaden kandydat nie spełnia progu ufności, odpowiedź nie zawiera odpowiedzi. W tym przykładzie użyto pytania, o którym wiadomo, że generuje wynik, aby zobaczyć składnię. Jeśli odpowiedzi nie są przydatne w Twoim przypadku, pomiń QueryAnswer z kodu. W przypadku złożonych odpowiedzi należy wziąć pod uwagę wzorzec RAG lub agentowe pobieranie.

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
);

Najważniejsze wnioski:

• QueryAnswer umożliwia wyodrębnianie odpowiedzi na zapytania pytaniopodobne.
• Odpowiedzi to zawartość dosłowna wyodrębniona z indeksu, a nie tekst wygenerowany.

W tym przewodniku użyjesz biblioteki klienta Wyszukiwanie AI platformy Azure dla Javy, aby dodać semantyczny ranking do istniejącego indeksu wyszukiwania oraz odpytywać indeks.

Ranking semantyczny to funkcjonalność po stronie zapytania, która używa maszynowego zrozumienia tekstu do przeskalowania wyników wyszukiwania, promując najbardziej semantycznie istotne dopasowania na początku listy. Możesz dodać konfigurację semantyczną do istniejącego indeksu bez konieczności ponownego kompilowania. Klasyfikacja semantyczna jest najbardziej skuteczna w przypadku tekstu informacyjnego lub opisowego.

Wymagania wstępne

• Konto Azure z aktywną subskrypcją. Utwórz bezpłatne konto.

• Usługa Wyszukiwanie AI platformy Azure.

• Indeks z opisowymi polami tekstowymi przypisanymi jako searchable i retrievable. Przyjmuje się, że w tym szybkim starcie używany jest indeks hotels-sample.

• Java 21 (LTS) i Maven.

• Narzędzie Git do sklonowania przykładowego repozytorium.

• Azure CLI na potrzeby uwierzytelniania bez klucza za pomocą Microsoft Entra ID.

Konfigurowanie dostępu

Przed rozpoczęciem upewnij się, że masz uprawnienia dostępu do zawartości i operacji w Wyszukiwanie AI platformy Azure. W tym przewodniku szybkiego startu użyto Microsoft Entra ID do uwierzytelniania oraz dostępu opartego na rolach w celu autoryzacji. Aby przypisać role, musisz być właścicielem lub administratorem dostępu użytkowników . Jeśli role nie są możliwe, zamiast tego użyj uwierzytelniania opartego na kluczach .

Aby skonfigurować zalecany dostęp oparty na rolach:

1. Włącz dostęp oparty na rolach dla usługi wyszukiwania.

2. Przypisz następujące role do konta użytkownika.

   • Współautor usługi wyszukiwania

   • Czytnik danych indeksu wyszukiwania

Pobierz punkt końcowy

Każda usługa Wyszukiwanie AI platformy Azure ma endpoint, który jest unikatowym adresem URL, który identyfikuje i zapewnia dostęp sieciowy do usługi. W późniejszej sekcji określisz ten punkt końcowy, aby programowo nawiązać połączenie z usługą wyszukiwania.

Aby uzyskać punkt końcowy:

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. W okienku po lewej stronie wybierz pozycję Przegląd.

3. Zanotuj punkt końcowy, który powinien wyglądać następująco: https://my-service.search.windows.net.

Rozpoczynanie od indeksu

Ten przewodnik modyfikuje istniejący indeks, aby uwzględnić konfigurację semantyczną. Zalecamy indeks hotels-sample, który można utworzyć w ciągu kilku minut za pomocą kreatora portalu Azure.

Aby użyć innego indeksu, zastąp nazwę indeksu, nazwy pól w konfiguracji semantycznej i nazwy pól w instrukcjach zapytania select w całym przykładowym kodzie. Indeks powinien zawierać opisowe pola tekstowe, które są przypisywane jako searchable i retrievable.

Aby przejrzeć i wysłać zapytanie do indeksu hotels-sample przed klasyfikacją semantyczną:

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. Na panelu po lewej stronie wybierz Zarządzanie wyszukiwaniem>Indeksy.

3. Wybierz hotels-sample.

4. Wybierz pozycję Konfiguracje semantyczne , aby wyświetlić wszystkie istniejące konfiguracje. Jeśli podczas procesu tworzenia kreatora włączono klasyfikację semantyczną, powinna istnieć konfiguracja domyślna.

   

5. Wybierz pozycję Eksplorator wyszukiwania, a następnie wybierz pozycję Wyświetl>widok JSON.

6. Wklej następujący kod JSON do edytora zapytań.

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

7. Wybierz pozycję Wyszukaj , aby uruchomić zapytanie.

   Odpowiedź powinna być podobna do poniższego przykładu. Jest to zapytanie pełnotekstowe sklasyfikowane przez BM25, więc wyniki są zgodne z poszczególnymi terminami zapytania i wariantami językowymi, a nie ogólnym znaczeniem zapytania. Na przykład walking i walk dopasowują się, a live i music dopasowują się niezależnie, zamiast jako frazę.

   "@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
   ]
   

   Wskazówka

   To zapytanie pokazuje, jak wygląda odpowiedź przed zastosowaniem klasyfikacji semantycznej. Po skonfigurowaniu konfiguracji semantycznej dodaj "queryType": "semantic" i "semanticConfiguration": "semantic-config" , aby zobaczyć, jak to samo zapytanie jest klasyfikowane inaczej według klasyfikacji semantycznej.

Konfigurowanie środowiska

1. Użyj narzędzia Git, aby sklonować przykładowe repozytorium.

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

2. Przejdź do folderu Szybki start.

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

3. W src/main/resources/application.properties zastąp wartość azure.search.endpoint symbolu zastępczego adresem URL uzyskanym w Uzyskiwanie punktu końcowego.

4. Skompiluj projekt w celu rozwiązania zależności, w tym azure-search-documents.

   mvn compile
   

   Po zakończeniu kompilacji sprawdź, czy w danych wyjściowych nie są wyświetlane żadne błędy.

5. W przypadku uwierzytelniania bez klucza przy użyciu Microsoft Entra ID zaloguj się do konta Azure. Jeśli masz wiele subskrypcji, wybierz tę, która zawiera usługę Wyszukiwanie AI platformy Azure.

   az login
   

Uruchamianie kodu

1. Pobierz istniejące ustawienia indeksu.

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

2. Zaktualizuj indeks przy użyciu konfiguracji semantycznej.

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

3. Uruchom zapytanie semantyczne.

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

4. Uruchom semantyczne zapytanie z podpisami.

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

5. Uruchom semantyczne zapytanie z odpowiedziami.

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

Wyjście

Dane wyjściowe GetIndexSettings.java to nazwa indeksu, jego pola i konfiguracje semantyczne. Przed dodaniem nowej konfiguracji indeks ma tylko domyślną.

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

Dane wyjściowe UpdateIndexSettings.java wymieniają wszystkie konfiguracje semantyczne w indeksie, w tym tę dodaną przez kod, a następnie wyświetlany jest komunikat o powodzeniu.

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

Wynik działania SemanticQuery.java zwraca wszystkie pasujące dokumenty uporządkowane według wyniku ponownego rankingowania semantycznego.

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

Dane wyjściowe SemanticQueryWithCaptions.java dodaje element podpisu z wyróżnionym trafieniem obok pól wyszukiwania. Podpisy są najbardziej odpowiednimi fragmentami w wyniku wyszukiwania. Jeśli indeks zawiera większy tekst, napisy ułatwiają wyodrębnianie najbardziej interesujących zdań.

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

Dane wyjściowe funkcji SemanticAnswer.java zawierają semantyczną odpowiedź pobraną z jednego z wyników, które najlepiej pasują do pytania, a następnie wyniki wyszukiwania z podpisami.

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

Omówienie kodu

Teraz, po uruchomieniu kodu, podzielmy kluczowe kroki:

1. Konfiguracja i uwierzytelnianie
2. Aktualizowanie indeksu przy użyciu konfiguracji semantycznej
3. Wykonywanie zapytań względem indeksu

Konfiguracja i uwierzytelnianie

Klasa SearchConfig.java ładuje właściwości z application.properties i tworzy DefaultAzureCredential do uwierzytelniania bez klucza.

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();
}

Najważniejsze wnioski:

• DefaultAzureCredential zapewnia uwierzytelnianie bez klucza przy użyciu Microsoft Entra ID. Łączy wiele typów poświadczeń, w tym poświadczenie Azure CLI z az login.
• Właściwości są ładowane z pliku application.properties w ścieżce classpath.
• Pola statyczne (SEARCH_ENDPOINT, INDEX_NAME, , SEMANTIC_CONFIG_NAMECREDENTIAL) są współużytkowane we wszystkich klasach w projekcie.

Aktualizowanie indeksu przy użyciu konfiguracji semantycznej

Klasa UpdateIndexSettings.java dodaje konfigurację semantyczną do istniejącego hotels-sample indeksu. Ta operacja nie usuwa żadnych dokumentów wyszukiwania, a indeks pozostaje operacyjny po dodaniu konfiguracji.

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);

Najważniejsze wnioski:

• SemanticPrioritizedFields określa, które pola ocenia semantyczny rangier. setTitleField Ustawia tytuł dokumentu, setContentFields ustawia główną zawartość i setKeywordsFields ustawia pola słowa kluczowego lub tagu.
• SemanticConfiguration paruje nazwę z polami priorytetowymi, identyfikując konfigurację semantyczną do użycia w czasie zapytania.
• createOrUpdateIndex Wypycha zaktualizowany schemat do usługi wyszukiwania bez ponownego kompilowania indeksu lub usuwania dokumentów.

Wykonywanie zapytań względem indeksu

Następujące trzy klasy wysyłają zapytanie do indeksu po kolei, przechodząc od podstawowego wyszukiwania semantycznego do semantycznego rankingu z podpisami i odpowiedziami.

Zapytanie semantyczne (brak podpisów, brak odpowiedzi)

Pierwsze zapytanie dodaje semantyczną klasyfikację bez podpisów ani odpowiedzi. Klasa SemanticQuery.java pokazuje minimalne wymaganie dotyczące wywoływania klasyfikacji semantycznej.

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"));
}

Najważniejsze wnioski:

• QueryType.SEMANTIC umożliwia semantyczne klasyfikowanie w zapytaniu.
• setSemanticConfigurationName określa, która konfiguracja semantyczna ma być używana.
• SearchPagedIterable zapewnia iterable dla wyników ponownie sklasyfikowanych. Każdy SearchResult zawiera getSemanticSearch() akcesor dla wyniku rerankera.

Semantyczne zapytanie z podpisami

Klasa SemanticQueryWithCaptions.java dodaje podpisy, aby wyodrębnić najbardziej odpowiednie fragmenty z każdego wyniku, z podświetleniem zastosowanym do istotnych terminów i fraz.

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());
        }
    }
}

Najważniejsze wnioski:

• QueryCaption(QueryCaptionType.EXTRACTIVE) umożliwia wyodrębnianie podpisów z pól zawartości.
• setHighlightEnabled(true) dodaje <em> tagi wokół ważnych terminów w podpisach.
• Każde SearchResult zapewnia getQueryCaptions() do wyszukiwania semantycznego.

Semantyczne zapytanie z odpowiedziami

Klasa SemanticAnswer.java dodaje semantyczne odpowiedzi. Ta klasa używa pytania jako tekstu wyszukiwania, ponieważ semantyczne odpowiedzi działają najlepiej, gdy zapytanie jest frazowane jako pytanie. Odpowiedź to fragment dosłowny wyodrębniony z indeksu, a nie stworzona odpowiedź z modelu generowania czatu.

Zapytanie i indeksowana zawartość muszą być ściśle dopasowane, aby odpowiedź została zwrócona. Jeśli żaden kandydat nie spełnia progu ufności, odpowiedź nie zawiera odpowiedzi. W tym przykładzie użyto pytania, o którym wiadomo, że generuje wynik, aby zobaczyć składnię. Jeśli odpowiedzi nie są przydatne w Twoim przypadku, pomiń setQueryAnswer z kodu. W przypadku złożonych odpowiedzi należy wziąć pod uwagę wzorzec RAG lub agentowe pobieranie.

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());
}

Najważniejsze wnioski:

• QueryAnswer(QueryAnswerType.EXTRACTIVE) umożliwia wyodrębnianie odpowiedzi na zapytania pytaniopodobne.
• Odpowiedzi to zawartość dosłowna wyodrębniona z indeksu, a nie tekst wygenerowany.
• results.getSemanticResults().getQueryAnswers() pobiera obiekty odpowiedzi oddzielnie od wyników wyszukiwania.

W tym przewodniku szybkiego startu użyjesz biblioteki klienta Wyszukiwanie AI platformy Azure dla języka JavaScript, aby dodać semantyczny ranking do istniejącego indeksu wyszukiwania i dokonywać zapytań do indeksu.

Ranking semantyczny to funkcjonalność po stronie zapytania, która używa maszynowego zrozumienia tekstu do przeskalowania wyników wyszukiwania, promując najbardziej semantycznie istotne dopasowania na początku listy. Możesz dodać konfigurację semantyczną do istniejącego indeksu bez konieczności ponownego kompilowania. Klasyfikacja semantyczna jest najbardziej skuteczna w przypadku tekstu informacyjnego lub opisowego.

Wymagania wstępne

• Konto Azure z aktywną subskrypcją. Utwórz bezpłatne konto.

• Usługa Wyszukiwanie AI platformy Azure.

• Indeks z opisowymi polami tekstowymi przypisanymi jako searchable i retrievable. Przyjmuje się, że w tym szybkim starcie używany jest indeks hotels-sample.

• Node.js 20 LTS lub nowszym.

• Narzędzie Git do sklonowania przykładowego repozytorium.

• Azure CLI na potrzeby uwierzytelniania bez klucza za pomocą Microsoft Entra ID.

Konfigurowanie dostępu

Przed rozpoczęciem upewnij się, że masz uprawnienia dostępu do zawartości i operacji w Wyszukiwanie AI platformy Azure. W tym przewodniku szybkiego startu użyto Microsoft Entra ID do uwierzytelniania oraz dostępu opartego na rolach w celu autoryzacji. Aby przypisać role, musisz być właścicielem lub administratorem dostępu użytkowników . Jeśli role nie są możliwe, zamiast tego użyj uwierzytelniania opartego na kluczach .

Aby skonfigurować zalecany dostęp oparty na rolach:

1. Włącz dostęp oparty na rolach dla usługi wyszukiwania.

2. Przypisz następujące role do konta użytkownika.

   • Współautor usługi wyszukiwania

   • Czytnik danych indeksu wyszukiwania

Pobierz punkt końcowy

Każda usługa Wyszukiwanie AI platformy Azure ma endpoint, który jest unikatowym adresem URL, który identyfikuje i zapewnia dostęp sieciowy do usługi. W późniejszej sekcji określisz ten punkt końcowy, aby programowo nawiązać połączenie z usługą wyszukiwania.

Aby uzyskać punkt końcowy:

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. W okienku po lewej stronie wybierz pozycję Przegląd.

3. Zanotuj punkt końcowy, który powinien wyglądać następująco: https://my-service.search.windows.net.

Rozpoczynanie od indeksu

Ten przewodnik modyfikuje istniejący indeks, aby uwzględnić konfigurację semantyczną. Zalecamy indeks hotels-sample, który można utworzyć w ciągu kilku minut za pomocą kreatora portalu Azure.

Aby użyć innego indeksu, zastąp nazwę indeksu, nazwy pól w konfiguracji semantycznej i nazwy pól w instrukcjach zapytania select w całym przykładowym kodzie. Indeks powinien zawierać opisowe pola tekstowe, które są przypisywane jako searchable i retrievable.

Aby przejrzeć i wysłać zapytanie do indeksu hotels-sample przed klasyfikacją semantyczną:

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. Na panelu po lewej stronie wybierz Zarządzanie wyszukiwaniem>Indeksy.

3. Wybierz hotels-sample.

4. Wybierz pozycję Konfiguracje semantyczne , aby wyświetlić wszystkie istniejące konfiguracje. Jeśli podczas procesu tworzenia kreatora włączono klasyfikację semantyczną, powinna istnieć konfiguracja domyślna.

   

5. Wybierz pozycję Eksplorator wyszukiwania, a następnie wybierz pozycję Wyświetl>widok JSON.

6. Wklej następujący kod JSON do edytora zapytań.

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

7. Wybierz pozycję Wyszukaj , aby uruchomić zapytanie.

   Odpowiedź powinna być podobna do poniższego przykładu. Jest to zapytanie pełnotekstowe sklasyfikowane przez BM25, więc wyniki są zgodne z poszczególnymi terminami zapytania i wariantami językowymi, a nie ogólnym znaczeniem zapytania. Na przykład walking i walk dopasowują się, a live i music dopasowują się niezależnie, zamiast jako frazę.

   "@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
   ]
   

   Wskazówka

   To zapytanie pokazuje, jak wygląda odpowiedź przed zastosowaniem klasyfikacji semantycznej. Po skonfigurowaniu konfiguracji semantycznej dodaj "queryType": "semantic" i "semanticConfiguration": "semantic-config" , aby zobaczyć, jak to samo zapytanie jest klasyfikowane inaczej według klasyfikacji semantycznej.

Konfigurowanie środowiska

1. Użyj narzędzia Git, aby sklonować przykładowe repozytorium.

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

2. Przejdź do folderu Szybki start.

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

3. W sample.env zastąp wartość AZURE_SEARCH_ENDPOINT symbolu zastępczego adresem URL uzyskanym w Uzyskiwanie punktu końcowego.

4. Zmień nazwę sample.env na .env.

   mv sample.env .env
   

5. Zainstaluj zależności.

   npm install
   

   Po zakończeniu instalacji powinien zostać wyświetlony node_modules folder w katalogu projektu.

6. W przypadku uwierzytelniania bez klucza przy użyciu Microsoft Entra ID zaloguj się do konta Azure. Jeśli masz wiele subskrypcji, wybierz tę, która zawiera usługę Wyszukiwanie AI platformy Azure.

   az login
   

Uruchamianie kodu

1. Pobierz istniejące ustawienia indeksu.

   node -r dotenv/config src/getIndexSettings.js
   

2. Zaktualizuj indeks przy użyciu konfiguracji semantycznej.

   node -r dotenv/config src/updateIndexSettings.js
   

3. Uruchom zapytanie semantyczne.

   node -r dotenv/config src/semanticQuery.js
   

4. Uruchom semantyczne zapytanie z podpisami.

   node -r dotenv/config src/semanticQueryReturnCaptions.js
   

5. Uruchom semantyczne zapytanie z odpowiedziami.

   node -r dotenv/config src/semanticAnswer.js
   

Wyjście

Skrypt getIndexSettings.js zwraca nazwę indeksu, jego pola i wszelkie istniejące konfiguracje semantyczne.

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

Skrypt updateIndexSettings.js zwraca wszystkie konfiguracje semantyczne w indeksie, w tym tę dodaną przez kod, a następnie wyświetla komunikat o powodzeniu.

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.

Skrypt semanticQuery.js zwraca wszystkie pasujące dokumenty uporządkowane według wyniku ponownego rangowania semantycznego.

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

Skrypt semanticQueryReturnCaptions.js zwraca element podpisu z wyróżnieniem trafień obok pól wyszukiwania. Podpisy są najbardziej odpowiednimi fragmentami w wyniku wyszukiwania. Jeśli indeks zawiera większy tekst, napisy ułatwiają wyodrębnianie najbardziej interesujących zdań.

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

Skrypt semanticAnswer.js zwraca semantyczną odpowiedź pobraną z jednego z wyników, które najlepiej pasują do pytania, a następnie wyniki wyszukiwania z podpisami.

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

Omówienie kodu

Teraz, po uruchomieniu kodu, podzielmy kluczowe kroki:

1. Konfiguracja i uwierzytelnianie
2. Aktualizowanie indeksu przy użyciu konfiguracji semantycznej
3. Wykonywanie zapytań względem indeksu

Konfiguracja i uwierzytelnianie

Plik config.js ładuje zmienne środowiskowe i tworzy element DefaultAzureCredential na potrzeby uwierzytelniania.

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();

Najważniejsze wnioski:

• DefaultAzureCredential zapewnia uwierzytelnianie bez klucza przy użyciu Microsoft Entra ID. Łączy wiele typów poświadczeń, w tym poświadczenie Azure CLI z az login.
• Zmienne środowiskowe są ładowane z .env pliku przy użyciu dotenv.

Aktualizowanie indeksu przy użyciu konfiguracji semantycznej

Plik updateIndexSettings.js dodaje konfigurację semantyczną do istniejącego hotels-sample indeksu. Ta operacja nie usuwa żadnych dokumentów wyszukiwania, a indeks pozostaje operacyjny po dodaniu konfiguracji.

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);

Najważniejsze wnioski:

• Konfiguracja semantyczna określa pola używane do klasyfikacji semantycznej. titleField definiuje tytuł dokumentu, contentFields definiuje główną zawartość i keywordsFields definiuje pola słowa kluczowego lub tagu.
• Utworzysz obiekt konfiguracji i wypchniesz go do tablicy istniejącego indeksu semanticSearch.configurations .
• createOrUpdateIndex Wypycha zaktualizowany schemat do usługi wyszukiwania bez ponownego kompilowania indeksu lub usuwania dokumentów.

Wykonywanie zapytań względem indeksu

Skrypty zapytań uruchamiają trzy zapytania w sekwencji, zaczynając od podstawowego wyszukiwania semantycznego aż do semantycznej klasyfikacji z odpowiedziami i podpisami.

Zapytanie semantyczne (brak podpisów, brak odpowiedzi)

Poniższy kod przedstawia minimalne wymaganie dotyczące wywoływania klasyfikacji semantycznej.

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"
        ]
    }
);

Najważniejsze wnioski:

• queryType: "semantic" umożliwia semantyczne klasyfikowanie w zapytaniu.
• semanticSearchOptions.configurationName określa, która konfiguracja semantyczna ma być używana.
• rerankerScore w wynikach wskazuje na istotność semantyczną (wyższa jest lepsza).

Semantyczne zapytanie z podpisami

Poniższy kod dodaje etykiety w celu wyodrębnienia najbardziej odpowiednich fragmentów z każdego wyniku, z podkreśleniem ważnych terminów i fraz.

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}`
            );
        }
    }
}

Najważniejsze wnioski:

• captions.captionType: "extractive" umożliwia wyodrębnianie podpisów z pól zawartości.
• Podpisy wyświetlają najbardziej odpowiednie fragmenty i dodają <em> tagi wokół ważnych terminów.

Semantyczne zapytanie z odpowiedziami

Ostatnie zapytanie dodaje semantyczne odpowiedzi. To zapytanie używa pytania jako tekstu wyszukiwania, ponieważ semantyczne odpowiedzi działają najlepiej, gdy zapytanie jest frazowane jako pytanie. Odpowiedź to fragment dosłowny wyodrębniony z indeksu, a nie stworzona odpowiedź z modelu generowania czatu.

Zapytanie i indeksowana zawartość muszą być ściśle dopasowane, aby odpowiedź została zwrócona. Jeśli żaden kandydat nie spełnia progu ufności, odpowiedź nie zawiera odpowiedzi. W tym przykładzie użyto pytania, o którym wiadomo, że generuje wynik, aby zobaczyć składnię. Jeśli odpowiedzi nie są przydatne w Twoim przypadku, pomiń answers z kodu. W przypadku złożonych odpowiedzi należy wziąć pod uwagę wzorzec RAG lub agentowe pobieranie.

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}`
    );
}

Najważniejsze wnioski:

• answers.answerType: "extractive" umożliwia wyodrębnianie odpowiedzi na zapytania pytaniopodobne.
• Odpowiedzi to zawartość dosłowna wyodrębniona z indeksu, a nie tekst wygenerowany.
• results.answers pobiera obiekty odpowiedzi oddzielnie od wyników wyszukiwania.

W tym przewodniku szybkiego startu użyjesz biblioteki klienta Wyszukiwanie AI platformy Azure dla Python, aby dodać semantyczny ranking do istniejącego indeksu wyszukiwania i przeszukiwać indeks.

Ranking semantyczny to funkcjonalność po stronie zapytania, która używa maszynowego zrozumienia tekstu do przeskalowania wyników wyszukiwania, promując najbardziej semantycznie istotne dopasowania na początku listy. Możesz dodać konfigurację semantyczną do istniejącego indeksu bez konieczności ponownego kompilowania. Klasyfikacja semantyczna jest najbardziej skuteczna w przypadku tekstu informacyjnego lub opisowego.

Wymagania wstępne

• Konto Azure z aktywną subskrypcją. Utwórz bezpłatne konto.

• Usługa Wyszukiwanie AI platformy Azure.

• Indeks z opisowymi polami tekstowymi przypisanymi jako searchable i retrievable. Przyjmuje się, że w tym szybkim starcie używany jest indeks hotels-sample.

• Python 3.10 lub nowszy.

• Visual Studio Code z rozszerzeniem Python.

• Narzędzie Git do sklonowania przykładowego repozytorium.

• Azure CLI na potrzeby uwierzytelniania bez klucza za pomocą Microsoft Entra ID.

Konfigurowanie dostępu

Przed rozpoczęciem upewnij się, że masz uprawnienia dostępu do zawartości i operacji w Wyszukiwanie AI platformy Azure. W tym przewodniku szybkiego startu użyto Microsoft Entra ID do uwierzytelniania oraz dostępu opartego na rolach w celu autoryzacji. Aby przypisać role, musisz być właścicielem lub administratorem dostępu użytkowników . Jeśli role nie są możliwe, zamiast tego użyj uwierzytelniania opartego na kluczach .

Aby skonfigurować zalecany dostęp oparty na rolach:

1. Włącz dostęp oparty na rolach dla usługi wyszukiwania.

2. Przypisz następujące role do konta użytkownika.

   • Współautor usługi wyszukiwania

   • Czytnik danych indeksu wyszukiwania

Pobierz punkt końcowy

Każda usługa Wyszukiwanie AI platformy Azure ma endpoint, który jest unikatowym adresem URL, który identyfikuje i zapewnia dostęp sieciowy do usługi. W późniejszej sekcji określisz ten punkt końcowy, aby programowo nawiązać połączenie z usługą wyszukiwania.

Aby uzyskać punkt końcowy:

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. W okienku po lewej stronie wybierz pozycję Przegląd.

3. Zanotuj punkt końcowy, który powinien wyglądać następująco: https://my-service.search.windows.net.

Rozpoczynanie od indeksu

Ten przewodnik modyfikuje istniejący indeks, aby uwzględnić konfigurację semantyczną. Zalecamy indeks hotels-sample, który można utworzyć w ciągu kilku minut za pomocą kreatora portalu Azure.

Aby użyć innego indeksu, zastąp nazwę indeksu, nazwy pól w konfiguracji semantycznej i nazwy pól w instrukcjach zapytania select w całym przykładowym kodzie. Indeks powinien zawierać opisowe pola tekstowe, które są przypisywane jako searchable i retrievable.

Aby przejrzeć i wysłać zapytanie do indeksu hotels-sample przed klasyfikacją semantyczną:

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. Na panelu po lewej stronie wybierz Zarządzanie wyszukiwaniem>Indeksy.

3. Wybierz hotels-sample.

4. Wybierz pozycję Konfiguracje semantyczne , aby wyświetlić wszystkie istniejące konfiguracje. Jeśli podczas procesu tworzenia kreatora włączono klasyfikację semantyczną, powinna istnieć konfiguracja domyślna.

   

5. Wybierz pozycję Eksplorator wyszukiwania, a następnie wybierz pozycję Wyświetl>widok JSON.

6. Wklej następujący kod JSON do edytora zapytań.

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

7. Wybierz pozycję Wyszukaj , aby uruchomić zapytanie.

   Odpowiedź powinna być podobna do poniższego przykładu. Jest to zapytanie pełnotekstowe sklasyfikowane przez BM25, więc wyniki są zgodne z poszczególnymi terminami zapytania i wariantami językowymi, a nie ogólnym znaczeniem zapytania. Na przykład walking i walk dopasowują się, a live i music dopasowują się niezależnie, zamiast jako frazę.

   "@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
   ]
   

   Wskazówka

   To zapytanie pokazuje, jak wygląda odpowiedź przed zastosowaniem klasyfikacji semantycznej. Po skonfigurowaniu konfiguracji semantycznej dodaj "queryType": "semantic" i "semanticConfiguration": "semantic-config" , aby zobaczyć, jak to samo zapytanie jest klasyfikowane inaczej według klasyfikacji semantycznej.

Konfigurowanie środowiska

1. Użyj narzędzia Git, aby sklonować przykładowe repozytorium.

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

2. Przejdź do folderu Szybki start i otwórz go w Visual Studio Code.

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

3. W sample.env zastąp wartość AZURE_SEARCH_ENDPOINT symbolu zastępczego adresem URL uzyskanym w Uzyskiwanie punktu końcowego.

4. Zmień nazwę sample.env na .env.

   mv sample.env .env
   

5. Otwórz plik semantic-ranking-quickstart.ipynb.

6. Naciśnij klawisze Ctrl+Shift+P, wybierz pozycję Notes: Wybierz pozycję Jądro notesu i postępuj zgodnie z monitami, aby utworzyć środowisko wirtualne. Wybierz requirements.txt dla zależności.

   Po zakończeniu w katalogu projektu powinien pojawić się folder .venv.

7. W przypadku uwierzytelniania bez klucza przy użyciu Microsoft Entra ID zaloguj się do konta Azure. Jeśli masz wiele subskrypcji, wybierz tę, która zawiera usługę Wyszukiwanie AI platformy Azure.

   az login
   

Uruchamianie kodu

1. Uruchom komórki Install packages and set variables aby zainstalować wymagane pakiety i załadować zmienne środowiskowe.

2. Uruchom pozostałe komórki sekwencyjnie, aby dodać konfigurację semantyczną i wykonać zapytanie względem indeksu.

Wyjście

Dane wyjściowe Get the index definition komórki to nazwa indeksu, jego pól i wszelkie istniejące konfiguracje semantyczne.

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

Dane wyjściowe komórki Add a semantic configuration to the index zawierają listę wszystkich konfiguracji semantycznych w indeksie, włącznie z tymi dodanymi przez kod, a następnie komunikat o powodzeniu.

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!

Wynik działania Run a term query komórki zwraca wszystkie pasujące dokumenty uporządkowane według wyniku BM25. To zapytanie odniesienia nie używa klasyfikacji semantycznej.

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

Dane wyjściowe Run a semantic query komórki zwracają wszystkie pasujące dokumenty uporządkowane przez wynik ponownego rangowania semantycznego.

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

Dane wyjściowe z komórki Return captions dodają element podpisu z podświetleniem trafień obok pól wyszukiwania. Podpisy są najbardziej odpowiednimi fragmentami w wyniku wyszukiwania. Jeśli indeks zawiera większy tekst, napisy ułatwiają wyodrębnianie najbardziej interesujących zdań.

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

Dane wyjściowe Return semantic answers komórki zawierają semantyczną odpowiedź pobraną z jednego z wyników, które najlepiej pasują do pytania, a następnie wyniki wyszukiwania z podpisami.

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

Omówienie kodu

Teraz, po uruchomieniu kodu, podzielmy kluczowe kroki:

1. Konfiguracja i uwierzytelnianie
2. Aktualizowanie indeksu przy użyciu konfiguracji semantycznej
3. Wykonywanie zapytań względem indeksu

Konfiguracja i uwierzytelnianie

Komórka Install packages and set variables ładuje zmienne środowiskowe i tworzy element DefaultAzureCredential na potrzeby uwierzytelniania.

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"
)

Najważniejsze wnioski:

• DefaultAzureCredential zapewnia uwierzytelnianie bez klucza przy użyciu Microsoft Entra ID. Łączy wiele typów poświadczeń, w tym poświadczenie Azure CLI z az login.
• Zmienne środowiskowe są ładowane z .env pliku przy użyciu python-dotenv.

Aktualizowanie indeksu przy użyciu konfiguracji semantycznej

Komórka Add a semantic configuration to the index dodaje konfigurację semantyczną do istniejącego hotels-sample indeksu. Ta operacja nie usuwa żadnych dokumentów wyszukiwania, a indeks pozostaje operacyjny po dodaniu konfiguracji.

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)

Najważniejsze wnioski:

• Konfiguracja semantyczna określa pola używane do klasyfikacji semantycznej. title_field Ustawia tytuł dokumentu, content_fields ustawia główną zawartość i keywords_fields ustawia pola słowa kluczowego lub tagu.
• Należy utworzyć konfigurację wraz z skojarzonym SemanticConfiguration modelemSemanticPrioritizedFields, a następnie dołączyć ją do istniejącego indeksu.
• create_or_update_index Wypycha zaktualizowany schemat do usługi wyszukiwania bez ponownego kompilowania indeksu lub usuwania dokumentów.

Wykonywanie zapytań względem indeksu

Komórki zapytań uruchamiają cztery zapytania w sekwencji: bazowe wyszukiwanie słów kluczowych, a następnie trzy semantyczne warianty rankingowe o rosnącej funkcjonalności.

Zapytanie terminowe (punkt odniesienia)

Komórka Run a term query uruchamia wyszukiwanie słów kluczowych przy użyciu oceniania BM25. To zapytanie bazowe nie używa klasyfikacji semantycznej i służy jako punkt porównania.

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
)

Najważniejsze wnioski:

• query_type='simple' określa wyszukiwanie słów kluczowych przy użyciu oceniania BM25.
• Element @search.score w wynikach wskazuje ocenę istotności BM25.

Zapytanie semantyczne (brak podpisów, brak odpowiedzi)

Komórka Run a semantic query pokazuje minimalne wymaganie dotyczące wywoływania klasyfikacji semantycznej.

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'
)

Najważniejsze wnioski:

• query_type='semantic' umożliwia semantyczne klasyfikowanie w zapytaniu.
• semantic_configuration_name określa, która konfiguracja semantyczna ma być używana.
• @search.reranker_score w wynikach wskazuje na istotność semantyczną (wyższa jest lepsza).

Semantyczne zapytanie z podpisami

Komórka Return captions dodaje napisy, aby wyselekcjonować najbardziej istotne fragmenty z każdego wyniku z wyróżnieniem ważnych terminów i fraz.

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")

Najważniejsze wnioski:

• query_caption='extractive' umożliwia wyodrębnianie podpisów z pól zawartości.
• Podpisy wyświetlają najbardziej odpowiednie fragmenty i dodają <em> tagi wokół ważnych terminów.

Semantyczne zapytanie z odpowiedziami

Komórka Return semantic answers dodaje odpowiedzi semantyczne. To zapytanie używa pytania jako tekstu wyszukiwania, ponieważ semantyczne odpowiedzi działają najlepiej, gdy zapytanie jest frazowane jako pytanie. Odpowiedź to fragment dosłowny wyodrębniony z indeksu, a nie stworzona odpowiedź z modelu generowania czatu.

Zapytanie i indeksowana zawartość muszą być ściśle dopasowane, aby odpowiedź została zwrócona. Jeśli żaden kandydat nie spełnia progu ufności, odpowiedź nie zawiera odpowiedzi. W tym przykładzie użyto pytania, o którym wiadomo, że generuje wynik, aby zobaczyć składnię. Jeśli odpowiedzi nie są przydatne w Twoim przypadku, pomiń query_answer z kodu. W przypadku złożonych odpowiedzi należy wziąć pod uwagę wzorzec RAG lub agentowe pobieranie.

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")

Najważniejsze wnioski:

• query_answer="extractive" umożliwia wyodrębnianie odpowiedzi na zapytania pytaniopodobne.
• Odpowiedzi to zawartość dosłowna wyodrębniona z indeksu, a nie tekst wygenerowany.
• results.get_answers() pobiera obiekty odpowiedzi oddzielnie od wyników wyszukiwania.

W tym przewodniku Quickstart użyjesz biblioteki klienta Wyszukiwanie AI platformy Azure dla języka JavaScript (zgodnej z TypeScript), aby dodać semantyczny ranking do istniejącego indeksu wyszukiwania i przeszukać indeks.

Ranking semantyczny to funkcjonalność po stronie zapytania, która używa maszynowego zrozumienia tekstu do przeskalowania wyników wyszukiwania, promując najbardziej semantycznie istotne dopasowania na początku listy. Możesz dodać konfigurację semantyczną do istniejącego indeksu bez konieczności ponownego kompilowania. Klasyfikacja semantyczna jest najbardziej skuteczna w przypadku tekstu informacyjnego lub opisowego.

Wymagania wstępne

• Konto Azure z aktywną subskrypcją. Utwórz bezpłatne konto.

• Usługa Wyszukiwanie AI platformy Azure.

• Indeks z opisowymi polami tekstowymi przypisanymi jako searchable i retrievable. Przyjmuje się, że w tym szybkim starcie używany jest indeks hotels-sample.

• Node.js 20 LTS lub nowszym, aby uruchomić skompilowany kod.

• TypeScript do kompilowania języka TypeScript do języka JavaScript.

• Narzędzie Git do sklonowania przykładowego repozytorium.

• Azure CLI na potrzeby uwierzytelniania bez klucza za pomocą Microsoft Entra ID.

Konfigurowanie dostępu

Przed rozpoczęciem upewnij się, że masz uprawnienia dostępu do zawartości i operacji w Wyszukiwanie AI platformy Azure. W tym przewodniku szybkiego startu użyto Microsoft Entra ID do uwierzytelniania oraz dostępu opartego na rolach w celu autoryzacji. Aby przypisać role, musisz być właścicielem lub administratorem dostępu użytkowników . Jeśli role nie są możliwe, zamiast tego użyj uwierzytelniania opartego na kluczach .

Aby skonfigurować zalecany dostęp oparty na rolach:

1. Włącz dostęp oparty na rolach dla usługi wyszukiwania.

2. Przypisz następujące role do konta użytkownika.

   • Współautor usługi wyszukiwania

   • Czytnik danych indeksu wyszukiwania

Pobierz punkt końcowy

Każda usługa Wyszukiwanie AI platformy Azure ma endpoint, który jest unikatowym adresem URL, który identyfikuje i zapewnia dostęp sieciowy do usługi. W późniejszej sekcji określisz ten punkt końcowy, aby programowo nawiązać połączenie z usługą wyszukiwania.

Aby uzyskać punkt końcowy:

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. W okienku po lewej stronie wybierz pozycję Przegląd.

3. Zanotuj punkt końcowy, który powinien wyglądać następująco: https://my-service.search.windows.net.

Rozpoczynanie od indeksu

Ten przewodnik modyfikuje istniejący indeks, aby uwzględnić konfigurację semantyczną. Zalecamy indeks hotels-sample, który można utworzyć w ciągu kilku minut za pomocą kreatora portalu Azure.

Aby użyć innego indeksu, zastąp nazwę indeksu, nazwy pól w konfiguracji semantycznej i nazwy pól w instrukcjach zapytania select w całym przykładowym kodzie. Indeks powinien zawierać opisowe pola tekstowe, które są przypisywane jako searchable i retrievable.

Aby przejrzeć i wysłać zapytanie do indeksu hotels-sample przed klasyfikacją semantyczną:

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. Na panelu po lewej stronie wybierz Zarządzanie wyszukiwaniem>Indeksy.

3. Wybierz hotels-sample.

4. Wybierz pozycję Konfiguracje semantyczne , aby wyświetlić wszystkie istniejące konfiguracje. Jeśli podczas procesu tworzenia kreatora włączono klasyfikację semantyczną, powinna istnieć konfiguracja domyślna.

   

5. Wybierz pozycję Eksplorator wyszukiwania, a następnie wybierz pozycję Wyświetl>widok JSON.

6. Wklej następujący kod JSON do edytora zapytań.

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

7. Wybierz pozycję Wyszukaj , aby uruchomić zapytanie.

   Odpowiedź powinna być podobna do poniższego przykładu. Jest to zapytanie pełnotekstowe sklasyfikowane przez BM25, więc wyniki są zgodne z poszczególnymi terminami zapytania i wariantami językowymi, a nie ogólnym znaczeniem zapytania. Na przykład walking i walk dopasowują się, a live i music dopasowują się niezależnie, zamiast jako frazę.

   "@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
   ]
   

   Wskazówka

   To zapytanie pokazuje, jak wygląda odpowiedź przed zastosowaniem klasyfikacji semantycznej. Po skonfigurowaniu konfiguracji semantycznej dodaj "queryType": "semantic" i "semanticConfiguration": "semantic-config" , aby zobaczyć, jak to samo zapytanie jest klasyfikowane inaczej według klasyfikacji semantycznej.

Konfigurowanie środowiska

1. Użyj narzędzia Git, aby sklonować przykładowe repozytorium.

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

2. Przejdź do folderu Szybki start.

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

3. W sample.env zastąp wartość AZURE_SEARCH_ENDPOINT symbolu zastępczego adresem URL uzyskanym w Uzyskiwanie punktu końcowego.

4. Zmień nazwę sample.env na .env.

   mv sample.env .env
   

5. Zainstaluj zależności.

   npm install
   

   Po zakończeniu instalacji powinien zostać wyświetlony node_modules folder w katalogu projektu.

6. Skompiluj pliki TypeScript do języka JavaScript.

   npm run build
   

7. W przypadku uwierzytelniania bez klucza przy użyciu Microsoft Entra ID zaloguj się do konta Azure. Jeśli masz wiele subskrypcji, wybierz tę, która zawiera usługę Wyszukiwanie AI platformy Azure.

   az login
   

Uruchamianie kodu

1. Pobierz istniejące ustawienia indeksu.

   node -r dotenv/config dist/getIndexSettings.js
   

2. Zaktualizuj indeks przy użyciu konfiguracji semantycznej.

   node -r dotenv/config dist/updateIndexSettings.js
   

3. Uruchom zapytanie semantyczne.

   node -r dotenv/config dist/semanticQuery.js
   

4. Uruchom semantyczne zapytanie z podpisami.

   node -r dotenv/config dist/semanticQueryReturnCaptions.js
   

5. Uruchom semantyczne zapytanie z odpowiedziami.

   node -r dotenv/config dist/semanticAnswer.js
   

   Uwaga

   Te polecenia uruchamiają skompilowane .js pliki z dist folderu . Kod TypeScript musi zostać transpilowany do języka JavaScript, zanim Node.js będzie mógł go wykonać, dlatego wcześniej uruchomiono polecenie npm run build.

Wyjście

Skrypt getIndexSettings.js zwraca nazwę indeksu, liczbę pól, szczegóły pola z typem i stanem wyszukiwania oraz wszelkie istniejące konfiguracje semantyczne.

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

Skrypt updateIndexSettings.js zwraca wszystkie konfiguracje semantyczne, w tym te, które zostały dodane.

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.

Skrypt semanticQuery.js zwraca wyniki uporządkowane według wyniku ponownej klasyfikacji.

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

Skrypt semanticQueryReturnCaptions.js zwraca napisy ekstrakcyjne z wyróżnieniem trafień. Podpisy są najbardziej odpowiednimi fragmentami w wyniku wyszukiwania.

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

Skrypt semanticAnswer.js zwraca semantyczną odpowiedź (zawartość dosłowną) pobraną z wyniku, który najlepiej pasuje do pytania.

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

Omówienie kodu

Teraz, po uruchomieniu kodu, podzielmy kluczowe kroki:

1. Konfiguracja i uwierzytelnianie
2. Aktualizowanie indeksu przy użyciu konfiguracji semantycznej
3. Wykonywanie zapytań względem indeksu

Konfiguracja i uwierzytelnianie

Plik config.ts ładuje zmienne środowiskowe, tworzy mechanizm DefaultAzureCredential dla uwierzytelniania i definiuje interfejs HotelDocument dla bezpieczeństwa typów.

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[];
}

Najważniejsze wnioski:

• DefaultAzureCredential zapewnia uwierzytelnianie bez klucza przy użyciu Microsoft Entra ID. Łączy wiele typów poświadczeń, w tym poświadczenie Azure CLI z az login.
• Interfejs HotelDocument zapewnia sprawdzanie typów w czasie kompilacji dla wyników wyszukiwania, zapewniając bezpieczny dostęp do pól dokumentów.
• Zmienne środowiskowe są ładowane z .env pliku przy użyciu dotenv.

Aktualizowanie indeksu przy użyciu konfiguracji semantycznej

Plik updateIndexSettings.ts dodaje konfigurację semantyczną do istniejącego hotels-sample indeksu. Ta operacja nie usuwa żadnych dokumentów wyszukiwania, a indeks pozostaje operacyjny po dodaniu konfiguracji. Adnotacje typów TypeScript zapewniają, że konfiguracja jest zgodna z oczekiwanym schematem.

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);

Najważniejsze wnioski:

• Typy typeScript, takie jak SemanticPrioritizedFields, SemanticConfigurationi SemanticField zapewniają walidację czasu kompilacji dla struktury konfiguracji.
• titleField Ustawia tytuł dokumentu, contentFields ustawia główną zawartość i keywordsFields ustawia pola słowa kluczowego lub tagu.
• createOrUpdateIndex Wypycha zaktualizowany schemat do usługi wyszukiwania bez ponownego kompilowania indeksu lub usuwania dokumentów.

Wykonywanie zapytań względem indeksu

Skrypty zapytań uruchamiają trzy zapytania w sekwencji, zaczynając od podstawowego wyszukiwania semantycznego aż do semantycznej klasyfikacji z odpowiedziami i podpisami.

Zapytanie semantyczne (brak podpisów, brak odpowiedzi)

Skrypt semanticQuery.ts przedstawia minimalne wymagania dotyczące wywoływania klasyfikacji semantycznej z wynikami bezpiecznymi pod względem typu.

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"
        ]
    }
);

Najważniejsze wnioski:

• SearchClient<HotelDocument> zapewnia bezpieczny dostęp do pól dokumentów w wynikach, z autouzupełnianiem nazw pól w select i result.document.
• queryType: "semantic" umożliwia semantyczne klasyfikowanie w zapytaniu.
• semanticSearchOptions.configurationName określa, która konfiguracja semantyczna ma być używana.

Semantyczne zapytanie z podpisami

Skrypt semanticQueryReturnCaptions.ts dodaje podpisy, aby wyodrębnić najbardziej odpowiednie fragmenty z każdego wyniku, z wyróżnieniem ważnych terminów i fraz.

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}`
            );
        }
    }
}

Najważniejsze wnioski:

• captions.captionType: "extractive" umożliwia wyodrębnianie podpisów z pól zawartości.
• Podpisy wyświetlają najbardziej odpowiednie fragmenty i dodają <em> tagi wokół ważnych terminów.

Semantyczne zapytanie z odpowiedziami

Skrypt semanticAnswer.ts dodaje odpowiedzi semantyczne. Używa pytania jako tekstu wyszukiwania, ponieważ semantyczne odpowiedzi działają najlepiej, gdy zapytanie jest frazowane jako pytanie. Odpowiedź to fragment dosłowny wyodrębniony z indeksu, a nie stworzona odpowiedź z modelu generowania czatu.

Zapytanie i indeksowana zawartość muszą być ściśle dopasowane, aby odpowiedź została zwrócona. Jeśli żaden kandydat nie spełnia progu ufności, odpowiedź nie zawiera odpowiedzi. W tym przykładzie użyto pytania, o którym wiadomo, że generuje wynik, aby zobaczyć składnię. Jeśli odpowiedzi nie są przydatne w Twoim przypadku, pomiń answers z kodu. W przypadku złożonych odpowiedzi należy wziąć pod uwagę wzorzec RAG lub agentowe pobieranie.

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}`
    );
}

Najważniejsze wnioski:

• answers.answerType: "extractive" umożliwia wyodrębnianie odpowiedzi na zapytania pytaniopodobne.
• Odpowiedzi to zawartość dosłowna wyodrębniona z indeksu, a nie tekst wygenerowany.
• results.answers pobiera obiekty odpowiedzi oddzielnie od wyników wyszukiwania.

W tym przewodniku szybkiego startu użyjesz interfejsów REST API Wyszukiwanie AI platformy Azure, aby dodać semantyczny ranking do istniejącego indeksu wyszukiwania i przeszukiwać indeks.

Ranking semantyczny to funkcjonalność po stronie zapytania, która używa maszynowego zrozumienia tekstu do przeskalowania wyników wyszukiwania, promując najbardziej semantycznie istotne dopasowania na początku listy. Możesz dodać konfigurację semantyczną do istniejącego indeksu bez konieczności ponownego kompilowania. Klasyfikacja semantyczna jest najbardziej skuteczna w przypadku tekstu informacyjnego lub opisowego.

Wymagania wstępne

• Konto Azure z aktywną subskrypcją. Utwórz bezpłatne konto.

• Usługa Wyszukiwanie AI platformy Azure.

• Indeks z opisowymi polami tekstowymi przypisanymi jako searchable i retrievable. Przyjmuje się, że w tym szybkim starcie używany jest indeks hotels-sample.

• Visual Studio Code z rozszerzeniem klienta REST.

• Narzędzie Git do sklonowania przykładowego repozytorium.

• Azure CLI na potrzeby uwierzytelniania bez klucza za pomocą Microsoft Entra ID.

Konfigurowanie dostępu

Przed rozpoczęciem upewnij się, że masz uprawnienia dostępu do zawartości i operacji w Wyszukiwanie AI platformy Azure. W tym przewodniku szybkiego startu użyto Microsoft Entra ID do uwierzytelniania oraz dostępu opartego na rolach w celu autoryzacji. Aby przypisać role, musisz być właścicielem lub administratorem dostępu użytkowników . Jeśli role nie są możliwe, zamiast tego użyj uwierzytelniania opartego na kluczach .

Aby skonfigurować zalecany dostęp oparty na rolach:

1. Włącz dostęp oparty na rolach dla usługi wyszukiwania.

2. Przypisz następujące role do konta użytkownika.

   • Współautor usługi wyszukiwania

   • Czytnik danych indeksu wyszukiwania

Pobierz punkt końcowy

Każda usługa Wyszukiwanie AI platformy Azure ma endpoint, który jest unikatowym adresem URL, który identyfikuje i zapewnia dostęp sieciowy do usługi. W późniejszej sekcji określisz ten punkt końcowy, aby programowo nawiązać połączenie z usługą wyszukiwania.

Aby uzyskać punkt końcowy:

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. W okienku po lewej stronie wybierz pozycję Przegląd.

3. Zanotuj punkt końcowy, który powinien wyglądać następująco: https://my-service.search.windows.net.

Rozpoczynanie od indeksu

Ten przewodnik modyfikuje istniejący indeks, aby uwzględnić konfigurację semantyczną. Zalecamy indeks hotels-sample, który można utworzyć w ciągu kilku minut za pomocą kreatora portalu Azure.

Aby użyć innego indeksu, zastąp nazwę indeksu, nazwy pól w konfiguracji semantycznej i nazwy pól w instrukcjach zapytania select w całym przykładowym kodzie. Indeks powinien zawierać opisowe pola tekstowe, które są przypisywane jako searchable i retrievable.

Aby przejrzeć i wysłać zapytanie do indeksu hotels-sample przed klasyfikacją semantyczną:

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. Na panelu po lewej stronie wybierz Zarządzanie wyszukiwaniem>Indeksy.

3. Wybierz hotels-sample.

4. Wybierz pozycję Konfiguracje semantyczne , aby wyświetlić wszystkie istniejące konfiguracje. Jeśli podczas procesu tworzenia kreatora włączono klasyfikację semantyczną, powinna istnieć konfiguracja domyślna.

   

5. Wybierz pozycję Eksplorator wyszukiwania, a następnie wybierz pozycję Wyświetl>widok JSON.

6. Wklej następujący kod JSON do edytora zapytań.

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

7. Wybierz pozycję Wyszukaj , aby uruchomić zapytanie.

   Odpowiedź powinna być podobna do poniższego przykładu. Jest to zapytanie pełnotekstowe sklasyfikowane przez BM25, więc wyniki są zgodne z poszczególnymi terminami zapytania i wariantami językowymi, a nie ogólnym znaczeniem zapytania. Na przykład walking i walk dopasowują się, a live i music dopasowują się niezależnie, zamiast jako frazę.

   "@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
   ]
   

   Wskazówka

   To zapytanie pokazuje, jak wygląda odpowiedź przed zastosowaniem klasyfikacji semantycznej. Po skonfigurowaniu konfiguracji semantycznej dodaj "queryType": "semantic" i "semanticConfiguration": "semantic-config" , aby zobaczyć, jak to samo zapytanie jest klasyfikowane inaczej według klasyfikacji semantycznej.

Konfigurowanie środowiska

1. Użyj narzędzia Git, aby sklonować przykładowe repozytorium.

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

2. Przejdź do folderu Szybki start i otwórz go w Visual Studio Code.

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

3. W semantic-index-update.rest zastąp wartość @searchUrl symbolu zastępczego adresem URL uzyskanym w Uzyskiwanie punktu końcowego.

4. Powtórz poprzedni krok dla semantic-query.restelementu .

5. W przypadku uwierzytelniania bez klucza przy użyciu Microsoft Entra ID zaloguj się do konta Azure. Jeśli masz wiele subskrypcji, wybierz tę, która zawiera usługę Wyszukiwanie AI platformy Azure.

   az login
   

6. W przypadku uwierzytelniania bez klucza za pomocą Microsoft Entra ID wygeneruj token dostępu.

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

7. W obu .rest plikach zastąp wartość zastępczą @personalAccessToken tokenem z poprzedniego kroku.

Uruchamianie kodu

1. Otwórz plik semantic-index-update.rest.

2. Wybierz pozycję Wyślij żądanie w pierwszym żądaniu GET, aby zweryfikować połączenie.

   Odpowiedź powinna pojawić się w sąsiednim okienku. Jeśli masz istniejące indeksy, są one wyświetlane według nazwy. Jeśli kod HTTP to 200 OK, możesz kontynuować.

3. ### Update the hotels-sample index to include a semantic configuration Wyślij żądanie, aby dodać konfigurację semantyczną do indeksu.

   Jeśli wystąpi 400 Bad Request błąd, schemat indeksu różni się od przykładu. ### Get the schema of the index Wyślij żądanie, skopiuj JSON odpowiedzi, dodaj semantic sekcję z kodu źródłowego do pliku JSON i zastąp treść żądania PUT twoim scalonym schematem.

4. Przełącz się na semantic-query.rest i wyślij żądania sekwencyjnie: proste zapytanie do porównania z linią bazową, a następnie semantyczne zapytania z klasyfikacją, podpisami i odpowiedziami.

Wyjście

Żądanie Send a search query to the hotels-sample index zwraca wyniki sklasyfikowane według relewantności BM25, co jest wskazywane przez pole @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
  ]
}

Żądanie Send a search query to the hotels-sample index with semantic ranking dodaje @search.rerankerScore element. Zwróć uwagę, że kolejność zmienia się z prostego zapytania.

{
  "@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
  ]
}

Żądanie Return captions in the query dodaje @search.captions z wyodrębnionym tekstem i wyróżnieniami.

{
  "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
  ]
}

Żądanie Return semantic answers in the query zwraca wyodrębnianą odpowiedź w @search.answers, gdy zapytanie frazuje się jako pytanie.

{
  "@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
  ]
}

Omówienie kodu

Teraz, po uruchomieniu kodu, podzielmy kluczowe kroki:

1. Konfiguracja i uwierzytelnianie
2. Aktualizowanie indeksu przy użyciu konfiguracji semantycznej
3. Wykonywanie zapytań względem indeksu

Konfiguracja i uwierzytelnianie

Oba .rest pliki definiują zmienne u góry do ponownego użycia we wszystkich żądaniach.

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

Najważniejsze wnioski:

• @searchUrl to punkt końcowy usługi wyszukiwania.
• @personalAccessToken jest tokenem Microsoft Entra ID uzyskanym z Azure CLI. Zastępuje to klucze interfejsu API uwierzytelnianiem bez klucza.
• Authorization: Bearer {{personalAccessToken}} jest uwzględniany w każdym nagłówku żądania na potrzeby uwierzytelniania.

Aktualizowanie indeksu przy użyciu konfiguracji semantycznej

Żądanie ### Update the hotels-sample index to include a semantic configuration w semantic-index-update.rest wysyła pełny schemat indeksu wraz z nową sekcją semantic. Interfejs API REST wymaga kompletnego schematu dla każdej operacji aktualizacji, więc nie można wysyłać tylko konfiguracji semantycznej.

Kluczowym dodatkiem semantic jest sekcja:

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

Najważniejsze wnioski:

• titleField określa, które pole zawiera tytuł dokumentu do oceny semantycznej.
• prioritizedContentFields identyfikuje główne pola zawartości. Semantyczny ranker analizuje to jako pierwsze podczas oceniania istotności.
• prioritizedKeywordsFields identyfikuje pola słów kluczowych lub tagów dla dodatkowego kontekstu.
• rankingOrder: BoostedRerankerScore łączy wynik BM25 z oceną semantycznego rerankera.
• Interfejs API REST wymaga pełnego schematu dla operacji PUT. semantic Tylko sekcja jest nowa; wszystkie inne pola są niezmienione.

Wykonywanie zapytań względem indeksu

Żądania w semantic-query.rest postępują od prostego wyszukiwania słów kluczowych do semantycznej klasyfikacji z podpisami i odpowiedziami. Wszystkie zapytania to żądania POST do Documents - Search Post (interfejs API REST).

Proste zapytanie

Żądanie ### Send a search query to the hotels-sample index to proste wyszukiwanie słów kluczowych, które nie używa klasyfikacji semantycznej. Służy jako punkt odniesienia do porównywania wyników z semantycznym rerankingiem i bez niego.

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

Najważniejsze wnioski:

• queryType: "simple" używa domyślnego algorytmu klasyfikacji BM25.
• Wyniki są klasyfikowane tylko według istotności słowa kluczowego (@search.score).

Zapytanie semantyczne (brak podpisów, brak odpowiedzi)

Żądanie dodaje semantyczną klasyfikację ### Send a search query to the hotels-sample index with semantic ranking. Poniższy kod JSON przedstawia minimalne wymaganie dotyczące wywoływania klasyfikacji semantycznej.

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

Najważniejsze wnioski:

• queryType: "semantic" umożliwia semantyczne klasyfikowanie w zapytaniu.
• semanticConfiguration określa, która konfiguracja semantyczna ma być używana.

Semantyczne zapytanie z podpisami

Żądanie ### Return captions in the query dodaje podpisy, aby wyodrębnić najbardziej odpowiednie fragmenty z każdego wyniku, z wyróżnieniem najważniejszych terminów i fraz.

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

Najważniejsze wnioski:

• captions: "extractive|highlight-true" umożliwia generowanie podpisów z użyciem tagów <em> otaczających kluczowe terminy.
• Podpisy są wyświetlane w tablicy @search.captions dla każdego wyniku.

Semantyczne zapytanie z odpowiedziami

Żądanie ### Return semantic answers in the query dodaje odpowiedzi semantyczne. Używa pytania jako tekstu wyszukiwania, ponieważ semantyczne odpowiedzi działają najlepiej, gdy zapytanie jest frazowane jako pytanie. Odpowiedź to fragment dosłowny wyodrębniony z indeksu, a nie stworzona odpowiedź z modelu generowania czatu.

Zapytanie i indeksowana zawartość muszą być ściśle dopasowane, aby odpowiedź została zwrócona. Jeśli żaden kandydat nie spełnia progu ufności, odpowiedź nie zawiera odpowiedzi. W tym przykładzie użyto pytania, o którym wiadomo, że generuje wynik, aby zobaczyć składnię. Jeśli odpowiedzi nie są przydatne w twoim scenariuszu, pomiń answers parametr z żądania. W przypadku złożonych odpowiedzi należy wziąć pod uwagę wzorzec RAG lub agentowe pobieranie.

{
    "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"
}

Najważniejsze wnioski:

• answers: "extractive" umożliwia wyodrębnianie odpowiedzi na zapytania pytaniopodobne.
• Odpowiedzi są wyświetlane w tablicy najwyższego poziomu @search.answers , oddzielone od poszczególnych wyników.
• Odpowiedzi to zawartość dosłowna wyodrębniona z indeksu, a nie tekst wygenerowany.