Hızlı Başlangıç: Vektör araması

Not

Azure Yapay Zeka Arama Azure portalı, REST API'leri ve Azure SDK’ları aracılığıyla kullanılabilir. Ayrıca kuruluş içeriğini Microsoft Foundry portalındaki aracılar için yeniden kullanılabilir, izin kullanan bilgi bankalarına dönüştüren yönetilen bilgi katmanı Foundry IQ'yu temel alır.

Not

Vektör arama iş akışlarına model eklemek için Azure Yapay Zeka Arama OpenAI'den , text-embedding-ada-002ve text-embedding-3-small Azure desteklertext-embedding-3-large. Sohbet tamamlama modellerini kullanan yapay zekayla zenginleştirilmiş iş akışları için bkz. GPT-4 aile modellerinin kullanımdan kaldırma durumunu denetlemek için model kullanımdan kaldırma zamanlamaları .

Bu hızlı başlangıçta, .NET için Azure Yapay Zeka Arama istemci kitaplığını kullanarak vector dizini oluşturacak, yükleyecek ve sorgulaacaksınız. .NET istemci kitaplığı, dizin işlemleri için REST API'leri üzerinde bir soyutlama sağlar.

Azure Yapay Zeka Arama vektör dizininde vektör ve nonvector alanlarını tanımlayan bir dizin şeması, ekleme alanını oluşturan algoritmalar için vektör arama yapılandırması ve sorgu zamanında değerlendirilen vektör alanı tanımlarındaki ayarlar bulunur. Dizinler - Oluştur veya Güncelleştir (REST API), vektör dizinini oluşturur.

Ipucu

• Hemen başlamak ister misiniz? GitHub source kodunu indirin.
• Bu hızlı başlangıç vektörleştirme adımını atlar ve satır içi eklemeler sağlar. Kendi içeriğiniz üzerinde tümleşik vektörleştirme için Verileri içeri aktarma sihirbazını deneyin.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz bir hesap oluşturun.

• Azure Yapay Zeka Arama hizmeti. Bu hızlı başlangıcın çoğu için Ücretsiz katmanını kullanabilirsiniz, ancak daha büyük veri dosyaları için Temel veya üzerini öneririz.

• .NET 8 veya üzeri.

• Git'i kullanarak örnek depoyu kopyalayın.

• Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure CLI.

Erişimi yapılandırma

Başlamadan önce, Azure Yapay Zeka Arama'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

   • Arama Hizmeti Katkıda Bulunanı

   • Arama Dizini Veri Katkıcısı

   • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure Yapay Zeka Arama hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

1. Azure portalında arama hizmetinize gidin.

2. Sol bölmeden Genel Bakış'ı seçin.

3. Uç noktayı not alın ve şu şekilde görünmelidir: https://my-service.search.windows.net.

Ortamı ayarlama

1. Örnek depoyu kopyalamak için Git'i kullanın.

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

2. Hızlı başlangıç klasörüne gidin.

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

3. VectorSearchCreatePopulateIndex/appsettings.json içinde, Endpoint yer tutucu değerini Uç noktayı al bölümünden aldığınız URL ile değiştirin.

4. için VectorSearchExamples/appsettings.jsonönceki adımı yineleyin.

5. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama hizmetinizi içeren aboneliği seçin.

   az login
   

Kodu çalıştırma

1. Dizini oluşturmak ve doldurmak için ilk projeyi çalıştırın.

   cd VectorSearchCreatePopulateIndex
   dotnet run
   

2. VectorSearchExamples/Program.cs dosyasının içinde çalıştırmak istediğiniz sorgu yöntemlerinin yorum satırını kaldırın.

3. Bu sorguları dizinde yürütmek için ikinci projeyi çalıştırın.

   cd ..\VectorSearchExamples
   dotnet run
   

Çıkış

İlk projenin çıktısı dizin oluşturma onayı ve başarılı belge yüklemelerini içerir.

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

İkinci projenin çıktısı, etkinleştirilen her sorgu yöntemi için arama sonuçlarını gösterir. Aşağıdaki örnekte tek vektör arama sonuçları gösterilmektedir.

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

Kodu anlama

Not

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

1. Vektör dizini oluşturma
2. Belgeleri dizine yükleme
3. Dizini sorgulama

Vektör dizini oluşturma

Azure Yapay Zeka Arama içerik eklemeden önce, içeriğin nasıl depolandığını ve yapılandırıldığını tanımlamak için bir dizin oluşturmanız gerekir.

Dizin şeması otel içeriğine göre düzenlenmiştir. Örnek veriler, kurgusal otellerin vektör ve nonvector açıklamalarından oluşur. içindeki aşağıdaki kod VectorSearchCreatePopulateIndex/Program.cs , vektör alanı DescriptionVectorda dahil olmak üzere dizin şemasını oluşturur.

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

Önemli çıkarımlar:

• Alan listesi oluşturarak dizin tanımlarsınız.

• Bu özel dizin birden çok arama özelliklerini destekler:

  • Tam metin arama (SearchableField)

  • Vektör araması (VectorSearchField)

  • Anlam sıralaması (SemanticSearch)

  • Fasetsel arama (IsFacetable ile işaretlenmiş alanlar)

  • Coğrafi uzamsal arama (Location ile SearchFieldDataType.GeographyPointalan)

  • Filtreleme ve sıralama (ve IsFilterableile IsSortable işaretlenmiş alanlar)

• İçindeki VectorSearchField ikinci parametre vectorSearchDimensions 'yi belirtir ve bu, gömme modelinizin çıkış boyutuyla eşleşmelidir. Bu hızlı başlangıçta text-embedding-ada-002 modeliyle eşleşmesi için 1,536 boyut kullanılır.

• Yapılandırma, VectorSearch Yaklaşık En Yakın Komşu (ANN) algoritmasını tanımlar. Desteklenen algoritmalar Hiyerarşik Gezinilebilir Küçük Dünya (HNSW) ve kapsamlı K-En Yakın Komşu (KNN) içerir. Daha fazla bilgi için bkz. Vektör aramasında ilgi.

Belgeleri dizine yükleme

Yeni oluşturulan dizinler boş. Bir dizini doldurmak ve aranabilir hale getirmek için dizin şemasına uygun JSON belgelerini karşıya yüklemeniz gerekir.

Azure Yapay Zeka Arama'de belgeler hem dizin oluşturma için giriş hem de sorgu çıkışları görevi görür. Kolaylık olması için, bu hızlı başlangıçta önceden derlenmiş vektörlerle örnek otel belgeleri sağlanmaktadır. Üretim senaryolarında içerik genellikle bağlı veri kaynaklarından alınır ve dizin oluşturucular kullanılarak JSON'a dönüştürülür.

Aşağıdaki kod, HotelData.json konumundan belgeleri arama hizmetinize yükler.

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

Kodunuz, SearchClient paketi tarafından sağlanan ana nesne olan Azure.Search.Documents aracılığıyla Azure Yapay Zeka Arama hizmetinizde barındırılan belirli bir arama diziniyle etkileşim kurar. SearchClient dizin işlemlerine erişim sağlar, örneğin:

• Veri alımı: UploadDocuments(), MergeDocuments(), DeleteDocuments()

• Arama işlemleri: Search(), Autocomplete(), Suggest()

Dizini sorgulama

içindeki VectorSearchExamples sorgular farklı arama desenlerini gösterir. Örnek vektör sorguları iki dizeyi temel alır:

• Tam metin arama dizesi: "historic hotel walk to restaurants and shopping"

• Vektör sorgu dizesi: "quintessential lodging near running trails, eateries, retail" (matematiksel bir gösterime vektörleştirilmiş)

Vektör sorgu dizesi, tam metin arama dizesine benzer, ancak dizinde var olmayan terimler içerir. Vektör sorgu dizesi için yalnızca anahtar sözcük araması sıfır sonuç döndürür. Ancak vektör araması, tam anahtar sözcükler yerine anlam temelinde ilgili eşleşmeleri bulur.

Aşağıdaki örnekler temel bir vektör sorgusuyla başlar ve aşamalı olarak filtreler, anahtar sözcük araması ve anlamsal yeniden sıralama ekler.

Tek vektör arama

yöntemi, SearchSingleVector vektör sorgu dizesiyle yakından eşleşen belge açıklamalarını bulmak istediğiniz temel bir senaryoyu gösterir. VectorizedQuery vektör aramasını yapılandırıyor:

• KNearestNeighborsCount vektör benzerliğine göre kaç sonuç döndürülür sınırlar.
• Fields aranacak vektör alanını belirtir.

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

Filtre içeren tek vektörlü arama

Azure AI Arama'da, filtreler dizindeki vektör olmayan alanlara uygulanır. SearchSingleVectorWithFilter yöntemi, ücretsiz Wi-Fi sağlamayan otelleri Tags alanında filtreleyerek elemektedir.

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

