金山云-文档中心-Query Vectors

对象存储(KS3)

查看更多结果

未找到含当前关键字的文档标题

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

API文档

向量存储桶（KS3 Vectors）

向量相关

Query Vectors

最近更新时间：2026-11-04 15:39:19



描述

进行向量相似性检索。使用此接口，您必须是这个 Bucket 的拥有者或拥有 ks3:QueryVectors 权限。

支持相似性查询：输入查询向量，返回指定数量的相似向量（最多 30 条，可配置支持存储桶，用户，全局3种配置），并返回相似度分数。

支持元数据过滤查询：结合相似性查询，通过可过滤元数据键（如日期、类别）筛选结果，缩小查询范围。

请求

请求语法

POST /QueryVectors HTTP/1.1
Host: ks3vectors-cn-beijing.ksyuncs.com
Date: GMT Date
Content-Type: application/json
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String

方式一：使用索引资源标识 indexKrn 指定目标索引。

{
  "indexKrn": "string",
  "queryVector": {… },
  "topK": int,
  "filter": JSON value,
  "returnData": false,
  "returnMetadata":boolean,
  "returnDistance":boolean
}

方式二：使用 indexName + vectorBucketName 组合指定目标索引。

{
  "indexName": "exampleindex",
  "vectorBucketName": "example-bucket",
  "queryVector": {… },
  "topK": int,
  "filter": JSON value,
  "returnData": boolean,
  "returnMetadata":boolean,
  "returnDistance":boolean
}

请求参数

该接口不使用请求参数。

请求头

该接口仅使用公共请求头。

请求体

segmentCount 与 segmentIndex 必须同时提供或同时省略：只提供其中一个返回 400 SegmentParamsIncomplete；segmentIndex 大于 segmentCount 返回 400 InvalidSegmentIndex。

名称	父节点	描述	类型	是否必选
indexKrn	无	向量索引资源名称	String	否（与 `indexName` + `vectorBucketName` 二选一，必选其一）
indexName	无	向量索引名称	String	否（与 `vectorBucketName` 成组使用，与 `indexKrn` 二选一）
vectorBucketName	无	向量存储桶名称	String	否（与 `indexName` 成组使用，与 `indexKrn` 二选一）
queryVector	无	查询向量，结构见下表。其维度与数据类型必须与创建索引时指定的一致。	Object	是
topK	无	返回的近似最近邻结果数量，取值范围 1~上限；上限默认 30，可经服务端白名单按账号或桶配置	Integer	是
filter	无	查询向量时的预过滤器。不传或传空对象表示不过滤	JSON	否
returnData	无	是否返回向量数据，默认 `false`	Boolean	否
returnMetadata	无	是否返回向量元数据，默认 `false`	Boolean	否
returnDistance	无	是否返回结果向量与查询向量之间的距离或相似度，默认 `false`	Boolean	否

VectorData 结构 queryVector 的内容：

节点名称（关键字）	父节点	描述	类型	是否必选
float32	queryVector	float32 类型的向量数据	Array	是

元数据过滤

写入向量时附带的可过滤元数据支持通过 filter 在执行向量搜索前进行预过滤，仅对符合过滤条件的向量执行搜索。支持以下操作符:

运算符	值类型	说明
$eq	String / Number / Boolean	精确匹配。当与数组类型的元数据比较时，若输入值匹配数组中的任意一个元素，则视为匹配。
$ne	String / Number / Boolean	不等于。
$gt	String / Number / Boolean	大于。
$gte	String / Number / Boolean	大于或等于。
$lt	String / Number / Boolean	小于。
$lte	String / Number / Boolean	小于或等于。
$in	数组	匹配数组中的任意一个值（类似 SQL 的 `IN`）。
$nin	数组	不匹配数组中的任何一个值（类似 SQL 的 `NOT IN`）。
$exists	Boolean	检查元数据的 key 是否存在。
$and	条件数组	多条件逻辑与（AND）。
$or	条件数组	多条件逻辑或（OR）。

过滤规则与限制：

filter 顶层对象为 AND 语义，多个字段同时出现表示需同时满足；同一字段上的多个运算符也按 AND 组合。
filter 为空对象或不传时表示不过滤。
嵌套深度不超过 8，超限返回 400 FilterTooDeep。
条件项数不超过 1024，超限返回 400 FilterTooManyTerms。
过滤表达式序列化后不超过 64KB，超限返回 400 FilterTooLarge。
引用创建索引时被声明为不可过滤的元数据字段会返回 400，此时响应头 x-kss-error-code 为 VectorIndexParameterInvalid。

