Rövid útmutató: Vektoros keresés

Ebben a rövid útmutatóban a .NET Azure AI Keresés ügyfélkönyvtárát használja, hogy létrehozzon, betöltsön és lekérdezzen egy vektorindexet. A .NET ügyfélkódtár absztrakciót biztosít a REST API-k felett az indexműveletek számára.

A Azure AI Keresés vektorindex indexsémával rendelkezik, amely vektor- és nemvektormezőket határoz meg, vektorkeresési konfigurációt a beágyazási területet létrehozó algoritmusokhoz, valamint a vektormező-definíciók lekérdezéskor kiértékelt beállításaihoz. Indexek – A vektorindex létrehozása vagy frissítése (REST API) létrehozza a vektorindexet.

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Egy Azure AI Keresés szolgáltatás. A rövid útmutatók többségéhez használhatja az ingyenes szintet, de a nagyobb adatfájlok esetében az Alapszintű vagy magasabb szintű verziót javasoljuk.

• .NET 8 vagy újabb.

• Git a mintaadattár klónozásához.

• A Microsoft Entra ID-vel történő kulcs nélküli hitelesítéshez használt Azure CLI.

Hozzáférés konfigurálása

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik hozzáféréssel a tartalomhoz és a műveletekhez a Azure AI Keresés. Ez a rövid útmutató a Microsoft Entra ID-t használja hitelesítéshez és szerepköralapú jogosultságkezeléshez. Szerepkörök hozzárendeléséhez tulajdonosnak vagy felhasználói hozzáférés-rendszergazdának kell lennie. Ha a szerepkörök nem megvalósíthatók, használja inkább a kulcsalapú hitelesítést .

Az ajánlott szerepköralapú hozzáférés konfigurálása:

1. Engedélyezze a szerepköralapú hozzáférést a keresési szolgáltatáshoz.

2. Rendelje hozzá a következő szerepköröket a felhasználói fiókjához.

   • Keresési szolgáltatás közreműködője

   • Keresési index adatszolgáltatója

   • Keresési index adatolvasó

Végpont lekérése

Minden Azure AI Keresés szolgáltatás rendelkezik egy endpoint, amely egy egyedi URL-cím, amely azonosítja és hálózati hozzáférést biztosít a szolgáltatáshoz. Egy későbbi szakaszban ezt a végpontot adja meg, hogy programozott módon csatlakozzon a keresési szolgáltatáshoz.

A végpont lekérése:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza az Áttekintés lehetőséget.

3. Jegyezze fel a végpontot, amelynek így kell kinéznie https://my-service.search.windows.net.

A környezet beállítása

1. A Git használatával klónozza a mintaadattárat.

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

2. Navigáljon a quickstart mappára.

   cd azure-search-dotnet-samples/quickstart-vector-search
   

3. Ebben VectorSearchCreatePopulateIndex/appsettings.jsona fájlban cserélje le a helyőrző értékét Endpoint a Get végpontban beszerzett URL-címre.

4. Ismételje meg az előző lépést a következőhöz VectorSearchExamples/appsettings.json: .

5. Ha kulcs nélküli hitelesítést szeretne a Microsoft Entra ID-vel, jelentkezzen be az Azure-fiókjába. Ha több előfizetéssel rendelkezik, válassza ki azt, amelyik a Azure AI Keresés szolgáltatást tartalmazza.

   az login
   

A kód futtatása

1. Futtassa az első projektet, hogy létrehozza és feltöltse az indexet.

   cd VectorSearchCreatePopulateIndex
   dotnet run
   

2. A VectorSearchExamples/Program.csprogramban törölje a futtatni kívánt lekérdezési metódusok kijelölését.

3. Futtassa a második projektet, hogy végrehajtsa azokat a lekérdezéseket az indexen.

   cd ..\VectorSearchExamples
   dotnet run
   

Kimenet

Az első projekt kimenete tartalmazza az index létrehozásának megerősítését és a sikeres dokumentumfeltöltéseket.

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

A második projekt kimenete az egyes engedélyezett lekérdezési módszerek keresési eredményeit jeleníti meg. Az alábbi példa egyvektoros keresési eredményeket mutat be.

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

A kód ismertetése

Most, hogy futtatta a kódot, bontsuk le a legfontosabb lépéseket:

1. Vektorindex létrehozása
2. Dokumentumok feltöltése az indexbe
3. Az index lekérdezése

Vektorindex létrehozása

Mielőtt tartalmat ad hozzá Azure AI Keresés, létre kell hoznia egy indexet a tartalom tárolási és strukturált módjának meghatározásához.

Az indexséma a szállodai tartalom köré van rendezve. A mintaadatok magukban foglalják a fiktív szállodák vektoros és nem vektoros leírásait. A következő kód létrehozza VectorSearchCreatePopulateIndex/Program.cs az indexsémát, beleértve a vektormezőt DescriptionVectoris.

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

Főbb tanulságok

• Az indexet mezők listájának létrehozásával határozhatja meg.

• Ez az adott index több keresési képességet is támogat:

  • Teljes szöveges keresés (SearchableField)

  • Vektorkeresés (VectorSearchField)

  • Szemantikai rangsor (SemanticSearch)

  • Faceted search (mezők megjelölve IsFacetable)

  • Geo-térbeli keresés (Location mező a következővel SearchFieldDataType.GeographyPoint: )

  • Szűrés és rendezés (mezők megjelölve IsFilterableIsSortable)

• A VectorSearchField második paramétere a vectorSearchDimensions, amelynek meg kell egyeznie a beágyazási modell kimeneti méretével. Ez a gyorsútmutató 1 536 dimenziót használ a text-embedding-ada-002 modellhez való megfeleléshez.

• A VectorSearch konfiguráció a legközelebbi szomszéd (ANN) algoritmust határozza meg. A támogatott algoritmusok közé tartozik a Hierarchical Navigable Small World (HNSW) és a teljes K-Legközelebbi szomszéd (KNN). További információ: Relevancia a vektorkeresésben.

Dokumentumok feltöltése az indexbe

Az újonnan létrehozott indexek üresek. Az index feltöltéséhez és kereséséhez fel kell töltenie az indexsémának megfelelő JSON-dokumentumokat.

A Azure AI Keresés a dokumentumok mind az indexelés, mind a lekérdezések kimenetei bemeneteként szolgálnak. Az egyszerűség kedvéért ez a rövid útmutató előre konfigurált vektorokkal kínál minta szállodai dokumentumokat. Éles helyzetekben a tartalmat gyakran lekérik a csatlakoztatott adatforrásokból, és indexelők használatával JSON formátumúra alakítják át.

Az alábbi kód dokumentumokat tölt fel a keresési szolgáltatásba HotelData.json.

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

A kód az Azure AI Keresés szolgáltatásban üzemeltetett adott keresőindex-szel lép kapcsolatba a SearchClient segítségével, ami a Azure.Search.Documents csomag által biztosított fő objektum. Ez SearchClient hozzáférést biztosít az indexműveletekhez, például:

• Adatbetöltés: UploadDocuments(), MergeDocuments(), DeleteDocuments()

• Keresési műveletek: Search(), , Autocomplete()Suggest()

Az index lekérdezése

A lekérdezések VectorSearchExamples különböző keresési mintákat mutatnak be. A példavektor-lekérdezések két sztringen alapulnak:

• Teljes szöveges keresési karakterlánc: "historic hotel walk to restaurants and shopping"

• Vektoros lekérdezési sztring: "quintessential lodging near running trails, eateries, retail" (vektorizált matematikai ábrázolásba)

A vektoros lekérdezési sztring szemantikailag hasonlít a teljes szöveges keresési sztringhez, de olyan kifejezéseket is tartalmaz, amelyek nem léteznek az indexben. A vektoros lekérdezési sztring csak kulcsszóval történő keresése nulla eredményt ad vissza. A vektorkeresés azonban a pontos kulcsszavak helyett a jelentés alapján keres releváns találatokat.

Az alábbi példák egy alapvektoros lekérdezéssel kezdődnek, és fokozatosan adnak hozzá szűrőket, kulcsszókeresést és szemantikai rerankingot.

Egyvektoros keresés

A SearchSingleVector módszer egy alapforgatókönyvet mutat be, amelyben a vektoros lekérdezési sztringgel szorosan egyező dokumentumleírásokat szeretne keresni. VectorizedQuery konfigurálja a vektorkeresést:

• KNearestNeighborsCount korlátozza, hogy hány eredményt ad vissza a vektorok hasonlósága alapján.
• Fields megadja a keresendő vektormezőt.

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

Egyvektoros keresés szűrővel

Az Azure AI Keresés szűrők a nemvektor mezőkre vonatkoznak egy indexben. A SearchSingleVectorWithFilter metódus szűri a mezőt, hogy kiszűrje azokat a Tags szállodákat, amelyek nem biztosítanak ingyenes Wi-Fi-t.

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

Egyvektoros keresés geoszűrővel

Megadhat egy földrajzi térbeli szűrőt , amely egy adott földrajzi területre korlátozza az eredményeket. A SingleSearchWithGeoFilter módszer egy földrajzi pontot (Washington D.C., hosszúsági és szélességi koordináták használatával) határoz meg, és 300 kilométeren belül ad vissza szállodákat. Alapértelmezés szerint a szűrők a vektorkeresés után futnak.

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

Hibrid keresés

