Gunakan QueryVectors untuk pencarian kesamaan vektor - Object Storage Service - Alibaba Cloud - Object Storage Service

Gunakan operasi QueryVectors untuk melakukan pencarian kemiripan vektor.

Catatan

QueryVectors melakukan pencarian kemiripan vektor pada indeks mode Standard. Untuk indeks mode Fusion, gunakan operasi QueryVectorsFusion sebagai gantinya. Untuk kompatibilitas mundur, jika skema indeks mode Fusion hanya mendefinisikan satu bidang vektor bernama float32, Anda tetap dapat menggunakan operasi QueryVectors untuk melakukan pencarian tersebut.

Permissions

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	Description
QueryVectors	`oss:QueryVectors`	Menanyakan data vektor.

Sintaksis Permintaan

Tingkat recall untuk panggilan QueryVectors mungkin rendah hingga 30 detik setelah indeks vektor dibuat. Data yang ditulis menggunakan operasi PutVectors akan tersedia untuk kueri dalam waktu sekitar 2 hingga 3 detik.

POST /?queryVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.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 permintaan 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 harus sesuai dengan dimensi indeks vektor.
filter	Container	No	N/A	Menyaring data berdasarkan metadata. Batasan berikut berlaku untuk filter metadata: Total ukuran metadata dalam satu filter tidak boleh melebihi 20 KB. Jumlah item metadata dalam satu filter tidak boleh melebihi 1.024. Kondisi filter 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	Number	Yes	10	Jumlah hasil paling mirip yang dikembalikan. Nilainya harus berupa bilangan bulat dari 1 hingga 500.

Operator Filter

Operator	Type	Description
`$eq`	String, Number, Boolean	Pencocokan eksak (untuk nilai tunggal). Saat digunakan pada metadata bertipe array, operator mengembalikan `true` jika nilainya cocok dengan salah satu elemen dalam array.
`$ne`	String, Number, Boolean	Mencocokkan nilai yang tidak sama dengan nilai yang ditentukan.
`$gt`	Number	Lebih besar dari.
`$gte`	Number	Lebih besar dari atau sama dengan.
`$lt`	Number	Kurang dari.
`$lte`	Number	Kurang dari atau sama dengan.
`$in`	Non-empty array of primitives	Mencocokkan nilai apa pun dalam array (mirip dengan operasi SQL `IN`).
`$nin`	Non-empty array of primitives	Tidak mencocokkan nilai apa pun dalam array (mirip dengan operasi SQL `NOT IN`).
`$exists`	Boolean	Memeriksa apakah kunci metadata ada.
`$and`	Non-empty array of filters	Menjalankan operasi logika AND pada array kondisi filter.
`$or`	Non-empty array of filters	Menjalankan operasi logika OR pada array kondisi filter.
`$nor`	Non-empty array of filters	Menjalankan operasi logika NOR pada array kondisi filter.

Contoh Filter

Berikut adalah contoh ekspresi filter umum. Jika operator tidak ditentukan, $eq digunakan secara default.

// Kesamaan sederhana (menggunakan $eq secara default saat operator dihilangkan)
{"category": "finance"}

// Kesamaan / ketidaksamaan eksplisit
{"category": {"$eq": "finance"}}
{"category": {"$ne": "archived"}}

// Perbandingan numerik
{"created_year": {"$gt": 2023}}
{"created_year": {"$gte": 2024}}
{"created_year": {"$lt": 2026}}
{"created_year": {"$lte": 2025}}

// Pencocokan array
{"language": {"$in": ["zh", "en"]}}
{"language": {"$nin": ["ja", "ko"]}}

// Pemeriksaan keberadaan
{"author": {"$exists": true}}

// Kombinasi logika
{"$and": [{"category": {"$eq": "finance"}}, {"created_year": {"$gte": 2024}}]}
{"$or": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}
{"$nor": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}

// Beberapa kondisi pada bidang yang sama (rentang)
{"score": {"$gte": 0.6, "$lte": 0.95}}

Response headers

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

Elemen Respons

Parameter	Type	Example	Description
vectors	Array of objects	/	Daftar hasil pencarian vektor.
key	String	doc-001	Kunci primary vektor. Node induk: vectors
distance	float32	0.25	Jarak kemiripan antara vektor yang dikembalikan dan vektor kueri. Nilai yang lebih kecil menunjukkan kemiripan yang lebih tinggi. Parameter ini hanya dikembalikan saat `returnDistance` diatur ke `true`. Node induk: vectors
metadata	Object	/	Metadata lengkap dari vektor. Parameter ini hanya dikembalikan saat `returnMetadata` diatur ke `true`. Node induk: vectors

Contoh

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

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

SDK

Operasi QueryVectors tersedia di SDK berikut:

ossutil CLI

Anda dapat menggunakan perintah query-vectors di tool baris perintah ossutil untuk menjalankan operasi ini.

Kode Error

Error code	HTTP status code	Description
VectorIndexParameterInvalid	400	Permintaan berisi parameter indeks vektor yang tidak valid.
MalformedJson	400	Format JSON pada badan permintaan tidak valid.
AccessDenied	403	Kemungkinan penyebab error ini meliputi: Permintaan tidak menyertakan informasi otentikasi pengguna. Anda tidak memiliki izin yang diperlukan untuk operasi ini.
NoSuchVectorIndex	404	Indeks vektor yang ditentukan tidak ada.
QpsLimitExceeded	503	Laju permintaan telah melebihi batas QPS. Permintaan Anda sedang dikendalikan alirannya.