Coğrafi filtre ile tek vektör araması

Sonuçları belirli bir coğrafi alanla sınırlamak için coğrafi uzamsal filtre belirtebilirsiniz. SingleSearchWithGeoFilter yöntemi bir coğrafi nokta (boylam ve enlem koordinatlarını kullanarak Washington D.C.) belirtir ve 300 kilometre içindeki otelleri döndürür. Varsayılan olarak, filtreler vektör aramasının ardından çalışır.

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

Karma arama

Karma arama , tam metin ve vektör sorgularını tek bir istekte birleştirir. SearchHybridVectorAndText yöntemi her iki sorgu türünü de eşzamanlı olarak çalıştırır ve ardından sonuçları birleşik bir derecelendirmede birleştirmek için Reciprocal Rank Fusion (RRF) kullanır. RRF, birleştirilmiş bir derecelendirme oluşturmak için her sonuç kümesindeki sonuç derecelendirmelerinin tersini kullanır. Karma arama puanlarının tek sorgulu puanlardan eşit olarak daha küçük olduğuna dikkat edin.

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

Anlamsal hibrit arama

SearchHybridVectorAndSemantic yöntemi, sonuçları dil anlama temelinde yeniden oluşturan anlam sıralamasını gösterir.

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

Bu sonuçları önceki sorgudaki karma arama sonuçlarıyla karşılaştırın. Anlamsal yeniden boyutlandırma olmadan Sublime Palace Hotel, Reciprocal Rank Fusion (RRF) metin ve vektör puanlarını birleştirerek birleştirilmiş bir sonuç elde ettiğinden birinci sırada yer alır. Anlamsal yeniden sıralamanın ardından Swirling Currents Hotel zirveye çıkar.

Anlam dereceleyicisi, her sonucun sorgunun amacıyla ne kadar iyi eşleştiğini değerlendirmek için makine kavrama modellerini kullanır. Swirling Currents Hotel'in açıklamasında, arama sorgusunun "walking access to shopping, dining, entertainment and the city center" ile yakından örtüşen "walk to restaurants and shopping" yer alır. Yakındaki yemek ve alışveriş için anlam eşleşmesi, açıklamasında yürünebilir olanakları vurgulamayan Sublime Palace Hotel'in daha üstüne çıkarır.

Önemli çıkarımlar:

• Karma aramada, vektör arama ile anahtar sözcükler üzerinde tam metin arama tümleştirebilirsiniz. Filtreler ve anlam derecelendirmesi vektörlere değil yalnızca metin içeriğine uygulanır.

• Gerçek sonuçlar semantik açıklamalı alt yazılar ve vurgular da dahil olmak üzere daha fazla ayrıntı içerir. Bu hızlı başlangıç kılavuzunda okunabilirliği artırmak için sonuçlar değiştirilir. Yanıtın tam yapısını almak için REST kullanarak isteği çalıştırın.

Kaynakları temizleme

Kendi aboneliğinizde çalışırken, artık ihtiyacınız olmayan kaynakları kaldırarak bir projeyi tamamlamak iyi bir fikirdir. Çalışır durumda kalan kaynaklar size pahalıya mal olabilir.

Kaynakları bulmak ve yönetmek için Azure portalında Tüm kaynaklar veya Kaynak grupları seçin. Kaynakları tek tek silebilir veya tüm kaynakları aynı anda kaldırmak için kaynak grubunu silebilirsiniz.

Bu hızlı başlangıçta Java için Azure Yapay Zeka Arama istemci kitaplığını kullanarak bir vector dizini oluşturacak, yükleyecek ve sorgulaacaksınız. Java istemci kitaplığı, dizin işlemleri için REST API'leri üzerinde bir soyutlama sağlar.

Azure Yapay Zeka Arama vektör dizininde vektör ve nonvector alanlarını tanımlayan bir dizin şeması, ekleme alanını oluşturan algoritmalar için vektör arama yapılandırması ve sorgu zamanında değerlendirilen vektör alanı tanımlarındaki ayarlar bulunur. Dizinler - Oluştur veya Güncelleştir (REST API), vektör dizinini oluşturur.

Ipucu

• Hemen başlamak ister misiniz? GitHub source kodunu indirin.
• Bu hızlı başlangıç vektörleştirme adımını atlar ve satır içi eklemeler sağlar. Kendi içeriğiniz üzerinde tümleşik vektörleştirme için Verileri içeri aktarma sihirbazını deneyin.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz bir hesap oluşturun.

• Azure Yapay Zeka Arama hizmeti. Bu hızlı başlangıcın çoğu için Ücretsiz katmanını kullanabilirsiniz, ancak daha büyük veri dosyaları için Temel veya üzerini öneririz.

• Java 21 (LTS) ve Maven.

• Git'i kullanarak örnek depoyu kopyalayın.

• Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure CLI.

Erişimi yapılandırma

Başlamadan önce, Azure Yapay Zeka Arama'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

   • Arama Hizmeti Katkıda Bulunanı

   • Arama Dizini Veri Katkıcısı

   • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure Yapay Zeka Arama hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

1. Azure portalında arama hizmetinize gidin.

2. Sol bölmeden Genel Bakış'ı seçin.

3. Uç noktayı not alın ve şu şekilde görünmelidir: https://my-service.search.windows.net.

Ortamı ayarlama

1. Örnek depoyu kopyalamak için Git'i kullanın.

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

2. Hızlı başlangıç klasörüne gidin.

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

3. src/main/resources/application.properties içinde, azure.search.endpoint yer tutucu değerini Uç noktayı al bölümünden aldığınız URL ile değiştirin.

4. Bağımlılıkları yükleyin.

   mvn clean dependency:copy-dependencies
   

   Derleme tamamlandığında proje dizininde bir target/dependency klasör görmeniz gerekir.

5. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama hizmetinizi içeren aboneliği seçin.

   az login
   

Kodu çalıştırma

1. Vektör dizini oluşturun.

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

2. Önceden derlenmiş eklemeler içeren belgeleri yükleyin.

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

3. Vektör arama sorgusu çalıştırın.

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

4. (İsteğe bağlı) Ek sorgu varyasyonları çalıştırın.

   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"
   

Çıkış

CreateIndex.java çıktısı dizin adını ve onayını gösterir.

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

Çıktı UploadDocuments.java dizine alınan her belge için başarı durumunu gösterir.

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.

çıktısı SearchSingle.java , vektör arama sonuçlarını benzerlik puanına göre sıralanmış olarak gösterir.

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

Kodu anlama

Not

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

1. Vektör dizini oluşturma
2. Belgeleri dizine yükleme
3. Dizini sorgulama

Vektör dizini oluşturma

Azure Yapay Zeka Arama içerik eklemeden önce, içeriğin nasıl depolandığını ve yapılandırıldığını tanımlamak için bir dizin oluşturmanız gerekir.

Dizin şeması otel içeriğine göre düzenlenmiştir. Örnek veriler, kurgusal otellerin vektör ve nonvector açıklamalarından oluşur. içindeki aşağıdaki kod CreateIndex.java , vektör alanı DescriptionVectorda dahil olmak üzere dizin şemasını oluşturur.

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

Önemli çıkarımlar:

• Alan listesi oluşturarak dizin tanımlarsınız.

• Bu özel dizin birden çok arama özelliklerini destekler:

  • Tam metin arama (setSearchable)

  • Vektör araması (DescriptionVector ile setVectorSearchProfileName)

  • Anlam sıralaması (SemanticConfiguration)

  • Fasetsel arama (setFacetable ile işaretlenmiş alanlar)

  • Coğrafi uzamsal arama (Location ile SearchFieldDataType.GEOGRAPHY_POINTalan)

  • Filtreleme ve sıralama (ve setFilterableile setSortable işaretlenmiş alanlar)

• Değer, setVectorSearchDimensions() ekleme modelinizin çıkış boyutuyla eşleşmelidir. Bu hızlı başlangıçta text-embedding-ada-002 modeliyle eşleşmesi için 1,536 boyut kullanılır.

• Yapılandırma, VectorSearch Yaklaşık En Yakın Komşu (ANN) algoritmasını tanımlar. Desteklenen algoritmalar Hiyerarşik Gezinilebilir Küçük Dünya (HNSW) ve kapsamlı K-En Yakın Komşu (KNN) içerir. Daha fazla bilgi için bkz. Vektör aramasında ilgi.

Belgeleri dizine yükleme

Yeni oluşturulan dizinler boş. Bir dizini doldurmak ve aranabilir hale getirmek için dizin şemasına uygun JSON belgelerini karşıya yüklemeniz gerekir.

