在 Azure AI 搜索 中创建技能组

技能集定义了用于从包含图像或原始内容的文档中生成矢量和文本内容及其结构的操作。 示例包括分块技能、嵌入（矢量化）技能、图像语言化和其他过程，例如图像的光学字符识别（OCR），以及无差异文本的实体识别和文本翻译。 技能集在从外部数据源提取原始内容后执行，并在处理 字段映射 后执行。

本文介绍如何使用 REST API 创建技能组，但同样的概念和步骤也适用于其他编程语言。

技能组定义规则包括：

• 必须在技能组集合中具有唯一的名称。 技能集是任何索引器都可以使用的顶级资源。
• 必须至少有一个技能。 三到五项技能是典型技能。 最大值为 30。
• 一个技能组可重复相同类型的技能。 例如，一个技能集可以包含多个Shaper技能。
• 技能集支持链式操作、循环操作和分支操作。

将技能集附加到索引器。 若要使用技能集，请在 索引器 中引用它，然后运行索引器以导入数据、调用技能处理并将输出发送到 索引。 技能集是一种高级资源，但它仅在索引器处理中运行。 作为高级资源，可以在多个索引器中引用它。

添加技能组定义

创建技能集时，请将其添加到搜索服务。 更新技能集时，会用请求负载中的内容完全覆盖现有技能集。 若要更新技能集，请使用 GET 检索技能集定义，对其进行修改，然后使用 PUT 对其进行更新。

从基本结构开始。 在 “创建技能集 REST API”中，以 JSON 编写请求正文。 它包含以下部分：

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[

   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"A Azure AI service resource in the same region as Azure AI Search",
      "key":"<Your-Azure-AI-AI services-Resource-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

在名称和描述之后，技能集具有四个主要属性：

• skills 数组，一个无序的技能集合。 技能可以独立存在，也可以通过输入输出关联而链接在一起，其中一个转换的输出作为另一个转换的输入。 技能可以是实用的（例如拆分文本）、转换的（基于 Azure AI 服务的 AI），也可以是你提供的自定义技能。 下一部分提供了技能数组的示例。

• cognitiveServices 用于会调用 Azure AI 服务 API 的计费技能。 如果您不使用计费技能或自定义实体查找，请删除该部分。 如果是，请附加 AI 服务资源。

• knowledgeStore（可选）指定 Azure 存储帐户及配置，以将技能组输出投影至 Azure 存储中的表格、Blob 和文件。 如果不需要，请删除此部分。 否则，指定知识存储。

• encryptionKey（可选）指定一个 Azure 密钥保管库和用于对技能组定义中的敏感内容（说明、连接字符串、密钥）进行加密的客户管理的密钥。 如果不使用客户管理的加密，请删除此属性。

添加技能

在技能组定义中，技能数组指定要执行的技能。 三到五项技能是常见的，你也可以根据需要添加任意数量的技能，但要遵守服务限制。

扩充管道的最终结果是搜索索引或知识存储中的文本内容。 因此，大多数技能要么从图像创建文本（OCR 文本、标题、标记），要么分析现有文本，以创建新信息（实体、关键短语、情绪）。 能够独立运行的技能被并行处理。 相互依赖的技能将一项技能（如关键短语）的输出指定为第二项技能（如文本翻译）的输入。 搜索服务确定技能执行的顺序和执行环境。

所有技能都有类型、上下文、输入和输出。 技能可以选择性地包含名称和说明。 以下示例显示了两个不相关的内置技能，以便可以比较基本结构。

"skills": [
    {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "name": "#1",
        "description": "This skill detects organizations in the source content",
        "context": "/document",
        "categories": [
            "Organization"
        ],
        "inputs": [
            {
                "name": "text",
                "source": "/document/content"
            }
        ],
        "outputs": [
            {
                "name": "organizations",
                "targetName": "orgs"
            }
        ]
    },
    {
        "name": "#2",
        "description": "This skill detects corporate logos in the source files",
        "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
        "context": "/document/normalized_images/*",
        "visualFeatures": [
            "brands"
        ],
        "inputs": [
            {
                "name": "image",
                "source": "/document/normalized_images/*"
            }
        ],
        "outputs": [
            {
                "name": "brands"
            }
        ]
    }
]

每项技能在其输入值和所采用的参数方面都是唯一的。 技能参考文档描述了给定技能的所有参数和属性。 尽管存在差异，但大多数技能共享一个通用集，且具有相似的模式。

设置技能上下文

每项技能都有一个上下文属性，用于确定操作发生的级别。 如果未显式设置 context 属性，则默认为 "/document"，上下文是整个文档（每个文档调用该技能一次）。

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

将 context 属性设置为以下示例之一：

上下文还决定了在扩充树中生成输出的位置。 例如，实体识别功能返回一个名为 organizations 的属性，捕获为 orgs。 如果上下文为 "/document"，则会将 organizations 节点添加为 "/document" 的子节点。 如果随后想要在下游技能中引用此节点，则路径为 "/document/orgs"。

定义输入

从扩充文档读取和写入的技能。 技能输入指定传入数据的源。 它通常是扩充文档的根节点。 对于 Blob，典型的技能输入是文档的内容属性。

有关每种技能的技能参考文档描述了它可以使用的输入。 每个输入都有一个标识特定输入的 name，以及一个指定扩充文档中数据位置的 source。 以下示例来自实体识别技能：

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]

