Gunakan QueryVectors untuk pencarian kesamaan vektor - Object Storage Service

Panggil QueryVectors untuk melakukan pencarian kemiripan vektor.

Permissions

Secara default, Akun Alibaba Cloud memiliki izin penuh, sedangkan Pengguna RAM dan Peran RAM tidak memiliki izin apa pun. Untuk memberikan izin, pemilik Akun Alibaba Cloud atau administrator harus menggunakan RAM policy atau bucket policy.

API	Action	Description
QueryVectors	`oss:QueryVectors`	Menanyakan data vektor.

Sintaksis permintaan

Selama 30 detik pertama setelah indeks vektor dibuat, tingkat recall untuk QueryVectors rendah. Setelah Anda menulis data menggunakan PutVectors, data tersebut dapat diakses oleh 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
}

Request headers

Operasi ini hanya menggunakan Header HTTP umum. Untuk informasi selengkapnya, lihat Common HTTP headers.

Parameter permintaan

Parameter	Type	Required	Example	Description
indexName	String	Yes	vectorindex1	Nama indeks vektor.
queryVector	Container	Yes	N/A	Vektor kueri. Dimensi vektor harus sesuai dengan dimensi indeks vektor.
filter	Container	No	N/A	Memfilter hasil pencarian berdasarkan metadata. Batasan berikut berlaku: Ukuran total metadata dalam satu ekspresi filter tidak boleh melebihi 64 KB. Jumlah bidang metadata dalam satu ekspresi filter tidak boleh melebihi 1.024. `filter condition` dapat disarangkan hingga kedalaman 8 level.
returnDistance	Boolean	No	false	Menentukan apakah jarak kemiripan dikembalikan. Nilai yang valid: true false (default)
returnMetadata	Boolean	No	false	Menentukan apakah metadata dikembalikan. Nilai yang valid: true false (default)
topK	Integer	Yes	10	Jumlah hasil paling mirip yang dikembalikan. Nilainya harus antara 1 hingga 100.

Operator filter

Operator	Type	Description
`$eq`	String	Mencocokkan satu nilai. Jika bidang metadata berupa array, operator ini mencocokkan elemen mana pun dalam array tersebut.
`$ne`	String	Tidak sama dengan.
`$in`	String array	Mencocokkan nilai apa pun dalam array (mirip dengan operasi `IN` pada SQL)
`$nin`	String array	Tidak mencocokkan nilai apa pun dalam array (mirip dengan operasi `NOT IN` pada SQL)
`$exists`	Boolean	Memeriksa apakah kunci metadata ada.
`$and`	Non-empty array of filters	Menjalankan operasi logika AND pada array yang terdiri dari dua ekspresi filter atau lebih.
`$or`	Non-empty array of filters	Menjalankan operasi logika OR pada array yang terdiri dari dua ekspresi filter atau lebih.

Response headers

Operasi ini hanya menggunakan Header HTTP umum. Untuk informasi selengkapnya, lihat Common HTTP headers.

Elemen respons

Parameter	Type	Example	Description
vectors	Array of objects	/	Array objek vektor yang dikembalikan. Jika kunci primary vektor yang ditentukan tidak ada, objek tersebut dihilangkan dari respons dan tidak dilaporkan sebagai error.
key	String	doc-001	Kunci primary vektor. Node induk: vectors
distance	Float	0.25	Jarak kemiripan antara vektor hasil dan vektor kueri. Nilai yang lebih kecil menunjukkan kemiripan yang lebih tinggi. Parameter ini hanya dikembalikan ketika `returnDistance` diatur ke `true`. Node induk: vectors
metadata	Object	/	Metadata lengkap untuk vektor tersebut. Parameter ini hanya dikembalikan ketika `returnMetadata` diatur 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
}

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

SDKs

Operasi QueryVectors tersedia di SDK berikut:

Ossutil CLI

Perintah ossutil untuk operasi QueryVectors adalah query-vectors.

Kode error

Error code	HTTP status code	Description
VectorIndexParameterInvalid	400	Parameter indeks vektor yang diberikan dalam permintaan tidak valid.
MalformedJson	400	Badan permintaan tidak dalam format JSON yang valid.
AccessDenied	403	Error ini terjadi karena salah satu alasan berikut: Permintaan tidak menyertakan informasi otentikasi. Anda tidak memiliki izin yang diperlukan untuk operasi ini.
NoSuchVectorIndex	404	Indeks vektor yang ditentukan tidak ada.
QpsLimitExceeded	503	Jumlah kueri per detik (QPS) melebihi batas. Laju permintaan dikendalikan.