全部产品
Search
文档中心

向量检索服务 Milvus 版:通过DiskANN索引实现向量范围搜索

更新时间:Oct 22, 2026

向量检索服务 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 的搜索包含以下三个步骤:

  1. 使用集合的度量,按与查询向量的相似度从近到远搜索候选向量。DiskANN 在此步骤中执行图搜索,不会遍历全库执行暴力检索。

  2. 仅保留距离或得分位于 radius 与 range_filter 之间的向量。

  3. 从保留的向量中返回最相似的前 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

距离越小

range_filter <= d < radius

range_filter = 0,或省略。L2 距离不小于 0,此时不排除半径内的近邻

IP

得分越大

radius < d <= range_filter

省略 range_filter,不应设为 0

COSINE

得分越大

radius < d <= range_filter

省略 range_filter,不应设为 0

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 时排除。

参数使用

参数

作用

建议

radius

外圈

根据上表及度量设置,避免与 range_filter 的取值关系颠倒

range_filter

内圈。省略表示不设置内圈

L2 可设为 0;IP / COSINE 设置内圈时,取值必须大于 radius

limit

最多返回条数,也是搜索终止条件之一

设置为业务所需的 K;增大该值不会扩大半径

search_list

图搜索的候选窗口,控制搜索广度

取值建议见下一节;该参数不表示每页结果条数

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 < radius

  • IP / 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 限制而未检索到的远邻不会返回。

相关文档