Azure AI Search'te dizin oluşturma

Bu makalede, bir arama dizini için şema tanımlama ve bir arama hizmetine gönderme adımlarını öğrenin. Dizin oluşturmak, arama hizmetinizdeki fiziksel veri yapılarını oluşturur. Dizin mevcut olduğunda, dizini ayrı bir görev olarak yükleyin.

Önkoşullar

• Anahtar tabanlı kimlik doğrulaması için arama hizmeti katkıda bulunanı veya yönetici API anahtarı olarak izinler yazın.

• Dizine eklemek istediğiniz verileri anlama. Arama dizini, aranabilir hale getirmek istediğiniz dış içeriği temel alır. Aranabilir içerik bir dizinde alan olarak depolanır. Aranabilir, alınabilir, filtrelenebilir, modellenebilir ve sıralanabilir yapmak istediğiniz kaynak alanları net bir fikriniz olmalıdır (kılavuz için şema denetim listesine bakın).

• Ayrıca kaynak verilerde dizinde belge anahtarı (veya kimliği) olarak kullanılabilecek benzersiz bir alanınız olmalıdır.

• Kararlı bir dizin konumu. Mevcut bir dizinin farklı bir arama hizmetine taşınması kullanıma açık olarak desteklenmez. Uygulama gereksinimlerini yeniden ziyaret edin ve mevcut arama hizmetinizin (kapasite ve konum) gereksinimleriniz için yeterli olduğundan emin olun.

• Son olarak, tüm hizmet katmanlarında oluşturabileceğiniz nesne sayısı için dizin sınırları vardır. Örneğin Ücretsiz katmanında denemeler yaparsanız herhangi bir zamanda yalnızca üç dizininiz olabilir. Dizinin kendi içinde, basit ve karmaşık alanların sayısında vektörler ve dizin sınırları vardır.

Belge anahtarları

Arama dizininin iki gereksinimi vardır: adı ve belge anahtarı olmalıdır.

Belge anahtarı, arama belgesinin benzersiz tanımlayıcısı ve arama belgesi ise bir şeyi tamamen açıklayan bir alan koleksiyonudur. Örneğin, bir film veri kümesini dizine alıyorsanız, arama belgesi tek bir filmin başlığını, türünü ve süresini içerir.

Azure AI Search'te belge anahtarının bir dize olması ve dizinine eklenecek içeriği sağlayan veri kaynağındaki benzersiz değerlerden kaynaklanması gerekir. Arama hizmeti anahtar değerleri oluşturmaz, ancak bazı senaryolarda (Azure tablo dizin oluşturucu gibi) var olan değerleri sentezler ve dizine alınan belgeler için benzersiz bir anahtar oluşturur.

Yeni ve güncelleştirilmiş içeriğin dizine alındığı artımlı dizin oluşturma sırasında, yeni anahtarlara sahip gelen belgeler eklenirken, dizin alanlarının null veya doldurulmuş olmasına bağlı olarak, var olan anahtarlara sahip gelen belgeler birleştirilir veya üzerine yazılır.

Şema denetim listesi

Arama dizininizin tasarım kararlarına yardımcı olması için bu denetim listesini kullanın.

1. Dizin ve alan adlarının, adlandırma kurallarına uyması için adlandırma kurallarını gözden geçirin.

2. Desteklenen veri türlerini gözden geçirin. Veri türü, alanın nasıl kullanıldığını etkiler. Örneğin sayısal içerik filtrelenebilir ancak tam metin aranamaz. En yaygın veri türü olan Edm.String, tam metin arama altyapısı kullanılarak belirteçlere ayrılan ve sorgulanan aranabilir metindir. Vektör alanı için en yaygın veri türü, Edm.Single ancak diğer türleri de kullanabilirsiniz.

3. Belge anahtarını tanımlama. Belge anahtarı bir dizin gereksinimidir. Tek bir dize alanıdır ve benzersiz değerler içeren bir kaynak veri alanından doldurulur. Örneğin Blob Depolama'dan dizin oluştururken meta veri depolama yolu genellikle belge anahtarı olarak kullanılır çünkü kapsayıcıdaki her blobu benzersiz şekilde tanımlar.

