PutVectorIndexFusion - Object Storage Service

注意事項

Fusion 模式索引通過 Schema 定義各欄位的類型與檢索能力，支援向量檢索、標量過濾、全文檢索索引等多種檢索能力。同一向量Bucket下可同時存在 Standard 模式與 Fusion 模式的索引。
請求中包含服務端不支援的參數時會直接報錯。
建立操作只能全部成功或全部失敗。

許可權說明

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

API	Action	說明
PutVectorIndexFusion	`oss:PutVectorIndexFusion`	建立Fusion模式的向量索引。

請求文法

POST /?putVectorIndexFusion 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",
   "mode": "fusion",
   "schemaConfiguration": {
      "fields": [
         {
            "name": "string",
            "type": "string"
         }
      ]
   }
}

要求標頭

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

請求參數

名稱	資料類型	是否必選	描述	樣本值
indexName	字串	是	索引名稱，使用者可自訂。在向量Bucket內全域唯一，長度 1～63 字元。只允許字母和數字，首字母必須以字母開頭。	vectorindex1
mode	字串	是	索引模式，建立Fusion模式索引時取值為 fusion。	fusion
schemaConfiguration	對象	是	Schema 配置的容器。服務端不支援的配置將直接報錯。	-
fields	對象數組	是	Schema 欄位配置。限制如下：總欄位數不超過 100 個。向量欄位數不超過 3 個。開啟分詞的欄位數不超過 8 個。其它標量欄位佔用剩餘配額。至少存在一個 type=vector 的欄位。父節點：schemaConfiguration	-
fields.name	字串	是	欄位名。單個索引內唯一，長度 1～63 字元。支援大小寫字母、數字和底線（_），首字母必須以字母開頭。父節點：fields	vector_1
fields.type	字串	是	欄位類型，取值： vector：向量。 double：浮點數。 long：整數。 bool：布爾。 string：字串，可開啟分詞以支援全文檢索索引。 ip：網路通訊協定地址。 geoPoint：位置點座標資訊，格式為“緯度,經度”，緯度在前、經度在後，緯度範圍為 [-90,+90]，經度範圍為 [-180,+180]。例如 35.8,-45.91。父節點：fields	vector

不同欄位類型支援的參數

欄位類型	名稱	資料類型	預設值	描述	是否必選
vector	dataType	字串	-	向量資料類型，使用者不可選，取值：float32（浮點型）。	是
	dimension	整型	-	向量維度，僅支援 1～4096 維。	是
	distanceMetric	字串	-	距離度量函數，取值： euclidean：歐氏距離。 cosine：餘弦距離。 ip：內積距離。	是
double	isArray	布爾值	false	是否為數組，數組最大支援 128 個元素。不支援 NaN、正負 Infinity 等值。	否
long	isArray	布爾值	false	是否為數組，數組最大支援 128 個元素。	否
ip	isArray	布爾值	false	是否為數組，數組最大支援 128 個元素。	否
string	isArray	布爾值	false	是否為數組，限制如下：數組最大支援 512 個元素。單個 string 元素最大 4 KB，數組所有元素整體最大 64 KB。該欄位開啟分詞（text）能力時，不支援數組。該欄位開啟分區鍵（isPartitionKey）時，不支援數組。	否
	isPartitionKey	布爾值	false	是否作為分區鍵。預設使用 hash(vector key) 定址到對應分區進行寫入；配置後使用 hash(partitionKey) 定址到對應分區進行寫入。僅支援將一個 string 類型欄位設定為分區鍵。	否
	exactMatch	布爾值	true	是否支援精確匹配（不分詞）的查詢能力。例如某欄位 field_a 寫入 "abcd123"，則查詢支援 field_a="abcd123" 的過濾能力。開啟 exactMatch 後，單個 string 最大 4 KB。預設值與限制如下： string 欄位預設 exactMatch=true、text.enabled=false。當 isPartitionKey=true 時，exactMatch 必須為 true，且不允許開啟 text 分詞。當 text.enabled=true 時，exactMatch 必須顯式指定 true 或 false。 text 與 exactMatch 至少開啟一個。在無 isArray、isPartitionKey 功能時，兩者允許同時開啟。	否
	text.enabled	布爾值	false	是否開啟分詞。開啟分詞後可支援全文檢索索引運算元。分詞能力限制如下：開啟分詞後，單個 string 最大 64 KB；同時開啟 exactMatch 時，單個 string 最大 4 KB。開啟分詞的 string 欄位不支援數組。 text 為分詞欄位的父節點，其下可配置 analyzer、analyzerParameters 等參數。	否
	text.analyzer	字串	standard	分詞器類型，取值： standard（預設值，允許不填）：標準分詞器，英文按單詞切分、中文按單字切分。 split：分隔字元分詞，使用者可自訂分詞效果。	否

分詞器參數（text.analyzerParameters）

不同分詞器支援的參數如下：

