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

Panggil operasi PutVectors untuk menulis data vektor ke dalam indeks.

Catatan

Satu indeks vektor dapat menyimpan hingga 2 miliar baris data vektor.
Satu permintaan PutVectors dapat menulis hingga 500 vektor. Operasi ini mendukung hingga 5 permintaan per detik (QPS).

Izin

Secara default, Akun Alibaba Cloud memiliki izin penuh. Pengguna Resource Access Management (RAM) atau Peran RAM tidak memiliki izin secara default. Pemilik Akun Alibaba Cloud atau administrator harus memberikan izin 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-internal.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	container	Ya	-	Array vektor yang akan ditulis. Jumlah elemen dalam container harus antara 1 hingga 500.
key	string	Ya	doc-001	Kunci primary dari vektor. Kunci ini berfungsi sebagai nilai unik untuk vektor tersebut. Batasan: Jika kunci sudah ada, vektor akan ditimpa. Namun, jika terdapat kunci duplikat dalam batch yang sama, kesalahan akan dikembalikan untuk seluruh batch. Panjang satu kunci harus antara 1 hingga 1.024 karakter. Kunci harus dalam format UTF-8. Node induk: vectors
data	container	Ya	-	Isi vektor. Batasan: 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 of numbers	Ya	[0.1, 0.2, 0.3]	Data vektor. Tipe datanya adalah float32. Dimensi vektor harus konsisten dengan dimensi yang didefinisikan dalam indeks. Saat menggunakan ukuran jarak cosine, vektor nol tidak diperbolehkan. Node induk: data
metadata	container	Tidak	-	Metadata. Batasan: Ukuran total: ≤ 40 KB Batasan untuk metadata yang dapat difilter: Panjang harus dalam rentang 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-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",
   "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 tersedia untuk operasi PutVectors:

antarmuka baris perintah ossutil

Untuk perintah ossutil yang sesuai dengan operasi PutVectors, lihat put-vectors.

Kode kesalahan

Kode kesalahan	Kode status HTTP	Deskripsi
VectorIndexParameterInvalid	400	Parameter indeks vektor 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	Kesalahan ini dikembalikan karena alasan berikut: Informasi otentikasi pengguna tidak disertakan dalam permintaan. Izin yang diperlukan tidak tersedia.
NoSuchVectorIndex	404	Indeks vektor yang ditentukan tidak ada.
QpsLimitExceeded	503	Batas QPS terlampaui akibat pembatasan laju. Jika kode status HTTP adalah 5xx, hanya sebagian data dalam permintaan batch yang mungkin berhasil ditulis. Operasi penulisan tidak bersifat atomik.