Azure Yapay Zeka Arama'te tam metin sorgusu oluşturma

Uyarı

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.

Tam metin araması için bir sorgu oluşturuyorsanız, bu makalede isteği ayarlama adımları sağlanır. Ayrıca bir sorgu yapısı tanıtır ve alan özniteliklerinin ve dil çözümleyicilerinin sorgu sonuçlarını nasıl etkileyebileceğini açıklar.

Önkoşullar

• Bir Azure AI Arama hizmeti (herhangi bir katman). Bir hizmet oluştur veya var olan bir hizmeti bul.

• Aranabilir olarak özniteliklendirilen dize alanları içeren bir arama dizini. Sorgu isteğinizin uç noktası olarak bir dizin takma adı da kullanabilirsiniz.

• Dizini sorgulama izinleri:

  • Anahtar tabanlı kimlik doğrulama: Arama hizmetiniz için bir sorgu API anahtarı.
  • Rol tabanlı kimlik doğrulaması: Arama Dizini Veri Okuyucusu rolü.

• SDK geliştirme için Azure Search istemci kitaplığını yükleyin:

  • Python: azure-search-documents
  • .NET: Azure. Search.Documents
  • JavaScript: @azure/search-documents
  • Java: azure-search-documents

Tavsiye

Hızlı bir kod örneği için Tam metin sorgu isteği örneği bölümüne atlayın.

Tam metin sorgu isteği örneği

Azure Yapay Zeka Arama'da sorgu, tek bir arama dizininin docs koleksiyonuna yönelik salt okunur bir istektir ve hem sorgu yürütmeyi bilgilendiren hem de yanıtı geri gelen yanıtı şekillendiren parametreler içerir.

Tam metin sorgusu bir search parametrede belirtilir ve terimler, tırnak içine alınmış tümcecikler ve işleçlerden oluşur. Diğer parametreler isteğe daha fazla tanım ekler.

Aşağıdaki Search POST REST API çağrısı, search ve diğer parametreler kullanılarak yapılan bir sorgu isteğini gösterir.

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "top": 10,
    "count": true
}

Başvuru:POST Araması

Önemli noktalar

• search , ister işleçlerle ister işleçler olmadan genellikle tüm terimler veya ifadeler olan eşleştirme ölçütlerini sağlar. Dizin şemasında aranabilir olarak özniteliklendirilen tüm alan, bir arama işlemi kapsamındadır.

• queryType ayrıştırıcıyı ayarlar: basit, tam. Varsayılan basit sorgu ayrıştırıcısı , tam metin araması için idealdir. Tam Lucene sorgu ayrıştırıcısı normal ifadeler, yakınlık araması, belirsiz ve joker karakter araması gibi gelişmiş sorgu yapıları içindir. Bu parametre, sorgu yanıtlarında gelişmiş anlamsal modelleme için semantik derecelendirme için semantik olarak da ayarlanabilir.

• searchMode eşleşmelerin ifadedeki tüm ölçütlere mi (duyarlığı tercih eder) yoksa herhangi bir ölçüte mi (geri çekmeyi tercih eder) dayandığını belirtir. Varsayılan herhangi biri'dir. Büyük metin blokları (içerik alanı veya uzun açıklamalar) içeren dizinlerde büyük olasılıkla boole işleçlerinin yoğun bir şekilde kullanılmasını bekliyorsanız, bu ayarın Boole araması üzerindeki etkisini değerlendirmek için sorguları parametresiyle searchMode=Any|All test etmeye özen gösterin.

• searchFields sorgu yürütmeyi belirli aranabilir alanlarla kısıtlar. Geliştirme sırasında, seçme ve arama için aynı alan listesini kullanmak yararlı olur. Aksi takdirde eşleşme, sonuçlarda göremeyeceğiniz alan değerlerini temel alarak belgenin neden döndürüldüğünün belirsiz olmasına neden olabilir.

Yanıtı şekillendirmek için kullanılan parametreler:

• select yanıtta döndürülecek alanları belirtir. Select deyiminde yalnızca dizinde alınabilir olarak işaretlenmiş alanlar kullanılabilir.

