Szybki start: ranking semantyczny - Azure AI Search

Z tego przewodnika Szybki start dowiesz się, jak używać klasyfikacji semantycznej , dodając semantyczną konfigurację do indeksu wyszukiwania i dodając parametry semantyczne do zapytania. Możesz użyć pliku hotels-sample-index lub własnego.

W usłudze Azure AI Search semantyczna klasyfikacja to funkcja po stronie zapytania, która wykorzystuje zrozumienie odczytu maszynowego od firmy Microsoft w celu ponownego podkreślenia wyników wyszukiwania, promując najbardziej semantycznie istotne dopasowania na początku listy. W zależności od zawartości i zapytania semantyczny ranking może znacznie poprawić istotność wyszukiwania przy minimalnym wysiłku dewelopera.

Możesz dodać konfigurację semantyczną do istniejącego indeksu bez konieczności ponownego kompilowania. Ranking semantyczny jest najbardziej skuteczny w tekście, który jest informacyjny lub opisowy.

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Usługa Azure AI Search z włączonym semantycznym rankerem.
Nowy lub istniejący indeks z opisowymi lub rozwlekłymi polami tekstowymi, które są oznaczone jako możliwe do wyszukiwania. W tym przewodniku Szybki start zakłada się hotels-sample-index.

Konfigurowanie dostępu

Można nawiązać połączenie z usługą Azure AI Search przy użyciu kluczy API lub Microsoft Entra ID wraz z przypisaniami ról. Klucze są łatwiejsze do rozpoczęcia od, ale role są bezpieczniejsze. Aby uzyskać więcej informacji, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu ról.

Aby skonfigurować dostęp oparty na rolach:

Zaloguj się do witryny Azure Portal i wybierz usługę wyszukiwania.
W okienku po lewej stronie wybierz Ustawienia>Klucze.
W obszarze Kontrola dostępu do interfejsu API wybierz pozycję Kontrola dostępu oparta na rolach lub Obie , jeśli potrzebujesz czasu, aby przenieść klientów do dostępu opartego na rolach.
W okienku po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).
Wybierz Dodaj>Dodaj przypisanie roli.
Przypisz role Współautor usługi wyszukiwania i Współautor danych indeksu wyszukiwania do konta użytkownika.

Rozpoczynanie od indeksu

W tym przewodniku Szybki start założono, że istniejący indeks został zmodyfikowany w celu uwzględnienia konfiguracji semantycznej. Zalecamy hotels-sample-index, który można utworzyć w ciągu kilku minut za pomocą kreatora portalu Azure.

Aby rozpocząć od istniejącego indeksu:

Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.
W obszarze zarządzanie wyszukiwaniem>Indeksy, wybierz pozycję hotels-sample-index.
Wybierz pozycję Konfiguracje semantyczne , aby upewnić się, że indeks nie ma konfiguracji semantycznej.
Wybierz Eksplorator wyszukiwania, a następnie wybierz widok JSON.

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

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

Wybierz pozycję Wyszukaj , aby uruchomić zapytanie.

To zapytanie jest wyszukiwaniem słów kluczowych. Odpowiedź powinna być podobna do poniższego przykładu, jak oceniona przez domyślny ranker BM25 L1 przy wyszukiwaniu pełnotekstowym.

W celu zapewnienia czytelności przykład wybiera tylko pola HotelId, HotelName i Description. Wyniki zawierają dosłowne dopasowania terminów zapytania (walking, distance, , livemusic) lub wariantów językowych (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

To zapytanie pokazuje, jak wygląda odpowiedź przed zastosowaniem klasyfikacji semantycznej. Później możesz uruchomić to samo zapytanie po skonfigurowaniu klasyfikacji semantycznej, aby zobaczyć, jak zmienia się odpowiedź.

Wskazówka

Konfigurację semantyczną można dodać w witrynie Azure Portal. Jeśli jednak chcesz dowiedzieć się, jak programowo dodać konfigurację semantyczną, kontynuuj z tym szybkim startem.

Konfigurowanie klienta

W tym przewodniku użyjesz środowiska IDE i biblioteki klienta Azure.Search.Documents, aby zaimplementować klasyfikację semantyczną do istniejącego indeksu wyszukiwania.

Zalecamy użycie Visual Studio dla tego szybkiego startu.

Wskazówka

Możesz pobrać kod źródłowy , aby rozpocząć od ukończonego projektu lub wykonać następujące kroki, aby utworzyć własny.

Instalowanie bibliotek

Uruchom program Visual Studio i otwórz quickstart-semantic-search.sln lub utwórz nowy projekt przy użyciu szablonu aplikacji konsolowej.
W obszarze Narzędzia>Menedżer pakietów NuGet wybierz pozycję Zarządzaj pakietami NuGet dla rozwiązania....
Wybierz przycisk Przeglądaj.
Wyszukaj pakiet Azure.Search.Documents i wybierz najnowszą stabilną wersję.
Wyszukaj pakiet Azure.Identity i wybierz najnowszą stabilną wersję.
Wybierz pozycję Zainstaluj , aby dodać zestaw do projektu i rozwiązania.

Jeśli zalogowałeś się do witryny Azure Portal, zalogowałeś się na platformie Azure. Jeśli nie masz pewności, zaloguj się przy użyciu interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell: az login lub az connect. Jeśli masz wiele dzierżaw i subskrypcji, zobacz Szybki start: nawiązywanie połączenia bez kluczy , aby uzyskać pomoc dotyczącą nawiązywania połączenia.

Aktualizowanie indeksu

W tej sekcji zaktualizujesz indeks wyszukiwania, aby uwzględnić konfigurację semantyczną. Kod pobiera definicję indeksu z usługi wyszukiwania i dodaje konfigurację semantyczną.

Otwórz projekt BuildIndex w programie Visual Studio. Program składa się z następującego kodu.

Ten kod używa elementu SearchIndexClient do zaktualizowania indeksu w usłudze wyszukiwania.

class BuildIndex
{
    static async Task Main(string[] args)
    {
        string searchServiceName = "PUT-YOUR-SEARCH-SERVICE-NAME-HERE";
        string indexName = "hotels-sample-index";
        string endpoint = $"https://{searchServiceName}.search.windows.net";
        var credential = new Azure.Identity.DefaultAzureCredential();

        await ListIndexesAsync(endpoint, credential);
        await UpdateIndexAsync(endpoint, credential, indexName);
    }

    // Print a list of all indexes on the search service
    // You should see hotels-sample-index in the list
    static async Task ListIndexesAsync(string endpoint, Azure.Core.TokenCredential credential)
    {
        try
        {
            var indexClient = new Azure.Search.Documents.Indexes.SearchIndexClient(
                new Uri(endpoint),
                credential
            );

            var indexes = indexClient.GetIndexesAsync();

            Console.WriteLine("Here's a list of all indexes on the search service. You should see hotels-sample-index:");
            await foreach (var index in indexes)
            {
                Console.WriteLine(index.Name);
            }
            Console.WriteLine(); // Add an empty line for readability
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error listing indexes: {ex.Message}");
        }
    }

    static async Task UpdateIndexAsync(string endpoint, Azure.Core.TokenCredential credential, string indexName)
    {
        try
        {
            var indexClient = new Azure.Search.Documents.Indexes.SearchIndexClient(
                new Uri(endpoint),
                credential
            );

            // Get the existing definition of hotels-sample-index
            var indexResponse = await indexClient.GetIndexAsync(indexName);
            var index = indexResponse.Value;

            // Add a semantic configuration
            const string semanticConfigName = "semantic-config";
            AddSemanticConfiguration(index, semanticConfigName);

            // Update the index with the new information
            var updatedIndex = await indexClient.CreateOrUpdateIndexAsync(index);
            Console.WriteLine("Index updated successfully.");

            // Print the updated index definition as JSON
            var refreshedIndexResponse = await indexClient.GetIndexAsync(indexName);
            var refreshedIndex = refreshedIndexResponse.Value;
            var jsonOptions = new JsonSerializerOptions { WriteIndented = true };
            string indexJson = JsonSerializer.Serialize(refreshedIndex, jsonOptions);
            Console.WriteLine($"Here is the revised index definition:\n{indexJson}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error updating index: {ex.Message}");
        }
    }

    // This is the semantic configuration definition
    static void AddSemanticConfiguration(SearchIndex index, string semanticConfigName)
    {
        if (index.SemanticSearch == null)
        {
            index.SemanticSearch = new SemanticSearch();
        }
        var configs = index.SemanticSearch.Configurations;
        if (configs == null)
        {
            throw new InvalidOperationException("SemanticSearch.Configurations is null and cannot be assigned. Your service must be Basic tier or higher.");
        }
        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
                )
            );
            Console.WriteLine($"Added new semantic configuration '{semanticConfigName}' to the index definition.");
        }
        else
        {
            Console.WriteLine($"Semantic configuration '{semanticConfigName}' already exists in the index definition.");
        }
        index.SemanticSearch.DefaultConfigurationName = semanticConfigName;
    }
}

Zastąp adres URL usługi wyszukiwania prawidłowym punktem końcowym.
Uruchom program.
Dane są rejestrowane w oknie konsoli przez Console.WriteLine. Powinny zostać wyświetlone komunikaty dla każdego kroku, w tym dane JSON schematu indeksu z nową konfiguracją semantyczną.

Uruchamianie zapytań semantycznych

W tej sekcji program uruchamia kilka semantycznych zapytań w sekwencji.

Otwórz projekt QueryIndex w programie Visual Studio. Program składa się z następującego kodu.

Ten kod używa elementu SearchClient do wysyłania zapytań do indeksu.

class SemanticQuery
{
    static async Task Main(string[] args)
    {
        string searchServiceName = "PUT-YOUR-SEARCH-SERVICE-NAME-HERE";
        string indexName = "hotels-sample-index";
        string endpoint = $"https://{searchServiceName}.search.windows.net";
        var credential = new Azure.Identity.DefaultAzureCredential();

        var client = new SearchClient(new Uri(endpoint), indexName, credential);

        // Query 1: Simple query
        string searchText = "walking distance to live music";
        Console.WriteLine("\nQuery 1: Simple query using the search string 'walking distance to live music'.");
        await RunQuery(client, searchText, new SearchOptions
        {
            Size = 5,
            QueryType = SearchQueryType.Simple,
            IncludeTotalCount = true,
            Select = { "HotelId", "HotelName", "Description" }
        });
        Console.WriteLine("Press Enter to continue to the next query...");
        Console.ReadLine();

        // Query 2: Semantic query (no captions, no answers)
        Console.WriteLine("\nQuery 2: Semantic query (no captions, no answers) for 'walking distance to live music'.");
        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);
        Console.WriteLine("Press Enter to continue to the next query...");
        Console.ReadLine();

        // Query 3: Semantic query with captions
        Console.WriteLine("\nQuery 3: Semantic query with captions.");
        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" }
        };
        // Add the field(s) you want captions for to the QueryCaption.Fields collection
        captionsOptions.HighlightFields.Add("Description");
        await RunQuery(client, searchText, captionsOptions, showCaptions: true);
        Console.WriteLine("Press Enter to continue to the next query...");
        Console.ReadLine();

        // Query 4: Semantic query with answers
        // This query uses different search text designed for an answers scenario
        string searchText2 = "what's a good hotel for people who like to read";
        searchText = searchText2; // Update searchText for the next query
        Console.WriteLine("\nQuery 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.");
        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);

        static async Task RunQuery(
        SearchClient client,
        string searchText,
        SearchOptions options,
        bool showCaptions = false,
        bool showAnswers = false)
        {
            try
            {
                var response = await client.SearchAsync<SearchDocument>(searchText, options);

                if (showAnswers && response.Value.SemanticSearch?.Answers != null)
                {
                    Console.WriteLine("Extractive Answers:");
                    foreach (var answer in response.Value.SemanticSearch.Answers)
                    {
                        Console.WriteLine($"  {answer.Highlights}");
                    }
                    Console.WriteLine(new string('-', 40));
                }

                await foreach (var result in response.Value.GetResultsAsync())
                {
                    var doc = result.Document;
                    // Print captions first if available
                    if (showCaptions && result.SemanticSearch?.Captions != null)
                    {
                        foreach (var caption in result.SemanticSearch.Captions)
                        {
                            Console.WriteLine($"Caption: {caption.Highlights}");
                        }
                    }
                    Console.WriteLine($"HotelId: {doc.GetString("HotelId")}");
                    Console.WriteLine($"HotelName: {doc.GetString("HotelName")}");
                    Console.WriteLine($"Description: {doc.GetString("Description")}");
                    Console.WriteLine($"@search.score: {result.Score}");

                    // Print @search.rerankerScore if available
                    if (result.SemanticSearch != null && result.SemanticSearch.RerankerScore.HasValue)
                    {
                        Console.WriteLine($"@search.rerankerScore: {result.SemanticSearch.RerankerScore.Value}");
                    }
                    Console.WriteLine(new string('-', 40));
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error querying index: {ex.Message}");
            }
        }
    }
}

