向量检索服务 Milvus 版(简称 Milvus)支持在 DiskANN 索引上执行范围搜索。DiskANN 上的范围搜索,按 Milvus 范围搜索语义执行:以查询向量为圆心,radius 为外圈,range_filter 为内圈,只保留位于环带内的向量,再从中返回最相似的前 limit 条。本文介绍这三个参数的配置方法、search_list 的取值建议及预期返回结果。
前提条件
已创建支持 DiskANN 索引的 Milvus 实例,详情请参见快速创建Milvus实例。
已准备带有数据的 Collection,并为待搜索的向量字段建立 DiskANN 索引。
已获取实例 Endpoint、用户名和密码,并确认运行 Python 的环境可访问该 Endpoint。
已安装 PyMilvus。
pip install pymilvus阿里云 DiskANN 的实现和参数可能与开源 Milvus 不同,详情请参见容量型磁盘索引(DiskANN)。小数据量示例用于说明参数和返回结果;评估搜索窗口的调优效果时,应使用接近业务规模的数据。
范围搜索原理
指定 radius 的搜索包含以下三个步骤:
使用集合的度量,按与查询向量的相似度从近到远搜索候选向量。DiskANN 在此步骤中执行图搜索,不会遍历全库执行暴力检索。
仅保留距离或得分位于
radius与range_filter之间的向量。从保留的向量中返回最相似的前 K 条。K 为请求中的
limit。
环带内不足 K 条时,返回条数可以少于 K。limit = 3 时最多返回 3 条,不保证返回环带内的全部向量。
默认情况下,过滤和搜索终止使用原始向量的精确距离:排除比内圈更近的向量并继续搜索,保留位于环带内的向量。当结果达到 K 条,或下一条精确距离达到或超出外圈边界时,搜索终止。
度量与不等式
DiskANN 只支持 L2、IP、COSINE 度量距离。
对于距离越小越相似的度量(L2),外圈边界值大于内圈边界值:
range_filter <= 距离 < radius对于距离或得分越大越相似的度量(IP、COSINE),外圈边界值小于内圈边界值,并且 radius 必须小于 range_filter:
radius < 距离 <= range_filter度量 | 越相似 | 环带 | 不设内圈时 |
L2 | 距离越小 |
|
|
IP | 得分越大 |
| 省略 |
COSINE | 得分越大 |
| 省略 |
range_filter 设为 0 表示返回半径内全部实体,适用于 L2 这类距离越小越近的度量。对于 COSINE / IP,将 range_filter 设为 0 会得到 radius < d <= 0 的区间,可能导致结果为空。例如 COSINE radius = 0.4、range_filter = 0 时,正相似度的向量不满足该区间条件。内圈为闭区间边界,外圈为开区间边界:对于 L2,距离等于 range_filter 时保留,等于 radius 时排除;对于 IP / COSINE,得分等于 range_filter 时保留,等于 radius 时排除。
参数使用
参数 | 作用 | 建议 |
| 外圈 | 根据上表及度量设置,避免与 |
| 内圈。省略表示不设置内圈 | L2 可设为 |
| 最多返回条数,也是搜索终止条件之一 | 设置为业务所需的 K;增大该值不会扩大半径 |
| 图搜索的候选窗口,控制搜索广度 | 取值建议见下一节;该参数不表示每页结果条数 |
search_list 不限制返回条数。limit = 500、search_list = 100 时,搜索会继续沿图进行,直到获取 500 条环带内的结果、精确距离超出外圈,或图遍历结束,不会在返回第 100 条结果时终止。未传入 search_list,或取值小于 100 时,范围搜索会将窗口调整为 100。返回条数上限仍为 limit。
推荐使用方法
保留精排
范围搜索的过滤和搜索终止依赖原始向量距离,建议保留默认精排配置:
查询参数不应设置为
use_refine = false。
根据环带的近邻深度设置 search_list
候选窗口应覆盖目标环带所在的近邻深度。配置建议如下:
环带包含最近邻(L2 的
range_filter = 0,或 IP / COSINE 省略range_filter):search_list至少取max(100, limit)。limit较小(几十到一百)时,取值为 100 的召回水平与普通 TopK 相近。内圈排除了较多近邻,即
range_filter排除了大量最近的向量、目标环带位于更远处:应将search_list增大至与目标近邻深度相同的量级。当窗口仅为 100,而环带位于数千个近邻的位置时,图搜索往往无法覆盖环带,返回结果会偏少。
limit 大于 search_list 时,结果不会被截断,但候选窗口相对较小,检索到环带内第 K 个近邻的概率会降低。为提高 K 条结果的召回稳定性,应将 search_list 设置为不小于 K。
limit 控制返回条数
limit 表示结果条数上限,不表示搜索深度。半径确定搜索范围后,增大 limit 只会增加同一环带内可返回的结果条数,直至环带内的结果已全部获取。环带内只有 10 条时,limit = 1000 仍然只有大约 10 条有效结果,PyMilvus 返回实际命中的结果列表,不会按 limit 补齐结果。
limit 达到 16384 及以上时,范围搜索仍执行图搜索,不使用 large TopK 扫描路径。K 较大且环带较宽时,延迟会明显增加。业务仅需要几十条结果时,不建议将 limit 设置为此量级。
返回条数可以少于 limit
以下两种情况下,返回条数可以少于请求条数:
环带内的向量数少于
limit。精确距离已超出外圈,后续候选向量的距离更大。
使用 PyMilvus 时,直接遍历实际返回的命中列表即可,通过 len(res[0]) 统计实际命中数,无需按 limit 预留固定数量的结果。
图搜索未覆盖目标环带时,返回条数也会偏少。此时应增大 search_list,无需放宽半径。search_list 与环带深度处于同一量级时,召回水平与相同窗口的普通 TopK 相近。在此窗口下,估计距离与精确距离之间的少量排序差异,不会使满足区间条件的结果变为不满足条件的结果,也不会持续导致整页结果缺失。
示例
以下示例使用已有的 Collection:my_collection_cosine、my_collection_l2、my_collection_ip 分别对应 COSINE、L2、IP 度量的 DiskANN 索引。向量字段名为 vector,示例查询向量为 8 维。请将 Endpoint、凭证、Collection 名称、向量字段名和向量维度替换为实际值,并确保搜索度量与索引一致。
COSINE:检索得分在 0.4 到 0.6 之间的前 3 条
默认度量是 COSINE 时,radius 必须小于 range_filter。下面的请求返回得分满足 0.4 < 得分 <= 0.6 的最多 3 条,按得分从高到低。
from pymilvus import MilvusClient
client = MilvusClient(uri="http://<your-endpoint>:19530", token="<your-username>:<your-password>")
query_vector = [
0.3580376395471989,
-0.6023495712049978,
0.18414012509913835,
-0.26286205330961354,
0.9029438446296592,
0.0,
0.0,
0.0,
]
res = client.search(
collection_name="my_collection_cosine",
anns_field="vector",
data=[query_vector],
limit=3,
search_params={
"metric_type": "COSINE",
"params": {
"radius": 0.4,
"range_filter": 0.6,
"search_list": 100,
},
},
)
for hits in res:
for hit in hits:
print(hit["id"], hit["distance"])limit = 3 时,可设置 search_list = 100。若调整为 limit = 200,应将 search_list 设置为不小于 200。
L2:检索半径 100 以内的前 10 条,不设置内圈
res = client.search(
collection_name="my_collection_l2",
anns_field="vector",
data=[query_vector],
limit=10,
search_params={
"metric_type": "L2",
"params": {
"radius": 100.0,
"range_filter": 0.0,
"search_list": 100,
},
},
)返回满足 0 <= 距离 < 100 的最近的最多 10 条结果。
L2:排除近邻,检索距离在 20 到 100 之间的结果
res = client.search(
collection_name="my_collection_l2",
anns_field="vector",
data=[query_vector],
limit=10,
search_params={
"metric_type": "L2",
"params": {
"radius": 100.0,
"range_filter": 20.0,
"search_list": 100,
},
},
)返回结果满足 20 <= 距离 < 100。如果距离小于 20 的近邻较多,应增大 search_list,使候选窗口能够覆盖被内圈排除的近邻深度。
IP:得分在 0.2 到 0.8 之间
res = client.search(
collection_name="my_collection_ip",
anns_field="vector",
data=[query_vector],
limit=10,
search_params={
"metric_type": "IP",
"params": {
"radius": 0.2,
"range_filter": 0.8,
"search_list": 100,
},
},
)返回满足 0.2 < 得分 <= 0.8 的得分最高的最多 10 条结果。
结果验证
返回结果应满足以下条件:
L2:
range_filter <= distance < radiusIP / COSINE:
radius < distance <= range_filter条数不超过
limit同一条查询中,L2 结果按距离从小到大排序,IP / COSINE 结果按得分从大到小排序
返回条数少于 limit 时,应检查区间范围和 search_list 设置;仅凭这两项,不能确认已返回区间内的全部向量。
使用注意事项
使用 COSINE / IP 时,应确保
radius和range_filter的大小关系正确;不设置内圈时,应省略range_filter,不应将其设为 0。search_list控制图搜索的候选窗口,不表示结果条数;返回条数由limit和环带内的实际命中数量决定。范围搜索中设置
use_refine = false后,将按估计距离过滤环带边界,可能降低边界附近结果的召回率。增大
limit不会扩大搜索范围。范围搜索不保证返回全库中位于环带内的每一个向量。DiskANN 按 ANN 从近到远获取前 K 条;受 K 和
search_list限制而未检索到的远邻不会返回。