Azure Yapay Zeka Arama'te arama dizinine veri yükleme

Bu makalede REST API'leri, Azure SDK'ları veya Azure portalını kullanarak belgeleri önceden tanımlanmış bir arama dizinine aktarma işlemi açıklanmaktadır.

Önkoşullar

• Azure Yapay Zeka Arama hizmeti (herhangi bir katman). Bir hizmet oluşturun veya var olan bir hizmeti bulun.

• Var olan bir arama dizini. Bu makalede zaten bir dizin oluşturduğunuz varsayılır. Bir adımda oluşturmanız ve yüklemeniz gerekiyorsa içeri aktarma sihirbazını veya dizin oluşturucuyu kullanın.

• Belgeleri yükleme izinleri:

  • Anahtar tabanlı kimlik doğrulaması: Arama hizmetiniz için bir yönetici API anahtarı .
  • Rol tabanlı kimlik doğrulaması: Arama hizmeti üzerinde Dizin Verisi Katkı Sağlayıcı rolü.

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

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

Azure portal’ı kullanma

Azure portalında, sorunsuz bir iş akışında dizinler oluşturmak ve yüklemek için içeri aktarma sihirbazını kullanın. Mevcut bir dizini yüklemek istiyorsanız alternatif bir yaklaşım seçin.

1. Azure portalında arama hizmetinize gidin.

2. Genel Bakış sayfasında, arama dizini oluşturmak ve doldurmak için komut çubuğunda Verileri içeri aktar'ı seçin.

   

   İş akışını gözden geçirmek için şu bağlantıları izleyebilirsiniz: Hızlı Başlangıç: Azure AI Arama dizini oluşturma ve Hızlı Başlangıç: Tümleşik vektörleştirme.

3. Sihirbaz tamamlandıktan sonra sonuçları denetlemek için Arama Gezgini'ni kullanın.

REST API’leri kullanma

Belgeler - Dizin , bir arama dizinine veri aktarmaya yönelik REST API'dir.

İsteğin gövdesi dizine eklenecek bir veya daha fazla belge içeriyor. Belgeler büyük/küçük harfe duyarlı bir anahtar aracılığıyla benzersiz olarak tanımlanır. Her belge bir eylemle ilişkilendirilir: "upload", "delete", "merge" veya "mergeOrUpload". Karşıya yükleme istekleri, belge verilerini bir dizi anahtar/değer çifti olarak içermelidir.

REST API'leri, çok fazla kod yazmak zorunda kalmadan dizin oluşturma iş akışlarını test etmek için kullanabileceğiniz ilk kavram kanıtı testi için kullanışlıdır. @search.action parametresi, belgelerin tam olarak mı yoksa kısmen belirli alanlar için yeni veya değiştirme değerleri bakımından mı ekleneceğini belirler.

Hızlı Başlangıç: REST kullanan tam metin araması adımları açıklar. Aşağıdaki örnek, örneğin değiştirilmiş bir sürümüdür. Değer kısa olacak şekilde kırpılır ve var olan bir belgenin üzerine yazılmasını önlemek için ilk HotelId değeri değiştirilir.

1. POST çağrısını, dizin adını, "docs/index" uç noktasını ve @search.action parametresini içeren istek gövdesini belirterek formüle edin.

   POST https://[service name].search.windows.net/indexes/hotels-sample/docs/index?api-version=2026-04-01
   Content-Type: application/json   
   api-key: [admin key] 
   {
       "value": [
       {
       "@search.action": "upload",
       "HotelId": "1111",
       "HotelName": "Stay-Kay City Hotel",
       "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
       "Category": "Boutique",
       "Tags": [ "pool", "air conditioning", "concierge" ]
       },
       {
       "@search.action": "mergeOrUpload",
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "This is description is replacing the original one for this hotel. New and changed values overwrite the previous ones. In a comma-delimited list like Tags, be sure to provide the full list because there is no merging of values within the field itself.",
       "Category": "Boutique",
       "Tags": [ "pool", "free wifi", "concierge", "my first new tag", "my second new tag" ]
       }
     ]
   }
   

