Azure AI Search'te dizini güncelleştirme veya yeniden oluşturma

Bu makalede Azure AI Search'teki mevcut bir dizinin artımlı dizin oluşturma yoluyla şema değişiklikleri veya içerik değişiklikleriyle nasıl güncelleştirilecekleri açıklanmaktadır. Yeniden derlemelerin gerekli olduğu durumları açıklar ve devam eden sorgu istekleri üzerinde yeniden derlemelerin etkilerini azaltmaya yönelik öneriler sağlar.

Etkin geliştirme sırasında, dizin tasarımını yinelerken dizinleri bırakmak ve yeniden oluşturmak yaygın bir işlemdir. Çoğu geliştirici, yeniden dizinlemenin daha hızlı gerçekleşmesi için verilerinin küçük bir temsili örneğiyle çalışır.

Üretimde olan uygulamalarda şema değişiklikleri için, mevcut bir dizini yan yana çalıştıran yeni bir dizin oluşturmanızı ve test etmenizi öneririz. Uygulama kodunuzun değiştirilmesini önlemek için yeni dizinde değiştirmek için bir dizin diğer adı kullanın.

İçeriği güncelleştirme

Artımlı dizin oluşturma ve kaynak verilerdeki değişikliklere karşı bir dizini eşitleme, çoğu arama uygulaması için temeldir. Bu bölümde, REST API aracılığıyla bir arama dizinindeki alan içeriğini güncelleştirmeye yönelik iş akışı açıklanmaktadır, ancak Azure SDK'ları eşdeğer işlevler sağlar.

İsteğin gövdesi dizine eklenecek bir veya daha fazla belge içeriyor. Belgeler benzersiz bir büyük/küçük harfe duyarlı anahtarla 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.

{  
  "value": [  
    {  
      "@search.action": "upload (default) | merge | mergeOrUpload | delete",  
      "key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)  
      "field_name": field_value (key/value pairs matching index schema)  
        ...  
    },  
    ...  
  ]  
}

• İlk olarak, Belgeler - Dizin (REST) veya Azure SDK'larındaki eşdeğer bir API gibi belgeleri yüklemek için API'leri kullanın. Dizin oluşturma teknikleri hakkında daha fazla bilgi için bkz . Belgeleri yükleme.

