在 Azure AI 搜索扩充管道中自定义 Web API 技能

项目
10/21/2024

借助自定义 Web API 技能，可以通过调用提供自定义操作的 Web API 终结点来扩展 AI 扩充。与内置技能类似，“自定义 Web API” 技能也有输入和输出。 Web API 根据输入在索引器运行时接收 JSON 有效负载，并输出 JSON 有效负载作为响应，以及成功状态代码。响应应包含自定义技能指定的输出。其他任何响应都被视为错误，并且不会执行任何扩充。本文档进一步详细介绍了 JSON 有效负载的结构。

本文档进一步详细介绍了 JSON 有效负载的结构。

注意

索引器会对 Web API 返回的某些标准 HTTP 状态代码重试两次。这些 HTTP 状态代码为：

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

技能参数

参数区分大小写。

参数名称	说明
`uri`	JSON 有效负载发送到的 Web API 的 URI。仅支持 https URI 方案。
`authResourceId`	（可选）一个字符串，如果设置了该字符串，则它指示此技能在连接到托管代码的函数或应用时应使用系统托管标识。此属性采用应用程序（客户端）ID 或应用在 Microsoft Entra ID 中的注册，并采用以下任何格式：`api://<appId>`、`<appId>/.default`、`api://<appId>/.default`。此值用于确定索引器检索到的身份验证令牌的作用域，并随自定义 Web 技能 API 请求一起发送到函数或应用。设置此属性要求搜索服务配置为托管标识，并且 Azure 函数应用配置为 Microsoft Entra 登录。要使用此参数，请使用 `api-version=2023-10-01-Preview` 调用 API。
`authIdentity`	（可选）搜索服务用于连接托管代码的函数或应用的用户托管标识。可以使用系统托管标识或用户托管标识。要使用系统托管标识，请将 `authIdentity` 留空。
`httpMethod`	发送有效负载时使用的方法。允许使用的方法为 `PUT` 或 `POST`
`httpHeaders`	键值对集合，其中键表示头名称，值表示发送到 Web API 的头值以及有效负载。此集合中禁止使用以下标头：`Accept`、`Accept-Charset`、`Accept-Encoding`、`Content-Length`、`Content-Type`、`Cookie`、`Host`、`TE`、`Upgrade`、`Via`。
`timeout`	（可选）如果指定，表明执行 API 调用的 http 客户端的超时值。必须将其格式化为 XSD“dayTimeDuration”值（ISO 8601 持续时间值的受限子集）。例如，`PT60S` 表示 60 秒。如果未设置，选择的是默认值 30 秒。超时可以设置为最大 230 秒和最小 1 秒。
`batchSize`	（可选）表示每 API 调用发送多少个“数据记录”（请参阅下面的 JSON 有效负载结构）。如果未设置，选择的是默认值 1000。建议使用此参数在索引编制吞吐量和 API 负载之间进行适当取舍。
`degreeOfParallelism`	（可选）在已指定的情况下指示索引器对你提供的终结点进行的并行调用数。如果终结点在压力下失败，可以减小此值，如果终结点可以处理负载，则可以提高此值。如果未设置，则将使用默认值 5。可以为 `degreeOfParallelism` 设置的最大值为 10，最小值为 1。

技能输入

此技能没有预定义的输入。输入是要传递给自定义技能的任何现有字段或扩充树中的任何节点。

技能输出

此技能没有预定义的输出。如果技能的输出应发送到搜索索引中的字段，请确保在索引器中定义输出字段映射。

示例定义

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

示例输入 JSON 结构

此 JSON 结构表示发送到 Web API 的有效负载。它始终遵循以下约束：

顶级实体名为values，并且是对象数组。此类对象的数量最多为batchSize。
values数组中的每个对象都有：
- recordId 属性，用于标识相应记录的唯一字符串。
- data 属性，它是 JSON 对象。 data属性的字段对应于技能定义的inputs部分中指定的“名称”。这些字段的值来自这些字段的source（可能来自文档中的字段，也可能来自另一个技能）。

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

示例输出 JSON 结构

“输出”对应于 Web API 返回的响应。 Web API 应仅返回 JSON 有效负载（通过查看 Content-Type 响应头进行验证），并且应遵循以下约束：

应有名为values且是对象数组的顶级实体。
数组中的对象数量应与发送到 Web API 的对象数量相同。
每个对象都应有：
- recordId 属性。
- data 属性，这个对象中的字段是与 output 中“名称”匹配的扩充，且值被视为扩充。
- errors属性，列出添加到索引器执行历史记录的任何错误的数组。此属性是必需的，但可以有 null 值。
- warnings属性，列出添加到索引器执行历史记录的任何警告的数组。此属性是必需的，但可以有 null 值。
在请求或响应中，values 中的对象的排序并不重要。不过，由于recordId用于关联，因此响应中任何包含recordId（不属于向 Web API 发送的原始请求）的记录都会遭放弃。

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

错误案例

除了 Web API 不可用或发送出非成功状态代码以外，还会将以下情况视为出错：

如果 Web API 返回成功状态代码，但响应指明它不是application/json，那么响应会被视为无效，并且不会执行任何扩充。
如果响应values数组中存在无效的记录（例如，recordId缺少或重复），则不会针对无效的记录执行任何扩充。开发自定义技能时，请务必遵守 Web API 技能协定。可以参考遵循此预期协定的 Power Skill 存储库中提供的此示例。

在 Web API 不可用或返回 HTTP 错误的情况下，包含 HTTP 错误的任何可用详细信息的易记错误都会添加到索引器执行历史记录。

通过