Azure Yapay Zeka Arama'de belgeler hem dizin oluşturma için giriş hem de sorgu çıkışları görevi görür. Kolaylık olması için, bu hızlı başlangıçta önceden derlenmiş vektörlerle örnek otel belgeleri sağlanmaktadır. Üretim senaryolarında içerik genellikle bağlı veri kaynaklarından alınır ve dizin oluşturucular kullanılarak JSON'a dönüştürülür.

içindeki aşağıdaki kod UploadDocuments.java , belgeleri arama hizmetinize yükler.

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

Kodunuz, SearchClient paketi tarafından sağlanan ana nesne olan azure-search-documents aracılığıyla Azure Yapay Zeka Arama hizmetinizde barındırılan belirli bir arama diziniyle etkileşim kurar. aşağıdaki SearchClient gibi işlemlere erişim sağlar:

• Veri alımı: uploadDocuments, mergeDocuments, deleteDocuments

• Arama işlemleri: search, autocomplete, suggest

Dizini sorgulama

Arama dosyalarındaki sorgular farklı arama desenleri gösterir. Örnek vektör sorguları iki dizeyi temel alır:

• Tam metin arama dizesi: "historic hotel walk to restaurants and shopping"

• Vektör sorgu dizesi: "quintessential lodging near running trails, eateries, retail" (matematiksel bir gösterime vektörleştirilmiş)

Vektör sorgu dizesi, tam metin arama dizesine benzer, ancak dizinde var olmayan terimler içerir. Vektör sorgu dizesi için yalnızca anahtar sözcük araması sıfır sonuç döndürür. Ancak vektör araması, tam anahtar sözcükler yerine anlam temelinde ilgili eşleşmeleri bulur.

Aşağıdaki örnekler temel bir vektör sorgusuyla başlar ve aşamalı olarak filtreler, anahtar sözcük araması ve anlamsal yeniden sıralama ekler.

Tek vektör arama

SearchSingle.java vektör sorgu dizesiyle yakından eşleşen belge açıklamalarını bulmak istediğiniz temel bir senaryoyu gösterir. VectorizedQuery vektör aramasını yapılandırıyor:

• setKNearestNeighborsCount() vektör benzerliğine göre kaç sonuç döndürülür sınırlar.
• setFields() aranacak vektör alanını belirtir.

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

Filtre içeren tek vektörlü arama

Azure AI Arama'da, filtreler dizindeki vektör olmayan alanlara uygulanır. SearchSingleWithFilter.java alanında ücretsiz Wi-Fi sağlamayan otelleri filtrelemek için filtreler uygulayın.

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

Coğrafi filtre ile tek vektör araması

Sonuçları belirli bir coğrafi alanla sınırlamak için coğrafi uzamsal filtre belirtebilirsiniz. SearchSingleWithGeoFilter.java bir coğrafi nokta (boylam ve enlem koordinatlarını kullanarak Washington D.C.) belirtir ve 300 kilometre içindeki otelleri döndürür. setFilterMode üzerinde çağrılan VectorSearchOptions yöntemi, filtrenin ne zaman çalıştırılacağını belirler. Bu durumda, POST_FILTER vektör aramasının ardından filtreyi çalıştırır.

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

Karma arama

Karma arama , tam metin ve vektör sorgularını tek bir istekte birleştirir. SearchHybrid.java her iki sorgu türünü de eşzamanlı olarak çalıştırır ve ardından sonuçları birleşik bir derecelendirmede birleştirmek için Karşılıklı Rank Fusion 'ı (RRF) kullanır. RRF, birleştirilmiş bir derecelendirme oluşturmak için her sonuç kümesindeki sonuç derecelendirmelerinin tersini kullanır. Karma arama puanlarının tek sorgulu puanlardan eşit olarak daha küçük olduğuna dikkat edin.

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

Anlamsal hibrit arama

SearchSemanticHybrid.java sonuçları dil anlama temelinde yeniden oluşturan anlamsal derecelendirmeyi gösterir.

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

Bu sonuçları önceki sorgudaki karma arama sonuçlarıyla karşılaştırın. Anlamsal yeniden boyutlandırma olmadan Sublime Palace Hotel, Reciprocal Rank Fusion (RRF) metin ve vektör puanlarını birleştirerek birleştirilmiş bir sonuç elde ettiğinden birinci sırada yer alır. Anlamsal yeniden sıralamanın ardından Swirling Currents Hotel zirveye çıkar.

Anlam dereceleyicisi, her sonucun sorgunun amacıyla ne kadar iyi eşleştiğini değerlendirmek için makine kavrama modellerini kullanır. Swirling Currents Hotel'in açıklamasında, arama sorgusunun "walking access to shopping, dining, entertainment and the city center" ile yakından örtüşen "walk to restaurants and shopping" yer alır. Yakındaki yemek ve alışveriş için anlam eşleşmesi, açıklamasında yürünebilir olanakları vurgulamayan Sublime Palace Hotel'in daha üstüne çıkarır.

Önemli çıkarımlar:

• Karma aramada, vektör arama ile anahtar sözcükler üzerinde tam metin arama tümleştirebilirsiniz. Filtreler ve anlam derecelendirmesi vektörlere değil yalnızca metin içeriğine uygulanır.

• Gerçek sonuçlar semantik açıklamalı alt yazılar ve vurgular da dahil olmak üzere daha fazla ayrıntı içerir. Bu hızlı başlangıç kılavuzunda okunabilirliği artırmak için sonuçlar değiştirilir. Yanıtın tam yapısını almak için REST kullanarak isteği çalıştırın.

Kaynakları temizleme

Kendi aboneliğinizde çalışırken, artık ihtiyacınız olmayan kaynakları kaldırarak bir projeyi tamamlamak iyi bir fikirdir. Çalışır durumda kalan kaynaklar size pahalıya mal olabilir.

Kaynakları bulmak ve yönetmek için Azure portalında Tüm kaynaklar veya Kaynak grupları seçin. Kaynakları tek tek silebilir veya tüm kaynakları aynı anda kaldırmak için kaynak grubunu silebilirsiniz.

Aksi takdirde, bu hızlı başlangıçta oluşturduğunuz dizini silmek için aşağıdaki komutu çalıştırın.

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

Bu hızlı başlangıçta, JavaScript için Azure Yapay Zeka Arama istemci kitaplığını kullanarak bir vektör dizini oluşturacak, yükleyecek ve sorgulayacaksınız. JavaScript istemci kitaplığı, dizin işlemleri için REST API'leri üzerinde bir soyutlama sağlar.

Azure Yapay Zeka Arama vektör dizininde vektör ve nonvector alanlarını tanımlayan bir dizin şeması, ekleme alanını oluşturan algoritmalar için vektör arama yapılandırması ve sorgu zamanında değerlendirilen vektör alanı tanımlarındaki ayarlar bulunur. Dizinler - Oluştur veya Güncelleştir (REST API), vektör dizinini oluşturur.

Ipucu

• Hemen başlamak ister misiniz? GitHub source kodunu indirin.
• Bu hızlı başlangıç vektörleştirme adımını atlar ve satır içi eklemeler sağlar. Kendi içeriğiniz üzerinde tümleşik vektörleştirme için Verileri içeri aktarma sihirbazını deneyin.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz bir hesap oluşturun.

• Azure Yapay Zeka Arama hizmeti. Bu hızlı başlangıcın çoğu için Ücretsiz katmanını kullanabilirsiniz, ancak daha büyük veri dosyaları için Temel veya üzerini öneririz.

• Node.js 20 LTS veya üzeri.

• Git'i kullanarak örnek depoyu kopyalayın.

• Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure CLI.

Erişimi yapılandırma

Başlamadan önce, Azure Yapay Zeka Arama'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

   • Arama Hizmeti Katkıda Bulunanı

   • Arama Dizini Veri Katkıcısı

   • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure Yapay Zeka Arama hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

1. Azure portalında arama hizmetinize gidin.

2. Sol bölmeden Genel Bakış'ı seçin.

3. Uç noktayı not alın ve şu şekilde görünmelidir: https://my-service.search.windows.net.

Ortamı ayarlama

1. Örnek depoyu kopyalamak için Git'i kullanın.

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

2. Hızlı başlangıç klasörüne gidin.

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

3. sample.env içinde, AZURE_SEARCH_ENDPOINT yer tutucu değerini Uç noktayı al bölümünden aldığınız URL ile değiştirin.

4. olarak sample.envyeniden adlandırın.env.

   mv sample.env .env
   

5. Bağımlılıkları yükleyin.

   npm install
   

   Yükleme tamamlandığında proje dizininde bir node_modules klasör görmeniz gerekir.

6. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama hizmetinizi içeren aboneliği seçin.

   az login
   

Kodu çalıştırma

1. Vektör dizini oluşturun.

   node -r dotenv/config src/createIndex.js
   

