Mulai cepat: Pencarian vektor

Dalam mulai cepat ini, Anda menggunakan pustaka klien Pencarian Azure AI untuk .NET untuk membuat, memuat, dan mengkueri indeks vektor. Pustaka klien .NET menyediakan abstraksi atas REST API untuk operasi indeks.

Dalam Pencarian Azure AI, indeks vektor memiliki skema indeks yang menentukan bidang vektor dan nonvektor, konfigurasi pencarian vektor untuk algoritma yang membuat ruang penyematan, dan pengaturan pada definisi bidang vektor yang dievaluasi pada waktu kueri. Indeks - Buat atau Perbarui (REST API) membuat indeks vektor.

Tips

• Ingin segera memulai? Unduh kode source di GitHub.
• Panduan cepat ini menghilangkan langkah vektorisasi dan menyediakan embedding langsung. Untuk vektorisasi terintegrasi atas konten Anda sendiri, coba wizard Impor data.

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.

• Layanan Pencarian Azure AI. Anda dapat menggunakan paket Gratis untuk sebagian besar Quickstart ini, tetapi kami merekomendasikan paket Dasar atau yang lebih tinggi untuk file data berukuran besar.

• .NET 8 atau yang lebih baru.

• Git untuk mengkloning repositori sampel.

• Azure CLI untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Pencarian Azure AI. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak dapat dilakukan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

2. Tetapkan peran berikut ke akun pengguna Anda.

   • Kontributor Layanan Pencarian

   • Kontributor Data Indeks Pencarian

   • Pembaca Indeks Data Pencarian

Dapatkan titik akhir

Setiap layanan Pencarian Azure AI memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

1. Buka layanan pencarian Anda di portal Azure.

2. Dari panel kiri, pilih Gambaran Umum.

3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Siapkan lingkungan

1. Gunakan Git untuk mengkloning repositori sampel.

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

2. Masuk ke folder panduan mulai cepat.

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

3. Di VectorSearchCreatePopulateIndex/appsettings.json, ganti nilai tempat penampung untuk Endpoint dengan URL yang Anda peroleh di Dapatkan titik akhir.

4. Ulangi langkah sebelumnya untuk VectorSearchExamples/appsettings.json.

5. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Pencarian Azure AI Anda.

   az login
   

Jalankan kode

1. Jalankan proyek pertama untuk membuat dan mengisi indeks.

   cd VectorSearchCreatePopulateIndex
   dotnet run
   

2. Di VectorSearchExamples/Program.cs, batalkan komentar metode kueri yang ingin Anda jalankan.

3. Jalankan proyek kedua untuk menjalankan kueri tersebut terhadap indeks.

   cd ..\VectorSearchExamples
   dotnet run
   

Keluaran

Output proyek pertama mencakup konfirmasi pembuatan indeks dan pengunggahan dokumen yang berhasil.

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

Output proyek kedua menunjukkan hasil pencarian untuk setiap metode kueri yang diaktifkan. Contoh berikut menunjukkan hasil pencarian vektor tunggal.

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

Memahami kode

Catatan

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

1. Membuat indeks vektor
2. Mengunggah dokumen ke indeks
3. Menjalankan kueri pada indeks

Membuat indeks vektor

Sebelum menambahkan konten ke Pencarian Azure AI, Anda harus membuat indeks untuk menentukan bagaimana konten disimpan dan terstruktur.

Skema indeks diatur di sekitar konten hotel. Data sampel terdiri dari deskripsi vektor dan nonvektor hotel fiktif. Kode berikut dalam VectorSearchCreatePopulateIndex/Program.cs membuat skema indeks, termasuk bidang DescriptionVectorvektor .

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

Poin-poin penting:

• Anda menentukan indeks dengan membuat daftar bidang.

• Indeks khusus ini mendukung beberapa kemampuan pencarian:

  • Pencarian teks lengkap (SearchableField)

  • Pencarian vektor (VectorSearchField)

  • Peringkat semantik (SemanticSearch)

  • Pencarian berfasis (bidang ditandai dengan IsFacetable)

  • Pencarian geo-spasial (Location kolom dengan SearchFieldDataType.GeographyPoint)

  • Pemfilteran dan pengurutan (bidang ditandai dengan IsFilterable dan IsSortable)

• Parameter kedua dalam VectorSearchField menentukan vectorSearchDimensions, yang harus cocok dengan ukuran output model penyematan Anda. Panduan Mulai Cepat ini menggunakan 1,536 dimensi untuk mencocokkan dengan model text-embedding-ada-002.

• Konfigurasi VectorSearch mendefinisikan algoritma Perkiraan Tetangga Terdekat (ANN). Algoritma yang didukung termasuk Hierarkis Navigable Small World (HNSW) dan K-Nearest Neighbor (KNN) yang lengkap. Untuk informasi selengkapnya, lihat Relevansi dalam pencarian vektor.

Mengunggah dokumen ke indeks

Indeks yang baru dibuat kosong. Untuk mengisi indeks dan membuatnya dapat dicari, Anda harus mengunggah dokumen JSON yang sesuai dengan skema indeks.

Dalam Pencarian Azure AI, dokumen berfungsi sebagai input untuk pengindeksan dan output untuk kueri. Untuk kemudahan, panduan cepat ini menyediakan dokumen contoh hotel dengan vektor yang telah dihitung sebelumnya. Dalam skenario produksi, konten sering ditarik dari sumber data yang terhubung dan diubah menjadi JSON menggunakan pengindeks.

Kode berikut mengunggah dokumen dari HotelData.json ke layanan pencarian Anda.

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

Kode Anda berinteraksi dengan indeks pencarian tertentu yang dihosting di layanan Pencarian Azure AI Anda melalui SearchClient, yang merupakan objek utama yang disediakan oleh paket Azure.Search.Documents. SearchClient menyediakan akses ke operasi indeks, seperti:

• Penyerapan data: UploadDocuments(), MergeDocuments(), DeleteDocuments()

• Operasi pencarian: Search(), Autocomplete(), Suggest()

Melakukan kueri pada indeks

Kueri dalam VectorSearchExamples menunjukkan pola pencarian yang berbeda. Contoh kueri vektor didasarkan pada dua string:

• String pencarian teks lengkap: "historic hotel walk to restaurants and shopping"

• String kueri vektor: "quintessential lodging near running trails, eateries, retail" (di-vektorisasi ke dalam representasi matematika)

String kueri vektor secara semantik mirip dengan string pencarian teks lengkap, tetapi menyertakan istilah yang tidak ada dalam indeks. Pencarian khusus kata kunci untuk string kueri vektor mengembalikan hasil nol. Namun, pencarian vektor menemukan kecocokan yang relevan berdasarkan arti daripada kata kunci yang tepat.

Contoh berikut dimulai dengan kueri vektor dasar dan secara progresif menambahkan filter, pencarian kata kunci, dan reranking semantik.

Pencarian vektor tunggal

Metode ini SearchSingleVector menunjukkan skenario dasar di mana Anda ingin menemukan deskripsi dokumen yang sangat cocok dengan string kueri vektor. VectorizedQuery mengonfigurasi pencarian vektor:

• KNearestNeighborsCount membatasi berapa banyak hasil yang dikembalikan berdasarkan kesamaan vektor.
• Fields menentukan bidang vektor untuk dicari.

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

Pencarian vektor tunggal dengan filter

Dalam Pencarian Azure AI, filter berlaku untuk bidang nonvektor dalam indeks. Metode ini SearchSingleVectorWithFilter memfilter berdasarkan kolom Tags untuk menyaring hotel mana pun yang tidak menyediakan Wi-Fi gratis.

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

Pencarian vektor tunggal dengan filter geografis

Anda dapat menentukan filter geo-spasial untuk membatasi hasil ke area geografis tertentu. Metode ini SingleSearchWithGeoFilter menentukan titik geografis (Washington D.C., menggunakan koordinat bujur dan lintang) dan mengembalikan hotel dalam jarak 300 kilometer. Secara default, filter berjalan setelah pencarian vektor.

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

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

Pencarian hibrid