• Büyük bir güncelleştirme için toplu işlem (toplu iş başına en fazla 1.000 belge veya toplu iş başına yaklaşık 16 MB (hangisi önce gelirse) önerilir ve dizin oluşturma performansını önemli ölçüde artırır.

• @search.action Var olan belgeler üzerindeki etkisini belirlemek için API'de parametresini ayarlayın.

  Eylem	Etki
  delete	Belgenin tamamını dizinden kaldırır. Tek bir alanı kaldırmak istiyorsanız, bunun yerine birleştirmeyi kullanın ve söz konusu alanı null olarak ayarlayın. Silinen belgeler ve alanlar dizinde hemen yer açmaz. Birkaç dakikada bir, fiziksel silme işlemini arka plan işlemi gerçekleştirir. Dizin istatistiklerini döndürmek için Azure portalını veya API'yi kullandığınızda, silme işleminin Azure portalına ve API'ler aracılığıyla yansıtılmadan önce kısa bir gecikme bekleyebilirsiniz.
  birleşmek	Zaten var olan bir belgeyi güncelleştirir ve bulunamaz bir belgeyi 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 değeriyle ["budget"] başlıyorsa ve ile ["economy", "pool"]bir birleştirme yürütürseniz, alanın son değeri tags olur ["economy", "pool"]. Bu ["budget", "economy", "pool"]olmayacak. Aynı davranış karmaşık koleksiyonlar için de geçerlidir. Belge, değeri [{ "Type": "Budget Room", "BaseRate": 75.0 }]olan Rooms adlı karmaşık bir koleksiyon alanı içeriyorsa ve değeriyle [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]bir birleştirme yürütürseniz Rooms alanının son değeri olur [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Yeni ve mevcut değerleri eklemez veya birleştirmez.
  mergeOrUpload	Belge varsa birleştirme ve belge yeniyse karşıya yükleme gibi davranır. Bu, artımlı güncelleştirmeler için en yaygın eylemdir.
  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.

Sorgular dizin oluşturma sırasında çalışmaya devam ediyor, ancak var olan alanları güncelleştiriyor veya kaldırıyorsanız, karışık sonuçlar ve daha yüksek azaltma sıklığı bekleyebilirsiniz.

Yanıtlar

Başarılı bir yanıt için durum kodu 200 döndürülür, yani tüm öğeler durabilir bir şekilde depolanmıştır ve dizine alınacaktır. Dizin oluşturma arka planda çalışır ve dizin oluşturma işlemi tamamlandıktan birkaç saniye sonra yeni belgeleri kullanıma (sorgulanabilir ve aranabilir) sağlar. Belirli bir gecikme, hizmet üzerindeki yüke bağlıdır.

Başarılı dizin oluşturma, tüm öğeler için true olarak ayarlanan durum özelliğinin yanı sıra özelliğin statusCode 201 (yeni yüklenen belgeler için) veya 200 (birleştirilmiş veya silinmiş belgeler için) olarak ayarlanmasıyla gösterilir:

{
  "value": [
    {
      "key": "unique_key_of_new_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 201
    },
    {
      "key": "unique_key_of_merged_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    },
    {
      "key": "unique_key_of_deleted_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    }
  ]
}

En az bir öğe başarıyla dizine alınamayınca durum kodu 207 döndürülür. Dizine kaydedilmemiş öğelerde durum alanı false olarak ayarlanır. errorMessage ve statusCode özellikleri dizin oluşturma hatasının nedenini gösterir:

{
  "value": [
    {
      "key": "unique_key_of_document_1",
      "status": false,
      "errorMessage": "The search service is too busy to process this document. Please try again later.",
      "statusCode": 503
    },
    {
      "key": "unique_key_of_document_2",
      "status": false,
      "errorMessage": "Document not found.",
      "statusCode": 404
    },
    {
      "key": "unique_key_of_document_3",
      "status": false,
      "errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
      "statusCode": 422
    }
  ]
}  

errorMessage özelliği, mümkünse dizin oluşturma hatasının nedenini gösterir.

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.

İ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 için statusCode özelliğini denetleyerek bunu onaylayabilirsiniz. statusCode 503 ise dizin oluşturma isteklerini azaltmanızı öneririz. Aksi takdirde, trafik dizine eklenemezse sistem 503 hatayla tüm istekleri reddetmeye başlayabilir.

Durum kodu 429, dizin başına belge sayısı kotanızı aştığınızı gösterir. Yeni bir dizin oluşturmanız veya daha yüksek kapasite sınırları için yükseltmeniz gerekir.

Artımlı dizin oluşturma ipuçları

• Dizin oluşturucular artımlı dizin oluşturmayı otomatikleştirir. Dizin oluşturucu kullanabiliyorsanız ve veri kaynağı değişiklik izlemeyi destekliyorsa, aranabilir içerik eklemek, güncelleştirmek veya üzerine yazmak için dizin oluşturucuyu yinelenen bir zamanlamaya göre çalıştırarak dış verilerinizle eşitlenmesini sağlayabilirsiniz.

• Doğrudan gönderme API'sini kullanarak dizin çağrıları yapıyorsanız, arama eylemi olarak kullanınmergeOrUpload.

• Yük, eklemek, güncelleştirmek veya silmek istediğiniz her belgenin anahtarlarını veya tanımlayıcılarını içermelidir.

• Dizininiz vektör alanları içeriyorsa ve özelliğini false olarak ayarlarsanızstored, değer değişmemiş olsa bile kısmi belge güncelleştirmenizde vektör sağladığınızdan emin olun. false ayarının stored yan etkisi, vektörlerin yeniden dizinleme işlemine bırakılmasıdır. Belge yükünde vektör sağlanması bunun gerçekleşmesini önler.

• Karmaşık türlerdeki basit alanların ve alt alanların içeriğini güncelleştirmek için, yalnızca değiştirmek istediğiniz alanları listeleyin. Örneğin, yalnızca bir açıklama alanını güncelleştirmeniz gerekiyorsa, yük belge anahtarından ve değiştirilen açıklamadan oluşmalıdır. Diğer alanların atlanması, mevcut değerlerini korur.

• Satır içi değişiklikleri dize koleksiyonunda birleştirmek için değerin tamamını sağlayın. Önceki bölümdeki tags alan örneğini hatırlayın. Yeni değerler, alanın tamamı için eski değerlerin üzerine yazılır ve alanın içeriğinde birleştirme yoktur.

Aşağıda şu ipuçlarını gösteren bir REST API örneği verilmiştir:

### Get Stay-Kay City Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

### Change the description, city, and tags for Stay-Kay City Hotel
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "value": [
            {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "Description": "I'm overwriting the description for Stay-Kay City Hotel.",
            "Tags": ["my old item", "my new item"],
            "Address": {
                "City": "Gotham City"
                }
            }
        ]
    }
       
### Retrieve the same document, confirm the overwrites and retention of all other values
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Dizin şemasını güncelleştirme

Dizin şeması, arama hizmetinde oluşturulan fiziksel veri yapılarını tanımlar, bu nedenle tam yeniden derleme yapmadan yapabileceğiniz çok fazla şema değişikliği yoktur.

Yeniden derleme olmadan güncelleştirmeler

Aşağıdaki liste, var olan bir dizine sorunsuz bir şekilde getirilebilen şema değişikliklerini numaralandırır. Genellikle, liste sorgu yürütme sırasında kullanılan yeni alanları ve işlevleri içerir.

• Yeni alan ekle
• retrievable Var olan bir alanda özniteliği ayarlama
• Var olan bir alanda güncelleştirme searchAnalyzerindexAnalyzer
• Dizine yeni bir çözümleyici tanımı ekleme (yeni alanlara uygulanabilir)
• Puanlama profilleri ekleme, güncelleştirme veya silme
• Eş anlamlı Haritaları ekleme, güncelleştirme veya silme
• Anlamsal yapılandırmaları ekleme, güncelleştirme veya silme
• CORS ayarlarını ekleme, güncelleştirme veya silme

İşlemlerin sırası:

1. Dizin tanımını alın.

2. Şemayı önceki listeden güncelleştirmelerle düzeltin.

3. Arama hizmetindeki dizin şemasını güncelleştirin.

4. Yeni bir alan eklediyseniz dizin içeriğini düzeltilmiş şemanızla eşleşecek şekilde güncelleştirin. Diğer tüm değişiklikler için mevcut dizinlenmiş içerik olduğu gibi kullanılır.

Bir dizin şemasını yeni bir alan içerecek şekilde güncelleştirdiğinizde, dizindeki mevcut belgelere bu alan için null değer verilir. Bir sonraki dizin oluşturma işinde, dış kaynak verilerindeki değerler Azure AI Search tarafından eklenen null değerlerin yerini alır.

Güncelleştirmeler sırasında sorgu kesintisi yaşanmamalıdır, ancak güncelleştirmeler yürürlüğe girecek şekilde sorgu sonuçları farklılık gösterir.

Yeniden derleme gerektiren güncelleştirmeler

Bazı değişiklikler için dizin bırakma ve yeniden derleme gerekir ve geçerli bir dizini yenisiyle değiştirir.

İşlemlerin sırası:

1. İleride başvurmak veya yeni bir sürüm için temel olarak kullanmak üzere ihtiyacınız olması durumunda bir dizin tanımı alın.

2. Dizin içeriğinin bir kopyasını korumak için bir yedekleme ve geri yükleme çözümü kullanmayı göz önünde bulundurun. C# ve Python'da çözümler vardır. Daha güncel olduğundan Python sürümünü öneririz.

   Arama hizmetinizde kapasite varsa yenisini oluştururken ve test ederken mevcut dizini koruyun.

3. Mevcut dizini bırakın. Dizini hedefleyen sorgular hemen bırakılır. Bir dizini silmenin geri alınamaz olduğunu ve alan koleksiyonu ve diğer yapılar için fiziksel depolamayı yok ettiğini unutmayın.

4. İsteğin gövdesinin değiştirilmiş veya değiştirilmiş alan tanımlarını ve yapılandırmalarını içerdiği düzeltilmiş bir dizin gönderin.

5. Dizini dış kaynaktan belgelerle birlikte yükleyin. Belgeler, yeni şemanın alan tanımları ve yapılandırmaları kullanılarak dizine alınır.

Dizini oluşturduğunuzda, dizin şemasındaki her alan için fiziksel depolama alanı ayrılır ve aranabilir her alan için ters dizin ve her vektör alanı için bir vektör dizini oluşturulur. Aranamayan alanlar filtrelerde veya ifadelerde kullanılabilir, ancak ters dizinleri yoktur ve tam metin veya benzer arama yapılabilir değildir. Dizin yeniden derlemesinde, bu ters dizinler ve vektör dizinleri, sağladığınız dizin şemasına göre silinir ve yeniden oluşturulur.

Uygulama kodunda kesintiyi en aza indirmek için dizin diğer adı oluşturmayı göz önünde bulundurun. Uygulama kodu diğer ada başvurur, ancak diğer adın işaret olduğu dizinin adını güncelleştirebilirsiniz.

İş yüklerini dengeleme

Dizin oluşturma arka planda çalışmaz, ancak arama hizmeti dizin oluşturma işlerini devam eden sorgulara göre dengeler. Dizin oluşturma sırasında, sorguların zamanında tamamlandığından emin olmak için Azure portalında sorgu isteklerini izleyebilirsiniz.

Dizin oluşturma iş yükleri kabul edilemez düzeyde sorgu gecikme süresine neden olursa performans analizi gerçekleştirin ve olası risk azaltma için bu performans ipuçlarını gözden geçirin.

Güncelleştirmeleri denetle

İlk belge yüklenir yüklenmez bir dizini sorgulamaya başlayabilirsiniz. Bir belgenin kimliğini biliyorsanız, Arama Belgesi REST API'si belirli bir belgeyi döndürür. Daha geniş kapsamlı test için dizin tamamen yüklenene kadar beklemeniz ve ardından görmeyi beklediğiniz bağlamı doğrulamak için sorguları kullanmanız gerekir.

Güncelleştirilmiş içeriği denetlemek için Arama Gezgini'ni veya REST istemcisini kullanabilirsiniz.

Bir alanı eklediyseniz veya yeniden adlandırdıysanız, o alanı döndürmek için select komutunu kullanın:

"search": "*",
"select": "document-id, my-new-field, some-old-field",
"count": true

Azure portalı dizin boyutu ve vektör dizin boyutu sağlar. Bir dizini güncelleştirdikten sonra bu değerleri de kontrol edebilirsiniz, ancak hizmet değişikliği işlerken küçük bir gecikme beklemeyi ve portal yenileme hızlarını hesaba katmak için birkaç dakika beklemeyi unutmayın.

Yalnız bırakılmış belgeleri silme

Azure AI Search, belirli bir belgeyi tek başına aramanız, güncelleştirmeniz ve silmeniz için belge düzeyinde işlemleri destekler. Aşağıdaki örnekte belgenin nasıl silineceği gösterilmektedir.

Belgenin silinmesi dizinde hemen yer açmaz. Birkaç dakikada bir, fiziksel silme işlemini arka plan işlemi gerçekleştirir. Dizin istatistiklerini döndürmek için Azure portalını veya API'yi kullandığınızda, silme işleminin Azure portalına ve API ölçümlerine yansıtılmadan önce kısa bir gecikme bekleyebilirsiniz.

1. Belge anahtarının hangi alan olduğunu belirleyin. Azure portalında her dizinin alanlarını görüntüleyebilirsiniz. Belge anahtarları dize alanlarıdır ve daha kolay fark etmelerini sağlamak için bir anahtar simgesiyle gösterilir.

2. Belge anahtarı alanının değerlerini denetleyin: search=*&$select=HotelId. Basit bir dize basittir, ancak dizinde base-64 kodlanmış bir alan kullanılıyorsa veya bir parsingMode ayardan arama belgeleri oluşturulduysa, aşina olmadığınız değerlerle çalışıyor olabilirsiniz.

3. Belge kimliğinin değerini doğrulamak ve silmeden önce içeriğini gözden geçirmek için belgeyi arayın. İstekte anahtarı veya belge kimliğini belirtin. Aşağıdaki örneklerde Hotels örnek dizini için basit bir dize ve cog-search-demo dizininin metadata_storage_path anahtarı için base-64 kodlanmış bir dize gösterilmektedir.

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

   GET https://[service name].search.windows.net/indexes/cog-search-demo/docs/aHR0cHM6Ly9oZWlkaWJsb2JzdG9yYWdlMi5ibG9iLmNvcmUud2luZG93cy5uZXQvY29nLXNlYXJjaC1kZW1vL2d1dGhyaWUuanBn0?api-version=2024-07-01
   

4. Arama dizininden kaldırmak için sil @search.action seçeneğini kullanarak belgeyi silin.

   POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/index?api-version=2024-07-01
   Content-Type: application/json   
   api-key: [admin key] 
   {  
     "value": [  
       {  
         "@search.action": "delete",  
         "id": "1111"  
       }  
     ]  
   }
   

Ayrıca bkz.

• Dizin Oluşturucu’ya genel bakış
• Büyük veri kümelerini büyük ölçekte dizinleme
• Azure portalında dizin oluşturma
• Azure SQL Veritabanı dizin oluşturucu
• NoSQL için Azure Cosmos DB dizin oluşturucu
• Azure blob dizin oluşturucu
• Azure tabloları dizin oluşturucu
• Azure AI Search'te güvenlik