İstemci uygulamalarında otomatik tamamlama ve arama önerileri ekleme

Not

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

Yazarken arama, sorgu verimliliğini artırmak için yaygın bir tekniktir. Azure Yapay Zeka Arama'te bu deneyim, kısmi girişi temel alarak bir terimi veya ifadeyi tamamlayan otomatik tamamlama aracılığıyla desteklenir (örneğin, mikro kelimesini mikroçip, mikroskop, microsoft ve diğer mikro eşleşmeleriyle tamamlama). İkinci kullanıcı deneyimi, eşleşen belgelerin kısa bir listesini oluşturan önerilerdir (örneğin, bu kitapla ilgili bir ayrıntı sayfasına bağlanabilmeniz için kimlik numarasıyla kitap başlıklarını döndürme). Hem otomatik tamamlama hem de öneriler dizindeki bir eşleşmeye göre önceden hesaplanır. Hizmet, sıfır sonuç döndüren otomatik olarak tamamlanmış sorgular veya öneriler sunmaz.

Bu deneyimleri Azure Yapay Zeka Arama'te uygulamak için:

Dizin şemasına bir suggester ekleyin.
İstekte Otomatik Tamamlama API'sini veya Öneriler API'sini çağıran bir sorgu oluşturun.
İstemci uygulamanıza yazdıkça arama etkileşimlerini işlemek için bir kullanıcı arabirimi denetimi ekleyin. Bu amaçla mevcut bir JavaScript kitaplığı kullanmanızı öneririz.

Azure Yapay Zeka Arama'te, otomatik olarak tamamlanan sorgular ve önerilen sonuçlar arama dizininden, bir öneri oluşturucuya kaydettiğiniz seçili alanlardan alınır. Öneride bulunan, dizinin bir parçasıdır ve hangi alanların sorguyu tamamlayan, sonuç öneren veya ikisini birden yapan içerik sağladığını belirtir. Dizin oluşturulduğunda ve yüklendiğinde, kısmi sorgularda eşleştirme için kullanılan ön ekleri depolamak için dahili olarak bir öneri veri yapısı oluşturulur. Öneriler için, benzersiz veya en azından tekrarlanmayan uygun alanları seçmek deneyim için önemlidir. Daha fazla bilgi için bkz. Bir önerici yapılandırma.

Bu makalenin geri kalanı sorgulara ve istemci koduna odaklanmıştır. Önemli noktaları göstermek için JavaScript ve C# kullanır. REST API örnekleri, her işlemi kısa bir şekilde sunmak için kullanılır. Uçtan uca kod örnekleri için bkz . .NET ile web sitesine arama ekleme.

İstek oluşturma

Bir talebin unsurları, arama-esnasında-yazma API'lerinden biri, kısmi sorgu ve bir öneri sistemini içerir. Aşağıdaki betik, örnek olarak Otomatik Tamamlama REST API'sini kullanarak isteğin bileşenlerini gösterir.

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

suggesterName parametresi, terimleri veya önerileri tamamlamak için kullanılan önericiyi bilen alanları sağlar. Özellikle öneriler için alan listesi, eşleşen sonuçlar arasında net seçenekler sunan önerilerden oluşmalıdır. Bilgisayar oyunları satan bir sitede, alan oyun başlığı olabilir.

search parametresi, jQuery Otomatik Tamamlama denetimi aracılığıyla karakterlerin sorgu isteğine beslendiği kısmi sorguyu sağlar. Önceki örnekte minecraf, denetimin neler geçirebileceğinin statik bir gösterimidir.

API'ler kısmi sorguya minimum uzunluk gereksinimleri getirmez; bir karakter kadar küçük olabilir. Ancak, jQuery Otomatik Tamamlama en düşük uzunluğu sağlar. En az iki veya üç karakter tipiktir.

Eşleşmeler, giriş dizesinin herhangi bir yerinde bir terimin başındadır. Hızlı kahverengi tilki göz önüne alındığında, hem otomatik tamamlama hem de öneriler, hızlı, kahverengi veya tilkininkısmi sürümleriyle eşleşir, ancak rown veya ox gibi kısmi düzeltme terimleriyle eşleşmez. Ayrıca, her eşleşme aşağı akış genişletmelerinin kapsamını ayarlar. Hızlı br'nin kısmi sorgusu hızlı kahverengi veya hızlı ekmek ile eşleşir, ancak kahverengi veya ekmek tek başına eşleşmez, çünkü quick* onları öncelemediği sürece eşleşme olmaz.