Pencarian hibrid menggabungkan kueri teks lengkap dan vektor dalam satu permintaan. Metode ini SearchHybridVectorAndText menjalankan kedua jenis kueri secara bersamaan, lalu menggunakan Reciprocal Rank Fusion (RRF) untuk menggabungkan hasilnya ke dalam peringkat terpadu. RRF menggunakan inversi peringkat hasil dari setiap hasil yang ditetapkan untuk menghasilkan peringkat gabungan. Perhatikan bahwa skor pencarian hibrid sama-sama lebih kecil dari skor kueri tunggal.

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

Pencarian hibrid semantik

Metode ini SearchHybridVectorAndSemantic menunjukkan peringkat semantik, yang melakukan rerank hasil berdasarkan pemahaman bahasa.

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

Bandingkan hasil ini dengan hasil pencarian hibrid dari kueri sebelumnya. Tanpa reranking semantik, Sublime Palace Hotel menempati peringkat pertama karena Reciprocal Rank Fusion (RRF) menggabungkan skor teks dan vektor untuk menghasilkan hasil gabungan. Setelah reranking semantik, Swirling Currents Hotel pindah ke tempat teratas.

Pemeringkat semantik menggunakan model pemahaman mesin untuk mengevaluasi seberapa baik setiap hasil cocok dengan niat kueri. Deskripsi Swirling Currents Hotel menyebutkan "walking access to shopping, dining, entertainment and the city center", yang selaras dengan kueri pencarian "walk to restaurants and shopping". Kecocokan semantik untuk bersantap dan berbelanja di dekatnya memposisikannya di atas Sublime Palace Hotel, yang tidak menekankan fasilitas yang bisa dicapai dengan berjalan kaki dalam deskripsinya.

Poin-poin penting:

• Dalam pencarian hibrid, Anda dapat mengintegrasikan pencarian vektor dengan pencarian teks lengkap melalui kata kunci. Filter dan peringkat semantik hanya berlaku untuk konten tekstual, bukan vektor.

• Hasil aktual mencakup detail lebih lanjut, termasuk keterangan semantik dan sorotan. Panduan cepat ini mengubah hasil agar lebih mudah dibaca. Untuk mendapatkan struktur respons lengkap, gunakan REST untuk menjalankan permintaan.

Membersihkan sumber daya

Saat Anda bekerja di langganan Anda sendiri, ada baiknya untuk menyelesaikan proyek dengan menghapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan berjalan dapat menyebabkan biaya tambahan.

Di portal Azure, pilih Semua sumber daya atau Kelompok sumber daya dari panel kiri untuk menemukan dan mengelola sumber daya. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus semua sumber daya sekaligus.

Dalam mulai cepat ini, Anda menggunakan pustaka klien Pencarian Azure AI untuk Java untuk membuat, memuat, dan mengkueri indeks vektor. Pustaka klien Java menyediakan abstraksi atas REST API untuk operasi indeks.

Dalam Pencarian Azure AI, indeks vektor memiliki skema indeks yang menentukan bidang vektor dan nonvektor, konfigurasi pencarian vektor untuk algoritma yang membuat ruang penyematan, dan pengaturan pada definisi bidang vektor yang dievaluasi pada waktu kueri. Indeks - Buat atau Perbarui (REST API) membuat indeks vektor.

Tips

• Ingin segera memulai? Unduh kode source di GitHub.
• Panduan cepat ini menghilangkan langkah vektorisasi dan menyediakan embedding langsung. Untuk vektorisasi terintegrasi atas konten Anda sendiri, coba wizard Impor data.

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.

• Layanan Pencarian Azure AI. Anda dapat menggunakan paket Gratis untuk sebagian besar Quickstart ini, tetapi kami merekomendasikan paket Dasar atau yang lebih tinggi untuk file data berukuran besar.

• Java 21 (LTS) dan Maven.

• Git untuk mengkloning repositori sampel.

• Azure CLI untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Pencarian Azure AI. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak dapat dilakukan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

2. Tetapkan peran berikut ke akun pengguna Anda.

   • Kontributor Layanan Pencarian

   • Kontributor Data Indeks Pencarian

   • Pembaca Indeks Data Pencarian

Dapatkan titik akhir

Setiap layanan Pencarian Azure AI memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

1. Buka layanan pencarian Anda di portal Azure.

2. Dari panel kiri, pilih Gambaran Umum.

3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Siapkan lingkungan

1. Gunakan Git untuk mengkloning repositori sampel.

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

2. Masuk ke folder panduan mulai cepat.

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

3. Di src/main/resources/application.properties, ganti nilai tempat penampung untuk azure.search.endpoint dengan URL yang Anda peroleh di Dapatkan titik akhir.

4. Pasang dependensi.

   mvn clean dependency:copy-dependencies
   

   Setelah build selesai, Anda akan melihat target/dependency folder di direktori proyek.

5. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Pencarian Azure AI Anda.

   az login
   

Jalankan kode

1. Buat indeks vektor.

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

2. Muat dokumen yang berisi embedding yang telah dikomputasi sebelumnya.

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

3. Jalankan kueri pencarian vektor.

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

4. (Opsional) Lakukan variasi kueri tambahan.

   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"
   

Keluaran

Output menunjukkan CreateIndex.java nama indeks dan konfirmasi.

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

Output UploadDocuments.java menunjukkan status keberhasilan setiap dokumen terindeks.

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.

Output SearchSingle.java menunjukkan hasil pencarian vektor yang diberi peringkat berdasarkan skor kesamaan.

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

Memahami kode

Catatan

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

1. Membuat indeks vektor
2. Mengunggah dokumen ke indeks
3. Menjalankan kueri pada indeks

Membuat indeks vektor

Sebelum menambahkan konten ke Pencarian Azure AI, Anda harus membuat indeks untuk menentukan bagaimana konten disimpan dan terstruktur.

Skema indeks diatur di sekitar konten hotel. Data sampel terdiri dari deskripsi vektor dan nonvektor hotel fiktif. Kode berikut dalam CreateIndex.java membuat skema indeks, termasuk bidang DescriptionVectorvektor .

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

Poin-poin penting:

• Anda menentukan indeks dengan membuat daftar bidang.

• Indeks khusus ini mendukung beberapa kemampuan pencarian:

  • Pencarian teks lengkap (setSearchable)

  • Pencarian vektor (DescriptionVector dengan setVectorSearchProfileName)

  • Peringkat semantik (SemanticConfiguration)

  • Pencarian berfasis (bidang ditandai dengan setFacetable)

  • Pencarian geo-spasial (Location kolom dengan SearchFieldDataType.GEOGRAPHY_POINT)

  • Pemfilteran dan pengurutan (bidang ditandai dengan setFilterable dan setSortable)

• Nilai setVectorSearchDimensions() harus cocok dengan ukuran output model penyematan Anda. Panduan Mulai Cepat ini menggunakan 1,536 dimensi untuk mencocokkan dengan model text-embedding-ada-002.

• Konfigurasi VectorSearch mendefinisikan algoritma Perkiraan Tetangga Terdekat (ANN). Algoritma yang didukung termasuk Hierarkis Navigable Small World (HNSW) dan K-Nearest Neighbor (KNN) yang lengkap. Untuk informasi selengkapnya, lihat Relevansi dalam pencarian vektor.

Mengunggah dokumen ke indeks

Indeks yang baru dibuat kosong. Untuk mengisi indeks dan membuatnya dapat dicari, Anda harus mengunggah dokumen JSON yang sesuai dengan skema indeks.

Dalam Pencarian Azure AI, dokumen berfungsi sebagai input untuk pengindeksan dan output untuk kueri. Untuk kemudahan, panduan cepat ini menyediakan dokumen contoh hotel dengan vektor yang telah dihitung sebelumnya. Dalam skenario produksi, konten sering ditarik dari sumber data yang terhubung dan diubah menjadi JSON menggunakan pengindeks.

Kode berikut dalam UploadDocuments.java mengunggah dokumen ke layanan pencarian Anda.

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

Kode Anda berinteraksi dengan indeks pencarian tertentu yang dihosting di layanan Pencarian Azure AI Anda melalui SearchClient, yang merupakan objek utama yang disediakan oleh paket azure-search-documents. SearchClient menyediakan akses ke operasi seperti:

• Penyerapan data: uploadDocuments, mergeDocuments, deleteDocuments

• Operasi pencarian: search, autocomplete, suggest

Melakukan kueri pada indeks

Kueri dalam file pencarian menunjukkan pola pencarian yang berbeda. Contoh kueri vektor didasarkan pada dua string:

• String pencarian teks lengkap: "historic hotel walk to restaurants and shopping"

• String kueri vektor: "quintessential lodging near running trails, eateries, retail" (di-vektorisasi ke dalam representasi matematika)

String kueri vektor secara semantik mirip dengan string pencarian teks lengkap, tetapi menyertakan istilah yang tidak ada dalam indeks. Pencarian khusus kata kunci untuk string kueri vektor mengembalikan hasil nol. Namun, pencarian vektor menemukan kecocokan yang relevan berdasarkan arti daripada kata kunci yang tepat.

Contoh berikut dimulai dengan kueri vektor dasar dan secara progresif menambahkan filter, pencarian kata kunci, dan reranking semantik.

Pencarian vektor tunggal

SearchSingle.java menunjukkan skenario dasar di mana Anda ingin menemukan deskripsi dokumen yang sangat cocok dengan string kueri vektor. VectorizedQuery mengonfigurasi pencarian vektor:

• setKNearestNeighborsCount() membatasi berapa banyak hasil yang dikembalikan berdasarkan kesamaan vektor.
• setFields() menentukan bidang vektor untuk dicari.

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

Pencarian vektor tunggal dengan filter

Dalam Pencarian Azure AI, filter berlaku untuk bidang nonvektor dalam indeks. SearchSingleWithFilter.java filter di kolom Tags untuk menghapus hotel yang tidak menyediakan Wi-Fi gratis.

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

Pencarian vektor tunggal dengan filter geografis

Anda dapat menentukan filter geo-spasial untuk membatasi hasil ke area geografis tertentu. SearchSingleWithGeoFilter.java menentukan titik geografis (Washington D.C., menggunakan koordinat bujur dan lintang) dan mengembalikan hotel dalam jarak 300 kilometer. Metode setFilterMode , dipanggil pada VectorSearchOptions, menentukan kapan filter berjalan. Dalam hal ini, POST_FILTER menjalankan filter setelah pencarian vektor.

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

Pencarian hibrid

Pencarian hibrid menggabungkan kueri teks lengkap dan vektor dalam satu permintaan. SearchHybrid.java menjalankan kedua jenis kueri secara bersamaan, lalu menggunakan Reciprocal Rank Fusion (RRF) untuk menggabungkan hasilnya ke dalam peringkat terpadu. RRF menggunakan inversi peringkat hasil dari setiap hasil yang ditetapkan untuk menghasilkan peringkat gabungan. Perhatikan bahwa skor pencarian hibrid sama-sama lebih kecil dari skor kueri tunggal.

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

Pencarian hibrid semantik

SearchSemanticHybrid.java menunjukkan peringkat semantik, yang melakukan rerank hasil berdasarkan pemahaman bahasa.

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

Bandingkan hasil ini dengan hasil pencarian hibrid dari kueri sebelumnya. Tanpa reranking semantik, Sublime Palace Hotel menempati peringkat pertama karena Reciprocal Rank Fusion (RRF) menggabungkan skor teks dan vektor untuk menghasilkan hasil gabungan. Setelah reranking semantik, Swirling Currents Hotel pindah ke tempat teratas.

Pemeringkat semantik menggunakan model pemahaman mesin untuk mengevaluasi seberapa baik setiap hasil cocok dengan niat kueri. Deskripsi Swirling Currents Hotel menyebutkan "walking access to shopping, dining, entertainment and the city center", yang selaras dengan kueri pencarian "walk to restaurants and shopping". Kecocokan semantik untuk bersantap dan berbelanja di dekatnya memposisikannya di atas Sublime Palace Hotel, yang tidak menekankan fasilitas yang bisa dicapai dengan berjalan kaki dalam deskripsinya.

Poin-poin penting:

• Dalam pencarian hibrid, Anda dapat mengintegrasikan pencarian vektor dengan pencarian teks lengkap melalui kata kunci. Filter dan peringkat semantik hanya berlaku untuk konten tekstual, bukan vektor.

• Hasil aktual mencakup detail lebih lanjut, termasuk keterangan semantik dan sorotan. Panduan cepat ini mengubah hasil agar lebih mudah dibaca. Untuk mendapatkan struktur respons lengkap, gunakan REST untuk menjalankan permintaan.

Membersihkan sumber daya

Saat Anda bekerja di langganan Anda sendiri, ada baiknya untuk menyelesaikan proyek dengan menghapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan berjalan dapat menyebabkan biaya tambahan.

Di portal Azure, pilih Semua sumber daya atau Kelompok sumber daya dari panel kiri untuk menemukan dan mengelola sumber daya. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus semua sumber daya sekaligus.

Jika tidak, jalankan perintah di bawah ini untuk menghapus indeks yang Anda buat dalam panduan mulai cepat ini.

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

Dalam mulai cepat ini, Anda menggunakan pustaka klien Pencarian Azure AI untuk JavaScript untuk membuat, memuat, dan mengkueri indeks vector. Pustaka klien JavaScript menyediakan abstraksi atas REST API untuk operasi indeks.

Dalam Pencarian Azure AI, indeks vektor memiliki skema indeks yang menentukan bidang vektor dan nonvektor, konfigurasi pencarian vektor untuk algoritma yang membuat ruang penyematan, dan pengaturan pada definisi bidang vektor yang dievaluasi pada waktu kueri. Indeks - Buat atau Perbarui (REST API) membuat indeks vektor.

Tips

• Ingin segera memulai? Unduh kode source di GitHub.
• Panduan cepat ini menghilangkan langkah vektorisasi dan menyediakan embedding langsung. Untuk vektorisasi terintegrasi atas konten Anda sendiri, coba wizard Impor data.

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.

• Layanan Pencarian Azure AI. Anda dapat menggunakan paket Gratis untuk sebagian besar Quickstart ini, tetapi kami merekomendasikan paket Dasar atau yang lebih tinggi untuk file data berukuran besar.

• Node.js 20 LTS atau yang lebih baru.

• Git untuk mengkloning repositori sampel.

• Azure CLI untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Pencarian Azure AI. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak dapat dilakukan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

2. Tetapkan peran berikut ke akun pengguna Anda.

   • Kontributor Layanan Pencarian

   • Kontributor Data Indeks Pencarian

   • Pembaca Indeks Data Pencarian

Dapatkan titik akhir

Setiap layanan Pencarian Azure AI memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

1. Buka layanan pencarian Anda di portal Azure.

2. Dari panel kiri, pilih Gambaran Umum.

3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Siapkan lingkungan

1. Gunakan Git untuk mengkloning repositori sampel.

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

2. Masuk ke folder panduan mulai cepat.

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

3. Di sample.env, ganti nilai tempat penampung untuk AZURE_SEARCH_ENDPOINT dengan URL yang Anda peroleh di Dapatkan titik akhir.

4. Ganti nama sample.env menjadi .env.

   mv sample.env .env
   

5. Pasang dependensi.

   npm install
   

   Ketika penginstalan selesai, Anda akan melihat node_modules folder di direktori proyek.

6. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Pencarian Azure AI Anda.

   az login
   

Jalankan kode

1. Buat indeks vektor.

   node -r dotenv/config src/createIndex.js
   

2. Muat dokumen yang berisi embedding yang telah dikomputasi sebelumnya.

   node -r dotenv/config src/uploadDocuments.js
   

3. Jalankan kueri pencarian vektor.

   node -r dotenv/config src/searchSingle.js
   

4. (Opsional) Lakukan variasi kueri tambahan.

   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
   

Keluaran

Output menunjukkan createIndex.js nama indeks dan konfirmasi.

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

Output uploadDocuments.js menunjukkan status keberhasilan setiap dokumen terindeks.

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.

Output searchSingle.js menunjukkan hasil pencarian vektor yang diberi peringkat berdasarkan skor kesamaan.

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

Memahami kode

Catatan

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

