Rychlý start: Vektorové vyhledávání

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro .NET k vytvoření, načtení a dotazování indexu vector. Klientská knihovna .NET poskytuje abstrakci rozhraní REST API pro operace indexu.

V Azure AI Vyhledávač má vektorový index schéma, které definuje vektorová a nevectorová pole, konfiguraci vektorového vyhledávání algoritmů, které vytvářejí vložený prostor a nastavení definic vektorových polí, které se vyhodnocují v době dotazu. Indexy – Vytvoření nebo aktualizace (REST API) vytvoří vektorový index.

Návod

• Chcete začít hned? Stáhněte zdrojový kód na GitHub.
• Tento rychlý start vynechá krok vektorizace a poskytuje vložené vkládání. Pokud chcete integrovat vektorizaci nad vlastním obsahem, zkuste průvodce importem dat.

Požadavky

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

• Služba Azure AI Vyhledávač. Pro většinu tohoto rychlého startu můžete použít úroveň Free, ale pro větší datové soubory doporučujeme basic nebo vyšší.

• Sémantický ranker povolený ve vyhledávací službě pro volitelný sémantický hybridní dotaz.

• .NET 8 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 založený na rolích 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

   • Přispěvatel dat indexu vyhledávání

   • Č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. Na webu Azure Portal přejděte do vyhledávací služby.

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.

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-vector-search
   

3. Nahraďte v VectorSearchCreatePopulateIndex/appsettings.json zástupnou hodnotu Endpoint adresou URL, kterou jste získali v Get endpoint.

4. Opakujte předchozí krok pro VectorSearchExamples/appsettings.json.

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 vytvořte a naplňte index.

   cd VectorSearchCreatePopulateIndex
   dotnet run
   

2. V VectorSearchExamples/Program.cs odkomentujte metody dotazu, které chcete spustit.

3. Spuštěním druhého projektu spusťte tyto dotazy na index.

   cd ..\VectorSearchExamples
   dotnet run
   

Výstup

Výstup prvního projektu zahrnuje potvrzení vytvoření indexu a úspěšné nahrání dokumentu.

Creating or updating index 'hotels-vector-quickstart'...
Index 'hotels-vector-quickstart' updated.

Key: 1, Succeeded: True
Key: 2, Succeeded: True
Key: 3, Succeeded: True
Key: 4, Succeeded: True
Key: 48, Succeeded: True
Key: 49, Succeeded: True
Key: 13, Succeeded: True

Výstup druhého projektu zobrazuje výsledky hledání pro každou povolenou metodu dotazu. Následující příklad ukazuje výsledky hledání s jedním vektorem.

Single Vector Search Results:
Score: 0.6605852, HotelId: 48, HotelName: Nordick's Valley Motel
Score: 0.6333684, HotelId: 13, HotelName: Luxury Lion Resort
Score: 0.605672, HotelId: 4, HotelName: Sublime Palace Hotel
Score: 0.6026341, HotelId: 49, HotelName: Swirling Currents Hotel
Score: 0.57902366, HotelId: 2, HotelName: Old Century Hotel

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

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

1. Vytvoření indexu vektoru
2. Nahrání dokumentů do indexu
3. Dotazování indexu

Vytvoření indexu vektoru

Než přidáte obsah do Azure AI Vyhledávač, musíte vytvořit index, který definuje, jak se obsah ukládá a strukturuje.

Schéma indexu je uspořádané kolem obsahu hotelu. Ukázková data se skládají z vektorových a nevectorových popisů fiktivních hotelů. Následující kód v VectorSearchCreatePopulateIndex/Program.cs definuje schéma indexu, včetně vektorového pole DescriptionVector.

static async Task CreateSearchIndex(string indexName, SearchIndexClient indexClient)
{
    var addressField = new ComplexField("Address");
    addressField.Fields.Add(new SearchableField("StreetAddress") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft });
    addressField.Fields.Add(new SearchableField("City") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true });
    addressField.Fields.Add(new SearchableField("StateProvince") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true });
    addressField.Fields.Add(new SearchableField("PostalCode") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true });
    addressField.Fields.Add(new SearchableField("Country") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true });

    var allFields = new List<SearchField>()
    {
        new SimpleField("HotelId", SearchFieldDataType.String) { IsKey = true, IsFacetable = true, IsFilterable = true },
        new SearchableField("HotelName") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft },
        new SearchableField("Description") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft },
        new VectorSearchField("DescriptionVector", 1536, "my-vector-profile"),
        new SearchableField("Category") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true },
        new SearchableField("Tags", collection: true) { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true },
        new SimpleField("ParkingIncluded", SearchFieldDataType.Boolean) { IsFacetable = true, IsFilterable = true },
        new SimpleField("LastRenovationDate", SearchFieldDataType.DateTimeOffset) { IsSortable = true },
        new SimpleField("Rating", SearchFieldDataType.Double) { IsFacetable = true, IsFilterable = true, IsSortable = true },
        addressField,
        new SimpleField("Location", SearchFieldDataType.GeographyPoint) { IsFilterable = true, IsSortable = true },
    };

    // Create the suggester configuration
    var suggester = new SearchSuggester("sg", new[] { "Address/City", "Address/Country" });

    // Create the semantic search
    var semanticSearch = new SemanticSearch()
    {
        Configurations =
        {
            new SemanticConfiguration(
                name: "semantic-config",
                prioritizedFields: new SemanticPrioritizedFields
                {
                    TitleField = new SemanticField("HotelName"),
                    KeywordsFields = { new SemanticField("Category") },
                    ContentFields = { new SemanticField("Description") }
                })
        }
    };

    // Add vector search configuration
    var vectorSearch = new VectorSearch();
    vectorSearch.Algorithms.Add(new HnswAlgorithmConfiguration(name: "my-hnsw-vector-config-1"));
    vectorSearch.Profiles.Add(new VectorSearchProfile(name: "my-vector-profile", algorithmConfigurationName: "my-hnsw-vector-config-1"));

    var definition = new SearchIndex(indexName)
    {
        Fields = allFields,
        Suggesters = { suggester },
        VectorSearch = vectorSearch,
        SemanticSearch = semanticSearch
    };

    // Create or update the index
    Console.WriteLine($"Creating or updating index '{indexName}'...");
    var result = await indexClient.CreateOrUpdateIndexAsync(definition);
    Console.WriteLine($"Index '{result.Value.Name}' updated.");
    Console.WriteLine();
}

Hlavní klíčové body:

• Index definujete vytvořením seznamu polí.

• Tento konkrétní index podporuje více možností vyhledávání:

  • Fulltextové vyhledávání (SearchableField)

  • Vektorové vyhledávání (VectorSearchField)

  • Sémantické řazení (SemanticSearch)

  • Fasetové vyhledávání (pole označená IsFacetable)

  • Geografické prostorové vyhledávání (Location pole s SearchFieldDataType.GeographyPoint)

  • Filtrování a řazení (pole označená IsFilterable a IsSortable)

• Druhý parametr v VectorSearchField určuje vectorSearchDimensions, který musí odpovídat výstupní velikosti vkládacího modelu. V tomto rychlém startu se k modelu text-embedding-ada-002 používá 1 536 dimenzí.

• Konfigurace VectorSearch definuje algoritmus přibližného nejbližšího souseda (ANN). Mezi podporované algoritmy patří Hierarchický Navigovatelný Malý Svět (HNSW) a úplný K-Nearest Neighbor (KNN). Další informace najdete v tématu Relevance při hledání vektorů.

Nahrání dokumentů do indexu

Nově vytvořené indexy jsou prázdné. Pokud chcete naplnit index a nastavit, aby byl prohledávatelný, musíte nahrát dokumenty JSON, které odpovídají schématu indexu.

V Azure AI Vyhledávač slouží dokumenty jako vstupy pro indexování a výstupy pro dotazy. Pro zjednodušení tento rychlý start poskytuje ukázkové hotelové dokumenty s předem určenými vektory. V produkčních scénářích se obsah často načítá z připojených zdrojů dat a transformuje se do FORMÁTU JSON pomocí indexerů.

Následující kód nahraje dokumenty z HotelData.json vaší vyhledávací služby.

static async Task UploadDocs(SearchClient searchClient)
{
    var jsonPath = Path.Combine(Directory.GetCurrentDirectory(), "HotelData.json");

    // Read and parse hotel data
    var json = await File.ReadAllTextAsync(jsonPath);
    List<Hotel> hotels = new List<Hotel>();
    try
    {
        using var doc = JsonDocument.Parse(json);
        if (doc.RootElement.ValueKind != JsonValueKind.Array)
        {
            Console.WriteLine("HotelData.json root is not a JSON array.");
        }
        // Deserialize all hotel objects
        hotels = doc.RootElement.EnumerateArray()
            .Select(e => JsonSerializer.Deserialize<Hotel>(e.GetRawText()))
            .Where(h => h != null)
            .ToList();
    }
    catch (JsonException ex)
    {
        Console.WriteLine($"Failed to parse HotelData.json: {ex.Message}");
    }

    try
    {
        // Upload hotel documents to Azure Search
        var result = await searchClient.UploadDocumentsAsync(hotels);
        foreach (var r in result.Value.Results)
        {
            Console.WriteLine($"Key: {r.Key}, Succeeded: {r.Succeeded}");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Failed to upload documents: " + ex);
    }
}

Kód komunikuje s konkrétním indexem vyhledávání hostovaným ve službě Azure AI Vyhledávač prostřednictvím SearchClient, což je hlavní objekt poskytovaný balíčkem Azure.Search.Documents. Poskytuje SearchClient přístup k operacím indexu, například:

• Příjem dat: UploadDocuments(), MergeDocuments()DeleteDocuments()

• Vyhledávací operace: Search(), Autocomplete()Suggest()

Dotazování indexu

Dotazy demonstrují VectorSearchExamples různé vzory hledání. Ukázkové vektorové dotazy jsou založené na dvou řetězcích:

• Textový řetězec pro fulltextové vyhledávání: "historic hotel walk to restaurants and shopping"

• Řetězec vektorového dotazu: "quintessential lodging near running trails, eateries, retail" (vektorizovaný na matematickou reprezentaci)

Řetězec vektorového dotazu je sémanticky podobný fulltextového hledanému řetězci, ale obsahuje výrazy, které v indexu neexistují. Hledání řetězce vektorového dotazu pouze s klíčovým slovem vrátí nulové výsledky. Hledání vektorů ale najde relevantní shody na základě významu, nikoli přesných klíčových slov.

Následující příklady začínají základním vektorovým dotazem a postupně přidávají filtry, vyhledávání klíčových slov a sémantické řazení.

Jednoúčelové vyhledávání vektorů

Tato SearchSingleVector metoda ukazuje základní scénář, ve kterém chcete najít popisy dokumentu, které úzce odpovídají řetězci vektorového dotazu. VectorizedQuery nakonfiguruje vektorové vyhledávání:

• KNearestNeighborsCount omezuje počet vrácených výsledků na základě podobnosti vektorů.
• Fields určuje vektorové pole, na které se má hledat.

public static async Task SearchSingleVector(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
        new SearchOptions
        {
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Select = { "HotelId", "HotelName", "Description", "Category", "Tags" },
        });

    Console.WriteLine($"Single Vector Search Results:");
    await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"Score: {result.Score}, HotelId: {doc.HotelId}, HotelName: {doc.HotelName}");
    }
    Console.WriteLine();
}

Vyhledávání jednoho vektoru s filtrem

Ve službě Azure AI Vyhledávač filtry se používají na nevektorová pole v indexu. Metoda SearchSingleVectorWithFilter filtruje hotely podle pole Tags a vyloučí všechny, které neposkytují bezplatné Wi-Fi.

