Gunakan PutVectors untuk menulis data vektor ke indeks vektor - Object Storage Service

Anda dapat memanggil operasi PutVectors untuk menulis data vektor ke dalam indeks.

Catatan penggunaan

Satu permintaan PutVectors dapat menulis hingga 500 vektor dan mendukung maksimal 5 permintaan per detik (QPS).

Izin

Akun Alibaba Cloud memiliki semua izin secara default. Namun, pengguna Resource Access Management (RAM) dan Peran RAM tidak memiliki izin secara default. Pemilik Akun Alibaba Cloud atau administrator harus memberikan izin operasi melalui Kebijakan RAM atau kebijakan bucket.

API	Action	Deskripsi
PutVectors	`oss:PutVectors`	Menulis data vektor.

Sintaksis permintaan

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

Header permintaan

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

Parameter permintaan

Nama	Tipe data	Wajib	Contoh	Deskripsi
indexName	String	Ya	vectorindex1	Nama indeks.
vectors	Kontainer	Ya	-	Array vektor yang akan ditulis. Jumlah elemen dalam kontainer harus antara 1 hingga 500.
key	String	Ya	doc-001	Kunci primary yang secara unik mengidentifikasi vektor. Batasan: Jika kunci sudah ada, vektor akan ditimpa. Jika terdapat kunci duplikat dalam batch yang sama, error akan dikembalikan untuk semua entri. Panjang kunci harus antara 1 hingga 1.024 karakter. Kunci harus dalam format UTF-8. Node induk: vectors
data	Kontainer	Ya	-	Isi vektor. Batasan: Jumlah dimensi vektor harus sesuai dengan jumlah dimensi yang dikonfigurasi untuk indeks vektor. Untuk ukuran jarak cosine, vektor nol (vektor yang semua elemennya bernilai nol) tidak diperbolehkan. Data vektor hanya boleh berisi bilangan titik mengambang yang valid. Nilai tidak valid seperti NaN (Not a Number) atau Infinity tidak diperbolehkan. Node induk: vectors
float32	Array angka	Ya	[0.1, 0.2, 0.3]	Data vektor bertipe float32. Jumlah dimensi vektor harus sesuai dengan jumlah dimensi yang ditentukan untuk indeks. Vektor nol tidak diperbolehkan saat Anda menggunakan ukuran jarak cosine. Node induk: data
metadata	Kontainer	Tidak	-	Metadata. Batasan: Ukuran total: ≤ 40 KB Batasan untuk metadata yang dapat difilter: Panjang: 0 hingga 10 Ukuran bagian yang dapat difilter: ≤ 2 KB Tipe yang didukung: string atau array string. Node induk: vectors

Header respons

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

Contoh

Contoh permintaan

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

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

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

SDK

SDK berikut mendukung operasi PutVectors:

Antarmuka baris perintah ossutil

Untuk informasi tentang perintah ossutil untuk operasi PutVectors, lihat put-vectors.

Kode error

Kode error	Kode status HTTP	Deskripsi
VectorIndexParameterInvalid	400	Parameter indeks vektor yang diberikan dalam permintaan tidak valid, atau satu tabel indeks vektor menyimpan lebih dari 50 juta baris data vektor.
MalformedJson	400	Format JSON dalam badan permintaan tidak valid.
AccessDenied	403	Kemungkinan penyebab error ini: Informasi autentikasi pengguna tidak disertakan dalam permintaan. Anda tidak memiliki izin yang diperlukan untuk operasi ini.
NoSuchVectorIndex	404	Indeks vektor yang ditentukan tidak ada.
QpsLimitExceeded	503	Jumlah permintaan per detik (QPS) melebihi batas. Jika kode status HTTP adalah 5xx, hanya sebagian data dalam batch yang sama mungkin berhasil ditulis. Operasi penulisan tidak menjamin atomicity.