QueryVectorsFusion - Object Storage Service

注意事項

QueryVectorsFusion 用於 Fusion 模式索引的檢索。對於 Standard 模式索引的向量相似性檢索，請使用 QueryVectors 介面。
相比 QueryVectors 按距離（distance）返回，QueryVectorsFusion 按相關性得分（score）返回結果，score 越大表示相關性越高。
knn、query、retriever 分別對應向量檢索、標量與全文過濾、多路召回融合，可按需組合使用。當使用 retriever 時，請求中只允許同時攜帶 indexName、limit、partitionKeys、returnMetadata、returnMetadataFields 參數。
nextToken 僅在純 query（不含 knn、retriever）的檢索情境下支援翻頁。

許可權說明

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

API	Action	說明
QueryVectorsFusion	`oss:QueryVectorsFusion`	檢索Fusion模式的向量索引。

請求文法

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

{
   "indexName": "string",
   "knn": [
      {
         "field": "string",
         "queryVector": [0.1],
         "topK": 10
      }
   ],
   "returnMetadata": true
}

要求標頭

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

請求參數

名稱	資料類型	是否必選	描述	樣本值
indexName	字串	是	待檢索的索引名稱。	vectorindex1
knn	對象數組	否	向量檢索配置，支援對一個或多個向量欄位進行近似最近鄰檢索，最多配置 3 個。具體子參數請參見下文的“knn 參數”。	-
query	對象	否	標量過濾與全文檢索索引條件，通過過濾運算元表達。具體運算元請參見下文的“過濾運算元”。	-
retriever	對象	否	多路召回融合配置，用於將多路檢索結果按融合演算法合并排序。具體子參數請參見下文的“retriever 參數”。使用 retriever 時，請求中只允許同時攜帶 indexName、limit、partitionKeys、returnMetadata、returnMetadataFields。	-
returnMetadata	布爾值	否	是否返迴向量的中繼資料。預設值 false。	true
returnMetadataFields	字串數組	否	指定需要返回的中繼資料欄位名。不指定時返回全部中繼資料欄位。不支援指定向量欄位。	["price","tag"]
partitionKeys	字串數組	否	指定分區鍵的取值，將檢索範圍限定在指定分區，可提升檢索效率。僅在索引 Schema 中定義了分區鍵時可用。最多 512 個元素，整體最大 4 KB。	["user_1"]
limit	整型	否	返回結果的最大條數。預設值 10。	10
nextToken	字串	否	翻頁標記。僅在純 query（不含 knn、retriever）的檢索情境下支援翻頁，將上一次返回的 nextToken 傳入即可擷取下一頁。	CAESABgB****
sort	對象數組	否	排序欄位，最多指定 3 個。支援按 long、double、bool、string（需開啟 exactMatch）、ip 類型欄位及其數組排序。支援按相關性得分 _score 排序，但 _score 僅支援降序（desc）。	[{"field":"price","order":"asc"}]

knn 參數

knn 為對象數組，每個元素表示對一個向量欄位的近似最近鄰檢索，最多配置 3 個。子參數如下：

名稱	資料類型	是否必選	描述	樣本值
field	字串	是	待檢索的向量欄位名，需為 Schema 中 type=vector 的欄位。	vector_1
queryVector	浮點數數組	是	查詢向量，維度需與 field 對應向量欄位的 dimension 一致。	[0.1, 0.2, 0.3]
topK	整型	否	返回的最近鄰數量。預設值 10。	10
filter	對象	否	向量檢索的預過濾條件，先按標量條件過濾再進行向量檢索。過濾運算元請參見下文的“過濾運算元”。	-
numCandidates	整型	否	向量檢索的候選集大小，取值需不小於 topK。預設值等於 topK。適當增大可提升召回品質，但會增加檢索開銷。無調參經驗時，建議使用服務端預設值。	100
boost	浮點數	否	該路向量檢索得分的權重係數。預設值 1.0。	1.0

retriever 參數

retriever 用於多路召回融合，由“複合檢索器”嵌套“簡單檢索器”組成。檢索器總數最多 3 個、至少 1 個。本期暫不支援複合檢索器嵌套複合檢索器。

複合檢索器：將多路簡單檢索器的結果按演算法融合，取值：
- rrf（Reciprocal Rank Fusion，倒數排名融合）：按各路結果的排名倒數加權融合。支援參數：
  - k：排名平滑常數，取值範圍 1～65536，預設值 50。
  - windowSize：參與融合的每路結果視窗大小，預設值 100。
  - weight：該路檢索器的權重，取值不小於 0，預設值 1.0。