2. Önceden derlenmiş eklemeler içeren belgeleri yükleyin.

   node -r dotenv/config src/uploadDocuments.js
   

3. Vektör arama sorgusu çalıştırın.

   node -r dotenv/config src/searchSingle.js
   

4. (İsteğe bağlı) Ek sorgu varyasyonları çalıştırın.

   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
   

Çıkış

createIndex.js çıktısı dizin adını ve onayını gösterir.

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

Çıktı uploadDocuments.js dizine alınan her belge için başarı durumunu gösterir.

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.

çıktısı searchSingle.js , vektör arama sonuçlarını benzerlik puanına göre sıralanmış olarak gösterir.

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

Kodu anlama

Not

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

1. Vektör dizini oluşturma
2. Belgeleri dizine yükleme
3. Dizini sorgulama

Vektör dizini oluşturma

Azure Yapay Zeka Arama içerik eklemeden önce, içeriğin nasıl depolandığını ve yapılandırıldığını tanımlamak için bir dizin oluşturmanız gerekir.

Dizin şeması otel içeriğine göre düzenlenmiştir. Örnek veriler, kurgusal otellerin vektör ve nonvector açıklamalarından oluşur. içindeki aşağıdaki kod createIndex.js , vektör alanı DescriptionVectorda dahil olmak üzere dizin şemasını oluşturur.

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

Önemli çıkarımlar:

• Alan listesi oluşturarak dizin tanımlarsınız.

• Bu özel dizin birden çok arama özelliklerini destekler:

  • Tam metin arama (searchable: true)

  • Vektör araması (DescriptionVector ile vectorSearchProfileName)

  • Anlam sıralaması (semanticSearch)

  • Fasetsel arama (facetable ile işaretlenmiş alanlar)

  • Coğrafi uzamsal arama (Location ile Edm.GeographyPointalan)

  • Filtreleme ve sıralama (ve filterableile sortable işaretlenmiş alanlar)

• özelliği, vectorSearchDimensions ekleme modelinizin çıkış boyutuyla eşleşmelidir. Bu hızlı başlangıçta text-embedding-ada-002 modeliyle eşleşmesi için 1,536 boyut kullanılır.

• Yapılandırma, vectorSearch Yaklaşık En Yakın Komşu (ANN) algoritmasını tanımlar. Desteklenen algoritmalar Hiyerarşik Gezinilebilir Küçük Dünya (HNSW) ve kapsamlı K-En Yakın Komşu (KNN) içerir. Daha fazla bilgi için bkz. Vektör aramasında ilgi.

Belgeleri dizine yükleme

Yeni oluşturulan dizinler boş. Bir dizini doldurmak ve aranabilir hale getirmek için dizin şemasına uygun JSON belgelerini karşıya yüklemeniz gerekir.

Azure Yapay Zeka Arama'de belgeler hem dizin oluşturma için giriş hem de sorgu çıkışları görevi görür. Kolaylık olması için, bu hızlı başlangıçta önceden derlenmiş vektörlerle örnek otel belgeleri sağlanmaktadır. Üretim senaryolarında içerik genellikle bağlı veri kaynaklarından alınır ve dizin oluşturucular kullanılarak JSON'a dönüştürülür.

içindeki aşağıdaki kod uploadDocuments.js , belgeleri arama hizmetinize yükler.

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

Kodunuz, SearchClient paketi tarafından sağlanan ana nesne olan @azure/search-documents aracılığıyla Azure Yapay Zeka Arama hizmetinizde barındırılan belirli bir arama diziniyle etkileşim kurar. SearchClient dizin işlemlerine erişim sağlar, örneğin:

• Veri alımı: uploadDocuments, mergeDocuments, deleteDocuments

• Arama işlemleri: search, autocomplete, suggest

Dizini sorgulama

Arama dosyalarındaki sorgular farklı arama desenleri gösterir. Örnek vektör sorguları iki dizeyi temel alır:

• Tam metin arama dizesi: "historic hotel walk to restaurants and shopping"

• Vektör sorgu dizesi: "quintessential lodging near running trails, eateries, retail" (matematiksel bir gösterime vektörleştirilmiş)

Vektör sorgu dizesi, tam metin arama dizesine benzer, ancak dizinde var olmayan terimler içerir. Vektör sorgu dizesi için yalnızca anahtar sözcük araması sıfır sonuç döndürür. Ancak vektör araması, tam anahtar sözcükler yerine anlam temelinde ilgili eşleşmeleri bulur.

Aşağıdaki örnekler temel bir vektör sorgusuyla başlar ve aşamalı olarak filtreler, anahtar sözcük araması ve anlamsal yeniden sıralama ekler.

Tek vektör arama

searchSingle.js vektör sorgu dizesiyle yakından eşleşen belge açıklamalarını bulmak istediğiniz temel bir senaryoyu gösterir. vectorQuery nesnesi vektör aramasını yapılandırıyor:

• kNearestNeighborsCount vektör benzerliğine göre kaç sonuç döndürülür sınırlar.
• fields aranacak vektör alanını belirtir.

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

Filtre içeren tek vektörlü arama

Azure AI Arama'da, filtreler dizindeki vektör olmayan alanlara uygulanır. searchSingleWithFilter.js alanında ücretsiz Wi-Fi sağlamayan otelleri filtrelemek için filtreler uygulayın.

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

Coğrafi filtre ile tek vektör araması

Sonuçları belirli bir coğrafi alanla sınırlamak için coğrafi uzamsal filtre belirtebilirsiniz. searchSingleWithGeoFilter.js bir coğrafi nokta (boylam ve enlem koordinatlarını kullanarak Washington D.C.) belirtir ve 300 kilometre içindeki otelleri döndürür. filterMode özelliği, filtrenin ne zaman çalıştırileceğini belirler. Bu durumda, postFilter vektör aramasının ardından filtreyi çalıştırır.

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

Karma arama

Karma arama , tam metin ve vektör sorgularını tek bir istekte birleştirir. searchHybrid.js her iki sorgu türünü de eşzamanlı olarak çalıştırır ve ardından sonuçları birleşik bir derecelendirmede birleştirmek için Karşılıklı Rank Fusion 'ı (RRF) kullanır. RRF, birleştirilmiş bir derecelendirme oluşturmak için her sonuç kümesindeki sonuç derecelendirmelerinin tersini kullanır. Karma arama puanlarının tek sorgulu puanlardan eşit olarak daha küçük olduğuna dikkat edin.

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

Anlamsal hibrit arama

searchSemanticHybrid.js sonuçları dil anlama temelinde yeniden oluşturan anlamsal derecelendirmeyi gösterir.

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

Bu sonuçları önceki sorgudaki karma arama sonuçlarıyla karşılaştırın. Anlamsal yeniden boyutlandırma olmadan Sublime Palace Hotel, Reciprocal Rank Fusion (RRF) metin ve vektör puanlarını birleştirerek birleştirilmiş bir sonuç elde ettiğinden birinci sırada yer alır. Anlamsal yeniden sıralamanın ardından Swirling Currents Hotel zirveye çıkar.

Anlam dereceleyicisi, her sonucun sorgunun amacıyla ne kadar iyi eşleştiğini değerlendirmek için makine kavrama modellerini kullanır. Swirling Currents Hotel'in açıklamasında, arama sorgusunun "walking access to shopping, dining, entertainment and the city center" ile yakından örtüşen "walk to restaurants and shopping" yer alır. Yakındaki yemek ve alışveriş için anlam eşleşmesi, açıklamasında yürünebilir olanakları vurgulamayan Sublime Palace Hotel'in daha üstüne çıkarır.

Önemli çıkarımlar:

• Karma aramada, vektör arama ile anahtar sözcükler üzerinde tam metin arama tümleştirebilirsiniz. Filtreler ve anlam derecelendirmesi vektörlere değil yalnızca metin içeriğine uygulanır.

• Gerçek sonuçlar semantik açıklamalı alt yazılar ve vurgular da dahil olmak üzere daha fazla ayrıntı içerir. Bu hızlı başlangıç kılavuzunda okunabilirliği artırmak için sonuçlar değiştirilir. Yanıtın tam yapısını almak için REST kullanarak isteği çalıştırın.

Kaynakları temizleme

Kendi aboneliğinizde çalışırken, artık ihtiyacınız olmayan kaynakları kaldırarak bir projeyi tamamlamak iyi bir fikirdir. Çalışır durumda kalan kaynaklar size pahalıya mal olabilir.

Kaynakları bulmak ve yönetmek için Azure portalında Tüm kaynaklar veya Kaynak grupları seçin. Kaynakları tek tek silebilir veya tüm kaynakları aynı anda kaldırmak için kaynak grubunu silebilirsiniz.

Aksi takdirde, bu hızlı başlangıçta oluşturduğunuz dizini silmek için aşağıdaki komutu çalıştırın.

