Rychlý start: Sémantické řazení

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro .NET k přidání semantického řazení do existujícího indexu vyhledávání a dotazování indexu.

Sémantické řazení je funkce na straně dotazu, která používá strojové porozumění textu k přehodnocení výsledků hledání a posouvá nejvíce sémanticky relevantní shody na začátek seznamu. Do existujícího indexu můžete přidat sémantickou konfiguraci bez nutnosti opětovného sestavení. Sémantické řazení je nejúčinnější pro informativní nebo popisný text.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač.

• Index s popisnými textovými poli přiřazenými jako searchable a retrievable. V tomto rychlém úvodu se předpokládá index ukázek hotelů.

• .NET 9 nebo novější.

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup na základě role pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Přejděte do vyhledávací služby na portálu Azure.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Začínáme s indexem

Tento rychlý start upraví existující index tak, aby zahrnoval sémantickou konfiguraci. Doporučujeme index ukázek hotelů, který můžete vytvořit v minutách pomocí průvodce portálem Azure.

Pokud chcete použít jiný index, nahraďte název indexu, názvy polí v sémantické konfiguraci a názvy polí v příkazech dotazu select v rámci vzorového kódu. Index by měl obsahovat popisná textová pole, která jsou přiřazena jako searchable a retrievable.

Přezkoumání a dotazování vzorkového indexu hotelů před sémantickým hodnocením:

1. Přejděte do vyhledávací služby na portálu Azure.

2. V levém podokně vyberte Správa vyhledávání>Indexy.

3. Vyberte hotely s ukázkou.

4. Vyberte Sémantické konfigurace pro zobrazení všech existujících konfigurací. Pokud jste při vytváření průvodce povolili sémantické řazení, měla by existovat výchozí konfigurace.

   

5. Vyberte Search explorer a poté vyberte Zobrazit>zobrazení JSON.

6. Do editoru dotazů vložte následující KÓD JSON.

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

7. Výběrem Hledat spusťte vyhledávání.

   Odpověď by měla být podobná následujícímu příkladu. Jedná se o fulltextový dotaz seřazený podle BM25, takže výsledky odpovídají jednotlivým termínům dotazu a lingvistickým variantám, nikoli celkovému významu dotazu. Například walking odpovídá walk, a live a music odpovídají nezávisle místo jedné fráze.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Tip

   Tento dotaz ukazuje, jak odpověď vypadá před uplatněním sémantického řazení. Po konfiguraci sémantické konfigurace přidejte "queryType": "semantic" a "semanticConfiguration": "semantic-config" podívejte se, jak je stejný dotaz seřazen jinak podle sémantického řazení.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

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

2. Přejděte do složky rychlý start.

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

3. V BuildIndex/Program.cs nahraďte zástupnou hodnotu pro endpoint adresou URL, kterou jste získali v Získání koncového bodu.

4. Opakujte předchozí krok pro QueryIndex/Program.cs.

5. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

Spuštění kódu

1. Spuštěním prvního projektu aktualizujte index sémantickou konfigurací.

   dotnet run --project BuildIndex
   

2. Spusťte druhý projekt pro dotazování indexu. Stisknutím klávesy Enter mezi dotazy zobrazíte průběh jednoduchého dotazu na sémantický dotaz s titulky a odpověďmi.

   dotnet run --project QueryIndex
   

Výstup

První projekt aktualizuje index ukázek hotelů pomocí sémantické konfigurace. Výstup obsahuje potvrzení sémantické konfigurace.

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

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

Druhý projekt spouští čtyři dotazy. Výstup obsahuje výsledky hledání se skóre relevance, titulky a odpovědi.

Query 1: Simple query using the search string 'walking distance to live music'.
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
----------------------------------------
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 2: Semantic query (no captions, no answers) for 'walking distance to live music'.
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
@search.rerankerScore: 2.271434783935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 3: Semantic query with captions.
Caption: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.
Extractive Answers:
  Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
----------------------------------------
... // Trimmed for brevity

Vysvětlení kódu

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Konfigurace a ověřování
2. Aktualizace indexu sémantickou konfigurací
3. Dotazování indexu

Konfigurace a ověřování

Oba projekty sdílejí stejný vzor konfigurace. Soubory Program.cs definují koncový bod vyhledávání a používají DefaultAzureCredential pro ověřování bez klíčů.

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

Klíčové poznatky:

• DefaultAzureCredential poskytuje ověřování bez klíčů pomocí Microsoft Entra ID. Zřetězuje více typů přihlašovacích údajů, včetně typu osvědčení Azure CLI z az login.
• SearchIndexClient spravuje operace na úrovni indexu, například aktualizaci schématu indexu.
• SearchClient zpracovává operace na úrovni dokumentu, jako je dotazování indexu.

Aktualizace indexu sémantickou konfigurací

Následující kód přidá sémantickou konfiguraci do existujícího indexu pomocí BuildIndex/Program.cs. Tato operace neodstraní žádné vyhledávací dokumenty a po přidání konfigurace zůstane index funkční.

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

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

Klíčové poznatky:

• Sémantická konfigurace určuje pole použitá pro sémantické řazení.
• Sémantické konfigurace lze přidat do existujících indexů bez opětovného sestavení.
• TitleField nastaví pole, které představuje název dokumentu.
• ContentFields nastaví pole obsahující hlavní obsah.
• KeywordsFields nastaví pole obsahující klíčová slova nebo značky.

Dotazování indexu

Projekt QueryIndex spouští čtyři dotazy postupně a postupuje z jednoduchého vyhledávání klíčových slov až po sémantické řazení s titulky a odpověďmi.

Jednoduchý dotaz

Prvním dotazem je jednoduché vyhledávání klíčových slov, které nepoužívá sémantické řazení. Tento dotaz slouží jako základ pro porovnávání výsledků se sémantickým přerovnáním.

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

Klíčové poznatky:

• SearchQueryType.Simple používá výchozí algoritmus řazení BM25.
• Výsledky jsou seřazené pouze podle relevance klíčových slov (@search.score).

Sémantický dotaz (žádné titulky, žádné odpovědi)

Další dotaz přidá sémantické řazení bez titulků ani odpovědí. Následující kód ukazuje minimální požadavek na vyvolání sémantického řazení.

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

Klíčové poznatky:

• SearchQueryType.Semantic umožňuje sémantické řazení dotazu.
• SemanticConfigurationName určuje, která sémantická konfigurace se má použít.
• @search.rerankerScore označuje sémantickou relevanci (vyšší je lepší).
• Počáteční výsledky dotazu termínů se přehodnotují pomocí sémantických modelů řazení. U této datové sady a dotazu jsou účinky sémantického řazení výraznější ve výsledcích s nižším pořadím.