- weight（加權融合）：按各路得分歸一化後加權求和。支援參數：
  - weight：該路檢索器的權重，預設值 1.0。
  - normalizer：得分歸一化方式，取值 none（不歸一化）、minMax（最大最小歸一化）、l2（L2 歸一化），預設值 none。
  - windowSize：參與融合的每路結果視窗大小。
簡單檢索器：融合的一路來源，取值：
- knn：一路向量檢索，子參數同上文的“knn 參數”。
- query：一路標量與全文檢索索引，子參數同下文的“過濾運算元”。

過濾運算元

query 及 filter 中通過過濾運算元表達標量過濾與全文檢索索引條件。支援的運算元如下：

運算元	說明	適用類型
`$and`	邏輯與，所有子條件（clauses）同時滿足。支援 boost（權重）。	邏輯運算元
`$or`	邏輯或，滿足任一子條件即可。支援 boost、minShouldMatch。	邏輯運算元
`$nor`	邏輯或非，所有子條件（clauses）均不滿足。不支援 boost。	邏輯運算元
`$eq` / `$in` / `$exists`	分別表示等於、在集合內、欄位存在。支援 boost（可使用對象形式攜帶 boost）。	標量運算元
`$ne` / `$nin`	分別表示不等於、不在集合內。	標量運算元
`$gt` / `$gte` / `$lt` / `$lte`	分別表示大於、大於等於、小於、小於等於。推薦使用雙邊區間過濾運算元 `$range`，效能會更好。	標量運算元
`$range`	區間過濾，通過 gt/gte/lt/lte 組合表達範圍，支援 boost。gt 與 gte 互斥、lt 與 lte 互斥。	標量運算元
`$textMatch`	分詞匹配（全文檢索索引）。支援參數 operator（可選 and/or，預設 or）、minShouldMatch、boost。檢索文本最大 512 位元組。僅適用於開啟分詞（text）的 string 欄位。	全文檢索索引運算元
`$textMatchPhrase`	短語匹配（全文檢索索引），要求匹配的詞項順序及相鄰關係一致。支援參數 boost。檢索文本最大 512 位元組。僅適用於開啟分詞（text）的 string 欄位。	全文檢索索引運算元
`$geoDistance`	按距離範圍檢索，命中以中心點為圓心、指定半徑內的文檔。支援參數 centerPoint（中心點座標，格式為字串“緯度,經度”）、distanceInMeter（距離中心點的半徑，單位米，取值大於 0）、boost。僅適用於 geoPoint 欄位。	地理運算元
`$geoBoundingBox`	按矩形地區檢索，命中矩形範圍內的文檔。支援參數 topLeft（矩形左上方座標）、bottomRight（矩形右下角座標），座標均為字串“緯度,經度”；支援 boost。僅適用於 geoPoint 欄位。	地理運算元
`$geoPolygon`	按多邊形地區檢索，命中多邊形範圍內的文檔。支援參數 points（多邊形頂點座標數組，每個點為字串“緯度,經度”，最多 16 個點）、boost。僅適用於 geoPoint 欄位。	地理運算元
`$matchAll`	匹配全部文檔。	全量運算元

運算元文法樣本

以下按類別給出各運算元的文法樣本，包含預設寫法與攜帶自訂參數的寫法。樣本中的 field_name 替換為實際欄位名。

邏輯運算元（$and / $or / $nor）

// $and：所有子條件同時滿足，支援 boost
{
  "$and": {
    "clauses": [
      { "title": { "$eq": "馬拉松" } },
      { "year":  { "$gte": 2020 } }
    ],
    "boost": 2.0
  }
}

// $or：滿足任一子條件即可，支援 boost、minShouldMatch
{
  "$or": {
    "clauses": [
      { "title": { "$eq": "馬拉松" } },
      { "year":  { "$gte": 2020 } }
    ],
    "boost": 2.0,
    "minShouldMatch": "50%"
  }
}

// $nor：所有子條件均不滿足，不支援 boost
{
  "$nor": {
    "clauses": [
      { "category": { "$eq": "drama" } },
      { "year":     { "$gte": 2020 } }
    ]
  }
}

等值 / 集合 / 存在運算元（$eq / $ne / $in / $nin / $exists）

// $eq：等於，支援簡寫與對象形式（對象形式可攜帶 boost）
{ "field_name": { "$eq": "documentary" } }
{ "field_name": { "$eq": { "value": "documentary", "boost": 2.0 } } }

// $ne：不等於（反向語義，不支援 boost）
{ "field_name": { "$ne": "documentary" } }

