Hora

[主页] [文档] [示例]

Hora 搜索无处不在！

Hora 是一个近似最近邻搜索算法（Approximate Nearest Neighbor Search Algorithm，维基百科）库。我们使用 Rust🦀 实现所有代码，以确保可靠性、高级抽象以及与 C++ 相当的高性能。

Hora，日语写作 「ほら」，发音为 [hōlə]，意为"哇"、"你看！"或"快看！"。这个名字灵感来源于一首著名的日本歌曲 「小さな恋のうた」（《小小恋歌》）。

演示

👩 人脸匹配 [在线演示]，快来试试吧！

🍷 葡萄酒评论语义搜索 [在线演示]，快来试试吧！

特性

• 高性能 ⚡️

  • SIMD 加速（packed_simd）
  • 稳定的算法实现
  • 多线程设计

• 支持多种语言 ☄️

  • Python
  • Javascript
  • Java
  • Go（进行中）
  • Ruby（进行中）
  • Swift（进行中）
  • R（进行中）
  • Julia（进行中）
  • 也可作为服务使用

• 支持多种索引 🚀

  • 分层可导航小世界图索引（Hierarchical Navigable Small World Graph Index，HNSWIndex）（详情）
  • 卫星系统图（Satellite System Graph，SSGIndex）（详情）
  • 乘积量化倒排文件（Product Quantization Inverted File，PQIVFIndex）（详情）
  • 随机投影树（Random Projection Tree，RPTIndex）（LSH，进行中）
  • 暴力搜索（BruteForce，BruteForceIndex）（基于 SIMD 的简单实现）

• 可移植性 💼

  • 支持 WebAssembly
  • 支持 Windows、Linux 和 OS X
  • 支持 IOS 和 Android（进行中）
  • 支持 no_std（进行中，部分支持）
  • 无重量级依赖，如 BLAS

• 可靠性 🔒

  • Rust 编译器保障所有代码安全
  • 所有语言库（如 Python）的内存由 Rust 管理
  • 广泛的测试覆盖

• 支持多种距离度量 🧮

  • 点积距离（Dot Product Distance）
    • 
  • 欧几里得距离（Euclidean Distance）
    • 
  • 曼哈顿距离（Manhattan Distance）
    • 
  • 余弦相似度（Cosine Similarity）
    • 

• 高效开发 ⭐

  • 文档完善
  • API 优雅、简洁、易学

安装

Rust

在 Cargo.toml 中添加：

[dependencies]
hora = "0.1.1"

Python

$ pip install horapy

Javascript (WebAssembly)

$ npm i horajs

从源码构建

$ git clone https://github.com/hora-search/hora
$ cargo build

基准测试

测试环境：aws t2.medium (CPU: Intel(R) Xeon(R) CPU E5-2686 v4 @ 2.30GHz) 更多信息

示例

Rust 示例 [更多信息]

use hora::core::ann_index::ANNIndex;
use rand::{thread_rng, Rng};
use rand_distr::{Distribution, Normal};

pub fn demo() {
    let n = 1000;
    let dimension = 64;

    // 生成样本点
    let mut samples = Vec::with_capacity(n);
    let normal = Normal::new(0.0, 10.0).unwrap();
    for _i in 0..n {
        let mut sample = Vec::with_capacity(dimension);
        for _j in 0..dimension {
            sample.push(normal.sample(&mut rand::thread_rng()));
        }
        samples.push(sample);
    }

    // 初始化索引
    let mut index = hora::index::hnsw_idx::HNSWIndex::<f32, usize>::new(
        dimension,
        &hora::index::hnsw_params::HNSWParams::<f32>::default(),
    );
    for (i, sample) in samples.iter().enumerate().take(n) {
        // 添加数据点
        index.add(sample, i).unwrap();
    }
    index.build(hora::core::metrics::Metric::Euclidean).unwrap();

    let mut rng = thread_rng();
    let target: usize = rng.gen_range(0..n);
    // 523 的邻居为: [523, 762, 364, 268, 561, 231, 380, 817, 331, 246]
    println!(
        "{:?} has neighbors: {:?}",
        target,
        index.search(&samples[target], 10) // 搜索 k 个最近邻
    );
}

感谢 @vaaaaanquish 提供的完整纯 Rust 🦀 图像搜索示例，关于此示例的更多信息，可点击使用纯 Rust 近似最近邻搜索库 hora 实现图像搜索查看。

