金山云-文档中心-Get Vectors

对象存储(KS3)

查看更多结果

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

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

API文档

向量存储桶（KS3 Vectors）

向量相关

Get Vectors

最近更新时间：2026-11-03 19:59:22



描述

根据 key 获取一条或多条向量数据。单次 GetVectors 请求最多可获取 100 条向量数据。使用此接口，您必须是这个 Bucket 的拥有者或拥有 ks3:GetVectors 权限。

请求

请求语法

POST /GetVectors 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",
  "keys": [ ... ],
  "returnData": boolean,
  "returnMetadata":boolean
}

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

{
  "indexName": "string",
  "vectorBucketName": "string",
  "keys": [ ... ],
  "returnData": boolean,
  "returnMetadata": boolean
}

请求参数

该接口不使用请求参数。

请求头

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

请求体

indexKrn（AWS4 签名下为 indexArn）与 indexName + vectorBucketName 组合严格二选一：同时提供返回 400 IndexArnAndNameConflict；两者都不提供返回 400 IndexInfoMissing。

参数	是否必填	类型	说明
indexKrn	否（与 `indexName` + `vectorBucketName` 二选一，必选其一）	String	向量索引资源名，格式为 `krn:ksc:ks3vectors:<region>:<accountId>:bucket/<bucketName>/index/<indexName>`。AWS4 签名下字段名为 `indexArn`
indexName	否（与 `vectorBucketName` 成组使用，与 `indexKrn` 二选一）	String	向量索引名称。长度为 3~63 字符，仅允许小写字母和数字，首字符必须是字母
vectorBucketName	否（与 `indexName` 成组使用，与 `indexKrn` 二选一）	String	向量存储桶名称。长度为 3~63 字符，允许小写字母、数字和 `-`，首尾不能是 `-`
keys	是	Array	目标向量主键列表，数组长度为 1~100，单个 `key` 长度为 1~1024 字符
returnData	否	Boolean	是否返回向量数据，默认 `false`
returnMetadata	否	Boolean	是否返回向量元数据，默认 `false`

响应

响应头

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

响应体

{
   "vectors": [ 
      { 
         "key": "string",
         "data": { ... },
         "metadata": JSON value
      }
   ]
}

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

名称	父节点	描述	类型
vectors	无	根据 `keys` 获取到的向量列表	Array

vectors 的内容：

名称	父节点	描述	类型
key	vectors	向量主键	String
data	vectors	条件返回：仅当 `returnData=true` 时返回；为 `false` 时该字段整体不出现	VectorData
metadata	vectors	条件返回：仅当 `returnMetadata=true` 时返回；为 `false` 时该字段整体不出现（不是 `null`）	JSON

data 的内容：

名称	父节点	描述	类型
float32	vectors.data	float32 类型的向量数据	Array

示例

案例一：获取向量数据

请求示例:

POST /GetVectors 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",
  "keys": ["key-1", "key-2"],
  "returnData": true
}

响应示例:

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

{
  "vectors": [
    {
      "key": "key-1",
      "data": {
        "float32": [1.0, 2.0]
      }
    },
    {
      "key": "key-2",
      "data": {
        "float32": [3.0, 4.0]
      }
    }
  ]
}

案例二：获取向量数据和元数据

请求示例:

POST /GetVectors 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",
  "keys": ["key-1", "key-2"],
  "returnData": true,
  "returnMetadata": true
}

响应示例:

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

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

错误码

HTTP 状态码	错误码	描述	典型触发场景
400	ValidationException	请求不合法	`keys` 为空、数量超过 100 或单个 `key` 长度不在 1~1024 字符内；请求体格式错误；资源标识冲突或缺失。
403	AccessDeniedException	访问被拒绝	无 `ks3:GetVectors` 权限，或被桶策略拒绝。
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."}]}

文档导读

上一篇：Put Vectors

下一篇：List Vectors

纯净模式常规模式

纯净模式

点击可全屏预览文档内容