Bagikan melalui

Menambahkan lengkapi otomatis dan mencari saran di aplikasi klien

  • Artikel

Cari selagi Anda mengetik adalah teknik umum untuk meningkatkan produktivitas kueri. Dalam Azure AI Search, pengalaman ini didukung melalui lengkapi otomatis, yang menyelesaikan istilah atau frasa berdasarkan input parsial (misalnya, menyelesaikan mikro dengan microchip, mikroskop, microsoft, dan kecocokan mikro lainnya). Pengalaman pengguna kedua adalah saran, yang menghasilkan daftar pendek dokumen yang cocok (misalnya, mengembalikan judul buku dengan ID sehingga Anda dapat menautkan ke halaman detail tentang buku tersebut). Baik lengkapi otomatis dan saran dipredikatkan pada kecocokan dalam indeks. Layanan ini tidak menawarkan kueri atau saran yang lengkapi otomatis yang mengembalikan hasil nol.

Untuk menerapkan pengalaman ini di Azure AI Search:

  • suggester Tambahkan ke skema indeks.
  • Buat kueri yang memanggil API Lengkapi Otomatis atau API Saran pada permintaan.
  • Tambahkan kontrol UI untuk menangani interaksi search-as-you-type di aplikasi klien Anda. Kami merekomendasikan untuk menggunakan pustaka JavaScript yang ada untuk tujuan ini.

Di Azure AI Search, kueri yang dilengkapi otomatis dan hasil yang disarankan diambil dari indeks pencarian, dari bidang yang dipilih yang Anda daftarkan dengan pemberi saran. Pemberi saran adalah bagian dari indeks, dan menentukan bidang mana yang menyediakan konten yang menyelesaikan kueri, menyarankan hasil, atau melakukan keduanya. Saat indeks dibuat dan dimuat, struktur data saran dibuat secara internal untuk menyimpan awalan yang digunakan untuk pencocokan pada kueri parsial. Untuk saran, memilih bidang unik yang cocok, atau setidaknya tidak berulang, sangat penting untuk pengalaman. Untuk informasi selengkapnya, lihat Mengonfigurasi pemberi saran.

Sisa artikel ini difokuskan pada kueri dan kode klien. Ini menggunakan JavaScript dan C# untuk mengilustrasikan poin-poin penting. Contoh REST API digunakan untuk secara ringkas menyajikan setiap operasi. Untuk sampel kode end-to-end, lihat Menambahkan pencarian ke situs web dengan .NET.

Siapkan permintaan

Elemen permintaan menyertakan salah satu API mencari selagi Anda mengetik, kueri parsial, dan saran. Skrip berikut ini mengilustrasikan komponen permintaan, menggunakan Lengkapi Otomatis REST API sebagai contoh.

POST /indexes/myxboxgames/docs/autocomplete?search&api-version=2024-07-01
{
  "search": "minecraf",
  "suggesterName": "sg"
}

Parameter suggesterName memberi Anda bidang sadar saran yang digunakan untuk menyelesaikan istilah atau saran. Untuk saran khususnya, daftar bidang harus terdiri dari saran yang menawarkan pilihan yang jelas di antara hasil yang cocok. Di situs yang menjual game komputer, bidang tersebut mungkin adalah judul game.

Parameter search menyediakan kueri parsial, di mana karakter diumpankan ke permintaan kueri melalui kontrol jQuery Autocomplete. Dalam contoh sebelumnya, minecraf adalah ilustrasi statis tentang apa yang mungkin diteruskan kontrol.

API tidak memberlakukan persyaratan panjang minimum pada kueri parsial; bisa sesedikor satu karakter. Namun, jQuery Autocomplete memberikan panjang minimum. Minimal dua atau tiga karakter adalah tipikal.

Kecocokan ada di awal istilah di mana saja dalam untai masukan. Mengingat rubah coklat cepat, baik pelengkapan otomatis dan saran cocok pada versi parsial, cepat, coklat, atau rubah tetapi tidak pada istilah infiks parsial seperti rown atau lembu. Selanjutnya, setiap kecocokan menetapkan cakupan untuk ekspansi hilirisasi. Kueri parsial dari kecocokan br cepat pada roti coklat cepat atau cepat, tetapi tidak coklat atau roti dengan sendirinya akan cocok kecuali cepat* mendahuluinya.

API untuk mencari selagi Anda mengetik

Ikuti tautan ini untuk halaman referensi REST dan .NET SDK:

Struktur respons

Respons untuk lengkapi otomatis dan saran adalah apa yang mungkin Anda harapkan untuk pola: Lengkapi Otomatis mengembalikan daftar istilah, Saran mengembalikan istilah ditambah ID dokumen sehingga Anda dapat mengambil dokumen (menggunakan API Dokumen Pencarianuntuk mengambil dokumen tertentu untuk halaman detail).