// $in / $nin：在 / 不在集合內（最多 1024 個元素，$in 可攜帶 boost）
{ "field_name": { "$in": ["comedy", "documentary"] } }
{ "field_name": { "$in": { "value": ["comedy", "documentary"], "boost": 2.0 } } }
{ "field_name": { "$nin": ["comedy", "documentary"] } }

// $exists：欄位是否存在
{ "field_name": { "$exists": true } }
{ "field_name": { "$exists": { "value": true, "boost": 2.0 } } }

範圍運算元（$gt / $gte / $lt / $lte / $range）

// $gt / $gte / $lt / $lte：單邊比較，簡寫形式
{ "field_name": { "$gt": 6 } }
{ "field_name": { "$gte": 6 } }

// $range：雙邊區間，支援 boost（推薦使用，效能更好）
// 約束：gt 與 gte 互斥、lt 與 lte 互斥，且不得與 $gt/$gte/$lt/$lte 在同一欄位混用
{
  "field_name": {
    "$range": {
      "gte": 6,
      "lt": 10,
      "boost": 2.0
    }
  }
}

全文檢索索引運算元（$textMatch / $textMatchPhrase）

// $textMatch：分詞匹配，預設寫法
{ "field_name": { "$textMatch": "a b c" } }
// $textMatch：攜帶自訂參數
{
  "field_name": {
    "$textMatch": {
      "value": "a b c",
      "operator": "or",
      "minShouldMatch": "75%",
      "boost": 2.0
    }
  }
}

// $textMatchPhrase：短語匹配，預設寫法
{ "field_name": { "$textMatchPhrase": "a b c" } }
// $textMatchPhrase：攜帶自訂參數（僅支援 boost）
{
  "field_name": {
    "$textMatchPhrase": {
      "value": "a b c",
      "boost": 2.0
    }
  }
}

地理位置運算元（$geoDistance / $geoBoundingBox / $geoPolygon）

// $geoDistance：按距離範圍檢索
{
  "field_name": {
    "$geoDistance": {
      "centerPoint": "5,5",
      "distanceInMeter": 10000,
      "boost": 2.0
    }
  }
}

// $geoBoundingBox：按矩形地區檢索
{
  "field_name": {
    "$geoBoundingBox": {
      "topLeft": "10,0",
      "bottomRight": "0,10",
      "boost": 2.0
    }
  }
}

// $geoPolygon：按多邊形地區檢索（最多 16 個頂點）
{
  "field_name": {
    "$geoPolygon": {
      "points": ["0,0", "5,5", "5,0"],
      "boost": 2.0
    }
  }
}

全部命中運算元（$matchAll）

// $matchAll：匹配全部文檔
{ "$matchAll": {} }
// 帶 boost
{ "$matchAll": { "boost": 2.0 } }

說明

不同欄位類型支援的過濾運算元不同。例如數值類欄位（long、double）支援比較與區間運算元，string 欄位的精確匹配（exactMatch）支援等值運算元、開啟分詞後支援全文檢索索引運算元，geoPoint 欄位支援地理運算元。請結合索引 Schema 中各欄位的能力配置使用。

回應標頭

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

響應元素

名稱	資料類型	描述	樣本值
vectors	對象數組	檢索命中的向量結果清單。	-
key	字串	向量的唯一標識。父節點：vectors	key1
score	浮點數	相關性得分，score 越大表示相關性越高。父節點：vectors	0.87
metadata	對象	向量的中繼資料。僅在 returnMetadata=true 時返回；可通過 returnMetadataFields 指定返回的欄位。父節��：vectors	-
nextToken	字串	翻頁標記。僅純 query 檢索情境下返回，用於擷取下一頁結果。	CAESABgB****

樣本

說明

以下樣本中的 queryVector 與向量取值僅用於示意結構、維度已縮短，實際調用時向量長度必須與建表時聲明的 dimension 嚴格一致，否則會報參數非法。

單路向量檢索

請求樣本

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

{
  "indexName": "docindex",
  "knn": {
    "field": "content_vector",
    "queryVector": [0.12, 0.53, 0.08, 0.91],
    "topK": 100
  },
  "limit": 10
}

向量檢索 + 前置標量過濾（混合檢索）

請求樣本

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

{
   "indexName": "vectorindex1",
   "knn": [
      {
         "field": "vector_1",
         "queryVector": [0.1, 0.2, 0.3],
         "topK": 10,
         "filter": {
            "price": { "$gte": 100, "$lte": 500 }
         }
      }
   ],
   "returnMetadata": true,
   "returnMetadataFields": ["price", "tag"],
   "limit": 10
}

返回樣本

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

{
   "vectors": [
      {
         "key": "key1",
         "score": 0.87,
         "metadata": {
            "price": 199,
            "tag": "shoes"
         }
      },
      {
         "key": "key2",
         "score": 0.72,
         "metadata": {
            "price": 320,
            "tag": "shoes"
         }
      }
   ]
}