standard 分詞器：
- caseSensitive：是否大小寫敏感。預設值 false，此時所有英文字母會轉換為小寫。如需保持大小寫敏感，可設定為 true。
- delimitWord：對於英文和數字串連在一起的單詞，是否分割英文和數字。預設值 false，表示數字和英文不拆分。設定為 true 時，例如 “iphone6” 會被拆分成 “iphone” 和 “6”。
split 分詞器：
- caseSensitive：同 standard 分詞器。
- delimiter：自訂分隔字元，必填，無預設值。可選值：空白字元（" "）、豎劃線（"|"）、短橫杠（"-"）、底線（"_"）、英文逗號（","）。

回應標頭

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

樣本

說明

以下樣本中的向量取值與維度僅用於示意結構，實際調用時向量長度必須與建表時聲明的 dimension 嚴格一致，否則會報參數非法。

綜合樣本（全欄位類型）

請求樣本

POST /?putVectorIndexFusion 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",
   "mode": "fusion",
   "schemaConfiguration": {
      "fields": [
         {
            "name": "vector_1",
            "type": "vector",
            "dataType": "float32",
            "dimension": 1024,
            "distanceMetric": "euclidean"
         },
         {
            "name": "vector_2",
            "type": "vector",
            "dataType": "float32",
            "dimension": 512,
            "distanceMetric": "cosine"
         },
         {
            "name": "timestamps",
            "type": "long",
            "isArray": true
         },
         {
            "name": "price",
            "type": "double"
         },
         {
            "name": "ip",
            "type": "ip"
         },
         {
            "name": "location",
            "type": "geoPoint"
         },
         {
            "name": "tag",
            "type": "string"
         },
         {
            "name": "user_id",
            "type": "string",
            "isPartitionKey": true
         },
         {
            "name": "tags",
            "type": "string",
            "isArray": true
         },
         {
            "name": "title_1",
            "type": "string",
            "exactMatch": true,
            "text": {
               "enabled": true,
               "analyzer": "standard",
               "analyzerParameters": {
                  "caseSensitive": true,
                  "delimitWord": false
               }
            }
         },
         {
            "name": "title_2",
            "type": "string",
            "exactMatch": false,
            "text": {
               "enabled": true,
               "analyzer": "split",
               "analyzerParameters": {
                  "caseSensitive": true,
                  "delimiter": " "
               }
            }
         }
      ]
   }
}

返回樣本

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

最小 Schema：單向量欄位

請求樣本

POST /?putVectorIndexFusion 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": "docindex",
  "mode": "fusion",
  "schemaConfiguration": {
    "fields": [
      {
        "name": "content_vector",
        "type": "vector",
        "dataType": "float32",
        "dimension": 1024,
        "distanceMetric": "cosine"
      }
    ]
  }
}

多向量：圖文視三路多模態

請求樣本

POST /?putVectorIndexFusion 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": "multimodalindex",
  "mode": "fusion",
  "schemaConfiguration": {
    "fields": [
      {
        "name": "text_vector",
        "type": "vector",
        "dataType": "float32",
        "dimension": 1024,
        "distanceMetric": "cosine"
      },
      {
        "name": "image_vector",
        "type": "vector",
        "dataType": "float32",
        "dimension": 512,
        "distanceMetric": "euclidean"
      },
      {
        "name": "video_vector",
        "type": "vector",
        "dataType": "float32",
        "dimension": 256,
        "distanceMetric": "ip"
      },
      {
        "name": "title",
        "type": "string",
        "exactMatch": true,
        "text": {
          "enabled": true,
          "analyzer": "standard"
        }
      },
      {
        "name": "duration",
        "type": "long"
      }
    ]
  }
}

全文檢索索引：standard 標準分詞器

請求樣本

POST /?putVectorIndexFusion 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": "kbindex",
  "mode": "fusion",
  "schemaConfiguration": {
    "fields": [
      {
        "name": "chunk_vector",
        "type": "vector",
        "dataType": "float32",
        "dimension": 1024,
        "distanceMetric": "cosine"
      },
      {
        "name": "title",
        "type": "string",
        "exactMatch": true,
        "text": {
          "enabled": true,
          "analyzer": "standard",
          "analyzerParameters": {
            "caseSensitive": false,
            "delimitWord": true
          }
        }
      },
      {
        "name": "body",
        "type": "string",
        "exactMatch": false,
        "text": {
          "enabled": true,
          "analyzer": "standard"
        }
      },
      {
        "name": "doc_id",
        "type": "string"
      },
      {
        "name": "year",
        "type": "long"
      },
      {
        "name": "status",
        "type": "string"
      },
      {
        "name": "updated_at",
        "type": "long"
      }
    ]
  }
}

分區鍵：多租戶 RAG 知識庫

請求樣本

POST /?putVectorIndexFusion 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": "tenantkbindex",
  "mode": "fusion",
  "schemaConfiguration": {
    "fields": [
      {
        "name": "chunk_vector",
        "type": "vector",
        "dataType": "float32",
        "dimension": 1024,
        "distanceMetric": "cosine"
      },
      {
        "name": "tenant_id",
        "type": "string",
        "isPartitionKey": true
      },
      {
        "name": "doc_id",
        "type": "string"
      },
      {
        "name": "content",
        "type": "string",
        "exactMatch": false,
        "text": {
          "enabled": true,
          "analyzer": "standard"
        }
      },
      {
        "name": "updated_at",
        "type": "long"
      }
    ]
  }
}

錯誤碼

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