2. @search.action Belge oluşturmak veya üzerine yazmak için parametresini upload olarak ayarlayın. Belgenin içindeki belirli alanlara yönelik güncellemeleri hedefliyorsanız, bunu merge veya uploadOrMerge olarak ayarlayın. Önceki örnekte her iki eylem de gösterilmektedir.

   Eylem	Etki
   karşıya yükle	Belge yeniyse eklendiği ve varsa güncelleştirildiği veya değiştirildiği "upsert" örneğine benzer. Belgede dizinin gerektirdiği değerler eksikse, belge alanının değeri null olarak ayarlanır.
   birleşmek	Zaten var olan bir belgeyi günceller, ancak bulunamayan bir belgenin işleminde başarısız olur. Birleştirme, mevcut değerlerin yerini alır. Bu nedenle, türünde Collection(Edm.String)alanlar gibi birden çok değer içeren koleksiyon alanlarını denetlemeyi unutmayın. Örneğin, bir tags alanı ["budget"] değeriyle başlarsa ve ["economy", "pool"] ile bir birleştirme gerçekleştirirseniz, tags alanının son değeri ["economy", "pool"] olur. Bu değil ["budget", "economy", "pool"].
   BirleştirVeyaYükle	Belge mevcutsa birleştirme, yeniyse karşıya yükleme işlemi gibi davranır. Bu, artımlı güncelleştirmeler için en yaygın eylemdir.
   delete	Delete, belirtilen belgeyi dizinden kaldırır. Silme işleminde anahtar alanı dışında belirttiğiniz tüm alan yoksayılır. Bir belgeden tek bir alanı kaldırmak istiyorsanız, bunun yerine birleştirmeyi kullanın ve alanı açıkça null olarak ayarlayın. Daha fazla bilgi için bkz. Arama dizinindeki belgeleri silme.

   İstek gövdesindeki eylemin ilk olarak yürütülmesi için herhangi bir sıralama garantisi yoktur. Tek bir istek gövdesinde aynı belgeyle ilişkilendirilmiş birden çok "birleştirme" eyleminin olması önerilmez. Aynı belge için birden çok "birleştirme" eylemi gerekiyorsa, belgeyi arama dizininde güncelleştirmeden önce istemci tarafı birleştirme işlemini gerçekleştirin.

   İlkel koleksiyonlarda, belge, Collection(Edm.String) türünde ve ["budget"] değerine sahip bir Etiket alanı içeriyorsa ve Etiketler için ["economy", "pool"] değeriyle bir birleştirme işlemi yaparsanız, Etiketler alanının son değeri ["economy", "pool"] olur. “Bütçe”, “ekonomi” veya “havuz” değil.

   Karmaşık koleksiyonlarda, belge { "Type": "Budget Room", "BaseRate": 75.0 } değerine sahip Rooms adlı karmaşık bir koleksiyon alanı içeriyorsa ve [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] değeriyle bir birleştirme yapıldığında, Rooms alanının son değeri [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] olur. Aşağıdakilerden biri olmayacaktır:

   • [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (ekleme öğeleri)

   • [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (öğeleri sırayla birleştirin, ardından ekleri ekler)

   Uyarı

   Saat dilimi bilgilerini içeren DateTimeOffset değerlerini dizininize yüklediğinizde, Azure Yapay Zeka Arama bu değerleri UTC olarak normalleştirir. Örneğin, 2025-01-13T14:03:00-08:00, 2025-01-13T22:03:00Z olarak depolanır. Saat dilimi bilgilerini depolamanız gerekiyorsa dizininize fazladan bir sütun ekleyin.

3. İsteği gönderin.

   Aşağıdaki tabloda, yanıtta döndürülebilecek çeşitli belge başına durum kodları açıklanmaktadır. Bazı durum kodları isteğin kendisiyle ilgili sorunları, diğerleri ise geçici hata koşullarını belirtir. İkincisi, bir gecikmeden sonra yeniden denemeniz gerekir.

   Durum kodu	Meaning	Yeniden denenebilir	Notes
   200	Belge başarıyla değiştirildi veya silindi.	Yok	Silme işlemleri idemopotenttir. Başka bir ifadeyle, dizinde bir belge anahtarı olmasa bile, bu anahtarla silme işlemi denenmesi 200 durum koduyla sonuçlanır.
   201	Belge başarıyla oluşturuldu.	Yok
   400	Belgede dizine alınmasını engelleyen bir hata oluştu.	Hayı	Yanıttaki hata iletisi, belgede neyin yanlış olduğunu gösterir.
   404	Belirtilen anahtar dizinde bulunmadığından belge birleştirilemedi.	Hayı	Bu hata, yeni belgeler oluşturduklarından dolayı karşıya yüklemeler için oluşmaz; silme işlemleri için ise idem-potent oldukları için gerçekleşmez.
   409	Belgeyi dizine almaya çalışırken sürüm çakışması algılandı.	Yes	Aynı belgeyi eş zamanlı olarak birden çok kez dizine almaya çalıştığınızda bu durum oluşabilir.
   422	Dizin, 'allowIndexDowntime' seçeneği 'true' olarak ayarlanarak güncellendiği için geçici olarak kullanılamıyor.	Yes
   429	Dizin başına belge sayısı kotanızı aştığınızı gösterir.	Hayı	Yeni bir dizin oluşturmanız veya daha yüksek kapasite sınırları için yükseltmeniz gerekir.
   503	Arama hizmetiniz, büyük olasılıkla ağır yük nedeniyle geçici olarak kullanılamıyor.	Yes	Kodunuzun yeniden denemeden önce beklemesi gerekir, yoksa hizmetin kullanım dışı durumunun uzaması riskiyle karşılaşırsınız.

   Uyarı

   İstemci kodunuz sık sık bir 207 yanıtıyla karşılaşırsa, olası nedenlerden biri sistemin yük altında olmasıdır. 503 özelliğini kontrol ederek statusCode ifadesini onaylayabilirsiniz. Bu durumda dizin oluşturma isteklerini azaltmanızı öneririz. Aksi takdirde, indeksleme trafiği azalmazsa, sistem 503 hatası vererek tüm istekleri reddetmeye başlayabilir.

4. Doğrulama adımı olarak yeni eklediğiniz belgeleri arayın:

   GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2026-04-01
   

Başvuru:Belgeler - Dizin, Belgeler - Get

Başarılı bir dizin isteği, tüm belgelerin başarılı olduğu bir grup için HTTP 200 (Tamam) veya bazı belgeler başarısız olursa HTTP 207 (Çoklu Durum) döndürür. Yanıt gövdesi her belgenin durumunu içerir:

{
    "value": [
        { "key": "1111", "status": true, "statusCode": 201 },
        { "key": "2", "status": true, "statusCode": 200 }
    ]
}

Belge anahtarı veya kimliği yeni olduğunda , null değeri belgede belirtilmeyen herhangi bir alanın değeri olur. Var olan bir belgedeki eylemler için, güncelleştirilmiş değerler önceki değerlerin yerini alır. "Birleştirme" veya "mergeUpload" içinde belirtilmemiş tüm alanlar arama dizininde olduğu gibi bırakılır.

Azure SDK'larını kullanma

Programlanabilirlik aşağıdaki Azure SDK'larında sağlanır.

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

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

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

// Define documents to upload
var documents = new[]
{
    new { HotelId = "1111", HotelName = "Stay-Kay City Hotel", Category = "Boutique" },
    new { HotelId = "1112", HotelName = "Old Century Hotel", Category = "Luxury" }
};

// Upload documents
IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(
    IndexDocumentsBatch.Upload(documents));

Console.WriteLine($"Uploaded {result.Results.Count} documents");

Veri yükünüzü doğrulama

Belgeleri yükledikten sonra verilerin doğru şekilde dizinlendiğini doğrulayın.

GET https://[service-name].search.windows.net/indexes/hotels-sample/docs/1111?api-version=2026-04-01
api-key: [admin-key]

// Verify document was indexed
var document = await searchClient.GetDocumentAsync<Hotel>("1111");
Console.WriteLine($"Found: {document.Value.HotelName}");

Veri içeri aktarma nasıl çalışır?

Arama hizmeti, dizin şemasına uygun JSON belgelerini kabul eder. Arama hizmeti, JSON belgelerinde düz metin içeriğini ve vektör içeriğini içeri aktarabilir ve dizinleyebilir.

• Düz metin içeriği dış veri kaynağındaki alanlardan, meta veri özelliklerinden veya beceri kümesi tarafından oluşturulan zenginleştirilmiş içerikten alınır. Beceriler görüntülerden ve yapılandırılmamış içeriklerden metinsel açıklamaları ayıklayabilir veya çıkarabilir.

• Vektör içeriği, bunu sağlayan bir veri kaynağından alınır veya Azure Yapay Zeka Arama dizin oluşturucu iş yükünde tümleşik vektörleştirme uygulayan bir beceri kümesi tarafından oluşturulur.

Bu belgeleri kendiniz hazırlayabilirsiniz, ancak içerik desteklenen bir veri kaynağında bulunuyorsa, dizin oluşturucu çalıştırmak veya içeri aktarma sihirbazını kullanmak belge alma, JSON serileştirme ve dizin oluşturmayı otomatikleştirebilir.

Veriler dizine eklendikten sonra dizinin fiziksel veri yapıları kilitlenir. Nelerin değiştirilebileceği ve değiştirilemeyeceği konusunda rehberlik için bkz. Dizini güncelleştirme ve yeniden derleme.

Dizin oluşturma bir arka plan işlemi değildir. Arama hizmeti dizin oluşturma ve sorgu iş yüklerini dengeler, ancak sorgu gecikme süresi çok yüksekse, kapasite ekleyebilir veya dizin yüklemek için düşük sorgu etkinliği dönemlerini belirleyebilirsiniz.

Daha fazla bilgi için bkz . Veri içeri aktarma stratejileri.

Sık karşılaşılan hataları giderme