A hibrid keresés egyetlen kérelemben egyesíti a teljes szöveges és vektoros lekérdezéseket. A SearchHybridVectorAndText metódus egyszerre futtatja mindkét lekérdezéstípust, majd a Kölcsönös rangsor fúzió (RRF) használatával egyesíti az eredményeket egy egységes rangsorban. Az RRF az egyes eredményhalmazok eredménysorainak inverzét használja egy egyesített rangsor létrehozásához. Figyelje meg, hogy a hibrid keresési pontszámok egységesen kisebbek, mint az egy lekérdezéses pontszámok.

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

Szemantikus hibrid keresés

A SearchHybridVectorAndSemantic módszer bemutatja a szemantikai rangsorolást, amely a nyelvtudás alapján reranksálja az eredményeket.

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

Hasonlítsa össze ezeket az eredményeket az előző lekérdezés hibrid keresési eredményeivel. Szemantikai reranking nélkül a Sublime Palace Hotel az első helyen áll, mivel a Kölcsönös Rangsor Fúzió (RRF) egyesíti a szöveget és a vektorpontszámokat az egyesített eredmény létrehozásához. A szemantikus reranking után a Swirling Currents Hotel a legfelső helyre kerül.

A szemantikai rangsoroló gépi szövegértési modelleket használ annak kiértékeléséhez, hogy az egyes eredmények mennyire egyek a lekérdezés szándékának megfelelően. Swirling Currents Hotel leírása említi "walking access to shopping, dining, entertainment and the city center", amely szorosan igazodik a keresési lekérdezés "walk to restaurants and shopping". Ez a szemantikus egyezés a közeli étkezéshez és vásárláshoz emeli a Sublime Palace Hotel felett, amely nem hangsúlyozza a sétálható kényelmi elemeket a leírásában.

Főbb tanulságok

• Hibrid keresés esetén a vektoros keresést teljes szöveges kereséssel integrálhatja kulcsszavakon keresztül. A szűrők és a szemantikai rangsorolás csak a szöveges tartalomra vonatkozik, a vektorokra nem.

• A tényleges eredmények további részleteket tartalmaznak, beleértve a szemantikai feliratokat és a kiemeléseket. Ez a rövid útmutató módosítja az eredményeket az olvashatóság érdekében. A válasz teljes szerkezetének lekéréséhez a REST használatával futtassa a kérést.

Erőforrások törlése

Ha a saját előfizetésében dolgozik, érdemes befejezni egy projektet a már nem szükséges erőforrások eltávolításával. Az otthagyott futó erőforrások pénzbe kerülhetnek.

Az Azure portálon válassza a Minden erőforrás vagy Erőforráscsoportok lehetőséget a bal oldali panelen az erőforrások megkereséséhez és kezeléséhez. Az erőforrásokat egyenként törölheti, vagy törölheti az erőforráscsoportot az összes erőforrás egyidejű eltávolításához.

Ebben a gyorstalpalóban az Azure AI Keresés klienskönyvtárat Java-ban fogja használni, hogy létrehozzon, betöltsön és lekérdezzen egy vektori indexet. A Java ügyfélkódtár absztrakciót biztosít a REST API-k felett az indexműveletek számára.

A Azure AI Keresés vektorindex indexsémával rendelkezik, amely vektor- és nemvektormezőket határoz meg, vektorkeresési konfigurációt a beágyazási területet létrehozó algoritmusokhoz, valamint a vektormező-definíciók lekérdezéskor kiértékelt beállításaihoz. Indexek – A vektorindex létrehozása vagy frissítése (REST API) létrehozza a vektorindexet.

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Egy Azure AI Keresés szolgáltatás. A rövid útmutatók többségéhez használhatja az ingyenes szintet, de a nagyobb adatfájlok esetében az Alapszintű vagy magasabb szintű verziót javasoljuk.

• Java 21 (LTS) és Maven.

• Git a mintaadattár klónozásához.

• A Microsoft Entra ID-vel történő kulcs nélküli hitelesítéshez használt Azure CLI.

Hozzáférés konfigurálása

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik hozzáféréssel a tartalomhoz és a műveletekhez a Azure AI Keresés. Ez a rövid útmutató a Microsoft Entra ID-t használja hitelesítéshez és szerepköralapú jogosultságkezeléshez. Szerepkörök hozzárendeléséhez tulajdonosnak vagy felhasználói hozzáférés-rendszergazdának kell lennie. Ha a szerepkörök nem megvalósíthatók, használja inkább a kulcsalapú hitelesítést .

Az ajánlott szerepköralapú hozzáférés konfigurálása:

1. Engedélyezze a szerepköralapú hozzáférést a keresési szolgáltatáshoz.

2. Rendelje hozzá a következő szerepköröket a felhasználói fiókjához.

   • Keresési szolgáltatás közreműködője

   • Keresési index adatszolgáltatója

   • Keresési index adatolvasó

Végpont lekérése

Minden Azure AI Keresés szolgáltatás rendelkezik egy endpoint, amely egy egyedi URL-cím, amely azonosítja és hálózati hozzáférést biztosít a szolgáltatáshoz. Egy későbbi szakaszban ezt a végpontot adja meg, hogy programozott módon csatlakozzon a keresési szolgáltatáshoz.

A végpont lekérése:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza az Áttekintés lehetőséget.

3. Jegyezze fel a végpontot, amelynek így kell kinéznie https://my-service.search.windows.net.

A környezet beállítása

1. A Git használatával klónozza a mintaadattárat.

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

2. Navigáljon a quickstart mappára.

   cd azure-search-java-samples/quickstart-vector-search
   

3. Ebben src/main/resources/application.propertiesa fájlban cserélje le a helyőrző értékét azure.search.endpoint a Get végpontban beszerzett URL-címre.

4. Telepítse a függőségeket.

   mvn clean dependency:copy-dependencies
   

   Amikor a build befejeződött, meg kell jelennie egy target/dependency mappának a projektkönyvtárban.

5. Ha kulcs nélküli hitelesítést szeretne a Microsoft Entra ID-vel, jelentkezzen be az Azure-fiókjába. Ha több előfizetéssel rendelkezik, válassza ki azt, amelyik a Azure AI Keresés szolgáltatást tartalmazza.

   az login
   

A kód futtatása

1. Vektorindex létrehozása.

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

2. Előre összeállított beágyazásokat tartalmazó dokumentumok betöltése.

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

3. Futtasson vektorkeresési lekérdezést.

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

4. (Nem kötelező) Futtasson további lekérdezésvariációkat.

   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"
   

Kimenet

A kimenet az CreateIndex.java index nevét és megerősítését jeleníti meg.

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

A kimenet UploadDocuments.java az egyes indexelt dokumentumok sikerességi állapotát jeleníti meg.

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.

A kimenet a SearchSingle.java hasonlósági pontszám alapján rangsorolt vektorkeresési eredményeket jeleníti meg.

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

A kód ismertetése

Most, hogy futtatta a kódot, bontsuk le a legfontosabb lépéseket:

1. Vektorindex létrehozása
2. Dokumentumok feltöltése az indexbe
3. Az index lekérdezése

Vektorindex létrehozása

Mielőtt tartalmat ad hozzá Azure AI Keresés, létre kell hoznia egy indexet a tartalom tárolási és strukturált módjának meghatározásához.

Az indexséma a szállodai tartalom köré van rendezve. A mintaadatok magukban foglalják a fiktív szállodák vektoros és nem vektoros leírásait. A következő kód létrehozza CreateIndex.java az indexsémát, beleértve a vektormezőt DescriptionVectoris.

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

Főbb tanulságok

• Az indexet mezők listájának létrehozásával határozhatja meg.

• Ez az adott index több keresési képességet is támogat:

  • Teljes szöveges keresés (setSearchable)

  • Vektorkeresés (DescriptionVector használva setVectorSearchProfileName)

  • Szemantikai rangsor (SemanticConfiguration)

  • Faceted search (mezők megjelölve setFacetable)

  • Geo-térbeli keresés (Location mező a következővel SearchFieldDataType.GEOGRAPHY_POINT: )

  • Szűrés és rendezés (mezők megjelölve setFilterablesetSortable)

• Az setVectorSearchDimensions() értéknek meg kell egyeznie a beágyazási modell kimeneti méretével. Ez a gyorsútmutató 1 536 dimenziót használ a text-embedding-ada-002 modellhez való megfeleléshez.

• A VectorSearch konfiguráció a legközelebbi szomszéd (ANN) algoritmust határozza meg. A támogatott algoritmusok közé tartozik a Hierarchical Navigable Small World (HNSW) és a teljes K-Legközelebbi szomszéd (KNN). További információ: Relevancia a vektorkeresésben.

Dokumentumok feltöltése az indexbe

Az újonnan létrehozott indexek üresek. Az index feltöltéséhez és kereséséhez fel kell töltenie az indexsémának megfelelő JSON-dokumentumokat.

A Azure AI Keresés a dokumentumok mind az indexelés, mind a lekérdezések kimenetei bemeneteként szolgálnak. Az egyszerűség kedvéért ez a rövid útmutató előre konfigurált vektorokkal kínál minta szállodai dokumentumokat. Éles helyzetekben a tartalmat gyakran lekérik a csatlakoztatott adatforrásokból, és indexelők használatával JSON formátumúra alakítják át.

Az alábbi kód UploadDocuments.java dokumentumokat tölt fel a keresési szolgáltatásba.

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