node -r dotenv/config src/deleteIndex.js

Bu hızlı başlangıçta, Python için Azure Yapay Zeka Arama istemci kitaplığını kullanarak vector dizini oluşturacak, yükleyecek ve sorgulaacaksınız. Python istemci kitaplığı, dizin işlemleri için REST API'leri üzerinde bir soyutlama sağlar.

Azure Yapay Zeka Arama vektör dizininde vektör ve nonvector alanlarını tanımlayan bir dizin şeması, ekleme alanını oluşturan algoritmalar için vektör arama yapılandırması ve sorgu zamanında değerlendirilen vektör alanı tanımlarındaki ayarlar bulunur. Dizinler - Oluştur veya Güncelleştir (REST API), vektör dizinini oluşturur.

Ipucu

• Hemen başlamak ister misiniz? GitHub source kodunu indirin.
• Bu hızlı başlangıç vektörleştirme adımını atlar ve satır içi eklemeler sağlar. Kendi içeriğiniz üzerinde tümleşik vektörleştirme için Verileri içeri aktarma sihirbazını deneyin.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz bir hesap oluşturun.

• Azure Yapay Zeka Arama hizmeti. Bu hızlı başlangıcın çoğu için Ücretsiz katmanını kullanabilirsiniz, ancak daha büyük veri dosyaları için Temel veya üzerini öneririz.

• Python 3.8 veya üzeri.

• Python ve Jupyter uzantılarıyla Visual Studio Code.

• Git'i kullanarak örnek depoyu kopyalayın.

• Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure CLI.

Erişimi yapılandırma

Başlamadan önce, Azure Yapay Zeka Arama'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

   • Arama Hizmeti Katkıda Bulunanı

   • Arama Dizini Veri Katkıcısı

   • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure Yapay Zeka Arama hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

1. Azure portalında arama hizmetinize gidin.

2. Sol bölmeden Genel Bakış'ı seçin.

3. Uç noktayı not alın ve şu şekilde görünmelidir: https://my-service.search.windows.net.

Ortamı ayarlama

1. Örnek depoyu kopyalamak için Git'i kullanın.

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

2. Hızlı başlangıç klasörüne gidin ve Visual Studio Code açın.

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

3. sample.env içinde, AZURE_SEARCH_ENDPOINT yer tutucu değerini Uç noktayı al bölümünden aldığınız URL ile değiştirin.

4. olarak sample.envyeniden adlandırın.env.

   mv sample.env .env
   

5. Aç vector-search-quickstart.ipynb.

6. Ctrl+Shift+P tuşlarına basın, Not Defteri: Not Defteri Çekirdeği'ni seçin ve bir sanal ortam oluşturmak için istemleri izleyin. Bağımlılıklar için requirements.txt seçin.

   Tamamlandığında, proje dizininde bir .venv klasör görmeniz gerekir.

7. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama hizmetinizi içeren aboneliği seçin.

   az login
   

Kodu çalıştırma

1. Install packages and set variables Gerekli paketleri yüklemek ve ortam değişkenlerini yüklemek için hücreyi çalıştırın.

2. Vektör dizini oluşturmak, belgeleri karşıya yüklemek ve farklı türde vektör sorguları çalıştırmak için kalan hücreleri sıralı olarak çalıştırın.

Çıkış

Her kod hücresi çıktısını not defterine yazdırır. Aşağıdaki örnek, vektör arama sonuçlarını benzerlik puanına Single vector searchgöre derecelendirerek gösteren çıktısıdır.

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

Kodu anlama

Not

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

1. Vektör dizini oluşturma
2. Belgeleri dizine yükleme
3. Dizini sorgulama

Vektör dizini oluşturma

Azure Yapay Zeka Arama içerik eklemeden önce, içeriğin nasıl depolandığını ve yapılandırıldığını tanımlamak için bir dizin oluşturmanız gerekir.

Dizin şeması otel içeriğine göre düzenlenmiştir. Örnek veriler, kurgusal otellerin vektör ve nonvector açıklamalarından oluşur. Create an index Not defterindeki hücre, vektör alanı DescriptionVectorda dahil olmak üzere dizin şemasını oluşturur.

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
]

Önemli çıkarımlar:

• Alan listesi oluşturarak dizin tanımlarsınız. Her alan, alan türünü ve ayarlarını tanımlayan bir yardımcı yöntemi kullanılarak oluşturulur.

• Bu özel dizin birden çok arama özelliklerini destekler:

  • Tam metin arama (SearchableField)

  • Vektör araması (DescriptionVector ile vector_search_profile_name)

  • Anlam sıralaması (SemanticConfiguration)

  • Fasetsel arama (facetable ile işaretlenmiş alanlar)

  • Coğrafi uzamsal arama (Location ile SearchFieldDataType.GeographyPointalan)

  • Filtreleme ve sıralama (ve filterableile sortable işaretlenmiş alanlar)

• özelliği, vector_search_dimensions ekleme modelinizin çıkış boyutuyla eşleşmelidir. Bu hızlı başlangıçta text-embedding-ada-002 modeliyle eşleşmesi için 1,536 boyut kullanılır.

• Yapılandırma, VectorSearch Yaklaşık En Yakın Komşu (ANN) algoritmasını tanımlar. Desteklenen algoritmalar Hiyerarşik Gezinilebilir Küçük Dünya (HNSW) ve kapsamlı K-En Yakın Komşu (KNN) içerir. Daha fazla bilgi için bkz. Vektör aramasında ilgi.

Belgeleri dizine yükleme

Yeni oluşturulan dizinler boş. Bir dizini doldurmak ve aranabilir hale getirmek için dizin şemasına uygun JSON belgelerini karşıya yüklemeniz gerekir.

Azure Yapay Zeka Arama'de belgeler hem dizin oluşturma için giriş hem de sorgu çıkışları görevi görür. Kolaylık olması için, bu hızlı başlangıçta önceden derlenmiş vektörlerle örnek otel belgeleri sağlanmaktadır. Üretim senaryolarında içerik genellikle bağlı veri kaynaklarından alınır ve dizin oluşturucular kullanılarak JSON'a dönüştürülür.

Create documents payload ve Upload the documents hücreleri belgeleri dizine yükler.

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

Kodunuz, SearchClient paketi tarafından sağlanan ana nesne olan azure-search-documents aracılığıyla Azure Yapay Zeka Arama hizmetinizde barındırılan belirli bir arama diziniyle etkileşim kurar. SearchClient dizin işlemlerine erişim sağlar, örneğin:

• Veri alımı: upload_documents(), merge_documents(), delete_documents()

• Arama işlemleri: search(), autocomplete(), suggest()

Dizini sorgulama

Not defterindeki sorgular farklı arama desenleri gösterir. Örnek vektör sorguları iki dizeyi temel alır:

• Tam metin arama dizesi: "historic hotel walk to restaurants and shopping"

• Vektör sorgu dizesi: "quintessential lodging near running trails, eateries, retail" (matematiksel bir gösterime vektörleştirilmiş)

Vektör sorgu dizesi, tam metin arama dizesine benzer, ancak dizinde var olmayan terimler içerir. Vektör sorgu dizesi için yalnızca anahtar sözcük araması sıfır sonuç döndürür. Ancak vektör araması, tam anahtar sözcükler yerine anlam temelinde ilgili eşleşmeleri bulur.

Aşağıdaki örnekler temel bir vektör sorgusuyla başlar ve aşamalı olarak filtreler, anahtar sözcük araması ve anlamsal yeniden sıralama ekler.

Tek vektör arama

Hücre, Single vector search vektör sorgu dizesiyle yakından eşleşen belge açıklamalarını bulmak istediğiniz temel bir senaryoyu gösterir. VectorizedQuery vektör aramasını yapılandırıyor:

• k_nearest_neighbors vektör benzerliğine göre kaç sonuç döndürülür sınırlar.
• fields aranacak vektör alanını belirtir.

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
)

Filtre içeren tek vektörlü arama

Azure AI Arama'da, filtreler dizindeki vektör olmayan alanlara uygulanır. Single vector search with filter alanındaki hücre filtreleri, ücretsiz Wi-Fi sağlamayan tüm otelleri filtreleyerek çıkarır.

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

Coğrafi filtre ile tek vektör araması

Sonuçları belirli bir coğrafi alanla sınırlamak için coğrafi uzamsal filtre belirtebilirsiniz. Hücre Single vector search with geo filter bir coğrafi nokta (boylam ve enlem koordinatlarını kullanarak Washington D.C.) belirtir ve 300 kilometre içindeki otelleri döndürür. vector_filter_mode parametresi, filtrenin ne zaman çalıştığını belirler. Bu durumda, postFilter vektör aramasının ardından filtreyi çalıştırır.

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

Karma arama

