REST Öğreticisi: Azure AI Search'te aranabilir içerik oluşturmak için beceri kümelerini kullanma
Bu öğreticide, dizin oluşturma sırasında içerik ayıklama ve dönüşümler için yapay zeka zenginleştirme işlem hattı oluşturan REST API'lerini çağırmayı öğrenin.
Beceri kümeleri ham içeriğe yapay zeka işlemesi ekleyerek bu içeriği daha düzgün ve aranabilir hale getirir. Beceri kümelerinin nasıl çalıştığını öğrendiğiniz zaman, görüntü analizinden doğal dil işlemeye, dışarıdan sağladığınız özelleştirilmiş işlemeye kadar çok çeşitli dönüştürmeleri destekleyebilirsiniz.
Bu öğretici şunların nasıl yapılacağını öğrenmenize yardımcı olur:
- Zenginleştirme işlem hattında nesneleri tanımlama.
- Beceri kümesi oluşturun. OCR, dil algılama, varlık tanıma ve anahtar ifade ayıklamayı çağır.
- İşlem hattını yürütür. Arama dizini oluşturma ve yükleme.
- Tam metin araması kullanarak sonuçları denetleyin.
Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap açın.
Genel bakış
Bu öğreticide veri kaynağı, dizin, dizin oluşturucu ve beceri kümesi oluşturmak için REST istemcisi ve Azure AI Search REST API'leri kullanılır.
Dizin oluşturucu, azure Depolama bir blob kapsayıcısında örnek verilerin (yapılandırılmamış metin ve görüntüler) içerik ayıklamasıyla başlayarak işlem hattındaki her adımı yönlendirir.
İçerik ayıklandıktan sonra beceri kümesi, bilgileri bulmak ve ayıklamak için Microsoft'tan yerleşik becerileri yürütür. Bu beceriler arasında resimlerde Optik Karakter Tanıma (OCR), metinde dil algılama, anahtar ifade ayıklama ve varlık tanıma (kuruluşlar) sayılabilir. Beceri kümesi tarafından oluşturulan yeni bilgiler bir dizindeki alanlara gönderilir. Dizin dolduruldıktan sonra sorgular, modeller ve filtrelerdeki alanları kullanabilirsiniz.
Önkoşullar
Not
Bu öğretici için ücretsiz bir arama hizmeti kullanabilirsiniz. Ücretsiz katman sizi üç dizin, üç dizin oluşturucu ve üç veri kaynağıyla sınırlar. Bu öğreticide hepsinden birer tane oluşturulur. Başlamadan önce, hizmetinizde yeni kaynakları kabul etmek için yer olduğundan emin olun.
Dosyaları indirme
Örnek veri deposunun zip dosyasını indirin ve içeriğini ayıklayın. Nasıl olduğunu öğrenin.
Örnek verileri Azure Depolama'a yükleme
Azure Depolama'da yeni bir kapsayıcı oluşturun ve bunu cog-search-demo olarak adlandırın.
Örnek veri dosyalarını karşıya yükleyin.
Azure AI Search'te bağlantı formüle edebilmeniz için depolama bağlantı dizesi alın.
Sol tarafta Erişim anahtarları'nı seçin.
Birinci veya ikinci anahtar için bağlantı dizesi kopyalayın. bağlantı dizesi aşağıdaki örneğe benzer:
DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
Azure Yapay Zeka Hizmetleri
Yerleşik yapay zeka zenginleştirmesi, Dil hizmeti ve doğal dil ve görüntü işleme için Azure AI Vision dahil olmak üzere Azure yapay zeka hizmetleri tarafından desteklenir. Bu öğretici gibi küçük iş yükleri için dizin oluşturucu başına yirmi işlemin ücretsiz ayırmasını kullanabilirsiniz. Daha büyük iş yükleri için kullandıkça öde fiyatlandırması için bir beceri kümesine Azure AI Services çok bölgeli bir kaynak ekleyin.
Arama hizmeti URL'si ve API anahtarı kopyalama
Bu öğretici için Azure AI Search bağlantıları için bir uç nokta ve bir API anahtarı gerekir. Bu değerleri Azure portalından alabilirsiniz.
Azure portalında oturum açın, arama hizmetine Genel Bakış sayfasına gidin ve URL'yi kopyalayın. Örnek uç nokta
https://mydemo.search.windows.netşeklinde görünebilir.Ayarlar> Keys altında bir yönetici anahtarı kopyalayın. Yönetici anahtarları nesneleri eklemek, değiştirmek ve silmek için kullanılır. Değiştirilebilir iki yönetici anahtarı vardır. İkisini de kopyalayın.
REST dosyanızı ayarlama
Visual Studio Code'ı başlatın ve skillset-tutorial.rest dosyasını açın. REST istemcisiyle ilgili yardıma ihtiyacınız varsa bkz . Hızlı Başlangıç: REST kullanarak metin araması.
Değişkenler için değerler sağlayın: arama hizmeti uç noktası, arama hizmeti yöneticisi API anahtarı, dizin adı, Azure Depolama hesabınıza bağlantı dizesi ve blob kapsayıcı adı.
İşlem hattını oluşturma
Yapay zeka zenginleştirmesi dizin oluşturucu temellidir. İzlenecek kılavuzun bu bölümü dört nesne oluşturur: veri kaynağı, dizin tanımı, beceri kümesi, dizin oluşturucu.
1. Adım: Veri kaynağı oluşturma
bağlantı dizesi örnek veri dosyalarını içeren Blob kapsayıcısına ayarlamak için Veri Kaynağı Oluştur'u çağırın.
### Create a data source
POST {{baseUrl}}/datasources?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-ds",
"description": null,
"type": "azureblob",
"subtype": null,
"credentials": {
"connectionString": "{{storageConnectionString}}"
},
"container": {
"name": "{{blobContainer}}",
"query": null
},
"dataChangeDetectionPolicy": null,
"dataDeletionDetectionPolicy": null
}
2. Adım: Beceri kümesi oluşturma
İçeriğinize hangi zenginleştirme adımlarının uygulanacağını belirtmek için Beceri Kümesi Oluştur'u arayın. Bağımlılık olmadığı sürece beceriler paralel olarak yürütülür.
### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-ss",
"description": "Apply OCR, detect language, extract entities, and extract key-phrases.",
"cognitiveServices": null,
"skills":
[
{
"@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
"context": "/document/normalized_images/*",
"defaultLanguageCode": "en",
"detectOrientation": true,
"inputs": [
{
"name": "image",
"source": "/document/normalized_images/*"
}
],
"outputs": [
{
"name": "text"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.MergeSkill",
"description": "Create merged_text, which includes all the textual representation of each image inserted at the right location in the content field. This is useful for PDF and other file formats that supported embedded images.",
"context": "/document",
"insertPreTag": " ",
"insertPostTag": " ",
"inputs": [
{
"name":"text",
"source": "/document/content"
},
{
"name": "itemsToInsert",
"source": "/document/normalized_images/*/text"
},
{
"name":"offsets",
"source": "/document/normalized_images/*/contentOffset"
}
],
"outputs": [
{
"name": "mergedText",
"targetName" : "merged_text"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.SplitSkill",
"textSplitMode": "pages",
"maximumPageLength": 4000,
"defaultLanguageCode": "en",
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "textItems",
"targetName": "pages"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
"description": "If you have multilingual content, adding a language code is useful for filtering",
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "languageName",
"targetName": "language"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
"context": "/document/pages/*",
"inputs": [
{
"name": "text",
"source": "/document/pages/*"
}
],
"outputs": [
{
"name": "keyPhrases",
"targetName": "keyPhrases"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Organization"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "organizations",
"targetName": "organizations"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Location"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "locations",
"targetName": "locations"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Person"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "persons",
"targetName": "persons"
}
]
}
]
}
Önemli noktalar:
İsteğin gövdesi aşağıdaki yerleşik becerileri belirtir:
Beceri Açıklama Optik Karakter Tanıma Görüntü dosyalarındaki metinleri ve sayıları tanır. Metin Birleştirme Önceden ayrılmış içeriği yeniden birleştirilen "birleştirilmiş içerik" oluşturur; ekli görüntüleri olan belgeler (PDF, DOCX vb.) için kullanışlıdır. Resimler ve metinler, belgenin çatlama aşamasında ayrılır. Birleştirme becerisi, zenginleştirme sırasında oluşturulan tanınan metinleri, resim başlık veya etiketleri belgedeki görüntünün ayıklandığı konuma ekleyerek bunları yeniden birleştirir. Beceri kümesindeki birleştirilmiş içerikle çalışırken, bu düğüm OCR veya görüntü analizinden hiç geçmemiş yalnızca metin içeren belgeler de dahil olmak üzere belgedeki tüm metinleri kapsar. Dil Algılama Dili algılar ve bir dil adı veya kodun çıkışını alır. Çok dilli veri kümelerinde, dil alanı filtreler için yararlı olabilir. Varlık Tanıma Birleştirilmiş içerikten kişilerin, kuruluşların ve konumların adlarını ayıklar. Metin Bölme Anahtar tümcecik ayıklama becerisini çağırmadan önce büyük birleştirilmiş içeriği daha küçük parçalara ayırır. Anahtar tümcecik ayıklama, 50.000 veya daha az karakterden oluşan girişi kabul eder. Bu sınıra uymak için örnek dosyaların birkaç tanesinin bölünmesi gerekir. Anahtar İfade Ayıklama En üstteki anahtar ifadeleri çıkarır. Her beceri, belge içeriğinde yürütülür. İşleme sırasında Azure AI Search, farklı dosya biçimlerindeki içeriği okumak için her belgeyi kırıyor. Kaynak dosyadan gelen, bulunan metin, oluşturulan
contentalanına her belge için birer birer yerleştirilir. Bu nedenle, giriş olur"/document/content".Anahtar ifade ayıklama için, büyük dosyaları sayfalara bölmek için metin bölücü becerisini kullandığımızdan, anahtar ifade ayıklama becerisinin bağlamı yerine (belgedeki her sayfa için)
"/document/content"şeklindedir"document/pages/*".
Not
Çıktılar bir dizine eşlenebilir, aşağı akış becerisine yönelik giriş olarak kullanılır veya dil kodunda olduğu gibi her iki şekilde de kullanılabilir. Dizinde bir dil kodu, filtreleme için yararlıdır. Beceri kümesi temelleri hakkında daha fazla bilgi için bkz. Beceri kümesini tanımlama.
3. Adım: Dizin oluşturma
Azure AI Search'te ters dizinleri ve diğer yapıları oluşturmak için kullanılan şemayı sağlamak için Dizin Oluştur'u çağırın.
Bir dizinin en büyük bileşeni, veri türü ve özniteliklerinin Azure AI Search'teki içeriği ve davranışı belirlediği alanlar koleksiyonudur. Yeni oluşturulan çıkışınız için alanlarınızın olduğundan emin olun.
### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-idx",
"defaultScoringProfile": "",
"fields": [
{
"name": "content",
"type": "Edm.String",
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
},
{
"name": "text",
"type": "Collection(Edm.String)",
"facetable": false,
"filterable": true,
"searchable": true,
"sortable": false
},
{
"name": "language",
"type": "Edm.String",
"searchable": false,
"sortable": true,
"filterable": true,
"facetable": false
},
{
"name": "keyPhrases",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "organizations",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "persons",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "locations",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "metadata_storage_path",
"type": "Edm.String",
"key": true,
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
},
{
"name": "metadata_storage_name",
"type": "Edm.String",
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
}
]
}
4. Adım: Dizin oluşturucu oluşturma ve çalıştırma
İşlem hattını yönlendirmek için Create Indexer'ı çağırın. Şimdiye kadar oluşturduğunuz üç bileşen (veri kaynağı, beceri kümesi, dizin) bir dizin oluşturucuya girişlerdir. Azure AI Search'te dizin oluşturucunun oluşturulması, işlem hattının tamamını harekete geçirir.
Bu adımın tamamlanması birkaç dakika sürebilir. Veri kümesi küçük olsa da, analiz becerileri bilgi işlem açısından yoğundur.
### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-idxr",
"description": "",
"dataSourceName" : "cog-search-demo-ds",
"targetIndexName" : "cog-search-demo-idx",
"skillsetName" : "cog-search-demo-ss",
"fieldMappings" : [
{
"sourceFieldName" : "metadata_storage_path",
"targetFieldName" : "metadata_storage_path",
"mappingFunction" : { "name" : "base64Encode" }
},
{
"sourceFieldName": "metadata_storage_name",
"targetFieldName": "metadata_storage_name"
}
],
"outputFieldMappings" :
[
{
"sourceFieldName": "/document/merged_text",
"targetFieldName": "content"
},
{
"sourceFieldName" : "/document/normalized_images/*/text",
"targetFieldName" : "text"
},
{
"sourceFieldName" : "/document/organizations",
"targetFieldName" : "organizations"
},
{
"sourceFieldName": "/document/language",
"targetFieldName": "language"
},
{
"sourceFieldName" : "/document/persons",
"targetFieldName" : "persons"
},
{
"sourceFieldName" : "/document/locations",
"targetFieldName" : "locations"
},
{
"sourceFieldName" : "/document/pages/*/keyPhrases/*",
"targetFieldName" : "keyPhrases"
}
],
"parameters":
{
"batchSize": 1,
"maxFailedItems":-1,
"maxFailedItemsPerBatch":-1,
"configuration":
{
"dataToExtract": "contentAndMetadata",
"imageAction": "generateNormalizedImages"
}
}
}
Önemli noktalar:
İsteğin gövdesinde önceki nesnelere başvurular, görüntü işleme için gereken yapılandırma özellikleri ve iki tür alan eşlemesi bulunur.
"fieldMappings"beceri kümesinden önce işlenir ve veri kaynağından dizindeki hedef alanlara içerik gönderilir. Var olan ve değiştirilmemiş içeriği dizine göndermek için alan eşlemelerini kullanırsınız. Alan adları ve türleri her iki uçta da aynıysa eşleme gerekmez."outputFieldMappings"beceri kümesi yürütmeden sonra beceriler tarafından oluşturulan alanlar içindir. belgeyi kırana veya zenginleştirme bunları oluşturanasourceFieldNamekadar içindeoutputFieldMappingsbaşvuruları yoktur.targetFieldName, dizin şemasında tanımlanan dizindeki bir alandır."maxFailedItems"parametresi -1 olarak ayarlanır ve dizin oluşturma altyapısına veri içeri aktarma sırasında hataları yoksaymasını bildirir. Tanıtım veri kaynağında çok az belge bulunduğundan bu kabul edilebilir bir durumdur. Daha büyük bir veri kaynağı için değeri, 0’dan daha büyük bir değere ayarlarsınız.deyimi,
"dataToExtract":"contentAndMetadata"dizin oluşturucuya blobun içerik özelliğinden ve her nesnenin meta verilerinden değerleri otomatik olarak ayıklamasını söyler.parametresi,
imageActiondizin oluşturucuya veri kaynağında bulunan görüntülerden metin ayıklamasını söyler. Yapılandırma"imageAction":"generateNormalizedImages", OCR Becerisi ve Metin Birleştirme Becerisi ile birlikte dizin oluşturucuya görüntülerden metin ayıklamasını (örneğin, trafik Durdurma işaretinden "dur" sözcüğü) ve içerik alanının bir parçası olarak eklemesini söyler. Bu davranış hem eklenmiş görüntüler (PDF içindeki bir görüntüyü düşünün) hem de jpg dosyası gibi tek başına görüntü dosyaları için geçerlidir.
Not
Bir dizin oluşturucu oluşturulduğunda, işlem hattı çağrılır. Verilere ulaşılırken, eşleme girişleri ve çıktıları veya işlemlerin sırası ile ilgili sorun olursa bunlar bu aşamada görüntülenir. İşlem hattını, kod veya betik değişiklikleriyle yeniden çalıştırmak için önce nesneleri bırakmanız gerekebilir. Daha fazla bilgi için bkz. Sıfırlama ve yeniden çalıştırma.
Dizin oluşturmayı izleme
Dizin oluşturucu oluşturma isteğini gönderdiğiniz anda dizin oluşturma ve zenginleştirme başlar. Beceri kümesi karmaşıklığı ve işlemlerine bağlı olarak dizin oluşturma işlemi biraz zaman alabilir.
Dizin oluşturucunun hala çalışıp çalışmadığını öğrenmek için Dizin Oluşturucu Durumunu Al'ı çağırarak dizin oluşturucunun durumunu denetleyin.
### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/cog-search-demo-idxr/status?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
Önemli noktalar:
Uyarılar bazı senaryolarda yaygındır ve her zaman bir sorunu göstermez. Örneğin, bir blob kapsayıcısı görüntü dosyaları içeriyorsa ve işlem hattı görüntüleri işlemezse, görüntülerin işlenmediğini belirten bir uyarı alırsınız.
Bu örnekte metin içermeyen bir PNG dosyası vardır. Metin tabanlı becerilerin beşi de (dil algılama, konumların varlık tanıması, kuruluşlar, kişiler ve anahtar ifade ayıklama) bu dosyada yürütülememektedir. Sonuçta elde edilen bildirim yürütme geçmişinde gösterilir.
Sonuçları denetleme
Yapay zeka tarafından oluşturulan içerik içeren bir dizin oluşturduğunuza göre sonuçları görmek için bazı sorgular çalıştırmak için Arama Belgeleri'ni çağırın.
### Query the index\
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"search": "*",
"select": "metadata_storage_name,language,organizations",
"count": true
}
Filtreler, sonuçları ilgilendiğiniz öğelere daraltmanıza yardımcı olabilir:
### Filter by organization
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"search": "*",
"filter": "organizations/any(organizations: organizations eq 'Microsoft')",
"select": "metadata_storage_name,organizations",
"count": true
}
Bu sorgular, Azure AI Search tarafından oluşturulan yeni alanlarda sorgu söz dizimi ve filtrelerle çalışma yollarından birkaçını gösterir. Daha fazla sorgu örneği için bkz . Belge Arama REST API'sindeki Örnekler, Basit söz dizimi sorgu örnekleri ve Tam Lucene sorgu örnekleri.
Sıfırlama ve yeniden çalıştırma
Geliştirmenin ilk aşamalarında, tasarım üzerinde yineleme yaygındır. Sıfırlama ve yeniden çalıştırma yinelemeye yardımcı olur.
Paketler
Bu öğreticide, yapay zeka zenginleştirme işlem hattı oluşturmak için REST API'lerini kullanmaya yönelik temel adımlar gösterilmektedir: veri kaynağı, beceri kümesi, dizin ve dizin oluşturucu.
Girişler ve çıkışlar aracılığıyla becerileri zincirlemenin mekaniğine ilişkin beceri kümesi tanımıyla birlikte yerleşik beceriler tanıtıldı. Ayrıca dizin oluşturucu tanımında zenginleştirilmiş değerleri işlem hattından Azure AI Arama hizmeti aranabilir bir dizine yönlendirmek için gerekli olduğunu öğrendinizoutputFieldMappings.
Son olarak, daha fazla yineleme için sonuçların nasıl test edileceğini ve sistemin nasıl sıfırlanacağını öğrendiniz. Dizine karşı sorgular düzenlendiğinde, zenginleştirilmiş dizin oluşturma işlem hattı tarafından oluşturulan çıktının döndürüldüğünü öğrendiniz.
Kaynakları temizleme
Kendi aboneliğinizde çalışırken, bir projenin sonunda artık ihtiyacınız olmayan kaynakları kaldırmak iyi bir fikirdir. Çalışır durumda bırakılan kaynaklar maliyetlerin artmasına neden olabilir. Kaynakları teker teker silebilir veya tüm kaynak grubunu silerek kaynak kümesinin tamamını kaldırabilirsiniz.
Sol gezinti bölmesindeki Tüm kaynaklar veya Kaynak grupları bağlantısını kullanarak kaynakları portalda bulabilir ve yönetebilirsiniz.
Sonraki adımlar
Artık yapay zeka zenginleştirme işlem hattındaki tüm nesneleri bildiğinize göre, beceri kümesi tanımlarına ve bireysel becerilere daha yakından bakın.