Zastąp adres URL usługi wyszukiwania prawidłowym punktem końcowym.
Uruchom program.
Dane są rejestrowane w oknie konsoli przez Console.WriteLine. Powinny zostać wyświetlone wyniki wyszukiwania dla każdego zapytania.

Dane wyjściowe zapytania semantycznego (bez podpisów ani odpowiedzi)

Te dane wyjściowe pochodzą z semantycznego zapytania bez podpisów ani odpowiedzi. Ciąg zapytania to "w odległości spaceru do muzyki na żywo".

W tym miejscu początkowe wyniki zapytania terminowego są oceniane ponownie przy użyciu semantycznych modeli rankingowych. W przypadku tego konkretnego zestawu danych i zapytania pierwsze kilka wyników znajduje się w podobnych pozycjach. Efekty klasyfikacji semantycznej są bardziej widoczne w pozostałej części wyników.

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: 5.074317
@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.5153193
@search.rerankerScore: 2.271434783935547
----------------------------------------
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.
@search.score: 4.8959594
@search.rerankerScore: 1.9861756563186646
----------------------------------------
HotelId: 39
HotelName: White Mountain Lodge & Suites
Description: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.
@search.score: 0.7334347
@search.rerankerScore: 1.9615401029586792
----------------------------------------
HotelId: 15
HotelName: By the Market Hotel
Description: Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
@search.score: 1.5502293
@search.rerankerScore: 1.9085469245910645
----------------------------------------
Press Enter to continue to the next query...

Dane wyjściowe zapytania semantycznego z podpisami

Poniżej przedstawiono wyniki zapytania, które dodaje etykiety z wyróżnieniem trafień.

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: 5.074317
@search.rerankerScore: 2.613231658935547
----------------------------------------
Caption:
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.5153193
@search.rerankerScore: 2.271434783935547
----------------------------------------
Caption: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within<em> short walking distance </em>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,.
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.
@search.score: 4.8959594
@search.rerankerScore: 1.9861756563186646
----------------------------------------
Caption: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend<em> evening entertainment </em>on the patio features special<em> guest musicians </em>or.
HotelId: 39
HotelName: White Mountain Lodge & Suites
Description: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.
@search.score: 0.7334347
@search.rerankerScore: 1.9615401029586792
----------------------------------------
Caption: Book now and Save up to 30%. Central location. <em>Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood.</em> Brand new rooms. Impeccable service.
HotelId: 15
HotelName: By the Market Hotel
Description: Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
@search.score: 1.5502293
@search.rerankerScore: 1.9085469245910645
----------------------------------------
Press Enter to continue to the next query...

Dane wyjściowe dla odpowiedzi semantycznych

Ostateczne zapytanie zwraca semantyczną odpowiedź. Zwróć uwagę, że zmieniliśmy ciąg zapytania dla tego przykładu: "co to jest dobry hotel dla osób, które lubią czytać".

Semantyczny ranker może wygenerować odpowiedź na ciąg zapytaniowy, który wykazuje cechy pytania. Wygenerowana odpowiedź jest wyodrębniona z zawartości, więc nie będzie zawierać zawartości skomponowanej, takiej jak to, czego można oczekiwać od modelu ukończenia czatu. Jeśli semantyczna odpowiedź nie jest przydatna w danym scenariuszu, możesz pominąć semantic_answers ze swojego kodu.

Aby utworzyć semantyczną odpowiedź, pytanie i odpowiedź muszą być ściśle dopasowane, a model musi znaleźć zawartość, która wyraźnie odpowiada na pytanie. Jeśli potencjalne odpowiedzi nie spełniają progu ufności, model nie zwraca odpowiedzi. W celach demonstracyjnych pytanie w tym przykładzie zostało zaprojektowane tak, aby uzyskać odpowiedź, aby zobaczyć składnię.

Pamiętaj, że odpowiedzi są dosłowną zawartością pobraną z indeksu i mogą brakować fraz, które użytkownik spodziewa się zobaczyć. Aby uzyskać złożone odpowiedzi wygenerowane przez model ukończenia czatu, rozważ użycie wzorca RAG lub agentowego pobierania danych.

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.
----------------------------------------
HotelId: 1
HotelName: 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.
@search.score: 2.0361428
@search.rerankerScore: 2.124817371368408
----------------------------------------
HotelId: 16
HotelName: 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.
@search.score: 3.759768
@search.rerankerScore: 2.0705394744873047
----------------------------------------
HotelId: 38
HotelName: Lakeside B & B
Description: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
@search.score: 0.7308748
@search.rerankerScore: 2.041472911834717
----------------------------------------
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: 3.391012
@search.rerankerScore: 2.0231292247772217
----------------------------------------
HotelId: 15
HotelName: By the Market Hotel
Description: Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
@search.score: 1.3198771
@search.rerankerScore: 2.021622657775879
----------------------------------------

Z tego przewodnika Szybki start dowiesz się, jak używać klasyfikacji semantycznej , dodając semantyczną konfigurację do indeksu wyszukiwania i dodając parametry semantyczne do zapytania. Możesz użyć pliku hotels-sample-index lub własnego.

W usłudze Azure AI Search semantyczna klasyfikacja to funkcja po stronie zapytania, która wykorzystuje zrozumienie odczytu maszynowego od firmy Microsoft w celu ponownego podkreślenia wyników wyszukiwania, promując najbardziej semantycznie istotne dopasowania na początku listy. W zależności od zawartości i zapytania semantyczny ranking może znacznie poprawić istotność wyszukiwania przy minimalnym wysiłku dewelopera.

Możesz dodać konfigurację semantyczną do istniejącego indeksu bez konieczności ponownego kompilowania. Ranking semantyczny jest najbardziej skuteczny w tekście, który jest informacyjny lub opisowy.

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Usługa Azure AI Search z włączonym semantycznym rankerem.
Nowy lub istniejący indeks z opisowymi lub rozwlekłymi polami tekstowymi, które są oznaczone jako możliwe do wyszukiwania. W tym przewodniku Szybki start zakłada się hotels-sample-index.

Konfigurowanie dostępu

Można nawiązać połączenie z usługą Azure AI Search przy użyciu kluczy API lub Microsoft Entra ID wraz z przypisaniami ról. Klucze są łatwiejsze do rozpoczęcia od, ale role są bezpieczniejsze. Aby uzyskać więcej informacji, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu ról.

Aby skonfigurować dostęp oparty na rolach:

Zaloguj się do witryny Azure Portal i wybierz usługę wyszukiwania.
W okienku po lewej stronie wybierz Ustawienia>Klucze.
W obszarze Kontrola dostępu do interfejsu API wybierz pozycję Kontrola dostępu oparta na rolach lub Obie , jeśli potrzebujesz czasu, aby przenieść klientów do dostępu opartego na rolach.
W okienku po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).
Wybierz Dodaj>Dodaj przypisanie roli.
Przypisz role Współautor usługi wyszukiwania i Współautor danych indeksu wyszukiwania do konta użytkownika.

Rozpoczynanie od indeksu

W tym przewodniku Szybki start założono, że istniejący indeks został zmodyfikowany w celu uwzględnienia konfiguracji semantycznej. Zalecamy hotels-sample-index, który można utworzyć w ciągu kilku minut za pomocą kreatora portalu Azure.

Aby rozpocząć od istniejącego indeksu:

Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.
W obszarze zarządzanie wyszukiwaniem>Indeksy, wybierz pozycję hotels-sample-index.
Wybierz pozycję Konfiguracje semantyczne , aby upewnić się, że indeks nie ma konfiguracji semantycznej.
Wybierz Eksplorator wyszukiwania, a następnie wybierz widok JSON.

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

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

Wybierz pozycję Wyszukaj , aby uruchomić zapytanie.

To zapytanie jest wyszukiwaniem słów kluczowych. Odpowiedź powinna być podobna do poniższego przykładu, jak oceniona przez domyślny ranker BM25 L1 przy wyszukiwaniu pełnotekstowym.

