(Azure AI 搜尋 REST API) 建立技能集

發行項
03/05/2024

技能集是用於 AI 擴充的認知技能集合，具有選擇性的規格，可用來在 Azure 記憶體中建立外部知識存放區。技能會叫用自然語言處理和其他轉換，例如實體辨識、關鍵片語擷取、將文字區塊化成邏輯頁面等等。

技能集會附加至索引器。若要使用技能集，請在索引器中參考它，然後執行索引器來匯入數據、叫用轉換和擴充，並將輸出字段對應至索引。技能集是高階資源，但只能在索引器處理內運作。因為是高層級的資源，所以您可以設計一次技能集，然後在多個索引子中參考。

您可以在要求上使用 POST 或 PUT。針對任一個，要求本文中的 JSON 檔會提供物件定義。

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

所有服務要求都需使用 HTTPS。如果技能集不存在，則會建立。如果已經存在，則會更新為新的定義。

注意

技能集是 AI 擴充的基礎。免費資源可用於有限的處理，但對於較大型或更頻繁的工作負載，則需要可計費的認知服務資源。

URI 參數

參數	Description
服務名稱	必要。將此設定為搜尋服務的唯一用戶定義名稱。
技能集名稱	如果使用 PUT，則為 URI 的必要專案。名稱必須是小寫，開頭為字母或數位、沒有斜線或點，且少於 128 個字元。名稱的開頭必須是字母或數位，但名稱的其餘部分可以包含任何字母、數位和破折號，只要連字元不是連續的。
api-version	必要。如需支援的版本清單，請參閱 API 版本。

要求標頭

下表說明必要及選用的要求標頭。

欄位	Description
Content-Type	必要。請設為 `application/json`
api-key	如果您使用 Azure 角色，並在要求上提供持有人令牌，則為選擇性，否則需要密鑰。建立要求必須包含 `api-key` 設定為系統管理員密鑰的標頭 (，而不是查詢密鑰) 。如需詳細資訊，請參閱使用密鑰驗證連線到 Azure AI 搜尋服務。

要求本文

要求的主體包含技能集定義。技能是獨立或透過輸入輸出關聯鏈結在一起，其中一個轉換的輸出會變成另一個轉換的輸入。一個技能集至少必須有一個技能。技能數目上限沒有理論上的限制，但三到五是常見的設定。

下列 JSON 是定義主要部分的高階表示法。

{   
  "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) { }
}

要求可包含下列屬性：