public static async Task SearchSingleVectorWithFilter(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> responseWithFilter = await searchClient.SearchAsync<Hotel>(
        new SearchOptions
        {
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Filter = "Tags/any(tag: tag eq 'free wifi')",
            Select = { "HotelId", "HotelName", "Description", "Category", "Tags" }
        });

    Console.WriteLine($"Single Vector Search With Filter Results:");
    await foreach (SearchResult<Hotel> result in responseWithFilter.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"Score: {result.Score}, HotelId: {doc.HotelId}, HotelName: {doc.HotelName}, Tags: {string.Join(String.Empty, doc.Tags)}");
    }
    Console.WriteLine();
}

Vyhledávání s jedním vektorem s geografickým filtrem

Můžete zadat geoprostorový filtr , který omezí výsledky na konkrétní geografickou oblast. Metoda SingleSearchWithGeoFilter určuje geografický bod (Washington D.C., pomocí souřadnic zeměpisné délky a zeměpisné šířky) a vrátí hotely v okruhu 300 kilometrů. Ve výchozím nastavení se filtry spouští po hledání vektorů.

public static async Task SingleSearchWithGeoFilter(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> responseWithGeoFilter = await searchClient.SearchAsync<Hotel>(
        new SearchOptions
        {
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Filter = "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
            Select = { "HotelId", "HotelName", "Description", "Address", "Category", "Tags" },
            Facets = { "Address/StateProvince" },
        });

    Console.WriteLine($"Vector query with a geo filter:");
    await foreach (SearchResult<Hotel> result in responseWithGeoFilter.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"HotelId: {doc.HotelId}");
        Console.WriteLine($"HotelName: {doc.HotelName}");
        Console.WriteLine($"Score: {result.Score}");
        Console.WriteLine($"City/State: {doc.Address.City}/{doc.Address.StateProvince}");
        Console.WriteLine($"Description: {doc.Description}");
        Console.WriteLine();
    }
    Console.WriteLine();
}

Hybridní vyhledávání

Hybridní vyhledávání kombinuje fulltextové a vektorové dotazy v jednom požadavku. Metoda SearchHybridVectorAndText spouští oba typy dotazů současně a pak pomocí reciproční Rank Fusion (RRF) sloučí výsledky do sjednoceného pořadí. RRF používá inverzní pořadí hodnocení z každé sady výsledků k vytvoření sloučeného pořadí. Všimněte si, že skóre hybridního vyhledávání jsou jednotně menší než skóre s jedním dotazem.

public static async Task<SearchResults<Hotel>> SearchHybridVectorAndText(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> responseWithFilter = await searchClient.SearchAsync<Hotel>(
        "historic hotel walk to restaurants and shopping",
        new SearchOptions
        {
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Select = { "HotelId", "HotelName", "Description", "Category", "Tags" },
            Size = 5,
        });

    Console.WriteLine($"Hybrid search results:");
    await foreach (SearchResult<Hotel> result in responseWithFilter.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"Score: {result.Score}");
        Console.WriteLine($"HotelId: {doc.HotelId}");
        Console.WriteLine($"HotelName: {doc.HotelName}");
        Console.WriteLine($"Description: {doc.Description}");
        Console.WriteLine($"Category: {doc.Category}");
        Console.WriteLine($"Tags: {string.Join(String.Empty, doc.Tags)}");
        Console.WriteLine();
    }
    Console.WriteLine();
    return responseWithFilter;
}

Sémantické hybridní vyhledávání

Metoda SearchHybridVectorAndSemantic ukazuje sémantické řazení, které přeřazuje výsledky na základě porozumění jazyku.

public static async Task SearchHybridVectorAndSemantic(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> responseWithFilter = await searchClient.SearchAsync<Hotel>(
        "historic hotel walk to restaurants and shopping",
        new SearchOptions
        {
            IncludeTotalCount = true,
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Select = { "HotelId", "HotelName", "Description", "Category", "Tags" },
            SemanticSearch = new SemanticSearchOptions
            {
                SemanticConfigurationName = "semantic-config"
            },
            QueryType = SearchQueryType.Semantic,
            Size = 5
        });

    Console.WriteLine($"Hybrid search results:");
    await foreach (SearchResult<Hotel> result in responseWithFilter.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"Score: {result.Score}");
        Console.WriteLine($"HotelId: {doc.HotelId}");
        Console.WriteLine($"HotelName: {doc.HotelName}");
        Console.WriteLine($"Description: {doc.Description}");
        Console.WriteLine($"Category: {doc.Category}");
        Console.WriteLine();
    }
    Console.WriteLine();
}

Porovnejte tyto výsledky s výsledky hybridního hledání z předchozího dotazu. Bez sémantického hodnocení se Sublime Palace Hotel řadí jako první, protože Reciproční Rank Fusion (RRF) kombinuje text a vektorové skóre, aby vznikl sloučený výsledek. Po sémantickém přehodnocení se Hotel Swirling Currents přesune na nejvyšší místo.

Sémantický ranker používá modely strojového porozumění k vyhodnocení, jak dobře jednotlivé výsledky odpovídají záměru dotazu. Swirling Currents Hotel v popisu zmiňuje "walking access to shopping, dining, entertainment and the city center", což se úzce shoduje s vyhledávacím dotazem "walk to restaurants and shopping". Tento sémantický zápas pro nedaleké restaurace a nakupování ho staví nad Sublime Palace Hotel, který ve svém popisu nezvýrazňuje pěší dostupnost svých možností.

Hlavní klíčové body:

• V hybridním vyhledávání můžete integrovat vektorové vyhledávání s fulltextovým vyhledáváním pomocí klíčových slov. Filtry a sémantické řazení se vztahují pouze na textový obsah, nikoli vektory.

• Skutečné výsledky obsahují více podrobností, včetně sémantických titulků a zvýraznění. Tento rychlý start upraví výsledky pro čitelnost. Pokud chcete získat úplnou strukturu odpovědi, spusťte požadavek pomocí rest.

Vyčistěte zdroje

Když pracujete ve vlastním předplatném, je vhodné dokončit projekt odebráním prostředků, které už nepotřebujete. Prostředky, které zůstaly spuštěné, vám můžou stát peníze.

Na portálu Azure vyberte Všechny prostředky nebo Zdrojové skupiny v levém podokně a vyhledejte a spravujte prostředky. Prostředky můžete odstranit jednotlivě nebo odstranit skupinu prostředků a odebrat tak všechny prostředky najednou.

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro Java k vytvoření, načtení a dotazování indexu vector. Klientská knihovna Java poskytuje abstrakci rozhraní REST API pro operace indexu.

V Azure AI Vyhledávač má vektorový index schéma, které definuje vektorová a nevectorová pole, konfiguraci vektorového vyhledávání algoritmů, které vytvářejí vložený prostor a nastavení definic vektorových polí, které se vyhodnocují v době dotazu. Indexy – Vytvoření nebo aktualizace (REST API) vytvoří vektorový index.

Návod

• Chcete začít hned? Stáhněte zdrojový kód na GitHub.
• Tento rychlý start vynechá krok vektorizace a poskytuje vložené vkládání. Pokud chcete integrovat vektorizaci nad vlastním obsahem, zkuste průvodce importem dat.

Požadavky

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

• Služba Azure AI Vyhledávač. Pro většinu tohoto rychlého startu můžete použít úroveň Free, ale pro větší datové soubory doporučujeme basic nebo vyšší.

• Sémantický ranker povolený ve vyhledávací službě pro volitelný sémantický hybridní dotaz.

• 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 založený na rolích 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

   • Přispěvatel dat indexu vyhledávání

   • Č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. Na webu Azure Portal přejděte do vyhledávací služby.

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.

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-vector-search
   

3. Nahraďte v src/main/resources/application.properties zástupnou hodnotu azure.search.endpoint adresou URL, kterou jste získali v Get endpoint.

4. Nainstalujte závislosti.

   mvn clean dependency:copy-dependencies
   

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

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. Vytvoření vektorového indexu

   mvn compile exec:java "-Dexec.mainClass=com.example.search.CreateIndex"
   

2. Načtěte dokumenty, které obsahují předem vypočítané embeddingy.

   mvn compile exec:java "-Dexec.mainClass=com.example.search.UploadDocuments"
   

3. Spusťte vektorový vyhledávací dotaz.

   mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchSingle"
   

4. (Volitelné) Spusťte další varianty dotazů.

   mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchSingleWithFilter"
   mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchSingleWithFilterGeo"
   mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchHybrid"
   mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchSemanticHybrid"
   

Výstup

Výstup CreateIndex.java zobrazuje název indexu a potvrzení.

Using Azure Search endpoint: https://<search-service-name>.search.windows.net
Using Azure Search index: hotels-vector-quickstart
Creating index...
hotels-vector-quickstart created

Výstup UploadDocuments.java ukazuje stav úspěchu pro každý indexovaný dokument.

Uploading documents...
Key: 1, Succeeded: true, ErrorMessage: none
Key: 2, Succeeded: true, ErrorMessage: none
Key: 3, Succeeded: true, ErrorMessage: none
Key: 4, Succeeded: true, ErrorMessage: none
Key: 48, Succeeded: true, ErrorMessage: none
Key: 49, Succeeded: true, ErrorMessage: none
Key: 13, Succeeded: true, ErrorMessage: none
Waiting for indexing... Current count: 0
All documents indexed successfully.

Výstup ukazuje výsledky vektorového SearchSingle.java hledání seřazené podle skóre podobnosti.

Single Vector search found 5
- HotelId: 48, HotelName: Nordick's Valley Motel, Tags: ["continental breakfast","air conditioning","free wifi"], Score 0.6605852
- HotelId: 13, HotelName: Luxury Lion Resort, Tags: ["bar","concierge","restaurant"], Score 0.6333684
- HotelId: 4, HotelName: Sublime Palace Hotel, Tags: ["concierge","view","air conditioning"], Score 0.605672
- HotelId: 49, HotelName: Swirling Currents Hotel, Tags: ["air conditioning","laundry service","24-hour front desk service"], Score 0.6026341
- HotelId: 2, HotelName: Old Century Hotel, Tags: ["pool","free wifi","air conditioning","concierge"], Score 0.57902366

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

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

1. Vytvoření indexu vektoru
2. Nahrání dokumentů do indexu
3. Dotazování indexu

Vytvoření indexu vektoru

Než přidáte obsah do Azure AI Vyhledávač, musíte vytvořit index, který definuje, jak se obsah ukládá a strukturuje.

Schéma indexu je uspořádané kolem obsahu hotelu. Ukázková data se skládají z vektorových a nevectorových popisů fiktivních hotelů. Následující kód v CreateIndex.java definuje schéma indexu, včetně vektorového pole DescriptionVector.

// Define fields
List<SearchField> fields = Arrays.asList(
    new SearchField("HotelId", SearchFieldDataType.STRING)
        .setKey(true)
        .setFilterable(true),
    new SearchField("HotelName", SearchFieldDataType.STRING)
        .setSortable(true)
        .setSearchable(true),
    new SearchField("Description", SearchFieldDataType.STRING)
        .setSearchable(true),
    new SearchField("DescriptionVector",
        SearchFieldDataType.collection(SearchFieldDataType.SINGLE))
        .setSearchable(true)
        .setVectorSearchDimensions(1536)
        .setVectorSearchProfileName("my-vector-profile"),
    new SearchField("Category", SearchFieldDataType.STRING)
        .setSortable(true)
        .setFilterable(true)
        .setFacetable(true)
        .setSearchable(true),
    new SearchField("Tags", SearchFieldDataType.collection(
        SearchFieldDataType.STRING))
        .setSearchable(true)
        .setFilterable(true)
        .setFacetable(true),
    // Additional fields: ParkingIncluded, LastRenovationDate, Rating, Address, Location
);

