金山云-文档中心-Create Index

对象存储(KS3)

查看更多结果

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

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

API文档

向量存储桶（KS3 Vectors）

索引相关

Create Index

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



描述

在向量存储桶中创建向量索引。使用此接口，您必须是这个 Bucket 的拥有者或具有 ks3:CreateIndex 权限。

1.单个向量 Bucket 中最多可创建 100 张向量索引。

2.创建索引时指定的 dataType、dimension、distanceMetric、metadataConfiguration 在创建后不可更改。

请求

请求语法

POST /CreateIndex HTTP/1.1
Host: ks3vectors-cn-beijing.ksyuncs.com
Authorization: authorization string
Date: Mon, 10 Dec 2025 12:49:14 GMT
Content-type: application/json

{
  "vectorBucketName": "string",
  "indexName": "string",
  "dataType": "string",
  "dimension":integer,
  "distanceMetric": "string",
  "metadataConfiguration": {
    "nonFilterableMetadataKeys": ["string"]
  }

可通过向量桶名称或向量桶 KRN 指定目标向量桶，vectorBucketName 与 vectorBucketKrn 严格二选一。同时提供返回 400 VectorBucketNameAndArnConflict，都不提供返回 400 VectorBucketInfoMissing

请求头

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

请求体

{
  "vectorBucketName": "example-bucket",
  "indexName": "exampleindex",
  "dataType": "float32",
  "dimension": 1024,
  "distanceMetric": "euclidean",
  "metadataConfiguration": {
    "nonFilterableMetadataKeys": ["key_c", "key_d"]
  }
}

使用向量桶 KRN 时，请求体为：

{
  "vectorBucketKrn": "krn:ksc:ks3vectors:cn-beijing:103735000000:bucket/example-bucket",
  "indexName": "exampleindex",
  "dataType": "float32",
  "dimension": 1024,
  "distanceMetric": "euclidean",
  "metadataConfiguration": {
    "nonFilterableMetadataKeys": ["key_c", "key_d"]
  }
}

名称	数据类型	是否必选	描述
indexName	string	是	索引名称在 Vector Bucket 内全局唯一，长度 3~63 字符仅支持小写字母与数字，首字母必须为字母
dataType	string	是	向量数据类型，当前仅支持float32
dimension	integer	是	向量维度，支持 2~4096 维
distanceMetric	string	是	距离度量函数，用于相似性搜索的距离度量。可选值: euclidean：欧氏距离 cosine：余弦距离
metadataConfiguration	object	否	向量索引的元数据配置的容器，仅支持填写非过滤元数据
nonFilterableMetadataKeys	string[]	否	不可用于筛选的元数据键列表。有如下输入限制：元数据个数为最多支持选择10个每个元数据主键名称的长度 1~63 字节，支持大小写字母、数字和下划线(_)，且起始字符只能是大小写字母和下划线(_) 父节点：metadataConfiguration
vectorBucketKrn	string	否，与 vectorBucketName 必选其一	向量存储桶的 KRN
vectorBucketName	string	否，与 vectorBucketKrn 必选其一	向量存储桶的名称

响应

响应头

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

响应体

创建成功，返回 application/json 数据，包含向量索引资源信息:

名称	父节点	数据类型	描述
indexKrn	无	string	向量索引资源名称 KRN，格式 `krn:ksc:ks3vectors:<region>:<accountid>:bucket/<bucketname>/index/<indexname>`

示例

请求示例

POST /CreateIndex HTTP/1.1
Host: ks3vectors-cn-beijing.ksyuncs.com
Authorization: authorization string
Date: Mon, 10 Dec 2025 12:49:14 GMT
Content-Type: application/json

{
  "vectorBucketName": "example-bucket",
  "indexName": "exampleindex",
  "dataType": "float32",
  "dimension": 1024,
  "distanceMetric": "euclidean",
  "metadataConfiguration": {
    "nonFilterableMetadataKeys": ["key_c", "key_d"]
  }
}

响应示例

HTTP/1.1 200 OK
Content-Type: application/json
Date: Tue, 19 Jul 2025 09:14:23 GMT
Server: KS3
x-kss-request-id: 54a47bda18ac4e6e91de369add54218***
{
  "indexKrn": "krn:ksc:ks3vectors:cn-beijing:103735000000:bucket/example-bucket/index/exampleindex"
}

错误码

HTTP 状态码	错误码	描述	典型触发场景
400	ValidationException	请求参数不合法	`indexName` 不符合命名规则；`dimension` 超出 2~4096；`dataType` 或 `distanceMetric` 非法；桶标识同时提供或缺失；传入索引 ARN/KRN。
402	ServiceQuotaExceededException	超过服务配额	单个桶的索引数量达到上限（默认 100）。
403	AccessDeniedException	访问被拒绝	非桶拥有者且无 `ks3:CreateIndex` 权限。
404	NotFoundException	资源不存在	指定的向量桶不存在。
409	ConflictException	资源冲突	同名索引已存在（`VectorBucketIndexAlreadyExist`），或并发操作冲突（`VectorIndexOperationConflict`）。
500	InternalServerException	服务内部错误	服务内部异常。

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

错误响应体格式如下：

{
  "message": "The indexName is invalid.",
  "fieldList": [
    {
      "path": "/indexName",
      "message": "..."
    }
  ]
}

fieldList 仅校验类错误（ValidationException）携带；其他错误只返回 message。

文档导读

上一篇：索引相关

下一篇：Get Index

纯净模式常规模式

纯净模式

点击可全屏预览文档内容