HNSWLib项目C++示例详解：从基础使用到高级功能

2026-02-04 04:47:30作者：殷蕙予

前言

HNSW（Hierarchical Navigable Small World）是一种高效的近似最近邻搜索算法，而HNSWLib是其C++实现库。本文将深入解析HNSWLib的C++示例代码，帮助开发者快速掌握这一强大工具的使用方法。

基础使用示例

索引创建与数据插入

首先我们来看最基本的索引创建和数据插入操作：

#include "../../hnswlib/hnswlib.h"

int main() {
    // 参数设置
    int dim = 16;               // 向量维度
    int max_elements = 10000;   // 最大元素数量
    int M = 16;                 // 图的连接数，影响内存消耗和搜索性能
    int ef_construction = 200;  // 构建时的搜索范围，影响构建质量和速度
    
    // 初始化索引空间（使用L2距离）
    hnswlib::L2Space space(dim);
    hnswlib::HierarchicalNSW<float>* alg_hnsw = 
        new hnswlib::HierarchicalNSW<float>(&space, max_elements, M, ef_construction);
    
    // 生成随机数据
    std::mt19937 rng(47);  // 固定种子保证可重复性
    std::uniform_real_distribution<> distrib_real;
    float* data = new float[dim * max_elements];
    for (int i = 0; i < dim * max_elements; i++) {
        data[i] = distrib_real(rng);
    }
    
    // 添加数据到索引
    for (int i = 0; i < max_elements; i++) {
        alg_hnsw->addPoint(data + i * dim, i);
    }
    
    // ... 后续操作
}

关键点解析：

M参数控制图中每个节点的连接数，值越大索引越精确但内存消耗也越大
ef_construction影响构建质量，值越大构建时间越长但索引质量越好
数据插入时需要一次性指定最大元素数量，这是HNSW的一个限制

搜索与召回率测试

构建完索引后，我们可以测试其搜索效果：

// 查询元素自身并计算召回率
float correct = 0;
for (int i = 0; i < max_elements; i++) {
    auto result = alg_hnsw->searchKnn(data + i * dim, 1);
    if (result.top().second == i) correct++;
}
std::cout << "Recall: " << correct / max_elements << "\n";

这里我们测试的是"自查询"的召回率，即每个向量能否正确找到自己，这是最基本的正确性测试。

序列化与反序列化

HNSW索引支持序列化到文件，便于保存和加载：

// 序列化索引
std::string hnsw_path = "hnsw.bin";
alg_hnsw->saveIndex(hnsw_path);
delete alg_hnsw;

// 反序列化索引
alg_hnsw = new hnswlib::HierarchicalNSW<float>(&space, hnsw_path);

序列化功能在实际应用中非常重要，可以避免每次使用时都重新构建索引。

高级功能示例

搜索时过滤

HNSWLib支持在搜索时进行结果过滤，这在很多实际场景中非常有用：

// 定义过滤函数：只允许能被divisor整除的标签
class PickDivisibleIds: public hnswlib::BaseFilterFunctor {
    unsigned int divisor;
public:
    PickDivisibleIds(unsigned int divisor): divisor(divisor) {
        assert(divisor != 0);
    }
    bool operator()(hnswlib::labeltype label_id) {
        return label_id % divisor == 0;
    }
};

// 使用过滤函数进行搜索
PickDivisibleIds pickEven(2);  // 只允许偶数标签
auto result = alg_hnsw->searchKnnCloserFirst(query_vector, k, &pickEven);

这种过滤机制可以用于实现各种业务逻辑，如：

只搜索特定类别的物品
排除某些不符合条件的结果
实现复杂的业务规则过滤

删除元素与内存重用

HNSWLib支持标记删除元素并重用其内存空间：

// 初始化索引时开启删除功能
hnswlib::HierarchicalNSW<float>* alg_hnsw = 
    new hnswlib::HierarchicalNSW<float>(&space, max_elements, M, ef_construction, 100, true);

// 标记删除部分元素
for (int i = 0; i < num_deleted; i++) {
    alg_hnsw->markDelete(i);
}

// 重用被删除元素的内存空间
for (int i = 0; i < num_deleted; i++) {
    int new_label = max_elements + i;
    alg_hnsw->addPoint(new_data + i * dim, new_label, true);  // replace_deleted=true
}