• top belirtilen sayıda en iyi eşleşen belgeyi döndürür. Bu örnekte yalnızca 10 sonuç döndürülür. Sonuçları sayfalandırmak için top ve skip (gösterilmiyor) kullanabilirsiniz.

• count, tüm dizindeki kaç belgenin genel olarak eşleştiğini ve geri döndürülenlerden daha fazla olabileceğini bildirir. Geçerli değerler "true" veya "false" şeklindedir. Varsayılan olarak "false" olur. Dizin kararlıysa sayı doğrudur, ancak aktif olarak eklenen, güncellenen veya silinen belgeler için sayımın eksik veya fazla bildirilmesine neden olur. Herhangi bir belge olmadan yalnızca sayıyı almak isterseniz $top=0 kullanabilirsiniz.

• orderby , sonuçları derecelendirme veya konum gibi bir değere göre sıralamak istiyorsanız kullanılır. Aksi takdirde, varsayılan değer, sonuçları sıralamak için ilgi puanını kullanmaktır. Bu parametre için aday olması için bir alan sıralanabilir olarak ilişkilendirilmelidir.

İstemci seçme

Erken geliştirme ve kavram kanıtı testi için Azure portal, REST istemcisi veya Jupyter notebook ile başlayın. Bu yaklaşımlar etkileşimlidir, hedefli test için yararlıdır ve kod yazmak zorunda kalmadan farklı özelliklerin etkilerini değerlendirmenize yardımcı olur.

Bir uygulamanın içinden arama yapmak için .NET, Java, JavaScript ve Python için Azure SDK'larında Azure.Document.Search istemci kitaplıklarını kullanın.

Azure portalı

Azure portalında bir dizini açtığınızda, alan özniteliklerine kolay erişim sağlamak için dizin JSON tanımı ile Search Explorer'ı yan yana sekmelerde çalıştırabilirsiniz. Sorguları test ederken hangilerinin aranabilir, sıralanabilir, filtrelenebilir ve modellenebilir olduğunu görmek için Alanlar tablosunu denetleyin.

1. Azure portalında arama hizmetinize gidin.

2. Hizmetinizde Dizinler'i seçin ve bir dizin seçin.

3. Arama gezgini sekmesinde bir dizin açılır, böylece hemen sorgulayabilirsiniz. Sorgu söz dizimlerini belirtmek için JSON görünümüne geçin.

   Aşağıda hotels-sample dizini için çalışan bir tam metin arama sorgusu ifadesi verilmişti:

      {
          "search": "pool spa +airport",
          "queryType": "simple",
          "searchMode": "any",
          "searchFields": "Description, Tags",
          "select": "HotelName, Description, Tags",
          "top": 10,
          "count": true
      }
   

   Başvuru:POST Araması

   Aşağıdaki ekran görüntüsünde sorgu ve yanıt gösterilmektedir:

   

REST API

GET ile çağrıldığında istek URL'sinin uzunluğu 8 KB'ı aşamaz. Bu uzunluk çoğu uygulama için yeterlidir. Ancak, bazı uygulamalar özellikle OData filtre ifadeleri kullanıldığında büyük sorgular üretir. Bu uygulamalar için, GET'den daha büyük filtrelere izin verdiğinden HTTP POST daha iyi bir seçimdir.

POST ile, post için istek boyutu sınırı yaklaşık 16 MB olduğundan, filtredeki yan tümcelerin sayısı ham filtre dizesinin boyutu değil sınırlayıcı faktördür. POST isteği boyut sınırı büyük olsa da, filtre ifadeleri rastgele karmaşık olamaz. Filtre karmaşıklığı sınırlamaları hakkında daha fazla bilgi için bkz. OData İfade söz dizimi.

İstek ayarlamak için REST istemcisi kullanın. Eğer başlamaya yardıma ihtiyacınız varsa, Quickstart: REST kullanarak tam metin arama bölümüne bakın.

Aşağıdaki örnek, tam metin araması için REST API'yi çağırır:

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "count": true
}

Başvuru:POST Araması

Kısmi Arama Yanıtlarının Devamı

