使用query-vectors进行向量相似性检索-对象存储-阿里云-对象存储(OSS)-阿里云帮助中心

权限说明

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

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

命令格式

ossutil vectors-api query-vectors --bucket value --index-name value --query-vector value --top-k value  [flags]

参数说明

参数	类型	说明
--bucket	string	向量Bucket名称。
--index-name	string	索引名称。
--query-vector	string	查询向量，JSON格式，维度必须与向量索引的维度相同。
--top-k	int	返回最相似的K个向量，支持1~500。
--filter	string	通过元数据对查询数据进行过滤。单次长度最大20KB 单次filter指令最多1024个
--return-distance	/	是否返回相似距离，留空或设置为 `true` 均表示开启。
--return-metadata	/	是否返回元数据，留空或设置为 `true` 均表示开启。

说明

query-vectors命令对应API接口QueryVectors。
关于支持的全局命令行选项，请参见全局命令行选项。

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}}

使用示例

在名为examplebucket的向量Bucket中名为 index 的向量索引里，type为comedy和documentary的向量中与查询向量最相似的前 10 条。

ossutil vectors-api query-vectors --bucket examplebucket --index-name index --filter "{\"$and\":[{\"type\":{\"$in\":[\"comedy\",\"documentary\"]}}]}" --query-vector "{\"float32\":[32]}" --top-k 10