你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

项目
12/18/2024

重要

对 Azure AI Foundry 模型目录的索引器连接的支持在补充使用条款下处于公共预览状态。预览版 REST API 支持此技能。

借助 AML 技能，可以使用自定义Azure 机器学习（AML）模型或部署的基础嵌入模型在 Azure AI Foundry 上扩展 AI 扩充。训练和部署 AML 模型后，AML 技能将其集成到技能集中。

AML 技能用法

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

注意

索引器对于从 AML 联机终结点返回的特定标准 HTTP 状态代码会重试两次。这些 HTTP 状态代码为：

503 Service Unavailable
429 Too Many Requests

可以使用 2024-07-01 稳定 API 版本或等效的 Azure SDK 或 2024-05-01-preview API 版本调用 AML 技能，以便连接到 Azure AI Foundry 门户中的模型目录。

Azure AI Foundry 中模型的 AML 技能

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

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

建议使用 导入和矢量化数据 向导来生成技能集，其中包括用于在 Azure AI Foundry 上部署的嵌入模型的 AML 技能。向导会生成用于输入、输出和映射的 AML 技能定义，这样就可以在编写任何代码之前轻松测试模型。

先决条件

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

@odata.type

Microsoft.Skills.Custom.AmlSkill

技能参数

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

参数名称	说明
`uri`	（密钥身份验证所需）JSON 有效负载发送到的 AML 联机终结点的评分 URI。仅支持 https URI 方案。若要在 Azure AI Foundry 模型目录中嵌入模型，这是目标 URI。
`key`	（密钥身份验证必需） AML 联机终结点或
`resourceId`	（令牌身份验证需要）。 AML 联机终结点的 Azure 资源管理器资源 ID。它应采用格式 `subscriptions/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name}`。
`region`	（对于令牌身份验证可选）。 AML 联机终结点部署到的区域。
`timeout`	（可选）如果指定，表明执行 API 调用的 http 客户端的超时值。必须将其格式化为 XSD“dayTimeDuration”值（ISO 8601 持续时间值的受限子集）。例如，`PT60S` 表示 60 秒。如果未设置，选择的是默认值 30 秒。超时可以设置为最大 230 秒和最小 1 秒。
`degreeOfParallelism`	（可选）在已指定的情况下指示索引器对你提供的终结点进行的并行调用数。如果终结点在请求负载过高的情况下发生故障，则可减小此值。如果终结点能够接受更多请求，并且你希望提高索引器的性能，则可增大此值。如果未设置，则将使用默认值 5。可以为 degreeOfParallelism 设置的最大值为 10，最小值为 1。

身份验证

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

基于密钥的身份验证。提供静态密钥以验证来自 AML 技能的评分请求。 uri设置此连接的和key参数。
基于令牌的身份验证，其中使用基于令牌的身份验证部署 AML 联机终结点。必须启用 Azure AI 搜索服务的托管标识，并在工作区上分配角色。然后，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”。这些字段的值来自这些字段的 source（可能来自文档中的字段，也可能来自另一个技能）

{
  "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 错误的任何可用详细信息的友好错误添加到索引器执行历史记录。

通过