自定义 Web API 矢量器

使用自定义 Web API 矢量器，可以将搜索查询配置为调用在查询时生成嵌入的 Web API 终结点。本文稍后将介绍终结点所需的 JSON 有效负载结构。您的数据在模型部署的地理位置中进行处理。

尽管矢量化器在查询时使用，但您需要在索引定义中指定它们，并通过矢量概况在向量字段上引用它们。有关详细信息，请参阅在搜索索引中配置向量器。

自定义 Web API 向量器在 REST API 中被称为 WebApiVectorizer。使用最新的稳定版本的索引 - 创建（REST API）或提供该功能的 Azure SDK 包。

矢量器参数

参数区分大小写。

参数名称	说明
`uri`	JSON 有效负载被发送到的 Web API 的 URI。仅支持 https URI 方案。
`httpMethod`	用于发送有效负载的方法。允许的方法为 `PUT` 或 `POST`。
`httpHeaders`	键值对集合，其中键表示头名称，值表示发送到 Web API 的头值以及有效负载。此集合中禁止以下标头：`Accept`、、`Accept-Charset`、、`Accept-EncodingContent-Length`、`Content-TypeCookie`、`Host`、`TE`、、 `Upgrade`。 `Via`
`authResourceId`	（可选）一个字符串，如果已设置，则指示此向量器使用托管标识连接到托管代码的函数或应用。此属性可接受 Microsoft Entra ID 中的应用程序（客户端）ID或应用注册，其格式之一为：`api://<appId>`、`<appId>/.default`、`api://<appId>/.default`。此值定义了查询管道检索的身份验证令牌的范围，并通过自定义 Web API 请求将其发送到函数或应用。设置此属性要求您的搜索服务已配置为托管标识，并且您的Azure函数应用已配置为Microsoft Entra登录。
`authIdentity`	（可选）搜索服务使用的用户管理的身份，用以连接到托管代码的函数或应用。可以使用系统托管标识或用户托管标识。若要使用系统托管标识，请留 `authIdentity` 空。
`timeout`	（可选）用于发出 API 调用的 HTTP 客户端的超时时间。它必须格式化为 XSD `dayTimeDuration` 值（ ISO 8601 持续时间值的受限子集）。例如， `PT60S` 表示 60 秒。如果未设置，则默认值为 30 秒。超时时间可以介于 1 到 230 秒之间。

支持的矢量查询类型

自定义 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 数据负载结构

自定义 Web API 向量化器使用的终结点所需的 JSON 有效负载结构与自定义 Web API 技能使用的结构相同，在技能文档中有更详细的讨论。

为自定义 Web API 向量器实现 Web API 终结点时，请记住以下注意事项。

向终结点发出请求时，矢量器在 values 阵列中一次只发送一条记录。
矢量器将要矢量化的数据传递到请求有效负载中 data JSON 对象的特定键中。键为 text、imageUrl 或 imageBinary，具体取决于请求的矢量查询类型。
矢量器期望得到的嵌入位于响应有效负载中 vector JSON 对象的 data 键下。
终结点返回的任何错误或警告都会被矢量化程序忽略，并且不适用于查询时调试。

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

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

另请参阅

Last updated on 2026-03-16

通过