Yazarken arama için API'ler

REST ve .NET SDK başvuru sayfaları için şu bağlantıları izleyin:

Yanıtı yapılandırın

Otomatik tamamlama yanıtları ve öneriler, desen için bekleyebileceğiniz yanıtlardır: Otomatik tamamlama bir terim listesi döndürür, Öneriler terimleri ve belge kimliğini döndürür; böylece belgeyi getirebilirsiniz (ayrıntılı bir sayfa için belirli bir belgeyi getirmek için Arama Belgesi API'sini kullanın).

Yanıtlar istek üzerindeki parametrelere göre şekillendirilir:

Otomatik tamamlama için, metin tamamlamanın bir veya iki terimle gerçekleşip gerçekleşmediğini belirlemek için autocompleteMode değerini ayarlayın.
Öneriler için, adlar ve açıklama gibi benzersiz veya farklı değerler içeren alanları döndürmek için $select ayarlayın. Yinelenen değerler (kategori veya şehir gibi) içeren alanlardan kaçının.

Aşağıdaki parametreler hem otomatik tamamlama hem de öneriler için geçerlidir, ancak özellikle bir öneri oluşturucu birden çok alan içerdiğinde öneriler için daha geçerlidir.

Parametre	Kullanım
aramaAlanları	Sorguyu belirli alanlarla sınırlandırın.
$filter	Sonuç kümesine (`$filter=Category eq 'ActionAdventure'`) eşleşme ölçütleri uygulayın.
$top	Sonuçları belirli bir sayı (`$top=5`) ile sınırlayın.

Kullanıcı etkileşim kodu ekleme

Sorgu teriminin otomatik olarak doldurulması veya eşleşen bağlantıların listesinin düşürülmesi için kullanıcı etkileşim kodu (genellikle JavaScript) gerekir. Bu kod, Azure Search Bilişsel dizininde otomatik tamamlama veya öneri sorguları gibi dış kaynaklardan gelen istekleri tüketebilir.

Bu kodu yerel olarak yazabilseniz de, aşağıdakilerden biri gibi mevcut JavaScript kitaplığındaki işlevleri kullanmak daha kolaydır.

Öneri kod parçacığında otomatik tamamlama pencere öğesi (jQuery kullanıcı arabirimi) görüntülenir. Bir arama kutusu oluşturabilir ve ardından otomatik tamamlama bileşenini kullanan bir JavaScript fonksiyonunda bu kutuya başvurabilirsiniz. Pencere öğesindeki özellikler kaynağı (otomatik tamamlama veya öneriler işlevi), eylem gerçekleştirilmeden önce giriş karakterlerinin en düşük uzunluğunu ve konumlandırmayı ayarlar.
XDSoft Otomatik Tamamlama eklentisi otomatik tamamlama kod parçacığında görünür.
Öneriler, Web sitelerine arama ekleme öğreticisinde ve kod örneğinde görünür.

Hem önerileri hem de otomatik tamamlamayı destekleyen bir arama kutusu oluşturmak için istemcideki bu kitaplıkları kullanın. Daha sonra arama kutusunda toplanan girişler, arama hizmetindeki öneriler ve otomatik tamamlama eylemleriyle eşleştirilebilir.

Öneriler

Bu bölümde, arama kutusu tanımından başlayarak önerilen sonuçların uygulanmasında size yol gösterilir. Ayrıca, bu makalede başvurulan ilk JavaScript otomatik tamamlama kütüphanesini çağıran betiğin nasıl çalıştığını da gösterir.

JQuery UI Otomatik Tamamlama kitaplığını ve C# dilinde bir MVC projesini varsayarsak, Arama kutusunu Index.cshtml dosyasında JavaScript kullanarak tanımlayabilirsiniz. Kitaplık, önerileri almak için MVC denetleyicisine zaman uyumsuz çağrılar yaparak arama kutusuna yazarken arama etkileşimini ekler.

\Views\Home klasörünün içindeki Index.cshtml dosyasında, arama kutusu oluşturmak için bir satır aşağıdaki gibi olabilir:

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

Bu örnek, stil oluşturma sınıfı, JavaScript tarafından başvurulacak kimlik ve yer tutucu metin içeren basit bir giriş metin kutusudur.

Aynı dosyanın içine arama kutusuna başvuran JavaScript ekleyin. Aşağıdaki işlev, kısmi terim girişlerine göre önerilen eşleşen belgeleri isteyen Suggest API'sini çağırır:

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

jQuery source KULLANıCı Arabirimi Otomatik Tamamlama işlevine arama kutusunun altında gösterilecek öğe listesinin nereden alınacağı bildirilir. Bu proje bir MVC projesi olduğundan, sorgu önerilerini döndürme mantığını içeren Suggest fonksiyonunu HomeController.cs'de çağırır. Bu işlev ayrıca vurguları, bulanık eşleştirmeyi ve terimi kontrol etmek için birkaç parametre geçirir. Otomatik tamamlama JavaScript API’si'sinde parametre terimi eklenir.

, minLength: 3 önerilerin yalnızca arama kutusunda en az üç karakter olduğunda gösterilmesini sağlar.

Bulanık eşleştirmeyi etkinleştirme

Benzer öğe araması, kullanıcı bir kelimeyi arama kutusuna yanlış yazsa bile yakın eşleşmelere göre sonuçlara ulaşmanızı sağlar. Düzenleme mesafesi 1'dir, yani kullanıcı girişi ile eşleşme arasında en fazla bir karakter farkı olabilir.

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

Vurgulama özelliğini etkinleştirme

Vurgulama, sonuçtaki girişe karşılık gelen karakterlere yazı tipi stili uygular. Örneğin, kısmi giriş mikro ise, sonuç mikroyumuşak, mikrokapsam vb. olarak görünür. Vurgulama, satır içinde HighlightPreTag işleviyle tanımlanan HighlightPostTag ve Suggest parametrelerine dayanır.

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

Öneri özelliği

C# ve bir MVC uygulaması kullanıyorsanız, Denetleyiciler dizinindeki HomeController.cs dosyası, önerilen sonuçlar için bir sınıf oluşturabileceğiniz yerdir. .NET'te bir Suggest işlev SuggestAsync yöntemini temel alır. .NET SDK'sı hakkında daha fazla bilgi için bkz . .NET Uygulamasından Azure AI Arama'yı kullanma.

yöntemi, InitSearch Azure AI Arama hizmeti için kimliği doğrulanmış bir HTTP dizin istemcisi oluşturur. SuggestOptions sınıfındaki özellikler sonuçlarda hangi alanların arandığını ve döndürüleceğini, eşleşme sayısını ve benzer eşleştirmenin kullanılıp kullanılmadığını belirler.

Otomatik tamamlama için, bulanık eşleştirme bir düzenleme mesafesiyle sınırlıdır (bir atlanmış veya yanlış yerleştirilmiş karakter). Otomatik tamamlama sorgularında bulanık eşleşme, bazen dizin boyutuna ve parçalanma şekline bağlı olarak beklenmeyen sonuçlar üretebilir.

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

SuggestAsync işlevi, arama terimi girişine ek olarak isabet vurgularının döndürülüp döndürülmeyeceğini veya bulanık eşleştirmenin kullanılıp kullanılmayacağını belirleyen iki parametre alır. Önerilen sonuçlara en fazla sekiz eşleşme eklenebilir. yöntemi daha sonra Öneri API'sine geçirilen bir SuggestOptions nesnesi oluşturur. Ardından alınan sonuç istemcide gösterilebilmesi için JSON biçimine dönüştürülür.

Otomatik Tamamlama

Şu ana kadar arama UX kodu önerilere odaklanmıştır. Sonraki kod bloğu, Azure Yapay Zeka Arama otomatik tamamlama isteği yaparak, XDSoft jQuery UI Autocomplete işlevini kullanarak otomatik tamamlama gösterir. Önerilerde olduğu gibi, bir C# uygulamasında, kullanıcı etkileşimini destekleyen kod index.cshtml dosyasına gider.

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

Otomatik tamamlama işlevi

Otomatik tamamlama, AutocompleteAsync yöntemini temel alır. Önerilerde olduğu gibi, bu kod bloğu HomeController.cs dosyasına gider.

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

Otomatik Tamamlama işlevi arama terimi girişini alır. yöntemi bir AutoCompleteParameters nesnesi oluşturur. Ardından alınan sonuç istemcide gösterilebilmesi için JSON biçimine dönüştürülür.

Sonraki adım

Aşağıdaki öğreticide, yazdıkça arama deneyimi gösterilmektedir.

Web sitesine arama ekleme (C#)

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-06-08