Azure AI 搜索扩充管道中的 AML 技能

使用 AML 技能通过 Azure AI Foundry 模型目录 或自定义 Azure 机器学习 （AML） 模型通过已部署的基础嵌入模型扩展 AI 扩充。 训练和部署 AML 模型后，AML 技能会将模型集成到技能集中。

AML 技能用法

与其他内置技能一样，自定义 AML 技能具有输入和输出。 输入作为 JSON 对象发送到已部署的 AML 联机终结点。 终结点的输出必须是响应中的 JSON 有效负载，以及成功状态代码。 数据在部署模型的地理位置进行处理。 响应应提供 AML 技能定义指定的输出。 任何其他响应都被视为错误，不会执行任何扩充。

可以使用稳定的 REST API 版本或等效的 Azure SDK 调用 AML 技能。 若要连接到 Azure AI Foundry 门户中的模型目录，请使用预览 API 版本。

Azure AI Foundry 中模型的 AML 技能

从 2024-05-01 预览版 REST API 和 Azure 门户开始，Azure AI 搜索也面向 2024-05-01-preview，Azure AI 搜索提供了 Azure AI Foundry 模型目录向量器，用于在 Azure AI Foundry 门户中与模型目录建立查询时连接。 如果要使用该向量器进行查询， AML 技能是用于使用模型目录中的模型生成嵌入的 索引 对应项。

在编制索引期间， AML 技能可以连接到模型目录，为索引生成向量。 在查询时，查询可以使用向量器连接到同一模型，以向量查询的文本字符串进行矢量化。 在此工作流中，应结合使用 AML 技能和模型目录向量器，以便使用相同的嵌入模型来编制索引和查询。 有关详细信息，包括支持的嵌入模型列表，请参阅 使用 Azure AI Foundry 模型目录中的嵌入模型。

建议使用 导入数据（新） 向导 生成技能集，其中包含用于在 Azure AI Foundry 中部署嵌入模型的 AML 技能。 该向导为输入、输出和映射生成 AML 技能定义，从而提供在编写任何代码之前测试模型的简单方法。

先决条件

• 一个用于从目录部署的嵌入模型的 Azure AI Foundry 项目 ，或为创建的自定义模型的 AML 工作区 。
• 从目录部署的嵌入模型或自定义模型的 AML 工作区的 联机终结点（实时） 的模型终结点。

@odata.type

Microsoft.Skills.Custom.AmlSkill

技能参数

参数区分大小写。 使用的参数取决于 AML 联机终结点所需的身份验证（如果有）。

身份验证

AML 联机终结点提供两个身份验证选项：

• 基于密钥的身份验证。 提供静态密钥以验证来自 AML 技能的评分请求。 uri设置此连接的和key参数。

• 基于令牌的身份验证，其中使用基于令牌的身份验证部署 AML 联机终结点。 Azure AI 搜索服务必须在 AML 工作区上具有 托管标识 和角色分配。 然后，AML 技能使用服务的托管标识向 AML 联机终结点进行身份验证，无需任何静态密钥。 搜索服务标识必须具有 “所有者 ”或 “参与者 ”角色。 resourceId设置参数，如果搜索服务位于不同于 AML 工作区的区域，请设置region参数。

技能输入

技能输入是文档破解期间创建的扩充文档的节点。 例如，它可能是根文档、规范化图像或 Blob 的内容。 此技能没有预定义的输入。 对于输入，应指定在 AML 技能执行时填充的一个或多个节点。

技能输出

技能输出是技能创建的扩充文档的新节点。 此技能没有预定义的输出。 对于输出，应提供可从 AML 技能的 JSON 响应填充的节点。

示例定义

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A custom model that detects the language in a document.",
    "uri": "https://language-model.models.contoso.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

示例输入 JSON 结构

此 JSON 结构表示发送到 AML 联机终结点的有效负载。 该结构的顶层字段对应技能定义的 inputs 节中指定的“names”。 这些字段的值来自这些字段的“源”，这些字段可能来自文档中的某个字段或其他技能。

{
  "text": "Este es un contrato en Inglés"
}

示例输出 JSON 结构

输出对应于来自 AML 联机终结点的响应。 AML 联机终结点只应返回 JSON 有效负载（通过查看 Content-Type 响应头验证），该终结点应该是一个对象，其中的字段是与 output 中的“names”匹配的扩充，其值被视为扩充。

{
    "detected_language_code": "es"
}

内联成形示例定义

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://language-model.models.contoso.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "shapedText",
        "sourceContext": "/document",
        "inputs": [
            {
              "name": "content",
              "source": "/document/content"
            }
        ]
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

内联成形 JSON 结构

{
  "shapedText": { "content": "Este es un contrato en Inglés" }
}

内联成形示例输出 JSON 结构

{
    "detected_language_code": "es"
}

错误案例

除了 AML 不可用或发送非合格状态代码外，以下情况被视为错误：

• AML 联机终结点返回成功状态代码，但响应指示它不是 application/json。 因此，响应无效，不会执行任何扩充。

• AML 联机终结点返回无效的 JSON。

如果 AML 联机终结点不可用或返回 HTTP 错误，则会向索引器执行历史记录添加有关 HTTP 错误的任何可用详细信息的友好错误。

另请参阅

• 在 Azure AI 搜索中创建技能组
• 使用 Azure AI Foundry 模型目录中的嵌入模型
• 排查 Azure 机器学习联机终结点部署和评分问题