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

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

技能组是用于 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-version=2020-06-30。 有关更多 版本,请参阅 API 版本。

请求标头

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

字段 说明
Content-Type 必需。 将其设置为 application/json
api-key 必需。 api-key 用于对搜索服务的请求进行身份验证。 它是一个字符串值,对于服务是唯一的。 创建请求必须包含 api-key 设置为管理密钥 (而不是查询密钥) 的标头。 可以在Azure 门户的搜索服务仪表板中找到 API 密钥

请求正文

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

以下 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) { }
} 

请求包含以下属性:

属性 说明
name 必需。 技能组的名称。 名称必须为小写,以字母或数字开头,没有斜杠或点,并且少于 128 个字符。 以字母或数字开头的名称后,名称的其余部分可以包含任何字母、数字和短划线,只要短划线不是连续的。
技能 技能数组。 每个技能都有一个 odata.type、名称、上下文以及输入和输出参数。 数组可以包括内置技能和自定义技能。 至少需要一项技能。 如果使用知识存储,请包括 整形程序技能 ,除非在投影中定义数据形状。
cognitiveServices 对于每个索引器每天对超过 20 个文档调用认知服务 API的可计费技能,需要一个一元密钥。 对于与搜索服务位于同一区域中的资源,该密钥必须为 。 有关详细信息,请参阅 附加认知服务资源

如果技能组仅包含自定义技能、实用工具技能 (条件技能、整形程序技能、文本合并、文本拆分) 或 文档提取技能,则可以省略密钥和此部分。

如果使用 自定义实体查找 技能,请包括此部分和一个密钥,以启用每个索引器每天超过 20 个事务的事务。
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 密钥保管库) 的访问权限的 Azure Active Directory 应用程序 ID,以及applicationSecret (指定 Azure AD 应用程序) 的身份验证密钥。 下一部分中的示例演示了语法。

响应

对于成功的请求,应看到状态代码“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 存储 (。 投影通常需要上游 整形程序技能 ,该技能从扩充树收集节点作为输入,输出可以传递给投影的单个形状。 整形器通常是要处理的最后一个技能。

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

另请参阅