在 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 存储库