Sémantický dotaz s titulky

Následující kód přidá popisky pro extrakci nejrelevantnějších částí z každého výsledku, přičemž zvýraznění klíčových slov (hitů) se použije u důležitých termínů a frází.

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

Klíčové poznatky:

• QueryCaption umožňuje extrahovat titulky z polí obsahu.
• Titulky zobrazují nejrelevavantnější pasáže a přidávají <em> značky kolem důležitých termínů.

Sémantický dotaz s odpověďmi

Poslední dotaz přidá sémantické odpovědi. Tento dotaz používá jiný hledaný řetězec (searchText2), protože sémantické odpovědi fungují nejlépe, když je dotaz frází jako otázka. Odpovědí je doslovný úsek extrahovaný z indexu, nikoli složená odpověď z modelu dokončování chatu.

Dotaz a indexovaný obsah musí být úzce zarovnané, aby se vrátila odpověď. Pokud žádný kandidát nesplňuje prahovou hodnotu spolehlivosti, odpověď neobsahuje odpověď. V tomto příkladu se používá otázka, která je známá k vytvoření výsledku, abyste viděli syntaxi. Pokud odpovědi nejsou pro váš scénář užitečné, vynecháte QueryAnswer z vašeho kódu. U složených odpovědí zvažte vzor RAG nebo získávání pomocí agentů.

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

Klíčové poznatky:

• QueryAnswer umožňuje extrahovatelné odpovědi pro dotazy podobné dotazům.
• Odpovědi jsou doslovný obsah extrahovaný z indexu, negenerovaný text.

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro Java k přidání semantického řazení do existujícího indexu vyhledávání a dotazování indexu.

Sémantické řazení je funkce na straně dotazu, která používá strojové porozumění textu k přehodnocení výsledků hledání a posouvá nejvíce sémanticky relevantní shody na začátek seznamu. Do existujícího indexu můžete přidat sémantickou konfiguraci bez nutnosti opětovného sestavení. Sémantické řazení je nejúčinnější pro informativní nebo popisný text.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač.

• Index s popisnými textovými poli přiřazenými jako searchable a retrievable. V tomto rychlém úvodu se předpokládá index ukázek hotelů.

• Java 21 (LTS) a Maven.

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup na základě role pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Přejděte do vyhledávací služby na portálu Azure.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Začínáme s indexem

Tento rychlý start upraví existující index tak, aby zahrnoval sémantickou konfiguraci. Doporučujeme index ukázek hotelů, který můžete vytvořit v minutách pomocí průvodce portálem Azure.

Pokud chcete použít jiný index, nahraďte název indexu, názvy polí v sémantické konfiguraci a názvy polí v příkazech dotazu select v rámci vzorového kódu. Index by měl obsahovat popisná textová pole, která jsou přiřazena jako searchable a retrievable.

Přezkoumání a dotazování vzorkového indexu hotelů před sémantickým hodnocením:

1. Přejděte do vyhledávací služby na portálu Azure.

2. V levém podokně vyberte Správa vyhledávání>Indexy.

3. Vyberte hotely s ukázkou.

4. Vyberte Sémantické konfigurace pro zobrazení všech existujících konfigurací. Pokud jste při vytváření průvodce povolili sémantické řazení, měla by existovat výchozí konfigurace.

   

5. Vyberte Search explorer a poté vyberte Zobrazit>zobrazení JSON.

6. Do editoru dotazů vložte následující KÓD JSON.

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

7. Výběrem Hledat spusťte vyhledávání.

   Odpověď by měla být podobná následujícímu příkladu. Jedná se o fulltextový dotaz seřazený podle BM25, takže výsledky odpovídají jednotlivým termínům dotazu a lingvistickým variantám, nikoli celkovému významu dotazu. Například walking odpovídá walk, a live a music odpovídají nezávisle místo jedné fráze.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Tip

   Tento dotaz ukazuje, jak odpověď vypadá před uplatněním sémantického řazení. Po konfiguraci sémantické konfigurace přidejte "queryType": "semantic" a "semanticConfiguration": "semantic-config" podívejte se, jak je stejný dotaz seřazen jinak podle sémantického řazení.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

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

2. Přejděte do složky rychlý start.

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

3. V src/main/resources/application.properties nahraďte zástupnou hodnotu pro azure.search.endpoint adresou URL, kterou jste získali v Získání koncového bodu.

4. Zkompilujte projekt a vyřešte závislosti, včetně azure-search-documents.

   mvn compile
   

   Po dokončení sestavení ověřte, že se ve výstupu nezobrazí žádné chyby.

5. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

Spuštění kódu

1. Získejte stávající nastavení indexu.

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

2. Aktualizujte index sémantickou konfigurací.

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

3. Spusťte sémantický dotaz.

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

4. Spusťte sémantický dotaz s popisky.

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

5. Spusťte sémantický dotaz s odpověďmi.

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

Výstup

Výstupem GetIndexSettings.java je název indexu, jeho polí a sémantické konfigurace. Před přidáním nové konfigurace má index pouze výchozí konfiguraci.

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

Výstup UpdateIndexSettings.java uvádí seznam všech sémantických konfigurací v indexu, včetně toho, který přidal kód, a následně zprávu o úspěchu.

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

Výstup SemanticQuery.java vrátí všechny odpovídající dokumenty seřazené podle sémantického pořadí re-ranker skóre.

Search result #1:
  Re-ranker Score: 2.61
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

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

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

Výstup SemanticQueryWithCaptions.java přidá prvek popisku se zvýrazněním nálezu spolu s vyhledávacími poli. Titulky jsou nejrelevavantnější pasáže ve výsledku. Pokud index obsahuje větší text, titulky vám pomůžou extrahovat nejzajímavější věty.

Search result #1:
  Re-ranker Score: 2.61
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

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

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

Výstup SemanticAnswer.java obsahuje sémantickou odpověď z jednoho z výsledků, které nejlépe odpovídají otázce a výsledky hledání s titulky.

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.98

Search Results:

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

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

Vysvětlení kódu

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Konfigurace a ověřování
2. Aktualizace indexu sémantickou konfigurací
3. Dotazování indexu

Konfigurace a ověřování

Třída SearchConfig.java načte vlastnosti z application.properties a vytvoří DefaultAzureCredential pro ověřování bez klíčů.

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

Klíčové poznatky:

• DefaultAzureCredential poskytuje ověřování bez klíčů pomocí Microsoft Entra ID. Zřetězuje více typů přihlašovacích údajů, včetně typu osvědčení Azure CLI z az login.
• Vlastnosti jsou načteny ze souboru application.properties v classpathu.
• Statická pole (SEARCH_ENDPOINT, INDEX_NAME, SEMANTIC_CONFIG_NAME, CREDENTIAL) jsou sdílena napříč všemi třídami v projektu.