W celu zapewnienia czytelności przykład wybiera tylko pola HotelId, HotelName i Description. Wyniki zawierają dosłowne dopasowania terminów zapytania (walking, distance, , livemusic) lub wariantów językowych (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

To zapytanie pokazuje, jak wygląda odpowiedź przed zastosowaniem klasyfikacji semantycznej. Później możesz uruchomić to samo zapytanie po skonfigurowaniu klasyfikacji semantycznej, aby zobaczyć, jak zmienia się odpowiedź.

Wskazówka

Konfigurację semantyczną można dodać w witrynie Azure Portal. Jeśli jednak chcesz dowiedzieć się, jak programowo dodać konfigurację semantyczną, kontynuuj z tym szybkim startem.

Konfigurowanie klienta

W tym szybkim przewodniku użyjesz IDE i biblioteki klienta @azure/search-documents aby dodać ranking semantyczny do istniejącego indeksu wyszukiwania.

W przewodniku Szybki start założono, że na komputerze są dostępne następujące elementy:

Program Visual Studio Code dla tego szybkiego przewodnika wprowadzającego.
Node.js (LTS) na potrzeby uruchamiania przykładu.

Wskazówka

Możesz pobrać kod źródłowy , aby rozpocząć od ukończonego projektu lub wykonać następujące kroki, aby utworzyć własny.

Konfigurowanie lokalnego środowiska deweloperskiego

Uruchom program Visual Studio Code w nowym katalogu.

mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
code .

Utwórz nowy pakiet dla modułów ESM w katalogu projektu.
```
npm init -y
npm pkg set type=module
```

Zainstaluj pakiety, w tym azure-search-documents.

npm install @azure/identity @azure/search-documents dotenv

Utwórz .env, i podaj punkt końcowy usługi wyszukiwania. Punkt końcowy można uzyskać z portalu Azure na stronie Przegląd usługi wyszukiwania.
```
AZURE_SEARCH_ENDPOINT=YOUR-SEARCH-SERVICE-ENDPOINT
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
SEMANTIC_CONFIGURATION_NAME=semantic-config
```
Utwórz katalog src w katalogu projektu.
```
mkdir src
```

Jeśli zalogowałeś się do witryny Azure Portal, zalogowałeś się na platformie Azure. Jeśli nie masz pewności, zaloguj się przy użyciu interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell: az login lub az connect. Jeśli masz wiele dzierżaw i subskrypcji, zobacz Szybki start: nawiązywanie połączenia bez kluczy , aby uzyskać pomoc dotyczącą nawiązywania połączenia.

Tworzenie wspólnego pliku uwierzytelniania

Utwórz plik w ./src o nazwie config.ts, aby odczytać plik .env i przechowywać zmienne środowiskowe oraz poświadczenia uwierzytelniania. Skopiuj poniższy kod; nie zmieniaj go. Ten plik będzie używany przez wszystkie inne pliki w tym przewodniku Szybki start.

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

// Configuration - use environment variables
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-index";
export const semanticConfigurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";

// Create credential
export const credential = new DefaultAzureCredential();

console.log(`Using Azure Search endpoint: ${searchEndpoint}`);
console.log(`Using index name: ${indexName}\n\n`);

Pobieranie schematu indeksu

W tej sekcji uzyskasz ustawienia istniejącego hotels-sample-index indeksu w usłudze wyszukiwania.

Utwórz plik w ./src nazwie getIndexSettings.js i skopiuj go w poniższym kodzie.

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

const indexClient = new SearchIndexClient(searchEndpoint, credential);

console.log('Getting semantic search index settings...');

// Get the existing schema
const index = await indexClient.getIndex(indexName);

console.log(`Index name: ${index.name}`);
console.log(`Number of fields: ${index.fields.length}`);

for(const field of index.fields) {
    console.log(`Field: ${field.name}, Type: ${field.type}, Searchable: ${field.searchable}`);
}

if(index.semanticSearch && index.semanticSearch.configurations) {
    console.log(`Semantic search configurations: ${index.semanticSearch.configurations.length}`);
    for(const config of index.semanticSearch.configurations) {
        console.log(`Configuration name: ${config.name}`);
        console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
    }
} else {
    console.log("No semantic configuration exists for this index.");
}

Uruchom kod.

node -r dotenv/config src/getIndexSettings.js

Dane wyjściowe to nazwa indeksu, lista pól i instrukcja wskazująca, czy istnieje konfiguracja semantyczna. Na potrzeby tego szybkiego startu, komunikat powinien mówić No semantic configuration exists for this index.

Aktualizowanie indeksu przy użyciu konfiguracji semantycznej

Utwórz plik w ./src o nazwie updateIndexSettings.js i skopiuj poniższy kod, aby dodać konfigurację semantyczną w istniejącym indeksie hotels-sample-index w swojej usłudze wyszukiwania. Ta operacja nie usuwa dokumentów wyszukiwania, a indeks nadal działa po dodaniu konfiguracji.

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

try {

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

    // Add the new semantic configuration to the existing index
    if (existingIndex.semanticSearch && existingIndex.semanticSearch.configurations) {
        existingIndex.semanticSearch.configurations.push(newSemanticConfiguration);
    } else {
        const configExists = existingIndex.semanticSearch?.configurations?.some(
            config => config.name === semanticConfigurationName
        );
        if (!configExists) {
            existingIndex.semanticSearch = {
                configurations: [newSemanticConfiguration]
            };
        }
    }

    await indexClient.createOrUpdateIndex(existingIndex);

    const updatedIndex = await indexClient.getIndex(indexName);

    console.log(`Semantic configurations:`);
    console.log("-".repeat(40));

    if (updatedIndex.semanticSearch && updatedIndex.semanticSearch.configurations) {
        for (const config of updatedIndex.semanticSearch.configurations) {
            console.log(`Configuration name: ${config.name}`);
            console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
            console.log(`Keywords fields: ${config.prioritizedFields.keywordsFields?.map(f => f.name).join(", ")}`);
            console.log(`Content fields: ${config.prioritizedFields.contentFields?.map(f => f.name).join(", ")}`);
            console.log("-".repeat(40));
        }
    } else {
        console.log("No semantic configurations found.");
    }

    console.log("Semantic configuration updated successfully.");
} catch (error) {
    console.error("Error updating semantic configuration:", error);
}

Uruchom kod.

node -r dotenv/config src/updateIndexSettings.js

Dane wyjściowe stanowią właśnie dodaną konfigurację semantyczną, Semantic configuration updated successfully..

Uruchamianie zapytań semantycznych

hotels-sample-index Gdy indeks ma konfigurację semantyczną, można uruchamiać zapytania zawierające parametry semantyczne.

Utwórz plik w ./src o nazwie semanticQuery.js i skopiuj do niego poniższy kod, aby utworzyć semantyczne zapytanie indeksu. Jest to minimalne wymaganie dotyczące wywoływania semantycznego rankingu.

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

let rowNumber = 1;
for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const score = result.score;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelId: ${doc.HotelId}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);
}

Uruchom kod.

node -r dotenv/config src/semanticQuery.js

Dane wyjściowe powinny składać się z 13 dokumentów uporządkowanych przez element rerankerScoreDisplay.

Przywracanie napisów

Opcjonalnie możesz dodać podpisy, aby wyodrębnić fragmenty tekstu i zastosować wyróżnianie trafień do ważnych terminów i fraz. To zapytanie SQL dodaje podpisy.

Utwórz plik w ./src o nazwie semanticQueryReturnCaptions.js i skopiuj poniższy kod, aby dodać napisy do zapytania.

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

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

console.log(`Using semantic configuration: ${semanticConfigurationName}`);
console.log("Search query: walking distance to live music");

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

console.log(`Found ${results.count} results with semantic search\n`);
let rowNumber = 1;

for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);

    // Caption handling with better debugging
    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];

        if (caption.highlights) {
            console.log(`  Caption with highlights: ${caption.highlights}`);
        } else if (caption.text) {
            console.log(`  Caption text: ${caption.text}`);
        } else {
            console.log(`  Caption exists but has no text or highlights content`);
        }
    } else {
        console.log("  No captions found for this result");
    }
    console.log("-".repeat(60));
}

Uruchom kod.

node -r dotenv/config src/semanticQueryReturnCaptions.js

Dane wyjściowe powinny zawierać nowy element nagłówka obok pola wyszukiwania. Nagłówki są najbardziej istotnymi fragmentami wewnątrz wyniku. Jeśli indeks zawiera większe fragmenty tekstu, podpisy mogą być pomocne do wyodrębnienia 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.

Zwracanie odpowiedzi semantycznych

W tym ostatnim zapytaniu zwróć semantyczne odpowiedzi.

Semantyczny ranker może wygenerować odpowiedź na ciąg zapytaniowy, który wykazuje cechy pytania. Wygenerowana odpowiedź jest wyodrębniona z zawartości, więc nie będzie zawierać zawartości skomponowanej, takiej jak to, czego można oczekiwać od modelu ukończenia czatu. Jeśli semantyczna odpowiedź nie jest przydatna w danym scenariuszu, możesz pominąć semantic_answers ze swojego kodu.

Aby utworzyć semantyczną odpowiedź, pytanie i odpowiedź muszą być ściśle dopasowane, a model musi znaleźć zawartość, która wyraźnie odpowiada na pytanie. Jeśli potencjalne odpowiedzi nie spełniają progu ufności, model nie zwraca odpowiedzi. W celach demonstracyjnych pytanie w tym przykładzie zostało zaprojektowane tak, aby uzyskać odpowiedź, aby zobaczyć składnię.

Utwórz plik o nazwie ./src w semanticAnswer.js i skopiuj poniższy kod, aby uzyskać odpowiedzi semantyczne.

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

console.log(`Answers:\n\n`);
let rowNumber = 1; 

// Extract semantic answers from the search results
const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    console.log(`Semantic answer result #${rowNumber++}:`);
    if (answer.highlights) {
        console.log(`Semantic Answer: ${answer.highlights}`);
    } else {
        console.log(`Semantic Answer: ${answer.text}`);
    }
    console.log(`Semantic Answer Score: ${answer.score}\n\n`);
}

console.log(`Search Results:\n\n`);
rowNumber = 1;

// Iterate through the search results
for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`${rerankerScoreDisplay}`);
    console.log(`${doc.HotelName}`);
    console.log(`${doc.Description || 'N/A'}`);

    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(`Caption: ${caption.highlights}\n`);
        } else {
            console.log(`Caption: ${caption.text}\n`);
        }
    }
}

Uruchom kod.

node -r dotenv/config src/semanticAnswer.js

Dane wyjściowe powinny wyglądać podobnie do poniższego przykładu, gdzie najlepsza odpowiedź na pytanie jest pobierana z jednego z wyników.

Pamiętaj, że odpowiedzi są dosłowną zawartością pobraną z indeksu i mogą brakować fraz, które użytkownik spodziewa się zobaczyć. Aby uzyskać złożone odpowiedzi wygenerowane przez model ukończenia czatu, rozważ użycie wzorca RAG lub agentowego pobierania danych.
```
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 library 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
```

Z tego przewodnika Szybki start dowiesz się, jak używać klasyfikacji semantycznej , dodając semantyczną konfigurację do indeksu wyszukiwania i dodając parametry semantyczne do zapytania. Możesz użyć pliku hotels-sample-index lub własnego.

W usłudze Azure AI Search semantyczna klasyfikacja to funkcja po stronie zapytania, która wykorzystuje zrozumienie odczytu maszynowego od firmy Microsoft w celu ponownego podkreślenia wyników wyszukiwania, promując najbardziej semantycznie istotne dopasowania na początku listy. W zależności od zawartości i zapytania semantyczny ranking może znacznie poprawić istotność wyszukiwania przy minimalnym wysiłku dewelopera.

Możesz dodać konfigurację semantyczną do istniejącego indeksu bez konieczności ponownego kompilowania. Ranking semantyczny jest najbardziej skuteczny w tekście, który jest informacyjny lub opisowy.

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Usługa Azure AI Search z włączonym semantycznym rankerem.
Nowy lub istniejący indeks z opisowymi lub rozwlekłymi polami tekstowymi, które są oznaczone jako możliwe do wyszukiwania. W tym przewodniku Szybki start zakłada się hotels-sample-index.

Konfigurowanie dostępu

Można nawiązać połączenie z usługą Azure AI Search przy użyciu kluczy API lub Microsoft Entra ID wraz z przypisaniami ról. Klucze są łatwiejsze do rozpoczęcia od, ale role są bezpieczniejsze. Aby uzyskać więcej informacji, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu ról.

Aby skonfigurować dostęp oparty na rolach:

Zaloguj się do witryny Azure Portal i wybierz usługę wyszukiwania.
W okienku po lewej stronie wybierz Ustawienia>Klucze.
W obszarze Kontrola dostępu do interfejsu API wybierz pozycję Kontrola dostępu oparta na rolach lub Obie , jeśli potrzebujesz czasu, aby przenieść klientów do dostępu opartego na rolach.
W okienku po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).
Wybierz Dodaj>Dodaj przypisanie roli.
Przypisz role Współautor usługi wyszukiwania i Współautor danych indeksu wyszukiwania do konta użytkownika.

Rozpoczynanie od indeksu

W tym przewodniku Szybki start założono, że istniejący indeks został zmodyfikowany w celu uwzględnienia konfiguracji semantycznej. Zalecamy hotels-sample-index, który można utworzyć w ciągu kilku minut za pomocą kreatora portalu Azure.

Aby rozpocząć od istniejącego indeksu:

Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.
W obszarze zarządzanie wyszukiwaniem>Indeksy, wybierz pozycję hotels-sample-index.
Wybierz pozycję Konfiguracje semantyczne , aby upewnić się, że indeks nie ma konfiguracji semantycznej.
Wybierz Eksplorator wyszukiwania, a następnie wybierz widok JSON.

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

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

Wybierz pozycję Wyszukaj , aby uruchomić zapytanie.

To zapytanie jest wyszukiwaniem słów kluczowych. Odpowiedź powinna być podobna do poniższego przykładu, jak oceniona przez domyślny ranker BM25 L1 przy wyszukiwaniu pełnotekstowym.