A kód az Azure AI Keresés szolgáltatásban üzemeltetett adott keresőindex-szel lép kapcsolatba a SearchClient segítségével, ami a azure-search-documents csomag által biztosított fő objektum. A SearchClient következő műveletekhez biztosít hozzáférést:

• Adatbetöltés: uploadDocuments, mergeDocuments, deleteDocuments

• Keresési műveletek: search, , autocompletesuggest

Az index lekérdezése

A keresési fájlokban lévő lekérdezések különböző keresési mintákat mutatnak be. A példavektor-lekérdezések két sztringen alapulnak:

• Teljes szöveges keresési karakterlánc: "historic hotel walk to restaurants and shopping"

• Vektoros lekérdezési sztring: "quintessential lodging near running trails, eateries, retail" (vektorizált matematikai ábrázolásba)

A vektoros lekérdezési sztring szemantikailag hasonlít a teljes szöveges keresési sztringhez, de olyan kifejezéseket is tartalmaz, amelyek nem léteznek az indexben. A vektoros lekérdezési sztring csak kulcsszóval történő keresése nulla eredményt ad vissza. A vektorkeresés azonban a pontos kulcsszavak helyett a jelentés alapján keres releváns találatokat.

Az alábbi példák egy alapvektoros lekérdezéssel kezdődnek, és fokozatosan adnak hozzá szűrőket, kulcsszókeresést és szemantikai rerankingot.

Egyvektoros keresés

SearchSingle.java egy olyan alapforgatókönyvet mutat be, amelyben a vektoros lekérdezési sztringgel szorosan egyező dokumentumleírásokat szeretne keresni. VectorizedQuery konfigurálja a vektorkeresést:

• setKNearestNeighborsCount() korlátozza, hogy hány eredményt ad vissza a vektorok hasonlósága alapján.
• setFields() megadja a keresendő vektormezőt.

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

Egyvektoros keresés szűrővel

Az Azure AI Keresés szűrők a nemvektor mezőkre vonatkoznak egy indexben. SearchSingleWithFilter.java szűri a mezőt, hogy kiszűrje azokat a Tags szállodákat, amelyek nem biztosítanak ingyenes Wi-Fi-t.

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

Egyvektoros keresés geoszűrővel

Megadhat egy földrajzi térbeli szűrőt , amely egy adott földrajzi területre korlátozza az eredményeket. SearchSingleWithGeoFilter.java földrajzi pontot (Washington D.C., hosszúsági és szélességi koordináták használatával) határoz meg, és 300 kilométeren belül ad vissza szállodákat. A setFilterMode-en meghívott VectorSearchOptions metódus határozza meg, hogy mikor fut a szűrő. Ebben az esetben POST_FILTER futtatja a szűrőt a vektorkeresés után.

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

Hibrid keresés

A hibrid keresés egyetlen kérelemben egyesíti a teljes szöveges és vektoros lekérdezéseket. SearchHybrid.java Mindkét lekérdezéstípust egyszerre futtatja, majd a Kölcsönös rangsor fúzió (RRF) használatával egyesíti az eredményeket egy egységes rangsorban. Az RRF az egyes eredményhalmazok eredménysorainak inverzét használja egy egyesített rangsor létrehozásához. Figyelje meg, hogy a hibrid keresési pontszámok egységesen kisebbek, mint az egy lekérdezéses pontszámok.

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

Szemantikus hibrid keresés

SearchSemanticHybrid.java a szemantikai rangsorolást mutatja be, amely a nyelvi megértés alapján reranksálja az eredményeket.

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

Hasonlítsa össze ezeket az eredményeket az előző lekérdezés hibrid keresési eredményeivel. Szemantikai reranking nélkül a Sublime Palace Hotel az első helyen áll, mivel a Kölcsönös Rangsor Fúzió (RRF) egyesíti a szöveget és a vektorpontszámokat az egyesített eredmény létrehozásához. A szemantikus reranking után a Swirling Currents Hotel a legfelső helyre kerül.

A szemantikai rangsoroló gépi szövegértési modelleket használ annak kiértékeléséhez, hogy az egyes eredmények mennyire egyek a lekérdezés szándékának megfelelően. Swirling Currents Hotel leírása említi "walking access to shopping, dining, entertainment and the city center", amely szorosan igazodik a keresési lekérdezés "walk to restaurants and shopping". Ez a szemantikus egyezés a közeli étkezéshez és vásárláshoz emeli a Sublime Palace Hotel felett, amely nem hangsúlyozza a sétálható kényelmi elemeket a leírásában.

Főbb tanulságok

• Hibrid keresés esetén a vektoros keresést teljes szöveges kereséssel integrálhatja kulcsszavakon keresztül. A szűrők és a szemantikai rangsorolás csak a szöveges tartalomra vonatkozik, a vektorokra nem.

• A tényleges eredmények további részleteket tartalmaznak, beleértve a szemantikai feliratokat és a kiemeléseket. Ez a rövid útmutató módosítja az eredményeket az olvashatóság érdekében. A válasz teljes szerkezetének lekéréséhez a REST használatával futtassa a kérést.

Erőforrások törlése

Ha a saját előfizetésében dolgozik, érdemes befejezni egy projektet a már nem szükséges erőforrások eltávolításával. Az otthagyott futó erőforrások pénzbe kerülhetnek.

Az Azure portálon válassza a Minden erőforrás vagy Erőforráscsoportok lehetőséget a bal oldali panelen az erőforrások megkereséséhez és kezeléséhez. Az erőforrásokat egyenként törölheti, vagy törölheti az erőforráscsoportot az összes erőforrás egyidejű eltávolításához.

Ellenkező esetben futtassa a következő parancsot az ebben a rövid útmutatóban létrehozott index törléséhez.

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

Ebben a rövid útmutatóban a JavaScripthez készült Azure AI Keresés ügyfélkönyvtárat használja egy vektor index létrehozásához, betöltéséhez és lekérdezéséhez. A JavaScript-ügyfélkódtár absztrakciót biztosít a REST API-k felett az indexműveletek számára.

A Azure AI Keresés vektorindex indexsémával rendelkezik, amely vektor- és nemvektormezőket határoz meg, vektorkeresési konfigurációt a beágyazási területet létrehozó algoritmusokhoz, valamint a vektormező-definíciók lekérdezéskor kiértékelt beállításaihoz. Indexek – A vektorindex létrehozása vagy frissítése (REST API) létrehozza a vektorindexet.

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Egy Azure AI Keresés szolgáltatás. A rövid útmutatók többségéhez használhatja az ingyenes szintet, de a nagyobb adatfájlok esetében az Alapszintű vagy magasabb szintű verziót javasoljuk.

• Node.js 20 LTS vagy újabb.

• Git a mintaadattár klónozásához.

• A Microsoft Entra ID-vel történő kulcs nélküli hitelesítéshez használt Azure CLI.

Hozzáférés konfigurálása

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik hozzáféréssel a tartalomhoz és a műveletekhez a Azure AI Keresés. Ez a rövid útmutató a Microsoft Entra ID-t használja hitelesítéshez és szerepköralapú jogosultságkezeléshez. Szerepkörök hozzárendeléséhez tulajdonosnak vagy felhasználói hozzáférés-rendszergazdának kell lennie. Ha a szerepkörök nem megvalósíthatók, használja inkább a kulcsalapú hitelesítést .

Az ajánlott szerepköralapú hozzáférés konfigurálása:

1. Engedélyezze a szerepköralapú hozzáférést a keresési szolgáltatáshoz.

2. Rendelje hozzá a következő szerepköröket a felhasználói fiókjához.

   • Keresési szolgáltatás közreműködője

   • Keresési index adatszolgáltatója

   • Keresési index adatolvasó

Végpont lekérése

Minden Azure AI Keresés szolgáltatás rendelkezik egy endpoint, amely egy egyedi URL-cím, amely azonosítja és hálózati hozzáférést biztosít a szolgáltatáshoz. Egy későbbi szakaszban ezt a végpontot adja meg, hogy programozott módon csatlakozzon a keresési szolgáltatáshoz.

A végpont lekérése:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza az Áttekintés lehetőséget.

3. Jegyezze fel a végpontot, amelynek így kell kinéznie https://my-service.search.windows.net.

A környezet beállítása

1. A Git használatával klónozza a mintaadattárat.

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

2. Navigáljon a quickstart mappára.

   cd azure-search-javascript-samples/quickstart-vector-js
   

3. Ebben sample.enva fájlban cserélje le a helyőrző értékét AZURE_SEARCH_ENDPOINT a Get végpontban beszerzett URL-címre.

4. Átnevezés sample.env : .env.

   mv sample.env .env
   

5. Telepítse a függőségeket.

   npm install
   

   Amikor a telepítés befejeződött, a projektkönyvtárban meg kell jelennie egy node_modules mappának.

6. Ha kulcs nélküli hitelesítést szeretne a Microsoft Entra ID-vel, jelentkezzen be az Azure-fiókjába. Ha több előfizetéssel rendelkezik, válassza ki azt, amelyik a Azure AI Keresés szolgáltatást tartalmazza.

   az login
   

A kód futtatása

1. Vektorindex létrehozása.

   node -r dotenv/config src/createIndex.js
   

2. Előre összeállított beágyazásokat tartalmazó dokumentumok betöltése.

   node -r dotenv/config src/uploadDocuments.js
   