Aktualizace indexu sémantickou konfigurací

Třída UpdateIndexSettings.java přidá sémantickou konfiguraci do existujícího hotels-sample indexu. Tato operace neodstraní žádné vyhledávací dokumenty a po přidání konfigurace zůstane index funkční.

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

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

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

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

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

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

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

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

configurations.add(newSemanticConfiguration);

indexClient.createOrUpdateIndex(existingIndex);

Klíčové poznatky:

• SemanticPrioritizedFields definuje, která pole se sémantický ranker vyhodnotí. setTitleField nastaví název dokumentu, setContentFields nastaví hlavní obsah a setKeywordsFields nastaví pole klíčových slov nebo značek.
• SemanticConfiguration spáruje název s poli s určením priority a identifikuje sémantickou konfiguraci, která se má použít v době dotazu.
• createOrUpdateIndex odešle aktualizované schéma do vyhledávací služby bez opětovného sestavení indexu nebo odstranění dokumentů.

Dotazování indexu

Následující tři třídy dotazují index v sekvenci a postupují ze základního sémantického vyhledávání na sémantické řazení s titulky a odpověďmi.

Sémantický dotaz (žádné titulky, žádné odpovědi)

První dotaz přidá sémantické řazení bez titulků nebo odpovědí. Třída SemanticQuery.java ukazuje minimální požadavek na vyvolání sémantického řazení.

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

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

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

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

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

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

Klíčové poznatky:

• QueryType.SEMANTIC umožňuje sémantické řazení dotazu.
• setSemanticConfigurationName určuje, která sémantická konfigurace se má použít.
• SearchPagedIterable poskytuje iterátor přes přeřazené výsledky. Každý SearchResult obsahuje přístupový objekt getSemanticSearch() pro skóre rerankeru.

Sémantický dotaz s titulky

Třída SemanticQueryWithCaptions.java přidá titulky k extrakci nejrelevantnějších pasáží z každého výsledku, s použitím zvýraznění klíčových slov pro důležité termíny a fráze.

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

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

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

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

Klíčové poznatky:

• QueryCaption(QueryCaptionType.EXTRACTIVE) umožňuje extrahovat titulky z polí obsahu.
• setHighlightEnabled(true) přidá <em> značky kolem důležitých termínů v titulcích.
• Každý SearchResult poskytuje getQueryCaptions() na sémantický vyhledávací přístup.

Sémantický dotaz s odpověďmi

Třída SemanticAnswer.java přidává sémantické odpovědi. Tato třída používá jako hledaný text otázku, protože sémantické odpovědi fungují nejlépe, když je dotaz formulován jako otázka. Odpovědí je doslovný úsek extrahovaný z indexu, nikoli složená odpověď z modelu dokončování chatu.

Dotaz a indexovaný obsah musí být úzce zarovnané, aby se vrátila odpověď. Pokud žádný kandidát nesplňuje prahovou hodnotu spolehlivosti, odpověď neobsahuje odpověď. V tomto příkladu se používá otázka, která je známá k vytvoření výsledku, abyste viděli syntaxi. Pokud odpovědi nejsou pro váš scénář užitečné, vynecháte setQueryAnswer z vašeho kódu. U složených odpovědí zvažte vzor RAG nebo získávání pomocí agentů.

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

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

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

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

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

Klíčové poznatky:

• QueryAnswer(QueryAnswerType.EXTRACTIVE) umožňuje extrahovatelné odpovědi pro dotazy podobné dotazům.
• Odpovědi jsou doslovný obsah extrahovaný z indexu, negenerovaný text.
• results.getSemanticResults().getQueryAnswers() načte objekty odpovědí odděleně od výsledků hledání.

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro JavaScript k přidání semantického řazení do existujícího indexu vyhledávání a dotazování indexu.

Sémantické řazení je funkce na straně dotazu, která používá strojové porozumění textu k přehodnocení výsledků hledání a posouvá nejvíce sémanticky relevantní shody na začátek seznamu. Do existujícího indexu můžete přidat sémantickou konfiguraci bez nutnosti opětovného sestavení. Sémantické řazení je nejúčinnější pro informativní nebo popisný text.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač.

• Index s popisnými textovými poli přiřazenými jako searchable a retrievable. V tomto rychlém úvodu se předpokládá index ukázek hotelů.

• Node.js 20 LTS nebo novější.

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup na základě role pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Přejděte do vyhledávací služby na portálu Azure.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Začínáme s indexem

Tento rychlý start upraví existující index tak, aby zahrnoval sémantickou konfiguraci. Doporučujeme index ukázek hotelů, který můžete vytvořit v minutách pomocí průvodce portálem Azure.

Pokud chcete použít jiný index, nahraďte název indexu, názvy polí v sémantické konfiguraci a názvy polí v příkazech dotazu select v rámci vzorového kódu. Index by měl obsahovat popisná textová pole, která jsou přiřazena jako searchable a retrievable.

Přezkoumání a dotazování vzorkového indexu hotelů před sémantickým hodnocením:

1. Přejděte do vyhledávací služby na portálu Azure.

2. V levém podokně vyberte Správa vyhledávání>Indexy.

3. Vyberte hotely s ukázkou.

4. Vyberte Sémantické konfigurace pro zobrazení všech existujících konfigurací. Pokud jste při vytváření průvodce povolili sémantické řazení, měla by existovat výchozí konfigurace.

   

5. Vyberte Search explorer a poté vyberte Zobrazit>zobrazení JSON.

6. Do editoru dotazů vložte následující KÓD JSON.

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

7. Výběrem Hledat spusťte vyhledávání.

   Odpověď by měla být podobná následujícímu příkladu. Jedná se o fulltextový dotaz seřazený podle BM25, takže výsledky odpovídají jednotlivým termínům dotazu a lingvistickým variantám, nikoli celkovému významu dotazu. Například walking odpovídá walk, a live a music odpovídají nezávisle místo jedné fráze.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Tip

   Tento dotaz ukazuje, jak odpověď vypadá před uplatněním sémantického řazení. Po konfiguraci sémantické konfigurace přidejte "queryType": "semantic" a "semanticConfiguration": "semantic-config" podívejte se, jak je stejný dotaz seřazen jinak podle sémantického řazení.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

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

2. Přejděte do složky rychlý start.

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

3. V sample.env nahraďte zástupnou hodnotu pro AZURE_SEARCH_ENDPOINT adresou URL, kterou jste získali v Získání koncového bodu.

4. Přejmenujte sample.env na .env.

   mv sample.env .env
   

5. Nainstalujte závislosti.

   npm install
   

   Po dokončení instalace by se měla v adresáři projektu zobrazit node_modules složka.

6. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

Spuštění kódu

1. Získejte stávající nastavení indexu.

   node -r dotenv/config src/getIndexSettings.js
   

2. Aktualizujte index sémantickou konfigurací.

   node -r dotenv/config src/updateIndexSettings.js
   

3. Spusťte sémantický dotaz.

   node -r dotenv/config src/semanticQuery.js
   

4. Spusťte sémantický dotaz s popisky.

   node -r dotenv/config src/semanticQueryReturnCaptions.js
   

5. Spusťte sémantický dotaz s odpověďmi.

   node -r dotenv/config src/semanticAnswer.js
   

Výstup

Skript getIndexSettings.js vrátí název indexu, jeho polí a všechny existující sémantické konfigurace.

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

Skript updateIndexSettings.js vrátí všechny sémantické konfigurace v indexu, včetně té, kterou přidal kód, a poté vypíše zprávu o úspěchu.

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

Skript semanticQuery.js vrátí všechny odpovídající dokumenty seřazené podle skóre re-rankingu vyjadřujícího sémantické pořadí.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

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

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

Skript semanticQueryReturnCaptions.js vrátí element popisku se zvýrazněním výsledků spolu s vyhledávacími poli. Titulky jsou nejrelevavantnější pasáže ve výsledku. Pokud index obsahuje větší text, titulky vám pomůžou extrahovat nejzajímavější věty.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

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

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

Skript semanticAnswer.js vrátí sémantickou odpověď vytaženou z jednoho z výsledků, které nejlépe odpovídají otázce, následované výsledky hledání s titulky.

Answers:

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

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

Vysvětlení kódu

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Konfigurace a ověřování
2. Aktualizace indexu sémantickou konfigurací
3. Dotazování indexu

Konfigurace a ověřování

Soubor config.js načte proměnné prostředí a vytvoří DefaultAzureCredential pro ověření.

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

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

export const credential = new DefaultAzureCredential();

Klíčové poznatky:

• DefaultAzureCredential poskytuje ověřování bez klíčů pomocí Microsoft Entra ID. Zřetězuje více typů přihlašovacích údajů, včetně typu osvědčení Azure CLI z az login.
• Proměnné prostředí se načítají ze souboru .env pomocí dotenv.

Aktualizace indexu sémantickou konfigurací

Soubor updateIndexSettings.js přidá do existujícího hotels-sample indexu sémantickou konfiguraci. Tato operace neodstraní žádné vyhledávací dokumenty a po přidání konfigurace zůstane index funkční.

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

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

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

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

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

await indexClient.createOrUpdateIndex(existingIndex);

Klíčové poznatky:

• Sémantická konfigurace určuje pole použitá pro sémantické řazení. titleField definuje název dokumentu, contentFields definuje hlavní obsah a keywordsFields definuje pole klíčových slov nebo značek.
• Vytvoříte konfigurační objekt a vložíte ho do pole existujícího indexu semanticSearch.configurations.
• createOrUpdateIndex odešle aktualizované schéma do vyhledávací služby bez opětovného sestavení indexu nebo odstranění dokumentů.

Dotazování indexu

Skripty dotazu spouštějí tři dotazy v posloupnosti a postupují od základního sémantického vyhledávání až po sémantické řazení s titulky a odpověďmi.

Sémantický dotaz (žádné titulky, žádné odpovědi)

Následující kód ukazuje minimální požadavek na vyvolání sémantického řazení.

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

Klíčové poznatky:

• queryType: "semantic" umožňuje sémantické řazení dotazu.
• semanticSearchOptions.configurationName určuje, která sémantická konfigurace se má použít.
• rerankerScore ve výsledcích označuje sémantickou relevanci (vyšší je lepší).

Sémantický dotaz s titulky

Následující kód přidá popisky pro extrakci nejrelevantnějších částí z každého výsledku, přičemž zvýraznění klíčových slov (hitů) se použije u důležitých termínů a frází.

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

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

Klíčové poznatky:

• captions.captionType: "extractive" umožňuje extrahovat titulky z polí obsahu.
• Titulky zobrazují nejrelevavantnější pasáže a přidávají <em> značky kolem důležitých termínů.

Sémantický dotaz s odpověďmi

Poslední dotaz přidá sémantické odpovědi. Tento dotaz používá jako hledaný text otázku, protože sémantické odpovědi fungují nejlépe, když je dotaz formulován jako otázka. Odpovědí je doslovný úsek extrahovaný z indexu, nikoli složená odpověď z modelu dokončování chatu.

Dotaz a indexovaný obsah musí být úzce zarovnané, aby se vrátila odpověď. Pokud žádný kandidát nesplňuje prahovou hodnotu spolehlivosti, odpověď neobsahuje odpověď. V tomto příkladu se používá otázka, která je známá k vytvoření výsledku, abyste viděli syntaxi. Pokud odpovědi nejsou pro váš scénář užitečné, vynecháte answers z vašeho kódu. U složených odpovědí zvažte vzor RAG nebo získávání pomocí agentů.

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

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

Klíčové poznatky:

• answers.answerType: "extractive" umožňuje extrahovatelné odpovědi pro dotazy podobné dotazům.
• Odpovědi jsou doslovný obsah extrahovaný z indexu, negenerovaný text.
• results.answers načte objekty odpovědí odděleně od výsledků hledání.

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro Python k přidání semantického řazení do existujícího indexu vyhledávání a dotazování indexu.

Sémantické řazení je funkce na straně dotazu, která používá strojové porozumění textu k přehodnocení výsledků hledání a posouvá nejvíce sémanticky relevantní shody na začátek seznamu. Do existujícího indexu můžete přidat sémantickou konfiguraci bez nutnosti opětovného sestavení. Sémantické řazení je nejúčinnější pro informativní nebo popisný text.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač.

• Index s popisnými textovými poli přiřazenými jako searchable a retrievable. V tomto rychlém úvodu se předpokládá index ukázek hotelů.

• Python 3.10 nebo novější.

• Visual Studio Code s příponou Python.

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup na základě role pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Přejděte do vyhledávací služby na portálu Azure.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Začínáme s indexem

Tento rychlý start upraví existující index tak, aby zahrnoval sémantickou konfiguraci. Doporučujeme index ukázek hotelů, který můžete vytvořit v minutách pomocí průvodce portálem Azure.

Pokud chcete použít jiný index, nahraďte název indexu, názvy polí v sémantické konfiguraci a názvy polí v příkazech dotazu select v rámci vzorového kódu. Index by měl obsahovat popisná textová pole, která jsou přiřazena jako searchable a retrievable.

Přezkoumání a dotazování vzorkového indexu hotelů před sémantickým hodnocením:

1. Přejděte do vyhledávací služby na portálu Azure.

2. V levém podokně vyberte Správa vyhledávání>Indexy.

3. Vyberte hotely s ukázkou.

4. Vyberte Sémantické konfigurace pro zobrazení všech existujících konfigurací. Pokud jste při vytváření průvodce povolili sémantické řazení, měla by existovat výchozí konfigurace.

   

5. Vyberte Search explorer a poté vyberte Zobrazit>zobrazení JSON.

6. Do editoru dotazů vložte následující KÓD JSON.

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

7. Výběrem Hledat spusťte vyhledávání.

   Odpověď by měla být podobná následujícímu příkladu. Jedná se o fulltextový dotaz seřazený podle BM25, takže výsledky odpovídají jednotlivým termínům dotazu a lingvistickým variantám, nikoli celkovému významu dotazu. Například walking odpovídá walk, a live a music odpovídají nezávisle místo jedné fráze.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Tip

   Tento dotaz ukazuje, jak odpověď vypadá před uplatněním sémantického řazení. Po konfiguraci sémantické konfigurace přidejte "queryType": "semantic" a "semanticConfiguration": "semantic-config" podívejte se, jak je stejný dotaz seřazen jinak podle sémantického řazení.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

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

2. Přejděte do složky rychlý start a otevřete ji v Visual Studio Code.

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

3. V sample.env nahraďte zástupnou hodnotu pro AZURE_SEARCH_ENDPOINT adresou URL, kterou jste získali v Získání koncového bodu.

4. Přejmenujte sample.env na .env.

   mv sample.env .env
   

5. Otevřít semantic-ranking-quickstart.ipynb.

6. Stiskněte Kombinaci kláves Ctrl+Shift+P, vyberte Poznámkový blok: Vyberte jádro poznámkového bloku a podle pokynů vytvořte virtuální prostředí. Vyberte requirements.txt pro závislosti.

   Po dokončení by se měla v adresáři projektu zobrazit .venv složka.

7. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

Spuštění kódu

1. Install packages and set variables Spusťte buňky pro instalaci požadovaných balíčků a k načtení proměnných prostředí.

2. Postupným spuštěním zbývajících buněk přidejte sémantickou konfiguraci a dotazujte index.

Výstup

Výstupem Get the index definition buňky je název indexu, jeho polí a všechny existující sémantické konfigurace.

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

Výstup Add a semantic configuration to the index buňky obsahuje seznam všech sémantických konfigurací v indexu, včetně kódu přidaného, následovaného zprávou o úspěchu.

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

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

✅ Semantic configuration successfully added!

Výstup Run a term query buňky vrátí všechny odpovídající dokumenty seřazené podle skóre BM25. Tento směrný dotaz nepoužívá sémantické řazení.

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

Výstup buňky Run a semantic query vrátí všechny odpovídající dokumenty seřazené podle skóre sémantického re-rankeru.

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

Výstup Return captions buňky přidá prvek titulku se zvýrazněním nalezeného vedle vyhledávacích polí. Titulky jsou nejrelevavantnější pasáže ve výsledku. Pokud index obsahuje větší text, titulky vám pomůžou extrahovat nejzajímavější věty.

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

Výstup Return semantic answers buňky obsahuje sémantickou odpověď z jednoho z výsledků, který nejlépe odpovídá otázce a výsledky hledání s titulky.

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

Vysvětlení kódu

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Konfigurace a ověřování
2. Aktualizace indexu sémantickou konfigurací
3. Dotazování indexu

Konfigurace a ověřování

Buňka Install packages and set variables načte proměnné prostředí a vytvoří DefaultAzureCredential pro autentizaci.

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

load_dotenv(override=True)

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

Klíčové poznatky:

• DefaultAzureCredential poskytuje ověřování bez klíčů pomocí Microsoft Entra ID. Zřetězuje více typů přihlašovacích údajů, včetně typu osvědčení Azure CLI z az login.
• Proměnné prostředí se načítají ze souboru .env pomocí python-dotenv.

Aktualizace indexu sémantickou konfigurací

Buňka Add a semantic configuration to the index přidá do existujícího hotels-sample indexu sémantickou konfiguraci. Tato operace neodstraní žádné vyhledávací dokumenty a po přidání konfigurace zůstane index funkční.

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

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

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

result = index_client.create_or_update_index(existing_index)

Klíčové poznatky:

• Sémantická konfigurace určuje pole použitá pro sémantické řazení. title_field nastaví název dokumentu, content_fields nastaví hlavní obsah a keywords_fields nastaví pole klíčových slov nebo značek.
• Vytvoříte konfiguraci s přidruženým SemanticConfiguration modelem SemanticPrioritizedFields a pak ji připojíte k existujícímu indexu.
• create_or_update_index odešle aktualizované schéma do vyhledávací služby bez opětovného sestavení indexu nebo odstranění dokumentů.

Dotazování indexu

Buňky dotazu spouštějí čtyři dotazy v posloupnosti: základní vyhledávání podle klíčových slov následované třemi sémantickými variantami řazení s narůstající funkčností.

Hledání termínu (výchozí)

Buňka Run a term query spouští hledání klíčových slov pomocí bodování BM25. Tento směrný dotaz nepoužívá sémantické řazení a slouží jako srovnávací bod.

from azure.search.documents import SearchClient

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

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

Klíčové poznatky:

• query_type='simple' specifikuje vyhledávání klíčových slov s využitím bodování BM25.
• Ve výsledcích @search.score označuje skóre relevance BM25.

Sémantický dotaz (žádné titulky, žádné odpovědi)

V Run a semantic query buňce je uveden minimální požadavek na vyvolání sémantického řazení.

from azure.search.documents import SearchClient

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

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

Klíčové poznatky:

• query_type='semantic' umožňuje sémantické řazení dotazu.
• semantic_configuration_name určuje, která sémantická konfigurace se má použít.
• @search.reranker_score ve výsledcích označuje sémantickou relevanci (vyšší je lepší).

Sémantický dotaz s titulky

Buňka Return captions přidá titulky pro extrakci nejrelevantnějších pasáží z každého výsledku, přičemž zvýraznění klíčových slov se použije u důležitých termínů a frází.

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

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

Klíčové poznatky:

• query_caption='extractive' umožňuje extrahovat titulky z polí obsahu.
• Titulky zobrazují nejrelevavantnější pasáže a přidávají <em> značky kolem důležitých termínů.

Sémantický dotaz s odpověďmi

Buňka Return semantic answers přidá sémantické odpovědi. Tento dotaz používá jako hledaný text otázku, protože sémantické odpovědi fungují nejlépe, když je dotaz formulován jako otázka. Odpovědí je doslovný úsek extrahovaný z indexu, nikoli složená odpověď z modelu dokončování chatu.

