PutVectorIndex - Object Storage Service

調用PutVectorIndex介面在向量儲存空間中建立向量索引。

注意事項

單個向量 Bucket 中最多建立 100 張向量索引
向量索引 PutVectorIndex 請求每秒最大支援 5 個。

許可權說明

阿里雲帳號預設擁有全部許可權。阿里雲帳號下的RAM使用者或RAM角色預設沒有任何許可權，需要阿里雲帳號或帳號管理員通過RAM Policy或Bucket Policy授予操作許可權。

API	Action	說明
PutVectorIndex	`oss:PutVectorIndex`	建立向量索引。

請求文法

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

{
   "dataType": "string",
   "dimension": int,
   "distanceMetric": "string",
   "indexName": "string",
   "metadata": { 
      "nonFilterableMetadataKeys": [string, string]
   }
}

要求標頭

此介面僅涉及公用要求標頭。更多資訊，請參見公用HTTP頭定義。

請求參數

名稱	資料類型	是否必選	樣本值	描述
dataType	字串	是	float32	向量資料類型，目前使用者不可選。預設值：float32。
dimension	數值	是	512	向量維度，支援1~4096維。預設為512。
distanceMetric	字串	是	euclidean	距離度量函數，可選值如下： euclidean：歐氏距離（預設值） cosine：餘弦距離
indexName	字串	是	vectorindex1	索引名稱，使用者可自訂，預設為空白。在 Vector Bucket 內全域唯一，長度 1 ～63 字元只允許字母和數字，首字母必須字母開頭
metadata	對象	否	-	中繼資料配置的容器，僅支援填寫非過濾中繼資料。
nonFilterableMetadataKeys	字串數組	否	["field1", "field2"]	非過濾中繼資料配置。有如下輸入限制：中繼資料個數為 1~10 個每個中繼資料主鍵名稱的長度 1~63 位元組，支援大小寫字母、數字和底線(_)，且起始字元只能是大小寫字母和底線(_) 父節點：metadata

回應標頭

此介面僅涉及公用回應標頭。更多資訊，請參見公用HTTP頭定義。

樣本

請求樣本

POST /?putVectorIndex HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.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

{
   "dataType": "float32",
   "dimension": 1024,
   "distanceMetric": "euclidean",
   "indexName": "vectorindex1",
   "metadata": { 
      "nonFilterableMetadataKeys": ["category", "timestamp"]
   }
}

返回樣本

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

錯誤碼

錯誤碼	HTTP狀態代碼	描述
VectorIndexParameterInvalid	400	請求中提供的向量索引參數不合法。
MalformedJson	400	請求體中的 JSON 格式不符合規範。
VectorBucketIndexExceedLimit	400	建立的索引數量已達到上限。單個向量 Bucket 最多允許建立 100 個向量索引。
AccessDenied	403	返回該錯誤的可能原因如下：發起請求時沒有傳入使用者驗證資訊。沒有操作許可權。
VectorBucketIndexAlreadyExist	409	指定的索引名稱已存在，無法重複建立。