N2

|pypi| |docs| |travis| |license|

.. begin_badges

.. |docs| image:: https://readthedocs.org/projects/n2/badge/?version=latest :target: https://n2.readthedocs.io/en/latest/?badge=latest :alt: 文档状态

.. |pypi| image:: https://img.shields.io/pypi/v/n2.svg?style=flat :target: https://pypi.python.org/pypi/n2 :alt: 最新版本

.. |travis| image:: https://travis-ci.org/kakao/n2.svg?branch=master :target: https://travis-ci.org/kakao/n2 :alt: 构建状态

.. |license| image:: https://img.shields.io/github/license/kakao/n2 :target: https://github.com/kakao/n2/blob/master/LICENSE :alt: Apache许可证2.0

.. end_badges

.. begin_intro

用C++编写的轻量级近似N\ earest N\ eighbor算法库（带有Python/Go绑定）。

N2代表两个“N”，源自“Approximate N\ earest N\ eighbor Algorithm”。

.. end_intro

.. begin_background

为什么开发N2

在N2出现之前，已经存在其他优秀的近似最近邻库，如Annoy和NMSLIB。然而，它们各自在易用性、性能等方面都有不同的优缺点。因此，N2的开发旨在结合现有aKNN库的优点，并弥补其不足之处。

.. end_background

.. begin_features

特性

• 轻量级库，能够快速处理大规模数据集。
• 在索引构建时间、搜索速度和内存使用方面表现出色。
• 支持多核CPU进行索引构建。
• 默认支持mmap功能，以高效处理大型索引文件。
• 支持Python/Go绑定。

.. end_features

支持的距离度量

请手动将下表与docs/index.rst中的表格同步。

+-----------+-------------+--------------------------------------------------------------------+ | 度量 | 定义 | d(p, q) | +-----------+-------------+--------------------------------------------------------------------+ | "angular" | 1 - cosθ | 1 - {sum(p :sub:i · q :sub:i) / | | | | sqrt(sum(p :sub:i · p :sub:i) · sum(q :sub:i · q :sub:i))} | +-----------+-------------+--------------------------------------------------------------------+ | "L2" | 平方L2 | sum{(p :sub:i - q :sub:i) :sup:2} | +-----------+-------------+--------------------------------------------------------------------+ | "dot" | 点积 | sum(p :sub:i · q :sub:i) | +-----------+-------------+--------------------------------------------------------------------+

.. begin_metric_detail

N2支持三种距离度量。对于“angular”和“L2”，距离d的定义是：向量越接近，d越小。而对于“dot”，距离d的定义是：向量越接近，d越大。您可能会好奇，为什么我们将“dot”度量实现为普通的点积，而不是*(1 - 点积)*？做出这一决定的原因是为了让用户可以直接将Hnsw搜索函数返回的d值解释为点积值。

.. end_metric_detail

快速入门

1. 使用pip安装N2。

.. code:: bash

$ pip install n2

2. 下面是一个演示如何使用N2的Python代码片段。

.. code:: python

import numpy as np

from n2 import HnswIndex

N, dim = 10240, 20
samples = np.arange(N * dim).reshape(N, dim)

index = HnswIndex(dim)
for sample in samples:
    index.add_data(sample)
index.build(m=5, n_threads=4)
print(index.search_by_id(0, 10))
# [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

完整文档

访问n2.readthedocs.io_获取完整文档。该文档详细介绍了以下内容：

• 安装指南_

  • 如何从源码构建等。

• 带有基本示例的用户指南

  • Python接口_
  • C++接口_
  • Go接口_

• 基准测试_

  • 详细说明我们是如何进行基准测试的。

性能

• 以下是我们的基准测试结果。
• 您还可以在ann-benchmarks.com_上查看各种Python ANN库的基准测试结果。请注意，ann-benchmarks.com_中使用的N2版本为0.1.6（截至2020年10月8日），而我们仍在不断努力提升N2的性能。

索引构建时间

|image0|

搜索速度

|image1|

内存使用

|image2|