W celu zapewnienia czytelności przykład wybiera tylko pola HotelId, HotelName i Description. Wyniki zawierają dosłowne dopasowania terminów zapytania (walking, distance, , livemusic) lub wariantów językowych (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

To zapytanie pokazuje, jak wygląda odpowiedź przed zastosowaniem klasyfikacji semantycznej. Później możesz uruchomić to samo zapytanie po skonfigurowaniu klasyfikacji semantycznej, aby zobaczyć, jak zmienia się odpowiedź.

Wskazówka

Konfigurację semantyczną można dodać w witrynie Azure Portal. Jeśli jednak chcesz dowiedzieć się, jak programowo dodać konfigurację semantyczną, kontynuuj z tym szybkim startem.

Konfigurowanie klienta

W tym przewodniku Szybki start użyjesz środowiska IDE i biblioteki klienta zestawu Java SDK usługi Azure AI Search , aby dodać semantyczny ranking do istniejącego indeksu wyszukiwania.

W przewodniku Szybki start założono, że na komputerze są dostępne następujące elementy:

Program Visual Studio Code z rozszerzeniami Java lub intelliJ IDEA
Java 21 (LTS).
Maven.

Konfigurowanie lokalnego środowiska deweloperskiego

Utwórz nowy katalog projektu Maven.

mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
code .

pom.xml Utwórz plik z wymaganymi zależnościami.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.azure.search</groupId>
    <artifactId>semantic-ranking-quickstart</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-search-documents</artifactId>
            <version>11.7.8</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.17.0</version>
        </dependency>
    </dependencies>
</project>

Skompiluj projekt, aby rozwiązać problemy z zależnościami.
```
mvn compile
```

Utwórz strukturę katalogu źródłowego.

mkdir -p src/main/java/com/azure/search/quickstart
mkdir -p src/main/resources

application.properties Utwórz plik w src/main/resources katalogu i podaj punkt końcowy usługi wyszukiwania. Punkt końcowy można uzyskać z portalu Azure na stronie Przegląd usługi wyszukiwania.
```
azure.search.endpoint=YOUR-SEARCH-SERVICE-ENDPOINT
azure.search.index.name=hotels-sample-index
semantic.configuration.name=semantic-config
```

Jeśli zalogowałeś się do witryny Azure Portal, zalogowałeś się na platformie Azure. Jeśli nie masz pewności, zaloguj się przy użyciu interfejsu wiersza polecenia platformy Azure: az login. Jeśli masz wiele dzierżaw i subskrypcji, zobacz Szybki start: nawiązywanie połączenia bez kluczy , aby uzyskać pomoc dotyczącą nawiązywania połączenia.

Tworzenie wspólnej klasy konfiguracji

Utwórz plik SearchConfig.java w katalogu src/main/java/com/azure/search/quickstart, aby odczytywać plik właściwości oraz przechowywać wartości konfiguracji i poświadczenia uwierzytelniania.

package com.azure.search.quickstart;

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

    static {
        System.out.println("Using Azure Search endpoint: " + SEARCH_ENDPOINT);
        System.out.println("Using index name: " + INDEX_NAME + "\n");
    }
}

Pobieranie schematu indeksu

W tej sekcji uzyskasz ustawienia istniejącego hotels-sample-index indeksu w usłudze wyszukiwania.

GetIndexSettings.java Utwórz plik w src/main/java/com/azure/search/quickstart katalogu.

package com.azure.search.quickstart;

import com.azure.search.documents.indexes.SearchIndexClientBuilder;
import com.azure.search.documents.indexes.models.SearchField;
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.SemanticSearch;

public class GetIndexSettings {
    public static void main(String[] args) {
        var indexClient = new SearchIndexClientBuilder()
            .endpoint(SearchConfig.SEARCH_ENDPOINT)
            .credential(SearchConfig.CREDENTIAL)
            .buildClient();

        System.out.println("Getting semantic search index settings...");

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

        System.out.println("Index name: " + index.getName());
        System.out.println("Number of fields: " + index.getFields().size());

        for (SearchField field : index.getFields()) {
            System.out.printf("Field: %s, Type: %s, Searchable: %s%n",
                field.getName(), field.getType(), field.isSearchable());
        }

        SemanticSearch semanticSearch = index.getSemanticSearch();
        if (semanticSearch != null &&
            semanticSearch.getConfigurations() != null) {
            System.out.println("Semantic search configurations: " +
                semanticSearch.getConfigurations().size());
            for (SemanticConfiguration config :
                semanticSearch.getConfigurations()) {
                System.out.println("Configuration name: " + config.getName());
                SemanticField titleField = config.getPrioritizedFields().getTitleField();
                if (titleField != null) {
                    System.out.println("Title field: " +
                        titleField.getFieldName());
                }
            }
        } else {
            System.out.println(
                "No semantic configuration exists for this index.");
        }

        System.exit(0);
    }
}

Skompiluj i uruchom kod.

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

Dane wyjściowe to nazwa indeksu, lista pól i instrukcja wskazująca, czy istnieje konfiguracja semantyczna. Na potrzeby tego szybkiego startu, komunikat powinien mówić No semantic configuration exists for this index.

Aktualizowanie indeksu przy użyciu konfiguracji semantycznej

Utwórz plik UpdateIndexSettings.java w katalogu src/main/java/com/azure/search/quickstart , aby dodać konfigurację semantyczną do istniejącego indeksu hotels-sample-index w usłudze wyszukiwania.

package com.azure.search.quickstart;

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;

public class UpdateIndexSettings {
    public static void main(String[] args) {
        try {
            var indexClient = new SearchIndexClientBuilder()
                .endpoint(SearchConfig.SEARCH_ENDPOINT)
                .credential(SearchConfig.CREDENTIAL)
                .buildClient();

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

            // Create prioritized fields for semantic configuration
            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);

            // Add the semantic configuration to the index
            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);
            }

            // Check if configuration already exists
            boolean configExists = configurations.stream()
                .anyMatch(config -> SearchConfig.SEMANTIC_CONFIG_NAME
                    .equals(config.getName()));

            if (!configExists) {
                configurations.add(newSemanticConfiguration);
            }

            indexClient.createOrUpdateIndex(existingIndex);

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

            System.out.println("Semantic configurations:");
            System.out.println("-".repeat(40));

            SemanticSearch updatedSemanticSearch =
                updatedIndex.getSemanticSearch();
            if (updatedSemanticSearch != null &&
                updatedSemanticSearch.getConfigurations() != null) {
                for (SemanticConfiguration config :
                    updatedSemanticSearch.getConfigurations()) {
                    System.out.println("Configuration name: " + config.getName());

                    SemanticPrioritizedFields fields =
                        config.getPrioritizedFields();
                    if (fields.getTitleField() != null) {
                        System.out.println("Title field: " +
                            fields.getTitleField().getFieldName());
                    }
                    if (fields.getKeywordsFields() != null) {
                        List<String> keywords = fields.getKeywordsFields().stream()
                            .map(SemanticField::getFieldName)
                            .toList();
                        System.out.println("Keywords fields: " +
                            String.join(", ", keywords));
                    }
                    if (fields.getContentFields() != null) {
                        List<String> content = fields.getContentFields().stream()
                            .map(SemanticField::getFieldName)
                            .toList();
                        System.out.println("Content fields: " +
                            String.join(", ", content));
                    }
                    System.out.println("-".repeat(40));
                }
            } else {
                System.out.println("No semantic configurations found.");
            }

            System.out.println("Semantic configuration updated successfully.");

            System.exit(0);
        } catch (Exception e) {
            System.err.println("Error updating semantic configuration: " +
                e.getMessage());
        }
    }
}

Skompiluj i uruchom kod.

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

Dane wyjściowe stanowią właśnie dodaną konfigurację semantyczną, Semantic configuration updated successfully..

Uruchamianie zapytań semantycznych

Po utworzeniu semantycznej konfiguracji indeksu hotels-sample-index można uruchamiać zapytania zawierające parametry semantyczne.

Utwórz plik SemanticQuery.java w katalogu src/main/java/com/azure/search/quickstart, aby utworzyć semantyczne zapytanie indeksu.

package com.azure.search.quickstart;

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;

public class SemanticQuery {
    public static void main(String[] args) {
        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);

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

            System.out.printf("Search result #%d:%n", rowNumber++);
            System.out.printf("  Re-ranker Score: %.2f%n", rerankerScore);
            System.out.printf("  HotelId: %s%n", document.get("HotelId"));
            System.out.printf("  HotelName: %s%n", document.get("HotelName"));
            System.out.printf("  Description: %s%n%n",
                document.get("Description") != null ?
                    document.get("Description") : "N/A");
        }

        System.exit(0);
    }
}

Skompiluj i uruchom kod.

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

Dane wyjściowe powinny składać się z 13 dokumentów uporządkowanych przez wynik ponownego generowania.

Przywracanie napisów

Opcjonalnie możesz dodać podpisy, aby wyodrębnić fragmenty tekstu i zastosować wyróżnianie trafień do ważnych terminów i fraz.

SemanticQueryWithCaptions.java Utwórz plik w src/main/java/com/azure/search/quickstart katalogu.

package com.azure.search.quickstart;

import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryCaption;
import com.azure.search.documents.models.QueryCaptionResult;
import com.azure.search.documents.models.QueryCaptionType;
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;
import java.util.List;

public class SemanticQueryWithCaptions {
    public static void main(String[] args) {
        var searchClient = new SearchClientBuilder()
            .endpoint(SearchConfig.SEARCH_ENDPOINT)
            .indexName(SearchConfig.INDEX_NAME)
            .credential(SearchConfig.CREDENTIAL)
            .buildClient();

        System.out.println("Using semantic configuration: " +
            SearchConfig.SEMANTIC_CONFIG_NAME);
        System.out.println("Search query: walking distance to live music");

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

        System.out.printf("Found results with semantic search%n%n");
        int rowNumber = 1;

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

            System.out.printf("Search result #%d:%n", rowNumber++);
            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") != null ?
                    document.get("Description") : "N/A");

            // Handle captions
            List<QueryCaptionResult> captions =
                result.getSemanticSearch().getQueryCaptions();
            if (captions != null && !captions.isEmpty()) {
                QueryCaptionResult caption = captions.get(0);

                if (caption.getHighlights() != null &&
                    !caption.getHighlights().trim().isEmpty()) {
                    System.out.printf("  Caption with highlights: %s%n",
                        caption.getHighlights());
                } else if (caption.getText() != null &&
                    !caption.getText().trim().isEmpty()) {
                    System.out.printf("  Caption text: %s%n",
                        caption.getText());
                } else {
                    System.out.println(
                        "  Caption exists but has no text or highlights content");
                }
            } else {
                System.out.println("  No captions found for this result");
            }
            System.out.println("-".repeat(60));
        }

        System.exit(0);
    }
}

Skompiluj i uruchom kod.

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

Dane wyjściowe powinny zawierać nowy element nagłówka obok pola wyszukiwania. Nagłówki są najbardziej istotnymi fragmentami wewnątrz wyniku. Jeśli indeks zawiera większe fragmenty tekstu, podpisy mogą być pomocne do wyodrębnienia 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.

Zwracanie odpowiedzi semantycznych

W tym ostatnim zapytaniu zwróć semantyczne odpowiedzi.

Semantyczny ranker może wygenerować odpowiedź na ciąg zapytaniowy, który wykazuje cechy pytania. Wygenerowana odpowiedź jest wyodrębniona z zawartości, więc nie będzie zawierać zawartości skomponowanej, takiej jak to, czego można oczekiwać od modelu ukończenia czatu.

Aby utworzyć semantyczną odpowiedź, pytanie i odpowiedź muszą być ściśle dopasowane, a model musi znaleźć zawartość, która wyraźnie odpowiada na pytanie. Jeśli potencjalne odpowiedzi nie spełniają progu ufności, model nie zwraca odpowiedzi. W celach demonstracyjnych pytanie w tym przykładzie zostało zaprojektowane tak, aby uzyskać odpowiedź, aby zobaczyć składnię.

SemanticAnswer.java Utwórz plik w src/main/java/com/azure/search/quickstart katalogu.

package com.azure.search.quickstart;

import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryAnswer;
import com.azure.search.documents.models.QueryAnswerResult;
import com.azure.search.documents.models.QueryAnswerType;
import com.azure.search.documents.models.QueryCaption;
import com.azure.search.documents.models.QueryCaptionResult;
import com.azure.search.documents.models.QueryCaptionType;
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;

import java.util.List;

public class SemanticAnswer {
    public static void main(String[] args) {
        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)
                .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);

        System.out.println("Answers:\n");

        // Extract semantic answers
        List<QueryAnswerResult> semanticAnswers =
            results.getSemanticResults().getQueryAnswers();
        int answerNumber = 1;

        if (semanticAnswers != null) {
            for (QueryAnswerResult answer : semanticAnswers) {
                System.out.printf("Semantic answer result #%d:%n",
                    answerNumber++);

                if (answer.getHighlights() != null &&
                    !answer.getHighlights().trim().isEmpty()) {
                    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%n",
                    answer.getScore());
            }
        }

        System.out.println("Search Results:\n");
        int rowNumber = 1;

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

            System.out.printf("Search result #%d:%n", rowNumber++);
            System.out.printf("Re-ranker Score: %.2f%n", rerankerScore);
            System.out.printf("Hotel: %s%n", document.get("HotelName"));
            System.out.printf("Description: %s%n",
                document.get("Description") != null ?
                    document.get("Description") : "N/A");

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

        System.exit(0);
    }
}

