金山云-文档中心-Put Vectors

对象存储(KS3)

查看更多结果

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

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

API文档

向量存储桶（KS3 Vectors）

向量相关

Put Vectors

最近更新时间：2026-11-03 19:52:57



描述

向索引中写入向量数据。使用此接口,您必须是这个 Bucket 的拥有者或拥有 ks3:PutVectors 权限。

单个向量索引表最多可存储 5000 万行向量数据。

PutVectors 请求单次最多可写入 500 条向量，每秒最多支持 5 次请求。

请求

请求语法

POST /PutVectors 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",
  "vectors": [
    {
      "key": "string",
      "data": {…},
      "metadata": JSON value
    }
  ]
}

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

{
  "indexName": "string",
  "vectorBucketName": "string",
  "vectors": [
    {
      "key": "string",
      "data": {…},
      "metadata": JSON value
    }
  ]
}

请求参数

该接口不使用请求参数。

请求头

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

请求体

请求体为向索引中写入向量数据的JSON：

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 字符，允许小写字母、数字和 `-`，首尾不能是 `-`。
vectors	是	Array	待写入的向量列表，数组长度为 1~500。同一请求内不允许出现重复的 `key`。

vectors 节点的字段：

参数	是否必填	类型	说明
key	是	String	向量主键，用于标识索引内的唯一向量。长度为 1~1024 字符，必须为 UTF-8 编码，单次请求内不可重复。
data	是	Object	向量数据，结构见下表。
metadata	否	JSON	向量关联的元数据。序列化后总大小不超过 40KB，其中可过滤部分不超过 2KB；键个数不超过 10 个；值类型仅支持整数、浮点数、字符串、数组。

data 节点的字段：

参数	是否必填	类型	说明
float32	是	Array	float32 类型的向量数据，数组长度必须等于索引创建时指定的维度。

响应

响应头

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

响应体

该接口不返回响应体。

示例

请求示例一：通过 `indexKrn` 写入向量

POST /PutVectors 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=****************************************
{
  "indexKrn": "krn:ksc:ks3vectors:cn-beijing:103735000000:bucket/example-bucket/index/exampleindex",
  "vectors": [
    {
      "key": "key-1",
      "data": {
        "float32": [1.0, 2.0, 3.0, 4.0]
      },
      "metadata": {
        "color": "red",
        "count": 10
      }
    }
  ]
}

示例二：通过 `indexName` + `vectorBucketName` 写入向量

POST /PutVectors 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",
  "vectors": [
    {
      "key": "key-1",
      "data": {
        "float32": [1.0, 2.0, 3.0, 4.0]
      },
      "metadata": {
        "color": "red",
        "count": 10
      }
    }
  ]
}

响应示例

HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Tue, 30 Dec 2025 08:46:33 GMT
Server: KS3
x-kss-request-id: 54a47bda18ac4e6e91de369add54218***

错误码

HTTP 状态码	错误码	描述	典型触发场景
400	ValidationException	请求不合法	请求体非法；`vectors` 为空或超过 500 条；`key` 为空、超过 1024 字符、非 UTF-8 或批内重复；`data.float32` 缺失或维度与索引不一致；`metadata` 超过 40KB、可过滤部分超过 2KB、键个数超过 10 个或值类型不合法；资源标识冲突或缺失。
402	ServiceQuotaExceededException	请求超过服务配额	写入后单个索引的向量总数超过配额上限（默认 5000 万）。
403	AccessDeniedException	访问被拒绝	无 `ks3:PutVectors` 权限，或被桶策略拒绝。
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."}]}

文档导读

上一篇：向量相关

下一篇：Get Vectors

纯净模式常规模式

纯净模式

点击可全屏预览文档内容