4. Veri kaynağınızda dizinde aranabilir içeriğe katkıda bulunan alanları belirleyin.

   Aranabilir nonvector içeriği, tam metin arama altyapısı kullanılarak sorgulanan kısa veya uzun dizeler içerir. İçerik ayrıntılıysa (küçük tümcecikler veya daha büyük öbekler), metnin nasıl belirteçlere ayrıldığına bakmak için farklı çözümleyicilerle denemeler yapın.

   Aranabilir vektör içeriği, matematiksel bir gösterim olarak var olan resimler veya metinler (herhangi bir dilde) olabilir. Vektör alanlarını küçültmek için dar veri türlerini veya vektör sıkıştırmayı kullanabilirsiniz.

   Alan özniteliği atamaları hem arama davranışlarını hem de arama hizmetindeki dizininizin fiziksel gösterimini belirler. Alanların nasıl belirtilmesi gerektiğini belirlemek, birçok müşteri için yinelemeli bir işlemdir. Yinelemeleri hızlandırmak için örnek verilerle başlayın, böylece kolayca bırakıp yeniden oluşturabilirsiniz.

5. Filtre olarak hangi kaynak alanların kullanılabileceğini belirleyin. Sayısal içerik ve kısa metin alanları, özellikle de yinelenen değerler içerenler iyi seçeneklerdir. Filtrelerle çalışırken şunları unutmayın:

   • Filtreler vektör ve nonvector sorgularında kullanılabilir, ancak filtrenin kendisi dizininizdeki alfasayısal (nonvector) alanlara uygulanır.

   • Filtrelenebilir alanlar isteğe bağlı olarak çok yönlü gezinmede kullanılabilir.

   • Filtrelenebilir alanlar rastgele sırayla döndürüldüğünden bunları da sıralanabilir hale getirebilirsiniz.

6. Vektör alanları için bir vektör arama yapılandırması ve gezinti yolları oluşturmak ve ekleme alanını doldurmak için kullanılan algoritmaları belirtin. Daha fazla bilgi için bkz . Vektör alanları ekleme.

   Vektör alanları, hangi algoritmaların kullanılacağı ve vektör sıkıştırması gibi, görüntülemeyen alanların sahip olmadığı ek özelliklere sahiptir.

   Vektör alanları sıralama, filtreleme ve model oluşturma gibi vektör verilerinde yararlı olmayan öznitelikleri atlar.

7. Seçici olmayan alanlar için varsayılan çözümleyicinin ("analyzer": null) mi yoksa farklı bir çözümleyicinin mi kullanılacağını belirleyin. Çözümleyiciler, dizin oluşturma ve sorgu yürütme sırasında metin alanlarını belirteçlere ayırmak için kullanılır.

   Çok dilli dizeler için bir dil çözümleyicisi düşünün.

   Hecelenmiş dizeler veya özel karakterler için özel çözümleyicileri göz önünde bulundurun. Bir örnek, bir alanın tüm içeriğini tek bir belirteç olarak ele alan anahtar sözcüktür . Bu davranış posta kodları, kimlikler ve bazı ürün adları gibi veriler için yararlıdır. Daha fazla bilgi için bkz. Kısmi terim araması ve özel karakterler içeren desenler.

Not

Tam metin araması, dizin oluşturma sırasında belirteçlere ayrılan terimler üzerinden gerçekleştirilir. Sorgularınız beklediğiniz sonuçları döndüremezse, aradığınız dizenin gerçekten var olduğunu doğrulamak için belirteç oluşturma test edin. Çeşitli çözümleyiciler için belirteçlerin nasıl üretildiğini görmek üzere dizelerde farklı çözümleyiciler deneyebilirsiniz.

Dizin oluşturma

Dizini oluşturmaya hazır olduğunuzda, isteği gönderebilen bir arama istemcisi kullanın. Erken geliştirme ve kavram kanıtı testi için Azure portalını veya REST API'lerini kullanabilirsiniz, aksi takdirde Azure SDK'larını kullanmak yaygın bir durumdur.

Geliştirme sırasında sık yapılan yeniden derlemeleri planlayın. Fiziksel yapılar hizmette oluşturulduğundan, birçok değişiklik için dizinlerin bırakılıp yeniden oluşturulması gerekir. Yeniden derlemelerin daha hızlı gerçekleşmesi için verilerinizin bir alt kümesiyle çalışmayı düşünebilirsiniz.