1. Membuat indeks vektor
2. Mengunggah dokumen ke indeks
3. Menjalankan kueri pada indeks

Membuat indeks vektor

Sebelum menambahkan konten ke Pencarian Azure AI, Anda harus membuat indeks untuk menentukan bagaimana konten disimpan dan terstruktur.

Skema indeks diatur di sekitar konten hotel. Data sampel terdiri dari deskripsi vektor dan nonvektor hotel fiktif. Kode berikut dalam createIndex.js membuat skema indeks, termasuk bidang DescriptionVectorvektor .

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

Poin-poin penting:

• Anda menentukan indeks dengan membuat daftar bidang.

• Indeks khusus ini mendukung beberapa kemampuan pencarian:

  • Pencarian teks lengkap (searchable: true)

  • Pencarian vektor (DescriptionVector dengan vectorSearchProfileName)

  • Peringkat semantik (semanticSearch)

  • Pencarian berfasis (bidang ditandai dengan facetable)

  • Pencarian geo-spasial (Location kolom dengan Edm.GeographyPoint)

  • Pemfilteran dan pengurutan (bidang ditandai dengan filterable dan sortable)

• Properti vectorSearchDimensions harus cocok dengan ukuran output model embedding Anda. Panduan Mulai Cepat ini menggunakan 1,536 dimensi untuk mencocokkan dengan model text-embedding-ada-002.

• Konfigurasi vectorSearch mendefinisikan algoritma Perkiraan Tetangga Terdekat (ANN). Algoritma yang didukung termasuk Hierarkis Navigable Small World (HNSW) dan K-Nearest Neighbor (KNN) yang lengkap. Untuk informasi selengkapnya, lihat Relevansi dalam pencarian vektor.

Mengunggah dokumen ke indeks

Indeks yang baru dibuat kosong. Untuk mengisi indeks dan membuatnya dapat dicari, Anda harus mengunggah dokumen JSON yang sesuai dengan skema indeks.

Dalam Pencarian Azure AI, dokumen berfungsi sebagai input untuk pengindeksan dan output untuk kueri. Untuk kemudahan, panduan cepat ini menyediakan dokumen contoh hotel dengan vektor yang telah dihitung sebelumnya. Dalam skenario produksi, konten sering ditarik dari sumber data yang terhubung dan diubah menjadi JSON menggunakan pengindeks.

Kode berikut dalam uploadDocuments.js mengunggah dokumen ke layanan pencarian Anda.

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

Kode Anda berinteraksi dengan indeks pencarian tertentu yang dihosting di layanan Pencarian Azure AI Anda melalui SearchClient, yang merupakan objek utama yang disediakan oleh paket @azure/search-documents. SearchClient menyediakan akses ke operasi indeks, seperti:

• Penyerapan data: uploadDocuments, mergeDocuments, deleteDocuments

• Operasi pencarian: search, autocomplete, suggest

Melakukan kueri pada indeks

Kueri dalam file pencarian menunjukkan pola pencarian yang berbeda. Contoh kueri vektor didasarkan pada dua string:

• String pencarian teks lengkap: "historic hotel walk to restaurants and shopping"

• String kueri vektor: "quintessential lodging near running trails, eateries, retail" (di-vektorisasi ke dalam representasi matematika)

String kueri vektor secara semantik mirip dengan string pencarian teks lengkap, tetapi menyertakan istilah yang tidak ada dalam indeks. Pencarian khusus kata kunci untuk string kueri vektor mengembalikan hasil nol. Namun, pencarian vektor menemukan kecocokan yang relevan berdasarkan arti daripada kata kunci yang tepat.

Contoh berikut dimulai dengan kueri vektor dasar dan secara progresif menambahkan filter, pencarian kata kunci, dan reranking semantik.

Pencarian vektor tunggal

searchSingle.js menunjukkan skenario dasar di mana Anda ingin menemukan deskripsi dokumen yang sangat cocok dengan string kueri vektor. Objek vectorQuery mengonfigurasi pencarian vektor:

• kNearestNeighborsCount membatasi berapa banyak hasil yang dikembalikan berdasarkan kesamaan vektor.
• fields menentukan bidang vektor untuk dicari.

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

Pencarian vektor tunggal dengan filter

Dalam Pencarian Azure AI, filter berlaku untuk bidang nonvektor dalam indeks. searchSingleWithFilter.js filter di kolom Tags untuk menghapus hotel yang tidak menyediakan Wi-Fi gratis.

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

Pencarian vektor tunggal dengan filter geografis

Anda dapat menentukan filter geo-spasial untuk membatasi hasil ke area geografis tertentu. searchSingleWithGeoFilter.js menentukan titik geografis (Washington D.C., menggunakan koordinat bujur dan lintang) dan mengembalikan hotel dalam jarak 300 kilometer. Properti filterMode menentukan kapan filter berjalan. Dalam hal ini, postFilter menjalankan filter setelah pencarian vektor.

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

Pencarian hibrid

Pencarian hibrid menggabungkan kueri teks lengkap dan vektor dalam satu permintaan. searchHybrid.js menjalankan kedua jenis kueri secara bersamaan, lalu menggunakan Reciprocal Rank Fusion (RRF) untuk menggabungkan hasilnya ke dalam peringkat terpadu. RRF menggunakan inversi peringkat hasil dari setiap hasil yang ditetapkan untuk menghasilkan peringkat gabungan. Perhatikan bahwa skor pencarian hibrid sama-sama lebih kecil dari skor kueri tunggal.

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

Pencarian hibrid semantik

searchSemanticHybrid.js menunjukkan peringkat semantik, yang melakukan rerank hasil berdasarkan pemahaman bahasa.

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

Bandingkan hasil ini dengan hasil pencarian hibrid dari kueri sebelumnya. Tanpa reranking semantik, Sublime Palace Hotel menempati peringkat pertama karena Reciprocal Rank Fusion (RRF) menggabungkan skor teks dan vektor untuk menghasilkan hasil gabungan. Setelah reranking semantik, Swirling Currents Hotel pindah ke tempat teratas.

Pemeringkat semantik menggunakan model pemahaman mesin untuk mengevaluasi seberapa baik setiap hasil cocok dengan niat kueri. Deskripsi Swirling Currents Hotel menyebutkan "walking access to shopping, dining, entertainment and the city center", yang selaras dengan kueri pencarian "walk to restaurants and shopping". Kecocokan semantik untuk bersantap dan berbelanja di dekatnya memposisikannya di atas Sublime Palace Hotel, yang tidak menekankan fasilitas yang bisa dicapai dengan berjalan kaki dalam deskripsinya.

Poin-poin penting:

• Dalam pencarian hibrid, Anda dapat mengintegrasikan pencarian vektor dengan pencarian teks lengkap melalui kata kunci. Filter dan peringkat semantik hanya berlaku untuk konten tekstual, bukan vektor.

• Hasil aktual mencakup detail lebih lanjut, termasuk keterangan semantik dan sorotan. Panduan cepat ini mengubah hasil agar lebih mudah dibaca. Untuk mendapatkan struktur respons lengkap, gunakan REST untuk menjalankan permintaan.

Membersihkan sumber daya

Saat Anda bekerja di langganan Anda sendiri, ada baiknya untuk menyelesaikan proyek dengan menghapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan berjalan dapat menyebabkan biaya tambahan.

Di portal Azure, pilih Semua sumber daya atau Kelompok sumber daya dari panel kiri untuk menemukan dan mengelola sumber daya. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus semua sumber daya sekaligus.

Jika tidak, jalankan perintah di bawah ini untuk menghapus indeks yang Anda buat dalam panduan mulai cepat ini.

node -r dotenv/config src/deleteIndex.js

Dalam panduan memulai cepat ini, Anda menggunakan pustaka klien Pencarian Azure AI untuk Python untuk membuat, memuat, dan mengkueri indeks vektor. Pustaka klien Python menyediakan abstraksi atas REST API untuk operasi indeks.

Dalam Pencarian Azure AI, indeks vektor memiliki skema indeks yang menentukan bidang vektor dan nonvektor, konfigurasi pencarian vektor untuk algoritma yang membuat ruang penyematan, dan pengaturan pada definisi bidang vektor yang dievaluasi pada waktu kueri. Indeks - Buat atau Perbarui (REST API) membuat indeks vektor.

