调用QueryVectors实现向量相似性检索-对象存储-阿里云-对象存储(OSS)-阿里云帮助中心

调用QueryVectors接口进行向量相似性检索。

说明

QueryVectors 用于 Standard 模式索引的向量相似性检索。对于 Fusion 模式索引，请使用 QueryVectorsFusion 接口进行检索。为保持兼容，如果 Fusion 模式索引的 Schema 中仅定义了一个名为 float32 的向量字段，也可继续使用 QueryVectors 接口进行检索。

权限说明

阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限，需要阿里云账号或账号管理员通过RAM Policy概述或Bucket Policy授予操作权限。

API	Action	说明
QueryVectors	`oss:QueryVectors`	查询向量数据。

请求语法

向量索引刚刚创建后的30秒内，QueryVectors的召回率较低。PutVectors写入数据后，2-3秒左右之后可通过QueryVectors查询到数据。

POST /?queryVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Content-type: application/json

{
   "filter": {
       "$and": [{
           "type": {
               "$in": ["comedy", "documentary"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    },
   "indexName": "string",
   "queryVector": {
       "float32":[float]
    },
   "returnDistance": boolean,
   "returnMetadata": boolean,
   "topK": int
}

请求头

此接口仅涉及公共请求头。更多信息，请参见公共HTTP头定义。

请求参数

名称	数据类型	是否必选	示例值	描述
indexName	字符串	是	vectorindex1	索引名称。
queryVector	容器	是	不适用	查询向量，维度必须与向量索引的维度相同。
filter	容器	否	不适用	通过元数据对查询数据进行过滤。配置可过滤元数据时：单次过滤指令中可过滤元数据的累计长度不超过 20 KB；单次过滤指令中可过滤元数据项数量不超过 1024 个；过滤条件嵌套层级最多支持 8 层；
returnDistance	布尔值	否	false	是否返回相似距离。取值： true false（默认值）
returnMetadata	布尔值	否	false	是否返回元数据。取值： true false（默认值）
topK	数值	是	10	设置返回最相似结果的数量，默认范围：1～500。

Filter操作符

操作符	支持类型	描述
`$eq`	String, Number, Boolean	精确匹配（用于单个值）。当与数组类型的元数据进行比较时，如果输入值能匹配数组中的任意一个元素，则返回true。
`$ne`	String, Number, Boolean	不等于
`$gt`	Number	大于
`$gte`	Number	大于等于
`$lt`	Number	小于
`$lte`	Number	小于等于
`$in`	Non-empty array of primitives	匹配数组中的任意一个值（类似于SQL的`IN`操作）
`$nin`	Non-empty array of primitives	不匹配数组中的任何一个值（类似于SQL的`NOT IN`操作）
`$exists`	Boolean	检查是否存在
`$and`	Non-empty array of filters	多条件判断与（AND）
`$or`	Non-empty array of filters	多条件判断或（OR）
`$nor`	Non-empty array of filters	多条件判断非（NOR）

Filter 示例

以下为常见的 Filter 表达式示例。省略操作符时，默认使用 $eq。

// 简单等值（省略操作符时默认使用 $eq）
{"category": "finance"}

// 显式等值 / 不等
{"category": {"$eq": "finance"}}
{"category": {"$ne": "archived"}}

// 数值比较
{"created_year": {"$gt": 2023}}
{"created_year": {"$gte": 2024}}
{"created_year": {"$lt": 2026}}
{"created_year": {"$lte": 2025}}

// 数组匹配
{"language": {"$in": ["zh", "en"]}}
{"language": {"$nin": ["ja", "ko"]}}

// 存在性检查
{"author": {"$exists": true}}

// 逻辑组合
{"$and": [{"category": {"$eq": "finance"}}, {"created_year": {"$gte": 2024}}]}
{"$or": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}
{"$nor": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}

// 同一字段的多个条件（范围）
{"score": {"$gte": 0.6, "$lte": 0.95}}

响应头

此接口仅涉及公共响应头。更多信息，请参见公共HTTP头定义。

响应元素

名称	数据类型	示例值	描述
vectors	对象数组	/	返回向量列表。如果查询的主键不存在，无报错但不返回当前key结果。
key	字符串	doc-001	向量主键。父节点：vectors
distance	float32	0.25	向量和查询向量之间的相似距离，值越小说明越相似（仅当returnDistance为true时返回）。父节点：vectors
metadata	对象	/	全量元数据（仅当returnMetadata为true时返回）。父节点：vectors

示例

POST /?queryVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
   "filter": {
       "$and": [{
           "category": {
               "$in": ["technology", "science"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    },
   "indexName": "vectorindex1",
   "queryVector": {
       "float32": [0.15, 0.25, 0.35, 0.45, 0.55]
    },
   "returnDistance": true,
   "returnMetadata": true,
   "topK": 5
}

返回示例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Connection: keep-alive
Server: AliyunOSS
Content-type: application/json

{
   "vectors": [ 
      { 
         "distance": 0.12,
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search",
             "year": "2020"
         }
      },
      { 
         "distance": 0.25,
         "key": "doc-003",
         "metadata": {
             "category": ["science"],
             "title": "Advanced Vector Operations",
             "year": "2020"
         }
      }
   ]
}

SDK

QueryVectors接口所对应的各语言SDK如下：

命令行工具ossutil

QueryVectors接口所对应的ossutil命令，请参见query-vectors。

错误码

错误码	HTTP状态码	描述
VectorIndexParameterInvalid	400	请求中提供的向量索引参数不合法。
MalformedJson	400	请求体中的 JSON 格式不符合规范。
AccessDenied	403	返回该错误的可能原因如下：发起请求时没有传入用户验证信息。没有操作权限。
NoSuchVectorIndex	404	指定的向量索引不存在。
QpsLimitExceeded	503	QPS 限流（请求速率受限）。