您现在访问的是微软AZURE全睃版技术文档网站,若需覝访问由世纪互蝔违蝥的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

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

技能集是一组用于AI 扩充的认知技能,包含用于在 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 而不是查询密钥) 。 可以在 搜索服务仪表板 的搜索服务仪表板中查找 API Azure 门户。

请求正文

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

以下 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 的投影对象数组,这些投影对象由 tables objects files 、、 组成。

tables
在 Azure Table 存储创建一个或多个表,将每个文档中的内容作为表中的行进行预测。 每个表可以具有以下三个属性:
  • name (确定) Azure 表存储中要创建或使用的表所需的存储。
  • generatedKeyName (可选) 是唯一标识文档的列的名称。 此列的值将在扩充期间生成。 如果省略它,搜索服务将基于表名创建默认键列。
  • source (必需的) 是扩充树的节点的路径,该节点提供 投影 的形状。 它通常是"形状器"技能的输出。 路径以 开始,表示根扩充文档,然后扩展到 、 或 扩充树中的另 /document/ /document/<shaper-output>/ /document/content/ 一个节点。 示例 /document/countries/* : (国家/地区) , (所有国家/地区 /document/countries/*/states/* /地区) 。

objects
将文档作为 Blob 项目到 Azure Blob 存储。 每个对象都有两个必需属性:
  • storageContainer是 Azure Blob 门户中要创建或使用的容器存储。
  • source 是提供投影形状的扩充树节点的路径。 它必须是有效的 JSON。 节点必须提供 JSON 对象,该对象来自发出有效 JSON 的技能或形状器技能的输出。

files
每个文件条目都定义 Blob 映像存储中的二进制存储。 文件投影具有两个必需属性:
  • storageContainer是 Azure Blob 门户中要创建或使用的容器存储。
  • source 是指向扩充树节点的路径,该树是投影的根。 此属性的有效值适用于从 Blob 数据源获取 "/document/normalized_images/*" 存储。
encryptionKey 可选。 用于使用你自己的密钥加密技能集定义,该密钥在Azure Key Vault。 适用于在 2019-01-01 或之后创建的可计费搜索服务。

部分包含用户定义的 () 、系统生成的 (所需的) ,以及提供所需的 (密钥的 ,也称为 encryptionKey keyVaultKeyName DNS keyVaultKeyVersion keyVaultUri) 。 示例 URI 可能是 https://my-keyvault-name.vault.azure.net ""。

(可选)可以指定 accessCredentials 是否未使用托管系统标识。 的属性包括 (Azure Active Directory应用程序 ID(已授予对指定 Azure Key Vault) 的访问权限)和 (应用程序Azure AD accessCredentials applicationId 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 存储中) 。 投影通常需要上游 形状 器技能,该技能从扩充树收集节点作为输入,输出可传递给投影的单个形状。 形状器通常是要处理的最后一项技能。

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

请参阅