Azure portalı

Portal aracılığıyla dizin tasarımı, sayısal alanlarda tam metin arama özelliklerine izin verme gibi belirli veri türleri için gereksinimleri ve şema kurallarını zorunlu kılar.

1. Azure Portal’ında oturum açın.

2. Yer olup olmadığını denetleyin. Arama hizmeti, hizmet katmanına göre değişen en fazla dizin sayısına tabidir. İkinci bir dizin için yeriniz olduğundan emin olun.

3. Arama hizmetine Genel Bakış sayfasında, arama dizini oluşturmak için iki seçenek arasından birini belirleyin:

   • Dizin şemasını belirtmek için eklenmiş bir düzenleyici olan dizin ekleme
   • İçeri aktarma sihirbazları

   Sihirbaz, dizin oluşturucu, veri kaynağı ve tamamlanmış dizin oluşturan uçtan uca bir iş akışıdır. Ayrıca verileri yükler. Bu istediğinizden fazlaysa, bunun yerine Dizin ekle'yi kullanın.

Aşağıdaki ekran görüntüsünde, dizin ekle ve Verileri içeri aktar komut çubuğunda gösterildiği yerler vurgulanır. Dizin oluşturulduktan sonra dizinleri Dizinler sekmesinde yeniden bulabilirsiniz.

İpucu

Portalda bir dizin oluşturduktan sonra JSON gösterimini kopyalayıp uygulama kodunuza ekleyebilirsiniz.

REST

Dizin Oluşturma (REST API), dizin oluşturmak için kullanılır. Arama hizmetinize bağlanmak ve istek göndermek için bir REST istemcisine ihtiyacınız vardır. Başlamak için bkz . Hızlı Başlangıç: REST kullanarak tam metin araması veya Hızlı Başlangıç: REST kullanarak vektör araması.

REST API, alan ilişkilendirmesi için varsayılan değerler sağlar. Örneğin, tüm Edm.String alanlar varsayılan olarak aranabilir. Öznitelikler açıklayıcı amaçlarla aşağıda tam olarak gösterilir, ancak varsayılan değerlerin geçerli olduğu durumlarda atlayabilirsiniz.

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "hotels",
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "retrievable": true, "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "StateProvince", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    }
  ],
  "suggesters": [ ],
  "scoringProfiles": [ ],
  "analyzers":(optional)[ ... ]
}

.NET SDK

.NET için Azure SDK'da dizin oluşturma ve güncelleştirme yöntemlerine sahip SearchIndexClient bulunur.

// Create the index
string indexName = "hotels";
SearchIndex index = new SearchIndex(indexName)
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("descriptionFr") { AnalyzerName = LexicalAnalyzerName.FrLucene }
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { SynonymMapNames = new[] { synonymMapName }, IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    }
};

await indexClient.CreateIndexAsync(index);

Daha fazla örnek için bkz. azure-search-dotnet-samples/quickstart/v11/.

Diğer SDK'lar

Azure AI Search için Azure SDK'ları genel kullanıma sunulan özellikleri uygular. Bu nedenle, bir arama dizini oluşturmak için SDK'lardan herhangi birini kullanabilirsiniz. Tümü dizin oluşturma ve güncelleştirme yöntemlerine sahip bir SearchIndexClient sağlar.

Azure SDK	İstemci	Örnekler
Java	SearchIndexClient	CreateIndexExample.java
JavaScript	SearchIndexClient	Dizinler
Python	SearchIndexClient	sample_index_crud_operations.py

Çıkış noktaları arası sorgular için ayarlama corsOptions

Dizin şemaları ayarı corsOptionsiçin bir bölüm içerir. Varsayılan olarak, tarayıcılar tüm çıkış noktaları arası istekleri engellediğinden istemci tarafı JavaScript herhangi bir API çağıramaz. Dizininizde çıkış noktaları arası sorgulara izin vermek için corsOptions özniteliğini ayarlayarak CORS'yi (Çıkış Noktaları Arası Kaynak Paylaşımı) etkinleştirin. Güvenlik nedeniyle yalnızca sorgu API'leri CORS'yi destekler.

