索引分析（AnalyzeIndexBySearch 与 analyze_index）

VSAG 提供了对已构建或已加载索引进行内省诊断的能力，可以在不重建索引的情况下排查召回率回归、 量化质量、图结构健康度以及查询性能问题。该能力通过两种方式对外暴露：

• C++ 接口 Index::AnalyzeIndexBySearch（声明在 include/vsag/index.h）；
• 命令行诊断工具 analyze_index，位于 tools/analyze_index/。

AnalyzeIndexBySearch 接口

// include/vsag/index.h
virtual std::string
AnalyzeIndexBySearch(const SearchRequest& request);

• 输入：SearchRequest（查询数据集 + topk + 搜索参数 JSON）。
• 输出：JSON 字符串，包含基于查询的动态指标。
• 支持的索引类型：当前支持 HGraph、IVF 与 SINDI。Pyramid 仅通过 GetStats() 提供 静态分析，尚未 override AnalyzeIndexBySearch。未实现该接口的索引在调用时会抛出异常。

该接口与 Index::GetStats() 互为补充：后者无需查询数据，只输出索引的静态结构指标。 对于基于图的索引，度分布、入口点质量、子索引召回率以及低召回热点节点等图健康度信息， 通过 GetStats() 而非 AnalyzeIndexBySearch 输出。

GetStats() 输出的静态指标

HGraph 指标

SINDI 指标

依赖原始 base 向量的 SINDI 指标在数据不可用时会输出 skipped_reason。当 use_reorder=true 时，索引内可读取原始向量；否则需要通过 analyze 参数或下方命令行参数 传入 SINDI base_path。

AnalyzeIndexBySearch 输出的动态指标

HGraph 指标

SINDI 指标

SINDI 动态召回和距离质量指标需要真值集。可通过 groundtruth_path 复用已有 .dev.gt， 也可通过 base_path 让 analyzer 基于原始 sparse base 生成精确真值集；save_groundtruth_path 可保存生成结果便于后续复用。没有可用真值集时，这些字段会输出 skipped_reason； postings_scanned 只依赖 query 和索引 posting，仍可正常输出。

量化相关字段在不同索引下命名不一致：

如需度分布、入口点分析或子索引质量分布等图健康度信息，请查看 GetStats() 的 JSON 输出—— AnalyzeIndexBySearch 仅关注查询驱动的动态信号。

analyze_index 工具

analyze_index 是上述分析接口的命令行封装。它从磁盘加载一个已序列化的 VSAG 索引， 打印元数据与 GetStats() 结果，并可选地针对查询文件运行 AnalyzeIndexBySearch。

构建

tools/ 默认不会编译，需要显式开启：

# 通过项目 Makefile
VSAG_ENABLE_TOOLS=ON make release

# 也可直接通过 CMake
cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release -DENABLE_TOOLS=ON
cmake --build build-release -j
# 产物：./build-release/tools/analyze_index/analyze_index

命令行参数

查询文件格式为 tools/analyze_index/analyze_index.cpp 中 load_query() 所读取的简单二进制 布局：(uint32 rows, uint32 cols, float32 data...)。

SINDI 的 query/base 数据使用 CSR sparse 二进制布局：int64 nrow, int64 ncol, int64 nnz， 随后是 int64 indptr[nrow + 1]、int32 indices[nnz] 和 float32 data[nnz]。SINDI 真值集 使用 .dev.gt 布局：uint32 query_count, uint32 topk，随后是展开后的 int32 ids 与 float32 distances。如果没有提供 --groundtruth_path 但提供了 --base_path，SINDI 分析会 基于原始 sparse base 生成真值集，并可通过 --save_groundtruth_path 保存复用。

两种分析模式

1. 仅静态分析（不提供查询文件）

./build-release/tools/analyze_index/analyze_index \
    --index_path /path/to/my_index.hgraph

输出索引名、维度、数据类型、距离度量、构建参数，以及 GetStats() 的 JSON。

2. 静态 + 动态分析

./build-release/tools/analyze_index/analyze_index \
    --index_path /path/to/my_index.ivf \
    --query_path /path/to/queries.bin \
    --search_parameter '{"ivf":{"scan_buckets_count":16}}' \
    --topk 50

除静态信息外，还会额外打印由 AnalyzeIndexBySearch 产出的 Search Analyze: { ... } JSON 块。

当序列化索引只内嵌 index_param 时，analyze_index 也可以在不提供 --build_parameter 的情况下 加载；缺失的 metadata 字段会尽可能使用 analyzer 默认值补齐。

典型使用场景

• 召回率回归排查：根据指标定位问题来源——是量化质量（quantization_*）、图结构 （connect_components、proximity_recall_neighbor），还是查询端参数 （对比 recall_query 与 recall_base）。
• 数据健康度体检：发现重复数据（duplicate_ratio）、断连分量或过多删除等情况。
• 参数调优：使用不同的 search_parameter 反复运行 AnalyzeIndexBySearch， 在 recall_query 与 time_cost_query 之间选择合适的工作点，无需重建索引。
• 假设性实验：通过 --build_parameter 在加载时覆盖原始构建参数，对未在文件中嵌入参数的索引 进行不同配置的评估。

参考

• 接口：include/vsag/index.h 中的 Index::AnalyzeIndexBySearch
• 实现：src/analyzer/{analyzer,hgraph_analyzer,pyramid_analyzer}.h
• 工具源码：tools/analyze_index/
• 工具说明：tools/analyze_index/README_zh.md