var searchIndex = new SearchIndex(indexName, fields);

// Define vector search configuration
var hnswParams = new HnswParameters()
    .setM(16)
    .setEfConstruction(200)
    .setEfSearch(128);
var hnsw = new HnswAlgorithmConfiguration("hnsw-vector-config");
hnsw.setParameters(hnswParams);

var vectorProfile = new VectorSearchProfile(
    "my-vector-profile",
    "hnsw-vector-config");
var vectorSearch = new VectorSearch()
    .setAlgorithms(Arrays.asList(hnsw))
    .setProfiles(Arrays.asList(vectorProfile));
searchIndex.setVectorSearch(vectorSearch);

// Define semantic configuration
var prioritizedFields = new SemanticPrioritizedFields()
    .setTitleField(new SemanticField("HotelName"))
    .setContentFields(Arrays.asList(new SemanticField("Description")))
    .setKeywordsFields(Arrays.asList(new SemanticField("Category")));
var semanticConfig = new SemanticConfiguration(
    "semantic-config",
    prioritizedFields);
var semanticSearch = new SemanticSearch()
    .setConfigurations(Arrays.asList(semanticConfig));
searchIndex.setSemanticSearch(semanticSearch);

// Define suggesters
var suggester = new SearchSuggester("sg", Arrays.asList("HotelName"));
searchIndex.setSuggesters(Arrays.asList(suggester));

// Create the search index
SearchIndex result = searchIndexClient.createOrUpdateIndex(searchIndex);

Hlavní klíčové body:

• Index definujete vytvořením seznamu polí.

• Tento konkrétní index podporuje více možností vyhledávání:

  • Fulltextové vyhledávání (setSearchable)

  • Vektorové vyhledávání (DescriptionVector s setVectorSearchProfileName)

  • Sémantické řazení (SemanticConfiguration)

  • Fasetové vyhledávání (pole označená setFacetable)

  • Geografické prostorové vyhledávání (Location pole s SearchFieldDataType.GEOGRAPHY_POINT)

  • Filtrování a řazení (pole označená setFilterable a setSortable)

• Hodnota setVectorSearchDimensions() se musí shodovat s velikostí výstupu vloženého modelu. V tomto rychlém startu se k modelu text-embedding-ada-002 používá 1 536 dimenzí.

• Konfigurace VectorSearch definuje algoritmus přibližného nejbližšího souseda (ANN). Mezi podporované algoritmy patří Hierarchický Navigovatelný Malý Svět (HNSW) a úplný K-Nearest Neighbor (KNN). Další informace najdete v tématu Relevance při hledání vektorů.

Nahrání dokumentů do indexu

Nově vytvořené indexy jsou prázdné. Pokud chcete naplnit index a nastavit, aby byl prohledávatelný, musíte nahrát dokumenty JSON, které odpovídají schématu indexu.

V Azure AI Vyhledávač slouží dokumenty jako vstupy pro indexování a výstupy pro dotazy. Pro zjednodušení tento rychlý start poskytuje ukázkové hotelové dokumenty s předem určenými vektory. V produkčních scénářích se obsah často načítá z připojených zdrojů dat a transformuje se do FORMÁTU JSON pomocí indexerů.

Následující kód přenese dokumenty do vaší vyhledávací služby.

// Documents contain hotel data with 1536-dimension vectors for DescriptionVector
static final List<Map<String, Object>> DOCUMENTS = Arrays.asList(
    new HashMap<>() {{
        put("@search.action", "mergeOrUpload");
        put("HotelId", "1");
        put("HotelName", "Stay-Kay City Hotel");
        put("Description", "This classic hotel is fully-refurbished...");
        put("DescriptionVector", Arrays.asList(/* 1536 float values */));
        put("Category", "Boutique");
        put("Tags", Arrays.asList("view", "air conditioning", "concierge"));
        // Additional fields...
    }}
    // Additional hotel documents
);

// Upload documents to the index
IndexDocumentsResult result = searchClient.uploadDocuments(DOCUMENTS);
for (IndexingResult r : result.getResults()) {
    System.out.println("Key: %s, Succeeded: %s".formatted(r.getKey(), r.isSucceeded()));
}

Kód komunikuje s konkrétním indexem vyhledávání hostovaným ve službě Azure AI Vyhledávač prostřednictvím SearchClient, což je hlavní objekt poskytovaný balíčkem azure-search-documents. Tento SearchClient poskytuje přístup k operacím, jako jsou:

• Příjem dat: uploadDocuments, mergeDocumentsdeleteDocuments

• Vyhledávací operace: search, autocompletesuggest

Dotazování indexu

Dotazy ve vyhledávacích souborech ukazují různé vzory hledání. Ukázkové vektorové dotazy jsou založené na dvou řetězcích:

• Textový řetězec pro fulltextové vyhledávání: "historic hotel walk to restaurants and shopping"

• Řetězec vektorového dotazu: "quintessential lodging near running trails, eateries, retail" (vektorizovaný na matematickou reprezentaci)

Řetězec vektorového dotazu je sémanticky podobný fulltextového hledanému řetězci, ale obsahuje výrazy, které v indexu neexistují. Hledání řetězce vektorového dotazu pouze s klíčovým slovem vrátí nulové výsledky. Hledání vektorů ale najde relevantní shody na základě významu, nikoli přesných klíčových slov.

Následující příklady začínají základním vektorovým dotazem a postupně přidávají filtry, vyhledávání klíčových slov a sémantické řazení.

Jednoúčelové vyhledávání vektorů

SearchSingle.java demonstruje základní scénář, ve kterém chcete najít popisy dokumentu, které úzce odpovídají řetězci vektorového dotazu. VectorizedQuery nakonfiguruje vektorové vyhledávání:

• setKNearestNeighborsCount() omezuje počet vrácených výsledků na základě podobnosti vektorů.
• setFields() určuje vektorové pole, na které se má hledat.

var vectorQuery = new VectorizedQuery(QueryVector.getVectorList())
    .setKNearestNeighborsCount(5)
    .setFields("DescriptionVector")
    .setExhaustive(true);

var vectorSearchOptions = new VectorSearchOptions()
    .setQueries(vectorQuery)
    .setFilterMode(VectorFilterMode.POST_FILTER);

var searchOptions = new SearchOptions()
    .setTop(7)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Description", "Category", "Tags")
    .setVectorSearchOptions(vectorSearchOptions);

var results = searchClient.search("*", searchOptions, Context.NONE);

for (SearchResult result : results) {
    SearchDocument document = result.getDocument(SearchDocument.class);
    System.out.println("HotelId: %s, HotelName: %s, Score: %s".formatted(
        document.get("HotelId"), document.get("HotelName"), result.getScore()));
}

Vyhledávání jednoho vektoru s filtrem

Ve službě Azure AI Vyhledávač filtry se používají na nevektorová pole v indexu. SearchSingleWithFilter.java filtry na poli Tags vyfiltrují všechny hotely, které neposkytují bezplatné Wi-Fi.

var vectorQuery = new VectorizedQuery(QueryVector.getVectorList())
    .setKNearestNeighborsCount(5)
    .setFields("DescriptionVector")
    .setExhaustive(true);

var vectorSearchOptions = new VectorSearchOptions()
    .setQueries(vectorQuery)
    .setFilterMode(VectorFilterMode.POST_FILTER);

// Add filter for "free wifi" tag
var searchOptions = new SearchOptions()
    .setTop(7)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Description", "Category", "Tags")
    .setFilter("Tags/any(tag: tag eq 'free wifi')")
    .setVectorSearchOptions(vectorSearchOptions);

var results = searchClient.search("*", searchOptions, Context.NONE);

Vyhledávání s jedním vektorem s geografickým filtrem

Můžete zadat geoprostorový filtr , který omezí výsledky na konkrétní geografickou oblast. SearchSingleWithGeoFilter.java určuje geografický bod (Washington D.C., pomocí souřadnic zeměpisné délky a zeměpisné šířky) a vrátí hotely v okruhu 300 kilometrů. Metoda setFilterMode, volaná na VectorSearchOptions, určuje, kdy se filtr spustí. V tomto případě POST_FILTER spustí filtr po hledání vektoru.

var searchOptions = new SearchOptions()
    .setTop(5)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Category", "Description",
               "Address/City", "Address/StateProvince")
    .setFacets("Address/StateProvince")
    .setFilter("geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300")
    .setVectorSearchOptions(vectorSearchOptions);

Hybridní vyhledávání

Hybridní vyhledávání kombinuje fulltextové a vektorové dotazy v jednom požadavku. SearchHybrid.java spustí oba typy dotazů současně a potom pomocí reciproční Rank Fusion (RRF) sloučí výsledky do sjednoceného pořadí. RRF používá inverzní pořadí hodnocení z každé sady výsledků k vytvoření sloučeného pořadí. Všimněte si, že skóre hybridního vyhledávání jsou jednotně menší než skóre s jedním dotazem.

var vectorQuery = new VectorizedQuery(QueryVector.getVectorList())
    .setKNearestNeighborsCount(5)
    .setFields("DescriptionVector")
    .setExhaustive(true);

var vectorSearchOptions = new VectorSearchOptions()
    .setQueries(vectorQuery)
    .setFilterMode(VectorFilterMode.POST_FILTER);

var searchOptions = new SearchOptions()
    .setTop(5)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Description", "Category", "Tags")
    .setVectorSearchOptions(vectorSearchOptions);

// Pass both text query and vector search options
var results = searchClient.search(
    "historic hotel walk to restaurants and shopping",
    searchOptions, Context.NONE);

Sémantické hybridní vyhledávání

SearchSemanticHybrid.java ukazuje sémantické řazení, které přeřazuje výsledky na základě porozumění jazyku.

var vectorQuery = new VectorizedQuery(QueryVector.getVectorList())
    .setKNearestNeighborsCount(5)
    .setFields("DescriptionVector")
    .setExhaustive(true);

var vectorSearchOptions = new VectorSearchOptions()
    .setQueries(vectorQuery)
    .setFilterMode(VectorFilterMode.POST_FILTER);

SemanticSearchOptions semanticSearchOptions = new SemanticSearchOptions()
    .setSemanticConfigurationName("semantic-config");

var searchOptions = new SearchOptions()
    .setTop(5)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Category", "Description")
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(semanticSearchOptions)
    .setVectorSearchOptions(vectorSearchOptions);

var results = searchClient.search(
    "historic hotel walk to restaurants and shopping",
    searchOptions, Context.NONE);

Porovnejte tyto výsledky s výsledky hybridního hledání z předchozího dotazu. Bez sémantického hodnocení se Sublime Palace Hotel řadí jako první, protože Reciproční Rank Fusion (RRF) kombinuje text a vektorové skóre, aby vznikl sloučený výsledek. Po sémantickém přehodnocení se Hotel Swirling Currents přesune na nejvyšší místo.

Sémantický ranker používá modely strojového porozumění k vyhodnocení, jak dobře jednotlivé výsledky odpovídají záměru dotazu. Swirling Currents Hotel v popisu zmiňuje "walking access to shopping, dining, entertainment and the city center", což se úzce shoduje s vyhledávacím dotazem "walk to restaurants and shopping". Tento sémantický zápas pro nedaleké restaurace a nakupování ho staví nad Sublime Palace Hotel, který ve svém popisu nezvýrazňuje pěší dostupnost svých možností.

Hlavní klíčové body:

• V hybridním vyhledávání můžete integrovat vektorové vyhledávání s fulltextovým vyhledáváním pomocí klíčových slov. Filtry a sémantické řazení se vztahují pouze na textový obsah, nikoli vektory.

• Skutečné výsledky obsahují více podrobností, včetně sémantických titulků a zvýraznění. Tento rychlý start upraví výsledky pro čitelnost. Pokud chcete získat úplnou strukturu odpovědi, spusťte požadavek pomocí rest.

Vyčistěte zdroje

Když pracujete ve vlastním předplatném, je vhodné dokončit projekt odebráním prostředků, které už nepotřebujete. Prostředky, které zůstaly spuštěné, vám můžou stát peníze.

Na portálu Azure vyberte Všechny prostředky nebo Zdrojové skupiny v levém podokně a vyhledejte a spravujte prostředky. Prostředky můžete odstranit jednotlivě nebo odstranit skupinu prostředků a odebrat tak všechny prostředky najednou.

V opačném případě spuštěním následujícího příkazu odstraňte index, který jste vytvořili v tomto rychlém startu.

mvn compile exec:java "-Dexec.mainClass=com.example.search.DeleteIndex"

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro JavaScript k vytvoření, načtení a dotazování indexu vector. Klientská knihovna JavaScriptu poskytuje abstrakci rozhraní REST API pro operace indexu.

V Azure AI Vyhledávač má vektorový index schéma, které definuje vektorová a nevectorová pole, konfiguraci vektorového vyhledávání algoritmů, které vytvářejí vložený prostor a nastavení definic vektorových polí, které se vyhodnocují v době dotazu. Indexy – Vytvoření nebo aktualizace (REST API) vytvoří vektorový index.

Návod

• Chcete začít hned? Stáhněte zdrojový kód na GitHub.
• Tento rychlý start vynechá krok vektorizace a poskytuje vložené vkládání. Pokud chcete integrovat vektorizaci nad vlastním obsahem, zkuste průvodce importem dat.

Požadavky

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

• Služba Azure AI Vyhledávač. Pro většinu tohoto rychlého startu můžete použít úroveň Free, ale pro větší datové soubory doporučujeme basic nebo vyšší.

• Sémantický ranker povolený ve vyhledávací službě pro volitelný sémantický hybridní dotaz.

• 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 založený na rolích 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

   • Přispěvatel dat indexu vyhledávání

   • Č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. Na webu Azure Portal přejděte do vyhledávací služby.

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.

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-vector-js
   

3. Nahraďte v sample.env zástupnou hodnotu AZURE_SEARCH_ENDPOINT adresou URL, kterou jste získali v Get endpoint.

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. Vytvoření vektorového indexu

   node -r dotenv/config src/createIndex.js
   

2. Načtěte dokumenty, které obsahují předem vypočítané embeddingy.

   node -r dotenv/config src/uploadDocuments.js
   

3. Spusťte vektorový vyhledávací dotaz.

   node -r dotenv/config src/searchSingle.js
   

4. (Volitelné) Spusťte další varianty dotazů.

   node -r dotenv/config src/searchSingleWithFilter.js
   node -r dotenv/config src/searchSingleWithFilterGeo.js
   node -r dotenv/config src/searchHybrid.js
   node -r dotenv/config src/searchSemanticHybrid.js
   

Výstup

Výstup createIndex.js zobrazuje název indexu a potvrzení.

Using Azure Search endpoint: https://<search-service-name>.search.windows.net
Using Azure Search index: hotels-vector-quickstart
Creating index...
hotels-vector-quickstart created

Výstup uploadDocuments.js ukazuje stav úspěchu pro každý indexovaný dokument.

Uploading documents...
Key: 1, Succeeded: true, ErrorMessage: none
Key: 2, Succeeded: true, ErrorMessage: none
Key: 3, Succeeded: true, ErrorMessage: none
Key: 4, Succeeded: true, ErrorMessage: none
Key: 48, Succeeded: true, ErrorMessage: none
Key: 49, Succeeded: true, ErrorMessage: none
Key: 13, Succeeded: true, ErrorMessage: none
Waiting for indexing... Current count: 0
All documents indexed successfully.

Výstup ukazuje výsledky vektorového searchSingle.js hledání seřazené podle skóre podobnosti.

Single Vector search found 5
- HotelId: 48, HotelName: Nordick's Valley Motel, Tags: ["continental breakfast","air conditioning","free wifi"], Score 0.6605852
- HotelId: 13, HotelName: Luxury Lion Resort, Tags: ["bar","concierge","restaurant"], Score 0.6333684
- HotelId: 4, HotelName: Sublime Palace Hotel, Tags: ["concierge","view","air conditioning"], Score 0.605672
- HotelId: 49, HotelName: Swirling Currents Hotel, Tags: ["air conditioning","laundry service","24-hour front desk service"], Score 0.6026341
- HotelId: 2, HotelName: Old Century Hotel, Tags: ["pool","free wifi","air conditioning","concierge"], Score 0.57902366

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

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

1. Vytvoření indexu vektoru
2. Nahrání dokumentů do indexu
3. Dotazování indexu

Vytvoření indexu vektoru

Než přidáte obsah do Azure AI Vyhledávač, musíte vytvořit index, který definuje, jak se obsah ukládá a strukturuje.

Schéma indexu je uspořádané kolem obsahu hotelu. Ukázková data se skládají z vektorových a nevectorových popisů fiktivních hotelů. Následující kód v createIndex.js definuje schéma indexu, včetně vektorového pole DescriptionVector.

const searchFields = [
    { name: "HotelId", type: "Edm.String", key: true, sortable: true, filterable: true, facetable: true },
    { name: "HotelName", type: "Edm.String", searchable: true, filterable: true },
    { name: "Description", type: "Edm.String", searchable: true },
    {
        name: "DescriptionVector",
        type: "Collection(Edm.Single)",
        searchable: true,
        vectorSearchDimensions: 1536,
        vectorSearchProfileName: "vector-profile"
    },
    { name: "Category", type: "Edm.String", filterable: true, facetable: true },
    { name: "Tags", type: "Collection(Edm.String)", filterable: true },
    // Additional fields: ParkingIncluded, LastRenovationDate, Rating, Address, Location
];

const vectorSearch = {
    profiles: [
        {
            name: "vector-profile",
            algorithmConfigurationName: "vector-search-algorithm"
        }
    ],
    algorithms: [
        {
            name: "vector-search-algorithm",
            kind: "hnsw",
            parameters: { m: 4, efConstruction: 400, efSearch: 1000, metric: "cosine" }
        }
    ]
};

const semanticSearch = {
    configurations: [
        {
            name: "semantic-config",
            prioritizedFields: {
                contentFields: [{ name: "Description" }],
                keywordsFields: [{ name: "Category" }],
                titleField: { name: "HotelName" }
            }
        }
    ]
};

const searchIndex = {
    name: indexName,
    fields: searchFields,
    vectorSearch: vectorSearch,
    semanticSearch: semanticSearch,
    suggesters: [{ name: "sg", searchMode: "analyzingInfixMatching", sourceFields: ["HotelName"] }]
};

const result = await indexClient.createOrUpdateIndex(searchIndex);

Hlavní klíčové body:

• Index definujete vytvořením seznamu polí.

• Tento konkrétní index podporuje více možností vyhledávání:

  • Fulltextové vyhledávání (searchable: true)

  • Vektorové vyhledávání (DescriptionVector s vectorSearchProfileName)

  • Sémantické řazení (semanticSearch)

  • Fasetové vyhledávání (pole označená facetable)

  • Geografické prostorové vyhledávání (Location pole s Edm.GeographyPoint)

  • Filtrování a řazení (pole označená filterable a sortable)

• Vlastnost vectorSearchDimensions se musí shodovat s výstupní velikostí modelu vkládání. V tomto rychlém startu se k modelu text-embedding-ada-002 používá 1 536 dimenzí.

• Konfigurace vectorSearch definuje algoritmus přibližného nejbližšího souseda (ANN). Mezi podporované algoritmy patří Hierarchický Navigovatelný Malý Svět (HNSW) a úplný K-Nearest Neighbor (KNN). Další informace najdete v tématu Relevance při hledání vektorů.

Nahrání dokumentů do indexu

Nově vytvořené indexy jsou prázdné. Pokud chcete naplnit index a nastavit, aby byl prohledávatelný, musíte nahrát dokumenty JSON, které odpovídají schématu indexu.

V Azure AI Vyhledávač slouží dokumenty jako vstupy pro indexování a výstupy pro dotazy. Pro zjednodušení tento rychlý start poskytuje ukázkové hotelové dokumenty s předem určenými vektory. V produkčních scénářích se obsah často načítá z připojených zdrojů dat a transformuje se do FORMÁTU JSON pomocí indexerů.

Následující kód přenese dokumenty do vaší vyhledávací služby.

const DOCUMENTS = [
    // Array of hotel documents with embedded 1536-dimension vectors
    // Each document contains: HotelId, HotelName, Description, DescriptionVector,
    // Category, Tags, ParkingIncluded, LastRenovationDate, Rating, Address, Location
];

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

const result = await searchClient.uploadDocuments(DOCUMENTS);
for (const r of result.results) {
    console.log(`Key: ${r.key}, Succeeded: ${r.succeeded}`);
}

Kód komunikuje s konkrétním indexem vyhledávání hostovaným ve službě Azure AI Vyhledávač prostřednictvím SearchClient, což je hlavní objekt poskytovaný balíčkem @azure/search-documents. Poskytuje SearchClient přístup k operacím indexu, například:

• Příjem dat: uploadDocuments, mergeDocumentsdeleteDocuments

• Vyhledávací operace: search, autocompletesuggest

Dotazování indexu

Dotazy ve vyhledávacích souborech ukazují různé vzory hledání. Ukázkové vektorové dotazy jsou založené na dvou řetězcích:

• Textový řetězec pro fulltextové vyhledávání: "historic hotel walk to restaurants and shopping"

• Řetězec vektorového dotazu: "quintessential lodging near running trails, eateries, retail" (vektorizovaný na matematickou reprezentaci)

Řetězec vektorového dotazu je sémanticky podobný fulltextového hledanému řetězci, ale obsahuje výrazy, které v indexu neexistují. Hledání řetězce vektorového dotazu pouze s klíčovým slovem vrátí nulové výsledky. Hledání vektorů ale najde relevantní shody na základě významu, nikoli přesných klíčových slov.

Následující příklady začínají základním vektorovým dotazem a postupně přidávají filtry, vyhledávání klíčových slov a sémantické řazení.

Jednoúčelové vyhledávání vektorů

searchSingle.js demonstruje základní scénář, ve kterém chcete najít popisy dokumentu, které úzce odpovídají řetězci vektorového dotazu. Objekt vectorQuery nakonfiguruje vektorové vyhledávání:

• kNearestNeighborsCount omezuje počet vrácených výsledků na základě podobnosti vektorů.
• fields určuje vektorové pole, na které se má hledat.

const vectorQuery = {
    vector: vector,
    kNearestNeighborsCount: 5,
    fields: ["DescriptionVector"],
    kind: "vector",
    exhaustive: true
};

