PutVectorIndexFusion - Object Storage Service - Alibaba Cloud Documentation Center

Gunakan operasi PutVectorIndexFusion untuk membuat indeks vektor dalam mode Fusion di bucket vektor.

Catatan

Mode Fusion saat ini berada dalam pratinjau undangan dan hanya tersedia di wilayah Indonesia (Jakarta). Untuk membuat indeks vektor dalam Mode Standar, lihat PutVectorIndex.

Catatan penggunaan

Indeks mode Fusion menggunakan skema untuk menentukan tipe dan kemampuan pengambilan setiap bidang, serta mendukung berbagai kemampuan pengambilan seperti pencarian vektor, pemfilteran skalar, dan pencarian teks penuh. Indeks mode Standar dan mode Fusion dapat berdampingan dalam bucket vektor yang sama.
Jika permintaan berisi parameter yang tidak didukung oleh server, error akan dikembalikan.
Operasi pembuatan akan sepenuhnya berhasil atau sepenuhnya gagal.

Izin

Secara default, Akun Alibaba Cloud memiliki izin penuh, sedangkan pengguna RAM atau peran RAM tidak memiliki izin apa pun. Pemilik Akun Alibaba Cloud atau administrator harus memberikan izin melalui RAM policy atau bucket policy.

API	Action	Deskripsi
PutVectorIndexFusion	`oss:PutVectorIndexFusion`	Membuat indeks vektor dalam mode Fusion.

Sintaksis permintaan

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"
         }
      ]
   }
}

Header permintaan

Operasi ini hanya menggunakan header permintaan umum. Untuk informasi selengkapnya, lihat Header HTTP umum.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi	Contoh
indexName	String	Ya	Nama indeks. Anda dapat menyesuaikannya sendiri. Harus unik secara global dalam bucket vektor dan panjangnya antara 1 hingga 63 karakter. Hanya boleh berisi huruf dan angka, serta harus dimulai dengan huruf.	vectorindex1
mode	String	Ya	Mode indeks. Tetapkan nilainya ke fusion untuk membuat indeks mode Fusion.	fusion
schemaConfiguration	Object	Ya	Kontainer untuk konfigurasi skema. Konfigurasi apa pun yang tidak didukung oleh server akan mengembalikan error.	-
fields	Array of objects	Ya	Konfigurasi bidang skema. Batasan berikut berlaku: Jumlah total bidang tidak boleh melebihi 100. Jumlah bidang vektor tidak boleh melebihi 3. Jumlah bidang dengan tokenisasi aktif tidak boleh melebihi 8. Bidang skalar lainnya menghabiskan kuota yang tersisa. Harus terdapat setidaknya satu bidang dengan type=vector. Parent node: schemaConfiguration	-
fields.name	String	Ya	Nama bidang. Harus unik dalam satu indeks dan panjangnya antara 1 hingga 63 karakter. Dapat berisi huruf besar dan kecil, angka, serta garis bawah (_), dan harus dimulai dengan huruf. Parent node: fields	vector_1
fields.type	String	Ya	Tipe bidang. Nilai yang valid: vector: vektor. double: bilangan titik mengambang. long: bilangan bulat. bool: nilai Boolean. string: string. Anda dapat mengaktifkan tokenisasi untuk mendukung pencarian teks penuh. ip: alamat IP. geoPoint: koordinat titik geografis, dalam format "latitude,longitude", dengan latitude terlebih dahulu lalu longitude. Rentang latitude adalah [-90,+90] dan rentang longitude adalah [-180,+180]. Contohnya: 35.8,-45.91. Parent node: fields	vector

Parameter yang didukung oleh setiap tipe bidang

Tipe bidang	Parameter	Tipe	Default	Deskripsi	Wajib
vector	dataType	String	-	Tipe data vektor. Nilai ini tetap dan tidak dapat dipilih: float32 (floating-point).	Ya
	dimension	Integer	-	Dimensi vektor. Hanya dimensi 1 hingga 4096 yang didukung.	Ya
	distanceMetric	String	-	Metrik jarak. Nilai yang valid: euclidean: Jarak Euclidean. cosine: jarak cosine. ip: jarak inner product.	Ya