Bazen Azure Yapay Zeka Arama tek bir Arama yanıtında istenen tüm sonuçları döndüremez. Kısmi yanıt, sorgunun $top belirtmeyerek veya $top için çok büyük bir değer belirterek çok fazla belge döndürmesi gibi farklı nedenlerle gerçekleşebilir. Bu gibi durumlarda, Azure Yapay Zeka Arama yanıt gövdesinde @odata.nextLink ek açıklamasını ve ayrıca POST isteğiyse @search.nextPageParameters içerir. Arama yanıtının bir sonraki bölümünü almak üzere başka bir Arama isteği formüle etmek için bu ek açıklamaların değerlerini kullanabilirsiniz. Bu davranış, özgün Arama isteğinin devamı olarak adlandırılır ve ek açıklamalar devamlılık belirteçleri olarak adlandırılır. Bu ek açıklamaların söz dizimi ve yanıt gövdesinde nerede göründükleri hakkında ayrıntılı bilgi için Yanıt bölümündeki örneklere bakın.

Azure Yapay Zeka Arama devamlılık belirteçleri döndürmesinin nedenleri uygulamaya özgü ve değiştirilebilir. Sağlam istemciler her zaman beklenenden daha az belgenin döndürüldüğü ve belgeleri almaya devam etmek için bir devamlılık belirtecinin eklendiği durumları işlemeye hazır olmalıdır. Ayrıca devam etmek için özgün istekle aynı HTTP yöntemini kullanmanız gerektiğini unutmayın. Örneğin, bir GET isteği gönderdiyseniz, gönderdiğiniz tüm devamlılık istekleri de GET (ve benzer şekilde POST için) kullanmalıdır.

Uyarı

@odata.nextLink ve @search.nextPageParameters'in amacı, hizmeti çok fazla sonuç isteyen sorgulardan korumaktır; genel bir sayfalama mekanizması sağlamak değildir. Sonuçları sayfalandırmak istiyorsanız $top ve $skip birlikte kullanın. Örneğin, 10 boyutlu sayfalar istiyorsanız, ilk isteğinizin $top=10 ve $skip=0 olması, ikinci isteğin $top=10 ve $skip=10 olması gerekir; üçüncü istekte $top=10 ve $skip=20 gibi bir değer olmalıdır.

Azure SDK'ları

Aşağıdaki örneklerde, Azure SDK'ları kullanarak tam metin sorgunun nasıl çalıştırıldığı gösterilmektedir.

Python

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Set up the client
service_name = "<your-search-service-name>"
index_name = "hotels-sample"
api_key = "<your-query-api-key>"

endpoint = f"https://{service_name}.search.windows.net"
credential = AzureKeyCredential(api_key)
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

# Run a full-text search query
results = client.search(
    search_text="NY +view",
    search_mode="all",
    search_fields=["HotelName", "Description", "Address/City", "Tags"],
    select=["HotelName", "Description", "Address/City", "Tags"],
    top=10,
    include_total_count=True
)

print(f"Total documents matching query: {results.get_count()}")
for result in results:
    print(f"Hotel: {result['HotelName']}")

Başvuru:SearchClient, arama

C#

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Set up the client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-query-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Run a full-text search query
SearchOptions options = new SearchOptions
{
    SearchMode = SearchMode.All,
    IncludeTotalCount = true,
    Size = 10
};
options.SearchFields.Add("HotelName");
options.SearchFields.Add("Description");
options.Select.Add("HotelName");
options.Select.Add("Description");

SearchResults<SearchDocument> response = await searchClient.SearchAsync<SearchDocument>("NY +view", options);

Console.WriteLine($"Total documents matching query: {response.TotalCount}");
await foreach (SearchResult<SearchDocument> result in response.GetResultsAsync())
{
    Console.WriteLine($"Hotel: {result.Document["HotelName"]}");
}

Başvuru:SearchClient, SearchAsync, SearchOptions

Ek SDK kaynakları

Azure SDK	İstemci	Örnekler
.NET	SearchClient	DotNetHowTo
Java	SearchClient	SearchForDynamicDocumentsExample.java
JavaScript	SearchClient	SDK örnekleri
Python	SearchClient	sample_simple_query.py