Karma arama , tam metin ve vektör sorgularını tek bir istekte birleştirir. Hücre Hybrid search her iki sorgu türünü de eşzamanlı olarak çalıştırır ve ardından sonuçları birleşik bir derecelendirmede birleştirmek için Karşılıklı Rank Fusion (RRF) kullanır. RRF, birleştirilmiş bir derecelendirme oluşturmak için her sonuç kümesindeki sonuç derecelendirmelerinin tersini kullanır. Karma arama puanlarının tek sorgulu puanlardan eşit olarak daha küçük olduğuna dikkat edin.

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

Anlamsal hibrit arama

Hücre Semantic hybrid search , sonuçları dil anlama temelinde yeniden oluşturan anlam sıralamasını gösterir.

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

Bu sonuçları önceki sorgudaki karma arama sonuçlarıyla karşılaştırın. Anlamsal yeniden boyutlandırma olmadan Sublime Palace Hotel, Reciprocal Rank Fusion (RRF) metin ve vektör puanlarını birleştirerek birleştirilmiş bir sonuç elde ettiğinden birinci sırada yer alır. Anlamsal yeniden sıralamanın ardından Swirling Currents Hotel zirveye çıkar.

Anlam dereceleyicisi, her sonucun sorgunun amacıyla ne kadar iyi eşleştiğini değerlendirmek için makine kavrama modellerini kullanır. Swirling Currents Hotel'in açıklamasında, arama sorgusunun "walking access to shopping, dining, entertainment and the city center" ile yakından örtüşen "walk to restaurants and shopping" yer alır. Yakındaki yemek ve alışveriş için anlam eşleşmesi, açıklamasında yürünebilir olanakları vurgulamayan Sublime Palace Hotel'in daha üstüne çıkarır.

Önemli çıkarımlar:

• Karma aramada, vektör arama ile anahtar sözcükler üzerinde tam metin arama tümleştirebilirsiniz. Filtreler ve anlam derecelendirmesi vektörlere değil yalnızca metin içeriğine uygulanır.

• Gerçek sonuçlar semantik açıklamalı alt yazılar ve vurgular da dahil olmak üzere daha fazla ayrıntı içerir. Bu hızlı başlangıç kılavuzunda okunabilirliği artırmak için sonuçlar değiştirilir. Yanıtın tam yapısını almak için REST kullanarak isteği çalıştırın.

Kaynakları temizleme

Kendi aboneliğinizde çalışırken, artık ihtiyacınız olmayan kaynakları kaldırarak bir projeyi tamamlamak iyi bir fikirdir. Çalışır durumda kalan kaynaklar size pahalıya mal olabilir.

Kaynakları bulmak ve yönetmek için Azure portalında Tüm kaynaklar veya Kaynak grupları seçin. Kaynakları tek tek silebilir veya tüm kaynakları aynı anda kaldırmak için kaynak grubunu silebilirsiniz.

Aksi takdirde, bu hızlı başlangıçta oluşturduğunuz dizini silmek için kod hücresini çalıştırabilirsiniz Clean up .

Bu hızlı başlangıç kılavuzunda, Azure Yapay Zeka Arama istemcisi için JavaScript (TypeScript ile uyumlu) kütüphanesini kullanarak vektör dizini oluşturacak, yükleyecek ve sorgulayacaksınız. JavaScript istemci kitaplığı, dizin işlemleri için REST API'leri üzerinde bir soyutlama sağlar.

Azure Yapay Zeka Arama vektör dizininde vektör ve nonvector alanlarını tanımlayan bir dizin şeması, ekleme alanını oluşturan algoritmalar için vektör arama yapılandırması ve sorgu zamanında değerlendirilen vektör alanı tanımlarındaki ayarlar bulunur. Dizinler - Oluştur veya Güncelleştir (REST API), vektör dizinini oluşturur.

Ipucu

• Hemen başlamak ister misiniz? GitHub source kodunu indirin.
• Bu hızlı başlangıç vektörleştirme adımını atlar ve satır içi eklemeler sağlar. Kendi içeriğiniz üzerinde tümleşik vektörleştirme için Verileri içeri aktarma sihirbazını deneyin.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz bir hesap oluşturun.

• Azure Yapay Zeka Arama hizmeti. Bu hızlı başlangıcın çoğu için Ücretsiz katmanını kullanabilirsiniz, ancak daha büyük veri dosyaları için Temel veya üzerini öneririz.

• Node.js 20 LTS veya daha üzeri derlenmiş kodu çalıştırmak için.

• TypeScript'i JavaScript'e derlemek için TypeScript.

• Git'i kullanarak örnek depoyu kopyalayın.

• Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure CLI.

Erişimi yapılandırma

Başlamadan önce, Azure Yapay Zeka Arama'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

   • Arama Hizmeti Katkıda Bulunanı

   • Arama Dizini Veri Katkıcısı

   • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure Yapay Zeka Arama hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

1. Azure portalında arama hizmetinize gidin.

2. Sol bölmeden Genel Bakış'ı seçin.

3. Uç noktayı not alın ve şu şekilde görünmelidir: https://my-service.search.windows.net.

Ortamı ayarlama

1. Örnek depoyu kopyalamak için Git'i kullanın.

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

2. Hızlı başlangıç klasörüne gidin.

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

3. sample.env içinde, AZURE_SEARCH_ENDPOINT yer tutucu değerini Uç noktayı al bölümünden aldığınız URL ile değiştirin.

4. olarak sample.envyeniden adlandırın.env.

   mv sample.env .env
   

5. Bağımlılıkları yükleyin.

   npm install
   

   Yükleme tamamlandığında proje dizininde bir node_modules klasör görmeniz gerekir.

6. TypeScript dosyalarını JavaScript'e derleyin.

   npm run build
   

7. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama hizmetinizi içeren aboneliği seçin.

   az login
   

Kodu çalıştırma

1. Vektör dizini oluşturun.

   node -r dotenv/config dist/createIndex.js
   

2. Önceden derlenmiş eklemeler içeren belgeleri yükleyin.

   node -r dotenv/config dist/uploadDocuments.js
   

3. Vektör arama sorgusu çalıştırın.

   node -r dotenv/config dist/searchSingle.js
   

4. (İsteğe bağlı) Ek sorgu varyasyonları çalıştırın.

   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
   

   Not

   Bu komutlar klasörden derlenmiş .js dosyaları dist çalıştırır. Node.js yürütmeden önce TypeScript kodunun JavaScript'e çevrilmiş olması gerekir. Bu nedenle daha önce çalıştırmıştınız npm run build.

Çıkış

createIndex.ts çıktısı dizin adını ve onayını gösterir.

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

Çıktı uploadDocuments.ts dizine alınan her belge için başarı durumunu gösterir.

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.

çıktısı searchSingle.ts , vektör arama sonuçlarını benzerlik puanına göre sıralanmış olarak gösterir.

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

Kodu anlama

Not

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

1. Vektör dizini oluşturma
2. Belgeleri dizine yükleme
3. Dizini sorgulama

Vektör dizini oluşturma

Azure Yapay Zeka Arama içerik eklemeden önce, içeriğin nasıl depolandığını ve yapılandırıldığını tanımlamak için bir dizin oluşturmanız gerekir.

Dizin şeması otel içeriğine göre düzenlenmiştir. Örnek veriler, kurgusal otellerin vektör ve nonvector açıklamalarından oluşur. içindeki aşağıdaki kod createIndex.ts , vektör alanı DescriptionVectorda dahil olmak üzere dizin şemasını oluşturur.

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

Önemli çıkarımlar:

• Alan listesi oluşturarak dizin tanımlarsınız.

• Bu özel dizin birden çok arama özelliklerini destekler:

  • Tam metin arama (searchable: true)

  • Vektör araması (DescriptionVector ile vectorSearchProfileName)

  • Anlam sıralaması (semanticSearch)

  • Fasetsel arama (facetable ile işaretlenmiş alanlar)

  • Coğrafi uzamsal arama (Location ile Edm.GeographyPointalan)

  • Filtreleme ve sıralama (ve filterableile sortable işaretlenmiş alanlar)

• özelliği, vectorSearchDimensions ekleme modelinizin çıkış boyutuyla eşleşmelidir. Bu hızlı başlangıçta text-embedding-ada-002 modeliyle eşleşmesi için 1,536 boyut kullanılır.

• Yapılandırma, vectorSearch Yaklaşık En Yakın Komşu (ANN) algoritmasını tanımlar. Desteklenen algoritmalar Hiyerarşik Gezinilebilir Küçük Dünya (HNSW) ve kapsamlı K-En Yakın Komşu (KNN) içerir. Daha fazla bilgi için bkz. Vektör aramasında ilgi.

Belgeleri dizine yükleme

Yeni oluşturulan dizinler boş. Bir dizini doldurmak ve aranabilir hale getirmek için dizin şemasına uygun JSON belgelerini karşıya yüklemeniz gerekir.

