Object Storage Service：QueryVectors

許可權說明

阿里雲帳號預設擁有全部許可權。阿里雲帳號下的RAM使用者或RAM角色預設沒有任何許可權，需要阿里雲帳號或帳號管理員通過RAM Policy概述或Bucket Policy授予操作許可權。

請求文法

向量索引剛剛建立後的30秒內，QueryVectors的召回率較低。PutVectors寫入資料後，2-3秒左右之後可通過QueryVectors查詢到資料。

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
}

要求標頭

此介面僅涉及公用要求標頭。更多資訊，請參見公用HTTP頭定義。

請求參數

// 簡單等值（省略操作符時預設使用 $eq）
{"category": "finance"}

// 顯式等值 / 不等
{"category": {"$eq": "finance"}}
{"category": {"$ne": "archived"}}

// 數值比較
{"created_year": {"$gt": 2023}}
{"created_year": {"$gte": 2024}}
{"created_year": {"$lt": 2026}}
{"created_year": {"$lte": 2025}}

// 數組匹配
{"language": {"$in": ["zh", "en"]}}
{"language": {"$nin": ["ja", "ko"]}}

// 存在性檢查
{"author": {"$exists": true}}

// 邏輯組合
{"$and": [{"category": {"$eq": "finance"}}, {"created_year": {"$gte": 2024}}]}
{"$or": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}
{"$nor": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}

// 同一欄位的多個條件（範圍）
{"score": {"$gte": 0.6, "$lte": 0.95}}

回應標頭

此介面僅涉及公用回應標頭。更多資訊，請參見公用HTTP頭定義。

響應元素

樣本

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
}

返回樣本

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

QueryVectors介面所對應的各語言SDK如下：

• 檢索Vectors（Python SDK V2）

• 檢索Vectors（Go SDK V2）

命令列工具ossutil

QueryVectors介面所對應的ossutil命令，請參見query-vectors。

錯誤碼