Tips

• Ingin segera memulai? Unduh kode source di GitHub.
• Panduan cepat ini menghilangkan langkah vektorisasi dan menyediakan embedding langsung. Untuk vektorisasi terintegrasi atas konten Anda sendiri, coba wizard Impor data.

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.

• Layanan Pencarian Azure AI. Anda dapat menggunakan paket Gratis untuk sebagian besar Quickstart ini, tetapi kami merekomendasikan paket Dasar atau yang lebih tinggi untuk file data berukuran besar.

• Python 3.8 atau yang lebih baru.

• Visual Studio Code dengan ekstensi Python dan Jupyter.

• Git untuk mengkloning repositori sampel.

• Azure CLI untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Pencarian Azure AI. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak dapat dilakukan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

2. Tetapkan peran berikut ke akun pengguna Anda.

   • Kontributor Layanan Pencarian

   • Kontributor Data Indeks Pencarian

   • Pembaca Indeks Data Pencarian

Dapatkan titik akhir

Setiap layanan Pencarian Azure AI memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

1. Buka layanan pencarian Anda di portal Azure.

2. Dari panel kiri, pilih Gambaran Umum.

3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Siapkan lingkungan

1. Gunakan Git untuk mengkloning repositori sampel.

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

2. Arahkan ke folder quickstart dan buka di Visual Studio Code.

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

3. Di sample.env, ganti nilai tempat penampung untuk AZURE_SEARCH_ENDPOINT dengan URL yang Anda peroleh di Dapatkan titik akhir.

4. Ganti nama sample.env menjadi .env.

   mv sample.env .env
   

5. Buka vector-search-quickstart.ipynb.

6. Tekan Ctrl+Shift+P, pilih Notebook: Pilih Notebook Kernel, dan ikuti perintah untuk membuat lingkungan virtual. Pilih requirements.txt untuk dependensi.

   Setelah selesai, Anda akan melihat .venv folder di direktori proyek.

7. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Pencarian Azure AI Anda.

   az login
   

Jalankan kode

1. Jalankan Install packages and set variables sel untuk menginstal paket yang diperlukan dan memuat variabel lingkungan.

2. Jalankan sel yang tersisa secara berurutan untuk membuat indeks vektor, mengunggah dokumen, dan menjalankan berbagai jenis kueri vektor.

Keluaran

Setiap sel kode mencetak outputnya ke buku catatan. Contoh berikut adalah output , Single vector searchyang menunjukkan hasil pencarian vektor yang diberi peringkat oleh skor kesamaan.

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

Memahami kode

Catatan

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

1. Membuat indeks vektor
2. Mengunggah dokumen ke indeks
3. Melakukan pencarian pada indeks

Membuat indeks vektor

Sebelum menambahkan konten ke Pencarian Azure AI, Anda harus membuat indeks untuk menentukan bagaimana konten disimpan dan terstruktur.

Skema indeks diatur di sekitar konten hotel. Data sampel terdiri dari deskripsi vektor dan nonvektor hotel fiktif. Sel Create an index dalam notebook membuat skema indeks, termasuk bidang DescriptionVector vektor.

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
]

Poin-poin Penting:

• Anda menentukan indeks dengan membuat daftar bidang. Setiap bidang dibuat menggunakan metode pembantu yang menentukan jenis bidang dan pengaturannya.

• Indeks khusus ini mendukung beberapa kemampuan pencarian:

  • Pencarian teks lengkap (SearchableField)

  • Pencarian vektor (DescriptionVector dengan vector_search_profile_name)

  • Peringkat semantik (SemanticConfiguration)

  • Pencarian berfasilitas (bidang ditandai dengan facetable)

  • Pencarian geo-spasial (Location kolom dengan SearchFieldDataType.GeographyPoint)

  • Pemfilteran dan pengurutan (bidang ditandai dengan filterable dan sortable)

• Properti vector_search_dimensions harus cocok dengan ukuran output model embedding Anda. Mulai cepat ini menggunakan 1.536 dimensi agar sesuai dengan model text-embedding-ada-002.

• Konfigurasi VectorSearch mendefinisikan algoritma Perkiraan Tetangga Terdekat (ANN). Algoritma yang didukung termasuk Hierarki yang Dapat Dinavigasi Small World (HNSW) dan K-Nearest Neighbor (KNN) yang ekstensif. Untuk informasi selengkapnya, lihat Relevansi dalam pencarian vektor.

Mengunggah dokumen ke indeks

Indeks yang baru dibuat kosong. Untuk mengisi indeks dan membuatnya dapat dicari, Anda harus mengunggah dokumen JSON yang sesuai dengan skema indeks.

Dalam Pencarian Azure AI, dokumen berfungsi sebagai input untuk pengindeksan dan output untuk kueri. Untuk kesederhanaan, mulai cepat ini menyediakan contoh dokumen hotel dengan vektor yang telah dikomputasi sebelumnya. Dalam skenario produksi, konten sering ditarik dari sumber data yang terhubung dan diubah menjadi JSON menggunakan pengindeks.

Sel Create documents payload dan Upload the documents memuat dokumen ke dalam indeks.

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

Kode Anda berinteraksi dengan indeks pencarian tertentu yang dihosting di layanan Pencarian Azure AI Anda melalui SearchClient, yang merupakan objek utama yang disediakan oleh paket azure-search-documents. SearchClient menyediakan akses ke operasi indeks, seperti:

• Penyerapan data: upload_documents(), merge_documents(), delete_documents()

• Operasi pencarian: search(), autocomplete(), suggest()

Melakukan kueri pada indeks

Kueri dalam buku catatan menunjukkan pola pencarian yang berbeda. Contoh kueri vektor didasarkan pada dua string:

• String pencarian teks lengkap: "historic hotel walk to restaurants and shopping"

• String kueri vektor: "quintessential lodging near running trails, eateries, retail" (di-vektorisasi ke dalam representasi matematika)

String kueri vektor secara semantik mirip dengan string pencarian teks lengkap, tetapi menyertakan istilah yang tidak ada dalam indeks. Pencarian khusus kata kunci untuk string kueri vektor mengembalikan hasil nol. Namun, pencarian vektor menemukan kecocokan yang relevan berdasarkan arti daripada kata kunci yang tepat.

Contoh berikut dimulai dengan kueri vektor dasar dan secara progresif menambahkan filter, pencarian kata kunci, dan reranking semantik.

Pencarian vektor tunggal

Sel Single vector search menunjukkan skenario dasar di mana Anda ingin menemukan deskripsi dokumen yang sangat cocok dengan string kueri vektor. VectorizedQuery mengonfigurasi pencarian vektor:

• k_nearest_neighbors membatasi berapa banyak hasil yang dikembalikan berdasarkan kesamaan vektor.
• fields menentukan bidang vektor untuk dicari.

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
)

Pencarian vektor tunggal dengan filter

Dalam Pencarian Azure AI, filter berlaku untuk bidang nonvektor dalam indeks. Filter pada sel Single vector search with filter di kolom Tags untuk menyaring hotel mana pun yang tidak menyediakan Wi-Fi gratis.

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

Pencarian vektor tunggal dengan filter geografis

Anda dapat menentukan filter geo-spasial untuk membatasi hasil ke area geografis tertentu. Sel Single vector search with geo filter menentukan titik geografis (Washington D.C., menggunakan koordinat bujur dan lintang) dan mengembalikan hotel dalam jarak 300 kilometer. Parameter vector_filter_mode menentukan kapan filter berjalan. Dalam hal ini, postFilter menjalankan filter setelah pencarian vektor.

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

Pencarian hibrid

Pencarian hibrid menggabungkan kueri teks lengkap dan vektor dalam satu permintaan. Sel Hybrid search menjalankan kedua jenis kueri secara bersamaan, lalu menggunakan Reciprocal Rank Fusion (RRF) untuk menggabungkan hasil ke dalam peringkat terpadu. RRF menggunakan inversi peringkat hasil dari setiap hasil yang ditetapkan untuk menghasilkan peringkat gabungan. Perhatikan bahwa skor pencarian hibrid sama-sama lebih kecil dari skor kueri tunggal.

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

