通过

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

自定义 Web API 矢量器

  • 项目

重要

根据补充使用条款，此功能以公共预览版提供。 2023-10-01-Preview REST API 和所有更高版本的预览版 REST API 支持此功能。

自定义 Web API 矢量器允许将搜索查询配置为调用 Web API 终结点，以便在查询时生成嵌入。 在本文档中进一步描述了在所提供的终结点中实现所需 JSON 有效负载的结构。 数据在部署模型的地理位置进行处理。

矢量器参数

参数区分大小写。

参数名称 说明
uri JSON 有效负载发送到的 Web API 的 URI。 仅支持 https URI 方案。
httpMethod 发送有效负载时使用的方法。 允许使用的方法为 PUT 或 POST
httpHeaders 键值对集合，其中键表示头名称，值表示发送到 Web API 的头值以及有效负载。 此集合中禁止使用以下标头：Accept、Accept-Charset、Accept-Encoding、Content-Length、Content-Type、Cookie、Host、TE、Upgrade、Via。
authResourceId （可选）字符串，如果设置了它，则指示此矢量器应在与托管代码的函数或应用的连接上使用托管标识。 此属性采用以下任何格式api://<appId><appId>/.defaultapi://<appId>/.default的应用程序（客户端）ID 或应用注册Microsoft Entra ID。 此值用于确定索引器检索到的身份验证令牌的作用域，并随自定义 Web API 请求一起发送到函数或应用。 设置此属性要求搜索服务配置为托管标识，并且 Azure 函数应用配置为 Microsoft Entra 登录。
authIdentity （可选）搜索服务用于连接托管代码的函数或应用的用户托管标识。 可以使用系统托管标识或用户托管标识。 要使用系统托管标识，请将 authIdentity 留空。
timeout （可选）如果指定，表明执行 API 调用的 http 客户端的超时值。 必须将其格式化为 XSD“dayTimeDuration”值（ISO 8601 持续时间值的受限子集）。 例如，PT60S 表示 60 秒。 如果未设置，选择的是默认值 30 秒。 超时可以设置为最大 230 秒和最小 1 秒。

支持的矢量查询类型

自定义 Web API 矢量器支持 text、imageUrl 和 imageBinary 矢量查询。

示例定义

"vectorizers": [
    {
        "name": "my-custom-web-api-vectorizer",
        "kind": "customWebApi",
        "customWebApiParameters": {
            "uri": "https://contoso.embeddings.com",
            "httpMethod": "POST",
            "httpHeaders": {
                "api-key": "0000000000000000000000000000000000000"
            },
            "timeout": "PT60S",
            "authResourceId": null,
            "authIdentity": null
        },
    }
]

JSON 有效负载结构

将 JSON 有效负载结构与自定义 Web API 矢量器一起使用时，终结点所需的 JSON 有效负载结构与自定义 Web API 技能相同，技能的文档将对此进行更详细的讨论。

在实现要与自定义 Web API 矢量器一起使用的 Web API 终结点时，还需要考虑以下其他事项。

  • 向终结点发出请求时，矢量器在 values 阵列中一次只发送一条记录。

  • 矢量器将要矢量化的数据传递到请求有效负载中 data JSON 对象的特定键中。 键为 text、imageUrl 或 imageBinary，具体取决于请求的矢量查询类型。

  • 矢量器期望得到的嵌入位于响应有效负载中 data JSON 对象的 vector 键下。

  • 终结点返回的任何错误或警告都会被矢量器忽略，并且在查询时无法用于调试。

  • 如果请求了 imageBinary 矢量查询，则发送到终结点的请求有效负载如下：

    {
    "values": [
        {
            "recordId": "0",
            "data":
            {
                "imageBinary": {
                    "data": "<base 64 encoded image binary data>"
                }
            }
        }
    ]
}

另请参阅