Dotaz a indexovaný obsah musí být úzce zarovnané, aby se vrátila odpověď. Pokud žádný kandidát nesplňuje prahovou hodnotu spolehlivosti, odpověď neobsahuje odpověď. V tomto příkladu se používá otázka, která je známá k vytvoření výsledku, abyste viděli syntaxi. Pokud odpovědi nejsou pro váš scénář užitečné, vynecháte query_answer z vašeho kódu. U složených odpovědí zvažte vzor RAG nebo získávání pomocí agentů.

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

Klíčové poznatky:

• query_answer="extractive" umožňuje extrahovatelné odpovědi pro dotazy podobné dotazům.
• Odpovědi jsou doslovný obsah extrahovaný z indexu, negenerovaný text.
• results.get_answers() načte objekty odpovědí odděleně od výsledků hledání.

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro JavaScript (kompatibilní s TypeScriptem) k přidání semantic ranking do existujícího indexu vyhledávání a dotazování indexu.

Sémantické řazení je funkce na straně dotazu, která používá strojové porozumění textu k přehodnocení výsledků hledání a posouvá nejvíce sémanticky relevantní shody na začátek seznamu. Do existujícího indexu můžete přidat sémantickou konfiguraci bez nutnosti opětovného sestavení. Sémantické řazení je nejúčinnější pro informativní nebo popisný text.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač.

• Index s popisnými textovými poli přiřazenými jako searchable a retrievable. V tomto rychlém úvodu se předpokládá index ukázek hotelů.

• Node.js 20 LTS nebo novější, aby se spustil zkompilovaný kód.

• TypeScript ke kompilaci TypeScriptu do JavaScriptu

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup na základě role pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Přejděte do vyhledávací služby na portálu Azure.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Začínáme s indexem

Tento rychlý start upraví existující index tak, aby zahrnoval sémantickou konfiguraci. Doporučujeme index ukázek hotelů, který můžete vytvořit v minutách pomocí průvodce portálem Azure.

Pokud chcete použít jiný index, nahraďte název indexu, názvy polí v sémantické konfiguraci a názvy polí v příkazech dotazu select v rámci vzorového kódu. Index by měl obsahovat popisná textová pole, která jsou přiřazena jako searchable a retrievable.

Přezkoumání a dotazování vzorkového indexu hotelů před sémantickým hodnocením:

1. Přejděte do vyhledávací služby na portálu Azure.

2. V levém podokně vyberte Správa vyhledávání>Indexy.

3. Vyberte hotely s ukázkou.

4. Vyberte Sémantické konfigurace pro zobrazení všech existujících konfigurací. Pokud jste při vytváření průvodce povolili sémantické řazení, měla by existovat výchozí konfigurace.

   

5. Vyberte Search explorer a poté vyberte Zobrazit>zobrazení JSON.

6. Do editoru dotazů vložte následující KÓD JSON.

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

7. Výběrem Hledat spusťte vyhledávání.

   Odpověď by měla být podobná následujícímu příkladu. Jedná se o fulltextový dotaz seřazený podle BM25, takže výsledky odpovídají jednotlivým termínům dotazu a lingvistickým variantám, nikoli celkovému významu dotazu. Například walking odpovídá walk, a live a music odpovídají nezávisle místo jedné fráze.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Tip

   Tento dotaz ukazuje, jak odpověď vypadá před uplatněním sémantického řazení. Po konfiguraci sémantické konfigurace přidejte "queryType": "semantic" a "semanticConfiguration": "semantic-config" podívejte se, jak je stejný dotaz seřazen jinak podle sémantického řazení.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

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

2. Přejděte do složky rychlý start.

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

3. V sample.env nahraďte zástupnou hodnotu pro AZURE_SEARCH_ENDPOINT adresou URL, kterou jste získali v Získání koncového bodu.

4. Přejmenujte sample.env na .env.

   mv sample.env .env
   

5. Nainstalujte závislosti.

   npm install
   

   Po dokončení instalace by se měla v adresáři projektu zobrazit node_modules složka.

6. Zkompilujte soubory TypeScriptu do JavaScriptu.

   npm run build
   

7. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

Spuštění kódu

1. Získejte stávající nastavení indexu.

   node -r dotenv/config dist/getIndexSettings.js
   

2. Aktualizujte index sémantickou konfigurací.

   node -r dotenv/config dist/updateIndexSettings.js
   

3. Spusťte sémantický dotaz.

   node -r dotenv/config dist/semanticQuery.js
   

4. Spusťte sémantický dotaz s popisky.

   node -r dotenv/config dist/semanticQueryReturnCaptions.js
   

5. Spusťte sémantický dotaz s odpověďmi.

   node -r dotenv/config dist/semanticAnswer.js
   

   Poznámka

   Tyto příkazy spustí zkompilované .js soubory ze dist složky. Před spuštěním Node.js musí být kód TypeScriptu transpilován do JavaScriptu, což je důvod, proč jste dříve spustili npm run build.

Výstup

Skript getIndexSettings.js vrátí název indexu, počet polí, podrobnosti o poli s typem a prohledávatelným stavem a všechny existující sémantické konfigurace.

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

Skript updateIndexSettings.js vrátí všechny sémantické konfigurace, včetně sémantiky, kterou jste přidali.

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

Skript semanticQuery.js vrátí výsledky seřazené podle skóre rerankeru.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown,
  within walking distance to theaters, art galleries, restaurants and
  shops. Visit Seattle Art Museum by day, and then head over to
  Benaroya Hall to catch the evening's concert performance.

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

Skript semanticQueryReturnCaptions.js vrátí extrahované titulky s označením relevantních částí. Titulky jsou nejrelevavantnější pasáže ve výsledku.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown,
  within walking distance to theaters, art galleries, restaurants and
  shops. Visit Seattle Art Museum by day, and then head over to
  Benaroya Hall to catch the evening's concert performance.

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

Skript semanticAnswer.js vrátí sémantickou odpověď (doslovný obsah) vytažený z výsledku, který nejlépe odpovídá otázce.

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by
day, and then come home to our shared living space to relax around
a stone fireplace, sip something warm, and explore the<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

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

Vysvětlení kódu

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Konfigurace a ověřování
2. Aktualizace indexu sémantickou konfigurací
3. Dotazování indexu

Konfigurace a ověřování

Soubor config.ts načte proměnné prostředí, vytvoří DefaultAzureCredential pro autentizaci a definuje HotelDocument rozhraní pro zajištění typové bezpečnosti.

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

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

export const credential = new DefaultAzureCredential();

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

Klíčové poznatky:

• DefaultAzureCredential poskytuje ověřování bez klíčů pomocí Microsoft Entra ID. Zřetězuje více typů přihlašovacích údajů, včetně typu osvědčení Azure CLI z az login.
• Rozhraní HotelDocument poskytuje kontrolu typů během času kompilace pro výsledky vyhledávání, čímž zajišťuje bezpečný přístup k polím dokumentů z hlediska správnosti typů.
• Proměnné prostředí se načítají ze souboru .env pomocí dotenv.

Aktualizace indexu sémantickou konfigurací

Soubor updateIndexSettings.ts přidá do existujícího hotels-sample indexu sémantickou konfiguraci. Tato operace neodstraní žádné vyhledávací dokumenty a po přidání konfigurace zůstane index funkční. Poznámky typu TypeScript zajišťují, že konfigurace odpovídá očekávanému schématu.

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

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

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

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

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

await indexClient.createOrUpdateIndex(existingIndex);

Klíčové poznatky:

• Typy TypeScriptu, jako je SemanticPrioritizedFields, SemanticConfigurationa SemanticField poskytují ověření doby kompilace pro strukturu konfigurace.
• titleField nastaví název dokumentu, contentFields nastaví hlavní obsah a keywordsFields nastaví pole klíčových slov nebo značek.
• createOrUpdateIndex odešle aktualizované schéma do vyhledávací služby bez opětovného sestavení indexu nebo odstranění dokumentů.

Dotazování indexu

Skripty dotazu spouštějí tři dotazy v posloupnosti a postupují od základního sémantického vyhledávání až po sémantické řazení s titulky a odpověďmi.

Sémantický dotaz (žádné titulky, žádné odpovědi)

Skript semanticQuery.ts ukazuje minimální požadavek na vyvolání sémantického řazení s výsledky bezpečnými pro typ.

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

Klíčové poznatky:

• SearchClient<HotelDocument> poskytuje typově bezpečný přístup k polím dokumentu ve výsledcích s automatickým dokončováním pro názvy polí v select a result.document.
• queryType: "semantic" umožňuje sémantické řazení dotazu.
• semanticSearchOptions.configurationName určuje, která sémantická konfigurace se má použít.

Sémantický dotaz s titulky

Skript semanticQueryReturnCaptions.ts přidá popisky pro extrahování nejrelevantnějších pasáží z každého výsledku, přičemž zvýraznění důležitých termínů a frází se použije.

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

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

Klíčové poznatky:

• captions.captionType: "extractive" umožňuje extrahovat titulky z polí obsahu.
• Titulky zobrazují nejrelevavantnější pasáže a přidávají <em> značky kolem důležitých termínů.

Sémantický dotaz s odpověďmi

Skript semanticAnswer.ts přidá sémantické odpovědi. Jako hledaný text používá otázku, protože sémantické odpovědi fungují nejlépe, když je dotaz frázován jako otázka. Odpovědí je doslovný úsek extrahovaný z indexu, nikoli složená odpověď z modelu dokončování chatu.

Dotaz a indexovaný obsah musí být úzce zarovnané, aby se vrátila odpověď. Pokud žádný kandidát nesplňuje prahovou hodnotu spolehlivosti, odpověď neobsahuje odpověď. V tomto příkladu se používá otázka, která je známá k vytvoření výsledku, abyste viděli syntaxi. Pokud odpovědi nejsou pro váš scénář užitečné, vynecháte answers z vašeho kódu. U složených odpovědí zvažte vzor RAG nebo získávání pomocí agentů.

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

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

Klíčové poznatky:

• answers.answerType: "extractive" umožňuje extrahovatelné odpovědi pro dotazy podobné dotazům.
• Odpovědi jsou doslovný obsah extrahovaný z indexu, negenerovaný text.
• results.answers načte objekty odpovědí odděleně od výsledků hledání.

V tomto rychlém startu použijete rozhraní Azure AI Vyhledávač REST API k přidání semantického řazení do existujícího indexu vyhledávání a dotazování indexu.

Sémantické řazení je funkce na straně dotazu, která používá strojové porozumění textu k přehodnocení výsledků hledání a posouvá nejvíce sémanticky relevantní shody na začátek seznamu. Do existujícího indexu můžete přidat sémantickou konfiguraci bez nutnosti opětovného sestavení. Sémantické řazení je nejúčinnější pro informativní nebo popisný text.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač.

• Index s popisnými textovými poli přiřazenými jako searchable a retrievable. V tomto rychlém úvodu se předpokládá index ukázek hotelů.

• Visual Studio Code s rozšířením klienta REST.

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup na základě role pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Přejděte do vyhledávací služby na portálu Azure.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Začínáme s indexem

Tento rychlý start upraví existující index tak, aby zahrnoval sémantickou konfiguraci. Doporučujeme index ukázek hotelů, který můžete vytvořit v minutách pomocí průvodce portálem Azure.

Pokud chcete použít jiný index, nahraďte název indexu, názvy polí v sémantické konfiguraci a názvy polí v příkazech dotazu select v rámci vzorového kódu. Index by měl obsahovat popisná textová pole, která jsou přiřazena jako searchable a retrievable.

Přezkoumání a dotazování vzorkového indexu hotelů před sémantickým hodnocením:

1. Přejděte do vyhledávací služby na portálu Azure.

2. V levém podokně vyberte Správa vyhledávání>Indexy.

3. Vyberte hotely s ukázkou.

4. Vyberte Sémantické konfigurace pro zobrazení všech existujících konfigurací. Pokud jste při vytváření průvodce povolili sémantické řazení, měla by existovat výchozí konfigurace.

   

5. Vyberte Search explorer a poté vyberte Zobrazit>zobrazení JSON.

6. Do editoru dotazů vložte následující KÓD JSON.

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

7. Výběrem Hledat spusťte vyhledávání.

   Odpověď by měla být podobná následujícímu příkladu. Jedná se o fulltextový dotaz seřazený podle BM25, takže výsledky odpovídají jednotlivým termínům dotazu a lingvistickým variantám, nikoli celkovému významu dotazu. Například walking odpovídá walk, a live a music odpovídají nezávisle místo jedné fráze.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Tip

   Tento dotaz ukazuje, jak odpověď vypadá před uplatněním sémantického řazení. Po konfiguraci sémantické konfigurace přidejte "queryType": "semantic" a "semanticConfiguration": "semantic-config" podívejte se, jak je stejný dotaz seřazen jinak podle sémantického řazení.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

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

2. Přejděte do složky rychlý start a otevřete ji v Visual Studio Code.

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

3. V semantic-index-update.rest nahraďte zástupnou hodnotu pro @searchUrl adresou URL, kterou jste získali v Získání koncového bodu.

4. Opakujte předchozí krok pro semantic-query.rest.

5. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