3. Futtasson vektorkeresési lekérdezést.

   node -r dotenv/config src/searchSingle.js
   

4. (Nem kötelező) Futtasson további lekérdezésvariációkat.

   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
   

Kimenet

A kimenet az createIndex.js index nevét és megerősítését jeleníti meg.

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

A kimenet uploadDocuments.js az egyes indexelt dokumentumok sikerességi állapotát jeleníti meg.

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.

A kimenet a searchSingle.js hasonlósági pontszám alapján rangsorolt vektorkeresési eredményeket jeleníti meg.

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

A kód ismertetése

Most, hogy futtatta a kódot, bontsuk le a legfontosabb lépéseket:

1. Vektorindex létrehozása
2. Dokumentumok feltöltése az indexbe
3. Az index lekérdezése

Vektorindex létrehozása

Mielőtt tartalmat ad hozzá Azure AI Keresés, létre kell hoznia egy indexet a tartalom tárolási és strukturált módjának meghatározásához.

Az indexséma a szállodai tartalom köré van rendezve. A mintaadatok magukban foglalják a fiktív szállodák vektoros és nem vektoros leírásait. A következő kód létrehozza createIndex.js az indexsémát, beleértve a vektormezőt DescriptionVectoris.

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

Főbb tanulságok

• Az indexet mezők listájának létrehozásával határozhatja meg.

• Ez az adott index több keresési képességet is támogat:

  • Teljes szöveges keresés (searchable: true)

  • Vektorkeresés (DescriptionVector használva vectorSearchProfileName)

  • Szemantikai rangsor (semanticSearch)

  • Faceted search (mezők megjelölve facetable)

  • Geo-térbeli keresés (Location mező a következővel Edm.GeographyPoint: )

  • Szűrés és rendezés (mezők megjelölve filterablesortable)

• A vectorSearchDimensions tulajdonságnak meg kell egyeznie a beágyazási modell kimeneti méretével. Ez a gyorsútmutató 1 536 dimenziót használ a text-embedding-ada-002 modellhez való megfeleléshez.

• A vectorSearch konfiguráció a legközelebbi szomszéd (ANN) algoritmust határozza meg. A támogatott algoritmusok közé tartozik a Hierarchical Navigable Small World (HNSW) és a teljes K-Legközelebbi szomszéd (KNN). További információ: Relevancia a vektorkeresésben.

Dokumentumok feltöltése az indexbe

Az újonnan létrehozott indexek üresek. Az index feltöltéséhez és kereséséhez fel kell töltenie az indexsémának megfelelő JSON-dokumentumokat.

A Azure AI Keresés a dokumentumok mind az indexelés, mind a lekérdezések kimenetei bemeneteként szolgálnak. Az egyszerűség kedvéért ez a rövid útmutató előre konfigurált vektorokkal kínál minta szállodai dokumentumokat. Éles helyzetekben a tartalmat gyakran lekérik a csatlakoztatott adatforrásokból, és indexelők használatával JSON formátumúra alakítják át.

Az alábbi kód uploadDocuments.js dokumentumokat tölt fel a keresési szolgáltatásba.

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

A kód az Azure AI Keresés szolgáltatásban üzemeltetett adott keresőindex-szel lép kapcsolatba a SearchClient segítségével, ami a @azure/search-documents csomag által biztosított fő objektum. Ez SearchClient hozzáférést biztosít az indexműveletekhez, például:

• Adatbetöltés: uploadDocuments, mergeDocuments, deleteDocuments

• Keresési műveletek: search, , autocompletesuggest

Az index lekérdezése

A keresési fájlokban lévő lekérdezések különböző keresési mintákat mutatnak be. A példavektor-lekérdezések két sztringen alapulnak:

• Teljes szöveges keresési karakterlánc: "historic hotel walk to restaurants and shopping"

• Vektoros lekérdezési sztring: "quintessential lodging near running trails, eateries, retail" (vektorizált matematikai ábrázolásba)

A vektoros lekérdezési sztring szemantikailag hasonlít a teljes szöveges keresési sztringhez, de olyan kifejezéseket is tartalmaz, amelyek nem léteznek az indexben. A vektoros lekérdezési sztring csak kulcsszóval történő keresése nulla eredményt ad vissza. A vektorkeresés azonban a pontos kulcsszavak helyett a jelentés alapján keres releváns találatokat.

Az alábbi példák egy alapvektoros lekérdezéssel kezdődnek, és fokozatosan adnak hozzá szűrőket, kulcsszókeresést és szemantikai rerankingot.

Egyvektoros keresés

searchSingle.js egy olyan alapforgatókönyvet mutat be, amelyben a vektoros lekérdezési sztringgel szorosan egyező dokumentumleírásokat szeretne keresni. Az vectorQuery objektum konfigurálja a vektorkeresést:

• kNearestNeighborsCount korlátozza, hogy hány eredményt ad vissza a vektorok hasonlósága alapján.
• fields megadja a keresendő vektormezőt.

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

Egyvektoros keresés szűrővel

Az Azure AI Keresés szűrők a nemvektor mezőkre vonatkoznak egy indexben. searchSingleWithFilter.js szűri a mezőt, hogy kiszűrje azokat a Tags szállodákat, amelyek nem biztosítanak ingyenes Wi-Fi-t.

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

Egyvektoros keresés geoszűrővel

Megadhat egy földrajzi térbeli szűrőt , amely egy adott földrajzi területre korlátozza az eredményeket. searchSingleWithGeoFilter.js földrajzi pontot (Washington D.C., hosszúsági és szélességi koordináták használatával) határoz meg, és 300 kilométeren belül ad vissza szállodákat. A filterMode tulajdonság határozza meg, hogy mikor fut a szűrő. Ebben az esetben postFilter futtatja a szűrőt a vektorkeresés után.

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

Hibrid keresés

A hibrid keresés egyetlen kérelemben egyesíti a teljes szöveges és vektoros lekérdezéseket. searchHybrid.js Mindkét lekérdezéstípust egyszerre futtatja, majd a Kölcsönös rangsor fúzió (RRF) használatával egyesíti az eredményeket egy egységes rangsorban. Az RRF az egyes eredményhalmazok eredménysorainak inverzét használja egy egyesített rangsor létrehozásához. Figyelje meg, hogy a hibrid keresési pontszámok egységesen kisebbek, mint az egy lekérdezéses pontszámok.

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

Szemantikus hibrid keresés

searchSemanticHybrid.js a szemantikai rangsorolást mutatja be, amely a nyelvi megértés alapján reranksálja az eredményeket.

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

Hasonlítsa össze ezeket az eredményeket az előző lekérdezés hibrid keresési eredményeivel. Szemantikai reranking nélkül a Sublime Palace Hotel az első helyen áll, mivel a Kölcsönös Rangsor Fúzió (RRF) egyesíti a szöveget és a vektorpontszámokat az egyesített eredmény létrehozásához. A szemantikus reranking után a Swirling Currents Hotel a legfelső helyre kerül.

A szemantikai rangsoroló gépi szövegértési modelleket használ annak kiértékeléséhez, hogy az egyes eredmények mennyire egyek a lekérdezés szándékának megfelelően. Swirling Currents Hotel leírása említi "walking access to shopping, dining, entertainment and the city center", amely szorosan igazodik a keresési lekérdezés "walk to restaurants and shopping". Ez a szemantikus egyezés a közeli étkezéshez és vásárláshoz emeli a Sublime Palace Hotel felett, amely nem hangsúlyozza a sétálható kényelmi elemeket a leírásában.

Főbb tanulságok

• Hibrid keresés esetén a vektoros keresést teljes szöveges kereséssel integrálhatja kulcsszavakon keresztül. A szűrők és a szemantikai rangsorolás csak a szöveges tartalomra vonatkozik, a vektorokra nem.

• A tényleges eredmények további részleteket tartalmaznak, beleértve a szemantikai feliratokat és a kiemeléseket. Ez a rövid útmutató módosítja az eredményeket az olvashatóság érdekében. A válasz teljes szerkezetének lekéréséhez a REST használatával futtassa a kérést.

Erőforrások törlése

Ha a saját előfizetésében dolgozik, érdemes befejezni egy projektet a már nem szükséges erőforrások eltávolításával. Az otthagyott futó erőforrások pénzbe kerülhetnek.

Az Azure portálon válassza a Minden erőforrás vagy Erőforráscsoportok lehetőséget a bal oldali panelen az erőforrások megkereséséhez és kezeléséhez. Az erőforrásokat egyenként törölheti, vagy törölheti az erőforráscsoportot az összes erőforrás egyidejű eltávolításához.

Ellenkező esetben futtassa a következő parancsot az ebben a rövid útmutatóban létrehozott index törléséhez.

node -r dotenv/config src/deleteIndex.js

Ebben a gyorsútmutatóban az Azure AI Keresés ügyfélkódtárát használja Pythonban, hogy létrehozzon, betöltsön és lekérdezzen egy vektorkatalógust. A Python ügyfélkódtár absztrakciót biztosít a REST API-k felett az indexműveletek számára.

A Azure AI Keresés vektorindex indexsémával rendelkezik, amely vektor- és nemvektormezőket határoz meg, vektorkeresési konfigurációt a beágyazási területet létrehozó algoritmusokhoz, valamint a vektormező-definíciók lekérdezéskor kiértékelt beállításaihoz. Indexek – A vektorindex létrehozása vagy frissítése (REST API) létrehozza a vektorindexet.

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Egy Azure AI Keresés szolgáltatás. A rövid útmutatók többségéhez használhatja az ingyenes szintet, de a nagyobb adatfájlok esetében az Alapszintű vagy magasabb szintű verziót javasoljuk.