Respons dibentuk oleh parameter pada permintaan:

  • Untuk pelengkapan otomatis, atur autocompleteMode untuk menentukan apakah penyelesaian teks terjadi pada satu atau dua istilah.

  • Untuk saran, atur $select untuk mengembalikan bidang yang berisi nilai unik atau membedakan, seperti nama dan deskripsi. Hindari bidang yang berisi nilai duplikat (seperti kategori atau kota).

Parameter berikut berlaku untuk lengkapi otomatis dan saran, tetapi lebih berlaku untuk saran, terutama ketika pemberi saran menyertakan beberapa bidang.

Parameter Penggunaan
searchFields Batasi kueri ke bidang tertentu.
$filter Terapkan kriteria kecocokan pada set hasil ($filter=Category eq 'ActionAdventure').
$top Batasi hasil ke angka tertentu ($top=5).

Tambahkan kode interaksi pengguna

Mengisi otomatis istilah kueri atau menurunkan daftar tautan yang cocok memerlukan kode interaksi pengguna, biasanya JavaScript, yang dapat menggunakan permintaan dari sumber eksternal, seperti melengkapi otomatis atau kueri saran terhadap indeks Kognitif Azure Search.

Meskipun Anda dapat menulis kode ini secara asli, lebih mudah untuk menggunakan fungsi dari pustaka JavaScript yang ada, seperti salah satu hal berikut.

  • Widget lengkapi otomatis (jQuery UI) muncul di cuplikan kode saran. Anda dapat membuat kotak pencarian, lalu mereferensikannya dalam fungsi JavaScript yang menggunakan widget lengkapi otomatis. Properti pada widget mengatur sumber (fungsi lengkapi otomatis atau saran), panjang minimum karakter input sebelum tindakan diambil, dan penempatan.

  • Plug-in XDSoft Autocomplete muncul di cuplikan kode pelengkapan otomatis.

  • Saran muncul di tutorial Tambahkan pencarian ke situs web dan sampel kode.

Gunakan pustaka ini di klien untuk membuat kotak pencarian yang mendukung saran dan lengkapi otomatis. Input yang dikumpulkan dalam kotak pencarian kemudian dapat dipasangkan dengan saran dan tindakan lengkapi otomatis pada layanan pencarian.

Saran

Bagian ini memandu Anda melalui implementasi hasil yang disarankan, dimulai dengan definisi kotak pencarian. Ini juga menunjukkan bagaimana dan skrip yang memanggil pustaka lengkapi otomatis JavaScript pertama yang dirujuk dalam artikel ini.

Dengan asumsi pustaka jQuery UI Autocomplete dan proyek MVC di C#, Anda dapat menentukan kotak pencarian menggunakan JavaScript dalam file Index.cshtml. Pustaka menambahkan interaksi mencari selagi Anda mengetik ke kotak pencarian dengan melakukan panggilan asinkron ke pengontrol MVC untuk mengambil saran.

Di Index.cshtml di dalam folder \Views\Home, baris untuk membuat kotak pencarian mungkin sebagai berikut:

<input class="searchBox" type="text" id="searchbox1" placeholder="search">

Contoh ini adalah kotak teks input sederhana dengan kelas untuk styling, ID yang akan dirujuk oleh JavaScript, dan teks tempat penampung.

Dalam file yang sama, sematkan JavaScript yang mereferensikan kotak pencarian. Fungsi berikut memanggil Suggest API, yang meminta dokumen yang cocok berdasarkan input istilah parsial:

$(function () {
    $("#searchbox1").autocomplete({
        source: "/home/suggest?highlights=false&fuzzy=false&",
        minLength: 3,
        position: {
            my: "left top",
            at: "left-23 bottom+10"
        }
    });
});

sourceMemberi tahu fungsi jQuery UI Autocomplete tempat untuk mendapatkan daftar item untuk ditampilkan di bawah kotak pencarian. Karena proyek ini adalah proyek MVC, proyek ini memanggil Suggest fungsi di HomeController.cs yang berisi logika untuk mengembalikan saran kueri. Fungsi ini juga melewati beberapa parameter untuk mengontrol sorotan, pencocokan fuzzy, dan istilah. Lengkapi otomatis dari JavaScript API menambahkan parameter istilah.

minLength: 3 memastikan bahwa rekomendasi hanya ditampilkan ketika setidaknya ada tiga karakter di kotak pencarian.

Aktifkan pencocokan fuzzy

Pencarian fuzzy memungkinkan Anda untuk mendapatkan hasil berdasarkan kecocokan dekat bahkan jika pengguna salah mengeja kata di kotak pencarian. Jarak edit adalah 1, yang berarti bisa ditemukan perbedaan maksimum dari satu karakter antara input pengguna dan kecocokan.

source: "/home/suggest?highlights=false&fuzzy=true&",

Aktifkan penyorotan

Penyorotan menerapkan gaya font pada karakter dalam hasil yang sesuai dengan input. Misalnya, jika input parsial mikro, hasilnya akan muncul sebagai mikrolunak, cakupan mikro, dan sebagainya. Penyorotan didasarkan pada HighlightPreTag parameter dan HighlightPostTag , yang ditentukan sebaris dengan Suggest fungsi .