6. Pro ověřování bez klíčů pomocí Microsoft Entra ID vygenerujte přístupový token.

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

7. V obou .rest souborech nahraďte zástupný znak @personalAccessToken tokenem z předchozího kroku.

Spuštění kódu

1. Otevřít semantic-index-update.rest.

2. V prvním požadavku GET vyberte Odeslat požadavek a ověřte připojení.

   V sousedním podokně by se měla zobrazit odpověď. Pokud máte existující indexy, jsou uvedené podle názvu. Pokud je kód HTTP 200 OK, můžete pokračovat.

3. ### Update the hotels-sample index to include a semantic configuration Odešlete žádost o přidání sémantické konfigurace do indexu.

   Pokud se zobrazí 400 Bad Request chyba, schéma indexu se liší od ukázky. ### Get the schema of the index Odešlete požadavek, zkopírujte JSON odpovědi, přidejte semantic oddíl ze zdrojového kódu do JSON a nahraďte tělo požadavku PUT vaším sloučeným schématem.

4. Postupně přepněte na semantic-query.rest a odešlete požadavky sekvenčně: jednoduchý dotaz pro základní srovnání a poté sémantické dotazy s řazením, popisky a odpověďmi.

Výstup

Požadavek Send a search query to the hotels-sample index vrátí výsledky seřazené podle relevance BM25, který je označen polem @search.score .

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

Požadavek Send a search query to the hotels-sample index with semantic ranking přidá @search.rerankerScore. Všimněte si, že pořadí se mění z jednoduchého dotazu.

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

Požadavek Return captions in the query se přidá s @search.captions, který obsahuje extrahovaný text a zvýraznění.

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

Požadavek Return semantic answers in the query vrátí extraktivní odpověď, když je dotaz @search.answers formulován jako otázka.

{
  "@odata.count": 46,
  "@search.answers": [
    {
      "key": "38",
      "text": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night...",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night...",
      "score": 0.9829999804496765
    }
  ],
  "value": [
    {
      "@search.score": 2.060124,
      "@search.rerankerScore": 2.124817371368408,
      "@search.captions": [
        {
          "text": "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city...",
          "highlights": "This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city..."
        }
      ],
      "HotelId": "1",
      "HotelName": "Stay-Kay City Hotel"
    },
    // Trimmed for brevity
  ]
}

Vysvětlení kódu

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Konfigurace a ověřování
2. Aktualizace indexu sémantickou konfigurací
3. Dotazování indexu

Konfigurace a ověřování

Oba .rest soubory definují proměnné v horní části pro opakované použití napříč všemi požadavky.

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

Klíčové poznatky:

• @searchUrl je koncový bod vaší vyhledávací služby.
• @personalAccessToken je token Microsoft Entra ID získaný z Azure CLI. Tím se nahradí klíče rozhraní API ověřováním bez klíčů.
• Authorization: Bearer {{personalAccessToken}} je součástí každé hlavičky požadavku pro ověřování.

Aktualizace indexu sémantickou konfigurací

Požadavek ### Update the hotels-sample index to include a semantic configuration v semantic-index-update.rest odešle úplné schéma indexu spolu s novou částí semantic. Rozhraní REST API vyžaduje úplné schéma pro jakoukoli operaci aktualizace, takže nemůžete odeslat pouze sémantickou konfiguraci.

Klíčovým přírůstkem je sekce semantic:

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

Klíčové poznatky:

• titleField určuje, které pole obsahuje název dokumentu pro sémantické vyhodnocení.
• prioritizedContentFields určuje pole hlavního obsahu. Sémantický ranker tyto hodnoty vyhodnotí jako první při vyhodnocování relevance.
• prioritizedKeywordsFields identifikuje pole klíčových slov nebo značek pro další kontext.
• rankingOrder: BoostedRerankerScore kombinuje skóre BM25 se skóre sémantického rerankeru.
• Rozhraní REST API vyžaduje úplné schéma pro operace PUT. Pouze oddíl semantic je nový; všechna ostatní pole zůstávají beze změny.

Dotazování indexu

Požadavky v semantic-query.rest postupují od jednoduchého vyhledávání klíčových slov k sémantickému řazení s popisky a odpověďmi. Všechny dotazy jsou požadavky POST na dokumenty – vyhledávací příspěvek (REST API).

Jednoduchý dotaz

Požadavek ### Send a search query to the hotels-sample index je jednoduché vyhledávání klíčových slov, které nepoužívá sémantické řazení. Slouží jako základ pro porovnávání výsledků se sémantickým přeřazením.

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

Klíčové poznatky:

• queryType: "simple" používá výchozí algoritmus řazení BM25.
• Výsledky jsou seřazené pouze podle relevance klíčových slov (@search.score).

Sémantický dotaz (žádné titulky, žádné odpovědi)

Požadavek ### Send a search query to the hotels-sample index with semantic ranking přidá sémantické řazení. Následující JSON ukazuje minimální požadavek na vyvolání sémantického řazení.

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

Klíčové poznatky:

• queryType: "semantic" umožňuje sémantické řazení dotazu.
• semanticConfiguration určuje, která sémantická konfigurace se má použít.

Sémantický dotaz s titulky

Požadavek ### Return captions in the query přidá titulky k extrakci nejrelevantnějších pasáží z každého výsledku, přičemž důležité termíny a fráze budou zvýrazněny.

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

Klíčové poznatky:

• captions: "extractive|highlight-true" umožňuje extrahovat titulky se značkami <em> kolem důležitých termínů.
• Titulky se zobrazí v @search.captions poli pro každý výsledek.

Sémantický dotaz s odpověďmi

Požadavek ### Return semantic answers in the query přidá sémantické odpovědi. Jako hledaný text používá otázku, protože sémantické odpovědi fungují nejlépe, když je dotaz frázován jako otázka. Odpovědí je doslovný úsek extrahovaný z indexu, nikoli složená odpověď z modelu dokončování chatu.

Dotaz a indexovaný obsah musí být úzce zarovnané, aby se vrátila odpověď. Pokud žádný kandidát nesplňuje prahovou hodnotu spolehlivosti, odpověď neobsahuje odpověď. V tomto příkladu se používá otázka, která je známá k vytvoření výsledku, abyste viděli syntaxi. Pokud odpovědi nejsou pro váš scénář užitečné, vynechte parametr answers z vaší žádosti. U složených odpovědí zvažte vzor RAG nebo získávání pomocí agentů.

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

Klíčové poznatky:

• answers: "extractive" umožňuje extrahovatelné odpovědi pro dotazy podobné dotazům.
• Odpovědi se zobrazují v poli nejvyšší úrovně @search.answers odděleně od jednotlivých výsledků.
• Odpovědi jsou doslovný obsah extrahovaný z indexu, negenerovaný text.