功能描述

从向量索引中根据一个目标向量 KNN 查询距离最近 TopK 向量。

请求消息样式

Endpoint 需使用 Bucket Endpoint。

POST /QueryVectors HTTP/1.1​
Host: {VectorBucketName}-{AccountID}.tosvectors-cn-beijing.volces.com​
Authorization: authorization string​
Date: Wed, 10 Dec 2025 12:49:14 GMT​
​
{​
    "vectorBucketName": "test-vector-bucket",​
    "indexName": "test-index",​
    "queryVector": {​
        "float32": [​
            0.1,​
            0.1,​
            0.1,​
            0.1,​
            0.1​
        ]​
    },​
    "topK": 10,​
    "returnDistance": true,​
    "returnMetadata": true,​
    "filter": {"$and": [{"key_a": "va"}]}​
}​

请求参数和消息头

无。

请求元素

名称	参数类型	是否必选	示例值	说明
vectorBucketName	string	是	test-vector-bucket	向量桶的名称。
indexName	string	是	test-index	向量索引的名称。
filter	JSON value	否	{"$and": [{"key_a": "va"}]}	在查询期间应用的元数据筛选器。
queryVector	VectorData	是	{ "float32": [0.1,0.1,0.1,0.1,0.1] }	查询向量。确保查询向量的维度与被查询的向量索引的维度相同。
returnDistance	boolean	否	true	指示是否在响应中包含计算出的距离。默认值：false。
returnMetadata	boolean	否	true	指示是否在响应中包含元数据。默认值：false。
topK	integer	是	10	为每个查询返回的结果数量。有效范围：最小值为 1，最大值为 30。

VectorData 结构体是 Union 类型，当前只有一个成员有效（float32），参见下表。

名称	参数类型	示例值	说明
float32	float32[]	[0.1, 0.1, 0.1, 0.1, 0.1]	向量数据。该向量维度必须和 CreateIndex 中定义的向量索引维度一致。

响应消息头

返回公共的响应头，请参见公共参数。

响应元素

如果操作成功，服务将返回一个 HTTP 200 响应码以及如下响应元素。

如果操作失败，返回响应码中定义的错误码。

字段	类型	示例值	说明
vectors	[]QueryOutputVector	参见下表	包含向量搜索结果的数组。

QueryOutputVector 结构体参数说明：

参数名称	参数类型	示例值	说明
data	VectorData	[0.1, 0.1, 0.1, 0.1, 0.1]	向量数据。确保查询向量的维度与被查询的向量索引的维度相同。
distance	float	0.050000004	查询向量与结果向量之间的距离。
key	string	key0	向量的唯一标识符。
metadata	JSON value	{ "key_a": "va", "key_b": "vb", "key_c": "vc1", "key_d": "vd" }	与向量关联的元数据。

请求示例

响应示例

对象存储