Pencarian hibrid semantik

Sel Semantic hybrid search menunjukkan peringkat semantik, yang melakukan rerank hasil berdasarkan pemahaman bahasa.

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

Bandingkan hasil ini dengan hasil pencarian hibrid dari kueri sebelumnya. Tanpa reranking semantik, Sublime Palace Hotel menempati peringkat pertama karena Reciprocal Rank Fusion (RRF) menggabungkan skor teks dan vektor untuk menghasilkan hasil gabungan. Setelah reranking semantik, Swirling Currents Hotel pindah ke tempat teratas.

Pemeringkat semantik menggunakan model pemahaman mesin untuk mengevaluasi seberapa baik setiap hasil cocok dengan niat kueri. Deskripsi Swirling Currents Hotel menyebutkan "walking access to shopping, dining, entertainment and the city center", yang selaras dengan kueri pencarian "walk to restaurants and shopping". Kecocokan semantik untuk bersantap dan berbelanja di dekatnya memposisikannya di atas Sublime Palace Hotel, yang tidak menekankan fasilitas yang bisa dicapai dengan berjalan kaki dalam deskripsinya.

Poin-poin penting:

• Dalam pencarian hibrid, Anda dapat mengintegrasikan pencarian vektor dengan pencarian teks lengkap melalui kata kunci. Filter dan peringkat semantik hanya berlaku untuk konten tekstual, bukan vektor.

• Hasil aktual mencakup detail lebih lanjut, termasuk keterangan semantik dan sorotan. Panduan cepat ini mengubah hasil agar lebih mudah dibaca. Untuk mendapatkan struktur respons lengkap, gunakan REST untuk menjalankan permintaan.

Membersihkan sumber daya

Saat Anda bekerja di langganan Anda sendiri, ada baiknya untuk menyelesaikan proyek dengan menghapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan berjalan dapat menyebabkan biaya tambahan.

Di portal Azure, pilih Semua sumber daya atau Kelompok sumber daya dari panel kiri untuk menemukan dan mengelola sumber daya. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus semua sumber daya sekaligus.

Jika tidak, Anda dapat menjalankan Clean up sel kode untuk menghapus indeks yang Anda buat dalam panduan cepat ini.

Dalam Panduan Memulai Cepat ini, Anda menggunakan pustaka klien Pencarian Azure AI untuk JavaScript (kompatibel dengan TypeScript) untuk membuat, memuat, dan mengkueri indeks vektor. Pustaka klien JavaScript menyediakan abstraksi atas REST API untuk operasi indeks.

Dalam Pencarian Azure AI, indeks vektor memiliki skema indeks yang menentukan bidang vektor dan nonvektor, konfigurasi pencarian vektor untuk algoritma yang membuat ruang penyematan, dan pengaturan pada definisi bidang vektor yang dievaluasi pada waktu kueri. Indeks - Buat atau Perbarui (REST API) membuat indeks vektor.

Tips

• Ingin segera memulai? Unduh kode source di GitHub.
• Panduan cepat ini menghilangkan langkah vektorisasi dan menyediakan embedding langsung. Untuk vektorisasi terintegrasi atas konten Anda sendiri, coba wizard Impor data.

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.

• Layanan Pencarian Azure AI. Anda dapat menggunakan paket Gratis untuk sebagian besar Quickstart ini, tetapi kami merekomendasikan paket Dasar atau yang lebih tinggi untuk file data berukuran besar.

• Node.js 20 LTS atau yang lebih baru untuk menjalankan kode yang dikompilasi.

• TypeScript untuk mengkompilasi TypeScript ke JavaScript.

• Git untuk mengkloning repositori sampel.

• Azure CLI untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Pencarian Azure AI. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak dapat dilakukan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

2. Tetapkan peran berikut ke akun pengguna Anda.

   • Kontributor Layanan Pencarian

   • Kontributor Data Indeks Pencarian

   • Pembaca Indeks Data Pencarian

Dapatkan titik akhir

Setiap layanan Pencarian Azure AI memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

1. Buka layanan pencarian Anda di portal Azure.

2. Dari panel kiri, pilih Gambaran Umum.

3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Siapkan lingkungan

1. Gunakan Git untuk mengkloning repositori sampel.

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

2. Masuk ke folder panduan mulai cepat.

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

3. Di sample.env, ganti nilai tempat penampung untuk AZURE_SEARCH_ENDPOINT dengan URL yang Anda peroleh di Dapatkan titik akhir.

4. Ganti nama sample.env menjadi .env.

   mv sample.env .env
   

5. Pasang dependensi.

   npm install
   

   Ketika penginstalan selesai, Anda akan melihat node_modules folder di direktori proyek.

6. Kompilasi file TypeScript ke JavaScript.

   npm run build
   

7. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Pencarian Azure AI Anda.

   az login
   

Jalankan kode

1. Buat indeks vektor.

   node -r dotenv/config dist/createIndex.js
   

2. Muat dokumen yang berisi embedding yang telah dikomputasi sebelumnya.

   node -r dotenv/config dist/uploadDocuments.js
   

3. Jalankan kueri pencarian vektor.

   node -r dotenv/config dist/searchSingle.js
   

4. (Opsional) Lakukan variasi kueri tambahan.

   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
   

   Catatan

   Perintah ini menjalankan file yang dikompilasi .js dari dist folder. Kode TypeScript harus ditranspilasi ke JavaScript sebelum Node.js dapat menjalankannya, itulah sebabnya Anda sebelumnya menjalankan npm run build.

Keluaran

Output menunjukkan createIndex.ts nama indeks dan konfirmasi.

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

Output uploadDocuments.ts menunjukkan status keberhasilan setiap dokumen terindeks.

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.

Output searchSingle.ts menunjukkan hasil pencarian vektor yang diberi peringkat berdasarkan skor kesamaan.

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

Memahami kode

Catatan

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

1. Membuat indeks vektor
2. Mengunggah dokumen ke indeks
3. Menjalankan kueri pada indeks

Membuat indeks vektor

Sebelum menambahkan konten ke Pencarian Azure AI, Anda harus membuat indeks untuk menentukan bagaimana konten disimpan dan terstruktur.

Skema indeks diatur di sekitar konten hotel. Data sampel terdiri dari deskripsi vektor dan nonvektor hotel fiktif. Kode berikut dalam createIndex.ts membuat skema indeks, termasuk bidang DescriptionVectorvektor .

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

Poin-poin penting:

• Anda menentukan indeks dengan membuat daftar bidang.

• Indeks khusus ini mendukung beberapa kemampuan pencarian:

  • Pencarian teks lengkap (searchable: true)

  • Pencarian vektor (DescriptionVector dengan vectorSearchProfileName)

  • Peringkat semantik (semanticSearch)

  • Pencarian berfasis (bidang ditandai dengan facetable)

  • Pencarian geo-spasial (Location kolom dengan Edm.GeographyPoint)

  • Pemfilteran dan pengurutan (bidang ditandai dengan filterable dan sortable)

• Properti vectorSearchDimensions harus cocok dengan ukuran output model embedding Anda. Panduan Mulai Cepat ini menggunakan 1,536 dimensi untuk mencocokkan dengan model text-embedding-ada-002.

• Konfigurasi vectorSearch mendefinisikan algoritma Perkiraan Tetangga Terdekat (ANN). Algoritma yang didukung termasuk Hierarkis Navigable Small World (HNSW) dan K-Nearest Neighbor (KNN) yang lengkap. Untuk informasi selengkapnya, lihat Relevansi dalam pencarian vektor.

Mengunggah dokumen ke indeks

Indeks yang baru dibuat kosong. Untuk mengisi indeks dan membuatnya dapat dicari, Anda harus mengunggah dokumen JSON yang sesuai dengan skema indeks.

Dalam Pencarian Azure AI, dokumen berfungsi sebagai input untuk pengindeksan dan output untuk kueri. Untuk kemudahan, panduan cepat ini menyediakan dokumen contoh hotel dengan vektor yang telah dihitung sebelumnya. Dalam skenario produksi, konten sering ditarik dari sumber data yang terhubung dan diubah menjadi JSON menggunakan pengindeks.