• Python 3.8 vagy újabb.

• Visual Studio CodePython és Jupyter kiterjesztéssel.

• Git a mintaadattár klónozásához.

• A Microsoft Entra ID-vel történő kulcs nélküli hitelesítéshez használt Azure CLI.

Hozzáférés konfigurálása

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik hozzáféréssel a tartalomhoz és a műveletekhez a Azure AI Keresés. Ez a rövid útmutató a Microsoft Entra ID-t használja hitelesítéshez és szerepköralapú jogosultságkezeléshez. Szerepkörök hozzárendeléséhez tulajdonosnak vagy felhasználói hozzáférés-rendszergazdának kell lennie. Ha a szerepkörök nem megvalósíthatók, használja inkább a kulcsalapú hitelesítést .

Az ajánlott szerepköralapú hozzáférés konfigurálása:

1. Engedélyezze a szerepköralapú hozzáférést a keresési szolgáltatáshoz.

2. Rendelje hozzá a következő szerepköröket a felhasználói fiókjához.

   • Keresési szolgáltatás közreműködője

   • Keresési index adatszolgáltatója

   • Keresési index adatolvasó

Végpont lekérése

Minden Azure AI Keresés szolgáltatás rendelkezik egy endpoint, amely egy egyedi URL-cím, amely azonosítja és hálózati hozzáférést biztosít a szolgáltatáshoz. Egy későbbi szakaszban ezt a végpontot adja meg, hogy programozott módon csatlakozzon a keresési szolgáltatáshoz.

A végpont lekérése:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza az Áttekintés lehetőséget.

3. Jegyezze fel a végpontot, amelynek így kell kinéznie https://my-service.search.windows.net.

A környezet beállítása

1. A Git használatával klónozza a mintaadattárat.

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

2. Nyissa meg a quickstart mappát a Visual Studio Code-ban.

   cd azure-search-python-samples/Quickstart-Vector-Search
   code .
   

3. Ebben sample.enva fájlban cserélje le a helyőrző értékét AZURE_SEARCH_ENDPOINT a Get végpontban beszerzett URL-címre.

4. Átnevezés sample.env : .env.

   mv sample.env .env
   

5. Nyisd meg vector-search-quickstart.ipynb.

6. Nyomja le a Ctrl+Shift+P billentyűkombinációt, válassza a Jegyzetfüzet: Jegyzetfüzet kernel kiválasztása lehetőséget, és kövesse az utasításokat egy virtuális környezet létrehozásához. Válassza a requirements.txt a függőségekhez.

   Ha elkészült, meg kell jelennie egy .venv mappának a projektkönyvtárban.

7. Ha kulcs nélküli hitelesítést szeretne a Microsoft Entra ID-vel, jelentkezzen be az Azure-fiókjába. Ha több előfizetéssel rendelkezik, válassza ki azt, amelyik a Azure AI Keresés szolgáltatást tartalmazza.

   az login
   

A kód futtatása

1. Futtassa a Install packages and set variables cellát a szükséges csomagok telepítéséhez és a környezeti változók betöltéséhez.

2. A többi cellát egymás után futtatva hozzon létre vektorindexet, töltsön fel dokumentumokat, és futtasson különböző típusú vektorlekérdezéseket.

Kimenet

Minden kódcella kinyomtatja a kimenetét a jegyzetfüzetbe. A következő példa a kimenete Single vector search, amely a vektorkeresés eredményeit jeleníti meg a hasonlósági pontszám alapján rangsorolva.

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

A kód ismertetése

Most, hogy futtatta a kódot, bontsuk le a legfontosabb lépéseket:

1. Vektorindex létrehozása
2. Dokumentumok feltöltése az indexbe
3. Az index lekérdezése

Vektorindex létrehozása

Mielőtt tartalmat ad hozzá Azure AI Keresés, létre kell hoznia egy indexet a tartalom tárolási és strukturált módjának meghatározásához.

Az indexséma a szállodai tartalom köré van rendezve. A mintaadatok magukban foglalják a fiktív szállodák vektoros és nem vektoros leírásait. A Create an index jegyzetfüzet cellájában létrejön az indexséma, beleértve a vektormezőt DescriptionVectoris.

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
]

Főbb tanulságok

• Az indexet mezők listájának létrehozásával határozhatja meg. Minden mező egy segédmetódussal jön létre, amely meghatározza a mező típusát és beállításait.

• Ez az adott index több keresési képességet is támogat:

  • Teljes szöveges keresés (SearchableField)

  • Vektorkeresés (DescriptionVector használva vector_search_profile_name)

  • Szemantikai rangsor (SemanticConfiguration)

  • Faceted search (mezők megjelölve facetable)

  • Geo-térbeli keresés (Location mező a következővel SearchFieldDataType.GeographyPoint: )

  • Szűrés és rendezés (mezők megjelölve filterablesortable)

• A vector_search_dimensions tulajdonságnak meg kell egyeznie a beágyazási modell kimeneti méretével. Ez a gyorsútmutató 1 536 dimenziót használ a text-embedding-ada-002 modellhez való megfeleléshez.

• A VectorSearch konfiguráció a legközelebbi szomszéd (ANN) algoritmust határozza meg. A támogatott algoritmusok közé tartozik a Hierarchical Navigable Small World (HNSW) és a teljes K-Legközelebbi szomszéd (KNN). További információ: Relevancia a vektorkeresésben.

Dokumentumok feltöltése az indexbe

Az újonnan létrehozott indexek üresek. Az index feltöltéséhez és kereséséhez fel kell töltenie az indexsémának megfelelő JSON-dokumentumokat.

A Azure AI Keresés a dokumentumok mind az indexelés, mind a lekérdezések kimenetei bemeneteként szolgálnak. Az egyszerűség kedvéért ez a rövid útmutató előre konfigurált vektorokkal kínál minta szállodai dokumentumokat. Éles helyzetekben a tartalmat gyakran lekérik a csatlakoztatott adatforrásokból, és indexelők használatával JSON formátumúra alakítják át.

A Create documents payload cellák és Upload the documents a cellák betöltik a dokumentumokat az indexbe.

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

A kód az Azure AI Keresés szolgáltatásban üzemeltetett adott keresőindex-szel lép kapcsolatba a SearchClient segítségével, ami a azure-search-documents csomag által biztosított fő objektum. Ez SearchClient hozzáférést biztosít az indexműveletekhez, például:

• Adatbetöltés: upload_documents(), merge_documents(), delete_documents()

• Keresési műveletek: search(), , autocomplete()suggest()

Az index lekérdezése

A jegyzetfüzet lekérdezései különböző keresési mintákat mutatnak be. A példavektor-lekérdezések két sztringen alapulnak:

• Teljes szöveges keresési karakterlánc: "historic hotel walk to restaurants and shopping"

• Vektoros lekérdezési sztring: "quintessential lodging near running trails, eateries, retail" (vektorizált matematikai ábrázolásba)

A vektoros lekérdezési sztring szemantikailag hasonlít a teljes szöveges keresési sztringhez, de olyan kifejezéseket is tartalmaz, amelyek nem léteznek az indexben. A vektoros lekérdezési sztring csak kulcsszóval történő keresése nulla eredményt ad vissza. A vektorkeresés azonban a pontos kulcsszavak helyett a jelentés alapján keres releváns találatokat.

Az alábbi példák egy alapvektoros lekérdezéssel kezdődnek, és fokozatosan adnak hozzá szűrőket, kulcsszókeresést és szemantikai rerankingot.

Egyvektoros keresés

A Single vector search cella egy alapforgatókönyvet mutat be, amelyben a vektoros lekérdezési sztringgel szorosan egyező dokumentumleírásokat szeretne keresni. VectorizedQuery konfigurálja a vektorkeresést:

• k_nearest_neighbors korlátozza, hogy hány eredményt ad vissza a vektorok hasonlósága alapján.
• fields megadja a keresendő vektormezőt.

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
)

Egyvektoros keresés szűrővel

Az Azure AI Keresés szűrők a nemvektor mezőkre vonatkoznak egy indexben. A Single vector search with filter cella szűri a mezőt, hogy kiszűrje azokat a Tags szállodákat, amelyek nem biztosítanak ingyenes Wi-Fi-t.

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

Egyvektoros keresés geoszűrővel

Megadhat egy földrajzi térbeli szűrőt , amely egy adott földrajzi területre korlátozza az eredményeket. A Single vector search with geo filter cella meghatároz egy földrajzi pontot (Washington D.C., hosszúsági és szélességi koordináták használatával), és 300 kilométeren belül ad vissza szállodákat. A vector_filter_mode paraméter határozza meg, hogy mikor fut a szűrő. Ebben az esetben postFilter futtatja a szűrőt a vektorkeresés után.

# 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]
)

Hibrid keresés

A hibrid keresés egyetlen kérelemben egyesíti a teljes szöveges és vektoros lekérdezéseket. A Hybrid search cella egyszerre futtatja mindkét lekérdezéstípust, majd a Kölcsönös rangsor fúzió (RRF) használatával egyesíti az eredményeket egy egységes rangsorban. Az RRF az egyes eredményhalmazok eredménysorainak inverzét használja egy egyesített rangsor létrehozásához. Figyelje meg, hogy a hibrid keresési pontszámok egységesen kisebbek, mint az egy lekérdezéses pontszámok.

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

