企业官网建设流程全解析

NSG核心API详解：从索引构建到搜索查询的Python接口使用指南

【免费下载链接】nsgNavigating Spreading-out Graph For Approximate Nearest Neighbor Search项目地址: https://gitcode.com/gh_mirrors/ns/nsg

NSG（Navigating Spreading-out Graph）是一种高效的近似最近邻搜索算法，通过构建特殊的图结构实现对大规模高维数据的快速检索。本文将详细介绍NSG项目的Python核心API，帮助开发者快速掌握从索引构建到搜索查询的完整流程，轻松上手近似最近邻搜索技术。

🌟 项目核心架构与API概览

NSG项目的Python接口通过pynsg模块提供，主要包含两大功能组件：索引管理和图结构创建。核心API集中在NSG类（定义于bindings.cpp）和图创建工具（graph_creator.py），形成从数据预处理到高效查询的完整链路。

图1：NSG在SIFT数据集上的搜索性能曲线（横轴为搜索参数，纵轴为召回率）

🚀 快速开始：环境准备与安装

1️⃣ 源码克隆与依赖安装

git clone https://gitcode.com/gh_mirrors/ns/nsg cd nsg pip install .

2️⃣ 核心模块导入

from pynsg import NSG, create_graph_file from pynsg.graph_creator import read_fvecs

🔧 核心API详解

1. NSG类：索引管理核心

初始化索引对象

nsg = NSG(dimension=128, num_points=100000, metric=Metric.L2)

• 参数说明：
  • dimension：数据维度（如SIFT特征为128维）
  • num_points：数据集大小
  • metric：距离度量方式（当前支持L2欧氏距离）

构建索引（build_index）

nsg.build_index( data=train_data, knng_path="knng.graph", L=100, R=30, C=50 )

• 关键参数：
  • knng_path：KNN图文件路径（可通过create_graph_file生成）
  • L/R/C：图构建参数（影响索引质量和构建速度）

图2：不同L参数下NSG在高斯分布数据上的性能对比（包含构建时间与搜索精度）

图优化（optimize_graph）

nsg.optimize_graph(data=train_data)

该方法通过局部优化提升图结构的连通性，可将搜索效率提升30%以上（见test_nsg_optimized_search.cpp验证结果）

搜索查询（search/search_opt）

# 普通搜索 results = nsg.search( queries=query_data, data=train_data, k=10, search_L=150 ) # 优化图搜索（需先调用optimize_graph） results_opt = nsg.search_opt( queries=query_data, k=10, search_L=100 )

• 性能对比：优化图搜索在相同召回率下可减少40%的计算量（参考figures/rand_graph.png随机数据测试结果）

索引持久化

# 保存索引 nsg.save_index("nsg_index.bin") # 加载索引 nsg.load_index("nsg_index.bin")

2. 图创建工具：create_graph_file

create_graph_file( filename="knng.graph", x=train_data, k=16, metric="L2", hnsw_efConstruction=200 )

• 功能：为原始数据构建KNN图（NSG索引的前置步骤）
• 参数：
  • k：近邻数量（推荐值16-32）
  • hnsw_efConstruction：HNSW算法参数（影响KNN图质量）

📊 典型应用流程

SIFT特征检索完整示例

# 1. 读取数据 train_data = read_fvecs("sift_base.fvecs") # [1M, 128] query_data = read_fvecs("sift_query.fvecs") # [10K, 128] # 2. 创建KNN图 create_graph_file("sift_knng.graph", train_data, k=16) # 3. 构建NSG索引 nsg = NSG(dimension=128, num_points=len(train_data)) nsg.build_index(train_data, "sift_knng.graph", L=100, R=30, C=50) nsg.optimize_graph(train_data) # 4. 执行搜索 top10_results = nsg.search_opt(query_data, k=10, search_L=120)

图3：NSG在GIST、SIFT、随机数据上的综合性能对比（包含索引大小与查询速度）

⚙️ 参数调优指南

调优建议：优先固定search_L=150，通过调整L（步长50）优化索引质量，实际应用可参考tests/test_nsg_search.cpp中的参数配置。

📝 总结

NSG通过高效的图结构设计，在大规模高维数据检索任务中展现了优异的性能。本文详细介绍了Python API的核心功能，包括索引构建、图优化、搜索查询等关键操作，并提供了完整的应用示例。开发者可根据实际场景调整参数，在搜索速度与精度之间取得最佳平衡。

对于高级应用，可深入研究C++核心实现（src/index_nsg.cpp）和优化算法，进一步提升NSG在特定数据集上的表现。

【免费下载链接】nsgNavigating Spreading-out Graph For Approximate Nearest Neighbor Search项目地址: https://gitcode.com/gh_mirrors/ns/nsg