Kode berikut dalam uploadDocuments.ts mengunggah dokumen ke layanan pencarian Anda.

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

Kode Anda berinteraksi dengan indeks pencarian tertentu yang dihosting di layanan Pencarian Azure AI Anda melalui SearchClient, yang merupakan objek utama yang disediakan oleh paket @azure/search-documents. SearchClient menyediakan akses ke operasi indeks, seperti:

• Penyerapan data: uploadDocuments, mergeDocuments, deleteDocuments

• Operasi pencarian: search, autocomplete, suggest

Melakukan kueri pada indeks

Kueri dalam file pencarian menunjukkan pola pencarian yang berbeda. Contoh kueri vektor didasarkan pada dua string:

• String pencarian teks lengkap: "historic hotel walk to restaurants and shopping"

• String kueri vektor: "quintessential lodging near running trails, eateries, retail" (di-vektorisasi ke dalam representasi matematika)

String kueri vektor secara semantik mirip dengan string pencarian teks lengkap, tetapi menyertakan istilah yang tidak ada dalam indeks. Pencarian khusus kata kunci untuk string kueri vektor mengembalikan hasil nol. Namun, pencarian vektor menemukan kecocokan yang relevan berdasarkan arti daripada kata kunci yang tepat.

Contoh berikut dimulai dengan kueri vektor dasar dan secara progresif menambahkan filter, pencarian kata kunci, dan reranking semantik.

Pencarian vektor tunggal

searchSingle.ts menunjukkan skenario dasar di mana Anda ingin menemukan deskripsi dokumen yang sangat cocok dengan string kueri vektor. Objek VectorQuery mengonfigurasi pencarian vektor:

• kNearestNeighborsCount membatasi berapa banyak hasil yang dikembalikan berdasarkan kesamaan vektor.
• fields menentukan bidang vektor untuk dicari.

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

Pencarian vektor tunggal dengan filter

Dalam Pencarian Azure AI, filter berlaku untuk bidang nonvektor dalam indeks. searchSingleWithFilter.ts filter di kolom Tags untuk menghapus hotel yang tidak menyediakan Wi-Fi gratis.

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

Pencarian vektor tunggal dengan filter geografis

Anda dapat menentukan filter geo-spasial untuk membatasi hasil ke area geografis tertentu. searchSingleWithGeoFilter.ts menentukan titik geografis (Washington D.C., menggunakan koordinat bujur dan lintang) dan mengembalikan hotel dalam jarak 300 kilometer. Properti filterMode menentukan kapan filter berjalan. Dalam hal ini, postFilter menjalankan filter setelah pencarian vektor.

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

Pencarian hibrid

Pencarian hibrid menggabungkan kueri teks lengkap dan vektor dalam satu permintaan. searchHybrid.ts menjalankan kedua jenis kueri secara bersamaan, lalu menggunakan Reciprocal Rank Fusion (RRF) untuk menggabungkan hasilnya ke dalam peringkat terpadu. RRF menggunakan inversi peringkat hasil dari setiap hasil yang ditetapkan untuk menghasilkan peringkat gabungan. Perhatikan bahwa skor pencarian hibrid sama-sama lebih kecil dari skor kueri tunggal.

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

Pencarian hibrid semantik

searchSemanticHybrid.ts menunjukkan peringkat semantik, yang melakukan rerank hasil berdasarkan pemahaman bahasa.

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

Bandingkan hasil ini dengan hasil pencarian hibrid dari kueri sebelumnya. Tanpa reranking semantik, Sublime Palace Hotel menempati peringkat pertama karena Reciprocal Rank Fusion (RRF) menggabungkan skor teks dan vektor untuk menghasilkan hasil gabungan. Setelah reranking semantik, Swirling Currents Hotel pindah ke tempat teratas.

Pemeringkat semantik menggunakan model pemahaman mesin untuk mengevaluasi seberapa baik setiap hasil cocok dengan niat kueri. Deskripsi Swirling Currents Hotel menyebutkan "walking access to shopping, dining, entertainment and the city center", yang selaras dengan kueri pencarian "walk to restaurants and shopping". Kecocokan semantik untuk bersantap dan berbelanja di dekatnya memposisikannya di atas Sublime Palace Hotel, yang tidak menekankan fasilitas yang bisa dicapai dengan berjalan kaki dalam deskripsinya.

Poin-poin penting:

• Dalam pencarian hibrid, Anda dapat mengintegrasikan pencarian vektor dengan pencarian teks lengkap melalui kata kunci. Filter dan peringkat semantik hanya berlaku untuk konten tekstual, bukan vektor.

• Hasil aktual mencakup detail lebih lanjut, termasuk keterangan semantik dan sorotan. Panduan cepat ini mengubah hasil agar lebih mudah dibaca. Untuk mendapatkan struktur respons lengkap, gunakan REST untuk menjalankan permintaan.

Membersihkan sumber daya

Saat Anda bekerja di langganan Anda sendiri, ada baiknya untuk menyelesaikan proyek dengan menghapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan berjalan dapat menyebabkan biaya tambahan.

Di portal Azure, pilih Semua sumber daya atau Kelompok sumber daya dari panel kiri untuk menemukan dan mengelola sumber daya. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus semua sumber daya sekaligus.

Jika tidak, jalankan perintah di bawah ini untuk menghapus indeks yang Anda buat dalam panduan mulai cepat ini.

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

Dalam panduan cepat ini, Anda menggunakan API REST Pencarian Azure AI untuk membuat, memuat, dan mengkueri indeks vektor.

Dalam Pencarian Azure AI, indeks vektor memiliki skema indeks yang menentukan bidang vektor dan nonvektor, konfigurasi pencarian vektor untuk algoritma yang membuat ruang penyematan, dan pengaturan pada definisi bidang vektor yang dievaluasi pada waktu kueri. Indeks - Buat atau Perbarui (REST API) membuat indeks vektor.

Tips

• Ingin segera memulai? Unduh kode source di GitHub.
• Panduan cepat ini menghilangkan langkah vektorisasi dan menyediakan embedding langsung. Untuk vektorisasi terintegrasi atas konten Anda sendiri, coba wizard Impor data.

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.

• Layanan Pencarian Azure AI. Anda dapat menggunakan paket Gratis untuk sebagian besar Quickstart ini, tetapi kami merekomendasikan paket Dasar atau yang lebih tinggi untuk file data berukuran besar.

• Visual Studio Code dengan ekstensi Klien REST.

• Git untuk mengkloning repositori sampel.

• Azure CLI untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Pencarian Azure AI. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak dapat dilakukan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

2. Tetapkan peran berikut ke akun pengguna Anda.

   • Kontributor Layanan Pencarian

   • Kontributor Data Indeks Pencarian

   • Pembaca Indeks Data Pencarian

Dapatkan titik akhir

Setiap layanan Pencarian Azure AI memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

1. Buka layanan pencarian Anda di portal Azure.

2. Dari panel kiri, pilih Gambaran Umum.

3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Siapkan lingkungan

1. Gunakan Git untuk mengkloning repositori sampel.

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

2. Arahkan ke folder quickstart dan buka di Visual Studio Code.

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

3. Di az-search-quickstart-vectors.rest, ganti nilai tempat penampung untuk @baseUrl dengan URL yang Anda peroleh di Dapatkan titik akhir.

4. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Pencarian Azure AI Anda.

   az login
   

5. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, buat token akses.

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

6. Ganti nilai tempat penampung untuk @token dengan token dari langkah sebelumnya.

Jalankan kode

1. Di bawah ### List existing indexes by name, pilih Kirim Permintaan untuk memverifikasi koneksi Anda.

   Respons akan muncul di panel yang berdekatan. Jika Anda memiliki indeks yang sudah ada, indeks tersebut akan dicantumkan. Jika tidak, daftar kosong. Jika kode HTTP adalah 200 OK, Anda siap untuk melanjutkan.

2. Kirim permintaan yang tersisa secara berurutan untuk membuat indeks vektor, mengunggah dokumen, dan menjalankan berbagai jenis kueri vektor.