Szemantikus hibrid keresés

A Semantic hybrid search cell bemutatja a szemantikai rangsorolást, amely a nyelvi megértés alapján újrasorolja az eredményeket.

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

Hasonlítsa össze ezeket az eredményeket az előző lekérdezés hibrid keresési eredményeivel. Szemantikai reranking nélkül a Sublime Palace Hotel az első helyen áll, mivel a Kölcsönös Rangsor Fúzió (RRF) egyesíti a szöveget és a vektorpontszámokat az egyesített eredmény létrehozásához. A szemantikus reranking után a Swirling Currents Hotel a legfelső helyre kerül.

A szemantikai rangsoroló gépi szövegértési modelleket használ annak kiértékeléséhez, hogy az egyes eredmények mennyire egyek a lekérdezés szándékának megfelelően. Swirling Currents Hotel leírása említi "walking access to shopping, dining, entertainment and the city center", amely szorosan igazodik a keresési lekérdezés "walk to restaurants and shopping". Ez a szemantikus egyezés a közeli étkezéshez és vásárláshoz emeli a Sublime Palace Hotel felett, amely nem hangsúlyozza a sétálható kényelmi elemeket a leírásában.

Főbb tanulságok

• Hibrid keresés esetén a vektoros keresést teljes szöveges kereséssel integrálhatja kulcsszavakon keresztül. A szűrők és a szemantikai rangsorolás csak a szöveges tartalomra vonatkozik, a vektorokra nem.

• A tényleges eredmények további részleteket tartalmaznak, beleértve a szemantikai feliratokat és a kiemeléseket. Ez a rövid útmutató módosítja az eredményeket az olvashatóság érdekében. A válasz teljes szerkezetének lekéréséhez a REST használatával futtassa a kérést.

Erőforrások törlése

Ha a saját előfizetésében dolgozik, érdemes befejezni egy projektet a már nem szükséges erőforrások eltávolításával. Az otthagyott futó erőforrások pénzbe kerülhetnek.

Az Azure portálon válassza a Minden erőforrás vagy Erőforráscsoportok lehetőséget a bal oldali panelen az erőforrások megkereséséhez és kezeléséhez. Az erőforrásokat egyenként törölheti, vagy törölheti az erőforráscsoportot az összes erőforrás egyidejű eltávolításához.

Ellenkező esetben futtathatja a Clean up kódcellát az ebben a rövid útmutatóban létrehozott index törléséhez.

Ebben a rövid útmutatóban a JavaScripthez készült Azure AI Keresés ügyfélkönyvtárat (amely kompatibilis a TypeScripttel) használja egy vektorkoordináták indexe létrehozásához, betöltéséhez és lekérdezéséhez. A JavaScript-ügyfélkódtár absztrakciót biztosít a REST API-k felett az indexműveletek számára.

A Azure AI Keresés vektorindex indexsémával rendelkezik, amely vektor- és nemvektormezőket határoz meg, vektorkeresési konfigurációt a beágyazási területet létrehozó algoritmusokhoz, valamint a vektormező-definíciók lekérdezéskor kiértékelt beállításaihoz. Indexek – A vektorindex létrehozása vagy frissítése (REST API) létrehozza a vektorindexet.

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Egy Azure AI Keresés szolgáltatás. A rövid útmutatók többségéhez használhatja az ingyenes szintet, de a nagyobb adatfájlok esetében az Alapszintű vagy magasabb szintű verziót javasoljuk.

• Node.js 20 LTS-t vagy újabb verziót a lefordított kód futtatásához.

• TypeScript a TypeScript JavaScriptre való fordításához.

• Git a mintaadattár klónozásához.

• A Microsoft Entra ID-vel történő kulcs nélküli hitelesítéshez használt Azure CLI.

Hozzáférés konfigurálása

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik hozzáféréssel a tartalomhoz és a műveletekhez a Azure AI Keresés. Ez a rövid útmutató a Microsoft Entra ID-t használja hitelesítéshez és szerepköralapú jogosultságkezeléshez. Szerepkörök hozzárendeléséhez tulajdonosnak vagy felhasználói hozzáférés-rendszergazdának kell lennie. Ha a szerepkörök nem megvalósíthatók, használja inkább a kulcsalapú hitelesítést .

Az ajánlott szerepköralapú hozzáférés konfigurálása:

1. Engedélyezze a szerepköralapú hozzáférést a keresési szolgáltatáshoz.

2. Rendelje hozzá a következő szerepköröket a felhasználói fiókjához.

   • Keresési szolgáltatás közreműködője

   • Keresési index adatszolgáltatója

   • Keresési index adatolvasó

Végpont lekérése

Minden Azure AI Keresés szolgáltatás rendelkezik egy endpoint, amely egy egyedi URL-cím, amely azonosítja és hálózati hozzáférést biztosít a szolgáltatáshoz. Egy későbbi szakaszban ezt a végpontot adja meg, hogy programozott módon csatlakozzon a keresési szolgáltatáshoz.

A végpont lekérése:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza az Áttekintés lehetőséget.

3. Jegyezze fel a végpontot, amelynek így kell kinéznie https://my-service.search.windows.net.

A környezet beállítása

1. A Git használatával klónozza a mintaadattárat.

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

2. Navigáljon a quickstart mappára.

   cd azure-search-javascript-samples/quickstart-vector-ts
   

3. Ebben sample.enva fájlban cserélje le a helyőrző értékét AZURE_SEARCH_ENDPOINT a Get végpontban beszerzett URL-címre.

4. Átnevezés sample.env : .env.

   mv sample.env .env
   

5. Telepítse a függőségeket.

   npm install
   

   Amikor a telepítés befejeződött, a projektkönyvtárban meg kell jelennie egy node_modules mappának.

6. A TypeScript-fájlok fordítása JavaScript-fájlba.

   npm run build
   

7. Ha kulcs nélküli hitelesítést szeretne a Microsoft Entra ID-vel, jelentkezzen be az Azure-fiókjába. Ha több előfizetéssel rendelkezik, válassza ki azt, amelyik a Azure AI Keresés szolgáltatást tartalmazza.

   az login
   

A kód futtatása

1. Vektorindex létrehozása.

   node -r dotenv/config dist/createIndex.js
   

2. Előre összeállított beágyazásokat tartalmazó dokumentumok betöltése.

   node -r dotenv/config dist/uploadDocuments.js
   

3. Futtasson vektorkeresési lekérdezést.

   node -r dotenv/config dist/searchSingle.js
   

4. (Nem kötelező) Futtasson további lekérdezésvariációkat.

   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
   

   Megjegyzés

   Ezek a parancsok futtatják a lefordított .js fájlokat a dist mappából. A TypeScript-kódot JavaScriptre kell lefordítani, mielőtt a Node.js végrehajthatja azt, ezért korábban futtatta a npm run build-t.

Kimenet

A kimenet az createIndex.ts index nevét és megerősítését jeleníti meg.

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

A kimenet uploadDocuments.ts az egyes indexelt dokumentumok sikerességi állapotát jeleníti meg.

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.

A kimenet a searchSingle.ts hasonlósági pontszám alapján rangsorolt vektorkeresési eredményeket jeleníti meg.

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

A kód ismertetése

Most, hogy futtatta a kódot, bontsuk le a legfontosabb lépéseket:

1. Vektorindex létrehozása
2. Dokumentumok feltöltése az indexbe
3. Az index lekérdezése

Vektorindex létrehozása

Mielőtt tartalmat ad hozzá Azure AI Keresés, létre kell hoznia egy indexet a tartalom tárolási és strukturált módjának meghatározásához.

Az indexséma a szállodai tartalom köré van rendezve. A mintaadatok magukban foglalják a fiktív szállodák vektoros és nem vektoros leírásait. A következő kód létrehozza createIndex.ts az indexsémát, beleértve a vektormezőt DescriptionVectoris.

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

Főbb tanulságok

• Az indexet mezők listájának létrehozásával határozhatja meg.

• Ez az adott index több keresési képességet is támogat:

  • Teljes szöveges keresés (searchable: true)

  • Vektorkeresés (DescriptionVector használva vectorSearchProfileName)

  • Szemantikai rangsor (semanticSearch)

  • Faceted search (mezők megjelölve facetable)

  • Geo-térbeli keresés (Location mező a következővel Edm.GeographyPoint: )

  • Szűrés és rendezés (mezők megjelölve filterablesortable)

• A vectorSearchDimensions tulajdonságnak meg kell egyeznie a beágyazási modell kimeneti méretével. Ez a gyorsútmutató 1 536 dimenziót használ a text-embedding-ada-002 modellhez való megfeleléshez.

• A vectorSearch konfiguráció a legközelebbi szomszéd (ANN) algoritmust határozza meg. A támogatott algoritmusok közé tartozik a Hierarchical Navigable Small World (HNSW) és a teljes K-Legközelebbi szomszéd (KNN). További információ: Relevancia a vektorkeresésben.

Dokumentumok feltöltése az indexbe

Az újonnan létrehozott indexek üresek. Az index feltöltéséhez és kereséséhez fel kell töltenie az indexsémának megfelelő JSON-dokumentumokat.