"corsOptions": {
  "allowedOrigins": [
    "*"
  ],
  "maxAgeInSeconds": 300

CORS için aşağıdaki özellikler ayarlanabilir:

• allowedOrigins (gerekli): Bu, dizininize erişmesine izin verilen çıkış noktalarının listesidir. Bu kaynaklardan sunulan JavaScript kodunun dizininizi sorgulamasına izin verilir (çağıranın geçerli bir anahtar sağladığını veya izinlere sahip olduğunu varsayarsak). Her çıkış noktası genellikle formdadır protocol://<fully-qualified-domain-name>:<port> ancak <port> genellikle atlanır. Daha fazla bilgi için bkz . Çıkış noktaları arası kaynak paylaşımı (Wikipedia).

  Tüm çıkış noktalarına erişime izin vermek istiyorsanız, allowedOrigins dizisine tek bir öğe olarak ekleyin*. Bu, üretim arama hizmetleri için önerilen bir uygulama değildir, ancak genellikle geliştirme ve hata ayıklama için yararlıdır.

• maxAgeInSeconds (isteğe bağlı): Tarayıcılar, CORS denetim öncesi yanıtlarını önbelleğe alma süresini (saniye cinsinden) belirlemek için bu değeri kullanır. Bu negatif olmayan bir tamsayı olmalıdır. Daha uzun bir önbellek süresi daha iyi performans sağlar, ancak CORS ilkesinin geçerlilik süresi uzatır. Bu değer ayarlı değilse, varsayılan olarak beş dakikalık bir süre kullanılır.

Mevcut dizinlerde izin verilen güncelleştirmeler

Dizin Oluştur, arama hizmetinizde fiziksel veri yapılarını (dosyalar ve ters dizinler) oluşturur. Dizin oluşturulduktan sonra, Dizin Oluştur veya Güncelleştir'i kullanarak değişiklikleri etkileyebilme olanağınız, değişikliklerinizin bu fiziksel yapıları geçersiz kılıp geçersiz kılmadığına bağlı olarak değişir. Alan dizininizde oluşturulduktan sonra alan özniteliklerinin çoğu değiştirilemez.

Alternatif olarak, uygulama kodunuzda kararlı bir başvuru görevi görecek bir dizin diğer adı oluşturabilirsiniz. Kodunuzu güncelleştirmek yerine, bir dizin diğer adını daha yeni dizin sürümlerine işaret eden şekilde güncelleştirebilirsiniz.

Tasarım sürecindeki değişim oranını en aza indirmek için aşağıdaki tabloda şemada hangi öğelerin sabit ve esnek olduğu açıklanmaktadır. Sabit bir öğeyi değiştirmek için dizin yeniden derlemesi gerekirken, esnek öğeler herhangi bir zamanda fiziksel uygulamayı etkilemeden değiştirilebilir.

Öğe	Güncelleştirilebilir mi?
Veri Akışı Adı	Hayır
Anahtar	Hayır
Alan adları ve türleri	Hayır
Alan öznitelikleri (aranabilir, filtrelenebilir, modellenebilir, sıralanabilir)	Hayır
Alan özniteliği (alınabilir)	Yes
Depolanan (vektörler için geçerlidir)	Hayır
Analyzer	Dizine özel çözümleyiciler ekleyebilir ve değiştirebilirsiniz. Dize alanlarındaki çözümleyici atamalarıyla ilgili olarak, yalnızca değiştirebilirsiniz searchAnalyzer. Diğer tüm atamalar ve değişiklikler için yeniden derleme gerekir.
Puanlama modelleri	Yes
Öneri araçları	Hayır
çıkış noktaları arası kaynak paylaşımı (CORS)	Yes
Şifreleme	Yes

Sonraki adımlar

Bir dizini verilerle yükleme veya eş anlamlılar eşlemesi ile dizini genişletme hakkında bilgi sahibi olmak için aşağıdaki bağlantıları kullanın.

• Verileri içeri aktarmaya genel bakış
• Vektör alanları ekleme
• Belgeleri yükleme
• Dizini güncelleştirme
• Eş anlamlı haritalar