Menambahkan fitur pelengkapan otomatis dan saran pencarian pada aplikasi klien

Note

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Pencarian saat Anda mengetik adalah teknik umum untuk meningkatkan efisiensi pencarian. Dalam Pencarian Azure AI, 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 pelengkapan otomatis maupun saran didasarkan pada kecocokan dalam indeks. Layanan ini tidak menawarkan kueri atau saran yang dilengkapi secara otomatis yang tidak mengembalikan hasil apa pun.

Untuk menerapkan pengalaman ini di Pencarian Azure AI:

  • Tambahkan suggester ke skema indeks.
  • Buat kueri yang memanggil Autocomplete API atau Suggestions API terhadap 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 Pencarian Azure AI, 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 "suggester".

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=2026-04-01
{
  "search": "minecraf",
  "suggesterName": "sg"
}

Parameter suggesterName memberikan Anda bidang yang dioptimalkan untuk saran, yang digunakan untuk melengkapi 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 dari apa yang mungkin dilewatkan oleh 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 cokelat cepat, baik penyelesaian otomatis dan saran cocok pada versi parsial dari the, quick, brown, atau fox tetapi tidak pada istilah infiks parsial seperti rown atau ox. Selanjutnya, setiap kecocokan menetapkan cakupan untuk pengembangan lanjutan. Kueri parsial dari cepat br cocok pada coklat cepat atau roti cepat, tetapi coklat atau roti sendiri tidak akan cocok kecuali cepat* mendahuluinya.

API untuk mencari selagi Anda mengetik

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

Strukturkan respons

Respon untuk lengkapi otomatis dan saran adalah seperti yang mungkin Anda harapkan untuk pola: Lengkapi Otomatis menghasilkan daftar istilah, Saran menghasilkan istilah ditambah ID dokumen sehingga Anda dapat mengakses dokumen (menggunakan API Dokumen Pencarian untuk mengakses 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 penyelesaian otomatis dan saran, tetapi lebih berlaku untuk saran, terutama ketika suggester melibatkan 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 menampilkan daftar tautan yang cocok memerlukan kode interaksi pengguna, biasanya JavaScript, yang dapat memproses permintaan dari sumber eksternal, seperti melengkapi otomatis atau kueri saran terhadap Azure Search Cognitive index.

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

Gunakan pustaka ini di klien untuk membuat kotak pencarian yang mendukung saran dan penyelesaian otomatis. Input yang dikumpulkan dalam kotak pencarian kemudian bisa dipadukan dengan saran dan fungsi lengkapi otomatis pada layanan pencarian.

Saran

Bagian ini memandu Anda melalui implementasi hasil yang disarankan, dimulai dengan definisi kotak pencarian. Ini juga menunjukkan bagaimana skrip tersebut 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. Perpustakaan menambahkan interaksi pencarian saat 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 penggayaan, ID yang akan menjadi referensi oleh JavaScript, dan teks penampung.

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

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

Fungsi source jQuery UI Autocomplete memberitahu dari mana 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 mengirimkan beberapa parameter untuk mengontrol sorotan, pencocokan samar, 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 buram

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 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 parameter HighlightPreTag dan HighlightPostTag, yang ditentukan sebaris dengan fungsi Suggest.

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 Pencarian Azure AI 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 SuggestAsync mengambil dua parameter yang menentukan apakah highlight hasil dikembalikan atau apakah pencocokan fuzzy digunakan selain input istilah pencarian. Hingga delapan pencocokan 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 dengan menggunakan fungsi Autocomplete UI XDSoft jQuery yang mengirimkan permintaan untuk pelengkapan otomatis Pencarian Azure AI. 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 pencarian-sebagai-anda-ketik.

Menambahkan pencarian ke situs web (C#)

  • Terakhir diperbarui pada