Skompiluj i uruchom kod.

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

Dane wyjściowe powinny wyglądać podobnie do poniższego przykładu, gdzie najlepsza odpowiedź na pytanie jest pobierana z jednego z wyników.

Pamiętaj, że odpowiedzi są dosłowną zawartością pobraną z indeksu i mogą brakować fraz, które użytkownik spodziewa się zobaczyć. Aby uzyskać złożone odpowiedzi wygenerowane przez model ukończenia czatu, rozważ użycie wzorca RAG lub agentowego pobierania danych.
```
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 library 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
```

Z tego przewodnika Szybki start dowiesz się, jak używać klasyfikacji semantycznej , dodając semantyczną konfigurację do indeksu wyszukiwania i dodając parametry semantyczne do zapytania. Możesz użyć pliku hotels-sample-index lub własnego.

W usłudze Azure AI Search semantyczna klasyfikacja to funkcja po stronie zapytania, która wykorzystuje zrozumienie odczytu maszynowego od firmy Microsoft w celu ponownego podkreślenia wyników wyszukiwania, promując najbardziej semantycznie istotne dopasowania na początku listy. W zależności od zawartości i zapytania semantyczny ranking może znacznie poprawić istotność wyszukiwania przy minimalnym wysiłku dewelopera.

Możesz dodać konfigurację semantyczną do istniejącego indeksu bez konieczności ponownego kompilowania. Ranking semantyczny jest najbardziej skuteczny w tekście, który jest informacyjny lub opisowy.

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Usługa Azure AI Search z włączonym semantycznym rankerem.
Nowy lub istniejący indeks z opisowymi lub rozwlekłymi polami tekstowymi, które są oznaczone jako możliwe do wyszukiwania. W tym przewodniku Szybki start zakłada się hotels-sample-index.

Konfigurowanie dostępu

Można nawiązać połączenie z usługą Azure AI Search przy użyciu kluczy API lub Microsoft Entra ID wraz z przypisaniami ról. Klucze są łatwiejsze do rozpoczęcia od, ale role są bezpieczniejsze. Aby uzyskać więcej informacji, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu ról.

Aby skonfigurować dostęp oparty na rolach:

Zaloguj się do witryny Azure Portal i wybierz usługę wyszukiwania.
W okienku po lewej stronie wybierz Ustawienia>Klucze.
W obszarze Kontrola dostępu do interfejsu API wybierz pozycję Kontrola dostępu oparta na rolach lub Obie , jeśli potrzebujesz czasu, aby przenieść klientów do dostępu opartego na rolach.
W okienku po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).
Wybierz Dodaj>Dodaj przypisanie roli.
Przypisz role Współautor usługi wyszukiwania i Współautor danych indeksu wyszukiwania do konta użytkownika.

Rozpoczynanie od indeksu

W tym przewodniku Szybki start założono, że istniejący indeks został zmodyfikowany w celu uwzględnienia konfiguracji semantycznej. Zalecamy hotels-sample-index, który można utworzyć w ciągu kilku minut za pomocą kreatora portalu Azure.

Aby rozpocząć od istniejącego indeksu:

Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.
W obszarze zarządzanie wyszukiwaniem>Indeksy, wybierz pozycję hotels-sample-index.
Wybierz pozycję Konfiguracje semantyczne , aby upewnić się, że indeks nie ma konfiguracji semantycznej.
Wybierz Eksplorator wyszukiwania, a następnie wybierz widok JSON.

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

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

Wybierz pozycję Wyszukaj , aby uruchomić zapytanie.

To zapytanie jest wyszukiwaniem słów kluczowych. Odpowiedź powinna być podobna do poniższego przykładu, jak oceniona przez domyślny ranker BM25 L1 przy wyszukiwaniu pełnotekstowym.

W celu zapewnienia czytelności przykład wybiera tylko pola HotelId, HotelName i Description. Wyniki zawierają dosłowne dopasowania terminów zapytania (walking, distance, , livemusic) lub wariantów językowych (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

To zapytanie pokazuje, jak wygląda odpowiedź przed zastosowaniem klasyfikacji semantycznej. Później możesz uruchomić to samo zapytanie po skonfigurowaniu klasyfikacji semantycznej, aby zobaczyć, jak zmienia się odpowiedź.

Wskazówka

Konfigurację semantyczną można dodać w witrynie Azure Portal. Jeśli jednak chcesz dowiedzieć się, jak programowo dodać konfigurację semantyczną, kontynuuj z tym szybkim startem.

Konfigurowanie klienta

W tym szybkim przewodniku dowiesz się, jak korzystać z notesu Jupyter i biblioteki azure-search-documents w zestawie Azure SDK dla języka Python do poznania rankingów semantycznych.

Na potrzeby tego przewodnika szybkiego startu zalecamy Visual Studio Code z Python 3.10 lub nowszy oraz rozszerzenie Python.

Wskazówka

Możesz pobrać gotowy notatnik i rozpocząć od ukończonego projektu lub wykonać te kroki, aby utworzyć własny.

W tym przewodniku Szybki start zalecamy środowisko wirtualne:

Uruchom program Visual Studio Code.
Otwórz plik semantic-search-quickstart.ipynb lub utwórz nowy notatnik.
Otwórz paletę poleceń przy użyciu Ctrl+Shift+P.
Wyszukaj frazę Python: Create Environment (Tworzenie środowiska).
Wybierz pozycję Venv.
Wybierz interpreter języka Python. Wybierz 3.10 lub nowszą.

Skonfigurowanie może potrwać minutę. Jeśli wystąpią problemy, zobacz Środowiska języka Python w programie VS Code.

Instalowanie pakietów i ustawianie zmiennych środowiskowych

Zainstaluj pakiety, w tym azure-search-documents.
```
! pip install -r requirements.txt --quiet
```
Zmień nazwę sample.env na .env, a następnie podaj punkt końcowy usługi wyszukiwania. Punkt końcowy można uzyskać z portalu Azure na stronie Przegląd usługi wyszukiwania.
```
AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
```

Jeśli zalogowałeś się do witryny Azure Portal, zalogowałeś się na platformie Azure. Jeśli nie masz pewności, zaloguj się przy użyciu interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell: az login lub az connect. Jeśli masz wiele dzierżaw i subskrypcji, zobacz Szybki start: nawiązywanie połączenia bez kluczy , aby uzyskać pomoc dotyczącą nawiązywania połączenia.

Aktualizowanie indeksu

W tej sekcji zaktualizujesz indeks wyszukiwania, aby uwzględnić konfigurację semantyczną. Kod pobiera definicję indeksu z usługi wyszukiwania i dodaje konfigurację semantyczną.

Otwórz plik semantic-search-quickstart.ipynb w programie Visual Studio Code lub utwórz nowy plik.

Podaj zmienne używane w rozwiązaniu.

# Provide variables
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
import os

load_dotenv(override=True) # Take environment variables from .env.

# The following variables from your .env file are used in this notebook
search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://search.azure.com/.default")
index_name = os.getenv("AZURE_SEARCH_INDEX", "hotels-sample-index")

Utwórz element SearchIndexClient i pobierz istniejący plik hotels-sample-index.

from azure.search.documents.indexes import SearchIndexClient
from azure.identity import DefaultAzureCredential
import os

# Initialize the client (similar to what you already have)
search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
index_name = "hotels-sample-index"  # or use your existing index_name variable

# Create the SearchIndexClient
index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)

try:
    # Get the existing index schema
    index = index_client.get_index(index_name)

    print(f"Index name: {index.name}")
    print(f"Number of fields: {len(index.fields)}")

    # Print field details
    for field in index.fields:
        print(f"Field: {field.name}, Type: {field.type}, Searchable: {field.searchable}")

    # Access semantic configuration if it exists
    if index.semantic_search and index.semantic_search.configurations:
        for config in index.semantic_search.configurations:
            print(f"Semantic config: {config.name}")
            if config.prioritized_fields.title_field:
                print(f"Title field: {config.prioritized_fields.title_field.field_name}")
    else:
        print("No semantic configuration exists for this index")

except Exception as ex:
    print(f"Error retrieving index: {ex}")

Uruchom kod.
Dane wyjściowe to nazwa indeksu, lista pól i instrukcja wskazująca, czy istnieje konfiguracja semantyczna. Na potrzeby tego przewodnika Szybki Start komunikat powinien brzmieć: "Dla tego indeksu nie istnieje żadna konfiguracja semantyczna".

Dodaj konfigurację semantyczną do istniejącego indeksu hotels-sample-index w usłudze wyszukiwania. Ta operacja nie usuwa dokumentów wyszukiwania, a indeks nadal działa po dodaniu konfiguracji.

# Add semantic configuration to hotels-sample-index and display updated index details
from azure.search.documents.indexes.models import (
    SemanticConfiguration,
    SemanticField,
    SemanticPrioritizedFields,
    SemanticSearch
)

try:
    # Get the existing index
    existing_index = index_client.get_index(index_name)

    # Create a new semantic configuration
    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")]
        )
    )

    # Add semantic configuration to the index
    if existing_index.semantic_search is None:
        existing_index.semantic_search = SemanticSearch(configurations=[new_semantic_config])
    else:
        # Check if configuration already exists
        config_exists = any(config.name == "semantic-config" 
                          for config in existing_index.semantic_search.configurations)
        if not config_exists:
            existing_index.semantic_search.configurations.append(new_semantic_config)

    # Update the index
    result = index_client.create_or_update_index(existing_index)

    # Get the updated index and display detailed information
    updated_index = index_client.get_index(index_name)

    print("Semantic configurations:")
    print("-" * 40)
    if updated_index.semantic_search and updated_index.semantic_search.configurations:
        for config in updated_index.semantic_search.configurations:
            print(f"  Configuration: {config.name}")
            if config.prioritized_fields.title_field:
                print(f"    Title field: {config.prioritized_fields.title_field.field_name}")
            if config.prioritized_fields.keywords_fields:
                keywords = [kf.field_name for kf in config.prioritized_fields.keywords_fields]
                print(f"    Keywords fields: {', '.join(keywords)}")
            if config.prioritized_fields.content_fields:
                content = [cf.field_name for cf in config.prioritized_fields.content_fields]
                print(f"    Content fields: {', '.join(content)}")
            print()
    else:
        print("  No semantic configurations found")

    print("✅ Semantic configuration successfully added!")

except Exception as ex:
    print(f"❌ Error adding semantic configuration: {ex}")

Uruchom kod.
Dane wyjściowe to właśnie dodana konfiguracja semantyczna.

Uruchamianie zapytań semantycznych

Gdy indeks ma konfigurację semantyczną, można uruchamiać zapytania zawierające parametry semantyczne.

Utwórz element SearchClient i żądanie zapytania, które zawiera typ zapytania semantycznego i konfigurację semantyczną. Jest to minimalne wymaganie dotyczące wywoływania semantycznego rankingu.

# Set up the search client
search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

# Runs a semantic query (runs a BM25-ranked query, rescoring and promoting the most semantically relevant matches to the top)
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')

for result in results:
    print(result["@search.reranker_score"])
    print(result["HotelId"])
    print(result["HotelName"])
    print(f"Description: {result['Description']}")

Uruchom kod.
Dane wyjściowe powinny składać się z 13 dokumentów uporządkowanych przez element "@search.reranker_score".

Przywracanie napisów

Opcjonalnie możesz dodać podpisy, aby wyodrębnić fragmenty tekstu i zastosować wyróżnianie trafień do ważnych terminów i fraz. To zapytanie SQL dodaje podpisy.

Dodaj captions do zapytania.

