将自定义技能添加到 Azure AI 搜索数据增强管道

AI 扩充管道可以包括你创建和发布的内置技能和自定义技能。 自定义代码在搜索服务外部运行（例如，作为Azure函数），但它接受输入并将输出发送到技能组，就像任何其他技能一样。 您的数据在模型部署的地理位置中进行处理。

自定义技能听起来可能很复杂，但实现这些技能可能很简单。 如果有提供模式匹配或分类模型的现有包，可以将从 Blob 提取的内容传递给这些模型进行处理。 由于 AI 扩充是基于Azure的，因此还应在Azure上托管模型。 常见的托管选项包括 Azure Functions 或 containers。

如果要构建自定义技能，本文介绍了用于将该技能集成到管道中的接口。 首要要求是能够以技能集可整体处理的方式接收输入并输出结果。 因此，本文的重点是扩充管道需要的输入格式和输出格式。

自定义技能的优点

通过构建自定义技能，您可以插入特定于您内容的转换。 例如，可以生成自定义分类模型，以区分商业与金融领域的合同和文档，或者，添加语音识别技能，以便深入探究音频文件获取相关内容。 有关分步示例，请参阅示例：为 AI 扩充创建自定义技能。

设置终结点和超时时间间隔

通过 自定义 Web API 技能为自定义技能指定接口。

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230-second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

URI 是函数或应用的 HTTPS 终结点。 在设置 URI 时，请确保该 URI 是安全的 (HTTPS)。 如果在Azure函数应用中托管代码，请在标头中包含 API 密钥，或作为 URI 中的 URI 参数来授权请求。

如果函数或应用使用Azure托管标识和Azure角色进行身份验证和授权，则自定义技能可以在请求中包含身份验证令牌。 以下几点说明了此方法的要求：

• 代表索引器发送请求的搜索服务必须配置为使用托管标识（系统或用户分配），以便Microsoft Entra ID能够对调用方进行身份验证。

• 必须将你的函数或应用配置为使用 Microsoft Entra ID。

• 自定义技能定义必须包括 authResourceId 属性。 此属性接收应用程序（客户端）ID，格式为 支持的格式：api://<appId>。

确保 uri 指向通过 authResourceId标识的应用程序的终结点。 不匹配的值可能会导致身份验证失败或发送到意外终结点的请求。 有关安全指南、建议的做法和验证配置的步骤，请参阅 托管标识身份验证的安全注意事项。

在默认情况下，如果在 30 秒的时间段 (PT30S) 内未返回响应，到终结点的连接就会超时。 索引管道是同步的，如果在该时间范围内未收到响应，则索引生成超时错误。 你可以通过设置 timeout 参数 (PT230S)，将该间隔增大至最大值 230 秒。

如果受 IP 访问限制保护的终结点没有响应，请暂时设置为 timeout 短值，例如 PT10S，更快地显示超时错误。 对于Azure函数应用，在“设置>>”下管理入站 IP 规则。 有关允许的 IP 地址，请参阅 配置 IP 防火墙规则以允许索引器连接。

设置 Web API 输入的格式

Web API 必须接受要处理的记录数组。 在每个记录中，提供一个属性包作为 Web API 的输入。

假设要创建一个基本的扩充器来识别合同文本中提到的第一个日期。 在此示例中，自定义技能接受单个输入 contractText。 该技能还有一个单一输出，即合同日期。 若要让丰富器更有趣，请以多部分复合类型的形式返回 contractDate。

Web API 应准备好接收一批输入记录。 数组的每个 values 成员都表示特定记录的输入。 每条记录都需要具有以下元素：

• 一个 recordId 成员，作为特定记录的唯一标识符。 扩充器返回结果时，它必须提供此功能 recordId ，以便调用方可以将记录结果与输入匹配。

• 一个 data 成员，包含每条记录的输入字段集合。

生成的 Web API 请求可能如下所示：

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issued on November 3, 2023 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

在实践中，可能会用数百甚至数千条记录调用你的代码，而不仅仅是这里显示的三条记录。

设置 Web API 输出的格式

输出格式是一组包含 a recordId 和属性包的记录。 此特定示例只有一个输出，但可以返回多个属性。 最佳做法是，如果无法处理某个记录，请考虑返回错误消息和警告消息。

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2023 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

将自定义技能添加到技能组

创建 Web API 扩充器时，可以将 HTTP 标头和参数定义为请求的一部分。 以下代码片段显示了如何在技能组定义中包含请求参数和可选的 HTTP 标头。 如果需要将配置设置传递到代码，设置 HTTP 标头就会很有用。

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

观看视频

有关视频介绍和演示，请观看以下演示。

后续步骤

本文介绍了将自定义技能集成到技能组时所需的接口要求。 若要了解有关自定义技能和技能集组合的详细信息，请参阅以下资源：

• Power Skills：自定义技能存储库
• 示例：创建 AI 扩充的自定义技能
• 如何定义技能集
• 创建技能组合 (REST)
• 如何映射扩充的域