关于COSINE度量下HNSW索引search_params中radius参数的困惑

问题场景 #

我创建集合时使用的索引参数如下：

index_params.add_index(
    field_name="video_embed",
    index_type="HNSW",
    metric_type="COSINE",
    params={"M": 32, "efConstruction": 500},
)

执行搜索时，当search_params设置为：

search_params = {
    "metric_type": "COSINE",
    "params": {
        "radius": 0.1,  # 最小相似度阈值
        "range_filter":1.0,
    }
}

能正常返回数据自身，比如：

{"id": "data-self-id", "distance": 0.9999995827674866}

但将radius调整为0.9后：

search_params = {
    "metric_type": "COSINE",
    "params": {
        "radius": 0.9,  # 最小相似度阈值
        "range_filter":1.0,
    }
}

部分数据搜不到自身，甚至无结果返回，移除range_filter后情况一致。尝试调整radius值，部分数据需设到0.57805才行，但这个值不通用，导致无法通过搜索相似结果过滤已有数据。

原因分析 #

1. HNSW是近似最近邻（ANN）索引，并非精确匹配索引，搜索时依赖ef参数控制遍历的节点数量。如果ef默认值过小，即使是自身节点，也可能因为遍历范围不足被遗漏。
2. 余弦相似度下，radius代表“最小相似度阈值”，当设置较大值时，需要索引遍历更多节点来找到符合条件的结果，默认ef无法覆盖足够范围。
3. 若向量未做归一化，自身的余弦相似度可能低于预期的1.0，导致大radius下被误过滤。

解决办法 #

1. 增大搜索时的ef参数

在search_params中添加ef并设置较大值（建议和efConstruction一致或更高，比如500-1000），扩大搜索遍历范围：

search_params = {
    "metric_type": "COSINE",
    "params": {
        "radius": 0.9,
        "ef": 1000,  # 提升搜索时的扩展因子，平衡精度与速度
        "range_filter":1.0,
    }
}

注意：ef越大搜索越精确，但耗时会增加，需根据业务场景调整。

2. 启用精确搜索（小数据集适用）

如果集合数据量不大，可强制使用精确搜索绕过HNSW的近似逻辑，确保找到自身：

search_params = {
    "metric_type": "COSINE",
    "params": {
        "radius": 0.9,
        "range_filter":1.0,
        "force_exact_search": True
    }
}

⚠️ 警告：精确搜索在数据量大时性能会急剧下降，仅适合小规模数据集。

3. 确保向量归一化

余弦相似度的计算依赖单位长度向量，插入数据前对video_embed做L2归一化，保证自身的余弦相似度接近1.0：

# 示例：使用numpy对向量归一化
import numpy as np

def normalize_vector(vec):
    norm = np.linalg.norm(vec)
    return vec / norm if norm != 0 else vec

# 插入数据前处理向量
video_embed = normalize_vector(video_embed)

4. 优化HNSW索引构建参数

如果经常需要大radius的搜索，可重新创建索引时增大M和efConstruction，让索引结构更密集：

index_params.add_index(
    field_name="video_embed",
    index_type="HNSW",
    metric_type="COSINE",
    params={"M": 64, "efConstruction": 1000},  # 增大M和efConstruction
)

代价是索引构建时间变长、内存占用增加，需权衡资源消耗。

内容的提问来源于stack exchange，提问作者Qi Xiang