A Azure AI Keresés a dokumentumok mind az indexelés, mind a lekérdezések kimenetei bemeneteként szolgálnak. Az egyszerűség kedvéért ez a rövid útmutató előre konfigurált vektorokkal kínál minta szállodai dokumentumokat. Éles helyzetekben a tartalmat gyakran lekérik a csatlakoztatott adatforrásokból, és indexelők használatával JSON formátumúra alakítják át.

Az alábbi kód uploadDocuments.ts dokumentumokat tölt fel a keresési szolgáltatásba.

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

A kód az Azure AI Keresés szolgáltatásban üzemeltetett adott keresőindex-szel lép kapcsolatba a SearchClient segítségével, ami a @azure/search-documents csomag által biztosított fő objektum. Ez SearchClient hozzáférést biztosít az indexműveletekhez, például:

• Adatbetöltés: uploadDocuments, mergeDocuments, deleteDocuments

• Keresési műveletek: search, , autocompletesuggest

Az index lekérdezése

A keresési fájlokban lévő lekérdezések különböző keresési mintákat mutatnak be. A példavektor-lekérdezések két sztringen alapulnak:

• Teljes szöveges keresési karakterlánc: "historic hotel walk to restaurants and shopping"

• Vektoros lekérdezési sztring: "quintessential lodging near running trails, eateries, retail" (vektorizált matematikai ábrázolásba)

A vektoros lekérdezési sztring szemantikailag hasonlít a teljes szöveges keresési sztringhez, de olyan kifejezéseket is tartalmaz, amelyek nem léteznek az indexben. A vektoros lekérdezési sztring csak kulcsszóval történő keresése nulla eredményt ad vissza. A vektorkeresés azonban a pontos kulcsszavak helyett a jelentés alapján keres releváns találatokat.

Az alábbi példák egy alapvektoros lekérdezéssel kezdődnek, és fokozatosan adnak hozzá szűrőket, kulcsszókeresést és szemantikai rerankingot.

Egyvektoros keresés

searchSingle.ts egy olyan alapforgatókönyvet mutat be, amelyben a vektoros lekérdezési sztringgel szorosan egyező dokumentumleírásokat szeretne keresni. Az VectorQuery objektum konfigurálja a vektorkeresést:

• kNearestNeighborsCount korlátozza, hogy hány eredményt ad vissza a vektorok hasonlósága alapján.
• fields megadja a keresendő vektormezőt.

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

Egyvektoros keresés szűrővel

Az Azure AI Keresés szűrők a nemvektor mezőkre vonatkoznak egy indexben. searchSingleWithFilter.ts szűri a mezőt, hogy kiszűrje azokat a Tags szállodákat, amelyek nem biztosítanak ingyenes Wi-Fi-t.

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

Egyvektoros keresés geoszűrővel

Megadhat egy földrajzi térbeli szűrőt , amely egy adott földrajzi területre korlátozza az eredményeket. searchSingleWithGeoFilter.ts földrajzi pontot (Washington D.C., hosszúsági és szélességi koordináták használatával) határoz meg, és 300 kilométeren belül ad vissza szállodákat. A filterMode tulajdonság határozza meg, hogy mikor fut a szűrő. Ebben az esetben postFilter futtatja a szűrőt a vektorkeresés után.

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

Hibrid keresés

A hibrid keresés egyetlen kérelemben egyesíti a teljes szöveges és vektoros lekérdezéseket. searchHybrid.ts Mindkét lekérdezéstípust egyszerre futtatja, majd a Kölcsönös rangsor fúzió (RRF) használatával egyesíti az eredményeket egy egységes rangsorban. Az RRF az egyes eredményhalmazok eredménysorainak inverzét használja egy egyesített rangsor létrehozásához. Figyelje meg, hogy a hibrid keresési pontszámok egységesen kisebbek, mint az egy lekérdezéses pontszámok.

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

Szemantikus hibrid keresés

searchSemanticHybrid.ts a szemantikai rangsorolást mutatja be, amely a nyelvi megértés alapján reranksálja az eredményeket.

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

Hasonlítsa össze ezeket az eredményeket az előző lekérdezés hibrid keresési eredményeivel. Szemantikai reranking nélkül a Sublime Palace Hotel az első helyen áll, mivel a Kölcsönös Rangsor Fúzió (RRF) egyesíti a szöveget és a vektorpontszámokat az egyesített eredmény létrehozásához. A szemantikus reranking után a Swirling Currents Hotel a legfelső helyre kerül.

A szemantikai rangsoroló gépi szövegértési modelleket használ annak kiértékeléséhez, hogy az egyes eredmények mennyire egyek a lekérdezés szándékának megfelelően. Swirling Currents Hotel leírása említi "walking access to shopping, dining, entertainment and the city center", amely szorosan igazodik a keresési lekérdezés "walk to restaurants and shopping". Ez a szemantikus egyezés a közeli étkezéshez és vásárláshoz emeli a Sublime Palace Hotel felett, amely nem hangsúlyozza a sétálható kényelmi elemeket a leírásában.

Főbb tanulságok

• Hibrid keresés esetén a vektoros keresést teljes szöveges kereséssel integrálhatja kulcsszavakon keresztül. A szűrők és a szemantikai rangsorolás csak a szöveges tartalomra vonatkozik, a vektorokra nem.

• A tényleges eredmények további részleteket tartalmaznak, beleértve a szemantikai feliratokat és a kiemeléseket. Ez a rövid útmutató módosítja az eredményeket az olvashatóság érdekében. A válasz teljes szerkezetének lekéréséhez a REST használatával futtassa a kérést.

Erőforrások törlése

Ha a saját előfizetésében dolgozik, érdemes befejezni egy projektet a már nem szükséges erőforrások eltávolításával. Az otthagyott futó erőforrások pénzbe kerülhetnek.

Az Azure portálon válassza a Minden erőforrás vagy Erőforráscsoportok lehetőséget a bal oldali panelen az erőforrások megkereséséhez és kezeléséhez. Az erőforrásokat egyenként törölheti, vagy törölheti az erőforráscsoportot az összes erőforrás egyidejű eltávolításához.

Ellenkező esetben futtassa a következő parancsot az ebben a rövid útmutatóban létrehozott index törléséhez.

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

Ebben a rövid útmutatóban a Azure AI Keresés REST API-k használatával hozhat létre, tölthet be és kérdezhet le egy vector-indexet.

A Azure AI Keresés vektorindex indexsémával rendelkezik, amely vektor- és nemvektormezőket határoz meg, vektorkeresési konfigurációt a beágyazási területet létrehozó algoritmusokhoz, valamint a vektormező-definíciók lekérdezéskor kiértékelt beállításaihoz. Indexek – A vektorindex létrehozása vagy frissítése (REST API) létrehozza a vektorindexet.

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Hozzon létre egy fiókot ingyenesen.

• Egy Azure AI Keresés szolgáltatás. A rövid útmutatók többségéhez használhatja az ingyenes szintet, de a nagyobb adatfájlok esetében az Alapszintű vagy magasabb szintű verziót javasoljuk.

• Visual Studio Code a REST ügyfélkiterjesztéssel.

• Git a mintaadattár klónozásához.

• A Microsoft Entra ID-vel történő kulcs nélküli hitelesítéshez használt Azure CLI.

Hozzáférés konfigurálása

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik hozzáféréssel a tartalomhoz és a műveletekhez a Azure AI Keresés. Ez a rövid útmutató a Microsoft Entra ID-t használja hitelesítéshez és szerepköralapú jogosultságkezeléshez. Szerepkörök hozzárendeléséhez tulajdonosnak vagy felhasználói hozzáférés-rendszergazdának kell lennie. Ha a szerepkörök nem megvalósíthatók, használja inkább a kulcsalapú hitelesítést .

Az ajánlott szerepköralapú hozzáférés konfigurálása:

1. Engedélyezze a szerepköralapú hozzáférést a keresési szolgáltatáshoz.

2. Rendelje hozzá a következő szerepköröket a felhasználói fiókjához.

   • Keresési szolgáltatás közreműködője

   • Keresési index adatszolgáltatója

   • Keresési index adatolvasó

Végpont lekérése

Minden Azure AI Keresés szolgáltatás rendelkezik egy endpoint, amely egy egyedi URL-cím, amely azonosítja és hálózati hozzáférést biztosít a szolgáltatáshoz. Egy későbbi szakaszban ezt a végpontot adja meg, hogy programozott módon csatlakozzon a keresési szolgáltatáshoz.

A végpont lekérése:

1. Nyissa meg a keresőszolgáltatást a Azure portálon.

2. A bal oldali panelen válassza az Áttekintés lehetőséget.

3. Jegyezze fel a végpontot, amelynek így kell kinéznie https://my-service.search.windows.net.

A környezet beállítása

1. A Git használatával klónozza a mintaadattárat.

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

2. Nyissa meg a quickstart mappát a Visual Studio Code-ban.

   cd azure-search-rest-samples/Quickstart-vectors
   code .
   

3. Ebben az-search-quickstart-vectors.resta fájlban cserélje le a helyőrző értékét @baseUrl a Get végpontban beszerzett URL-címre.

4. Ha kulcs nélküli hitelesítést szeretne a Microsoft Entra ID-vel, jelentkezzen be az Azure-fiókjába. Ha több előfizetéssel rendelkezik, válassza ki azt, amelyik a Azure AI Keresés szolgáltatást tartalmazza.

   az login
   