屬性	Description
NAME	必要。技能集的名稱。名稱必須是小寫，開頭為字母或數位、沒有斜線或點，且少於 128 個字元。名稱的開頭必須是字母或數位，但名稱的其餘部分可以包含任何字母、數位和破折號，只要連字元不是連續的。
skills	技能陣列。每個技能都有 odata.type、name、context 和輸入和輸出參數。數位可以包含內建技能和自定義技能。至少需要一個技能。如果您使用知識存放區，除非您在投影中定義數據圖形，否則請包含 Shaper 技能。
cognitiveServices	每個索引器每天在 20 份以上的檔上呼叫認知服務 API 的可計費技能都需要一個全機密鑰。索引鍵必須是與搜尋服務位於相同區域中的資源。如需詳細資訊，請參閱附加認知服務資源。如果您使用自定義實體查閱技能，請包含本節和索引鍵，以啟用每個索引器每日超過 20 筆交易的交易。如果您的技能集只包含自定義技能、公用程式技能 (條件式、Shaper、文字合併、文字分割) 或檔擷取技能，則您不需要認知服務密鑰，因此可以排除`cognitiveServices`區段。如果您想要從技能集移除附加的認知服務資源， (還原為使用) 指定`@odata.type`為 `#Microsoft.Azure.Search.DefaultCognitiveServices`的「預設」限制，請參閱此範例以取得詳細資訊。
knowledgeStore	選擇性。 Azure 記憶體的擴充輸出目的地。需要 azure 記憶體帳戶和投影連接字串。 `storageConnectionString` (需要) 此格式的字串： `"DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net"`。 `projections` (必要) 由指定`objectsfiles`或 Null 所組成的`tables`投影物件陣列。 `tables` 在 Azure 資料表記憶體中建立一或多個數據表，將每個文件的內容投影為數據表中的數據列。每個資料表可以有下列三個屬性： `name` (必要) 決定在 Azure 資料表記憶體中建立或使用的數據表。 `generatedKeyName` (選擇性) 是可唯一識別文件的數據行名稱。此數據行的值會在擴充期間產生。如果您省略，搜尋服務會根據數據表名稱建立預設索引鍵數據行。 `source` (必要) 是擴充樹狀結構節點的路徑，可提供投影的形狀。它通常是 Shaper 技能的輸出。路徑開頭 `/document/`為，代表根擴充檔，然後延伸至 `/document/<shaper-output>/`擴充樹狀結構內的、或 `/document/content/`另一個節點。範例： `/document/countries/` (所有國家/地區) ，或 `/document/countries//states/` (所有國家/地區的州) 。 `objects` 在 Azure Blob 儲存體中將檔投影為 Blob。每個物件都有兩個必要屬性： `storageContainer`是要在 Azure Blob 儲存體中建立或使用的容器名稱。 `source` 是擴充樹狀結構節點的路徑，可提供投影的形狀。它必須是有效的 JSON。節點必須從發出有效 JSON 或 Shaper 技能輸出的技能提供 JSON 物件。 `files` 每個檔案項目都會定義 Blob 記憶體中二進位映像的記憶體。檔案投影有兩個必要屬性： `storageContainer`是要在 Azure Blob 儲存體中建立或使用的容器名稱。 `source` 是擴充樹狀結構節點的路徑，其為投影的根目錄。此屬性的有效值適用於 `"/document/normalized_images/"` 從 Blob 記憶體來源的影像。
encryptionKey	選擇性。用來使用您自己的密鑰加密待用技能集定義，並在 Azure 金鑰保存庫中管理。適用於在 2019-01-01 之後建立的可計費搜尋服務。區 `encryptionKey` 段包含使用者定義的 `keyVaultKeyName` (必要) 、系統產生的 `keyVaultKeyVersion` (必要) ，以及 `keyVaultUri` 提供所需的密鑰 (，也稱為 DNS 名稱) 。範例 URI 可能是 “https://my-keyvault-name.vault.azure.net"。您可以選擇性地指定 `accessCredentials` 您是否未使用受控系統識別。 `accessCredentials`的屬性包括 `applicationId` (Microsoft Entra ID 應用程式識別碼，這些標識碼已授與您指定之 Azure 金鑰保存庫) 的訪問許可權，以及 `applicationSecret` (已註冊應用程式) 的驗證密鑰。下一節中的範例說明語法。

回應

若要求成功，應該會看到狀態碼 "201 Created"。

根據預設，回應本文將包含所建立技能集定義的 JSON。不過，如果 Prefer 要求標頭設定 return=minimal為，則回應本文是空的，而成功狀態代碼為 “204 No Content”，而不是 “201 Created”。無論使用 PUT 或 POST 建立技能集，都會發生此情況。

範例

範例：辨識客戶評論中商務實體和情感的技能集

此技能集會以異步方式使用兩種技能，獨立處理 /document/content 為兩個不同的轉換。技能為實體辨識和情感。在擴充樹狀結構中， /document/content 提供來自外部數據源的內容 (或客戶檢閱) 。

{
  "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": { }
}

範例：知識存放區

技能集可以選擇性地將輸出傳送至 Azure 記憶體中的知識存放區。它需要 Azure 記憶體帳戶的連接字串，並預測擴充的內容會落在數據表或 Blob 記憶體中， (做為物件或檔案) 。投影通常需要上游 Shaper 技能，以從擴充樹狀結構收集節點作為輸入，並輸出可傳遞至投影的單一圖形。塑形器通常是要處理的最後一個技能。

{
  "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": { }
}

範例：加密金鑰

加密金鑰是客戶管理的金鑰，用於額外的敏感性內容加密。此範例示範如何在技能集上指定客戶管理的加密。

{
    "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)"}
    }
}

共用方式為

(Azure AI 搜尋 REST API) 建立技能集

URI 參數

要求標頭

要求本文

回應

範例

另請參閱

其他資源