Beceri Kümesi Oluşturma (Azure AI Arama REST API'si)

Beceri kümesi, Azure Depolama'da dış bilgi deposu oluşturmaya yönelik isteğe bağlı belirtimlerle yapay zeka zenginleştirmesi için kullanılan bilişsel beceriler koleksiyonudur. Beceriler doğal dil işlemeyi ve varlık tanıma, anahtar ifade ayıklama, metni mantıksal sayfalara bölme gibi diğer dönüştürmeleri çağırır.

Beceri kümesi bir dizin oluşturucuya eklenir. Beceri kümesini kullanmak için bir dizin oluşturucuda buna başvurun ve ardından dizin oluşturucuyu çalıştırarak verileri içeri aktarın, dönüştürmeleri ve zenginleştirmeyi çağırın ve çıkış alanlarını bir dizine eşleyin. Beceri kümesi üst düzey kaynaktır, ancak yalnızca dizin oluşturucu işlemesinde çalışır. Üst düzey bir kaynak olarak, beceri kümesini bir kez tasarlayabilir ve birden çok dizin oluşturucuda buna başvurabilirsiniz.

İstekte POST veya PUT kullanabilirsiniz. her ikisinde de, istek gövdesindeki JSON belgesi nesne tanımını sağlar.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
  Content-Type: application/json  
  api-key: [admin key]  

Tüm hizmet istekleri için HTTPS gereklidir. Beceri kümesi yoksa oluşturulur. Zaten varsa, yeni tanıma güncelleştirilir.

Not

Beceri kümeleri yapay zeka zenginleştirmesinin temelini oluşturur. Sınırlı işlem için ücretsiz bir kaynak kullanılabilir, ancak daha büyük veya daha sık iş yükleri için faturalanabilir bir Bilişsel Hizmetler kaynağı gerekir.

URI Parametreleri

Parametre Açıklama
hizmet adı Gereklidir. Bunu arama hizmetinizin benzersiz, kullanıcı tanımlı adı olarak ayarlayın.
beceri kümesi adı PUT kullanılıyorsa URI'de gereklidir. Ad küçük harf olmalı, harf veya sayı ile başlamalıdır, eğik çizgi veya nokta içermemelidir ve 128 karakterden az olmalıdır. Ad bir harf veya sayı ile başlamalıdır, ancak tireler ardışık kalmadıkları sürece adın kalan kısmı herhangi bir harf, sayı ve kısa çizgi içerebilir.
api-sürümü Gereklidir. Desteklenen sürümlerin listesi için bkz. API sürümleri.

İstek Üst Bilgileri

Aşağıdaki tabloda gerekli ve isteğe bağlı istek üst bilgileri açıklanmaktadır.

Alanlar Description
İçerik Türü Gereklidir. Bunu olarak ayarlayın application/json
api-key İsteğe bağlı olarak Azure rollerini kullanıyorsanız ve istekte taşıyıcı belirteci sağlanıyorsa bir anahtar gereklidir. Oluşturma istekleri, yönetici anahtarınıza ayarlanmış bir api-key üst bilgi içermelidir (sorgu anahtarının aksine). Ayrıntılar için bkz. Anahtar kimlik doğrulamasını kullanarak Azure AI Search'e bağlanma .

İstek Gövdesi

İsteğin gövdesi beceri kümesi tanımını içerir. Beceriler tek başınadır veya bir dönüşümün çıkışının diğerine giriş olduğu giriş-çıkış ilişkilendirmeleri aracılığıyla zincirlenir. Beceri kümesinin en az bir becerisi olmalıdır. Maksimum beceri sayısı için teorik bir sınır yoktur, ancak üç ile beş arası yaygın bir yapılandırmadır.

Aşağıdaki JSON, tanımın ana bölümlerinin üst düzey bir gösterimidir.

{   
  "name" : (optional on PUT; required on POST) "Name of the skillset",  
  "description" : (optional) "Anything you want, or nothing at all",   
  "skills" : (required) ["An array of skills. Each skill has an odata.type, name, input and output parameters"],
  "cognitiveServices": 
      {
        "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
        "description": "Optional. Anything you want, or null",
        "key": "<YOUR-COGNITIVE-SERVICES-ALL-IN-ONE-KEY>"
      },
  "knowledgeStore": (optional) { ... },
  "encryptionKey": (optional) { }
} 

İstek aşağıdaki özellikleri içerir:

Özellik Açıklama
name Gereklidir. Beceri kümesinin adı. Ad küçük harf olmalı, harf veya sayı ile başlamalıdır, eğik çizgi veya nokta içermemelidir ve 128 karakterden az olmalıdır. Ad bir harf veya sayı ile başlamalıdır, ancak tireler ardışık kalmadıkları sürece adın kalan kısmı herhangi bir harf, sayı ve kısa çizgi içerebilir.
Beceri Bir dizi beceri. Her becerinin odata.type, name, context ve giriş ve çıkış parametreleri vardır. Dizi yerleşik becerileri ve özel becerileri içerebilir. En az bir beceri gereklidir. Bilgi deposu kullanıyorsanız, projeksiyonda veri şeklini tanımlamadığınız sürece bir Şekillendirici becerisi ekleyin.
cognitiveServices Dizin oluşturucu başına günde 20'den fazla belgede Bilişsel Hizmetler API'si çağıran faturalanabilir beceriler için hepsi bir arada anahtar gereklidir. Anahtar, arama hizmetiyle aynı bölgedeki bir kaynak için olmalıdır. Daha fazla bilgi için bkz. Bilişsel Hizmetler kaynağı ekleme. Özel Varlık Arama becerisini kullanıyorsanız bu bölümü ve dizin oluşturucu başına günlük 20'nin ötesinde işlemleri etkinleştirmek için bir anahtar ekleyin.

Bilişsel Hizmetler Anahtarına ihtiyacınız yoktur ve beceri kümeniz yalnızca özel beceriler, yardımcı beceriler (Koşullu, Şekillendirici, Metin Birleştirme, Metin Bölme) veya Belge Ayıklama becerisinden oluşuyorsa bölümü dışlayabilirsinizcognitiveServices. Ekli bilişsel hizmet kaynağınızı bir beceri kümesinden kaldırmak istiyorsanız ("varsayılan" sınırları kullanmaya dönmek için) olarak #Microsoft.Azure.Search.DefaultCognitiveServicesbelirtin@odata.type. Daha fazla bilgi için bu örneğe bakın.
knowledgeStore İsteğe bağlı. Azure Depolama'ya zenginleştirme çıkışı hedefi. Azure Depolama hesabına ve projeksiyonlarına bağlantı dizesi gerektirir.

storageConnectionString (gerekli) Şu biçimde bir dize: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net".

projections(gerekli) Belirtilen veya null olan , objects, files' yi içeren tablesbir projeksiyon nesneleri dizisi.

tables
Azure Tablo Depolama'da bir veya daha fazla tablo oluşturur ve her belgedeki içeriği tablodaki satırlar olarak yansıtmaktadır. Her tablo aşağıdaki üç özelliğe sahip olabilir:
  • name (gerekli) Azure Tablo Depolama'da oluşturulacak veya kullanılacak tabloyu belirler.
  • generatedKeyName (isteğe bağlı), belgeyi benzersiz olarak tanımlayan bir sütunun adıdır. Zenginleştirme sırasında bu sütunun değerleri oluşturulur. Bunu atlarsanız, arama hizmeti tablo adını temel alan bir varsayılan anahtar sütunu oluşturur.
  • source (gerekli), projeksiyonun şeklini sağlayan zenginleştirme ağacı düğümünün yoludur. Bu genellikle bir Shaper becerisinin çıkışıdır. Yollar, kök zenginleştirilmiş belgeyi temsil eden ile /document/başlar ve daha sonra zenginleştirme ağacındaki , veya veya /document/content/başka bir düğüme genişletilir/document/<shaper-output>/. Örnekler: /document/countries/* (tüm ülkeler) veya /document/countries/*/states/* (tüm ülkelerdeki tüm eyaletler).

objects
Belgeleri Azure Blob Depolama blob olarak projeler. Her nesnenin iki gerekli özelliği vardır:
  • storageContainer, Azure Blob Depolama içinde oluşturulacak veya kullanılacak kapsayıcının adıdır.
  • source projeksiyonun şeklini sağlayan zenginleştirme ağacı düğümünün yoludur. Geçerli bir JSON olmalıdır. Düğüm, geçerli bir JSON ya da bir Shaper becerisinin çıkışını yayan bir beceriden bir JSON nesnesi sağlamalıdır.

files
Her dosya girdisi Blob Depolama'da ikili görüntülerin depolanmasını tanımlar. Dosya projeksiyonlarının iki gerekli özelliği vardır:
  • storageContainer, Azure Blob Depolama içinde oluşturulacak veya kullanılacak kapsayıcının adıdır.
  • source projeksiyonun kökü olan zenginleştirme ağacı düğümünün yoludur. Bu özellik için geçerli bir değer, "/document/normalized_images/*" Blob Depolama'dan alınan görüntüler içindir.
encryptionKey İsteğe bağlı. Azure Key Vault yönetilen, bekleyen bir beceri kümesi tanımını kendi anahtarlarınızla şifrelemek için kullanılır. 2019-01-01 veya sonrasında oluşturulan faturalanabilir arama hizmetleri için kullanılabilir.

Bir encryptionKey bölüm kullanıcı tanımlı keyVaultKeyName (gerekli), sistem tarafından oluşturulan keyVaultKeyVersion (gerekli) ve anahtarı sağlayan bir keyVaultUri (DNS adı olarak da adlandırılır) içerir. Örnek bir URI"https://my-keyvault-name.vault.azure.net".

İsteğe bağlı olarak, yönetilen bir sistem kimliği kullanmadığınızda belirtebilirsiniz accessCredentials . accessCredentials özellikleri şunlardır applicationId (belirtilen Azure Key Vault erişim izinleri verilmiş Microsoft Entra ID uygulama kimliği) ve applicationSecret (kayıtlı uygulamanın kimlik doğrulama anahtarı). Sonraki bölümdeki bir örnekte söz dizimi gösterilmektedir.

Yanıt

Başarılı bir istek için "201 Oluşturuldu" durum kodunu görmeniz gerekir.

Varsayılan olarak, yanıt gövdesi oluşturulan beceri kümesi tanımının JSON'unu içerir. Ancak, istek üst bilgisi olarak return=minimalayarlanırsa Prefer yanıt gövdesi boştur ve başarı durum kodu "201 Oluşturuldu" yerine "204 İçerik Yok" olur. Beceri kümesini oluşturmak için PUT veya POST kullanılıp kullanılmadığına bakılmaksızın bu durum geçerlidir.

Örnekler

Örnek: Müşteri incelemelerinde iş varlıklarını ve yaklaşımı tanıyan beceri kümesi

Bu beceri kümesi, iki farklı dönüşüm olarak bağımsız olarak işlenmek /document/content üzere iki beceriyi zaman uyumsuz olarak kullanır. Beceriler Varlık Tanıma ve Yaklaşım'dır. Zenginleştirme ağacında, /document/content dış veri kaynağından içeriği (veya müşteri incelemelerini) sağlar.

{
  "name": "reviews-ss",
  "description": 
  "Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
  "skills":
  [
    {
      "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
      "context": "/document/content",
      "categories": [ "Organization" ],
      "defaultLanguageCode": "en",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "organizations",
          "targetName": "companyName"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
      "inputs": [
           {
              "name": "text",
              "source": "/document/content"
           },
          {
               "name": "languageCode",
               "source": "/document/languageCode"
           }
        ],
      "outputs": [
        {
            "name": "sentiment",
            "targetName": "reviewSentiment"
        },
        {
            "name": "confidenceScores",
            "targetName": "sentimentScore"
        }
      ]
    }
  ],
  "cognitiveServices": 
    {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "description": "mycogsvcs resource in West US 2",
    "key": "<your cognitive services all-in-one key goes here>"
    },
  "knowledgeStore": { },
  "encryptionKey": { }
}

Örnek: Bilgi deposu

Beceri kümesi isteğe bağlı olarak Azure Depolama'daki bilgi deposuna çıkış gönderebilir. Bir Azure Depolama hesabına bağlantı dizesi ve zenginleştirilmiş içeriğin tabloya mı yoksa blob depolamaya mı (nesne veya dosya olarak) eklendiğini belirleyen projeksiyonlar gerektirir. Projeksiyonlar genellikle giriş olarak bir zenginleştirme ağacından düğüm toplayarak projeksiyona geçirilebilecek tek bir şeklin çıkışını veren bir yukarı akış Şekillendirici becerisi gerektirir. Şekillendirici genellikle işlenecek son beceridir.

{
  "name": "reviews-ss",
  "description": 
  "Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
  "skills":
  [
    { ... },
    { ... },
    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "context": "/document/content",
      "inputs": [
        {
            "name": "Company",
            "source": "/document/content/companyName"
        },
        {
            "name": "Sentiment_Score",
            "source": "/document/content/sentimentScore"
        },
        {
            "name": "Sentiment_Label",
            "source": "/document/content/reviewSentiment"
        }
      ],
      "outputs": [
        {
          "name": "output",
          "targetName": "shapeCustomerReviews"
        }
      ]
    }
  ],
  "cognitiveServices": 
    {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "description": "mycogsvcs resource in West US 2",
    "key": "<your cognitive services all-in-one key goes here>"
    },
  "knowledgeStore": { 
      "storageConnectionString": "<your storage account connection string>", 
      "projections": [ 
          { 
            "tables": [ 
                { "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
                . . .
            ], 
            "objects": [ ], 
            "files": [ ]  
          }
      ]     
  } 
  "encryptionKey": { }
}

Örnek: Şifreleme anahtarları

Şifreleme anahtarları, hassas içeriğin ek şifrelemesi için kullanılan müşteri tarafından yönetilen anahtarlardır. Bu örnekte, bir beceri kümesinde müşteri tarafından yönetilen şifrelemeyi nasıl belirteceğiniz gösterilmektedir.

{
    "name": "reviews-ss",
    "description": "A brief description of the skillset",
    "skills":  [ omitted for brevity ],
    "cognitiveServices": { omitted for brevity },
    "knowledgeStore":  { omitted for brevity  },
    "encryptionKey": (optional) { 
        "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
        "keyVaultKeyVersion": "Version of the Azure Key Vault key",
        "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
        "accessCredentials": (optional, only if not using managed system identity) {
            "applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
            "applicationSecret": "Authentication key of the specified Azure AD application)"}
    }
}

Ayrıca bkz.