Rust高效近邻搜索库anndists使用指南

简介

anndists是一个基于Rust的高效近似最近邻(ANN)搜索库，专注于快速距离计算和相似性搜索。它提供了多种近似最近邻算法实现，适用于大规模数据集的相似性搜索场景。

主要特性

• 支持多种距离度量：欧氏距离、余弦相似度等
• 提供多种近似最近邻算法实现
• 内存高效，适合大规模数据集
• 线程安全的API设计
• 提供Rust原生接口和Python绑定

安装

在Cargo.toml中添加依赖：

[dependencies]
anndists = "0.3"

基本使用方法

1. 创建索引并添加数据

use anndists::ann::Hnsw;
use anndists::distance::Euclidean;

// 创建一个HNSW索引，维度为128，使用欧氏距离
let mut index = Hnsw::<f32, Euclidean>::new(128);

// 添加向量到索引
let data = vec![
    vec![1.0, 2.0, 3.0, /* ... */], 
    vec![4.0, 5.0, 6.0, /* ... */],
    // 更多数据...
];

for (i, vec) in data.iter().enumerate() {
    index.add(i, vec);
}

// 构建索引
index.build();

2. 最近邻搜索

let query = vec![1.5, 2.5, 3.5, /* ... */];
let k = 5; // 查找5个最近邻

// 搜索最近的k个邻居
let results = index.search(&query, k);

for (id, distance) in results {
    println!("ID: {}, Distance: {}", id, distance);
}

3. 使用不同距离度量

use anndists::distance::Cosine;

// 使用余弦相似度
let mut index = Hnsw::<f32, Cosine>::new(128);

4. 批量搜索

let queries = vec![
    vec![1.5, 2.5, 3.5, /* ... */],
    vec![4.5, 5.5, 6.5, /* ... */],
];

for result in index.batch_search(&queries, k) {
    println!("Query results: {:?}", result);
}

高级配置

调整HNSW参数

use anndists::params::HnswParams;

let params = HnswParams {
    m: 16,      // 每个节点的最大连接数
    ef_construction: 200, // 构建时的搜索范围
    ef_search: 100,       // 搜索时的搜索范围
    ..Default::default()
};

let mut index = Hnsw::<f32, Euclidean>::with_params(128, params);

持久化索引

use std::fs::File;
use std::io::{BufWriter, BufReader};

// 保存索引
let file = File::create("index.bin").unwrap();
let writer = BufWriter::new(file);
bincode::serialize_into(writer, &index).unwrap();

// 加载索引
let file = File::open("index.bin").unwrap();
let reader = BufReader::new(file);
let index: Hnsw<f32, Euclidean> = bincode::deserialize_from(reader).unwrap();

性能建议

1. 对于大型数据集，分批添加数据并定期调用build_partial方法
2. 根据数据特性调整HNSW参数
3. 考虑使用并行构建索引（如果可用）
4. 对于高维数据，可能需要增加ef_construction和ef_search值

应用场景

• 推荐系统
• 图像/视频检索
• 自然语言处理中的语义搜索
• 异常检测
• 聚类分析

完整示例demo

use anndists::ann::Hnsw;
use anndists::distance::{Euclidean, Cosine};
use anndists::params::HnswParams;

fn main() {
    // 示例1: 使用欧氏距离创建索引并搜索
    let mut index_euclidean = Hnsw::<f32, Euclidean>::new(3);
    
    let data = vec![
        vec![1.0, 2.0, 3.0],
        vec![4.0, 5.0, 6.0],
        vec![7.0, 8.0, 9.0],
    ];
    
    for (i, vec) in data.iter().enumerate() {
        index_euclidean.add(i, vec);
    }
    
    index_euclidean.build();
    
    let query = vec![1.5, 2.5, 3.5];
    let results = index_euclidean.search(&query, 2);
    println!("欧氏距离搜索结果: {:?}", results);
    
    // 示例2: 使用余弦相似度
    let mut index_cosine = Hnsw::<f32, Cosine>::new(3);
    
    for (i, vec) in data.iter().enumerate() {
        index_cosine.add(i, vec);
    }
    
    index_cosine.build();
    
    let results = index_cosine.search(&query, 2);
    println!("余弦相似度搜索结果: {:?}", results);
    
    // 示例3: 高级配置
    let params = HnswParams {
        m: 8,
        ef_construction: 100,
        ef_search: 50,
        ..Default::default()
    };
    
    let mut custom_index = Hnsw::<f32, Euclidean>::with_params(3, params);
    
    for (i, vec) in data.iter().enumerate() {
        custom_index.add(i, vec);
    }
    
    custom_index.build();
    
    let batch_results = custom_index.batch_search(&[query.clone(), vec![4.5, 5.5, 6.5]], 2);
    println!("批量搜索结果: {:?}", batch_results);
    
    // 示例4: 索引持久化
    {
        use std::fs::File;
        use std::io::{BufWriter, BufReader};
        
        // 保存索引
        let file = File::create("index.bin").unwrap();
        let writer = BufWriter::new(file);
        bincode::serialize_into(writer, &custom_index).unwrap();
        
        // 加载索引
        let file = File::open("index.bin").unwrap();
        let reader = BufReader::new(file);
        let loaded_index: Hnsw<f32, Euclidean> = bincode::deserialize_from(reader).unwrap();
        
        println!("从文件加载的索引搜索结果: {:?}", loaded_index.search(&query, 2));
    }
}

这个完整示例展示了anndists库的主要功能，包括：

1. 使用不同距离度量（欧氏距离和余弦相似度）创建索引
2. 添加数据和构建索引
3. 单查询和批量查询
4. 自定义HNSW参数
5. 索引的序列化和反序列化