• 技能可以有多个输入。 name 是特定输入。 对于实体识别，具体输入为“text”和“languageCode”。

• source 属性指定哪个字段或行提供要处理的内容。 对于基于文本的技能，源是提供文本的文档或行中的字段。 对于基于图像的技能，提供输入的节点是规范化图像。

  源示例	说明
  source: /document	对于表格数据集，一个文档对应于一行。
  source: /document/content	对于 Blob，源通常是 Blob 的内容属性。
  source: /document/some-named-field	对于基于文本的技能（如实体识别或关键短语提取）来说，源应是诸如“description”或“summary”之类的字段，其中包含要分析的足够文本。
  source: /document/normalized_images/*	对于图像内容，源是在文档破解期间已规范化的图像。

如果技能对数组进行循环访问，则上下文和输入源都应将 /* 包含在正确的位置。 有关完整语法的详细信息，请参阅 技能上下文和输入注释语言。

定义输出

每个技能旨在发出特定类型的输出，技能集按名称引用这些输出。 技能输出具有 name 和可选的 targetName。

每个技能的 技能参考文档 描述了它可以生成的输出。 以下示例来自实体识别技能：

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]

• 技能可以有多个输出。 name 属性标识特定输出。 例如，对于实体识别，输出可以是人、位置、组织等。

• 该 targetName 属性指定希望此节点在扩充文档中具有的名称。 如果技能输出具有相同的名称，则此属性非常有用。 如果有多项技能返回相同的输出，请使用 targetName 在扩充节点路径中进行名称消歧。 如果未指定目标名称，则名称属性将用于这两者。

在某些情况下，需要单独引用数组的每个元素。 例如，假设你想要将 的每个元素单独传递到另一个技能。 为此，请向此路径添加星号："/document/orgs/*"。

技能输出将作为扩充树中的新节点写入扩充文档。 它可能是一个简单的值，例如情绪分数或语言代码。 它也可以是一个集合，例如组织、人员或位置的列表。 技能输出还可以是一个复杂的结构，就像整形器技能一样。 技能的输入决定了形状的构成，但输出是命名对象，可以在搜索索引、知识存储投影或其他技能中按名称进行引用。

添加自定义技能

本部分包含自定义技能的示例。 URI 指向一个 Azure 函数，该函数反过来调用你提供的模型或转换。 有关详细信息，请参阅将自定义技能添加到 Azure AI 搜索扩充管道。

尽管自定义技能执行管道外部的代码，但在技能数组中，这只是另一种技能。 与内置技能类似，它具有类型、上下文、输入和输出。 像内置技能一样，它也在扩充树中进行读取和写入。 请注意，context 字段设置为带有星号的 "/document/orgs/*"，这意味着，在 下的每个组织上都会调用扩展步骤"/document/orgs"。

输出（例如本示例中的公司说明）是针对已识别的每个组织生成的。 在下游步骤中引用节点时（例如，在关键短语提取中），请使用路径 "/document/orgs/*/companyDescription" 执行此操作。

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "This skill calls an Azure function, which in turn calls custom code",
  "uri": "https://indexer-e2e-webskill.chinacloudsites.cn/api/InvokeCode?code=<YOUR-FUNCTION-KEY>",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "<YOUR-APIM-KEY>"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

将输出发送到目标

虽然可以选择缓存技能输出以供重复使用，但它通常是暂时的，仅在技能执行正在进行时存在。

• 若要将输出发送到搜索索引中的字段，请在索引器中创建一个输出字段映射。

• 若要将输出发送到知识库，请创建投影。

• 若要将输出发送到下游技能，请在下游技能的输入源属性中通过其节点名称引用输出，例如 "/document/organization"。 有关示例，请参阅引用注释。

有关第一个技能组的技巧

• 请尝试 导入数据 向导。

  该向导自动执行几个步骤，这些步骤可能第一次具有挑战性。 它定义技能组、索引和索引器，包括字段映射和输出字段映射。 如果您正在使用知识存储，它还会在其中定义投影。 对于某些技能（例如 OCR 或图像分析），向导将添加实用工具技能，用于合并在文档破解期间分隔的图像和文本内容。

  向导运行后，可以在 Azure 门户中打开每个对象以查看其 JSON 定义。

• 尝试调试会话来触发技能包执行，通过目标文档查看技能包创建的增强文档。 可以查看和修改输入与输出设置及值。 此教程是一个很好的起点：教程：使用调试会话调试技能组。

下一步

上下文和输入源字段是扩充树中节点的路径。 下一步，请详细了解扩充树中的节点的路径语法。