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

自定义 Web API 矢量器

2025-09-12

自定义 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-Encoding`、`Content-Length`、`Content-Type`、`Cookie`、`Host`、`TE`、`Upgrade`、`Via`。
`authResourceId`	（可选）字符串，如果设置了它，则指示此矢量器应在与托管代码的函数或应用的连接上使用托管标识。此属性采用应用程序（客户端）ID 或应用在 Microsoft Entra 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 秒。超时可以设置为最大 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，具体取决于请求的矢量查询类型。
矢量器期望得到的嵌入位于响应有效负载中 vector JSON 对象的 data 键下。
终结点返回的任何错误或警告都会被矢量器忽略，并且在查询时无法用于调试。

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

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

另请参阅

反馈

此页面是否有帮助？