QueryVectors - Object Storage Service

Gunakan operasi QueryVectors untuk melakukan pencarian kesamaan vektor.

Izin

Akun Alibaba Cloud memiliki semua izin secara default. Pengguna Resource Access Management (RAM) atau Peran RAM tidak memiliki izin secara default. Administrator Akun Alibaba Cloud harus memberikan izin kepada Pengguna RAM atau Peran RAM melalui Kebijakan RAM atau Kebijakan Bucket.

API	Aksi	Deskripsi
QueryVectors	`oss:QueryVectors`	Menginterogasi data vektor.

Sintaks permintaan

Selama 30 detik setelah pembuatan indeks vektor, tingkat recall dari operasi QueryVectors rendah. Setelah menulis data dengan memanggil operasi PutVectors, data tersebut dapat di-query menggunakan operasi QueryVectors dalam waktu sekitar 2 hingga 3 detik.

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

{
   "filter": {
       "$and": [{
           "type": {
               "$in": ["comedy", "documentary"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    },
   "indexName": "string",
   "queryVector": {
       "float32":[float]
    },
   "returnDistance": boolean,
   "returnMetadata": boolean,
   "topK": int
}

Header permintaan

Operasi ini hanya menggunakan header permintaan umum. Untuk informasi lebih lanjut, lihat Header permintaan umum.

Parameter permintaan

Nama	Tipe data	Diperlukan	Contoh	Deskripsi
indexName	String	Ya	vectorindex1	Nama indeks.
queryVector	Container	Ya	N/A	Vektor query. Dimensi harus sama dengan dimensi indeks vektor.
filter	Container	Tidak	N/A	Memfilter data query berdasarkan metadata. Saat mengonfigurasi metadata yang dapat difilter: Total panjang metadata yang dapat difilter dalam satu instruksi filter tidak boleh melebihi 64 KB. Jumlah item metadata yang dapat difilter dalam satu instruksi filter tidak boleh melebihi 1.024. Kondisi filter dapat bersarang hingga kedalaman 8 level.
returnDistance	Boolean	Tidak	false	Menentukan apakah akan mengembalikan jarak kesamaan. Nilai valid: true false (default)
returnMetadata	Boolean	Tidak	false	Menentukan apakah akan mengembalikan metadata. Nilai valid: true false (default)
topK	Number	Ya	10	Jumlah vektor paling mirip yang akan dikembalikan. Nilainya harus bilangan bulat dari 1 hingga 30.

Operator filter

Operator	Tipe yang didukung	Deskripsi
`$eq`	String	Cocokkan persis untuk satu nilai. Saat dibandingkan dengan metadata tipe array, operator ini mengembalikan true jika nilai input cocok dengan elemen apa pun dalam array.
`$ne`	String	Tidak sama dengan
`$in`	Array string	Cocokkan nilai apa pun dalam array. Ini mirip dengan operasi `IN` dalam SQL.
`$nin`	Array string	Tidak cocok dengan nilai apa pun dalam array. Ini mirip dengan operasi `NOT IN` dalam SQL.
`$exists`	Boolean	Memeriksa apakah kunci metadata ada.
`$and`	Array filter non-kosong	Melakukan operasi logika AND pada beberapa kondisi.
`$or`	Array filter non-kosong	Melakukan operasi logika OR pada beberapa kondisi.

Header respons

Operasi ini hanya menggunakan header respons umum. Untuk informasi lebih lanjut, lihat Header respons umum.

Elemen respons

Nama	Tipe data	Contoh	Deskripsi
vectors	Array objek	/	Daftar vektor yang dikembalikan. Jika kunci utama yang diquery tidak ada, tidak ada kesalahan yang dilaporkan dan hasil untuk kunci itu tidak dikembalikan.
key	String	doc-001	Kunci utama vektor. Node induk: vectors
distance	float32	0,25	Jarak kesamaan antara vektor dan vektor query. Nilai yang lebih kecil menunjukkan kesamaan yang lebih tinggi. Parameter ini hanya dikembalikan ketika returnDistance disetel ke true. Node induk: vectors
metadata	Objek	/	Semua metadata. Parameter ini hanya dikembalikan ketika returnMetadata disetel ke true. Node induk: vectors

Contoh

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

{
   "filter": {
       "$and": [{
           "category": {
               "$in": ["technology", "science"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    },
   "indexName": "vectorindex1",
   "queryVector": {
       "float32": [0.15, 0.25, 0.35, 0.45, 0.55]
    },
   "returnDistance": true,
   "returnMetadata": true,
   "topK": 5
}

Respons contoh

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

{
   "vectors": [ 
      { 
         "distance": 0.12,
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search",
             "year": "2020"
         }
      },
      { 
         "distance": 0.25,
         "key": "doc-003",
         "metadata": {
             "category": ["science"],
             "title": "Advanced Vector Operations",
             "year": "2020"
         }
      }
   ]
}

Kode kesalahan

Kode kesalahan	Kode status HTTP	Deskripsi
VectorIndexParameterInvalid	400	Parameter indeks vektor dalam permintaan tidak valid.
MalformedJson	400	Format JSON badan permintaan tidak valid.
AccessDenied	403	Kesalahan ini dikembalikan karena alasan berikut: Informasi otentikasi pengguna tidak termasuk dalam permintaan. Anda tidak memiliki izin yang diperlukan.
NoSuchVectorIndex	404	Indeks vektor yang ditentukan tidak ada.
QpsLimitExceeded	503	Pembatasan laju permintaan (QPS).