Python 示例 [更多信息]

import numpy as np
from horapy import HNSWIndex

dimension = 50
n = 1000

# 初始化索引实例
index = HNSWIndex(dimension, "usize")

samples = np.float32(np.random.rand(n, dimension))
for i in range(0, len(samples)):
    # 添加节点
    index.add(np.float32(samples[i]), i)

index.build("euclidean")  # 构建索引

target = np.random.randint(0, n)
# 410 in Hora ANNIndex <HNSWIndexUsize> (dimension: 50, dtype: usize, max_item: 1000000, n_neigh: 32, n_neigh0: 64, ef_build: 20, ef_search: 500, has_deletion: False)

has neighbors: [410, 736, 65, 36, 631, 83, 111, 254, 990, 161]

print("{} in {} \nhas neighbors: {}".format( target, index, index.search(samples[target], 10))) # search

**`JavaScript` 示例** [[更多信息](https://github.com/hora-search/hora-wasm)]

```JavaScript
import * as horajs from "horajs";

const demo = () => {
    const dimension = 50;
    var bf_idx = horajs.BruteForceIndexUsize.new(dimension);
    // var hnsw_idx = horajs.HNSWIndexUsize.new(dimension, 1000000, 32, 64, 20, 500, 16, false);
    for (var i = 0; i < 1000; i++) {
        var feature = [];
        for (var j = 0; j < dimension; j++) {
            feature.push(Math.random());
        }
        bf_idx.add(feature, i); // add point
    }
    bf_idx.build("euclidean"); // build index
    var feature = [];
    for (var j = 0; j < dimension; j++) {
        feature.push(Math.random());
    }
    console.log("bf result", bf_idx.search(feature, 10)); //bf result Uint32Array(10) [704, 113, 358, 835, 408, 379, 117, 414, 808, 826]
}

(async () => {
    await horajs.default();
    await horajs.init_env();
    demo();
})();

Java 示例 [更多信息]

public void demo() {
    final int dimension = 2;
    final float variance = 2.0f;
    Random fRandom = new Random();

    BruteForceIndex bruteforce_idx = new BruteForceIndex(dimension); // init index instance

    List<float[]> tmp = new ArrayList<>();
    for (int i = 0; i < 5; i++) {
        for (int p = 0; p < 10; p++) {
            float[] features = new float[dimension];
            for (int j = 0; j < dimension; j++) {
                features[j] = getGaussian(fRandom, (float) (i * 10), variance);
            }
            bruteforce_idx.add("bf", features, i * 10 + p); // add point
            tmp.add(features);
          }
    }
    bruteforce_idx.build("bf", "euclidean"); // build index

    int search_index = fRandom.nextInt(tmp.size());
    // nearest neighbor search
    int[] result = bruteforce_idx.search("bf", 10, tmp.get(search_index));
    // [main] INFO com.hora.app.ANNIndexTest  - demo bruteforce_idx[7, 8, 0, 5, 3, 9, 1, 6, 4, 2]
    log.info("demo bruteforce_idx" + Arrays.toString(result));
}

private static float getGaussian(Random fRandom, float aMean, float variance) {
    float r = (float) fRandom.nextGaussian();
    return aMean + r * variance;
}

路线图

• 完整的测试覆盖
• 实现 EFANNA 算法以实现更快的 KNN 图构建
• Swift 支持及 iOS/macOS 部署示例
• 支持 R 语言
• 支持 mmap

相关项目与对比

• Faiss、Annoy、ScaNN：

  • Hora 的实现深受这些库的启发。
  • Faiss 更侧重于 GPU 场景，而 Hora 比 Faiss 更轻量（无繁重依赖）。
  • Hora 期望支持更多语言，所有与性能相关的部分都将由 Rust🦀 实现。
  • Annoy 仅支持 LSH (Random Projection, 局部敏感哈希/随机投影) 算法。
  • ScaNN 和 Faiss 的用户友好性较差（例如缺乏文档）。
  • Hora 完全基于 Rust 🦀。

• Milvus、Vald、Jina AI

  • Milvus 和 Vald 也支持多种语言，但以服务（service）形式而非库（library）形式提供
  • Milvus 基于 Faiss 等库构建，而 Hora 是一个所有算法都自行实现的库

贡献

我们感谢您的参与！

我们很高兴您能参与，欢迎任何贡献，包括文档和测试。 您可以在 GitHub 上创建 Pull Request 或 Issue，我们会尽快审核。

我们使用 GitHub issues 来跟踪建议和漏洞。

克隆仓库

git clone https://github.com/hora-search/hora

构建

cargo build

测试

cargo test --lib

尝试更改

cd examples
cargo run

许可证

整个仓库采用 Apache License 许可。

Hora 快速上手指南

环境准备

系统要求

• 操作系统: Windows / Linux / macOS
• Rust 版本: 1.56+（如需从源码编译）
• Python 版本: 3.6+（如需使用 Python 绑定）

前置依赖

语言	依赖
Rust	Rust 工具链
Python	pip 或 conda
JavaScript/Node.js	npm 或 yarn
Java	JDK 8+

---

安装步骤

Rust 项目

在 Cargo.toml 中添加：

[dependencies]
hora = "0.1.1"

Python（推荐国内镜像加速）

# 使用清华镜像
pip install horapy -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或使用阿里云镜像
pip install horapy -i https://mirrors.aliyun.com/pypi/simple/

JavaScript/WebAssembly

npm i horajs

从源码构建

git clone https://github.com/hora-search/hora
cd hora
cargo build --release

---

基本使用

Rust 示例

use hora::core::ann_index::ANNIndex;
use rand::{thread_rng, Rng};
use rand_distr::{Distribution, Normal};

fn main() {
    let n = 1000;
    let dimension = 64;

    // 生成随机样本数据
    let mut samples = Vec::with_capacity(n);
    let normal = Normal::new(0.0, 10.0).unwrap();
    for _ in 0..n {
        let sample: Vec<f32> = (0..dimension)
            .map(|_| normal.sample(&mut rand::thread_rng()))
            .collect();
        samples.push(sample);
    }

    // 创建 HNSW 索引
    let mut index = hora::index::hnsw_idx::HNSWIndex::<f32, usize>::new(
        dimension,
        &hora::index::hnsw_params::HNSWParams::<f32>::default(),
    );

    // 添加数据点
    for (i, sample) in samples.iter().enumerate() {
        index.add(sample, i).unwrap();
    }

    // 构建索引
    index.build(hora::core::metrics::Metric::Euclidean).unwrap();

    // 搜索最近邻
    let mut rng = thread_rng();
    let target: usize = rng.gen_range(0..n);
    let neighbors = index.search(&samples[target], 10);
    
    println!("目标点 {} 的10个最近邻: {:?}", target, neighbors);
}

Python 示例

import numpy as np
from horapy import HNSWIndex

# 参数设置
dimension = 50
n = 1000

# 初始化索引
index = HNSWIndex(dimension, "usize")

# 生成随机数据并添加
samples = np.float32(np.random.rand(n, dimension))
for i in range(n):
    index.add(np.float32(samples[i]), i)

# 构建索引（使用欧氏距离）
index.build("euclidean")

# 搜索最近邻
target = np.random.randint(0, n)
neighbors = index.search(samples[target], 10)

print(f"目标点 {target} 的10个最近邻: {neighbors}")

JavaScript 示例

import * as horajs from "horajs";

const demo = async () => {
    const dimension = 50;
    
    // 创建暴力搜索索引（或换用 HNSWIndexUsize）
    const index = horajs.BruteForceIndexUsize.new(dimension);
    
    // 添加数据点
    for (let i = 0; i < 1000; i++) {
        const feature = Array.from({length: dimension}, () => Math.random());
        index.add(feature, i);
    }
    
    // 构建索引
    index.build("euclidean");
    
    // 搜索
    const query = Array.from({length: dimension}, () => Math.random());
    const result = index.search(query, 10);
    console.log("最近邻结果:", result);
};

(async () => {
    await horajs.default();
    await horajs.init_env();
    demo();
})();

---

关键概念速查

索引类型	适用场景	特点
HNSWIndex	通用场景，推荐首选	图索引，搜索快，内存适中
SSGIndex	高维数据	卫星系统图，精度更高
PQIVFIndex	大规模数据	乘积量化，内存友好
BruteForceIndex	小数据集/基准测试	精确搜索，速度慢

距离度量: euclidean（欧氏距离）、cosine（余弦相似度）、dot（点积）、manhattan（曼哈顿距离）