source: "/home/suggest?highlights=true&fuzzy=true&",

Fungsi saran

Jika Anda menggunakan C# dan aplikasi MVC, file HomeController.cs di direktori Pengontrol adalah tempat Anda dapat membuat kelas untuk hasil yang disarankan . Di .NET, Suggest fungsi didasarkan pada metode SuggestAsync. Untuk informasi selengkapnya tentang .NET SDK, lihat Cara menggunakan Azure AI Search dari Aplikasi .NET.

Metode ini InitSearch membuat klien indeks HTTP terautentikasi ke layanan Pencarian Azure AI. Properti pada kelas SuggestOptions menentukan bidang mana yang dicari dan dikembalikan dalam hasil, jumlah kecocokan, dan apakah pencocokan fuzzy digunakan.

Untuk lengkapi otomatis, pencocokan fuzzy terbatas pada satu jarak edit (satu karakter yang dihilangkan atau salah taruh). Pencocokan fuzzy dalam kueri lengkapi otomatis terkadang dapat menghasilkan hasil yang tidak terduga tergantung pada ukuran indeks dan bagaimana pecahannya.

public async Task<ActionResult> SuggestAsync(bool highlights, bool fuzzy, string term)
{
    InitSearch();

    var options = new SuggestOptions()
    {
        UseFuzzyMatching = fuzzy,
        Size = 8,
    };

    if (highlights)
    {
        options.HighlightPreTag = "<b>";
        options.HighlightPostTag = "</b>";
    }

    // Only one suggester can be specified per index.
    // The suggester for the Hotels index enables autocomplete/suggestions on the HotelName field only.
    // During indexing, HotelNames are indexed in patterns that support autocomplete and suggested results.
    var suggestResult = await _searchClient.SuggestAsync<Hotel>(term, "sg", options).ConfigureAwait(false);

    // Convert the suggest query results to a list that can be displayed in the client.
    List<string> suggestions = suggestResult.Value.Results.Select(x => x.Text).ToList();

    // Return the list of suggestions.
    return new JsonResult(suggestions);
}

Fungsi ini SuggestAsync mengambil dua parameter yang menentukan apakah sorotan hit dikembalikan atau pencocokan fuzzy digunakan selain input istilah pencarian. Hingga delapan kecocokan dapat dimasukkan dalam hasil yang disarankan. Metode ini membuat objek SuggestOptions, yang kemudian diteruskan ke API Saran. Hasilnya kemudian dikonversi ke JSON sehingga dapat ditampilkan di klien.

Pelengkapan otomatis

Sejauh ini, kode UX pencarian telah berpusat pada saran. Blok kode berikutnya menunjukkan pelengkapan otomatis, menggunakan fungsi Autocomplete UI XDSoft jQuery, meneruskan permintaan untuk pelengkapan otomatis Azure AI Search. Seperti saran, dalam aplikasi C #, kode yang mendukung interaksi pengguna masuk ke index.cshtml.

$(function () {
    // using modified jQuery Autocomplete plugin v1.2.8 https://xdsoft.net/jqplugins/autocomplete/
    // $.autocomplete -> $.autocompleteInline
    $("#searchbox1").autocompleteInline({
        appendMethod: "replace",
        source: [
            function (text, add) {
                if (!text) {
                    return;
                }

                $.getJSON("/home/autocomplete?term=" + text, function (data) {
                    if (data && data.length > 0) {
                        currentSuggestion2 = data[0];
                        add(data);
                    }
                });
            }
        ]
    });

    // complete on TAB and clear on ESC
    $("#searchbox1").keydown(function (evt) {
        if (evt.keyCode === 9 /* TAB */ && currentSuggestion2) {
            $("#searchbox1").val(currentSuggestion2);
            return false;
        } else if (evt.keyCode === 27 /* ESC */) {
            currentSuggestion2 = "";
            $("#searchbox1").val("");
        }
    });
});

Fungsi Lengkapi Otomatis

Lengkapi otomatis didasarkan pada metode AutocompleteAsync. Seperti saran, blok kode ini akan masuk ke file homecontroller.cs ini.

public async Task<ActionResult> AutoCompleteAsync(string term)
{
    InitSearch();

    // Setup the autocomplete parameters.
    var ap = new AutocompleteOptions()
    {
        Mode = AutocompleteMode.OneTermWithContext,
        Size = 6
    };
    var autocompleteResult = await _searchClient.AutocompleteAsync(term, "sg", ap).ConfigureAwait(false);

    // Convert the autocompleteResult results to a list that can be displayed in the client.
    List<string> autocomplete = autocompleteResult.Value.Results.Select(x => x.Text).ToList();

    return new JsonResult(autocomplete);
}

Fungsi Lengkapi Otomatis mengambil input istilah pencarian. Metode ini membuat objek AutoCompleteParameters. Hasilnya kemudian dikonversi ke JSON sehingga dapat ditampilkan di klien.

Langkah selanjutnya

Tutorial berikut menunjukkan pengalaman search-as-you-type.

Menambahkan pencarian ke situs web (C#)