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

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

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

@odata.type

Microsoft.Skills.Custom.WebApiSkill

技能参数

参数区分大小写。

技能输入

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

技能输出

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

示例定义

{
  "@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 部分中指定的“names”。 这些字段的值来自这些字段的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 错误的任何可用详细信息的易记错误都会添加到索引器执行历史记录。

另请参阅

• 定义技能集
• 向 AI 扩充管道添加自定义技能
• 示例：创建 AI 扩充的自定义技能
• Power Skill 存储库