# Runs a semantic query that returns captions
results =  search_client.search(query_type='semantic', semantic_configuration_name='semantic-config',
    search_text="walking distance to live music", 
    select='HotelName,HotelId,Description', query_caption='extractive')

for result in results:
    print(result["@search.reranker_score"])
    print(result["HotelId"])
    print(result["HotelName"])
    print(f"Description: {result['Description']}")

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

Uruchom kod.

Dane wyjściowe powinny zawierać nowy element nagłówka obok pola wyszukiwania. Nagłówki są najbardziej istotnymi fragmentami wewnątrz wyniku. Jeśli indeks zawiera większe fragmenty tekstu, podpisy mogą być pomocne do wyodrębnienia 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.

Zwracanie odpowiedzi semantycznych

W tym ostatnim zapytaniu zwróć semantyczne odpowiedzi.

Semantyczny ranker może wygenerować odpowiedź na ciąg zapytaniowy, który wykazuje cechy pytania. Wygenerowana odpowiedź jest wyodrębniona z zawartości, więc nie będzie zawierać zawartości skomponowanej, takiej jak to, czego można oczekiwać od modelu ukończenia czatu. Jeśli semantyczna odpowiedź nie jest przydatna w danym scenariuszu, możesz pominąć semantic_answers ze swojego kodu.

Aby utworzyć semantyczną odpowiedź, pytanie i odpowiedź muszą być ściśle dopasowane, a model musi znaleźć zawartość, która wyraźnie odpowiada na pytanie. Jeśli potencjalne odpowiedzi nie spełniają progu ufności, model nie zwraca odpowiedzi. W celach demonstracyjnych pytanie w tym przykładzie zostało zaprojektowane tak, aby uzyskać odpowiedź, aby zobaczyć składnię.

Dodaj answers do zapytania.

# Run a semantic query that returns semantic answers  
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")

for result in results:
    print(result["@search.reranker_score"])
    print(result["HotelName"])
    print(f"Description: {result['Description']}")

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

Uruchom kod.

Dane wyjściowe powinny wyglądać podobnie do poniższego przykładu, gdzie najlepsza odpowiedź na pytanie jest pobierana z jednego z wyników.

Pamiętaj, że odpowiedzi są dosłowną zawartością pobraną z indeksu i mogą brakować fraz, które użytkownik spodziewa się zobaczyć. Aby uzyskać złożone odpowiedzi wygenerowane przez model ukończenia czatu, rozważ użycie wzorca RAG lub agentowego pobierania danych.

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

2.124817371368408
1
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.

2.0705394744873047
16
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.

2.041472911834717
38
Lakeside B & B
Description: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Caption: 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.

2.084540843963623
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<em> city. #1 </em>Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.

...

Z tego przewodnika Szybki start dowiesz się, jak używać klasyfikacji semantycznej , dodając semantyczną konfigurację do indeksu wyszukiwania i dodając parametry semantyczne do zapytania. Możesz użyć pliku hotels-sample-index lub własnego.

W usłudze Azure AI Search semantyczna klasyfikacja to funkcja po stronie zapytania, która wykorzystuje zrozumienie odczytu maszynowego od firmy Microsoft w celu ponownego podkreślenia wyników wyszukiwania, promując najbardziej semantycznie istotne dopasowania na początku listy. W zależności od zawartości i zapytania semantyczny ranking może znacznie poprawić istotność wyszukiwania przy minimalnym wysiłku dewelopera.

Możesz dodać konfigurację semantyczną do istniejącego indeksu bez konieczności ponownego kompilowania. Ranking semantyczny jest najbardziej skuteczny w tekście, który jest informacyjny lub opisowy.

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Usługa Azure AI Search z włączonym semantycznym rankerem.
Nowy lub istniejący indeks z opisowymi lub rozwlekłymi polami tekstowymi, które są oznaczone jako możliwe do wyszukiwania. W tym przewodniku Szybki start zakłada się hotels-sample-index.

Konfigurowanie dostępu

Można nawiązać połączenie z usługą Azure AI Search przy użyciu kluczy API lub Microsoft Entra ID wraz z przypisaniami ról. Klucze są łatwiejsze do rozpoczęcia od, ale role są bezpieczniejsze. Aby uzyskać więcej informacji, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu ról.

Aby skonfigurować dostęp oparty na rolach:

Zaloguj się do witryny Azure Portal i wybierz usługę wyszukiwania.
W okienku po lewej stronie wybierz Ustawienia>Klucze.
W obszarze Kontrola dostępu do interfejsu API wybierz pozycję Kontrola dostępu oparta na rolach lub Obie , jeśli potrzebujesz czasu, aby przenieść klientów do dostępu opartego na rolach.
W okienku po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).
Wybierz Dodaj>Dodaj przypisanie roli.
Przypisz role Współautor usługi wyszukiwania i Współautor danych indeksu wyszukiwania do konta użytkownika.

Rozpoczynanie od indeksu

W tym przewodniku Szybki start założono, że istniejący indeks został zmodyfikowany w celu uwzględnienia konfiguracji semantycznej. Zalecamy hotels-sample-index, który można utworzyć w ciągu kilku minut za pomocą kreatora portalu Azure.

Aby rozpocząć od istniejącego indeksu:

Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.
W obszarze zarządzanie wyszukiwaniem>Indeksy, wybierz pozycję hotels-sample-index.
Wybierz pozycję Konfiguracje semantyczne , aby upewnić się, że indeks nie ma konfiguracji semantycznej.
Wybierz Eksplorator wyszukiwania, a następnie wybierz widok JSON.

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

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

Wybierz pozycję Wyszukaj , aby uruchomić zapytanie.

To zapytanie jest wyszukiwaniem słów kluczowych. Odpowiedź powinna być podobna do poniższego przykładu, jak oceniona przez domyślny ranker BM25 L1 przy wyszukiwaniu pełnotekstowym.

W celu zapewnienia czytelności przykład wybiera tylko pola HotelId, HotelName i Description. Wyniki zawierają dosłowne dopasowania terminów zapytania (walking, distance, , livemusic) lub wariantów językowych (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

To zapytanie pokazuje, jak wygląda odpowiedź przed zastosowaniem klasyfikacji semantycznej. Później możesz uruchomić to samo zapytanie po skonfigurowaniu klasyfikacji semantycznej, aby zobaczyć, jak zmienia się odpowiedź.

Wskazówka

Konfigurację semantyczną można dodać w witrynie Azure Portal. Jeśli jednak chcesz dowiedzieć się, jak programowo dodać konfigurację semantyczną, kontynuuj z tym szybkim startem.

Konfigurowanie klienta

W tym przewodniku szybkiego startu korzystasz z klienta REST i interfejsów API REST usługi Azure AI Search do konfiguracji i używania rankera semantycznego.

Zalecamy użycie Visual Studio Code z zainstalowanym rozszerzeniem klienta REST do tej szybkiej konfiguracji.

Wskazówka

Możesz pobrać kod źródłowy , aby rozpocząć od ukończonego projektu lub wykonać następujące kroki, aby utworzyć własny.

Uruchom program Visual Studio Code i otwórz plik semantic-search-index-update.rest lub utwórz nowy plik.
U góry ustaw zmienne środowiskowe dla usługi wyszukiwania, autoryzacji i nazwy indeksu.
- W polu @searchURLzaloguj się do witryny Azure Portal i skopiuj adres URL ze strony Przegląd usługi wyszukiwania.
- W przypadku @personalAccessToken, postępuj zgodnie z instrukcjami w temacie Łączenie bez kluczy, aby uzyskać osobisty token dostępu.

Aby przetestować połączenie, wyślij pierwsze żądanie.

### List existing indexes by name (verify the connection)
 GET  {{searchUrl}}/indexes?api-version=2025-09-01&$select=name  HTTP/1.1
 Authorization: Bearer {{personalAccessToken}}

Wybierz pozycję Wyślij żądanie.
Dane wyjściowe dla tego żądania GET zwracają listę istniejących indeksów. Powinien zostać wyświetlony kod stanu powodzenia HTTP 200 oraz lista indeksów, w tym hotels-sample-index używana w tym przewodniku Szybki start.

Aktualizowanie indeksu

Aby zaktualizować indeks przy użyciu interfejsu API REST, należy podać cały schemat oraz modyfikacje, które chcesz wprowadzić. To żądanie zawiera schemat hotels-sample-index oraz konfigurację semantyczną. Modyfikacja składa się z następującego kodu JSON.

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

Sformułuj żądanie PUT określające nazwę indeksu, operację i pełny schemat JSON. Wszystkie wymagane elementy schematu muszą być obecne. To żądanie zawiera pełny schemat dla hotels-sample-index oraz konfigurację semantyczną.

PUT {{searchUrl}}/indexes/hotels-sample-index?api-version=2025-09-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{personalAccessToken}}

