使用PutVectors写入向量数据-对象存储-阿里云-对象存储(OSS)-阿里云帮助中心

注意事项

单个向量索引表最多可存储 20 亿行向量数据。
PutVectors 的 QPS 上限为 1000，单并发最大支持批量写入 500 条，所有并发批量最多写入 2500 条。

权限说明

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

API	Action	说明
PutVectors	`oss:PutVectors`	写入向量数据。

请求语法

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

{
   "indexName": "string",
   "vectors": [ 
      { 
         "data": {
            "float32":[float]
         },
         "key": "string",
         "metadata": {
             "key1": ["value1", "value2"],
             "key2": "value2"
         }
      }
   ]
}

请求头

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

请求参数

名称	数据类型	是否必选	示例值	描述
indexName	字符串	是	vectorindex1	索引名称。
vectors	容器	是	-	写入的向量数组，容器元素个数在1-500之间。
key	字符串	是	doc-001	写入向量主键，标识向量唯一值。限制： key相同则覆盖，但若在同一批次中key有重复则全部异常 key单值长度在1~1024字符之间 key需为utf8格式父节点：vectors
data	容器	是	-	向量内容。限制：向量的维度必须与向量索引配置的维度数量相匹配对于余弦距离度量，不允许出现零向量（所有元素均为零的向量）向量数据必须仅包含有效的浮点数值。不允许包含无效值，如 NaN（非数值）或无穷大（Infinity）父节点：vectors
float32	数值数组	是	[0.1, 0.2, 0.3]	向量数据，数据类型为float32。向量维度必须与索引定义的维度一致。使用余弦距离度量时，不允许出现零向量。父节点：data
metadata	容器	否	-	元数据。限制：总大小 <= 200KB 可过滤metadata限制：数量 ∈ [0, 100] 可过滤部分大小 <= 2KB 支持类型为 String、Number、Boolean、List 父节点：vectors

响应头

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

示例

Standard 模式

请求示例

POST /?putVectors 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

{
   "indexName": "vectorindex1",
   "vectors": [
      {
         "key": "doc-001",
         "data": {
            "float32": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      },
      {
         "key": "doc-002",
         "data": {
            "float32": [0.6, 0.7, 0.8, 0.9, 1.0]
         },
         "metadata": {
             "category": ["technology", "database"],
             "title": "Advanced Database Indexing"
         }
      }
   ]
}

返回示例

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

Fusion 模式

说明

Fusion 模式索引的 data 使用创建索引时在 Schema 中定义的向量字段名（而非 Standard 模式使用的固定向量字段名 float32），且支持写入多个向量字段。

请求示例

POST /?putVectors 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

{
   "indexName": "vectorindex1",
   "vectors": [
      {
         "key": "doc-001",
         "data": {
            "vector_field_name_1": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      },
      {
         "key": "doc-002",
         "data": {
            "vector_field_name_1": [0.1, 0.2, 0.3, 0.4, 0.5],
            "vector_field_name_2": [0.6, 0.7, 0.8, 0.9, 1.0]
         },
         "metadata": {
             "category": ["technology", "database"],
             "title": "Advanced Database Indexing"
         }
      }
   ]
}

返回示例

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

SDK

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

命令行工具ossutil

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

错误码

错误码	HTTP状态码	描述
VectorIndexParameterInvalid	400	请求中提供的向量索引参数不合法，或单张向量 Index 表存储超过 5000 万行向量数据。
MalformedJson	400	请求体中的 JSON 格式不符合规范。
AccessDenied	403	返回该错误的可能原因如下：发起请求时没有传入用户验证信息。没有操作权限。
NoSuchVectorIndex	404	指定的向量索引不存在。
QpsLimitExceeded	503	QPS 限流（请求速率受限）。当 HTTP 状态码为 5xx 时，可能在同一批请求中只有部分数据写入成功，写入不具备原子性。