响应

响应头

该接口仅返回公共响应头。

响应体

请求成功，该接口请求返回 HTTP 200状态码，并以 JSON 格式返回响应数据。

节点名称（关键字）	父节点	描述	类型
vectors	无	根按相似度排序的查询结果列表	Array

QueryOutputVector 结构 vectors 的内容：

节点名称（关键字）	父节点	描述	类型
key	vectors	向量主键	String
data	vectors	向量数据，根据向量索引数据类型由对应的字段承载数据	VectorData
metadata	vectors	条件返回：仅当 `returnMetadata=true` 时返回；为 `false` 时该字段整体不出现（不是 `null`）	JSON
distance	vectors	条件返回：仅当 `returnDistance=true` 时返回；为 `false` 时该字段整体不出现（不是 `null`）。`euclidean` 索引下为距离，值越小表示越相似；`cosine` 索引下为余弦相似度，值越大表示越相似	Float

VectorData 结构 data 的内容：

节点名称（关键字）	父节点	描述	类型
float32	vectors.data	float32 类型的向量数据	Array

示例

纯向量相似检索

请求示例:

POST /QueryVectors HTTP/1.1
Host: ks3vectors-cn-beijing.ksyuncs.com
Date: Tue, 30 Dec 2025 08:46:33 GMT
Content-Type: application/json
Content-Length: 45
Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1558882298;1558889498&q-key-time=1558882298;1558889498&q-header-list=content-length;date;host&q-url-param-list=&q-signature=****************************************

{
  "indexName": "exampleindex",
  "vectorBucketName": "example-bucket",
  "queryVector": {
    "float32": [1.0, 2.0]
  },
  "topK": 2,
  "returnData": true,
  "returnMetadata": true,
  "returnDistance": true
}

响应示例:

HTTP/1.1 200 OK
Date: Tue, 30 Dec 2025 08:46:33 GMT
Content-Type: application/json
Connection: close
X-Kss-Request-Id: MTg4NWYxZTQ2YTNmOTMyOF*************

{
  "vectors": [
    {
      "key": "key-1",
      "data": {
        "float32": [1.0, 2.0]
      },
      "metadata": {
        "color": "red",
        "count": 10
      },
      "distance": 0.0
    },
    {
      "key": "key-2",
      "data": {
        "float32": [3.0, 4.0]
      },
      "metadata": {
        "color": "blue",
        "count": 20
      },
      "distance": 8.0
    }
  ]
}

带元数据过滤的检索

通过 filter 先过滤出 type 为 comedy 或 documentary 的向量，再做相似搜索:

请求示例：

POST /QueryVectors HTTP/1.1
Host: ks3vectors-cn-beijing.ksyuncs.com
Date: Tue, 30 Dec 2025 08:46:33 GMT
Content-Type: application/json
Content-Length: 45
Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1558882298;1558889498&q-key-time=1558882298;1558889498&q-header-list=content-length;date;host&q-url-param-list=&q-signature=****************************************

{
  "indexName": "exampleindex",
  "vectorBucketName": "example-bucket",
  "queryVector": {
    "float32": [1.0, 2.0]
  },
  "topK": 10,
  "filter": {
    "$and": [
      {
        "type": {
          "$in": ["comedy", "documentary"]
        }
      }
    ]
  }
}

错误码

HTTP 状态码	错误码	描述	典型触发场景
400	ValidationException	请求不合法	`queryVector` 缺失、`float32` 缺失或维度与索引不一致；`topK` 缺失或超出允许范围；`filter` 运算符、取值或规模不合法；引用不可过滤元数据字段；资源标识冲突或缺失。
403	AccessDeniedException	访问被拒绝	无 `ks3:QueryVectors` 权限，或被桶策略拒绝。
404	NotFoundException	资源不存在	指定的向量桶或向量索引不存在。
500	InternalServerException	服务内部错误	服务内部异常。

具体错误码通过响应头 x-kss-error-code 返回。

错误响应体格式如下，fieldList 仅校验类错误携带；非校验类错误只返回 message：

{"message": "The indexName is invalid.", "fieldList": [{"path": "/indexName", "message": "indexName must be 3-63 characters, only lowercase letters and digits, starting with a lowercase letter."}]}

文档导读

上一篇：Delete Vectors

下一篇：向量存储桶公共请求头

纯净模式常规模式

纯净模式

点击可全屏预览文档内容