const searchOptions = {
    top: 7,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"],
    includeTotalCount: true,
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const results = await searchClient.search("*", searchOptions);

for await (const result of results.results) {
    const doc = result.document;
    console.log(`HotelId: ${doc.HotelId}, HotelName: ${doc.HotelName}, Score: ${result.score}`);
}

Vyhledávání jednoho vektoru s filtrem

Ve službě Azure AI Vyhledávač filtry se používají na nevektorová pole v indexu. searchSingleWithFilter.js filtry na poli Tags vyfiltrují všechny hotely, které neposkytují bezplatné Wi-Fi.

const searchOptions = {
    top: 7,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"],
    includeTotalCount: true,
    filter: "Tags/any(tag: tag eq 'free wifi')", // Adding filter for "free wifi" tag
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const results = await searchClient.search("*", searchOptions);

Vyhledávání s jedním vektorem s geografickým filtrem

Můžete zadat geoprostorový filtr , který omezí výsledky na konkrétní geografickou oblast. searchSingleWithGeoFilter.js určuje geografický bod (Washington D.C., pomocí souřadnic zeměpisné délky a zeměpisné šířky) a vrátí hotely v okruhu 300 kilometrů. Vlastnost filterMode určuje, kdy se filtr spustí. V tomto případě postFilter spustí filtr po hledání vektoru.

const searchOptions = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Category", "Description", "Address/City", "Address/StateProvince"],
    facets: ["Address/StateProvince"],
    filter: "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

Hybridní vyhledávání

Hybridní vyhledávání kombinuje fulltextové a vektorové dotazy v jednom požadavku. searchHybrid.js spustí oba typy dotazů současně a potom pomocí reciproční Rank Fusion (RRF) sloučí výsledky do sjednoceného pořadí. RRF používá inverzní pořadí hodnocení z každé sady výsledků k vytvoření sloučeného pořadí. Všimněte si, že skóre hybridního vyhledávání jsou jednotně menší než skóre s jedním dotazem.

const vectorQuery = {
    vector: vector,
    kNearestNeighborsCount: 5,
    fields: ["DescriptionVector"],
    kind: "vector",
    exhaustive: true
};

const searchOptions = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"],
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

// Use search text for keyword search (hybrid search = vector + keyword)
const searchText = "historic hotel walk to restaurants and shopping";
const results = await searchClient.search(searchText, searchOptions);

Sémantické hybridní vyhledávání

searchSemanticHybrid.js ukazuje sémantické řazení, které přeřazuje výsledky na základě porozumění jazyku.

const searchOptions = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Category", "Description"],
    queryType: "semantic",
    semanticSearchOptions: {
        configurationName: "semantic-config"
    },
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const searchText = "historic hotel walk to restaurants and shopping";
const results = await searchClient.search(searchText, searchOptions);

for await (const result of results.results) {
    console.log(`Score: ${result.score}, Re-ranker Score: ${result.rerankerScore}`);
}

Porovnejte tyto výsledky s výsledky hybridního hledání z předchozího dotazu. Bez sémantického hodnocení se Sublime Palace Hotel řadí jako první, protože Reciproční Rank Fusion (RRF) kombinuje text a vektorové skóre, aby vznikl sloučený výsledek. Po sémantickém přehodnocení se Hotel Swirling Currents přesune na nejvyšší místo.

Sémantický ranker používá modely strojového porozumění k vyhodnocení, jak dobře jednotlivé výsledky odpovídají záměru dotazu. Swirling Currents Hotel v popisu zmiňuje "walking access to shopping, dining, entertainment and the city center", což se úzce shoduje s vyhledávacím dotazem "walk to restaurants and shopping". Tento sémantický zápas pro nedaleké restaurace a nakupování ho staví nad Sublime Palace Hotel, který ve svém popisu nezvýrazňuje pěší dostupnost svých možností.

Hlavní klíčové body:

• V hybridním vyhledávání můžete integrovat vektorové vyhledávání s fulltextovým vyhledáváním pomocí klíčových slov. Filtry a sémantické řazení se vztahují pouze na textový obsah, nikoli vektory.

• Skutečné výsledky obsahují více podrobností, včetně sémantických titulků a zvýraznění. Tento rychlý start upraví výsledky pro čitelnost. Pokud chcete získat úplnou strukturu odpovědi, spusťte požadavek pomocí rest.

Vyčistěte zdroje

Když pracujete ve vlastním předplatném, je vhodné dokončit projekt odebráním prostředků, které už nepotřebujete. Prostředky, které zůstaly spuštěné, vám můžou stát peníze.

Na portálu Azure vyberte Všechny prostředky nebo Zdrojové skupiny v levém podokně a vyhledejte a spravujte prostředky. Prostředky můžete odstranit jednotlivě nebo odstranit skupinu prostředků a odebrat tak všechny prostředky najednou.

V opačném případě spuštěním následujícího příkazu odstraňte index, který jste vytvořili v tomto rychlém startu.

node -r dotenv/config src/deleteIndex.js

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro Python k vytvoření, načtení a dotazování indexu vector. Klientská knihovna Python poskytuje abstrakci rozhraní REST API pro operace indexu.

V Azure AI Vyhledávač má vektorový index schéma, které definuje vektorová a nevectorová pole, konfiguraci vektorového vyhledávání algoritmů, které vytvářejí vložený prostor a nastavení definic vektorových polí, které se vyhodnocují v době dotazu. Indexy – Vytvoření nebo aktualizace (REST API) vytvoří vektorový index.

Návod

• Chcete začít hned? Stáhněte zdrojový kód na GitHub.
• Tento rychlý start vynechá krok vektorizace a poskytuje vložené vkládání. Pokud chcete integrovat vektorizaci nad vlastním obsahem, zkuste průvodce importem dat.

Požadavky

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

• Služba Azure AI Vyhledávač. Pro většinu tohoto rychlého startu můžete použít úroveň Free, ale pro větší datové soubory doporučujeme basic nebo vyšší.

• Sémantický ranker povolený ve vyhledávací službě pro volitelný sémantický hybridní dotaz.

• Python 3.8 nebo novější.

• Visual Studio Code s rozšířeními Python a Jupyter.

• 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 založený na rolích 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

   • Přispěvatel dat indexu vyhledávání

   • Č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. Na webu Azure Portal přejděte do vyhledávací služby.

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.

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-Vector-Search
   code .
   

3. Nahraďte v sample.env zástupnou hodnotu AZURE_SEARCH_ENDPOINT adresou URL, kterou jste získali v Get endpoint.

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

   mv sample.env .env
   

5. Otevřít vector-search-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. Spusťte buňku Install packages and set variables, abyste nainstalovali požadované balíčky a načetli proměnné prostředí.

2. Spuštěním zbývajících buněk postupně vytvořte vektorový index, nahrajte dokumenty a spusťte různé typy vektorových dotazů.

Výstup

Každá buňka kódu vytiskne svůj výstup do poznámkového bloku. Následující příklad je výstupem Single vector search, který zobrazuje výsledky vektorového hledání seřazené podle skóre podobnosti.

Total results: 7
- HotelId: 48, HotelName: Nordick's Valley Motel, Category: Boutique
- HotelId: 13, HotelName: Luxury Lion Resort, Category: Luxury
- HotelId: 4, HotelName: Sublime Palace Hotel, Category: Boutique
- HotelId: 49, HotelName: Swirling Currents Hotel, Category: Suite
- HotelId: 2, HotelName: Old Century Hotel, Category: Boutique

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

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

1. Vytvoření indexu vektoru
2. Nahrání dokumentů do indexu
3. Dotazování indexu

Vytvoření indexu vektoru

Než přidáte obsah do Azure AI Vyhledávač, musíte vytvořit index, který definuje, jak se obsah ukládá a strukturuje.

Schéma indexu je uspořádané kolem obsahu hotelu. Ukázková data se skládají z vektorových a nevectorových popisů fiktivních hotelů. Buňka Create an index v poznámkovém bloku vytvoří schéma indexu včetně vektorového pole DescriptionVector.

fields = [
    SimpleField(name="HotelId", type=SearchFieldDataType.String, key=True, filterable=True),
    SearchableField(name="HotelName", type=SearchFieldDataType.String, sortable=True),
    SearchableField(name="Description", type=SearchFieldDataType.String),
    SearchField(
        name="DescriptionVector",
        type=SearchFieldDataType.Collection(SearchFieldDataType.Single),
        searchable=True,
        vector_search_dimensions=1536,
        vector_search_profile_name="my-vector-profile"
    ),
    SearchableField(name="Category", type=SearchFieldDataType.String, sortable=True, filterable=True, facetable=True),
    SearchField(name="Tags", type=SearchFieldDataType.Collection(SearchFieldDataType.String), searchable=True, filterable=True, facetable=True),
    # Additional fields omitted for brevity
]

Hlavní klíčové body:

• Index definujete vytvořením seznamu polí. Každé pole se vytvoří pomocí pomocné metody, která definuje typ pole a jeho nastavení.

• Tento konkrétní index podporuje více možností vyhledávání:

  • Fulltextové vyhledávání (SearchableField)

  • Vektorové vyhledávání (DescriptionVector s vector_search_profile_name)

  • Sémantické řazení (SemanticConfiguration)

  • Fasetové vyhledávání (pole označená facetable)

  • Geografické prostorové vyhledávání (Location pole s SearchFieldDataType.GeographyPoint)

  • Filtrování a řazení (pole označená filterable a sortable)

• Vlastnost vector_search_dimensions se musí shodovat s výstupní velikostí modelu vkládání. V tomto rychlém startu se k modelu text-embedding-ada-002 používá 1 536 dimenzí.

• Konfigurace VectorSearch definuje algoritmus přibližného nejbližšího souseda (ANN). Mezi podporované algoritmy patří Hierarchický Navigovatelný Malý Svět (HNSW) a úplný K-Nearest Neighbor (KNN). Další informace najdete v tématu Relevance při hledání vektorů.

Nahrání dokumentů do indexu

Nově vytvořené indexy jsou prázdné. Pokud chcete naplnit index a nastavit, aby byl prohledávatelný, musíte nahrát dokumenty JSON, které odpovídají schématu indexu.

V Azure AI Vyhledávač slouží dokumenty jako vstupy pro indexování a výstupy pro dotazy. Pro zjednodušení tento rychlý start poskytuje ukázkové hotelové dokumenty s předem určenými vektory. V produkčních scénářích se obsah často načítá z připojených zdrojů dat a transformuje se do FORMÁTU JSON pomocí indexerů.

Buňky Create documents payload a Upload the documents načítají dokumenty do indexu.

documents = [
    # List of hotel documents with embedded 1536-dimension vectors
    # Each document contains: HotelId, HotelName, Description, DescriptionVector,
    # Category, Tags, ParkingIncluded, LastRenovationDate, Rating, Address, Location
]

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

result = search_client.upload_documents(documents=documents)
for r in result:
    print(f"Key: {r.key}, Succeeded: {r.succeeded}, ErrorMessage: {r.error_message}")

Kód komunikuje s konkrétním indexem vyhledávání hostovaným ve službě Azure AI Vyhledávač prostřednictvím SearchClient, což je hlavní objekt poskytovaný balíčkem azure-search-documents. Poskytuje SearchClient přístup k operacím indexu, například:

• Příjem dat: upload_documents(), merge_documents()delete_documents()

• Vyhledávací operace: search(), autocomplete()suggest()

Dotazování indexu

Dotazy v poznámkovém bloku ukazují různé způsoby hledání. Ukázkové vektorové dotazy jsou založené na dvou řetězcích:

• Textový řetězec pro fulltextové vyhledávání: "historic hotel walk to restaurants and shopping"

• Řetězec vektorového dotazu: "quintessential lodging near running trails, eateries, retail" (vektorizovaný na matematickou reprezentaci)

Řetězec vektorového dotazu je sémanticky podobný fulltextového hledanému řetězci, ale obsahuje výrazy, které v indexu neexistují. Hledání řetězce vektorového dotazu pouze s klíčovým slovem vrátí nulové výsledky. Hledání vektorů ale najde relevantní shody na základě významu, nikoli přesných klíčových slov.

Následující příklady začínají základním vektorovým dotazem a postupně přidávají filtry, vyhledávání klíčových slov a sémantické řazení.

Jednoúčelové vyhledávání vektorů

Buňka Single vector search ukazuje základní scénář, ve kterém chcete najít popisy dokumentu, které úzce odpovídají řetězci vektorového dotazu. VectorizedQuery nakonfiguruje vektorové vyhledávání:

• k_nearest_neighbors omezuje počet vrácených výsledků na základě podobnosti vektorů.
• fields určuje vektorové pole, na které se má hledat.

vector_query = VectorizedQuery(
    vector=vector,
    k_nearest_neighbors=5,
    fields="DescriptionVector",
    kind="vector",
    exhaustive=True
)

results = search_client.search(
    vector_queries=[vector_query],
    select=["HotelId", "HotelName", "Description", "Category", "Tags"],
    top=5,
    include_total_count=True
)

Vyhledávání jednoho vektoru s filtrem

Ve službě Azure AI Vyhledávač filtry se používají na nevektorová pole v indexu. Buňka Single vector search with filter vyfiltruje Tags pole a vyfiltruje všechny hotely, které neposkytují bezplatné Wi-Fi.

# vector_query omitted for brevity

results = search_client.search(
    vector_queries=[vector_query],
    filter="Tags/any(tag: tag eq 'free wifi')",
    select=["HotelId", "HotelName", "Description", "Category", "Tags"],
    top=7,
    include_total_count=True
)

Vyhledávání s jedním vektorem s geografickým filtrem

Můžete zadat geoprostorový filtr , který omezí výsledky na konkrétní geografickou oblast. Buňka Single vector search with geo filter určuje geografický bod (Washington D.C., pomocí souřadnic zeměpisné délky a zeměpisné šířky) a vrátí hotely v okruhu 300 kilometrů. Parametr vector_filter_mode určuje, kdy se filtr spustí. V tomto případě postFilter spustí filtr po hledání vektoru.

# vector_query omitted for brevity

results = search_client.search(
    include_total_count=True,
    top=5,
    select=[
        "HotelId", "HotelName", "Category", "Description", "Address/City", "Address/StateProvince"
    ],
    facets=["Address/StateProvince"],
    filter="geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
    vector_filter_mode="postFilter",
    vector_queries=[vector_query]
)

Hybridní vyhledávání

Hybridní vyhledávání kombinuje fulltextové a vektorové dotazy v jednom požadavku. Buňka Hybrid search spouští oba typy dotazů současně a potom pomocí reciproční Rank Fusion (RRF) sloučí výsledky do sjednoceného pořadí. RRF používá inverzní pořadí hodnocení z každé sady výsledků k vytvoření sloučeného pořadí. Všimněte si, že skóre hybridního vyhledávání jsou jednotně menší než skóre s jedním dotazem.

# vector_query omitted for brevity

results = search_client.search(
    search_text="historic hotel walk to restaurants and shopping",
    vector_queries=[vector_query],
    select=["HotelId", "HotelName", "Description", "Category", "Tags"],
    top=5,
    include_total_count=True
)

Sémantické hybridní vyhledávání

Buňka Semantic hybrid search ukazuje sémantické řazení, které přeřazuje výsledky na základě porozumění jazyku.

# vector_query omitted for brevity

results = search_client.search(
    search_text="historic hotel walk to restaurants and shopping",
    vector_queries=[vector_query],
    select=["HotelId", "HotelName", "Category", "Description"],
    query_type="semantic",
    semantic_configuration_name="my-semantic-config",
    top=5,
    include_total_count=True
)

Porovnejte tyto výsledky s výsledky hybridního hledání z předchozího dotazu. Bez sémantického hodnocení se Sublime Palace Hotel řadí jako první, protože Reciproční Rank Fusion (RRF) kombinuje text a vektorové skóre, aby vznikl sloučený výsledek. Po sémantickém přehodnocení se Hotel Swirling Currents přesune na nejvyšší místo.

Sémantický ranker používá modely strojového porozumění k vyhodnocení, jak dobře jednotlivé výsledky odpovídají záměru dotazu. Swirling Currents Hotel v popisu zmiňuje "walking access to shopping, dining, entertainment and the city center", což se úzce shoduje s vyhledávacím dotazem "walk to restaurants and shopping". Tento sémantický zápas pro nedaleké restaurace a nakupování ho staví nad Sublime Palace Hotel, který ve svém popisu nezvýrazňuje pěší dostupnost svých možností.

Hlavní klíčové body:

• V hybridním vyhledávání můžete integrovat vektorové vyhledávání s fulltextovým vyhledáváním pomocí klíčových slov. Filtry a sémantické řazení se vztahují pouze na textový obsah, nikoli vektory.

• Skutečné výsledky obsahují více podrobností, včetně sémantických titulků a zvýraznění. Tento rychlý start upraví výsledky pro čitelnost. Pokud chcete získat úplnou strukturu odpovědi, spusťte požadavek pomocí rest.

Vyčistěte zdroje

Když pracujete ve vlastním předplatném, je vhodné dokončit projekt odebráním prostředků, které už nepotřebujete. Prostředky, které zůstaly spuštěné, vám můžou stát peníze.

Na portálu Azure vyberte Všechny prostředky nebo Zdrojové skupiny v levém podokně a vyhledejte a spravujte prostředky. Prostředky můžete odstranit jednotlivě nebo odstranit skupinu prostředků a odebrat tak všechny prostředky najednou.

Jinak můžete buňku Clean up kódu spustit a odstranit index, který jste vytvořili v tomto rychlém startu.

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro JavaScript (kompatibilní s TypeScriptem) k vytvoření, načtení a dotazování indexu vector. Klientská knihovna JavaScriptu poskytuje abstrakci rozhraní REST API pro operace indexu.

V Azure AI Vyhledávač má vektorový index schéma, které definuje vektorová a nevectorová pole, konfiguraci vektorového vyhledávání algoritmů, které vytvářejí vložený prostor a nastavení definic vektorových polí, které se vyhodnocují v době dotazu. Indexy – Vytvoření nebo aktualizace (REST API) vytvoří vektorový index.

Návod

• Chcete začít hned? Stáhněte zdrojový kód na GitHub.
• Tento rychlý start vynechá krok vektorizace a poskytuje vložené vkládání. Pokud chcete integrovat vektorizaci nad vlastním obsahem, zkuste průvodce importem dat.

Požadavky

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

• Služba Azure AI Vyhledávač. Pro většinu tohoto rychlého startu můžete použít úroveň Free, ale pro větší datové soubory doporučujeme basic nebo vyšší.

• Sémantický ranker povolený ve vyhledávací službě pro volitelný sémantický hybridní dotaz.

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

• Kompilujte TypeScript do JavaScriptu pomocí TypeScriptu.

• 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 založený na rolích 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

   • Přispěvatel dat indexu vyhledávání

   • Č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. Na webu Azure Portal přejděte do vyhledávací služby.

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.

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-vector-ts
   

3. Nahraďte v sample.env zástupnou hodnotu AZURE_SEARCH_ENDPOINT adresou URL, kterou jste získali v Get endpoint.

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. Vytvoření vektorového indexu

   node -r dotenv/config dist/createIndex.js
   

2. Načtěte dokumenty, které obsahují předem vypočítané embeddingy.

   node -r dotenv/config dist/uploadDocuments.js
   

3. Spusťte vektorový vyhledávací dotaz.

   node -r dotenv/config dist/searchSingle.js
   

4. (Volitelné) Spusťte další varianty dotazů.

   node -r dotenv/config dist/searchSingleWithFilter.js
   node -r dotenv/config dist/searchSingleWithFilterGeo.js
   node -r dotenv/config dist/searchHybrid.js
   node -r dotenv/config dist/searchSemanticHybrid.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

Výstup createIndex.ts zobrazuje název indexu a potvrzení.

Using Azure Search endpoint: https://<search-service-name>.search.windows.net
Using index name: hotels-vector-quickstart
Creating index...
hotels-vector-quickstart created

Výstup uploadDocuments.ts ukazuje stav úspěchu pro každý indexovaný dokument.

Uploading documents...
Key: 1, Succeeded: true, ErrorMessage: none
Key: 2, Succeeded: true, ErrorMessage: none
Key: 3, Succeeded: true, ErrorMessage: none
Key: 4, Succeeded: true, ErrorMessage: none
Key: 48, Succeeded: true, ErrorMessage: none
Key: 49, Succeeded: true, ErrorMessage: none
Key: 13, Succeeded: true, ErrorMessage: none
All documents indexed successfully.

Výstup ukazuje výsledky vektorového searchSingle.ts hledání seřazené podle skóre podobnosti.

Single Vector search found 5
- HotelId: 48, HotelName: Nordick's Valley Motel, Tags: ["continental breakfast","air conditioning","free wifi"], Score 0.6605852
- HotelId: 13, HotelName: Luxury Lion Resort, Tags: ["bar","concierge","restaurant"], Score 0.6333684
- HotelId: 4, HotelName: Sublime Palace Hotel, Tags: ["concierge","view","air conditioning"], Score 0.605672
- HotelId: 49, HotelName: Swirling Currents Hotel, Tags: ["air conditioning","laundry service","24-hour front desk service"], Score 0.6026341
- HotelId: 2, HotelName: Old Century Hotel, Tags: ["pool","free wifi","air conditioning","concierge"], Score 0.57902366

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

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

1. Vytvoření indexu vektoru
2. Nahrání dokumentů do indexu
3. Dotazování indexu

Vytvoření indexu vektoru

Než přidáte obsah do Azure AI Vyhledávač, musíte vytvořit index, který definuje, jak se obsah ukládá a strukturuje.

Schéma indexu je uspořádané kolem obsahu hotelu. Ukázková data se skládají z vektorových a nevectorových popisů fiktivních hotelů. Následující kód v createIndex.ts definuje schéma indexu, včetně vektorového pole DescriptionVector.

const searchFields: SearchField[] = [
    { name: "HotelId", type: "Edm.String", key: true, sortable: true, filterable: true, facetable: true },
    { name: "HotelName", type: "Edm.String", searchable: true, filterable: true },
    { name: "Description", type: "Edm.String", searchable: true },
    {
        name: "DescriptionVector",
        type: "Collection(Edm.Single)",
        searchable: true,
        vectorSearchDimensions: 1536,
        vectorSearchProfileName: "vector-profile"
    },
    { name: "Category", type: "Edm.String", filterable: true, facetable: true },
    { name: "Tags", type: "Collection(Edm.String)", filterable: true },
    // Additional fields: ParkingIncluded, LastRenovationDate, Rating, Address, Location
];

const vectorSearch: VectorSearch = {
    profiles: [
        {
            name: "vector-profile",
            algorithmConfigurationName: "vector-search-algorithm"
        }
    ],
    algorithms: [
        {
            name: "vector-search-algorithm",
            kind: "hnsw",
            parameters: { m: 4, efConstruction: 400, efSearch: 1000, metric: "cosine" }
        }
    ]
};

const semanticSearch: SemanticSearch = {
    configurations: [
        {
            name: "semantic-config",
            prioritizedFields: {
                contentFields: [{ name: "Description" }],
                keywordsFields: [{ name: "Category" }],
                titleField: { name: "HotelName" }
            }
        }
    ]
};

const searchIndex: SearchIndex = {
    name: indexName,
    fields: searchFields,
    vectorSearch: vectorSearch,
    semanticSearch: semanticSearch,
    suggesters: [{ name: "sg", searchMode: "analyzingInfixMatching", sourceFields: ["HotelName"] }]
};

const result = await indexClient.createOrUpdateIndex(searchIndex);

Hlavní klíčové body:

• Index definujete vytvořením seznamu polí.

• Tento konkrétní index podporuje více možností vyhledávání:

  • Fulltextové vyhledávání (searchable: true)

  • Vektorové vyhledávání (DescriptionVector s vectorSearchProfileName)

  • Sémantické řazení (semanticSearch)

  • Fasetové vyhledávání (pole označená facetable)

  • Geografické prostorové vyhledávání (Location pole s Edm.GeographyPoint)

  • Filtrování a řazení (pole označená filterable a sortable)

• Vlastnost vectorSearchDimensions se musí shodovat s výstupní velikostí modelu vkládání. V tomto rychlém startu se k modelu text-embedding-ada-002 používá 1 536 dimenzí.

• Konfigurace vectorSearch definuje algoritmus přibližného nejbližšího souseda (ANN). Mezi podporované algoritmy patří Hierarchický Navigovatelný Malý Svět (HNSW) a úplný K-Nearest Neighbor (KNN). Další informace najdete v tématu Relevance při hledání vektorů.

Nahrání dokumentů do indexu

Nově vytvořené indexy jsou prázdné. Pokud chcete naplnit index a nastavit, aby byl prohledávatelný, musíte nahrát dokumenty JSON, které odpovídají schématu indexu.

V Azure AI Vyhledávač slouží dokumenty jako vstupy pro indexování a výstupy pro dotazy. Pro zjednodušení tento rychlý start poskytuje ukázkové hotelové dokumenty s předem určenými vektory. V produkčních scénářích se obsah často načítá z připojených zdrojů dat a transformuje se do FORMÁTU JSON pomocí indexerů.

Následující kód přenese dokumenty do vaší vyhledávací služby.

const DOCUMENTS = [
    // Array of hotel documents with embedded 1536-dimension vectors
    // Each document contains: HotelId, HotelName, Description, DescriptionVector,
    // Category, Tags, ParkingIncluded, LastRenovationDate, Rating, Address, Location
];

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

const result = await searchClient.uploadDocuments(DOCUMENTS);
for (const r of result.results) {
    console.log(`Key: ${r.key}, Succeeded: ${r.succeeded}`);
}

Kód komunikuje s konkrétním indexem vyhledávání hostovaným ve službě Azure AI Vyhledávač prostřednictvím SearchClient, což je hlavní objekt poskytovaný balíčkem @azure/search-documents. Poskytuje SearchClient přístup k operacím indexu, například:

• Příjem dat: uploadDocuments, mergeDocumentsdeleteDocuments

• Vyhledávací operace: search, autocompletesuggest

Dotazování indexu

Dotazy ve vyhledávacích souborech ukazují různé vzory hledání. Ukázkové vektorové dotazy jsou založené na dvou řetězcích:

• Textový řetězec pro fulltextové vyhledávání: "historic hotel walk to restaurants and shopping"

• Řetězec vektorového dotazu: "quintessential lodging near running trails, eateries, retail" (vektorizovaný na matematickou reprezentaci)

Řetězec vektorového dotazu je sémanticky podobný fulltextového hledanému řetězci, ale obsahuje výrazy, které v indexu neexistují. Hledání řetězce vektorového dotazu pouze s klíčovým slovem vrátí nulové výsledky. Hledání vektorů ale najde relevantní shody na základě významu, nikoli přesných klíčových slov.

Následující příklady začínají základním vektorovým dotazem a postupně přidávají filtry, vyhledávání klíčových slov a sémantické řazení.

Jednoúčelové vyhledávání vektorů

searchSingle.ts demonstruje základní scénář, ve kterém chcete najít popisy dokumentu, které úzce odpovídají řetězci vektorového dotazu. Objekt VectorQuery nakonfiguruje vektorové vyhledávání:

• kNearestNeighborsCount omezuje počet vrácených výsledků na základě podobnosti vektorů.
• fields určuje vektorové pole, na které se má hledat.

const vectorQuery: VectorQuery<HotelDocument> = {
    vector: vector,
    kNearestNeighborsCount: 5,
    fields: ["DescriptionVector"],
    kind: "vector",
    exhaustive: true
};

const searchOptions: SearchOptions<HotelDocument> = {
    top: 7,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"] as const,
    includeTotalCount: true,
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const results: SearchDocumentsResult<HotelDocument> = await searchClient.search("*", searchOptions);

for await (const result of results.results) {
    const doc = result.document;
    console.log(`HotelId: ${doc.HotelId}, HotelName: ${doc.HotelName}, Score: ${result.score}`);
}

Vyhledávání jednoho vektoru s filtrem

Ve službě Azure AI Vyhledávač filtry se používají na nevektorová pole v indexu. searchSingleWithFilter.ts filtry na poli Tags vyfiltrují všechny hotely, které neposkytují bezplatné Wi-Fi.

const searchOptions: SearchOptions<HotelDocument> = {
    top: 7,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"] as const,
    includeTotalCount: true,
    filter: "Tags/any(tag: tag eq 'free wifi')", // Adding filter for "free wifi" tag
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const results: SearchDocumentsResult<HotelDocument> = await searchClient.search("*", searchOptions);

Vyhledávání s jedním vektorem s geografickým filtrem

Můžete zadat geoprostorový filtr , který omezí výsledky na konkrétní geografickou oblast. searchSingleWithGeoFilter.ts určuje geografický bod (Washington D.C., pomocí souřadnic zeměpisné délky a zeměpisné šířky) a vrátí hotely v okruhu 300 kilometrů. Vlastnost filterMode určuje, kdy se filtr spustí. V tomto případě postFilter spustí filtr po hledání vektoru.

const searchOptions: SearchOptions<HotelDocument> = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Category", "Description", "Address/City", "Address/StateProvince"] as const,
    facets: ["Address/StateProvince"],
    filter: "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

Hybridní vyhledávání

Hybridní vyhledávání kombinuje fulltextové a vektorové dotazy v jednom požadavku. searchHybrid.ts spustí oba typy dotazů současně a potom pomocí reciproční Rank Fusion (RRF) sloučí výsledky do sjednoceného pořadí. RRF používá inverzní pořadí hodnocení z každé sady výsledků k vytvoření sloučeného pořadí. Všimněte si, že skóre hybridního vyhledávání jsou jednotně menší než skóre s jedním dotazem.

const vectorQuery: VectorQuery<HotelDocument> = {
    vector: vector,
    kNearestNeighborsCount: 5,
    fields: ["DescriptionVector"],
    kind: "vector",
    exhaustive: true
};

const searchOptions: SearchOptions<HotelDocument> = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"] as const,
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

// Use search text for keyword search (hybrid search = vector + keyword)
const searchText = "historic hotel walk to restaurants and shopping";
const results: SearchDocumentsResult<HotelDocument> = await searchClient.search(searchText, searchOptions);

Sémantické hybridní vyhledávání

searchSemanticHybrid.ts ukazuje sémantické řazení, které přeřazuje výsledky na základě porozumění jazyku.

const searchOptions: SearchOptions<HotelDocument> = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Category", "Description"] as const,
    queryType: "semantic" as const,
    semanticSearchOptions: {
        configurationName: "semantic-config"
    },
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const searchText = "historic hotel walk to restaurants and shopping";
const results: SearchDocumentsResult<HotelDocument> = await searchClient.search(searchText, searchOptions);

for await (const result of results.results) {
    console.log(`Score: ${result.score}, Re-ranker Score: ${result.rerankerScore}`);
}

Porovnejte tyto výsledky s výsledky hybridního hledání z předchozího dotazu. Bez sémantického hodnocení se Sublime Palace Hotel řadí jako první, protože Reciproční Rank Fusion (RRF) kombinuje text a vektorové skóre, aby vznikl sloučený výsledek. Po sémantickém přehodnocení se Hotel Swirling Currents přesune na nejvyšší místo.

Sémantický ranker používá modely strojového porozumění k vyhodnocení, jak dobře jednotlivé výsledky odpovídají záměru dotazu. Swirling Currents Hotel v popisu zmiňuje "walking access to shopping, dining, entertainment and the city center", což se úzce shoduje s vyhledávacím dotazem "walk to restaurants and shopping". Tento sémantický zápas pro nedaleké restaurace a nakupování ho staví nad Sublime Palace Hotel, který ve svém popisu nezvýrazňuje pěší dostupnost svých možností.

Hlavní klíčové body:

• V hybridním vyhledávání můžete integrovat vektorové vyhledávání s fulltextovým vyhledáváním pomocí klíčových slov. Filtry a sémantické řazení se vztahují pouze na textový obsah, nikoli vektory.

• Skutečné výsledky obsahují více podrobností, včetně sémantických titulků a zvýraznění. Tento rychlý start upraví výsledky pro čitelnost. Pokud chcete získat úplnou strukturu odpovědi, spusťte požadavek pomocí rest.

Vyčistěte zdroje

Když pracujete ve vlastním předplatném, je vhodné dokončit projekt odebráním prostředků, které už nepotřebujete. Prostředky, které zůstaly spuštěné, vám můžou stát peníze.

Na portálu Azure vyberte Všechny prostředky nebo Zdrojové skupiny v levém podokně a vyhledejte a spravujte prostředky. Prostředky můžete odstranit jednotlivě nebo odstranit skupinu prostředků a odebrat tak všechny prostředky najednou.

V opačném případě spuštěním následujícího příkazu odstraňte index, který jste vytvořili v tomto rychlém startu.

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

V tomto rychlém startu použijete rozhraní REST API Azure AI Vyhledávač k vytvoření, načtení a dotazování indexu vector.

V Azure AI Vyhledávač má vektorový index schéma, které definuje vektorová a nevectorová pole, konfiguraci vektorového vyhledávání algoritmů, které vytvářejí vložený prostor a nastavení definic vektorových polí, které se vyhodnocují v době dotazu. Indexy – Vytvoření nebo aktualizace (REST API) vytvoří vektorový index.

Návod

• Chcete začít hned? Stáhněte zdrojový kód na GitHub.
• Tento rychlý start vynechá krok vektorizace a poskytuje vložené vkládání. Pokud chcete integrovat vektorizaci nad vlastním obsahem, zkuste průvodce importem dat.

Požadavky

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

• Služba Azure AI Vyhledávač. Pro většinu tohoto rychlého startu můžete použít úroveň Free, ale pro větší datové soubory doporučujeme basic nebo vyšší.

• Sémantický ranker povolený ve vyhledávací službě pro volitelný sémantický hybridní dotaz.

• 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 založený na rolích 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

   • Přispěvatel dat indexu vyhledávání

   • Č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. Na webu Azure Portal přejděte do vyhledávací služby.

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.

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-vectors
   code .
   

3. Nahraďte v az-search-quickstart-vectors.rest zástupnou hodnotu @baseUrl adresou URL, kterou jste získali v Get endpoint.

4. 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
   

5. 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 -o tsv
   

6. Nahraďte zástupnou hodnotu @token tokenem z předchozího kroku.

Spuštění kódu

1. V části ### List existing indexes by nameVyberte Odeslat žádost a ověřte připojení.

   V sousedním podokně by se měla zobrazit odpověď. Pokud máte existující indexy, jsou uvedené. V opačném případě je seznam prázdný. Pokud je kód HTTP 200 OK, můžete pokračovat.

2. Odeslání zbývajících požadavků postupně za účelem vytvoření vektorového indexu, nahrání dokumentů a spuštění různých typů vektorových dotazů.

Výstup

Každý požadavek dotazu vrátí výsledky JSON. Následující příklad je výstupem ### Run a single vector query požadavku, který zobrazuje výsledky vektorového hledání seřazené podle skóre podobnosti.

{
  "@odata.count": 5,
  "value": [
    {
      "@search.score": 0.6605852,
      "HotelId": "48",
      "HotelName": "Nordick's Valley Motel",
      "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer. Hiking? Wine Tasting? Exploring the caverns? It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.",
      "Category": "Boutique",
      "Tags": [
        "continental breakfast",
        "air conditioning",
        "free wifi"
      ]
    },
    {
      "@search.score": 0.6333684,
      "HotelId": "13",
      "HotelName": "Luxury Lion Resort",
      "Description": "Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium and transportation hubs, we feature the best in convenience and comfort.",
      "Category": "Luxury",
      "Tags": [
        "bar",
        "concierge",
        "restaurant"
      ]
    },
    {
      "@search.score": 0.605672,
      "HotelId": "4",
      "HotelName": "Sublime Palace Hotel",
      "Description": "Sublime Palace 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.",
      "Category": "Boutique",
      "Tags": [
        "concierge",
        "view",
        "air conditioning"
      ]
    },
    {
      "@search.score": 0.6026341,
      "HotelId": "49",
      "HotelName": "Swirling Currents Hotel",
      "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs.",
      "Category": "Suite",
      "Tags": [
        "air conditioning",
        "laundry service",
        "24-hour front desk service"
      ]
    },
    {
      "@search.score": 0.57902366,
      "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.",
      "Category": "Boutique",
      "Tags": [
        "pool",
        "free wifi",
        "air conditioning",
        "concierge"
      ]
    }
  ]
}

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

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

1. Vytvoření indexu vektoru
2. Nahrání dokumentů do indexu
3. Dotazování indexu

Vytvoření indexu vektoru

Než přidáte obsah do Azure AI Vyhledávač, musíte vytvořit index, který definuje, jak se obsah ukládá a strukturuje. Tento rychlý start volá Indexy: vytvoření (REST API) k vytvoření vektorového indexu pojmenovaného hotels-vector-quickstart a jeho fyzických datových struktur ve vyhledávací službě.

Schéma indexu je uspořádané kolem obsahu hotelu. Ukázková data se skládají z vektorových a nevectorových popisů fiktivních hotelů. Následující výňatek ukazuje klíčovou ### Create a new index strukturu požadavku.

PUT {{baseUrl}}/indexes/hotels-vector-quickstart?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "name": "hotels-vector-quickstart",
    "fields": [
        { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
        { "name": "HotelName", "type": "Edm.String", "searchable": true },
        { "name": "Description", "type": "Edm.String", "searchable": true },
        {
            "name": "DescriptionVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "dimensions": 1536,
            "vectorSearchProfile": "my-vector-profile"
        },
        { "name": "Category", "type": "Edm.String", "filterable": true, "facetable": true },
        { "name": "Tags", "type": "Collection(Edm.String)", "filterable": true, "facetable": true }
        // Additional fields omitted for brevity
    ],
    "vectorSearch": {
        "algorithms": [
            { "name": "hnsw-vector-config", "kind": "hnsw" }
        ],
        "profiles": [
            { "name": "my-vector-profile", "algorithm": "hnsw-vector-config" }
        ]
    },
    "semantic": {
        "configurations": [
            {
                "name": "semantic-config",
                "prioritizedFields": {
                    "titleField": { "fieldName": "HotelName" },
                    "prioritizedContentFields": [{ "fieldName": "Description" }]
                }
            }
        ]
    }
}

Hlavní klíčové body:

• Tento konkrétní index podporuje více možností vyhledávání:

  • Fulltextové vyhledávání (pole, která mají searchable nastavenou hodnotu true)

  • Vektorové vyhledávání (DescriptionVector s vectorSearchProfile)

  • Sémantické řazení (semantic konfigurace)

  • Fasetové vyhledávání (pole s facetable nastavenou na true hodnotou)

  • Geografické prostorové vyhledávání (Location pole s Edm.GeographyPoint)

  • Filtrování a řazení (pole s filterable nastaveným na sortable na true)

• Vlastnost dimensions se musí shodovat s výstupní velikostí modelu vkládání. V tomto rychlém startu se k modelu text-embedding-ada-002 používá 1 536 dimenzí.

• Tato vectorSearch část definuje algoritmus Přibližný nejbližší soused (ANN). Mezi podporované algoritmy patří Hierarchický Navigovatelný Malý Svět (HNSW) a úplný K-Nearest Neighbor (KNN). Další informace najdete v tématu Relevance při hledání vektorů.

Nahrání dokumentů do indexu

Nově vytvořené indexy jsou prázdné. Pokud chcete naplnit index a nastavit, aby byl prohledávatelný, musíte nahrát dokumenty JSON, které odpovídají schématu indexu.

V Azure AI Vyhledávač slouží dokumenty jako vstupy pro indexování a výstupy pro dotazy. Pro zjednodušení tento rychlý začátek poskytuje ukázkové hotelové dokumenty jako vložený JSON. V produkčních scénářích se ale obsah často načítá z připojených zdrojů dat a transformuje se do FORMÁTU JSON pomocí indexerů.

Tento rychlý start volá dokumenty – index (REST API) pro přidání ukázkových hotelových dokumentů do indexu. Následující výňatek ukazuje strukturu ### Upload 7 documents požadavku.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/index?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "value": [
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "HotelName": "Stay-Kay City Hotel",
            "Description": "This classic hotel is ideally located on the main commercial artery of the city...",
            "DescriptionVector": [-0.0347, 0.0289, ... ],  // 1536 floats
            "Category": "Boutique",
            "Tags": ["view", "air conditioning", "concierge"],
            "ParkingIncluded": false,
            "Rating": 3.60,
            "Address": { "City": "New York", "StateProvince": "NY" },
            "Location": { "type": "Point", "coordinates": [-73.975403, 40.760586] }
        }
        // Additional documents omitted for brevity
    ]
}

Hlavní klíčové body:

• Každý dokument v value poli představuje hotel a obsahuje pole, která odpovídají schématu indexu. Parametr @search.action určuje operaci, která se má provést pro každý dokument. Tento rychlý start používá mergeOrUpload, který přidá dokument, pokud neexistuje nebo aktualizuje dokument, pokud existuje.

• Dokumenty v datové části se skládají z polí definovaných ve schématu indexu.

Dotazování indexu

Dotazy v ukázkovém souboru ukazují různé vzory hledání. Ukázkové vektorové dotazy jsou založené na dvou řetězcích:

• Textový řetězec pro fulltextové vyhledávání: "historic hotel walk to restaurants and shopping"

• Řetězec vektorového dotazu: "quintessential lodging near running trails, eateries, retail" (vektorizovaný na matematickou reprezentaci)

Řetězec vektorového dotazu je sémanticky podobný fulltextového hledanému řetězci, ale obsahuje výrazy, které v indexu neexistují. Hledání řetězce vektorového dotazu pouze s klíčovým slovem vrátí nulové výsledky. Hledání vektorů ale najde relevantní shody na základě významu, nikoli přesných klíčových slov.

Následující příklady začínají základním vektorovým dotazem a postupně přidávají filtry, vyhledávání klíčových slov a sémantické řazení.

Jednoúčelové vyhledávání vektorů

Požadavek ### Run a single vector query ukazuje základní scénář, ve kterém chcete najít popisy dokumentu, které úzce odpovídají řetězci vektorového dotazu. Pole vectorQueries konfiguruje vektorové vyhledávání:

• k omezuje počet vrácených výsledků na základě podobnosti vektorů.
• fields určuje vektorové pole, na které se má hledat.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "select": "HotelId, HotelName, Description, Category, Tags",
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector of "quintessential lodging near running trails, eateries, retail"
            "k": 5,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

Vyhledávání jednoho vektoru s filtrem

Ve službě Azure AI Vyhledávač filtry se používají na nevektorová pole v indexu. Požadavek ### Run a vector query with a filter v poli Tags vyfiltruje všechny hotely, které neposkytují bezplatné Wi-Fi.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "select": "HotelId, HotelName, Description, Category, Tags",
    "filter": "Tags/any(tag: tag eq 'free wifi')",
    "vectorFilterMode": "postFilter",
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

Vyhledávání s jedním vektorem s geografickým filtrem

Můžete zadat geoprostorový filtr , který omezí výsledky na konkrétní geografickou oblast. Požadavek ### Run a vector query with a geo filter určuje geografický bod (Washington D.C., pomocí souřadnic zeměpisné délky a zeměpisné šířky) a vrátí hotely v okruhu 300 kilometrů. Parametr vectorFilterMode určuje, kdy se filtr spustí. V tomto případě postFilter spustí filtr po hledání vektoru.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "select": "HotelId, HotelName, Address/City, Address/StateProvince, Description",
    "filter": "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
    "vectorFilterMode": "postFilter",
    "top": 5,
    "facets": [ "Address/StateProvince"],
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector
            "k": 5,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

Hybridní vyhledávání

Hybridní vyhledávání kombinuje fulltextové a vektorové dotazy v jednom požadavku. Požadavek ### Run a hybrid query spustí oba typy dotazů současně a potom pomocí reciproční Rank Fusion (RRF) sloučí výsledky do sjednoceného pořadí. RRF používá inverzní pořadí hodnocení z každé sady výsledků k vytvoření sloučeného pořadí. Všimněte si, že skóre hybridního vyhledávání jsou jednotně menší než skóre s jedním dotazem.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelId, HotelName, Category, Tags, Description",
    "top": 5,
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector
            "k": 5,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

Sémantické hybridní vyhledávání

Požadavek ### Run a hybrid query with semantic reranking ukazuje sémantické řazení, které přeřazuje výsledky na základě porozumění jazyku.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelId, HotelName, Category, Description",
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "top": 5,
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

Porovnejte tyto výsledky s výsledky hybridního hledání z předchozího dotazu. Bez sémantického hodnocení se Sublime Palace Hotel řadí jako první, protože Reciproční Rank Fusion (RRF) kombinuje text a vektorové skóre, aby vznikl sloučený výsledek. Po sémantickém přehodnocení se Hotel Swirling Currents přesune na nejvyšší místo.

Sémantický ranker používá modely strojového porozumění k vyhodnocení, jak dobře jednotlivé výsledky odpovídají záměru dotazu. Swirling Currents Hotel v popisu zmiňuje "walking access to shopping, dining, entertainment and the city center", což se úzce shoduje s vyhledávacím dotazem "walk to restaurants and shopping". Tento sémantický zápas pro nedaleké restaurace a nakupování ho staví nad Sublime Palace Hotel, který ve svém popisu nezvýrazňuje pěší dostupnost svých možností.

Hlavní klíčové body:

• V hybridním vyhledávání můžete integrovat vektorové vyhledávání s fulltextovým vyhledáváním pomocí klíčových slov. Filtry a sémantické řazení se vztahují pouze na textový obsah, nikoli vektory.

Vyčistěte zdroje

Když pracujete ve vlastním předplatném, je vhodné dokončit projekt odebráním prostředků, které už nepotřebujete. Prostředky, které zůstaly spuštěné, vám můžou stát peníze.

Na portálu Azure vyberte Všechny prostředky nebo Zdrojové skupiny v levém podokně a vyhledejte a spravujte prostředky. Prostředky můžete odstranit jednotlivě nebo odstranit skupinu prostředků a odebrat tak všechny prostředky najednou.

Jinak můžete odeslat ### Delete an index požadavek na odstranění indexu, který jste vytvořili v tomto rychlém startu.

Související obsah

• Vektorové vyhledávání v Azure AI Vyhledávač
• úložiště azure-search-vector-samples GitHub