double	isArray	Boolean	false	Apakah bidang tersebut merupakan array. Array mendukung maksimal 128 elemen. Nilai seperti NaN dan Infinity positif atau negatif tidak didukung.	Tidak
long	isArray	Boolean	false	Apakah bidang tersebut merupakan array. Array mendukung maksimal 128 elemen.	Tidak
ip	isArray	Boolean	false	Apakah bidang tersebut merupakan array. Array mendukung maksimal 128 elemen.	Tidak
string	isArray	Boolean	false	Apakah bidang tersebut merupakan array. Batasan berikut berlaku: Array mendukung maksimal 512 elemen. Satu elemen string maksimal 4 KB, dan total semua elemen array maksimal 64 KB. Array tidak didukung ketika tokenisasi (text) diaktifkan untuk bidang tersebut. Array tidak didukung ketika bidang digunakan sebagai kunci partisi (isPartitionKey).	Tidak
	isPartitionKey	Boolean	false	Apakah bidang tersebut digunakan sebagai kunci partisi. Secara default, hash(vector key) digunakan untuk menentukan partisi target saat menulis. Setelah dikonfigurasi, hash(partitionKey) digunakan untuk menentukan partisi target saat menulis. Hanya satu bidang string yang dapat ditetapkan sebagai kunci partisi.	Tidak
	exactMatch	Boolean	true	Apakah mendukung kueri exact-match (tidak ditokenisasi). Misalnya, jika bidang field_a ditulis dengan "abcd123", kueri mendukung pemfilteran pada field_a="abcd123". Saat exactMatch diaktifkan, satu string maksimal 4 KB. Nilai default dan batasannya sebagai berikut: Secara default, bidang string memiliki exactMatch=true dan text.enabled=false. Ketika isPartitionKey=true, exactMatch harus true, dan tokenisasi teks tidak dapat diaktifkan. Ketika text.enabled=true, exactMatch harus secara eksplisit diatur ke true atau false. Setidaknya salah satu dari text atau exactMatch harus diaktifkan. Ketika isArray maupun isPartitionKey tidak digunakan, keduanya dapat diaktifkan secara bersamaan.	Tidak
	text.enabled	Boolean	false	Apakah tokenisasi diaktifkan. Setelah tokenisasi diaktifkan, operator pencarian teks penuh didukung. Batasan berikut berlaku untuk tokenisasi: Setelah tokenisasi diaktifkan, satu string maksimal 64 KB. Ketika exactMatch juga diaktifkan, satu string maksimal 4 KB. Bidang string dengan tokenisasi aktif tidak mendukung array. text adalah node induk dari bidang tokenisasi, di mana parameter seperti analyzer dan analyzerParameters dapat dikonfigurasi.	Tidak
	text.analyzer	String	standard	Tipe alat analisis. Nilai yang valid: standard (default, dapat dihilangkan): alat analisis standar, yang memisahkan teks Inggris berdasarkan kata dan teks Tionghoa berdasarkan karakter. split: tokenisasi berbasis delimiter, yang memungkinkan Anda menyesuaikan hasil tokenisasi.	Tidak

Parameter alat analisis (text.analyzerParameters)

Parameter yang didukung oleh setiap alat analisis adalah sebagai berikut:

alat analisis standard:
- caseSensitive: apakah pencocokan peka huruf besar/kecil. Nilai default adalah false, sehingga semua huruf Inggris diubah menjadi huruf kecil. Untuk menjaga sensitivitas huruf besar/kecil, atur ke true.
- delimitWord: untuk kata yang menggabungkan huruf dan angka, apakah huruf dan angka tersebut dipisahkan. Nilai default adalah false, artinya angka dan huruf tidak dipisah. Ketika diatur ke true, misalnya "iphone6" dipisah menjadi "iphone" dan "6".
alat analisis split:
- caseSensitive: sama seperti alat analisis standard.
- delimiter: delimiter khusus. Parameter ini wajib dan tidak memiliki nilai default. Nilai yang valid: spasi (" "), garis vertikal ("|"), tanda hubung ("-"), garis bawah ("_"), dan koma (",").

Header respons

Operasi ini hanya menggunakan header respons umum. Untuk informasi selengkapnya, lihat Header HTTP umum.

Contoh

Catatan

Nilai dan dimensi vektor dalam contoh berikut hanya menggambarkan struktur. Dalam pemanggilan aktual, panjang vektor harus persis sesuai dengan dimension yang dideklarasikan saat indeks dibuat. Jika tidak, error parameter tidak valid akan dikembalikan.

Contoh lengkap (semua tipe bidang)

Contoh permintaan

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": " "
               }
            }
         }
      ]
   }
}

Contoh respons

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

Skema minimal: satu bidang vektor

Contoh permintaan

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"
      }
    ]
  }
}

Vektor ganda: teks, gambar, dan video (multimodal)

Contoh permintaan

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"
      }
    ]
  }
}

Pencarian teks penuh: alat analisis standard

Contoh permintaan

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"
      }
    ]
  }
}

Kunci partisi: basis pengetahuan RAG multi-penyewa

Contoh permintaan

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"
      }
    ]
  }
}

Kode error

Kode error	Kode status HTTP	Deskripsi
VectorIndexParameterInvalid	400	Parameter indeks vektor yang diberikan dalam permintaan tidak valid.
MalformedJson	400	Badan permintaan tidak dalam format JSON yang valid.
VectorBucketIndexExceedLimit	400	Jumlah indeks yang dibuat telah mencapai batas atas. Satu bucket vektor dapat berisi hingga 100 indeks vektor.
AccessDenied	403	Akses ditolak. Kemungkinan penyebab: Permintaan tidak menyertakan informasi otentikasi yang diperlukan. Anda tidak memiliki izin yang diperlukan untuk melakukan operasi ini.
VectorBucketIndexAlreadyExist	409	Nama indeks yang ditentukan sudah ada dan tidak dapat dibuat lagi.