純標量檢索（不含向量）

請求樣本

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

{
  "indexName": "productindex",
  "query": {
    "$and": {
      "clauses": [
        { "category": { "$in": { "value": ["phone", "tablet"] } } },
        { "price": { "$range": { "gte": 1000, "lte": 5000 } } },
        { "stock": { "$gt": 0 } }
      ]
    }
  },
  "sort": [{ "price": { "order": "asc" } }],
  "limit": 20,
  "returnMetadata": true,
  "returnMetadataFields": ["title", "brand", "price", "stock"]
}

全文檢索索引（$textMatch）

請求樣本

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

{
  "indexName": "kbindex",
  "query": {
    "body": {
      "$textMatch": {
        "value": "無線 降噪 耳機",
        "operator": "or",
        "minShouldMatch": "2",
        "boost": 1.0
      }
    }
  },
  "limit": 10,
  "returnMetadata": true,
  "returnMetadataFields": ["title", "doc_id"]
}

地理位置檢索（$geoDistance）

請求樣本

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

{
  "indexName": "poiindex",
  "query": {
    "location": {
      "$geoDistance": {
        "centerPoint": "31.23,121.47",
        "distanceInMeter": 5000,
        "boost": 1.0
      }
    }
  },
  "sort": [{ "rating": { "order": "desc" } }],
  "limit": 20,
  "returnMetadata": true,
  "returnMetadataFields": ["name", "rating", "city"]
}

多路混合檢索：RRF 融合

請求樣本

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

{
  "indexName": "productindex",
  "retriever": {
    "rrf": {
      "k": 50,
      "windowSize": 100,
      "retrievers": [
        {
          "retriever": {
            "knn": {
              "field": "text_vector",
              "queryVector": [0.12, 0.53, 0.08],
              "topK": 100
            }
          },
          "weight": 2.0
        },
        {
          "retriever": {
            "simple": {
              "query": {
                "title": { "$textMatch": { "value": "無線 耳機" } }
              }
            }
          },
          "weight": 0.5
        }
      ]
    }
  },
  "limit": 10,
  "returnMetadata": true,
  "returnMetadataFields": ["title", "brand"]
}

返回樣本

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

{
   "vectors": [
      {
         "key": "product-001",
         "score": 0.04755,
         "metadata": {
            "title": "無線降噪耳機",
            "brand": "AliBrand"
         }
      },
      {
         "key": "product-007",
         "score": 0.03846,
         "metadata": {
            "title": "頭戴式耳機",
            "brand": "NovaBrand"
         }
      }
   ]
}

多路混合檢索：Weight 加權歸一化融合

請求樣本

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

{
  "indexName": "productindex",
  "retriever": {
    "weight": {
      "windowSize": 100,
      "retrievers": [
        {
          "retriever": {
            "knn": {
              "field": "text_vector",
              "queryVector": [0.12, 0.53, 0.08],
              "topK": 100
            }
          },
          "weight": 0.7,
          "normalizer": "minMax"
        },
        {
          "retriever": {
            "simple": {
              "query": {
                "title": { "$textMatch": { "value": "無線 耳機" } }
              }
            }
          },
          "weight": 0.3,
          "normalizer": "minMax"
        }
      ]
    }
  },
  "limit": 10,
  "returnMetadata": true,
  "returnMetadataFields": ["title", "brand"]
}

返回樣本

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

{
   "vectors": [
      {
         "key": "product-001",
         "score": 0.23056,
         "metadata": {
            "title": "無線降噪耳機",
            "brand": "AliBrand"
         }
      }
   ]
}

分頁（nextToken）

請求樣本

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

{
  "indexName": "kbindex",
  "query": {
    "$and": {
      "clauses": [
        { "title": { "$textMatch": { "value": "向量資料庫" } } },
        { "year": { "$range": { "gte": 2024 } } }
      ]
    }
  },
  "nextToken": "CAESCG15aC1mESgEeKaGA",
  "limit": 50,
  "returnMetadata": true,
  "returnMetadataFields": ["title", "year"]
}

錯誤碼

錯誤碼	HTTP狀態代碼	描述
MalformedJson	400	請求體中的 JSON 格式不符合規範。
InvalidArgument	400	請求中提供的檢索參數不合法，例如查詢向量維度與索引不一致、使用了欄位不支援的過濾運算元等。
NoSuchVectorIndex	404	指定的向量索引不存在。
AccessDenied	403	返回該錯誤的可能原因如下：發起請求時沒有傳入使用者驗證資訊。沒有操作許可權。