.. begin_footnote

参考文献
------------------------------------------------------------------------------

- Y\. A. Malkov 和 D. A. Yashunin, “使用分层可导航小世界图进行高效且鲁棒的近似最近邻搜索,” CoRR, vol. abs/1603.09320, 2016. [在线]. 可用地址: http://arxiv.org/abs/1603.09320
-  NMSLIB: https://github.com/nmslib/nmslib
-  Annoy: https://github.com/spotify/annoy

许可
------------------------------------------------------------------------------

本软件采用`Apache 2许可证`_授权，如下所述。

版权所有 © 2017 Kakao Corp. http://www.kakaocorp.com

根据Apache许可证第2.0版（“许可证”）授权；除非符合许可证规定，否则不得使用本项目。您可以在http://www.apache.org/licenses/LICENSE-2.0获得许可证副本。

除非适用法律要求或书面协议另有约定，否则根据“AS IS”基础分发的软件不提供任何形式的保证或条件，无论是明示还是暗示。有关权限和限制的具体语言，请参阅许可证。

.. _Apache 2 许可证: https://github.com/kakao/n2/blob/master/LICENSE
.. _Annoy: https://github.com/spotify/annoy
.. _NMSLIB: https://github.com/nmslib/nmslib
.. _安装指南: https://n2.readthedocs.io/en/latest/install.html
.. _Python 接口: https://n2.readthedocs.io/en/latest/python_api.html
.. _C++ 接口: https://n2.readthedocs.io/en/latest/cpp_api.html
.. _Go 接口: https://n2.readthedocs.io/en/latest/go_api.html
.. _基准测试: https://n2.readthedocs.io/en/latest/benchmark.html
.. _n2.readthedocs.io: https://n2.readthedocs.io/en/latest/
.. _ann-benchmarks.com: http://ann-benchmarks.com/

.. |image0| image:: docs/imgs/build_time/build_time_threads.png
.. |image1| image:: docs/imgs/search_time/search_time.png
.. |image2| image:: docs/imgs/mem/memory_usage.png

.. end_footnote

N2 快速上手指南

N2 是一个用 C++ 编写的高性能近似最近邻（Approximate Nearest Neighbor, ANN）搜索库，支持 Python 和 Go 绑定。它在索引构建速度、搜索效率和内存占用方面表现优异，特别适合处理大规模数据集。

环境准备

• 操作系统：Linux / macOS / Windows
• Python 版本：Python 3.6+
• 依赖项：
  • numpy（用于数据处理）
  • 编译工具链（如 gcc 或 clang，若需从源码安装）

💡 提示：国内用户可使用清华或阿里云镜像加速 pip 安装。

安装步骤

通过 pip 直接安装（推荐）：

pip install n2

如需使用国内镜像源加速安装：

pip install n2 -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是一个最简单的 Python 示例，演示如何构建索引并执行近邻搜索：

import numpy as np
from n2 import HnswIndex

# 生成示例数据：10240 条，每条 20 维
N, dim = 10240, 20
samples = np.arange(N * dim).reshape(N, dim)

# 创建索引
index = HnswIndex(dim)

# 添加数据
for sample in samples:
    index.add_data(sample)

# 构建索引（设置连接数 m=5，使用 4 个线程）
index.build(m=5, n_threads=4)

# 查询 ID 为 0 的样本的最近 10 个邻居
results = index.search_by_id(0, 10)
print(results)
# 输出示例：[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

支持的距離度量

N2 支持三种距离度量方式：

度量类型	说明	距离定义
angular	余弦相似度	1 - cosθ（值越小越相似）
L2	欧氏距离平方	Σ(pi - qi)²（值越小越相似）
dot	点积	Σ(pi · qi)（值越大越相似）

默认使用 angular 度量。如需切换，可在创建 HnswIndex 时指定 metric 参数，例如：

index = HnswIndex(dim, metric='L2')

---

更多详细用法（包括 C++/Go 接口、高级参数调优等），请访问官方文档：https://n2.readthedocs.io