Keluaran

Setiap permintaan kueri mengembalikan hasil JSON. Contoh berikut adalah output permintaan ### Run a single vector query, yang menunjukkan hasil pencarian vektor yang diperingkat berdasarkan skor kesamaan.

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

Memahami kode

Catatan

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

1. Membuat indeks vektor
2. Mengunggah dokumen ke indeks
3. Menjalankan kueri pada indeks

Membuat indeks vektor

Sebelum menambahkan konten ke Pencarian Azure AI, Anda harus membuat indeks untuk menentukan bagaimana konten disimpan dan terstruktur. Mulai cepat ini memanggil Indeks - Buat (REST API) untuk membangun indeks vektor bernama hotels-vector-quickstart dan struktur data fisiknya pada layanan pencarian Anda.

Skema indeks diatur di sekitar konten hotel. Data sampel terdiri dari deskripsi vektor dan nonvektor hotel fiktif. Kutipan berikut menunjukkan struktur utama dari permintaan ### 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" }]
                }
            }
        ]
    }
}

Poin-poin penting:

• Indeks khusus ini mendukung beberapa kemampuan pencarian:

  • Pencarian teks lengkap (bidang dengan searchable diatur ke true)

  • Pencarian vektor (DescriptionVector dengan vectorSearchProfile)

  • Peringkat semantik (semantic konfigurasi)

  • Pencarian tersaring (bidang dengan facetable diatur ke true)

  • Pencarian geo-spasial (Location kolom dengan Edm.GeographyPoint)

  • Pemfilteran dan pengurutan (bidang yang diatur dengan filterable dan sortable ke true)

• Properti dimensions harus cocok dengan ukuran output model embedding Anda. Panduan Mulai Cepat ini menggunakan 1,536 dimensi untuk mencocokkan dengan model text-embedding-ada-002.

• Bagian vectorSearch ini mendefinisikan algoritma Perkiraan Tetangga Dekat (ANN). Algoritma yang didukung termasuk Hierarkis Navigable Small World (HNSW) dan K-Nearest Neighbor (KNN) yang lengkap. Untuk informasi selengkapnya, lihat Relevansi dalam pencarian vektor.

Mengunggah dokumen ke indeks

Indeks yang baru dibuat kosong. Untuk mengisi indeks dan membuatnya dapat dicari, Anda harus mengunggah dokumen JSON yang sesuai dengan skema indeks.

Dalam Pencarian Azure AI, dokumen berfungsi sebagai input untuk pengindeksan dan output untuk kueri. Untuk kesederhanaan, panduan cepat ini menyediakan contoh dokumen hotel dalam bentuk JSON sebaris. Namun, dalam skenario produksi, konten sering ditarik dari sumber data yang terhubung dan diubah menjadi JSON menggunakan pengindeks.

Mulai cepat ini memanggil Dokumen - Indeks (REST API) untuk menambahkan dokumen hotel sampel ke indeks Anda. Kutipan berikut menunjukkan struktur ### Upload 7 documents permintaan.

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

Poin-poin penting:

• Setiap dokumen dalam value array mewakili hotel dan berisi bidang yang cocok dengan skema indeks. Parameter @search.action menentukan operasi yang akan dilakukan untuk setiap dokumen. Panduan memulai cepat ini menggunakan mergeOrUpload, yang menambah dokumen jika tidak ada atau memperbarui dokumen jika memang ada.

• Dokumen dalam payload terdiri dari bidang yang ditentukan dalam skema indeks.

Melakukan kueri pada indeks

Kueri dalam file sampel menunjukkan pola pencarian yang berbeda. Contoh kueri vektor didasarkan pada dua string:

• String pencarian teks lengkap: "historic hotel walk to restaurants and shopping"

• String kueri vektor: "quintessential lodging near running trails, eateries, retail" (di-vektorisasi ke dalam representasi matematika)

String kueri vektor secara semantik mirip dengan string pencarian teks lengkap, tetapi menyertakan istilah yang tidak ada dalam indeks. Pencarian khusus kata kunci untuk string kueri vektor mengembalikan hasil nol. Namun, pencarian vektor menemukan kecocokan yang relevan berdasarkan arti daripada kata kunci yang tepat.

Contoh berikut dimulai dengan kueri vektor dasar dan secara progresif menambahkan filter, pencarian kata kunci, dan reranking semantik.

Pencarian vektor tunggal

Permintaan ### Run a single vector query ini menunjukkan skenario sederhana di mana Anda ingin menemukan deskripsi dokumen yang sesuai erat dengan string kueri vektor. Array vectorQueries mengonfigurasi pencarian vektor:

• k membatasi berapa banyak hasil yang dikembalikan berdasarkan kesamaan vektor.
• fields menentukan bidang vektor untuk dicari.

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

Pencarian vektor tunggal dengan filter

Dalam Pencarian Azure AI, filter berlaku untuk bidang nonvektor dalam indeks. Permintaan ### Run a vector query with a filter memfilter bidang Tags untuk menghilangkan hotel yang tidak menyediakan Wi-Fi gratis.

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

Pencarian vektor tunggal dengan filter geografis

Anda dapat menentukan filter geo-spasial untuk membatasi hasil ke area geografis tertentu. Permintaan mencakup titik geografis ### Run a vector query with a geo filter (Washington D.C., menggunakan koordinat bujur dan lintang) dan akan mengembalikan hotel dalam radius 300 kilometer. Parameter vectorFilterMode menentukan kapan filter berjalan. Dalam hal ini, postFilter menjalankan filter setelah pencarian vektor.

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

Pencarian hibrid

Pencarian hibrid menggabungkan kueri teks lengkap dan vektor dalam satu permintaan. Permintaan ### Run a hybrid query menjalankan kedua jenis kueri secara bersamaan, lalu menggunakan Reciprocal Rank Fusion (RRF) untuk menggabungkan hasilnya ke dalam peringkat terpadu. RRF menggunakan inversi peringkat hasil dari setiap hasil yang ditetapkan untuk menghasilkan peringkat gabungan. Perhatikan bahwa skor pencarian hibrid sama-sama lebih kecil dari skor kueri tunggal.

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

Pencarian hibrid semantik

Permintaan ### Run a hybrid query with semantic reranking menunjukkan peringkat semantik, yang mengurutkan ulang hasil berdasarkan pemahaman bahasa.

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

Bandingkan hasil ini dengan hasil pencarian hibrid dari kueri sebelumnya. Tanpa reranking semantik, Sublime Palace Hotel menempati peringkat pertama karena Reciprocal Rank Fusion (RRF) menggabungkan skor teks dan vektor untuk menghasilkan hasil gabungan. Setelah reranking semantik, Swirling Currents Hotel pindah ke tempat teratas.

Pemeringkat semantik menggunakan model pemahaman mesin untuk mengevaluasi seberapa baik setiap hasil cocok dengan niat kueri. Deskripsi Swirling Currents Hotel menyebutkan "walking access to shopping, dining, entertainment and the city center", yang selaras dengan kueri pencarian "walk to restaurants and shopping". Kecocokan semantik untuk bersantap dan berbelanja di dekatnya memposisikannya di atas Sublime Palace Hotel, yang tidak menekankan fasilitas yang bisa dicapai dengan berjalan kaki dalam deskripsinya.

Poin-poin penting:

• Dalam pencarian hibrid, Anda dapat mengintegrasikan pencarian vektor dengan pencarian teks lengkap melalui kata kunci. Filter dan peringkat semantik hanya berlaku untuk konten tekstual, bukan vektor.

Membersihkan sumber daya

Saat Anda bekerja di langganan Anda sendiri, ada baiknya untuk menyelesaikan proyek dengan menghapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan berjalan dapat menyebabkan biaya tambahan.

Di portal Azure, pilih Semua sumber daya atau Kelompok sumber daya dari panel kiri untuk menemukan dan mengelola sumber daya. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus semua sumber daya sekaligus.

Jika tidak, Anda dapat mengirim permintaan ### Delete an index untuk menghapus indeks yang Anda buat dalam tutorial singkat ini.

Konten terkait

• Pencarian vektor di Pencarian Azure AI
• azure-search-vector-samples GitHub repositori