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

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

项目
09/01/2024

重要

对 Azure AI Studio 模型目录的索引器连接的支持以公共预览版提供补充使用条款。预览版 REST API 支持此技能。

通过 AML 技能，可以使用自定义 Azure 机器学习 (AML) 模型来扩展 AI 扩充。在训练和部署 AML 模型后，AML 技能即可将其集成到 AI 扩充中。

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

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

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

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

注意

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

503 Service Unavailable
429 Too Many Requests

先决条件

AML 工作区
此工作区中的联机终结点（实时）。

@odata.type

Microsoft.Skills.Custom.AmlSkill

技能参数

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

参数名称	说明
`uri`	（密钥身份验证所需）JSON 有效负载发送到的 AML 联机终结点的评分 URI。仅支持 https 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 联机终结点使用的身份验证（如果有）。 AML 联机终结点提供两个身份验证选项：

基于密钥的身份验证。提供静态密钥，对来自 AML 技能的评分请求进行身份验证
- 使用 uri 和 key 参数
基于令牌的身份验证。使用基于令牌的身份验证来部署 AML 联机终结点。必须启用 Azure AI 搜索服务的托管标识。然后，AML 技能使用服务的托管标识向 AML 联机终结点进行身份验证，无需任何静态密钥。必须为该标识分配所有者或参与者角色。
- 使用 resourceId 参数。
- 如果搜索服务与 AML 工作区位于不同的区域，请使用 region 参数设置 AML 联机终结点已部署到的区域

技能输入

此技能没有“预定义”输入。可以选择在执行此技能时已提供的一个或多个字段作为输入，发送到 AML 联机终结点的 JSON 有效负载将会有不同的字段。

技能输出

此技能没有“预定义”输出。根据 AML 联机终结点返回的响应添加输出字段，以便能够从 JSON 响应中选取这些字段。

示例定义

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.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://contoso.count-things.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 错误的任何可用详细信息。

通过