将自定义技能添加到 Azure AI 搜索扩充管道

注释

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。

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

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

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

自定义技能的优点

通过构建自定义技能，可以插入针对您的内容的唯一转换。例如，可以生成自定义分类模型，以区分商业与金融领域的合同和文档，或者，添加语音识别技能，以便深入探究音频文件获取相关内容。有关分步示例，请参阅示例：为 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>。

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

设置 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.chinacloudsites.cn/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

后续步骤

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

Last updated on 2026-07-27