你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

(Azure AI 搜索 REST API) 创建技能组

项目
02/28/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 参数

参数	说明
服务名称	必需。将其设置为搜索服务的唯一用户定义名称。
技能组名称	如果使用 PUT，则为 URI 上的必需项。名称必须为小写，以字母或数字开头，没有斜杠或点，并且少于 128 个字符。名称必须以字母或数字开头，但名称的其余部分可以包含任何字母、数字和短划线，只要短划线不是连续的。
api-version	必需。有关支持的版本列表，请参阅 API 版本。

请求标头

下表介绍必需和可选的请求标头。

字段	说明
Content-Type	必需。将其设置为 `application/json`
api-key	如果使用的是 Azure 角色，并且请求中提供了持有者令牌，则为可选，否则需要密钥。创建请求必须包含 `api-key` 设置为管理密钥 (而不是查询密钥) 的标头。有关详细信息，请参阅使用密钥身份验证连接到 Azure AI 搜索。

请求正文

请求正文包含技能组定义。技能要么独立，要么通过输入-输出关联链接在一起，其中一个转换的输出成为另一个转换的输入。技能组合必须具有至少一种技能。最大技能数在理论上没有限制，但三到五个是一种常见配置。

以下 JSON 是定义main部分的高级表示形式。

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

请求包含以下属性：

属性	说明
name	必需。技能组的名称。名称必须为小写，以字母或数字开头，没有斜杠或点，并且少于 128 个字符。名称必须以字母或数字开头，但名称的其余部分可以包含任何字母、数字和短划线，只要短划线不是连续的。
技能	技能数组。每个技能都有一个 odata.type、名称、上下文以及输入和输出参数。数组可以包括内置技能和自定义技能。至少需要一项技能。如果使用知识存储，请包括整形程序技能，除非在投影中定义数据形状。
cognitiveServices	对于每个索引器每天对超过 20 个文档调用认知服务 API的可计费技能，需要一个一元密钥。对于与搜索服务位于同一区域中的资源，该密钥必须为。有关详细信息，请参阅附加认知服务资源。如果使用自定义实体查找技能，请包含此部分和一个密钥，以启用每个索引器每天超过 20 个事务的事务。不需要认知服务密钥，因此如果技能集仅包含自定义技能、实用工具技能 (条件技能、整形程序技能、文本合并、文本拆分) 技能或文档提取技能，则可以排除`cognitiveServices`部分。如果要从技能组中删除附加的认知服务资源， (还原使用“默认”限制) 指定`@odata.type`为 `#Microsoft.Azure.Search.DefaultCognitiveServices`，请参阅此示例了解详细信息。
knowledgeStore	可选。将扩充输出到 Azure 存储的目标。需要对 Azure 存储帐户和投影进行连接字符串。 `storageConnectionString` 需要 () 采用以下格式的字符串： `"DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net"`。 `projections` (必需) 由指定或 null 组成的`tablesobjectsfiles`投影对象的数组。 `tables` 在 Azure 表存储中创建一个或多个表，将每个文档中的内容投影为表中的行。每个表可以具有以下三个属性： `name` (必需) 确定在 Azure 表存储中创建或使用的表。 `generatedKeyName` (可选) 是唯一标识文档的列的名称。扩充期间将生成此列的值。如果省略它，搜索服务将根据表名创建默认键列。 `source` (必需的) 是扩充树中提供投影形状的节点的路径。它通常是整形程序技能的输出。路径以 `/document/`开头，表示根扩充文档，然后扩展到 `/document/<shaper-output>/`扩充树中的、或 `/document/content/`或另一个节点。示例： `/document/countries/` () 所有国家/地区，或 `/document/countries//states/` () 所有国家/地区的所有州。 `objects` 将文档投影为 Azure Blob 存储中的 blob。每个对象都有两个必需属性： `storageContainer`是在 Azure Blob 存储中创建或使用的容器的名称。 `source` 是指向提供投影形状的扩充树节点的路径。它必须是有效的 JSON。节点必须提供 JSON 对象，该对象来自发出有效 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`已被授予对指定 Azure 密钥保管库) 的访问权限 (Microsoft Entra ID 应用程序 ID，以及`applicationSecret`已注册应用程序) (身份验证密钥。下一部分中的示例演示了语法。

响应

对于成功的请求，应看到状态代码“201 Created”。

默认情况下，响应正文将包含已创建的技能组合定义的 JSON。但是，如果 Prefer 请求标头设置为 return=minimal，则响应正文为空，成功状态代码为“204 无内容”，而不是“201 已创建”。无论使用 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 存储。投影通常需要上游整形程序技能，该技能从扩充树收集节点作为输入，输出可传递给投影的单个形状。整形程序通常是要处理的最后一项技能。

{
  "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 参数

请求标头

请求正文

响应

示例

另请参阅

其他资源