QueryVectors - Object Storage Service

調用QueryVectors介面進行向量相似性檢索。

許可權說明

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

API	Action	說明
QueryVectors	`oss:QueryVectors`	查詢向量資料。

請求文法

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

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
}

要求標頭

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

請求參數

名稱	資料類型	是否必選	樣本值	描述
indexName	字串	是	vectorindex1	索引名稱。
queryVector	容器	是	不適用	查詢向量，維度必須與向量索引的維度相同。
filter	容器	否	不適用	通過中繼資料對查詢資料進行過濾。配置可過濾中繼資料時：單次過濾指令中可過濾中繼資料的累計長度不超過 64 KB；單次過濾指令中可過濾中繼資料項數量不超過 1024 個；過濾條件嵌套層級最多支援 8 層；
returnDistance	布爾值	否	false	是否返回相似距離。取值： true false（預設值）
returnMetadata	布爾值	否	false	是否返回中繼資料。取值： true false（預設值）
topK	數值	是	10	返回最相似的K個向量，支援1~30。

Filter操作符

操作符	支援類型	描述
`$eq`	String	精確匹配（用於單個值）。當與數群組類型的中繼資料進行比較時，如果輸入值能匹配數組中的任意一個元素，則返回true。
`$ne`	String	不等於
`$in`	String array	匹配數組中的任意一個值（類似於SQL的`IN`操作）
`$nin`	String array	不匹配數組中的任何一個值（類似於SQL的`NOT IN`操作）
`$exists`	Boolean	檢查中繼資料的key是否存在
`$and`	Non-empty array of filters	多條件判斷與（AND）
`$or`	Non-empty array of filters	多條件判斷或（OR）

回應標頭

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

響應元素

名稱	資料類型	樣本值	描述
vectors	對象數組	/	返迴向量列表。如果查詢的主鍵不存在，無報錯但不返回當前key結果。
key	字串	doc-001	向量主鍵。父節點：vectors
distance	float32	0.25	向量和查詢向量之間的相似距離，值越小說明越相似（僅當returnDistance為true時返回）。父節點：vectors
metadata	對象	/	全量中繼資料（僅當returnMetadata為true時返回）。父節點：vectors

樣本

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
}

返回樣本

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

錯誤碼

錯誤碼	HTTP狀態代碼	描述
VectorIndexParameterInvalid	400	請求中提供的向量索引參數不合法。
MalformedJson	400	請求體中的 JSON 格式不符合規範。
AccessDenied	403	返回該錯誤的可能原因如下：發起請求時沒有傳入使用者驗證資訊。沒有操作許可權。
NoSuchVectorIndex	404	指定的向量索引不存在。
QpsLimitExceeded	503	QPS 限流（請求速率受限）。