{
   "name": "hotels-sample-index",
   "fields": [
       { "name": "HotelId", "type": "Edm.String", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "key": true },
       { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
       { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
       { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
       { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
       { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
       { "name": "ParkingIncluded", "type": "Edm.Boolean", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
       { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "searchable": false, "filterable": false, "retrievable": true, "stored": true, "sortable": true, "facetable": false },
       { "name": "Rating", "type": "Edm.Double", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": true, "facetable": true },
       { "name": "Address", "type": "Edm.ComplexType", "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
          { "name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" }]},
       { "name": "Location", "type": "Edm.GeographyPoint", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": true, "facetable": false },
       { "name": "Rooms", "type": "Collection(Edm.ComplexType)", "fields": [
          { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
          { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
          { "name": "Type", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "BaseRate", "type": "Edm.Double", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
          { "name": "BedOptions", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "SleepsCount", "type": "Edm.Int64", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
          { "name": "SmokingAllowed", "type": "Edm.Boolean", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
          { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" }]},
       { "name": "id", "type": "Edm.String", "searchable": false, "filterable": false, "retrievable": false, "stored": true, "sortable": false, "facetable": false },
       { "name": "rid", "type": "Edm.String", "searchable": false, "filterable": false, "retrievable": false, "stored": true, "sortable": false, "facetable": false }],
  "scoringProfiles": [],
  "suggesters": [],
  "analyzers": [],
  "normalizers": [],
  "tokenizers": [],
  "tokenFilters": [],
  "charFilters": [],
  "similarity": {
    "@odata.type": "#Microsoft.Azure.Search.BM25Similarity"
  },
  "semantic": {
    "configurations": [
      {
        "name": "semantic-config",
        "rankingOrder": "BoostedRerankerScore",
        "prioritizedFields": {
          "titleField": {
            "fieldName": "HotelName"
          },
          "prioritizedContentFields": [
            {
              "fieldName": "Description"
            }
          ],
          "prioritizedKeywordsFields": [
            {
              "fieldName": "Tags"
            }
          ]
        }
      }
    ]
  }
}

Wybierz pozycję Wyślij żądanie.
Dane wyjściowe tego żądania POST to komunikat o stanie HTTP 200 Success.

Uruchamianie zapytań semantycznych

Wymagane parametry semantyczne obejmują query_type i semantic_configuration_name. Oto przykład podstawowego zapytania semantycznego używającego minimalnych parametrów.

Otwórz plik semantic-search-query.rest lub utwórz nowy plik.
Na górze pliku ustaw zmienne środowiskowe dla usługi wyszukiwania, autoryzacji i nazwy indeksu.
- W polu @searchURLzaloguj się do witryny Azure Portal i skopiuj adres URL ze strony Przegląd usługi wyszukiwania.
- W przypadku @personalAccessToken, postępuj zgodnie z instrukcjami w temacie Łączenie bez kluczy, aby uzyskać osobisty token dostępu.

Przetestuj połączenie za pomocą żądania GET, które zwraca hotels-sample-index.

GET {{searchUrl}}/indexes/hotels-sample-index?api-version=2025-09-01  HTTP/1.1
Authorization: Bearer {{personalAccessToken}}

Wyślij zapytanie zawierające semantyczne typ zapytania i nazwę konfiguracji.

 POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-09-01  HTTP/1.1
 Content-Type: application/json
 Authorization: Bearer {{personalAccessToken}}

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

Dane wyjściowe składają się z wyników wyszukiwania w formacie JSON. Trzynaście hoteli pasuje do zapytania. Pierwsze siedem znajduje się w tym przykładzie.

{
   "@odata.count": 13,
   "@search.answers": [],
   "value": [
     {
       "@search.score": 5.074317,
       "@search.rerankerScore": 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.score": 5.5153193,
       "@search.rerankerScore": 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.score": 4.8959594,
       "@search.rerankerScore": 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."
     },
     {
       "@search.score": 0.7334347,
       "@search.rerankerScore": 1.9615401029586792,
       "HotelId": "39",
       "HotelName": "White Mountain Lodge & Suites",
       "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
     },
     {
       "@search.score": 1.5502293,
       "@search.rerankerScore": 1.9085469245910645,
       "HotelId": "15",
       "HotelName": "By the Market Hotel",
       "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
     },
     {
       "@search.score": 1.7595702,
       "@search.rerankerScore": 1.90234375,
       "HotelId": "49",
       "HotelName": "Swirling Currents Hotel",
       "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
     },
     {
       "@search.score": 2.0364518,
       "@search.rerankerScore": 1.9012802839279175,
       "HotelId": "31",
       "HotelName": "Country Residence Hotel",
       "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
     }
   ]
 }

Przywracanie napisów

Opcjonalnie możesz dodać podpisy, aby wyodrębnić fragmenty tekstu i zastosować wyróżnianie trafień do ważnych terminów i fraz. To zapytanie dodaje etykiety, które zawierają podświetlanie wyników wyszukiwania.

captions Dodaj parametr i wyślij żądanie.

POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-09-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{personalAccessToken}}

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

Dane wyjściowe składają się z tych samych wyników, z dodatkiem "@search.captions". Oto kod JSON pojedynczego dokumentu. Każde dopasowanie obejmuje wyniki wyszukiwania, podpisy w postaci zwykłego tekstu, formatowanie wyróżnienia oraz wybrane pola.

{
   "@search.score": 5.074317,
   "@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. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
       "highlights": "Chic hotel near the city. 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."
}

Zwracanie odpowiedzi semantycznych

W tym ostatnim zapytaniu zwróć semantyczne odpowiedzi.

Semantyczny ranker może wygenerować odpowiedź na ciąg zapytaniowy, który wykazuje cechy pytania. Wygenerowana odpowiedź jest wyodrębniona z zawartości, więc nie będzie zawierać zawartości skomponowanej, takiej jak to, czego można oczekiwać od modelu ukończenia czatu. Jeśli semantyczna odpowiedź nie jest przydatna w danym scenariuszu, możesz pominąć semantic_answers ze swojego kodu.

Aby utworzyć semantyczną odpowiedź, pytanie i odpowiedź muszą być ściśle dopasowane, a model musi znaleźć zawartość, która wyraźnie odpowiada na pytanie. Jeśli potencjalne odpowiedzi nie spełniają progu ufności, model nie zwraca odpowiedzi. W celach demonstracyjnych pytanie w tym przykładzie zostało zaprojektowane tak, aby uzyskać odpowiedź, aby zobaczyć składnię.

Sformułuj żądanie przy użyciu ciągu wyszukiwania, który zadaje pytanie.

POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-09-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{personalAccessToken}}

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

Dane wyjściowe składają się z 41 wyników dla nowego zapytania z "@search.odpowiedzi" dla pytania w zapytaniu dotyczącym hoteli dla osób, które lubią czytać.

Pamiętaj, że odpowiedzi są dosłowną zawartością pobraną z indeksu i mogą brakować fraz, które użytkownik spodziewa się zobaczyć. Aby uzyskać złożone odpowiedzi wygenerowane przez model ukończenia czatu, rozważ użycie wzorca RAG lub agentowego pobierania danych.

W tym przykładzie odpowiedź jest uznawana za dobrze dopasowaną do pytania.

{
  "@odata.count": 41,
  "@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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our 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.",
      "score": 0.9829999804496765
    }
  ],
  "value": [
    {
      "@search.score": 2.0361428,
      "@search.rerankerScore": 2.124817371368408,
      "HotelId": "1",
      "HotelName": "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."
    },
    {
      "@search.score": 3.759768,
      "@search.rerankerScore": 2.0705394744873047,
      "HotelId": "16",
      "HotelName": "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."
    },
    {
      "@search.score": 0.7308748,
      "@search.rerankerScore": 2.041472911834717,
      "HotelId": "38",
      "HotelName": "Lakeside B & B",
      "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
    },
    {
      "@search.score": 3.391012,
      "@search.rerankerScore": 2.0231292247772217,
      "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": 1.3198771,
      "@search.rerankerScore": 2.021622657775879,
      "HotelId": "15",
      "HotelName": "By the Market Hotel",
      "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
    },
    {
      "@search.score": 1.3983066,
      "@search.rerankerScore": 2.005582809448242,
      "HotelId": "5",
      "HotelName": "Red Tide Hotel",
      "Description": "On entering this charming hotel in Scarlet Harbor, you'll notice an uncommon blend of antiques, original artwork, and contemporary comforts that give this hotel its signature look. Each suite is furnished to accentuate the views and unique characteristics of the building's classic architecture. No two suites are alike. However, all guests are welcome in the mezzanine plaza, the surrounding gardens, and the northside terrace for evening refreshments."
    },
    {
      "@search.score": 1.4815493,
      "@search.rerankerScore": 1.9739465713500977,
      "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."
    }
  ]
}

Z tego przewodnika Szybki start dowiesz się, jak używać klasyfikacji semantycznej , dodając semantyczną konfigurację do indeksu wyszukiwania i dodając parametry semantyczne do zapytania. Możesz użyć pliku hotels-sample-index lub własnego.

W usłudze Azure AI Search semantyczna klasyfikacja to funkcja po stronie zapytania, która wykorzystuje zrozumienie odczytu maszynowego od firmy Microsoft w celu ponownego podkreślenia wyników wyszukiwania, promując najbardziej semantycznie istotne dopasowania na początku listy. W zależności od zawartości i zapytania semantyczny ranking może znacznie poprawić istotność wyszukiwania przy minimalnym wysiłku dewelopera.

Możesz dodać konfigurację semantyczną do istniejącego indeksu bez konieczności ponownego kompilowania. Ranking semantyczny jest najbardziej skuteczny w tekście, który jest informacyjny lub opisowy.

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Usługa Azure AI Search z włączonym semantycznym rankerem.
Nowy lub istniejący indeks z opisowymi lub rozwlekłymi polami tekstowymi, które są oznaczone jako możliwe do wyszukiwania. W tym przewodniku Szybki start zakłada się hotels-sample-index.

Konfigurowanie dostępu

Można nawiązać połączenie z usługą Azure AI Search przy użyciu kluczy API lub Microsoft Entra ID wraz z przypisaniami ról. Klucze są łatwiejsze do rozpoczęcia od, ale role są bezpieczniejsze. Aby uzyskać więcej informacji, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu ról.

Aby skonfigurować dostęp oparty na rolach:

Zaloguj się do witryny Azure Portal i wybierz usługę wyszukiwania.
W okienku po lewej stronie wybierz Ustawienia>Klucze.
W obszarze Kontrola dostępu do interfejsu API wybierz pozycję Kontrola dostępu oparta na rolach lub Obie , jeśli potrzebujesz czasu, aby przenieść klientów do dostępu opartego na rolach.
W okienku po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).
Wybierz Dodaj>Dodaj przypisanie roli.
Przypisz role Współautor usługi wyszukiwania i Współautor danych indeksu wyszukiwania do konta użytkownika.

Rozpoczynanie od indeksu

W tym przewodniku Szybki start założono, że istniejący indeks został zmodyfikowany w celu uwzględnienia konfiguracji semantycznej. Zalecamy hotels-sample-index, który można utworzyć w ciągu kilku minut za pomocą kreatora portalu Azure.

Aby rozpocząć od istniejącego indeksu:

Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.
W obszarze zarządzanie wyszukiwaniem>Indeksy, wybierz pozycję hotels-sample-index.
Wybierz pozycję Konfiguracje semantyczne , aby upewnić się, że indeks nie ma konfiguracji semantycznej.
Wybierz Eksplorator wyszukiwania, a następnie wybierz widok JSON.

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

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

Wybierz pozycję Wyszukaj , aby uruchomić zapytanie.

To zapytanie jest wyszukiwaniem słów kluczowych. Odpowiedź powinna być podobna do poniższego przykładu, jak oceniona przez domyślny ranker BM25 L1 przy wyszukiwaniu pełnotekstowym.

W celu zapewnienia czytelności przykład wybiera tylko pola HotelId, HotelName i Description. Wyniki zawierają dosłowne dopasowania terminów zapytania (walking, distance, , livemusic) lub wariantów językowych (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

To zapytanie pokazuje, jak wygląda odpowiedź przed zastosowaniem klasyfikacji semantycznej. Później możesz uruchomić to samo zapytanie po skonfigurowaniu klasyfikacji semantycznej, aby zobaczyć, jak zmienia się odpowiedź.

Wskazówka

Konfigurację semantyczną można dodać w witrynie Azure Portal. Jeśli jednak chcesz dowiedzieć się, jak programowo dodać konfigurację semantyczną, kontynuuj z tym szybkim startem.

Konfigurowanie klienta

W tym szybkim przewodniku użyjesz IDE i biblioteki klienta @azure/search-documents aby dodać ranking semantyczny do istniejącego indeksu wyszukiwania.

W przewodniku Szybki start założono, że na komputerze są dostępne następujące elementy:

Program Visual Studio Code dla tego szybkiego przewodnika wprowadzającego.
Node.js (LTS) na potrzeby uruchamiania przykładu.
TypeScript do pisania przykładowego kodu.

Wskazówka

Możesz pobrać kod źródłowy , aby rozpocząć od ukończonego projektu lub wykonać następujące kroki, aby utworzyć własny.

Konfigurowanie lokalnego środowiska deweloperskiego

Uruchom program Visual Studio Code w nowym katalogu.

mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
code .

Utwórz nowy pakiet dla modułów ESM w katalogu projektu.
```
npm init -y
npm pkg set type=module
```
Zainstaluj pakiety programistyczne, w tym azure-search-documents.
```
npm install @azure/identity @azure/search-documents dotenv
```
Instalowanie pakietów zależności programistycznych.
```
npm install dotenv @types/node --save-dev
```

Utwórz plik tsconfig.json w katalogu projektu, aby włączyć moduły ESM i ustawić rozdzielczość modułu.

 {
   "compilerOptions": {
     "target": "es2022",
     "module": "esnext",
     "moduleResolution": "bundler",
     "rootDir": "./src",
     "outDir": "./dist/",
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "strict": true,
     "skipLibCheck": true,
     "declaration": true,
     "sourceMap": true,
     "resolveJsonModule": true,
     "moduleDetection": "force",
     "allowSyntheticDefaultImports": true,
     "verbatimModuleSyntax": false
   },
   "include": [
     "src/**/*.ts"
   ],
   "exclude": [
     "node_modules/**/*",
     "**/*.spec.ts"
   ]
 }

Aktualizacja package.json w celu uwzględnienia skryptu do kompilowania plików TypeScript. Dodaj następujący wiersz do scripts sekcji.
```
"build": "tsc"
```
Utwórz .env, i podaj punkt końcowy usługi wyszukiwania. Punkt końcowy można uzyskać z portalu Azure na stronie Przegląd usługi wyszukiwania.
```
AZURE_SEARCH_ENDPOINT=YOUR-SEARCH-SERVICE-ENDPOINT
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
SEMANTIC_CONFIGURATION_NAME=semantic-config
```
Utwórz katalog src w katalogu projektu.
```
mkdir src
```

Jeśli zalogowałeś się do witryny Azure Portal, zalogowałeś się na platformie Azure. Jeśli nie masz pewności, zaloguj się przy użyciu interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell: az login lub az connect. Jeśli masz wiele dzierżaw i subskrypcji, zobacz Szybki start: nawiązywanie połączenia bez kluczy , aby uzyskać pomoc dotyczącą nawiązywania połączenia.

Tworzenie wspólnego pliku uwierzytelniania

Utwórz plik w ./src o nazwie config.ts, aby odczytać plik .env i przechowywać zmienne środowiskowe oraz poświadczenia uwierzytelniania. Skopiuj poniższy kod; nie zmieniaj go. Ten plik będzie używany przez wszystkie inne pliki w tym przewodniku Szybki start.

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

// Configuration - use environment variables
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-index";
export const semanticConfigurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";

// Create credential
export const credential = new DefaultAzureCredential();

console.log(`Using Azure Search endpoint: ${searchEndpoint}`);
console.log(`Using index name: ${indexName}\n\n`);

// Hotel document interface
export interface HotelDocument {
    "@search.action"?: string;
    HotelId: string;
    HotelName: string;
    Description: string;
    Category: string;
    Tags: string[];
    ParkingIncluded: string;
    LastRenovationDate: string;
    Rating: number;
    Address: {
        StreetAddress: string;
        City: string;
        StateProvince: string;
        PostalCode: string;
        Country: string;
    };
}

Pobieranie schematu indeksu

W tej sekcji uzyskasz ustawienia istniejącego hotels-sample-index indeksu w usłudze wyszukiwania.

Utwórz plik w ./src nazwie getIndexSettings.ts i skopiuj go w poniższym kodzie.

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

const indexClient = new SearchIndexClient(searchEndpoint, credential);

console.log('Updating semantic search index...');

// Get the existing schema
const index = await indexClient.getIndex(indexName);

console.log(`Index name: ${index.name}`);
console.log(`Number of fields: ${index.fields.length}`);

for(const field of index.fields) {

    // @ts-ignore
    console.log(`Field: ${field.name}, Type: ${field.type}, Searchable: ${field.searchable}`);
}

if(index.semanticSearch && index.semanticSearch.configurations) {
    console.log(`Semantic search configurations: ${index.semanticSearch.configurations.length}`);
    for(const config of index.semanticSearch.configurations) {
        console.log(`Configuration name: ${config.name}`);
        console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
    }
} else {
    console.log("No semantic configuration exists for this index.");
}

Uruchom kod.

npm run build && node -r dotenv/config dist/getIndexSettings.js

Dane wyjściowe to nazwa indeksu, lista pól i instrukcja wskazująca, czy istnieje konfiguracja semantyczna. Na potrzeby tego szybkiego startu, komunikat powinien mówić No semantic configuration exists for this index.

Aktualizowanie indeksu przy użyciu konfiguracji semantycznej

Utwórz plik w ./src o nazwie updateIndexSettings.ts i skopiuj poniższy kod, aby dodać konfigurację semantyczną w istniejącym indeksie hotels-sample-index w swojej usłudze wyszukiwania. Ta operacja nie usuwa dokumentów wyszukiwania, a indeks nadal działa po dodaniu konfiguracji.

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

try {

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

    // Add the new semantic configuration to the existing index
    if (existingIndex.semanticSearch && existingIndex.semanticSearch.configurations) {
        existingIndex.semanticSearch.configurations.push(newSemanticConfiguration);
    } else {
        const configExists = existingIndex.semanticSearch?.configurations?.some(
            config => config.name === semanticConfigurationName
        );
        if (!configExists) {
            existingIndex.semanticSearch = {
                configurations: [newSemanticConfiguration]
            };
        }
    }

    await indexClient.createOrUpdateIndex(existingIndex);

    const updatedIndex = await indexClient.getIndex(indexName);

    console.log(`Semantic configurations:`);
    console.log("-".repeat(40));

    if (updatedIndex.semanticSearch && updatedIndex.semanticSearch.configurations) {
        for (const config of updatedIndex.semanticSearch.configurations) {
            console.log(`Configuration name: ${config.name}`);
            console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
            console.log(`Keywords fields: ${config.prioritizedFields.keywordsFields?.map(f => f.name).join(", ")}`);
            console.log(`Content fields: ${config.prioritizedFields.contentFields?.map(f => f.name).join(", ")}`);
            console.log("-".repeat(40));
        }
    } else {
        console.log("No semantic configurations found.");
    }

    console.log("Semantic configuration updated successfully.");
} catch (error) {
    console.error("Error updating semantic configuration:", error);
}

Uruchom kod.

npm run build && node -r dotenv/config dist/updateIndexSettings.js

Dane wyjściowe stanowią właśnie dodaną konfigurację semantyczną, Semantic configuration updated successfully..

Uruchamianie zapytań semantycznych

hotels-sample-index Gdy indeks ma konfigurację semantyczną, można uruchamiać zapytania zawierające parametry semantyczne.

Utwórz plik w ./src o nazwie semanticQuery.ts i skopiuj do niego poniższy kod, aby utworzyć semantyczne zapytanie indeksu. Jest to minimalne wymaganie dotyczące wywoływania semantycznego rankingu.

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

let rowNumber = 1;
for await (const result of results.results) {

    // Log each result
    const doc = result.document;
    const score = result.score;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelId: ${doc.HotelId}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);
}

Uruchom kod.

npm run build && node -r dotenv/config dist/semanticQuery.js

Dane wyjściowe powinny składać się z 13 dokumentów uporządkowanych przez element rerankerScoreDisplay.

Przywracanie napisów

Opcjonalnie możesz dodać podpisy, aby wyodrębnić fragmenty tekstu i zastosować wyróżnianie trafień do ważnych terminów i fraz. To zapytanie SQL dodaje podpisy.

Utwórz plik w ./src o nazwie semanticQueryReturnCaptions.ts i skopiuj poniższy kod, aby dodać napisy do zapytania.

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

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

// Debug info
console.log(`Using semantic configuration: ${semanticConfigurationName}`);
console.log("Search query: walking distance to live music");

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

console.log(`Found ${results.count} results with semantic search\n`);
let rowNumber = 1;

for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);

    // Caption handling with better debugging
    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];

        if (caption.highlights) {
            console.log(`  Caption with highlights: ${caption.highlights}`);
        } else if (caption.text) {
            console.log(`  Caption text: ${caption.text}`);
        } else {
            console.log(`  Caption exists but has no text or highlights content`);
        }
    } else {
        console.log("  No captions found for this result");
    }
    console.log("-".repeat(60));
}

Uruchom kod.

npm run build && node -r dotenv/config dist/semanticQueryReturnCaptions.js

Dane wyjściowe powinny zawierać nowy element nagłówka obok pola wyszukiwania. Nagłówki są najbardziej istotnymi fragmentami wewnątrz wyniku. Jeśli indeks zawiera większe fragmenty tekstu, podpisy mogą być pomocne do wyodrębnienia 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.

Zwracanie odpowiedzi semantycznych

W tym ostatnim zapytaniu zwróć semantyczne odpowiedzi.

Semantyczny ranker może wygenerować odpowiedź na ciąg zapytaniowy, który wykazuje cechy pytania. Wygenerowana odpowiedź jest wyodrębniona z zawartości, więc nie będzie zawierać zawartości skomponowanej, takiej jak to, czego można oczekiwać od modelu ukończenia czatu. Jeśli semantyczna odpowiedź nie jest przydatna w danym scenariuszu, możesz pominąć semantic_answers ze swojego kodu.

Aby utworzyć semantyczną odpowiedź, pytanie i odpowiedź muszą być ściśle dopasowane, a model musi znaleźć zawartość, która wyraźnie odpowiada na pytanie. Jeśli potencjalne odpowiedzi nie spełniają progu ufności, model nie zwraca odpowiedzi. W celach demonstracyjnych pytanie w tym przykładzie zostało zaprojektowane tak, aby uzyskać odpowiedź, aby zobaczyć składnię.

Utwórz plik o nazwie ./src w semanticAnswer.ts i skopiuj poniższy kod, aby uzyskać odpowiedzi semantyczne.

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

console.log(`Answers:\n\n`);
let rowNumber = 1; 

// Extract semantic answers from the search results
const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    console.log(`Semantic answer result #${rowNumber++}:`);
    if (answer.highlights) {
        console.log(`Semantic Answer: ${answer.highlights}`);
    } else {
        console.log(`Semantic Answer: ${answer.text}`);
    }
    console.log(`Semantic Answer Score: ${answer.score}\n\n`);
}

console.log(`Search Results:\n\n`);
rowNumber = 1;

// Iterate through the search results
for await (const result of results.results) {


    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;
    console.log(`Search result #${rowNumber++}:`);
    console.log(`${rerankerScoreDisplay}`);
    console.log(`${doc.HotelName}`);
    console.log(`${doc.Description || 'N/A'}`);

    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(`Caption: ${caption.highlights}\n`);
        } else {
            console.log(`Caption: ${caption.text}\n`);
        }
    }
}

Uruchom kod.

npm run build && node -r dotenv/config dist/semanticAnswer.js

Dane wyjściowe powinny wyglądać podobnie do poniższego przykładu, gdzie najlepsza odpowiedź na pytanie jest pobierana z jednego z wyników.

Pamiętaj, że odpowiedzi są dosłowną zawartością pobraną z indeksu i mogą brakować fraz, które użytkownik spodziewa się zobaczyć. Aby uzyskać złożone odpowiedzi wygenerowane przez model ukończenia czatu, rozważ użycie wzorca RAG lub agentowego pobierania danych.
```
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 library 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
```

Udostępnij przez

Szybki start: klasyfikacja semantyczna

Wymagania wstępne

Konfigurowanie dostępu

Rozpoczynanie od indeksu

Konfigurowanie klienta

Instalowanie bibliotek

Zaloguj się do Azure

Aktualizowanie indeksu

Uruchamianie zapytań semantycznych

Dane wyjściowe zapytania semantycznego (bez podpisów ani odpowiedzi)

Dane wyjściowe zapytania semantycznego z podpisami

Dane wyjściowe dla odpowiedzi semantycznych

Wymagania wstępne

Konfigurowanie dostępu

Rozpoczynanie od indeksu

Konfigurowanie klienta

Konfigurowanie lokalnego środowiska deweloperskiego

Zaloguj się do Azure

Tworzenie wspólnego pliku uwierzytelniania

Pobieranie schematu indeksu

Aktualizowanie indeksu przy użyciu konfiguracji semantycznej

Uruchamianie zapytań semantycznych

Przywracanie napisów

Zwracanie odpowiedzi semantycznych

Wymagania wstępne

Konfigurowanie dostępu

Rozpoczynanie od indeksu

Konfigurowanie klienta

Konfigurowanie lokalnego środowiska deweloperskiego

Zaloguj się do Azure

Tworzenie wspólnej klasy konfiguracji

Pobieranie schematu indeksu

Aktualizowanie indeksu przy użyciu konfiguracji semantycznej

Uruchamianie zapytań semantycznych

Przywracanie napisów

Zwracanie odpowiedzi semantycznych

Wymagania wstępne

Konfigurowanie dostępu

Rozpoczynanie od indeksu

Konfigurowanie klienta

Instalowanie pakietów i ustawianie zmiennych środowiskowych

Zaloguj się do Azure

Aktualizowanie indeksu

Uruchamianie zapytań semantycznych

Przywracanie napisów

Zwracanie odpowiedzi semantycznych

Wymagania wstępne

Konfigurowanie dostępu

Rozpoczynanie od indeksu

Konfigurowanie klienta

Aktualizowanie indeksu

Uruchamianie zapytań semantycznych

Przywracanie napisów

Zwracanie odpowiedzi semantycznych

Wymagania wstępne

Konfigurowanie dostępu

Rozpoczynanie od indeksu

Konfigurowanie klienta

Konfigurowanie lokalnego środowiska deweloperskiego

Zaloguj się do Azure

Tworzenie wspólnego pliku uwierzytelniania

Pobieranie schematu indeksu

Aktualizowanie indeksu przy użyciu konfiguracji semantycznej

Uruchamianie zapytań semantycznych

Przywracanie napisów

Zwracanie odpowiedzi semantycznych

Czyszczenie zasobów

Treści powiązane

Sprzężenie zwrotne

Dodatkowe źródła