Bir sorgu türü seçin: basit | dolu

Sorgunuz tam metin aramasıysa, arama terimleri ve tümcecikleri olarak geçirilen tüm metinleri işlemek için sorgu ayrıştırıcısı kullanılır. Azure Yapay Zeka Arama iki sorgu ayrıştırıcısı sunar.

• Basit ayrıştırıcı, basit sorgu söz dizimini anlamaktadır. Bu ayrıştırıcı, serbest biçimli metin sorgularındaki hızı ve etkinliği için varsayılan olarak seçildi. Söz dizimi, terim ve tümcecik aramaları için yaygın arama işleçlerini (AND, OR, NOT) ve (Seattle ve Seaside'da * olduğu gibi) ön ek (sea*) aramayı destekler. Genel bir öneri, önce basit ayrıştırıcıyı denemek ve ardından uygulama gereksinimleri daha güçlü sorgular için çağrıda bulunursa tam ayrıştırıcıya geçmektir.

• Lucene sorgu söz dizimi tam olarak, queryType=full isteğe eklediğinizde etkinleştirilir ve Apache Lucene Ayrıştırıcısı'na dayanır.

Tam söz dizimi ve basit söz dizimi, hem aynı ön eki hem de Boole işlemlerini destekleyen ölçüde çakışır, ancak tam söz dizimi daha fazla işleç sağlar. Genel olarak, Boole ifadeleri için daha fazla işleç ve bulanık arama, joker karakter arama, yakınlık araması, ve düzenli ifadeler gibi gelişmiş sorgular için daha fazla operatör vardır.

Sorgu yöntemlerini seçme

Arama temelde, terimlerin veya tümceciklerin bir arama kutusundan veya sayfadaki tıklama olaylarından toplandığı kullanıcı odaklı bir alıştırmadır. Aşağıdaki tabloda, beklenen arama deneyimiyle birlikte kullanıcı girişi toplayabileceğiniz mekanizmalar özetlenmektedir.

Giriş	Deneyim
Arama yöntemi	Kullanıcı, terimleri veya tümcecikleri işleçlerle veya işleçler olmadan bir arama kutusuna yazar ve isteği göndermek için Ara'yı seçer. Arama aynı istek üzerindeki filtrelerle kullanılabilir, ancak otomatik tamamlama veya önerilerle kullanılamaz.
Otomatik tamamlama yöntemi	Bir kullanıcı birkaç karakter yazar ve her yeni karakter yazıldıktan sonra sorgular başlatılır. Yanıt, dizinden tamamlanmış bir dizedir. Sağlanan dize geçerliyse, kullanıcı Ara'yı seçerek bu sorguyu hizmete gönderir.
Öneriler yöntemi	Otomatik tamamlamada olduğu gibi, bir kullanıcı birkaç karakter yazar ve artımlı sorgular oluşturulur. Yanıt, genellikle birkaç benzersiz veya açıklayıcı alanla temsil edilen eşleşen belgelerin açılan listesidir. Seçimlerden herhangi biri geçerliyse, kullanıcı birini seçer ve eşleşen belge döndürülür.
Çok yönlü gezinme	Sayfada arama kapsamını daraltan tıklanabilir gezinti bağlantıları veya içerik haritaları gösterilir. Yüzeyli gezinti yapısı, başlangıç sorgusuna göre dinamik olarak oluşturulur. Örneğin, search=* tüm olası kategorilerden oluşan bir özellikli gezinti ağacını doldurmak için. Bir sorgu yanıtından fasetli gezinti yapısı oluşturulur, ancak aynı zamanda bir sonraki sorguyu ifade etmek için de bir mekanizmadır. n REST API başvurusu, facets Bir Arama Belgeleri işleminin sorgu parametresi olarak belgelenmiştir, ancak parametresi olmadan search kullanılabilir.
Filter yöntemi	Filtreler, sonuçları daraltmak için fasetlerle birlikte kullanılır. Ayrıca, sayfanın arkasına, örneğin sayfayı dile özgü alanlarla başlatmak için bir filtre uygulayabilirsiniz. REST API başvurusunda, $filter Arama Belgeleri işleminin sorgu parametresi olarak belgelenir, ancak parametresi olmadan search kullanılabilir.

Alan özniteliklerinin sorgular üzerindeki etkisi

Sorgu türleri ve oluşturma hakkında bilginiz varsa, sorgu isteğindeki parametrelerin bir dizindeki alan özniteliklerine bağlı olduğunu hatırlayabilirsiniz. Örneğin, sorgularda ve arama sonuçlarında yalnızca aranabilir ve alınabilir olarak işaretlenmiş alanlar kullanılabilir. İsteğinizde , searchve filter parametrelerini ayarlarkenorderby, beklenmeyen sonuçlardan kaçınmak için öznitelikleri denetlemeniz gerekir.

Hotels-sample dizininin aşağıdaki ekran görüntüsünde, yalnızca lastRenovationDate ve Rating alanlarının son iki alanı sıralanabilir. Bu, yalnızca yan tümcesinde kullanılması gereken bir "$orderby" gereksinimdir.

Alan özniteliği tanımları için bkz . Dizin Oluşturma (REST API).

Belirteçlerin sorgular üzerindeki etkisi

Dizin oluşturma sırasında, arama altyapısı sorgu zamanında eşleşme bulma olasılığını en üst düzeye çıkarmak için dizelerde bir metin çözümleyicisi kullanır. En azından dizeler küçük harfle yazılır, ancak çözümleyiciye bağlı olarak, lemmatizasyon ve durdurucu kelimelerin kaldırılması işlemi uygulanabilir. Daha büyük dizeler veya bileşik sözcükler genellikle boşluk, kısa çizgi veya uzun çizgi ile ayrılır ve ayrı belirteçler olarak indekslenir.

Önemli nokta, dizininizin içerdiğini düşündüğünüz ve içinde bulunanların farklı olabileceğidir. Sorgular beklenen sonuçları döndürmezse, Çözümleyici tarafından oluşturulan belirteçleri Çözümleme Metni (REST API) aracılığıyla inceleyebilirsiniz. Belirteç oluşturma ve sorgular üzerindeki etkisi hakkında daha fazla bilgi için bkz. Kısmi terim araması ve özel karakterler içeren desenler.

Sorgu sorunlarını giderme

Aşağıdaki tabloda sık karşılaşılan sorgu sorunları ve bunların nasıl çözüleceğini listeledik.

Sorun	Nedeni	Çözüm
Boş sonuçlar	Sorgu terimleriyle eşleşen belge yok.	Alanın şemada aranabilir olarak işaretlendiğini doğrulayın. Belirteçleştirmeyi denetlemek için Metin Analizi API'sini kullanın.
Beklenmeyen sonuçlar	Sorgu, istenmeyen alanlarla eşleşir.	Hangi alanların aranacaklarını sınırlamak için kullanın searchFields .
Çok fazla sonuç	Sorgu çok kapsamlı.	Filtreleri ekleyin, searchMode=all kullanın veya gerekli terimleri + işleciyle ekleyin.
Sonuçlar beklendiği gibi sıralanmamış	İlgi puanlaması beklentilerle eşleşmiyor.	Puanlama profillerini veya anlam sıralamasını göz önünde bulundurun.
Eksik kısmi eşleşmeler	Çözümleyici beklenenden farklı bir şekilde belirteç hale getirdi.	Joker karakter (*) soneki kullanın veya Metin Çözümlemesi API'si ile çözümleyici davranışını denetleyin.
Filtre çalışmıyor	Alan filtrelenebilir olarak işaretlenmez.	Dizin şemasını, alan üzerinde filterable: true ayarlayacak şekilde güncelleyin.

İlgili içerik

Artık sorgu isteklerinin nasıl çalıştığını daha iyi anladığınıza göre, uygulamalı deneyim için aşağıdaki hızlı başlangıçları deneyin.

• Arama gezgini
• Hızlı Başlangıç: Tam metin arama
• Basit sorgu söz dizimi
• Lucene tam sorgu söz dizimi
• OData filtre söz dizimi