Azure Yapay Zeka Arama'te arama sonuçlarını şekillendirme veya arama sonuçları oluşturmayı değiştirme

Bu makalede, arama sonuçlarının bileşimi ve tam metin arama sonuçlarını senaryolarınıza uyacak şekilde şekillendirme açıklanmaktadır. Arama sonuçları sorgu yanıtında döndürülür. Yanıtın şekli, sorgunun kendisindeki parametreler tarafından belirlenir. Bu parametreler şunlardır:

• Dizinde bulunan eşleşme sayısı (count)
• Yanıtta döndürülen eşleşme sayısı (varsayılan olarak 50, top ile yapılandırılabilir) veya sayfa başına (skip ve top)
• Derecelendirme için kullanılan her sonuç için bir arama puanı (@search.score)
• Arama sonuçlarına dahil edilen alanlar (select)
• Sıralama mantığı (orderby)
• Sonuç içindeki terimlerin vurgulanması, metin içindeki tüm veya kısmi terimle eşleşme
• Semantik dereceleyiciden isteğe bağlı öğeler (answers her eşleşme için en üstte captions )

Arama sonuçları en üst düzey alanları içerebilir, ancak yanıtın çoğu dizideki eşleşen belgelerden oluşur.

Sorgu yanıtını tanımlamak için istemciler ve API'ler

Sorgu yanıtını yapılandırmak için aşağıdaki istemcileri kullanabilirsiniz:

• Desteklenen herhangi bir parametreyi belirtebilmeniz için JSON görünümünü kullanarak Azure portalında Arama Gezgini
• Belgeler - POST (REST API'leri)
• SearchClient.Search Yöntemi (.NET için Azure SDK)
• SearchClient.Search Yöntemi (Python için Azure SDK)
• SearchClient.Search Yöntemi (JavaScript için Azure)
• SearchClient.Search Yöntemi (Java için Azure)

Sonuç bileşimi

Sonuçlar çoğunlukla tablosaldır, tüm retrievable alanların alanlarından oluşur veya yalnızca parametresinde select belirtilen alanlarla sınırlıdır. Sorgu mantığınız ilgi derecelendirmesini engellemediği sürece satırlar, genellikle uygunluk sırasına göre sıralanmış eşleşen belgelerdir.

Arama sonuçlarında hangi alanların olduğunu seçebilirsiniz. Bir arama belgesinde çok fazla sayıda alan olsa da, her belgeyi sonuçlarda temsil etmek için genellikle yalnızca birkaçı gerekir. Sorgu isteğinde, yanıtta hangi select=<field list> alanların görüneceğini belirtmek için retrievable ekleyin.

Belgeler arasında karşıtlık ve farklılaşma sunan alanları seçerek kullanıcının bir tıklama yanıtını davet etmek için yeterli bilgi sağlayın. Bir e-ticaret sitesinde ürün adı, açıklaması, markası, rengi, boyutu, fiyatı ve derecelendirmesi olabilir. hotels-sample dizini için, aşağıdaki örnekteki "seçim" alanları olabilir:

POST /indexes/hotels-sample/docs/search?api-version=2026-04-01 
    {  
      "search": "sandy beaches",
      "select": "HotelId, HotelName, Description, Rating, Address/City",
      "count": true
    }

Beklenmeyen sonuçlar için ipuçları

Bazen, görmeyi beklediğiniz şey sorgu çıktısı değildir. Örneğin, bazı sonuçların yinelenen sonuçlar gibi göründüğünü veya üst kısımda görünmesi gereken bir sonucun sonuçlarda daha düşük bir konuma getirildiğini fark edebilirsiniz. Sorgu sonuçları beklenmedik olduğunda, sonuçların iyileşip iyileşmediğini görmek için şu sorgu değişikliklerini deneyebilirsiniz:

• Ölçütlerden herhangi biri yerine tüm ölçütlerde eşleşme gerektirecek şekilde (varsayılan) searchMode=any olarak değiştirin searchMode=all . Bu durum özellikle boole işleçleri sorguya eklendiğinde geçerlidir.

• Sorgu sonucunu değiştirip değiştirmediğini görmek için farklı sözcük temelli çözümleyicilerle veya özel çözümleyicilerle denemeler yapın. Varsayılan çözümleyici, hecelenmiş sözcükleri ayırır ve sözcükleri kök formlara küçültür ve bu da genellikle sorgu yanıtının sağlamlığını artırır. Ancak, kısa çizgileri korumanız gerekiyorsa veya dizeler özel karakterler içeriyorsa, dizinin doğru biçimde belirteçler içerdiğinden emin olmak için özel çözümleyiciler yapılandırmanız gerekebilir. Daha fazla bilgi için bkz Kısmi terim araması ve özel karakterler içeren desenler (kısa çizgi, wildcard, regex, desenler).

Eşleşmeleri sayma

parametresi, count dizindeki sorguyla eşleşme olarak kabul edilen belge sayısını döndürür. Sayıyı döndürmek için sorgu isteğine ekleyin count=true . Arama hizmeti tarafından uygulanan maksimum değer yoktur. Sorgunuza ve belgelerinizin içeriğine bağlı olarak, sayı dizindeki her belge kadar yüksek olabilir.

Dizin kararlı olduğunda sayı doğrudur. Sistem belgeleri etkin bir şekilde ekliyor, güncelleştiriyor veya siliyorsa, tam olarak dizine eklenmemiş belgeler hariç olmak üzere yaklaşık sayıdır.

Arama hizmetindeki rutin bakım veya diğer iş yükleri sayıyı etkilemez. Ancak, birden çok bölümünüz ve tek bir replikanız varsa, bölümler yeniden başlatılırken belge sayısında birkaç dakika süren kısa süreli dalgalanmalar yaşayabilirsiniz.

Yanıttaki sonuç sayısı

Azure Yapay Zeka Arama, sorguların aynı anda çok fazla belge almasını önlemek için sunucu tarafı sayfalama kullanır. Yanıttaki sonuç sayısını belirleyen sorgu parametreleri top ve skip. top bir sayfadaki arama sonuçlarının sayısını ifade eder. skip, top'nin bir aralığıdır ve arama motoruna, bir sonraki kümeyi almadan önce kaç sonucun atlanması gerektiği bilgisini verir.

Varsayılan sayfa boyutu 50,en büyük sayfa boyutu ise 1.000'dir. 1.000'den büyük bir değer belirtirseniz ve dizininizde 1.000'den fazla sonuç bulunursa, yalnızca ilk 1.000 sonuç döndürülür. Eşleşme sayısı sayfa boyutunu aşarsa yanıt, sonraki sonuç sayfasını almaya yönelik bilgiler içerir. Örneğin:

"@odata.nextLink": "https://contoso-search-eastus.search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01"

En üstteki eşleşmeler, sorgunun tam metin arama veya anlamsal olduğu varsayılarak arama puanına göre belirlenir. Aksi takdirde, en üst eşleşmeler tam eşleşme sorguları için rastgele bir sıradır (tekdüzen @search.score=1.0 rastgele derecelendirmeyi gösterir).

Varsayılan 50'yi geçersiz kılmak için ayarlayın top . Daha yeni önizleme API'lerinde karma sorgu kullanıyorsanız en fazla 10.000 belge döndürmek için maxTextRecallSize belirtebilirsiniz.

Sonuç kümesinde döndürülen tüm belgelerin sayfalandırmasını denetlemek için top ve skip değerlerini birlikte kullanın. Bu sorgu, ilk 15 eşleşen belge kümesini ve toplam eşleşme sayısını döndürür.

POST https://contoso-search-eastus.search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01

{
    "search": "room with a view",
    "count": true,
    "top": 15,
    "skip": 0
}

Bu sorgu ikinci kümeyi döndürür ve sonraki 15'i (16 ile 30) almak için ilk 15'i atlar:

POST https://contoso-search-eastus.search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01

{
    "search": "room with a view",
    "count": true,
    "top": 15,
    "skip": 15
}

Temel alınan dizin değişiyorsa sayfalandırılmış sorguların sonuçlarının kararlı olacağı garanti edilmez. Sayfalama, her sayfanın değerini skip değiştirir, ancak her sorgu bağımsızdır ve sorgu zamanında dizinde mevcut olan verilerin geçerli görünümünde çalışır (başka bir deyişle, genel amaçlı veritabanında bulunanlar gibi sonuçların önbelleğe alınmaması veya anlık görüntüsü yoktur).

Yinelenenleri nasıl elde edebileceğinize dair aşağıda bir örnek verilmiştir. Dört belge içeren bir dizin varsayma:

{ "id": "1", "rating": 5 }
{ "id": "2", "rating": 3 }
{ "id": "3", "rating": 2 }
{ "id": "4", "rating": 1 }

Şimdi sonuçların derecelendirmeye göre sıralanmış şekilde aynı anda iki tane döndürülmesini istediğinizi varsayalım. Sonuçların ilk sayfasını almak için şu sorguyu yürütebilirsiniz: $top=2&$skip=0&$orderby=rating desc, aşağıdaki sonuçları üretir:

{ "id": "1", "rating": 5 }
{ "id": "2", "rating": 3 }

Hizmette, sorgu çağrıları arasında dizinine beşinci bir belge eklendiğini varsayalım: { "id": "5", "rating": 4 }. Kısa bir süre sonra ikinci sayfayı $top=2&$skip=2&$orderby=rating descgetirmek için bir sorgu yürütür ve şu sonuçları alırsınız:

{ "id": "2", "rating": 3 }
{ "id": "3", "rating": 2 }

2. belgenin iki kez getirildiğini unutmayın. Bunun nedeni, yeni belge 5'in derecelendirme için daha büyük bir değere sahip olmasıdır, bu nedenle belge 2'den önce sıralanır ve ilk sayfaya iner. Bu davranış beklenmeyen bir davranış olsa da, arama motorunun davranışı için bu tipiktir.

Çok sayıda sonuç üzerinden sayfalama

Sayfalama için alternatif bir teknik, sıralama sırası ve aralık filtresi kullanarak skip için geçici bir çözüm üretmektir.

Bu geçici çözümde, bir belge kimliği alanına veya her belge için benzersiz olan başka bir alana sıralama ve filtreleme uygulanır. Benzersiz alanın arama dizininde filterable ve sortable ilişkilendirmesi olmalıdır.

1. Sıralanmış sonuçların tam sayfasını döndürmek için bir sorgu gönderin.

   POST /indexes/good-books/docs/search?api-version=2026-04-01
       {  
         "search": "divine secrets",
         "top": 50,
         "orderby": "id asc"
       }
   

2. Arama sorgusu tarafından döndürülen son sonucu seçin. Burada yalnızca kimlik değerine sahip örnek bir sonuç gösterilmiştir.

   {
       "id": "50"
   }
   

3. Bir sonraki sonuç sayfasını getirmek için bir aralık sorgusunda bu kimlik değerini kullanın. Bu kimlik alanı benzersiz değerlere sahip olmalıdır, aksi takdirde sayfalandırma yinelenen sonuçlar içerebilir.

   POST /indexes/good-books/docs/search?api-version=2026-04-01
       {  
         "search": "divine secrets",
         "top": 50,
         "orderby": "id asc",
         "filter": "id gt 50"
       }
   

4. Sayfalandırma, sorgu sıfır sonuç döndürdüğünde sona erer.

Sonuçları sıralama

Tam metin arama sorgusunda sonuçlar şu şekilde sıralanabilir:

• arama puanı
• anlamsal yeniden sıralayıcı puanı
• sortable alanında bir sıralama düzeni

Puanlama profili ekleyerek belirli alanlarda bulunan eşleşmeleri de artırabilirsiniz.

Arama puanına göre sırala

Tam metin arama sorguları için sonuçlar, ilgiyi belirlemek için terim sıklığı, belge uzunluğu ve ortalama belge uzunluğunu dikkate alan BM25 algoritması kullanılarak otomatik olarak bir arama puanına göre sıralanır .

Aralık @search.score ya sınırsızdır ya da eski hizmetlerde 0 ile 1 arasında değişir (ancak 1.00 dahil değildir).

Her iki algoritma için de @search.score 1,00'a eşit bir değer, tüm sonuçların 1,0 puanına sahip olduğu, puanlanmamış veya sıralanmamış bir sonuç kümesini belirtir. Sorgu formu bulanık arama, genel karakter veya regex sorguları ya da boş bir arama (search=* ) olduğunda, puanlanmamış sonuçlar oluşur. Puanlanmamış sonuçlara göre bir derecelendirme yapısı uygulamanız gerekiyorsa, bu hedefe ulaşmak için bir orderby ifadeyi göz önünde bulundurun.

Semantik yeniden sıralayıcıya göre sırala

Semantik dereceleyici kullanıyorsanız, @search.rerankerScore sonuçlarınızın sıralama düzenini belirler.

@search.rerankerScore aralığı 1 ile 4,00 arasındadır; burada, daha yüksek bir puan daha güçlü bir anlamsal eşleşmeyi gösterir.

Orderby ile sipariş

Tutarlı sıralama bir uygulama gereksinimiyse, alanda bir orderby ifade tanımlayabilirsiniz. Sonuçları sıralamak için yalnızca "sıralanabilir" olarak dizine alınan alanlar kullanılabilir.

orderby'de yaygın olarak kullanılan alanlar arasında derecelendirme, tarih ve konum bulunur. Konuma göre filtreleme, filtre ifadesinin alan adıyla birlikte geo.distance() işlevini çağırmasını gerektirir.

Sayısal alanlar (Edm.Double, Edm.Int32, Edm.Int64) sayısal düzende sıralanır (örneğin, 1, 2, 10, 11, 20).

Dize alanları (Edm.Stringalt Edm.ComplexType alanlar), dile bağlı olarak ASCII sıralama düzeninde veya Unicode sıralama düzeninde sıralanır.

• Dize alanlarındaki sayısal içerik alfabetik olarak sıralanır (1, 10, 11, 2, 20).

• Büyük harf dizeleri küçük harflerden önce sıralanır (APPLE, Apple, BANANA, Banana, apple, banana). Bu davranışı değiştirmek için sıralamadan önce metni önceden işlemek için bir metin normalleştiricisi atayabilirsiniz. Azure Yapay Zeka Arama alanın analizsiz bir kopyasına göre sıralandığından, alanda küçük harf belirteci kullanmanın sıralama davranışı üzerinde hiçbir etkisi yoktur.

• Diyakritiklerle başlayan dizeler en son görünür (Äpfel, Öffnen, Üben)

Puanlama profili kullanarak ilgi düzeyini artırma

Sipariş tutarlılığını yükselten bir diğer yaklaşım da özel puanlama profili kullanmaktır. Puanlama profilleri, belirli alanlarda bulunan eşleşmeleri artırma özelliğiyle arama sonuçlarındaki öğelerin derecelendirmesi üzerinde daha fazla denetim sahibi olmanıza olanak sağlar. Ek puanlama mantığı, her belgenin arama puanları birbirinden daha uzak olduğundan çoğaltmalar arasındaki küçük farkları geçersiz kılmaya yardımcı olabilir. Bu yaklaşım için derecelendirme algoritmasını öneririz.

İsabet vurgulama

İsabet vurgulama, sonuçlarda eşleşen terimlere kalın veya sarı vurgular gibi metin biçimlendirmesi uygulanmasını ifade eder ve bu da eşleşmiş terimleri kolayca fark etmeyi sağlar. Vurgulama, eşleşmenin hemen belirgin olmadığı bir açıklama alanı gibi daha uzun içerik alanları için kullanışlıdır.

Vurgulamanın tek tek terimlere uygulandığına dikkat edin. Tüm alanın içeriği için vurgu özelliği yoktur. Bir tümceciği vurgulamak istiyorsanız, tırnak içine alınmış bir sorgu dizesinde eşleşen terimleri (veya tümceciği) sağlamanız gerekir. Bu teknik, bu bölümde daha ayrıntılı olarak açıklanmıştır.

Sorgu isteğinde isabet vurgulama yönergeleri verilir. Bulanık ve joker karakter arama gibi arama motorunda sorgu genişletmeyi tetikleyen sorgular, isabet vurgulama için sınırlı desteğe sahiptir.

İsabet vurgulama gereksinimleri

• Alanlar Edm.String veya Collection(Edm.String) olmalıdır.
• Alanlar şu konumda ilişkilendirilmelidir: searchable

İstek içinde vurgulamayı belirtin

Vurgulanan terimleri döndürmek için sorgu isteğine highlight parametresini ekleyin. parametresi, virgülle ayrılmış alan listesine ayarlanır.

Varsayılan olarak işaretleme biçimi <em> biçimindedir, ancak etiketi highlightPostTag ve highlightPreTag parametrelerini kullanarak geçersiz kılabilirsiniz. İstemci kodunuz yanıtı işler (örneğin, kalın yazı tipi veya sarı arka plan uygulayarak).

POST /indexes/good-books/docs/search?api-version=2026-04-01
    {  
      "search": "divine secrets",  
      "highlight": "title, original_title",
      "highlightPreTag": "<b>",
      "highlightPostTag": "</b>"
    }

Varsayılan olarak, Azure Yapay Zeka Arama alan başına en fazla beş vurgu döndürür. Bu sayıyı, sonuna bir tamsayı ekleyerek ayarlayabilirsiniz. Örneğin, "highlight": "description-10" açıklama alanındaki eşleşen içerik üzerinde en fazla 10 vurgulanmış terim döndürür.

Vurgulanan sonuçlar

Sorguya vurgulama eklendiğinde yanıt, uygulama kodunuzun bu yapıyı hedeflemesi için her sonuç için bir @search.highlights içerir. "Vurgulama" için belirtilen alanların listesi yanıta eklenir.

Anahtar sözcük aramasında her terim bağımsız olarak taranır. "İlahi sırlar" arama sorgusu, bu terimlerden herhangi birini içeren belgelerdeki eşleşmeleri döndürür.

Anahtar sözcük arama vurgulama

Vurgulanan bir alanın içinde biçimlendirme tüm terimlere uygulanır. Örneğin, "Ya-Ya Kardeşliğinin İlahi Sırları" ile yapılan bir eşleşmede, biçimlendirme ardışık olsalar bile her terime ayrı olarak uygulanır.

"@odata.count": 39,
"value": [
    {
        "@search.score": 19.593246,
        "@search.highlights": {
            "original_title": [
                "<em>Divine</em> <em>Secrets</em> of the Ya-Ya Sisterhood"
            ],
            "title": [
                "<em>Divine</em> <em>Secrets</em> of the Ya-Ya Sisterhood"
            ]
        },
        "original_title": "Divine Secrets of the Ya-Ya Sisterhood",
        "title": "Divine Secrets of the Ya-Ya Sisterhood"
    },
    {
        "@search.score": 12.779835,
        "@search.highlights": {
            "original_title": [
                "<em>Divine</em> Madness"
            ],
            "title": [
                "<em>Divine</em> Madness (Cherub, #5)"
            ]
        },
        "original_title": "Divine Madness",
        "title": "Divine Madness (Cherub, #5)"
    },
    {
        "@search.score": 12.62534,
        "@search.highlights": {
            "original_title": [
                "Grave <em>Secrets</em>"
            ],
            "title": [
                "Grave <em>Secrets</em> (Temperance Brennan, #5)"
            ]
        },
        "original_title": "Grave Secrets",
        "title": "Grave Secrets (Temperance Brennan, #5)"
    }
]

İfade araması vurgulama

Tüm terim biçimlendirmesi, birden çok terimin çift tırnak içine alındığı bir tümcecik aramasında bile geçerlidir. Aşağıdaki örnek aynı sorgudur, ancak "ilahi sırlar" tırnak işaretleri içine alınmış bir ifade olarak gönderilir (bazı REST istemcileri, iç tırnak işaretlerinden ters eğik çizgiyle \" kaçış yapılmasını gerektirir).

POST /indexes/good-books/docs/search?api-version=2026-04-01 
    {  
      "search": "\"divine secrets\"",
      "select": "title,original_title",
      "highlight": "title",
      "highlightPreTag": "<b>",
      "highlightPostTag": "</b>",
      "count": true
    }

Ölçütler artık her iki terime de sahip olduğundan, arama dizininde yalnızca bir eşleşme bulunur. Önceki sorguya verilen yanıt şöyle görünür:

{
    "@odata.count": 1,
    "value": [
        {
            "@search.score": 19.593246,
            "@search.highlights": {
                "title": [
                    "<b>Divine</b> <b>Secrets</b> of the Ya-Ya Sisterhood"
                ]
            },
            "original_title": "Divine Secrets of the Ya-Ya Sisterhood",
            "title": "Divine Secrets of the Ya-Ya Sisterhood"
        }
    ]
}

Eski hizmetlerde cümle vurgulama

15 Temmuz 2020'ye kadar oluşturulan Arama hizmeti, tümcecik sorguları için farklı bir vurgulama deneyimi uygular.

Aşağıdaki örnekler için tırnak içine alınmış "super bowl" tümceciği içeren bir sorgu dizesi varsayın. Temmuz 2020'ye kadar tümcecikteki terimler vurgulanır:

"@search.highlights": {
    "sentence": [
        "The <em>super</em> <em>bowl</em> is <em>super</em> awesome with a <em>bowl</em> of chips"
   ]

Temmuz 2020'de oluşturulan arama hizmetleri için yalnızca tam tümcecik sorgusuyla eşleşen tümcecikler @search.highlights dönülür:

"@search.highlights": {
    "sentence": [
        "The <em>super</em> <em>bowl</em> is super awesome with a bowl of chips"
   ]

Sonraki adımlar

İstemciniz için hızla bir arama sayfası oluşturmak için şu seçenekleri göz önünde bulundurun:

• Tanıtım uygulaması oluşturun, Azure portalında, bir HTML sayfası oluşturur ve bu sayfa, arama çubuğu, yönlü gezinme ve görüntüleriniz varsa küçük resim alanı içerir.

• Web uygulamalarına arama ekleme, kullanıcı deneyimi için React JavaScript kitaplıklarını kullanan bir C# öğreticisi ve kod örneğidir. Uygulama Azure Static Web Apps kullanılarak dağıtılır ve sayfalandırma uygular.