Azure Yapay Zeka Arama'de belgeler hem dizin oluşturma için giriş hem de sorgu çıkışları görevi görür. Kolaylık olması için, bu hızlı başlangıçta önceden derlenmiş vektörlerle örnek otel belgeleri sağlanmaktadır. Üretim senaryolarında içerik genellikle bağlı veri kaynaklarından alınır ve dizin oluşturucular kullanılarak JSON'a dönüştürülür.

içindeki aşağıdaki kod uploadDocuments.ts , belgeleri arama hizmetinize yükler.

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

Kodunuz, SearchClient paketi tarafından sağlanan ana nesne olan @azure/search-documents aracılığıyla Azure Yapay Zeka Arama hizmetinizde barındırılan belirli bir arama diziniyle etkileşim kurar. SearchClient dizin işlemlerine erişim sağlar, örneğin:

• Veri alımı: uploadDocuments, mergeDocuments, deleteDocuments

• Arama işlemleri: search, autocomplete, suggest

Dizini sorgulama

Arama dosyalarındaki sorgular farklı arama desenleri gösterir. Örnek vektör sorguları iki dizeyi temel alır:

• Tam metin arama dizesi: "historic hotel walk to restaurants and shopping"

• Vektör sorgu dizesi: "quintessential lodging near running trails, eateries, retail" (matematiksel bir gösterime vektörleştirilmiş)

Vektör sorgu dizesi, tam metin arama dizesine benzer, ancak dizinde var olmayan terimler içerir. Vektör sorgu dizesi için yalnızca anahtar sözcük araması sıfır sonuç döndürür. Ancak vektör araması, tam anahtar sözcükler yerine anlam temelinde ilgili eşleşmeleri bulur.

Aşağıdaki örnekler temel bir vektör sorgusuyla başlar ve aşamalı olarak filtreler, anahtar sözcük araması ve anlamsal yeniden sıralama ekler.

Tek vektör arama

searchSingle.ts vektör sorgu dizesiyle yakından eşleşen belge açıklamalarını bulmak istediğiniz temel bir senaryoyu gösterir. VectorQuery nesnesi vektör aramasını yapılandırıyor:

• kNearestNeighborsCount vektör benzerliğine göre kaç sonuç döndürülür sınırlar.
• fields aranacak vektör alanını belirtir.

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

Filtre içeren tek vektörlü arama

Azure AI Arama'da, filtreler dizindeki vektör olmayan alanlara uygulanır. searchSingleWithFilter.ts alanında ücretsiz Wi-Fi sağlamayan otelleri filtrelemek için filtreler uygulayın.

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

Coğrafi filtre ile tek vektör araması

Sonuçları belirli bir coğrafi alanla sınırlamak için coğrafi uzamsal filtre belirtebilirsiniz. searchSingleWithGeoFilter.ts bir coğrafi nokta (boylam ve enlem koordinatlarını kullanarak Washington D.C.) belirtir ve 300 kilometre içindeki otelleri döndürür. filterMode özelliği, filtrenin ne zaman çalıştırileceğini belirler. Bu durumda, postFilter vektör aramasının ardından filtreyi çalıştırır.

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

Karma arama

Karma arama , tam metin ve vektör sorgularını tek bir istekte birleştirir. searchHybrid.ts her iki sorgu türünü de eşzamanlı olarak çalıştırır ve ardından sonuçları birleşik bir derecelendirmede birleştirmek için Karşılıklı Rank Fusion 'ı (RRF) kullanır. RRF, birleştirilmiş bir derecelendirme oluşturmak için her sonuç kümesindeki sonuç derecelendirmelerinin tersini kullanır. Karma arama puanlarının tek sorgulu puanlardan eşit olarak daha küçük olduğuna dikkat edin.

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

Anlamsal hibrit arama

searchSemanticHybrid.ts sonuçları dil anlama temelinde yeniden oluşturan anlamsal derecelendirmeyi gösterir.

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

Bu sonuçları önceki sorgudaki karma arama sonuçlarıyla karşılaştırın. Anlamsal yeniden boyutlandırma olmadan Sublime Palace Hotel, Reciprocal Rank Fusion (RRF) metin ve vektör puanlarını birleştirerek birleştirilmiş bir sonuç elde ettiğinden birinci sırada yer alır. Anlamsal yeniden sıralamanın ardından Swirling Currents Hotel zirveye çıkar.

Anlam dereceleyicisi, her sonucun sorgunun amacıyla ne kadar iyi eşleştiğini değerlendirmek için makine kavrama modellerini kullanır. Swirling Currents Hotel'in açıklamasında, arama sorgusunun "walking access to shopping, dining, entertainment and the city center" ile yakından örtüşen "walk to restaurants and shopping" yer alır. Yakındaki yemek ve alışveriş için anlam eşleşmesi, açıklamasında yürünebilir olanakları vurgulamayan Sublime Palace Hotel'in daha üstüne çıkarır.

Önemli çıkarımlar:

• Karma aramada, vektör arama ile anahtar sözcükler üzerinde tam metin arama tümleştirebilirsiniz. Filtreler ve anlam derecelendirmesi vektörlere değil yalnızca metin içeriğine uygulanır.

• Gerçek sonuçlar semantik açıklamalı alt yazılar ve vurgular da dahil olmak üzere daha fazla ayrıntı içerir. Bu hızlı başlangıç kılavuzunda okunabilirliği artırmak için sonuçlar değiştirilir. Yanıtın tam yapısını almak için REST kullanarak isteği çalıştırın.

Kaynakları temizleme

Kendi aboneliğinizde çalışırken, artık ihtiyacınız olmayan kaynakları kaldırarak bir projeyi tamamlamak iyi bir fikirdir. Çalışır durumda kalan kaynaklar size pahalıya mal olabilir.

Kaynakları bulmak ve yönetmek için Azure portalında Tüm kaynaklar veya Kaynak grupları seçin. Kaynakları tek tek silebilir veya tüm kaynakları aynı anda kaldırmak için kaynak grubunu silebilirsiniz.

Aksi takdirde, bu hızlı başlangıçta oluşturduğunuz dizini silmek için aşağıdaki komutu çalıştırın.

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

Bu hızlı başlangıçta, vector dizini oluşturmak, yüklemek ve sorgulamak için Azure Yapay Zeka Arama REST API kullanacaksınız.

Azure Yapay Zeka Arama vektör dizininde vektör ve nonvector alanlarını tanımlayan bir dizin şeması, ekleme alanını oluşturan algoritmalar için vektör arama yapılandırması ve sorgu zamanında değerlendirilen vektör alanı tanımlarındaki ayarlar bulunur. Dizinler - Oluştur veya Güncelleştir (REST API), vektör dizinini oluşturur.

Ipucu

• Hemen başlamak ister misiniz? GitHub source kodunu indirin.
• Bu hızlı başlangıç vektörleştirme adımını atlar ve satır içi eklemeler sağlar. Kendi içeriğiniz üzerinde tümleşik vektörleştirme için Verileri içeri aktarma sihirbazını deneyin.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz bir hesap oluşturun.

• Azure Yapay Zeka Arama hizmeti. Bu hızlı başlangıcın çoğu için Ücretsiz katmanını kullanabilirsiniz, ancak daha büyük veri dosyaları için Temel veya üzerini öneririz.

• REST İstemci uzantısı ile Visual Studio Code.

• Git'i kullanarak örnek depoyu kopyalayın.

• Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure CLI.

Erişimi yapılandırma

Başlamadan önce, Azure Yapay Zeka Arama'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

   • Arama Hizmeti Katkıda Bulunanı

   • Arama Dizini Veri Katkıcısı

   • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure Yapay Zeka Arama hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

1. Azure portalında arama hizmetinize gidin.

2. Sol bölmeden Genel Bakış'ı seçin.

3. Uç noktayı not alın ve şu şekilde görünmelidir: https://my-service.search.windows.net.

Ortamı ayarlama

1. Örnek depoyu kopyalamak için Git'i kullanın.

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

2. Hızlı başlangıç klasörüne gidin ve Visual Studio Code açın.

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

3. az-search-quickstart-vectors.rest içinde, @baseUrl yer tutucu değerini Uç noktayı al bölümünden aldığınız URL ile değiştirin.

4. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama hizmetinizi içeren aboneliği seçin.

   az login
   

5. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için bir erişim belirteci oluşturun.

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

6. için @token yer tutucu değerini önceki adımdaki belirteçle değiştirin.

Kodu çalıştırma

1. bağlantınızı doğrulamak için altında ### List existing indexes by nameİstek Gönder'i seçin.

   Bir yanıt bitişik bir bölmede görünmelidir. Mevcut dizinleriniz varsa, bunlar listelenir. Aksi takdirde, liste boş olur. HTTP kodu ise 200 OKdevam etmeye hazırsınız demektir.