5. A Microsoft Entra ID kulcs nélküli hitelesítéséhez hozzon létre egy hozzáférési jogkivonatot.

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

6. Cserélje le a @token helyőrző értékét az előző lépés tokenjével.

A kód futtatása

1. A kapcsolat ### List existing indexes by nameellenőrzéséhez válassza a Kérés küldése lehetőséget.

   A válasznak egy szomszédos panelen kell megjelennie. Ha már rendelkezik meglévő indexel, azok szerepelnek a listában. Ellenkező esetben a lista üres. Ha a HTTP-kód az 200 OK, készen áll a folytatásra.

2. A fennmaradó kéréseket egymás után küldve hozzon létre egy vektorindexet, töltsön fel dokumentumokat, és futtasson különböző típusú vektorlekérdezéseket.

Kimenet

Minden lekérdezési kérelem JSON-eredményeket ad vissza. A következő példa a kérelem kimenete, amely a ### Run a single vector query vektorkeresés eredményeit jeleníti meg a hasonlósági pontszám alapján rangsorolva.

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

A kód ismertetése

Most, hogy futtatta a kódot, bontsuk le a legfontosabb lépéseket:

1. Vektorindex létrehozása
2. Dokumentumok feltöltése az indexbe
3. Az index lekérdezése

Vektorindex létrehozása

Mielőtt tartalmat ad hozzá Azure AI Keresés, létre kell hoznia egy indexet a tartalom tárolási és strukturált módjának meghatározásához. Ez a rövid útmutató meghívja az Indexek – Létrehozás (REST API) szolgáltatást, hogy létrehozhasson egy elnevezett hotels-vector-quickstart vektorindexet és annak fizikai adatstruktúráit a keresési szolgáltatásban.

Az indexséma a szállodai tartalom köré van rendezve. A mintaadatok magukban foglalják a fiktív szállodák vektoros és nem vektoros leírásait. Az alábbi részlet a kérelem kulcsstruktúráját ### Create a new index mutatja be.

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

Főbb tanulságok

• Ez az adott index több keresési képességet is támogat:

  • Teljes szöveges keresés (a searchable-re beállított mezők: true)

  • Vektorkeresés (DescriptionVector használva vectorSearchProfile)

  • Szemantikai rangsorolás (semantic konfiguráció)

  • Faceted search (facetable mezők true értékre beállítva)

  • Geo-térbeli keresés (Location mező a következővel Edm.GeographyPoint: )

  • Szűrés és rendezés (mezők, ahol a filterable és sortable értéke true)

• A dimensions tulajdonságnak meg kell egyeznie a beágyazási modell kimeneti méretével. Ez a gyorsútmutató 1 536 dimenziót használ a text-embedding-ada-002 modellhez való megfeleléshez.

• A vectorSearch szakasz a legközelebbi szomszéd (ANN) algoritmust határozza meg. A támogatott algoritmusok közé tartozik a Hierarchical Navigable Small World (HNSW) és a teljes K-Legközelebbi szomszéd (KNN). További információ: Relevancia a vektorkeresésben.

Dokumentumok feltöltése az indexbe

Az újonnan létrehozott indexek üresek. Az index feltöltéséhez és kereséséhez fel kell töltenie az indexsémának megfelelő JSON-dokumentumokat.

A Azure AI Keresés a dokumentumok mind az indexelés, mind a lekérdezések kimenetei bemeneteként szolgálnak. Az egyszerűség kedvéért ez a gyors kezdő útmutató minta szállodai dokumentumokat tartalmaz beágyazott JSON-ként. Éles helyzetekben azonban a tartalmat gyakran leküldik a csatlakoztatott adatforrásokból, és indexelők használatával JSON-vá alakítják át.

Ez a rövid útmutató meghívja a Dokumentumok – Index (REST API) alkalmazást, hogy minta szállodai dokumentumokat vegyen fel az indexbe. Az alábbi részlet a kérelem struktúráját ### Upload 7 documents mutatja be.

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

Főbb tanulságok

• A tömb minden dokumentuma value egy szállodát jelöl, és az indexsémának megfelelő mezőket tartalmaz. A @search.action paraméter meghatározza az egyes dokumentumokhoz végrehajtandó műveletet. Ez a gyors kezdési útmutató a mergeOrUpload elemet használja. Ha a dokumentum nem létezik, hozzáadja, ha pedig létezik, frissíti azt.

• A payload dokumentumai az index séma által meghatározott mezőkből állnak.

Az index lekérdezése

A mintafájl lekérdezései különböző keresési mintákat mutatnak be. A példavektor-lekérdezések két sztringen alapulnak:

• Teljes szöveges keresési karakterlánc: "historic hotel walk to restaurants and shopping"

• Vektoros lekérdezési sztring: "quintessential lodging near running trails, eateries, retail" (vektorizált matematikai ábrázolásba)

A vektoros lekérdezési sztring szemantikailag hasonlít a teljes szöveges keresési sztringhez, de olyan kifejezéseket is tartalmaz, amelyek nem léteznek az indexben. A vektoros lekérdezési sztring csak kulcsszóval történő keresése nulla eredményt ad vissza. A vektorkeresés azonban a pontos kulcsszavak helyett a jelentés alapján keres releváns találatokat.

Az alábbi példák egy alapvektoros lekérdezéssel kezdődnek, és fokozatosan adnak hozzá szűrőket, kulcsszókeresést és szemantikai rerankingot.

Egyvektoros keresés

A ### Run a single vector query kérés egy alapforgatókönyvet mutat be, amelyben a vektoros lekérdezési sztringgel szorosan egyező dokumentumleírásokat szeretne keresni. A vectorQueries tömb konfigurálja a vektorkeresést:

• k korlátozza, hogy hány eredményt ad vissza a vektorok hasonlósága alapján.
• fields megadja a keresendő vektormezőt.

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

Egyvektoros keresés szűrővel

Az Azure AI Keresés szűrők a nemvektor mezőkre vonatkoznak egy indexben. A ### Run a vector query with a filter kérelem szűri a mezőt, hogy kiszűrje azokat a Tags szállodákat, amelyek nem biztosítanak ingyenes Wi-Fi-t.

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

Egyvektoros keresés geoszűrővel

Megadhat egy földrajzi térbeli szűrőt , amely egy adott földrajzi területre korlátozza az eredményeket. A ### Run a vector query with a geo filter kérelem egy földrajzi pontot (Washington D.C., hosszúsági és szélességi koordináták használatával) határoz meg, és 300 kilométeren belül ad vissza szállodákat. A vectorFilterMode paraméter határozza meg, hogy mikor fut a szűrő. Ebben az esetben postFilter futtatja a szűrőt a vektorkeresés után.

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

Hibrid keresés

A hibrid keresés egyetlen kérelemben egyesíti a teljes szöveges és vektoros lekérdezéseket. A ### Run a hybrid query kérelem egyszerre futtatja mindkét lekérdezéstípust, majd a Kölcsönös rangsor fúzió (RRF) használatával egyesíti az eredményeket egy egységes rangsorban. Az RRF az egyes eredményhalmazok eredménysorainak inverzét használja egy egyesített rangsor létrehozásához. Figyelje meg, hogy a hibrid keresési pontszámok egységesen kisebbek, mint az egy lekérdezéses pontszámok.

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

Szemantikus hibrid keresés

A ### Run a hybrid query with semantic reranking kérés bemutatja a szemantikai rangsorolást, amely a nyelvi megértés alapján reranksálja az eredményeket.

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

Hasonlítsa össze ezeket az eredményeket az előző lekérdezés hibrid keresési eredményeivel. Szemantikai reranking nélkül a Sublime Palace Hotel az első helyen áll, mivel a Kölcsönös Rangsor Fúzió (RRF) egyesíti a szöveget és a vektorpontszámokat az egyesített eredmény létrehozásához. A szemantikus reranking után a Swirling Currents Hotel a legfelső helyre kerül.

A szemantikai rangsoroló gépi szövegértési modelleket használ annak kiértékeléséhez, hogy az egyes eredmények mennyire egyek a lekérdezés szándékának megfelelően. Swirling Currents Hotel leírása említi "walking access to shopping, dining, entertainment and the city center", amely szorosan igazodik a keresési lekérdezés "walk to restaurants and shopping". Ez a szemantikus egyezés a közeli étkezéshez és vásárláshoz emeli a Sublime Palace Hotel felett, amely nem hangsúlyozza a sétálható kényelmi elemeket a leírásában.

Főbb tanulságok

• Hibrid keresés esetén a vektoros keresést teljes szöveges kereséssel integrálhatja kulcsszavakon keresztül. A szűrők és a szemantikai rangsorolás csak a szöveges tartalomra vonatkozik, a vektorokra nem.

Erőforrások törlése

Ha a saját előfizetésében dolgozik, érdemes befejezni egy projektet a már nem szükséges erőforrások eltávolításával. Az otthagyott futó erőforrások pénzbe kerülhetnek.

Az Azure portálon válassza a Minden erőforrás vagy Erőforráscsoportok lehetőséget a bal oldali panelen az erőforrások megkereséséhez és kezeléséhez. Az erőforrásokat egyenként törölheti, vagy törölheti az erőforráscsoportot az összes erőforrás egyidejű eltávolításához.

Ellenkező esetben elküldheti a ### Delete an index kérést annak az indexnek a törlésére, amelyet ebben a gyorsútmutatóban hozott létre.