QueryVectorsFusion-对象存储(OSS)-阿里云帮助中心

注意事项

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	返回该错误的可能原因如下：发起请求时没有传入用户验证信息。没有操作权限。