2. Vektör dizini oluşturmak, belgeleri karşıya yüklemek ve farklı türde vektör sorguları çalıştırmak için kalan istekleri sırayla gönderin.

Çıkış

Her sorgu isteği JSON sonuçları döndürür. Aşağıdaki örnek, benzerlik puanına ### Run a single vector query göre sıralanmış vektör arama sonuçlarını gösteren isteğin çıktısıdır.

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

Kodu anlama

Not

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

1. Vektör dizini oluşturma
2. Belgeleri dizine yükleme
3. Dizini sorgulama

Vektör dizini oluşturma

Azure Yapay Zeka Arama içerik eklemeden önce, içeriğin nasıl depolandığını ve yapılandırıldığını tanımlamak için bir dizin oluşturmanız gerekir. Bu hızlı başlangıçta, arama hizmetinizde adlı bir vektör dizini ve onun fiziksel veri yapıları oluşturmak için hotels-vector-quickstart çağrıları yapılır.

Dizin şeması otel içeriğine göre düzenlenmiştir. Örnek veriler, kurgusal otellerin vektör ve nonvector açıklamalarından oluşur. Aşağıdaki alıntıda isteğin anahtar yapısı gösterilmektedir ### Create a new index .

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

Önemli çıkarımlar:

• Bu özel dizin birden çok arama özelliklerini destekler:

  • Tam metin araması (searchable alanları true olarak ayarlandı)

  • Vektör araması (DescriptionVector ile vectorSearchProfile)

  • Anlam derecelendirmesi (semantic yapılandırma)

  • Fasetli arama (facetable içerecek şekilde ayarlanmış alanlartrue)

  • Coğrafi uzamsal arama (Location ile Edm.GeographyPointalan)

  • Filtreleme ve sıralama (filterable ve sortable, true olarak ayarlanmış alanlar)

• özelliği, dimensions ekleme modelinizin çıkış boyutuyla eşleşmelidir. Bu hızlı başlangıçta text-embedding-ada-002 modeliyle eşleşmesi için 1,536 boyut kullanılır.

• vectorSearch bölümü En Yakın Yaklaşık Komşu (ANN) algoritmasını tanımlar. Desteklenen algoritmalar Hiyerarşik Gezinilebilir Küçük Dünya (HNSW) ve kapsamlı K-En Yakın Komşu (KNN) içerir. Daha fazla bilgi için bkz. Vektör aramasında ilgi.

Belgeleri dizine yükleme

Yeni oluşturulan dizinler boş. Bir dizini doldurmak ve aranabilir hale getirmek için dizin şemasına uygun JSON belgelerini karşıya yüklemeniz gerekir.

Azure Yapay Zeka Arama'de belgeler hem dizin oluşturma için giriş hem de sorgu çıkışları görevi görür. Kolaylık olması için, bu hızlı başlangıçta satır içi JSON olarak örnek otel belgeleri sağlanır. Ancak üretim senaryolarında içerik genellikle bağlı veri kaynaklarından alınır ve dizin oluşturucular kullanılarak JSON'a dönüştürülür.

Bu hızlı başlangıçta, dizininize örnek otel belgeleri eklemek için Belgeler - Dizin (REST API) çağrısı yapılır. Aşağıdaki alıntıda isteğin yapısı gösterilmektedir ### Upload 7 documents .

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

Önemli çıkarımlar:

• Dizideki value her belge bir oteli temsil eder ve dizin şemasıyla eşleşen alanlar içerir. @search.action parametresi, her belge için gerçekleştirilecek işlemi belirtir. Bu hızlı başlangıçta, mevcut değilse belgeyi ekleyen veya mevcutsa güncelleştiren mergeOrUpload kullanılır.

• Yükteki belgeler, dizin şemasında tanımlanan alanlardan oluşur.

Dizini sorgulama

Örnek dosyadaki sorgular farklı arama desenleri gösterir. Örnek vektör sorguları iki dizeyi temel alır:

• Tam metin arama dizesi: "historic hotel walk to restaurants and shopping"

• Vektör sorgu dizesi: "quintessential lodging near running trails, eateries, retail" (matematiksel bir gösterime vektörleştirilmiş)

Vektör sorgu dizesi, tam metin arama dizesine benzer, ancak dizinde var olmayan terimler içerir. Vektör sorgu dizesi için yalnızca anahtar sözcük araması sıfır sonuç döndürür. Ancak vektör araması, tam anahtar sözcükler yerine anlam temelinde ilgili eşleşmeleri bulur.

Aşağıdaki örnekler temel bir vektör sorgusuyla başlar ve aşamalı olarak filtreler, anahtar sözcük araması ve anlamsal yeniden sıralama ekler.

Tek vektör arama

İstek, ### Run a single vector query vektör sorgu dizesiyle yakından eşleşen belge açıklamalarını bulmak istediğiniz temel bir senaryoyu gösterir. Dizi, vectorQueries vektör aramasını yapılandırıyor:

• k vektör benzerliğine göre kaç sonuç döndürülür sınırlar.
• fields aranacak vektör alanını belirtir.

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

Filtre içeren tek vektörlü arama

Azure AI Arama'da, filtreler dizindeki vektör olmayan alanlara uygulanır. İstek, ### Run a vector query with a filter alanında, ücretsiz Wi-Fi sağlamayan otelleri filtrelemek için bir filtre uygular.

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

Coğrafi filtre ile tek vektör araması

Sonuçları belirli bir coğrafi alanla sınırlamak için coğrafi uzamsal filtre belirtebilirsiniz. İstek ### Run a vector query with a geo filter bir coğrafi nokta (boylam ve enlem koordinatları kullanılarak Washington D.C.) belirtir ve 300 kilometre içindeki otelleri döndürür. vectorFilterMode parametresi, filtrenin ne zaman çalıştığını belirler. Bu durumda, postFilter vektör aramasının ardından filtreyi çalıştırır.

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

Karma arama

Karma arama , tam metin ve vektör sorgularını tek bir istekte birleştirir. İstek ### Run a hybrid query her iki sorgu türünü de eşzamanlı olarak çalıştırır ve ardından sonuçları birleşik bir derecelendirmede birleştirmek için Karşılıklı Rank Fusion (RRF) kullanır. RRF, birleştirilmiş bir derecelendirme oluşturmak için her sonuç kümesindeki sonuç derecelendirmelerinin tersini kullanır. Karma arama puanlarının tek sorgulu puanlardan eşit olarak daha küçük olduğuna dikkat edin.

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

Anlamsal hibrit arama

İstek ### Run a hybrid query with semantic reranking , sonuçları dil anlama temelinde yeniden oluşturan anlamsal derecelendirmeyi gösterir.

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

Bu sonuçları önceki sorgudaki karma arama sonuçlarıyla karşılaştırın. Anlamsal yeniden boyutlandırma olmadan Sublime Palace Hotel, Reciprocal Rank Fusion (RRF) metin ve vektör puanlarını birleştirerek birleştirilmiş bir sonuç elde ettiğinden birinci sırada yer alır. Anlamsal yeniden sıralamanın ardından Swirling Currents Hotel zirveye çıkar.

Anlam dereceleyicisi, her sonucun sorgunun amacıyla ne kadar iyi eşleştiğini değerlendirmek için makine kavrama modellerini kullanır. Swirling Currents Hotel'in açıklamasında, arama sorgusunun "walking access to shopping, dining, entertainment and the city center" ile yakından örtüşen "walk to restaurants and shopping" yer alır. Yakındaki yemek ve alışveriş için anlam eşleşmesi, açıklamasında yürünebilir olanakları vurgulamayan Sublime Palace Hotel'in daha üstüne çıkarır.

Önemli çıkarımlar:

• Karma aramada, vektör arama ile anahtar sözcükler üzerinde tam metin arama tümleştirebilirsiniz. Filtreler ve anlam derecelendirmesi vektörlere değil yalnızca metin içeriğine uygulanır.

Kaynakları temizleme

Kendi aboneliğinizde çalışırken, artık ihtiyacınız olmayan kaynakları kaldırarak bir projeyi tamamlamak iyi bir fikirdir. Çalışır durumda kalan kaynaklar size pahalıya mal olabilir.

Kaynakları bulmak ve yönetmek için Azure portalında Tüm kaynaklar veya Kaynak grupları seçin. Kaynakları tek tek silebilir veya tüm kaynakları aynı anda kaldırmak için kaynak grubunu silebilirsiniz.

Aksi takdirde, bu hızlı başlangıçta oluşturduğunuz dizini silme isteği gönderebilirsiniz ### Delete an index .

İlgili içerik

• Azure Yapay Zeka Arama'te Vektör araması
• azure-search-vector-samples GitHub deposu