VSAG 介绍

VSAG 全称 Vector Search Algorithm Group，是一个用于相似性检索的向量索引库。VSAG 允许用户在各种规模的向量集合中进行高效搜索，包括无法完全放入内存的集合，同时提供基于向量维度和数据规模自动生成参数的能力，使开发者无需深入了解底层算法原理即可快速上手。

VSAG 使用 C++ 编写，并提供：

• Python 包装 pyvsag
• Node.js / TypeScript 绑定 vsag（由 napi-rs 生成）

该项目由蚂蚁集团发起并主导开发，目前以开源社区的方式维护。

主要特性

• 低内存占用：通过量化（RaBitQ、PQ、SQ4/SQ8）降低使用成本；
• 高性能检索：针对 x86_64（SSE/AVX/AVX2/AVX512/AMX）和 ARM（Neon/SVE）做了指令集适配；
• 丰富的索引类型：HGraph、IVF、Pyramid、BruteForce、SINDI / SINDI_V2（稀疏）等；
• 灵活的过滤与混合搜索：支持 bitmap 与 callback 两种过滤方式，以及混合 (data vector, attribute) 查询；
• 易于集成：提供基于 CMake 的集成方式，详见 README。

如何阅读本文档

• 用户指南：如果你是新用户，请从安装、创建索引和搜索开始。
• 索引：比较不同索引类型，并查询索引参数。
• 高级功能：深入了解搜索、序列化、内存管理和混合索引能力。
• API 参考：include/vsag/ 下公有头文件的 C++ 类、方法与类型参考手册。
• 性能与调优：查看最佳实践、Tune、性能参考和评估工具。
• 开发者指南：了解源码构建、测试和贡献流程。
• 资源：查看版本日志、路线图、社区、关联项目、论文和贡献者信息。

Contributing

VSAG 是免费和开源的。你可以在 GitHub 上获取到源代码，以及提交错误报告和功能请求到 GitHub问题跟踪器 上。VSAG 依靠社区来修复错误和增加功能：如果你想做出贡献，请阅读 贡献指南 并考虑 创建合并请求。

License

VSAG 源代码和文档在 Apache-2.0 许可证下发布。

安装

VSAG 是一个向量检索库，支持在 C++、Python 和 Node.js / TypeScript 程序中使用。核心 C++ 库支持 Linux，也支持在 Apple Silicon 上使用 macOS 14 或更高版本从源码构建。完整 CI 仍以 Linux 为主；预编译 C++ 包和 pyvsag wheel 当前也主要面向 Linux。

如果使用的是 Python，可以从官方第三方包仓库 PyPI 下载，包名为 pyvsag。pyvsag 的版本与源代码版本一一对应，版本功能可以直接参考 GitHub 发布日志。Python 包使用 manylinux2014 构建，可以在绝大部分 Linux 环境中运行。通过如下命令获得最新版本：

pip install pyvsag

如果使用的是 Node.js，可以从 npm 直接安装 vsag 包：

npm install vsag

下载预编译二进制包

我们为 C++ 用户提供预编译的二进制包，可以在 GitHub Releases 中找到。

预编译二进制分为两个版本：

• 旧的 pre-C++11 ABI：文件名为 vsag-vX.Y.Z-pre-cxx11-abi.tar.gz，使用 -D_GLIBCXX_USE_CXX11_ABI=0 编译；
• C++11 ABI：文件名为 vsag-vX.Y.Z-cxx11-abi.tar.gz，使用 -D_GLIBCXX_USE_CXX11_ABI=1 编译。

其中 X.Y.Z 是版本号。两个版本分别满足不同应用对 ABI 的需求。

使用 Docker 镜像

我们也提供了包含完整开发工具链的 Docker 镜像，推荐用于开发和 CI：

docker pull vsaglib/vsag:ubuntu

镜像内的工具版本（clang-format / clang-tidy 等）与项目要求保持一致。

从源代码构建

VSAG 可以使用 CMake 从源代码构建，支持 Linux x86_64 / aarch64，以及 macOS arm64。macOS 当前验证范围是核心 C++ 库的 make debug、make release 与 make test；Python wheel 打包仍以 Linux 为主。

构建依赖：

• 操作系统：
  • Ubuntu 20.04 或更高版本
  • 或 CentOS 7 或更高版本
  • 或 macOS 14 或更高版本（Apple Silicon）
• 编译器：
  • GCC 9.4.0 或更高版本
  • 或 Clang 13.0.0 或更高版本
  • macOS 使用 Xcode Command Line Tools 提供的 Apple Clang
• 构建工具：
  • CMake 3.18.0 或更高版本
  • clang-format 15（精确版本，用于代码格式化）
  • clang-tidy 15（精确版本，用于静态检查）
• 其他依赖项：
  • Linux：gfortran、OpenMP、libaio、Python 3.6+、curl
  • macOS：Xcode Command Line Tools、Homebrew

依赖项可以通过以下脚本安装：

# 自动识别当前平台
./scripts/deps/install_deps.sh

# 也可以直接调用平台脚本
./scripts/deps/install_deps_ubuntu.sh  # Debian / Ubuntu
./scripts/deps/install_deps_centos.sh  # CentOS / AliOS
./scripts/deps/install_deps_macos.sh   # macOS

如需 Linux io_uring 存储后端，请安装 liburing，并在直接配置 CMake 时添加 -DENABLE_LIBURING=ON。未启用时，uring_io 配置会回退到 buffer_io。用法与 限制见磁盘索引。

VSAG 使用 CMake 管理工程，常用构建目标封装在项目根目录的 Makefile 中。运行以下命令可以在发布模式下编译并安装：

make release && make install

更多构建选项请参考 编译构建。

创建索引

VSAG 中所有检索能力都围绕 Index 接口展开。要使用某种索引，首先需要通过工厂方法 vsag::Factory::CreateIndex(name, parameters) 创建实例，其中：

• name 是索引类型名称，对应 include/vsag/constants.h 中定义的常量；
• parameters 是一段 JSON 字符串，声明数据类型、距离度量、维度等构建参数。

当前支持的索引类型

完整示例可在 examples/cpp/ 目录中按照前缀编号依次查看（101_ ~ 109_ 为索引类型，2xx_ 为自定义资源，3xx_ 为功能特性）。

使用磁盘 I/O 的 SINDI_V2

std::string params = R"(
{
    "dim": 1024,
    "dtype": "sparse",
    "metric_type": "ip",
    "index_param": {
        "term_id_limit": 30000,
        "use_reorder": true,
        "term_io": {
            "type": "async_io",
            "file_path": "/path/to/sindi_v2.terms"
        },
        "rerank_io": {
            "type": "async_io",
            "file_path": "/path/to/sindi_v2.rerank"
        }
    }
}
)";
auto index = vsag::Factory::CreateIndex("sindi_v2", params).value();

通用的构建参数

所有索引在创建时都需要声明以下字段：

• dtype：向量数据类型，当前常用为 "float32"；部分索引也支持 "fp16"、"bf16"、"int8"；
• metric_type：距离度量方式，支持 "l2"、"ip"、"cosine"；
• dim：向量维度，必须与后续写入的数据一致。

索引特有参数以嵌套对象形式提供，例如 HGraph 在构建期使用 index_param 子对象（hgraph 保留给 ef_search 等查询期参数）。

示例：创建 HGraph 索引

#include <vsag/vsag.h>

auto hgraph_build_parameters = R"(
{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "fp32",
        "max_degree": 16,
        "ef_construction": 100
    }
}
)";
auto index = vsag::Factory::CreateIndex("hgraph", hgraph_build_parameters).value();

示例：创建 HGraph 索引（SQ8 量化）

auto hgraph_build_parameters = R"(
{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "max_degree": 32,
        "ef_construction": 100,
        "base_quantization_type": "sq8"
    }
}
)";
auto index = vsag::Factory::CreateIndex("hgraph", hgraph_build_parameters).value();

不同索引支持的参数及其语义，请参考 索引参数。

k-近邻搜索

以下内容假设你已经安装 VSAG。我们提供了 C++、Python、TypeScript 三种语言的代码示例，可以在 examples/ 目录找到。本页以 C++ BruteForce 索引为例，完整示例见 examples/cpp/105_index_brute_force.cpp。

在多数情况下，程序入口需要调用一次 vsag::init() 来完成一次性的初始化（如全局日志、分配器等）。本页示例中省略了其他辅助代码，以突出关键步骤。

获取一些向量

VSAG 主要用于处理固定维度 d 的向量集合，通常维度为几百到几千维。这些向量需要按照按行的方式组织才能写入 VSAG，类似于 vector[num_vectors][dim] 这样的 C++ 数组。从接口上说，VSAG 只依赖传入的向量集合首地址指针 （const float* 类型），所以应用可以自由选择使用 C++ 数组、std::vector 或者手动分配的内存来存储原始向量。

当前 VSAG 只支持 32-bit 的浮点数向量。

一次 k-近邻搜索需要两个向量集合。

• base 集合代表数据库中的所有向量，我们将会在其中进行搜索，它的大小是 向量数 * 向量维度；
• query 集合代表查询向量，我们要为其查找最近的邻居，它的大小是 向量数 * 向量维度。当前，VSAG 只支持 向量数 = 1的查询，即不支持批量查询；

现在，我们生成一些 d=128 维的随机向量，以及它们对应的 ID（搜索结果会以 ID 形式返回）。

    int64_t num_vectors = 10000;
    int64_t dim = 128;
    int64_t *ids = new int64_t[num_vectors];
    float *datas = new float[num_vectors * dim];
    std::mt19937 rng(47);
    std::uniform_real_distribution<float> distrib_real;
    for (int64_t i = 0; i < num_vectors; ++i) {
        ids[i] = i;
    }
    for (int64_t i = 0; i < dim * num_vectors; ++i) {
        datas[i] = distrib_real(rng);
    }

    float* query_vector = new float[dim];
    for (int64_t i = 0; i < dim; ++i) {
        query_vector[i] = distrib_real(rng);
    }

这里使用的是 C++ 原生数组。当然，你也可以使用 std::vector<float> 来实现，并且通过 data() 方法得到数组首地址。

构建索引并写入向量

VSAG 库的使用主要围绕着 Index 接口，它封装了向量集合，并且提供了一系列能力。在 VSAG 中，Index 有多种实现，每种实现具备的能力和适用的场景不尽相同。在这个示例中，我们将使用最简单的版本，基于暴力搜索的索引 BruteForce。

所有索引都需要显式地创建，从而声明向量的维度和相似度计算方法。在这个示例中，向量的维度 dim=128，相似度使用欧几里得距离（L2）计算。

    std::string brute_force_build_parameters = R"(
    {
        "dtype": "float32",
        "metric_type": "l2",
        "dim": 128
    }
    )";
    auto index = vsag::Factory::CreateIndex("brute_force", brute_force_build_parameters).value();

向量索引的数据写入涉及到两个方法：Build 和 Add。Build 方法带初始化性质，一些依赖训练过程来分析数据分布的索引，需要通过调用 Build 方法来启用。Add 是一般性的向量数据写入方法，大部分的索引都实现了这个方法，除了部分完全静态的索引类型。

BruteForce 索引支持用 Build 和 Add 方法写入数据，这里我们用 Add 方法来演示。

    auto base = vsag::Dataset::Make();
    base->NumElements(num_vectors)
        ->Dim(dim)
        ->Ids(ids)
        ->Float32Vectors(datas)
        ->Owner(false);
    index->Add(base);

搜索

向量索引的一个核心作用是 k-近邻 搜索，即对于每个查询向量，在数据库中查找 k 个最相近的邻居。

搜索方法需要传入查询向量、k 值以及搜索参数。BruteForce 索引没有搜索参数，所以这里传入一个空的 Json 字符串。返回的结果中包含两个信息：最相近邻居的 ID ，最相近邻居与查询向量的距离。这两个信息可以分别通过结果集的 GetIds() 和 GetDistances() 方法获得。

    auto query = vsag::Dataset::Make();
    query->NumElements(1)->Dim(dim)->Float32Vectors(query_vector)->Owner(false);

    auto brute_force_search_parameters = R"({})";
    int64_t topk = 10;
    auto result = index->KnnSearch(query, topk, brute_force_search_parameters).value();

    std::cout << "results: " << std::endl;
    for (int64_t i = 0; i < result->GetDim(); ++i) {
        std::cout << result->GetIds()[i] << ": " << result->GetDistances()[i] << std::endl;
    }

搜索请求至多返回 k 个结果，这些结果按照最近邻和查询向量的距离升序排序。输出的结果类似于：

按阈值过滤

阈值过滤支持仍在维护的索引：BruteForce、HGraph、IVF、Pyramid、SINDI 和 SIMQ。 HNSW 和 DiskANN 已移除且不受支持；本选项不会为这两个旧索引新增或修改行为。

KNN 搜索参数支持在 JSON 顶层设置可选的 threshold：

{
  "threshold": 4.0,
  "hgraph": { "ef_search": 64 }
}

设置后，结果至多返回 k 个邻居，并且每个返回距离都小于或等于 threshold。 边界值会被包含，结果仍按距离升序排列，因此可能返回少于 k 个结果，甚至没有结果。 不设置该字段时，KNN 行为保持不变。阈值使用索引返回的距离语义：l2 为 L2 平方距离， ip 为 1 - inner_product，cosine 为 1 - cosine_similarity。因此 ip 可以使用负阈值； 阈值必须是有限的 JSON 数字。

通过统一请求接口时，BruteForce、HGraph 和 IVF 支持使用 SearchRequest::threshold_； Pyramid、SINDI 和 SIMQ 通过 KNN JSON 参数支持该选项。这六种索引是本功能支持的仍在维护的索引。 该选项只限制 KNN 结果；范围搜索请使用 RangeSearch 及其 radius 参数。threshold 可以和现有索引专用搜索参数同时传入。

results:
6519: 13.855
2332: 15.2735
2126: 15.5844
7388: 15.6583
795: 15.5958
3979: 15.815
4756: 15.9983
510: 16.1128
8703: 16.1161
5583: 16.1256

C API

VSAG 在 include/vsag/vsag_c_api.h 中导出 C ABI。它封装了与 C++ API 相同的索引实现， 适合需要不透明句柄和 C 风格函数的应用及语言绑定。

当前安装的头文件不能直接被 C 编译单元包含：其中使用了未加条件保护的 extern "C" 代码块和 C++ bool。请将包含该头文件的编译单元按 C++ 编译（例如使用 .cpp 文件）。 如果应用的其余部分使用 C，请在这个 C++ 编译单元中封装所需操作，再导出应用自己的 C 接口。

生命周期

在 C++ 编译单元中包含安装后的头文件，并链接普通 VSAG 库：

#include <vsag/vsag_c_api.h>

基本生命周期如下：

1. 使用 vsag_index_factory 创建不透明的 vsag_index_t。
2. 构建索引，或先训练再增量添加向量。
3. 执行搜索、更新、序列化或读取操作。
4. 使用 vsag_index_destroy 释放句柄。

创建失败时，vsag_index_factory 返回 nullptr。其他函数返回 Error_t； code == VSAG_SUCCESS 表示成功，否则可从 message 读取错误详情。

const char* build_params =
    "{\"dtype\":\"float32\",\"metric_type\":\"l2\",\"dim\":128,"
    "\"index_param\":{\"base_quantization_type\":\"fp32\","
    "\"max_degree\":32,\"ef_construction\":200}}";

vsag_index_t index = vsag_index_factory("hgraph", build_params);
if (index == nullptr) {
    /* 处理创建失败 */
}

Error_t error = vsag_index_build(index, base, ids, 128, count);
if (error.code != VSAG_SUCCESS) {
    /* 检查 error.message */
}

vsag_index_destroy(index);

搜索结果缓冲区

SearchResult_t 中的 ids 与 dists 缓冲区由调用方持有。执行 KNN 或范围 搜索前，两个缓冲区都至少分配 k 个元素。VSAG 最多写入 k 条结果，并把实际 数量写入 count。

int64_t result_ids[10];
float result_dists[10];
SearchResult_t result{};
result.dists = result_dists;
result.ids = result_ids;

Error_t error =
    vsag_index_knn_search(index, query, 128, 10, "{\"hgraph\":{\"ef_search\":100}}", &result);

带过滤器的重载接收 FilterFunc_t。回调返回 true 表示该 ID 有效，可以出现 在结果中。

范围搜索结果上限

两个 C 范围搜索接口都要求显式传入正数结果上限：

Error_t
vsag_index_range_search(vsag_index_t index,
                        const float* query,
                        uint64_t dim,
                        float radius,
                        int64_t k,
                        const char* parameters,
                        SearchResult_t* result);

k 必须至少为 1。它会传递给 C++ 范围搜索的 limited_size 参数，同时保护 调用方缓冲区：result.count 不会超过 k。从旧签名升级时，需要为 vsag_index_range_search 和 vsag_index_range_search_with_filter 同时补上该参数。

接口分组

• 创建与释放： vsag_index_factory、vsag_index_destroy。
• 写入数据： vsag_index_build、vsag_index_train、vsag_index_add。
• 搜索： vsag_index_knn_search、vsag_index_range_search 及其过滤器重载。
• 读取与更新： vsag_index_calculate_distance_by_ids、 vsag_index_get_vector_by_ids、vsag_index_update_ids、vsag_index_update_vector 及 vsag_index_update_vector_force。
• 复制与复用： vsag_index_clone、vsag_index_export_model。
• 持久化： vsag_serialize_file、vsag_deserialize_file、 vsag_serialize_write_func 及 vsag_deserialize_read_func。

具体接口是否可用仍取决于索引类型。不支持的操作返回 VSAG_UNSUPPORTED_INDEX_OPERATION。

持久化错误

vsag_serialize_file 与 vsag_deserialize_file 会校验目标文件是否成功打开。 不要假定文件操作已经完成；应检查返回的 Error_t 是否为 VSAG_READ_ERROR、 VSAG_MISSING_FILE 或其他非成功状态。

应用自行管理存储时，可以使用基于回调的持久化接口。回调中的 offset 和 size 使用头文件里声明的 OffsetType 与 SizeType。

参考

include/vsag/vsag_c_api.h 是函数签名、错误码、回调和结构体的完整源码级 参考。搜索参数 JSON 与对应索引页面中的 C++ API 相同。

pyvsag

pyvsag 是 VSAG 的 Python 绑定包，接口封装基于 pybind11 实现，源代码位于仓库 python_bindings/ 目录，打包脚本位于 python/。

安装

从 PyPI 安装最新发布版本：

pip install pyvsag

需要在 Linux 环境下使用（manylinux2014 wheel）。如果希望构建本地 wheel，可以运行：

# 构建特定 Python 版本的 wheel
make pyvsag PY_VERSION=3.11

# 或一次构建所有受支持版本
make pyvsag-all

快速开始

pyvsag 暴露一个与 C++ Index 对象对应的 Index 类，构建与搜索参数使用 JSON 字符串传递：

import json
import numpy as np
import pyvsag

dim = 128
num_elements = 1000

ids = np.arange(num_elements, dtype=np.int64)
data = np.float32(np.random.random((num_elements, dim)))

index_params = json.dumps({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": dim,
    "index_param": {
        "base_quantization_type": "fp32",
        "max_degree": 16,
        "ef_construction": 100,
    },
})

index = pyvsag.Index("hgraph", index_params)
index.build(vectors=data, ids=ids, num_elements=num_elements, dim=dim)

query = np.float32(np.random.random(dim))
search_params = json.dumps({"hgraph": {"ef_search": 100}})
result_ids, result_dists = index.knn_search(
    vector=query, k=10, parameters=search_params,
)
for rid, rdist in zip(result_ids, result_dists):
    print(f"{rid}: {rdist}")

完整示例请查阅仓库中的 examples/python/ 目录，建议从 103_index_hgraph.py 开始。

保存与加载

index.save("index.bin")

new_index = pyvsag.Index("hgraph", index_params)
new_index.load("index.bin")

当前 save 与 load 包装不会传播底层序列化和反序列化操作返回的错误。请确认输出文件 已经生成，并对重要索引执行保存后重新加载的 round-trip 校验，再依赖持久化结果。

索引操作

除构建、搜索、保存与加载外，Python 绑定还提供以下索引管理方法：

# 添加两条稠密向量
new_vectors = np.random.random((2, dim)).astype(np.float32)
new_ids = np.array([10_001, 10_002], dtype=np.int64)
index.add(new_vectors, new_ids, len(new_ids), dim)

assert index.check_id_exist(10_001)
print(index.get_num_elements(), index.get_memory_usage())
print(index.get_min_max_id())

# 计算一个 query 到候选 ID 列表的距离
candidate_ids = np.array([10_001, 10_002], dtype=np.int64)
distances = index.cal_distance_by_id(query, candidate_ids)

# 删除 ID；返回值为实际删除数量
removed = index.remove(candidate_ids)

add 接受展开的连续数组或 row-major 二维矩阵。dtype: "float16" 时传入 numpy.float16；dtype: "bfloat16" 时传入包含 BF16 位模式的 numpy.uint16 数组。 具体操作是否受支持仍取决于索引类型。输入校验和 add 等操作会抛出 Python 异常； remove、cal_distance_by_id、save 与 load 则使用上述 sentinel 或未检查行为， 不会统一传播底层操作错误。

与 C++ 库的关系

pyvsag 绑定的是同一份核心 C++ 实现，行为和性能特征与 C++ 版本保持一致。因此：

• 大多数 C++ 参数在 Python 中以相同的 JSON 字段传递；
• C++ 版本新增的索引类型、量化方式、距离度量会随 pyvsag 的下一个 release 一同发布；
• 构建 wheel 时所使用的依赖项与发布版 C++ 库相同（OpenBLAS、libaio 等）。

关于可用参数和索引类型，请参考 创建索引 和 索引参数。

索引

VSAG 提供了一系列索引实现，它们共享同一套构建式 API、同一种序列化格式、同一组操作 （Build、Add、KnnSearch、RangeSearch、Remove、Serialize / Deserialize 等）， 差异在于底层使用的数据结构与折中取舍。

本节覆盖当前活跃维护的索引：

brute_force 作为精确检索基线也可使用（见 创建索引 与 examples/cpp/105_index_brute_force.cpp）。

参数约定

所有索引共享以下顶层构建字段：

索引特有的构建参数放在 index_param 子对象中；查询参数放在以索引名命名的子对象中 （例如 hgraph、ivf、sindi、sindi_v2、pyramid）。LazyHGraph 转换到 graph 阶段后也使用 hgraph 搜索参数。具体参数定义在各索引页面内给出，也可查阅 索引参数 进行总览。

索引参数

本页汇总 VSAG 各索引类型的常用参数。完整枚举请参考源码：

• 构建参数键：src/constants.cpp
• 公开常量：include/vsag/constants.h
• 每个索引的示例：examples/cpp/*_index_*.cpp（例如 103_index_hgraph.cpp）

通用参数

所有索引在构建时都接受以下顶层字段。其中 dtype、metric_type 必填，repr 可选。 非稀疏数据必须提供 dim；dtype: "sparse" 省略 dim 时默认使用 4096：

dtype 与 repr 描述不同维度：前者是标量编码，后者是记录布局。显式设置 repr 时， dtype: "sparse" 要求 repr: "sparse"。受支持的多向量索引使用 repr: "multi_vector"，并配合 float32 等标量 dtype。

HGraph

HGraph 的构建参数使用通用的 index_param 键（参见 examples/cpp/103_index_hgraph.cpp）； hgraph 键则保留给搜索期参数。

{
    "dim": 128,
    "dtype": "float32",
    "metric_type": "l2",
    "index_param": {
        "base_quantization_type": "fp32",
        "max_degree": 32,
        "ef_construction": 400
    }
}

搜索时：

{"hgraph": {"ef_search": 100}}

ef_search 接受任意正的有符号 64 位整数，不再存在与 topk 相关的上限。非常大的取值会 明显增加延迟和搜索前沿占用的内存。 use_conjugate_graph_search 为布尔值（默认 true）；当构建时设置 use_conjugate_graph: true 后，它控制是否使用已学习的共轭边。

hgraph 搜索参数还接受 brute_force_threshold（[0.0, 1.0] 区间的 float， 默认 0.0）。当取值 > 0 且当前请求的 filter 的 ValidRatio() 不超过该 阈值时，HGraph 会跳过图遍历，直接在通过过滤的 id 上做精确暴扫。详见 HGraph 索引文档。

LazyHGraph

LazyHGraph 的构建参数可以放在顶层 lazy_hgraph 对象中（推荐，语义更清晰），也可以放在 通用的 index_param 对象中。hgraph 子对象会转交给转换后的内部 HGraph。

{
    "dim": 128,
    "dtype": "float32",
    "metric_type": "l2",
    "lazy_hgraph": {
        "transition_threshold": 1000,
        "hgraph": {
            "base_quantization_type": "sq8",
            "max_degree": 26,
            "ef_construction": 100
        }
    }
}

LazyHGraph 只支持 dtype: "float32"。搜索参数使用 hgraph 对象，例如 {"hgraph": {"ef_search": 100}}。详见 LazyHGraph 索引文档。

hgraph 搜索参数还接受以下 filter 相关参数：

IVF

{
    "ivf": {
        "nlist": 4096,
        "base_quantization_type": "sq8",
        "nprobe": 32
    }
}

Brute Force

{"brute_force": {}}

无需额外参数。

Pyramid

Pyramid 构建参数同样放在 index_param 下：

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 24,
        "ef_construction": 300,
        "store_paths": true
    }
}

store_paths 是 Pyramid 顶层构建参数，默认值为 false。需要通过 GetDataByIdsWithFlag 和 DATA_FLAG_PATH 返回默认或命名 hierarchy 的原始路径时应启用它；路径完整性与持久化语义见 Pyramid 参数表。

MRLE 与 split RaBitQ 组合使用 base_quantization_type: "tq"、 tq_chain: "mrle, rabitq"、mrle_dim，以及 rabitq_bits_per_dim_base/rabitq_bits_per_dim_precise。该配置会自动从 split base codes 精排，并保留原始 FP32 向量供仅解码路径使用。完整配置及存储/召回权衡见 Pyramid 页面。

SINDI（稀疏向量）

{
    "dtype": "sparse",
    "metric_type": "ip",
    "dim": 1024,
    "index_param": {
        "term_id_limit": 30000,
        "doc_prune_ratio": 0.1
    }
}

use_quantization、不可变构建与 n_candidate 等搜索参数见 SINDI 页面。

SINDI_V2（稀疏向量）

SINDI_V2 兼容 SINDI 的全部功能，并支持内存与磁盘 I/O。

{
    "dtype": "sparse",
    "metric_type": "ip",
    "dim": 1024,
    "index_param": {
        "term_id_limit": 30000,
        "use_reorder": true,
        "term_io": {
            "type": "async_io",
            "file_path": "/path/to/sindi_v2.terms"
        },
        "rerank_io": {
            "type": "async_io",
            "file_path": "/path/to/sindi_v2.rerank"
        }
    }
}

详情见 SINDI_V2 页面。

运行期参数

除构建参数外，Index::Tune 与 SearchParam 可在运行时调整 ef_search、nprobe 等参数。参考 优化器 与各 examples/cpp/3xx_feature_*.cpp 示例。

HGraph

HGraph 是 VSAG 的旗舰 图索引。它构建的是多层近邻图， 提供了丰富的量化方案、统一的构建参数 schema（index_param），并原生支持精排（reorder）、 增量更新、删除、以及基于 ELP 的运行时自动调优。

对于大多数稠密向量场景（文本 / 图像 / 多模态 embedding，维度 64–4096，规模从数千到数亿）， HGraph 都是推荐的默认索引。

• 源码：src/algorithm/hgraph.{h,cpp}
• 示例：examples/cpp/103_index_hgraph.cpp

工作原理

1. 构图。 向量被组织成层级近邻图：上层作为导航入口，底层连接每个数据点到在 max_degree 预算内的最近邻。构图算法可以是 NSW 风格插入（graph_type: "nsw"，默认） 或 ODescent（graph_type: "odescent"）。
2. 量化。 底层存储使用可配置的量化器进行压缩（base_quantization_type — fp32、fp16、bf16、sq8、sq4、sq8_uniform、sq4_uniform、pq、pqfs、rabitq、tq）。 可选地再保留一份高精度副本（use_reorder: true 搭配 precise_quantization_type）， 用于对粗排结果进行重打分。
3. 搜索。 自顶向下在图上做贪心 beam search，扩展候选集到 ef_search 个节点；如启用精排， 最终结果会在高精度表示上重新打分。

快速开始

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 32,
        "ef_construction": 400
    }
})";
auto index = vsag::Factory::CreateIndex("hgraph", params).value();

// 构建索引。
auto base = vsag::Dataset::Make();
base->NumElements(n)->Dim(128)->Ids(ids)->Float32Vectors(data)->Owner(false);
index->Build(base);

// 执行检索。
auto query = vsag::Dataset::Make();
query->NumElements(1)->Dim(128)->Float32Vectors(q)->Owner(false);
auto result = index->KnnSearch(
    query, /*topk=*/10, R"({"hgraph": {"ef_search": 100}})").value();

构建参数

构建参数放在 index_param 下。下表列出最常用的配置项；完整列表请见 索引参数。

use_reverse_edges 面向需要快速检查入邻居、图分析或图维护算法的负载。维护反向邻接表会让边 存储约翻倍，因此默认关闭。

label_remap_type 只改变内部 label map，不改变用户 ID。默认值为 "pg"； "robin" 选择另一种 robin-map 实现，建议针对实际 ID 分布实测后再调整。

向量存储去重

同时设置 support_duplicate: true 和 deduplicate_storage: true 后，重复向量会共享 同一个物理编码槽位，但仍保留各自的标签。该选项目前仅支持使用 graph_type: "nsw" 的 稠密向量 HGraph 索引；graph_type: "odescent" 不支持。

启用存储去重后，暂不支持以下操作和配置：

• 强制删除（support_force_remove: true）；
• 调用 ImportCache() 后基于缓存加速构建；
• Merge；
• v0.14 旧版序列化格式。

UpdateVector 仅支持尚未与其他重复组成员共享向量存储的 ID。

当前序列化格式和 streaming serialization 均受支持。

支持的输入数据类型

顶层构建配置中的 dtype 字段决定 Dataset 如何解释原始向量字节。HGraph 支持四种输入类型， dtype 值、对应的 Dataset setter 与演示示例见下表。

dim 始终表示逻辑维度（元素数量），与字节长度无关，因此四种数据类型下 dim 取值相同。

int8 输入

量化好的 int8 向量直接通过 Int8Vectors 传入：

std::vector<int8_t> data(num_vectors * dim);  // 填入 int8 元素
auto base = vsag::Dataset::Make();
base->NumElements(num_vectors)->Dim(dim)->Ids(ids)
    ->Int8Vectors(data.data())->Owner(false);

对应构建配置（注意 dtype: "int8"）：

{
    "dtype": "int8",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "pq",
        "max_degree": 26,
        "ef_construction": 100,
        "alpha": 1.2
    }
}

查询时同样使用 Int8Vectors 和相同的 dtype。可运行示例： 316_index_int8_hgraph.cpp。

float16 / bfloat16 输入

FP16 与 BF16 都通过 Float16Vectors 传入，参数类型为 const uint16_t*，指向各元素的 16 位 存储。从 float 到 16 位格式的转换由调用方负责。VSAG 源码树内提供了便捷辅助函数 （vsag::generic::FloatToFP16 位于 src/simd/fp16_simd.h， vsag::generic::FloatToBF16 位于 src/simd/bf16_simd.h）， 但它们是内部头文件，并未通过 include/vsag/ 对外安装。链接已安装版 VSAG 库的应用需要自行 完成转换（例如复制这段小工具函数、使用 _cvtss_sh / F16C 内置指令，或调用任意 FP16 库）。下面 的示例代码为了简洁直接使用了源码树内的辅助函数：

// 下面的 fp16/bf16 辅助函数位于 src/simd/，并未随 VSAG 一并安装。
// 链接已安装版 VSAG 时，请替换为自行实现的 float -> uint16_t 转换。
#include "simd/fp16_simd.h"  // FloatToFP16（BF16 场景改为 simd/bf16_simd.h / FloatToBF16）

std::vector<uint16_t> data(num_vectors * dim);
for (size_t i = 0; i < data.size(); ++i) {
    data[i] = vsag::generic::FloatToFP16(some_float_source());
}
auto base = vsag::Dataset::Make();
base->NumElements(num_vectors)->Dim(dim)->Ids(ids)
    ->Float16Vectors(data.data())->Owner(false);

构建配置：

{
    "dtype": "float16",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "pq",
        "max_degree": 26,
        "ef_construction": 100,
        "alpha": 1.2
    }
}

切换到 BF16 时，将 dtype 改为 "bfloat16"、把 FloatToFP16 替换为 FloatToBF16 即可； Float16Vectors setter 与构建/检索流程不变。可运行 FP16 示例： 321_index_fp16_hgraph.cpp。

注意。 321_index_fp16_hgraph.cpp 文件头注释提到 BFloat16Vectors()，但该 setter 并不 存在 —— FP16 与 BF16 都通过 Float16Vectors 传入。无论 dtype 是 "float16" 还是 "bfloat16"，都使用同一个 setter。

输入类型选择建议

• 对精度要求最高、且内存预算充裕时，选 float32（默认）。
• 想把输入存储减半，选 float16 / bfloat16。FP16 指数范围更小，BF16 尾数位更少但指数范围 与 FP32 一致，对 embedding 类向量通常更友好。
• 数据本身已是整数量化结果（来自上游量化器或 int8 输出的模型）时，选 int8。此时通常仍配合 pq / sq8 之类的索引内量化器使用。

dtype 仅约束输入表示；索引内的实际存储仍由 base_quantization_type（以及 use_reorder: true 下的 precise_quantization_type）决定，因此 dtype: "float16" + base_quantization_type: "sq8" 这样的组合是允许的。

检索参数

检索参数放在 hgraph 子对象下：

auto result = index->KnnSearch(
    query, topk, R"({"hgraph": {"ef_search": 200}})").value();

高选择性过滤下的暴搜回退（brute_force_threshold）

图搜索在大多数候选都能通过过滤时是最优策略——图遍历能很快进入查询邻域。但是当 过滤越来越严格（只有极少数向量能通过）时，beam 需要扩展非常多的节点才能凑够 ef_search 个通过过滤的候选，此时召回率会下降，延迟反而上升。在某个临界点， 对通过过滤的 id 做一次完整暴扫既更快又精确。

brute_force_threshold 允许 HGraph 在每次查询时自动按 filter 选择率做这个切换：

// 当 filter 仅保留 ≤ 1% 的 id 时，自动改走暴力扫描。
auto params = R"({"hgraph": {"ef_search": 200, "brute_force_threshold": 0.01}})";
auto result = index->KnnSearch(query, topk, params, my_filter).value();

工作原理（实现位于 src/algorithm/hgraph/hgraph_search.cpp）：

• 暴搜回退仅在同时满足以下条件时触发：
  • brute_force_threshold > 0.0，并且
  • 提供了 filter，并且
  • filter->ValidRatio() <= brute_force_threshold。
• Filter::ValidRatio() 的准确性会直接影响是否切换 —— 这是用户提供的提示值。 详见 带过滤的搜索 中关于该方法的约定。
• 暴搜会遍历所有通过过滤的内部 id，并按 64 一批用当前最精确的 flatten 存储 计算距离（顺序：若启用了 store_raw_vector 则用原始向量；否则若 use_reorder=true 则用精排副本；否则用基础量化编码）。
• 由于暴搜在有精排副本时本身就用了精确编码，走暴搜分支的查询不会再做精排。
• 该机制对 KnnSearch（非迭代器重载，也即 SearchWithRequest 与标准的 KnnSearch(query, k, params, filter) 走的入口）和 RangeSearch 生效；对 迭代器风格的 KnnSearch(..., IteratorContext*&, ...) 不生效，因为一次 扫描无法分页跨越多次迭代调用。

取值建议：

• 不带过滤或过滤通过率较高的场景，保持默认 0.0。
• 高选择性过滤（如 ValidRatio ≤ 0.05）下，0.01–0.05 是合理起点。再往上调 实际上等于「只要带 filter 就走暴搜」。
• 暴搜的代价大致是 O(N × dim)，N 是索引内总向量数（与选择率无关，因为 每个 id 都要走一次 CheckValid）。当原本需要把 ef_search 调到很大才能 维持召回时，暴搜带来的收益最明显。

可运行示例： 322_feature_hgraph_brute_force_threshold.cpp。

过滤跳过策略（skip_ratio 与 skip_strategy）

当搜索带有 filter 时，HGraph 在图遍历过程中需要频繁调用 Filter::CheckValid() 来验证每个候选点是否有效。这个检查可能很耗时（特别是复杂过滤逻辑）。skip_ratio 和 skip_strategy 提供了一种概率性优化：通过跳过部分 filter 检查来加速搜索，但可能降低召回率。

工作原理

这是一个概率性优化策略：我们事先不知道哪些点是有效的，因此按概率决定是否访问每个点。

• skip_ratio（默认 0.2）：控制跳过 filter 检查的激进程度。skip_ratio=0.2 表示跳过 20% 的无效点，只检查 80% 的无效点。值越大，跳过的越多，速度越快，但召回率可能越低。
• skip_strategy（默认 “deterministic_accumulative”）：决定如何分配跳过：
  • “random”：随机跳过。每个点被访问的概率为 visit_ratio = valid_ratio + (1 - valid_ratio) * (1 - skip_ratio)，大约跳过 skip_ratio 比例的无效点。
  • “deterministic_accumulative”：确定性累积跳过。按固定间隔做出访问决策，使长期访问比例趋近于目标 visit_ratio，相比 random 策略方差更小。

具体公式：

• 设 valid_ratio 为 filter 的全局有效率（来自 Filter::ValidRatio()）
• 每个点被访问的概率 = valid_ratio + (1 - valid_ratio) * (1 - skip_ratio)
• 如果 Filter::ValidRatio() 估计准确，期望跳过约 skip_ratio 比例的无效候选检查

使用示例

// 保守设置：跳过 10% 的无效候选检查，适合召回率要求高、延迟不那么关键的场景
auto params = R"({"hgraph": {"ef_search": 200, "skip_ratio": 0.1}})";
auto result = index->KnnSearch(query, topk, params, my_filter).value();

// 使用随机策略
auto params = R"({"hgraph": {"ef_search": 200, "skip_ratio": 0.2, "skip_strategy": "random"}})";
auto result = index->KnnSearch(query, topk, params, my_filter).value();

// 激进跳过：跳过 50% 的无效候选检查，以更低延迟为目标
auto params = R"({"hgraph": {"ef_search": 200, "skip_ratio": 0.5}})";
auto result = index->KnnSearch(query, topk, params, my_filter).value();

取值建议

• 默认 0.2：适合大多数场景，在性能和召回率之间取得平衡。
• 0.1 或更低：保守设置，适合对召回率要求高、延迟不那么关键、可接受召回率下降的场景（如实时推荐系统）。
• 0.5 或更高：激进跳过，适合对延迟敏感、可接受召回率下降的场景。
• 0.0：不跳过任何点，等同于关闭此优化（所有点都会被检查）。

注意事项：

• 仅在带 filter 的搜索中生效。无 filter 时这些参数会被忽略。
• 如果 Filter::ValidRatio() 估计准确，性能优化效果更好。
• 与 brute_force_threshold 可同时使用：当 filter 非常严格（ValidRatio 很小）时，brute_force_threshold 会触发暴搜回退；否则使用图遍历 + skip 优化。

何时选择 HGraph

• 维度大约在 64–4096 的稠密 float 向量。
• 对延迟敏感且要求高召回的场景。
• 需要增量插入（可选通过 support_force_remove 打开物理删除）的混合负载。
• 内存受限环境，可用 sq8 / sq4_uniform / pq 压缩，再配合 use_reorder 弥补召回。

对于 Source ID 稳定的每日构建或快照构建，参见 HGraph 构建缓存。其中说明了 Dataset::SourceID、 ExportCache/ImportCache、persist_source_id 与缓存命中率诊断。

如果你的业务偏向粗粒度分桶（每次查询只扫部分桶）或严重受 SSD I/O 制约，建议先对比 IVF 再决定是否选择 HGraph。

相关文档

• 创建索引
• 图索引增强
• 优化器
• 序列化格式

LazyHGraph

LazyHGraph 是一个自适应的稠密向量索引：数据量较小时先使用精确的 BruteForce 索引，达到可配置的 transition_threshold 后自动转换为 HGraph。它适合“初始规模较小、 后续持续增长”的集合：早期查询保持精确并避免构图开销，规模变大后获得 HGraph 的近似检索 延迟与量化能力。

• 源码：src/algorithm/lazy_hgraph.{h,cpp}
• 示例： examples/cpp/111_index_lazy_hgraph.cpp

工作方式

1. Flat 阶段。 达到阈值前，数据存放在内部 BruteForce 索引中，使用 FP32 向量， 搜索结果是精确的。
2. 转换。 当 Build 收到不少于 transition_threshold 条向量，或 Add 让 flat 阶段增长到该规模时，LazyHGraph 会用 flat 数据构建内部 HGraph。
3. Graph 阶段。 转换完成后，新增数据与查询都交给内部 HGraph 处理。搜索参数仍使用 hgraph 子对象。

快速开始

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "lazy_hgraph": {
        "transition_threshold": 1000,
        "hgraph": {
            "base_quantization_type": "sq8",
            "max_degree": 26,
            "ef_construction": 100,
            "build_thread_count": 4
        }
    }
})";
auto index = vsag::Factory::CreateIndex("lazy_hgraph", params).value();

auto base = vsag::Dataset::Make();
base->NumElements(n)->Dim(128)->Ids(ids)->Float32Vectors(data)->Owner(false);
index->Add(base);

auto query = vsag::Dataset::Make();
query->NumElements(1)->Dim(128)->Float32Vectors(q)->Owner(false);
auto result = index->KnnSearch(
    query, /*topk=*/10, R"({"hgraph": {"ef_search": 100}})").value();

构建参数

LazyHGraph 的构建参数放在顶层 lazy_hgraph 对象中。为了兼容通用工厂参数形态， 同一个对象也可以放在 index_param 中。

LazyHGraph 只支持顶层 dtype: "float32"。flat 阶段固定使用 FP32 BruteForce 存储，不接受单独的 flat 量化参数。

搜索参数

搜索参数与 HGraph 一样，使用 hgraph 子对象：

{"hgraph": {"ef_search": 100}}

在 flat 阶段，搜索是精确的；进入 graph 阶段后，内部 HGraph 会使用传入的 HGraph 搜索参数，例如 ef_search。

生命周期说明

• Build 会根据输入规模选择初始阶段：小于 transition_threshold 保持 flat； 大于等于阈值则直接构建 HGraph。
• Add 可能触发从 flat 到 graph 的单向转换。
• flat 阶段的 Remove 始终执行物理删除，即使调用方传入 RemoveMode::MARK_REMOVE， 这样后续图转换不会携带 tombstone。
• GetExtraInfoByIds、UpdateExtraInfo 与基于 extra_info 的过滤在两个阶段都支持。 见 Extra Info。

何时使用 LazyHGraph

• 稠密 FP32 集合初始较小，并会持续增长。
• 集合较小时希望获得精确结果。
• 希望同一个索引在规模变大后自动切换到 HGraph。

如果数据在构建时已经很大、需要非 FP32 输入类型，或希望从第一条插入开始就使用图索引行为， 请直接使用 HGraph。

相关文档

• HGraph
• Extra Info
• 创建索引

IVF

IVF（Inverted File，倒排索引）是 VSAG 的 分桶式 索引。它在构建时将语料聚类成若干桶， 查询时只扫描与查询距离最近的若干个桶的中心对应的倒排列表，把 O(N) 的线性扫描降为 O(N · scan_buckets_count / buckets_count)，并通过这两个参数在召回与延迟之间进行权衡。

与图索引相比，IVF 在召回上略有损失，但换来了更低的内存开销、更高的批量吞吐以及更简单的 切片方式——因此在语料非常大（数亿及以上）、内存紧张、或查询可天然并行化的场景中， IVF 通常是一个更合适的默认选择。

• 源码：src/algorithm/ivf.{h,cpp}、src/algorithm/ivf_parameter.{h,cpp}
• 示例：examples/cpp/106_index_ivf.cpp

工作原理

1. 聚类。 在数据集的采样上运行 k-means（或随机采样，ivf_train_type: "random"） 得到 buckets_count 个中心（centroid）。
2. 分配。 每条向量被写入距离最近的中心对应的倒排列表，以配置的粗量化 （base_quantization_type）存储；可选地再保留一份高精度副本（use_reorder: true） 用于精排。
3. 检索。 查询时先计算查询向量与所有中心的距离，选出最近的 scan_buckets_count 个桶；然后只在这些桶内对向量打分。启用精排时，factor 控制从粗排阶段多取多少候选 再送入精排器重打分。

此外还有一种 GNO-IMI 策略（partition_strategy_type: "gno_imi"），它把空间按两组 正交中心划分（first_order_buckets_count × second_order_buckets_count），在超大规模 语料上能得到更精细的分区。

快速开始

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "buckets_count": 256,
        "base_quantization_type": "sq8",
        "partition_strategy_type": "ivf",
        "ivf_train_type": "kmeans"
    }
})";
auto index = vsag::Factory::CreateIndex("ivf", params).value();

// 构建索引。
auto base = vsag::Dataset::Make();
base->NumElements(n)->Dim(128)->Ids(ids)->Float32Vectors(data)->Owner(false);
index->Build(base);

// 执行检索。
auto query = vsag::Dataset::Make();
query->NumElements(1)->Dim(128)->Float32Vectors(q)->Owner(false);
auto result = index->KnnSearch(
    query, /*topk=*/10,
    R"({"ivf": {"scan_buckets_count": 16}})").value();

支持的输入数据类型

当前公开的 Build、Add 和检索路径接收通过 Dataset::Float32Vectors 提供的 FP32 向量，dtype 应设为 "float32"。base_quantization_type 选择的是内部编码和存储，不会使 API 接受 FP16/BF16 输入。创建 IVF 索引时不支持 dtype: "int8"。

构建参数

构建参数放在 index_param 下。完整列表请见 索引参数。

precise_codes_layout: "bucket" 要求 use_reorder: true，支持 memory_io、 block_memory_io、buffer_io、async_io 和 uring_io （需要构建环境支持 io_uring）。不支持 mmap_io 和 pqfs 精排量化。bucket 布局当前 要求 buckets_per_data: 1；一个向量分配到多个 bucket 的配置会被拒绝。

对于 flat 和 bucket 两种布局，序列化后的精排 codes 都可以通过外部 Reader 只读加载。向 Index::Load 传入 precise_io_type: "reader_io" 和 precise_reader。 flat 布局的 reader 必须恰好对应 high_precision_codes block payload，bucket 布局 则必须对应 ivf_precise_bucket block payload。启用 precise_enable_read_cache 后， reader_io 会使用通用读缓存。

vsag::LoadParameters load_parameters;
load_parameters.Set("precise_io_type", "reader_io")
    .Set("precise_enable_read_cache", true)
    .Set("precise_cache_total_size", 256ULL * 1024 * 1024)
    .SetReader("precise_reader", precise_codes_reader);
auto loaded = vsag::Index::Load(stream, load_parameters).value();

reader_io 是加载与查询阶段的只读放置策略。构建时应使用可写的 precise IO，序列化后 再在查询服务加载索引时绑定外部 reader。

buckets_count 的经验值一般为 sqrt(N) ~ 4 * sqrt(N)，其中 N 是语料规模。

检索参数

检索参数放在 ivf 子对象下：

auto result = index->KnnSearch(
    query, topk,
    R"({"ivf": {"scan_buckets_count": 32, "factor": 2.0, "parallelism": 4}})").value();

auto fast_result = index->KnnSearch(
    query, topk,
    R"({"ivf": {"scan_buckets_count": 32, "factor": 2.0, "enable_reorder": false}})").value();

何时选择 IVF

• 超大规模语料（数亿及以上），工作集无法完全放入内存。
• 对每秒查询数（QPS）敏感、对单次延迟相对宽松的批量或高吞吐场景。
• 内存紧张的部署，可使用激进的量化方案（sq8、sq4_uniform、pq、pqfs）配合 use_reorder 恢复召回。
• 对切片友好的部署：桶天然映射到分片或磁盘块。

对于延迟敏感、要求高召回的稠密 embedding 场景，请优先比较 HGraph。

相关文档

• 创建索引
• 索引参数
• 序列化格式

SINDI

SINDI（Sparse INverted Dense Index）是 VSAG 面向 稀疏向量 的索引—— 例如 BM25、SPLADE 以及其他学习稀疏（learned sparse）编码器产出的向量。与稠密索引 （HGraph、IVF）不同，SINDI 直接在“词项-权重”对上工作，是 VSAG 中接受 dtype: "sparse" 的索引之一。

• 源码：src/algorithm/sindi/
• 示例：examples/cpp/109_index_sindi.cpp

工作原理

1. 基于窗口的倒排表。 文档按固定窗口大小（window_size）分组，每个窗口独立维护一套 倒排表——即“词项 → (doc_id, value) 列表”的映射。
2. 可选的剪枝与量化。 构建时可通过 doc_prune_ratio 按文档粒度丢弃权重最低的词项； use_quantization: true 使用 SQ8，use_quantization: "fp16" 使用半精度值。
3. 打分。 检索时，SINDI 遍历查询向量的非零项，按窗口访问对应的倒排表，使用大小为 n_candidate 的大顶堆聚合得分，最后取 top-k。启用 use_reorder 时，候选会在正排 存储上重打分。默认正排存储保留 fp32 值；设置 rerank_type: "dmq8" 时使用压缩的 DMQ 正排以降低重排内存。

返回的距离为 1 - inner_product，使结果与稠密索引一样按升序排序。

需要同时支持内存与磁盘 I/O 时，请选择 SINDI_V2。

快速开始

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "sparse",
    "metric_type": "ip",
    "dim": 1024,
    "index_param": {
        "term_id_limit": 30000,
        "window_size": 50000,
        "doc_prune_ratio": 0.0,
        "use_quantization": false,
        "use_reorder": false,
        "remap_term_ids": false
    }
})";
auto index = vsag::Factory::CreateIndex("sindi", params).value();

// 使用 SparseVector 构建数据集。
auto base = vsag::Dataset::Make();
base->NumElements(n)
    ->SparseVectors(sparse_vectors)  // vsag::SparseVector*
    ->Ids(ids)
    ->Owner(false);
index->Build(base);

// 执行检索。
auto query = vsag::Dataset::Make();
query->NumElements(1)->SparseVectors(&query_vec)->Owner(false);
auto result = index->KnnSearch(
    query, /*topk=*/10,
    R"({"sindi": {"n_candidate": 100}})").value();

构建参数

构建参数放在 index_param 下。dtype 必须 为 "sparse"，metric_type 必须 为 "ip"。

dim 与 term_id_limit 的区别。 对于稀疏向量 {0:0.1, 2:0.5, 177:0.8}， dim 为 3（三个非零项），而 term_id_limit 至少应为 178（最大词项 ID + 1）。 term_id_limit 要按词表大小估计，这是使用时最常见的坑。

稀疏值格式

use_quantization 保留原有 bool 行为，同时新增一个字符串取值：

使用 false 或 true 构建的索引仍保留旧版序列化表示。旧版本 VSAG 无法解析使用新 "fp16" 格式的 SINDI 索引；部署 FP16 产物前应先升级读取端。

不可变低内存构建

完成后的 SINDI 只读时，可以设置 immutable: true：

{
    "dtype": "sparse",
    "metric_type": "ip",
    "dim": 1024,
    "index_param": {
        "term_id_limit": 30000,
        "window_size": 50000,
        "use_quantization": "fp16",
        "remap_term_ids": true,
        "immutable": true
    }
}

Build() 会把每个完成的可变窗口压缩成不可变 payload，并在继续构建前释放临时窗口。该功能 提交时的 Sparse4M FP16 实测中，构建峰值内存从 27.03 GB 降到 6.08 GB（降低 77.51%）， 构建时间则从约 330 秒增加到 599 秒。这些数字是特定负载的实测证据，不是容量保证。

不可变运行态支持 KNN、范围搜索以及旧版 Serialize/Deserialize。它不支持增量 Add、GetSparseVectorByInnerId、CalcDistanceById 与 CalDistanceById。 mutable 和 immutable 运行态均支持 SerializeStreaming、DeserializeStreaming 与 Index::Load。 反序列化时，新建 SINDI 的 immutable 设置必须与存储格式一致。 新索引会记录有序倒排链格式版本，加载时可跳过归一化排序；缺少该标记的旧索引仍保持兼容， 并在加载时完成排序归一化。

Host 过滤

mutable 和 immutable SINDI 及 SINDI_V2 索引都可以按单值数值 host 对文档 分组，避免返回其他 host 的文档。host-aware Build() 或 mutable Add() 批次需要提供完整的 uint32_t host_id 数组；没有 host 的文档使用 0：

base->NumElements(n)
    ->SparseVectors(sparse_vectors)
    ->Ids(ids)
    ->UInt32Metadata("host_id", base_host_ids)
    ->Owner(false);
index->Build(base);

uint32_t query_host_id = 42;
query->NumElements(1)
    ->SparseVectors(&query_vec)
    ->UInt32Metadata("host_id", &query_host_id)
    ->Owner(false);

每个 Build() 或 mutable Add() 批次都会按 host 对 inner ID 分组，同时保持 external label 不变。host 查询统一扫描相关 posting window，并在该 host 的一个或多个 inner-ID 区间上执行 精确成员检查。多次 mutable Add() 可以为同一 host 追加互不连续的区间；删除标记和额外的 用户 Filter 会与 host 成员检查共同生效。

host ID 0 是缺失 host 分组，1 到 UINT32_MAX 表示普通 host；不同 host 的数量不能超过 成功写入索引的文档数。mutable 索引一旦包含 host metadata，后续每次 Add() 都必须提供 完整的 host_id 数组；已有 host-unaware 文档后不能再引入 host metadata。查询 host_id: 0 时只检索缺失 host 的文档，不提供 host_id 时保留全索引 KNN 行为；查询没有 已索引文档的 host 返回空结果。构建时没有 base host metadata 的索引会忽略查询 host metadata，行为保持不变。host 过滤当前仅适用于 KNN；范围搜索仍使用原有全索引路径。

检索参数

检索参数放在 sindi 子对象下：

合并 ratio 与 threshold 限制后，每条非空倒排链至少扫描一个 posting。

同一 window 内的单 term posting 先按实际存储值降序排列，值相同时按内部 doc id 升序排列。ratio 和 threshold 同时生效时，实际扫描 floor(list_size · (1 - ratio)) 与 floor(threshold / window_count) 中的较小值。 SINDI 会根据构建阶段的 doc_prune_ratio 与检索阶段的 query_prune_ratio 自动选择堆插入策略。按当前 0.1 阈值，当两个比例都 <= 0.1 时，SINDI 使用 基于距离数组的入堆路径；只要任一比例大于 0.1，就使用基于 term-list 的入堆路径。 旧版 use_term_lists_heap_insert 检索参数会被忽略；请改用剪枝比例控制该行为。

auto result = index->KnnSearch(
    query, topk,
    R"({"sindi": {"n_candidate": 200, "filter_callback_limit": 10000, "query_prune_ratio": 0.1}})").value();

何时选择 SINDI

• 使用 BM25、SPLADE、uniCOIL 等学习稀疏编码器的稀疏检索场景。
• 稠密 + 稀疏的混合检索管线：SINDI 负责稀疏一路，HGraph / IVF 负责稠密 embedding。
• 稀疏语料的内存受限部署：use_quantization: true 选择 SQ8，"fp16" 把 FP32 权重字节数减半； use_reorder: true 以正排内存换召回，rerank_type: "dmq8" 可降低这部分正排开销。
• 需要降低构建峰值内存的只读快照：使用 immutable: true，接受更慢的构建和不能增量写入。

SINDI 不支持 稠密向量，只支持内积相似度。范围检索与基于 ID 的过滤均已支持， 具体用法参见示例代码。 当 rerank_type 为 dmq8 时，码本由首次构建固定，因此模型建立后的增量 Add 和 UpdateVector 不受支持。

实践建议

• 中文数据集的稀疏向量，推荐使用 BGE-M3 编码；英文数据集更常见的默认选择是 SPLADE。
• BGE-M3 同时支持 sparse 和 dense 输出。当前 SINDI 负责稀疏一路，VSAG 未来计划 支持稀疏与稠密融合打分检索。
• 稀疏向量不能完全替代 BM25 全文检索。实践中，BM25 + 稀疏向量 + 稠密向量的三路 召回通常优于任意两路组合。
• 在索引层面，SINDI 也可以承载 BM25 风格打分：查询侧用逆文档频率作为词项权重， 文档侧用词频等特征计算出的词项权重作为向量值即可。

常用配置

1. 扁平暴力搜索索引。倒排索引保留全部非零项（doc_prune_ratio: 0.0），不保留正排索引 重排（use_reorder: false），不开启量化（use_quantization: false）。这是最直接的 高召回基线。
2. 剪枝高精索引。构建时剪掉大部分低权重词项（doc_prune_ratio: 0.4），保留正排索引 用于重排（use_reorder: true），并开启量化减少倒排索引内存 （use_quantization: true）。这是常见的精度与内存折中配置。
3. 压缩正排重排索引。在上一种配置基础上，设置 rerank_type: "dmq8"，与 use_reorder: true 一起使用，以降低正排重排内存。
4. 超大稀疏词表支持。对于词项 ID 在 uint32 范围内非常稀疏的场景，例如基于哈希的 分词器、外部词表 ID，或存在大量空白区间的词表，建议设置 remap_term_ids: true。 这样可以避免管理大量空倒排列表带来的内存浪费，也能降低触达 term_id_limit 上限的风险。
5. 只读低内存构建。当构建峰值内存比构建速度更重要，且完成后不再增量写入时，增加 immutable: true，通常配合 use_quantization: "fp16" 与 remap_term_ids: true 使用。

标记删除

SINDI 支持 RemoveMode::MARK_REMOVE。调用 Remove(ids)（默认模式）会为给定的 id 打上删除标记：它们不再出现在检索结果中，GetNumElements() 相应减少， GetNumberRemoved() 返回累计删除数量。删除不存在或已删除的 id 不会有任何效果。 RemoveMode::FORCE_REMOVE 不支持，调用会返回错误。

被标记删除的文档在索引重建前仍占用内存，空间不会被物理回收。

相关文档

• 创建索引
• 索引参数
• k-近邻搜索

SINDI_V2

SINDI_V2 是 VSAG 的 term-first 稀疏向量索引。它与 SINDI 使用相同的窗口化倒排检索模型和 1 - inner_product 距离定义，但按 term 保存 posting，因此搜索时只需读取查询实际使用的倒排链。

• 工厂入口：sindi_v2
• 源码：src/algorithm/sindi_v2/
• dtype 必须为：sparse
• metric_type 必须为：ip

存储布局

每个 term payload 只保存非空 window：

non_empty_window_count
ordered {window_id, posting_count}[]
local_doc_ids[]
alignment padding
encoded_values[]

查询时，SINDI_V2 将稀疏 metadata 展开为 window_count + 1 个 window offset， 并通过 reader_io、mmap_io、buffer_io、async_io 或内存后端，只加载 查询保留 term 对应的 posting。

这与 SINDI 的 window-first 序列化不同。两个工厂入口使用不同的持久化格式， 加载索引时不能互换。

快速开始

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "sparse",
    "metric_type": "ip",
    "dim": 1024,
    "index_param": {
        "term_id_limit": 30000,
        "window_size": 50000,
        "doc_prune_ratio": 0.1,
        "use_quantization": true,
        "use_reorder": true,
        "remap_term_ids": true,
        "term_io": {
            "type": "buffer_io",
            "file_path": "/tmp/sindi_v2.terms"
        },
        "rerank_io": {
            "type": "block_memory_io"
        }
    }
})";
auto index = vsag::Factory::CreateIndex("sindi_v2", params).value();
index->Build(base);

auto result = index->KnnSearch(
    query, 10,
    R"({"sindi_v2": {
        "n_candidate": 100,
        "query_prune_ratio": 0.1,
        "term_prune_ratio": 0.2,
        "term_retain_threshold": 10000
    }})").value();

构建参数

构建参数放在 index_param 下。

文件型 term_io 支持 mmap_io、buffer_io 和 async_io，并要求设置 file_path。文件型 rerank_io 未设置 file_path 时，VSAG 使用 <term_io.file_path>.rerank。

rerank_layout > 0 要求 use_reorder: true。rerank_type: "dmq8" 要求 rerank_layout: 0，并使用默认的 block_memory_io 重排后端。

Host 过滤

SINDI_V2 支持与 SINDI 相同的 uint32_t host_id 构建数据和 KNN 查询 metadata 约定。mutable 与 immutable 索引均支持该功能。两者共用 host 分组与路由组件，同时 SINDI_V2 保持自己的 term-first posting 存储。host 成员检查统一在 posting-window 检索中执行， 并支持 mutable Add() 产生的多个区间。缺失 host ID 0、mutable Add() metadata、streaming 序列化及仅支持 KNN 的规则均与 SINDI 相同。

检索参数

检索参数放在 {"sindi_v2": {...}} 下。

合并 ratio 与 threshold 限制后，每条非空 term list 至少扫描一个 posting。

SINDI V2 会根据构建阶段的 doc_prune_ratio 与检索阶段的 query_prune_ratio 自动选择堆插入策略。按当前 0.1 阈值，当两个比例都 <= 0.1 时，使用基于距离数组的 入堆路径；只要任一比例大于 0.1，就使用基于 term-list 的入堆路径。

如何选择 SINDI 与 SINDI_V2

完整稀疏索引常驻内存、且 window-first 序列化合适时选择 SINDI。需要按 term 组织持久化 posting，或希望搜索时只从外部存储读取查询 term list 时选择 SINDI_V2。

SIMQ

SIMQ 是 VSAG 面向 多向量（multi-vector） 检索的索引——适用于每篇文档 由一组 token 级向量（而非单个 embedding）表示的数据场景。这种模式常见于 ColBERT 等 late-interaction 模型，其中文档由每个 token 对应一个向量表示， 相关性通过 MaxSim（各查询 token 的最大相似度之和）计算。

• 源码：src/algorithm/simq/

工作原理

1. Token 向量动态聚类。 构建阶段，所有文档的全部 token 向量被抽取到一个 扁平池中，使用基于 HGraph 的动态聚类算法进行聚类。初始聚类中心按 init_cluster_ratio 控制的比例采样；超过 max_cluster_size 的簇会被增量切分。
2. 代表性图用于粗排。 在簇中心上构建一个代表性 HGraph。检索时，每个查询 token 在该图上搜索最近的若干个簇（由 coarse_k 控制），跨查询 token 累加簇得分，得到候选集。
3. 精确 MaxSim 精排。 对得分最高的 rerank_k 个候选文档，从磁盘（或内存） 读回原始 token 向量，计算查询 token 与文档 token 之间的精确 MaxSim 相似度。

聚类粗排与精确精排的两阶段结合， 为多向量检索提供了可调的召回率/延迟权衡。

快速开始

#include <vsag/vsag.h>

std::string build_params = R"({
    "dtype": "float32",
    "metric_type": "ip",
    "dim": 256,
    "index_param": {
        "base_io_type": "async_io",
        "base_file_path": "/path/to/simq_base_codes.bin",
        "init_cluster_ratio": 0.1,
        "max_cluster_size": 160,
        "split_start_idx": 80,
        "random_seed": 42,
        "coarse_k": 50,
        "rerank_k": 1000
    }
})";
auto index = vsag::Factory::CreateIndex("simq", build_params).value();

// 使用 MultiVector 构建数据集。
// 每篇文档包含可变数量的 token 向量，每个向量维度为 dim。
std::vector<vsag::MultiVector> base_mvs(num_docs);
std::vector<int64_t> ids(num_docs);
for (int64_t i = 0; i < num_docs; ++i) {
    base_mvs[i].len_ = doc_token_counts[i];             // 文档 i 的 token 数量
    base_mvs[i].vectors_ = doc_token_vectors[i];        // 扁平数组：len_ * dim 个 float
    ids[i] = i;
}
auto base = vsag::Dataset::Make();
base->NumElements(num_docs)
    ->Dim(dim)
    ->Ids(ids.data())
    ->MultiVectors(base_mvs.data())
    ->MultiVectorDim(dim)
    ->Owner(false);
index->Build(base);

// 使用多向量查询进行检索。
vsag::MultiVector query_mv;
query_mv.len_ = query_token_count;
query_mv.vectors_ = query_token_vectors;
auto query = vsag::Dataset::Make();
query->NumElements(1)
    ->Dim(dim)
    ->MultiVectors(&query_mv)
    ->MultiVectorDim(dim)
    ->Owner(false);

std::string search_params = R"({
    "simq": {
        "coarse_k": 600,
        "rerank_k": 5000
    }
})";
auto result = index->KnnSearch(query, /*topk=*/100, search_params).value();

// 读取结果。
const int64_t* result_ids = result->GetIds();
const float* result_dists = result->GetDistances();
int64_t result_count = result->GetDim();
for (int64_t i = 0; i < result_count; ++i) {
    int64_t id = result_ids[i];
    float dist = result_dists[i];
}

构建参数

SIMQ 专属构建参数放在 index_param 下。dim、dtype、metric_type 是顶层字段。dtype 必须 为 "float32"，metric_type 必须 为 "ip"。

• dim — 所有文档和查询中的所有 token 共享同一维度
• base_io_type — 可选值：async_io、uring_io、memory_io、 block_memory_io、buffer_io、mmap_io、reader_io。原生 uring_io 需要以 liburing 构建，否则回退到 buffer_io
• base_file_path — 默认值为占位符，使用磁盘类型（async_io、 uring_io、buffer_io、mmap_io）时需提供真实路径
• init_cluster_ratio — 取值范围 (0, 1]。值越小簇越少越大， 值越大簇越多越细
• max_cluster_size — 必须 > 1
• split_start_idx — 通常设为 max_cluster_size 的一半， 取值范围 (1, max_cluster_size)
• coarse_k、rerank_k — 必须 > 0

聚类参数的选择。 init_cluster_ratio 与 max_cluster_size 共同控制 簇的数量与大小。较小的 init_cluster_ratio 搭配较大的 max_cluster_size 会产生更少的簇，粗排更快但召回降低。建议以 init_cluster_ratio = 0.1–0.2、 max_cluster_size = 2 × split_start_idx 为起点，再通过检索参数调优。

检索参数

检索参数放在 simq 子对象下：

• coarse_k — 覆盖构建时的值。值越大候选范围越广， 召回越高但延迟也越大
• rerank_k — 覆盖构建时的值。值越大召回越高， 但磁盘读取和计算开销也越大
• 不设置时使用构建时的默认值。显式设置时两个值都必须 > 0

auto result = index->KnnSearch(
    query, topk,
    R"({"simq": {"coarse_k": 600, "rerank_k": 5000}})").value();

搜索统计

KnnSearch 与 RangeSearch 会在返回的 dataset 上附带 JSON 统计对象。可以读取完整对象， 也可以按 key 获取单项值：

std::cout << result->GetStatistics() << '\n';
auto values = result->GetStatistics(
    {"simq_coarse_candidate_count", "simq_rerank_candidate_count"});

这些计数器可以在调节召回和延迟时，区分候选池过窄、过滤、精排和输出上限各自的影响。

何时选择 SIMQ

• Late-interaction 检索：使用 ColBERT 等模型，每篇文档是一组 token 向量， 相关性通过 MaxSim 计算。
• 多向量粒度匹配：单 embedding 丢失过多信息，需要 token 级细粒度匹配。
• 大规模多向量语料：暴力 MaxSim 检索过慢，需要粗排 + 精排的两阶段管线 来平衡召回与延迟。

SIMQ 仅接受 float32 多向量数据，仅支持内积相似度。 不支持 单稠密向量或稀疏向量（请使用 HGraph 或 SINDI）。

实践建议

• 调整 coarse_k 与 rerank_k。 增大 coarse_k 扩大簇级候选范围； 增大 rerank_k 让更多文档进入精确打分。实践中 rerank_k 对召回的影响 更大，但每个额外候选都需要一次磁盘读取和完整的 MaxSim 计算，延迟也会增加。
• IO 类型选择。 语料规模超出内存时使用 async_io；多向量数据可以放入 内存时，使用 memory_io 或 block_memory_io 获得最低的精排延迟。
• 簇大小配置。 将 max_cluster_size 设为 split_start_idx 的约两倍。切分位置 决定了簇溢出时 token 向量的分配方式，居中设置可使两半保持平衡。

MultiVector 字段说明

相关文档

• 创建索引
• 索引参数
• k-近邻搜索

Pyramid

Pyramid 是 VSAG 的 层级路径分区 图索引。每条向量都附带一个路径字符串（例如 "a/d/f"），Pyramid 会按路径树为每个节点构建一个子图；查询时提供一个路径前缀， 检索即被限定在相应的子树内。

这种设计非常适合多租户部署、标签分区的物料库，或者任何“一个逻辑索引服务多个群体、 群体之间不允许结果交叉”的场景。

• 源码：src/algorithm/pyramid.{h,cpp}、src/algorithm/pyramid_zparameters.{h,cpp}
• 示例（单层级）：examples/cpp/107_index_pyramid.cpp
• 示例（多层级）：examples/cpp/112_index_pyramid_multi_hierarchy.cpp

工作原理

1. 路径树。 每条向量在 ID 之外还携带一个 path，分隔符为 / （例如 "tenant_a/lang_en/topic_news"）。Pyramid 会为构建期间出现过的每个路径前缀 维护一个子索引。
2. 按层构建子图。 默认情况下每一层都会独立构建一张近邻图。可以用 no_build_levels 跳过那些太小或太粗、不适合构图的层级——这些层级仍作为透传容器存在，但检索会退化为 线性扫描。
3. 图的构建。 每个子图与 HGraph 采用同一套机制：nsw 插入或 odescent，并通过 graph_iter_turn、neighbor_sample_rate、alpha 控制构图剪枝。底层向量按 base_quantization_type 存储；启用精排时另外保留一份高精度副本。
4. 检索。 查询向量同样要附带路径。搜索会顺路径树向下走到最具体匹配查询路径的子图， 然后在该子图内执行图检索（ef_search；中间层由 subindex_ef_search 控制）。

快速开始

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 32,
        "alpha": 1.2,
        "graph_type": "odescent",
        "graph_iter_turn": 15,
        "neighbor_sample_rate": 0.2,
        "no_build_levels": [0, 1],
        "use_reorder": true,
        "build_thread_count": 16
    }
})";
auto index = vsag::Factory::CreateIndex("pyramid", params).value();

// 构建时为每条向量提供路径。
auto base = vsag::Dataset::Make();
base->NumElements(n)
    ->Dim(128)
    ->Ids(ids)
    ->Paths(paths)          // std::string* 长度为 n，例如 "a/d/f"
    ->Float32Vectors(data)
    ->Owner(false);
index->Build(base);

// 按路径前缀执行检索。
std::string query_path = "a/d";
auto query = vsag::Dataset::Make();
query->NumElements(1)
    ->Dim(128)
    ->Float32Vectors(q)
    ->Paths(&query_path)
    ->Owner(false);
auto result = index->KnnSearch(
    query, /*topk=*/10,
    R"({"pyramid": {"ef_search": 100}})").value();

支持的输入数据类型

当前公开的 Build、Add 和检索路径接收通过 Dataset::Float32Vectors 提供的 FP32 向量，dtype 应设为 "float32"。base_quantization_type 选择的是内部编码和存储，本身不会使 API 接受 FP16、BF16 或 INT8 输入。

构建参数

构建参数放在 index_param 下。

RaBitQ split 配置

需要同时设置以下五个参数，才能启用 RaBitQ x+y split 存储和精排：

{
    "use_reorder": true,
    "base_quantization_type": "rabitq",
    "precise_quantization_type": "rabitq",
    "rabitq_bits_per_dim_base": 3,
    "rabitq_bits_per_dim_precise": 5
}

Pyramid 使用 split code 的 code-code 距离完成增量 FLAT→GRAPH 晋升，因此默认不保留 内部 FP32 副本。需要访问原始向量或完整 Analyzer 指标时，可在构建时将 store_raw_vector 设置为 true。

MRLE 与 split RaBitQ

对于使用 Matryoshka Representation Learning 训练的向量，Pyramid 可以先截断维度，再编码 为 split RaBitQ：

{
    "base_quantization_type": "tq",
    "tq_chain": "mrle, rabitq",
    "mrle_dim": 1280,
    "precise_quantization_type": "rabitq",
    "rabitq_bits_per_dim_base": 3,
    "rabitq_bits_per_dim_precise": 5,
    "use_reorder": true
}

该配置使用 3-bit filter planes 构图和搜索、5-bit supplement planes 精排；两部分编码的是 同一个截断后向量。Pyramid 使用 split code-code 距离完成构图提升，不保留原始 FP32 向量；除非构建时启用 store_raw_vector，否则依赖可解码向量的 Analyzer 指标会被标记为 不可用。如果 embedding 模型没有针对前缀维度训练，截断可能显著降低召回率。

构建缓存

ExportCache 会保存每个层级、每个节点的 NSW 图种子，ImportCache 可在后续 Build 中复用。缓存数据使用索引缓存 payload 格式，而非 streaming 索引序列化格式。需要复用缓存的索引通过 footer 序列化前应设置 persist_source_id: true，并且两次构建中的每个向量都必须提供唯一的 Dataset::SourceID。缓存预热仅适用于 graph_type: "nsw"；ODescent、重复 ID 模式、缺少 source ID 或 source ID 重复时会自动回退到普通冷构建。ef_construction 不作为缓存路径的准入条件。完整恢复的缓存图行会被保留，缓存未命中的节点则使用当前向量构建。

检索参数

检索参数放在 pyramid 子对象下：

auto result = index->KnnSearch(
    query, topk,
    R"({"pyramid": {"ef_search": 200, "subindex_ef_search": 80}})").value();

多层级支持 (Multi-Hierarchy)

一个 Pyramid 索引可以同时维护多棵独立的路径树，每棵树由名称标识（如 "site"、"category"）。所有层级共享向量 ID 和数据——只有路径不同。每个层级可以 选择性地覆盖图构建参数。

当同一组向量需要沿多个维度同时分区时，这个特性非常有用。例如，一个电商平台可能 需要按站点（site-a/lang-en）和按品类（electronics/phones）同时分区， 检索时可以独立选择任一层级。

构建配置

在 index_param 中添加 hierarchies 数组。每个元素可以是：

• 字符串（继承全部顶层参数）："site"
• 对象（含 name 和可选的参数覆盖）： {"name": "category", "max_degree": 64, "no_build_levels": [0]}

可按层级覆盖的参数：max_degree、ef_construction、alpha、no_build_levels、 index_min_size、root_graph_type。

root_graph_type: "multi_layer" 只改变所选层级的根节点。底图使用顶层 graph_storage_type：默认使用 Flat，也可使用 Compressed，以构建和检索速度换取更低的图 内存；路由图和子图仍使用 Sparse。稀疏路由图先选择更好的入口点，再进入底图检索。批量 Build 与增量 Add 都使用类似 HGraph 的 route 与 bottom 联合插入流程。该结构要求 graph_type: "nsw"；参数校验会拒绝 multi_layer 与 odescent 的组合。存在独立 precise storage 时，底图和路由图的边统一使用 precise codes 构建，否则使用 base codes；查询遍历 继续使用 base codes，最终精排使用配置的 reorder source。

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 32,
        "alpha": 1.2,
        "graph_type": "odescent",
        "graph_iter_turn": 15,
        "neighbor_sample_rate": 0.2,
        "no_build_levels": [0, 1],
        "use_reorder": true,
        "build_thread_count": 16,
        "hierarchies": [
            "site",
            {"name": "category", "max_degree": 64, "no_build_levels": [0]}
        ]
    }
}

命名层级的 Dataset API

使用重载方法 Paths(hierarchy_name, paths) 为每个层级设置路径。所有层级共享同一份 Ids() 和 Float32Vectors()：

auto base = vsag::Dataset::Make();
base->NumElements(n)
    ->Dim(128)
    ->Ids(ids)
    ->Float32Vectors(data)
    ->Paths("site", site_paths)         // std::string* 长度为 n
    ->Paths("category", category_paths) // 第二个层级的独立路径
    ->Owner(false);
index->Build(base);

按 ID 取回路径

将顶层构建参数 store_paths 设为 true 后，Pyramid 会保留原始路径，供按 ID 取回。在 GetDataByIdsWithFlag 中选择 DATA_FLAG_PATH 后，返回路径的顺序与请求 ID 的顺序一致。默认匿名 hierarchy 使用 GetPaths()，命名 hierarchy 使用 GetPaths(hierarchy_name)：

int64_t requested_ids[] = {product_id_b, product_id_a};
auto data = index->GetDataByIdsWithFlag(
    requested_ids, 2, DATA_FLAG_ID | DATA_FLAG_PATH).value();

const std::string* site_paths = data->GetPaths("site");
const std::string* category_paths = data->GetPaths("category");

GetDataByIds 以及未选择 DATA_FLAG_PATH 的 GetDataByIdsWithFlag 都不会附带路径 数组。store_paths 为 false 时选择 DATA_FLAG_PATH 会返回参数错误。开启路径存储 后，只有当所有请求 ID 在某个 hierarchy 中都有已记录的路径，结果才会包含该 hierarchy。只要其中一个 ID 在构建或追加时没有提供该 hierarchy 的路径，对应 getter 就返回 nullptr；其他路径完整的 hierarchy 仍会正常返回。单 hierarchy 模式下， GetPaths() 遵循相同的完整性规则。

检索指定层级

通过检索参数中的 "hierarchies" 指定要检索的层级。查询 Dataset 也需要在对应的 层级名称上设置路径：

auto query = vsag::Dataset::Make();
query->NumElements(1)
    ->Dim(128)
    ->Float32Vectors(q)
    ->Paths("site", &query_path)   // 指向 "site" 层级
    ->Owner(false);

auto result = index->KnnSearch(
    query, /*topk=*/10,
    R"({"pyramid": {"ef_search": 100, "hierarchies": ["site"]}})").value();

增量插入 (Add)

Add() 的用法与 Build() 一致——提供命名路径，索引会自动插入到所有匹配的层级：

auto new_data = vsag::Dataset::Make();
new_data->NumElements(count)
    ->Dim(128)
    ->Ids(new_ids)
    ->Float32Vectors(new_vectors)
    ->Paths("site", new_site_paths)
    ->Paths("category", new_cat_paths);
index->Add(new_data);

范围检索 (RangeSearch)

RangeSearch 同样支持通过检索参数选择层级：

auto result = index->RangeSearch(
    query, /*radius=*/20.0f,
    R"({"pyramid": {"ef_search": 100, "hierarchies": ["category"]}})").value();

序列化与反序列化

多 hierarchy 索引的序列化和反序列化完全透明。序列化格式包含所有 hierarchy 名称及其图结构。当 store_paths: true 时，常规序列化和 streaming 序列化还会持久化 已保留的原始路径，因此反序列化后仍可通过 GetDataByIdsWithFlag 获取。使用默认值 false 时，图 hierarchy 会被持久化，但不会保留按 ID 索引的原始路径：

// 序列化
auto binary_set = index->Serialize().value();

// 反序列化到新索引（必须使用相同的构建参数）
auto new_index = vsag::Factory::CreateIndex("pyramid", build_params).value();
new_index->Deserialize(binary_set);

何时选择 Pyramid

• 多租户服务：每个租户只能看到自己分区的结果，且希望避免为每个租户单独维护一份索引。
• 带有层级标签的物料库（语言 / 地域 / 品类），查询永远限定在某个已知的前缀下。
• 小分区非常多的负载：可以用 no_build_levels 与 index_min_size 跳过那些小到不值得 构图的分区。

如果不需要按路径限定查询范围，HGraph 更简洁，性能通常也更高。

可以通过索引分析检查 Pyramid 的树结构、子索引质量、 GetStats() 输出的 base 采样召回率和重复比例。每个 hierarchy 的 root_graphs 会报告 root_graph_type、bottom_graph_storage_type、bottom_graph_node_count、 bottom_graph_size、route_graph_count、route_node_counts 和 route_graph_size。 AnalyzeIndexBySearch 还会输出按路径限定的 query 召回率、距离、耗时，以及开启 reorder 时的量化指标。query 数据集必须包含与 KnnSearch 相同的默认或命名 hierarchy 路径；批量数据集在需要或提供路径时，应为每条 query 提供一条路径。analyze_index 工具当前无法从 dense query 文件加载 hierarchy 路径，因此 按路径执行动态分析时请使用 C++ 接口。

标记删除

Pyramid 支持 RemoveMode::MARK_REMOVE。调用 Remove(ids)（默认模式）会为给定的 id 打上删除标记：它们会从后续检索结果中排除，GetNumElements() 相应减少， GetNumberRemoved() 返回累计删除数量。删除不存在或已删除的 id 不会有任何效果。 RemoveMode::FORCE_REMOVE 不支持，调用会返回错误。

被标记删除的向量在索引重建前仍占用内存，空间不会被物理回收。

相关文档

• 创建索引
• 索引参数
• 图索引增强
• HGraph

BruteForce

BruteForce 是 VSAG 提供的精确扁平索引。查询时直接对语料中的每条向量计算距离并返回真实的 top-k —— 没有图遍历、没有倒排表、不做近似。它的主要用途是为 HGraph、IVF 等近似索引提供 ground truth 基准，也适合用于小规模语料或对召回率有严格要求的生产场景。

• 源码：src/algorithm/bruteforce/bruteforce.{h,cpp}
• 示例：examples/cpp/105_index_brute_force.cpp

工作原理

1. Build。 向量按照 base_quantization_type（默认 fp32，即原始精度）编码后保存到一个 扁平数据单元中。对于不压缩的量化器，不需要训练；当使用 PQ/SQ_uniform 等需要训练的量化器 时，Build 会先跑一遍训练。
2. Add。 新向量直接追加到扁平存储中，没有再平衡或重建成本。
3. Search。 针对每条查询，按照配置的 metric_type（l2、ip 或 cosine）逐条计算 距离，再用 top-k 小顶堆得到最近邻 id。距离计算使用 SIMD 内核，并支持单查询内并行： 通过 parallelism 搜索参数可以把同一条查询的扫描拆分到多个线程上（实现见 BruteForce::SearchWithRequest，src/algorithm/brute_force.cpp）。

由于索引保留了每一条向量（除非选择了有损量化器），当 base_quantization_type = fp32 时 结果是完全精确的，因此 eval_performance 工具默认用 BruteForce 作为生成 ground truth 的 参考索引。

快速开始

#include <vsag/vsag.h>

std::string params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128
})";
auto index = vsag::Factory::CreateIndex("brute_force", params).value();

// 构建。
auto base = vsag::Dataset::Make();
base->NumElements(n)->Dim(128)->Ids(ids)->Float32Vectors(data)->Owner(false);
index->Build(base);

// 搜索 —— 没有索引特有的旋钮，传空 JSON 即可（也可以设置 `parallelism`）。
auto query = vsag::Dataset::Make();
query->NumElements(1)->Dim(128)->Float32Vectors(q)->Owner(false);
auto result = index->KnnSearch(query, /*topk=*/10, "{}").value();

完整可运行示例见 examples/cpp/105_index_brute_force.cpp。

支持的输入数据类型

当前公开的 Build、Add、KnnSearch、RangeSearch 与 UpdateVector 路径仅接受 FP32 向量。运行时通过 Dataset::Float32Vectors 传入向量；创建索引时 dtype 应设为 "float32"，不支持 dtype: "int8"。

base_quantization_type 描述的是索引内部编码和存储，而非输入类型。选择内部 fp16、bf16 等量化器不会使 API 接受 FP16/BF16 输入。

构建参数

最简配置只需要三个顶层字段（dtype、metric_type、dim）。大多数场景下不需要 index_param，这也是 示例 105 所采用的形式。进阶用法可通过 index_param 启用量化或存储相关的开关：

关于 store_raw_vector 的说明。 store_raw_vector 字段会被共用的 InnerIndexParameter 解析，但 BruteForce 不会根据它决定是否启用 GetRawVectorByIds。在 BruteForce 上，原始向量读取能力仅在 base_quantization_type = fp32、并且度量不是 cosine 或量化器配置了 持有向量范数（hold_molds）时开启。在 BruteForce 上设置 store_raw_vector: true 目前不会改变任何能力标志 —— 如果需要量化索引同时 支持 GetRawVectorByIds，请使用 HGraph 或 IVF。

下面是一个使用 sq8 量化以节省内存、同时保持线性扫描语义的示例：

{
    "dtype": "float32",
    "metric_type": "ip",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8"
    }
}

当 base_quantization_type 选择了需要训练的量化器（sq8、sq4、sq8_uniform、sq4_uniform、 pq、pqfs、rabitq）时，Build 会先用传入的数据集训练量化器，此时召回率不再保证 100%。只有 fp32、fp16、bf16 不需要训练，能保持精确距离（仅受浮点数值精度影响）。

搜索参数

BruteForce 没有任何索引特有的搜索旋钮（不存在 ef、nprobe 之类的参数），但通用的 IndexSearchParameter 字段都生效：

// 默认单线程扫描。
auto r1 = index->KnnSearch(query, topk, "{}").value();

// 用 8 个线程并行扫描同一条查询。
auto r2 = index->KnnSearch(query, topk, R"({"parallelism": 8})").value();

// RangeSearch 使用同一个 parallelism 参数。
auto r3 = index->RangeSearch(query, radius, R"({"parallelism": 8})").value();

范围查询语义参见 范围搜索。

删除向量

BruteForce 同时支持 RemoveMode::MARK_REMOVE 与 RemoveMode::FORCE_REMOVE；两种模式都不需要 配置 HGraph 专用的 support_force_remove。

启用 use_attribute_filter: true 时，BruteForce 不支持任一种删除模式；如需删除属性过滤数据，请重建索引。

• MARK_REMOVE 是默认模式。它只写入墓碑标记，后续搜索会过滤该 id，但向量存储仍保持已分配状态。 GetNumElements() 不计已标记的 id，GetNumberRemoved() 返回其数量。
• FORCE_REMOVE 会物理删除请求的每条向量。必要时它用最后一个内部槽位覆盖被删除槽位，并保留被移动 向量的外部 id。成功的物理删除不会新增墓碑；之前已标记删除的数量仍由 GetNumberRemoved() 反映。

index->Remove(std::vector<int64_t>{id1, id2}, vsag::RemoveMode::MARK_REMOVE);
index->Remove(std::vector<int64_t>{id3, id4}, vsag::RemoveMode::FORCE_REMOVE);

物理删除是同步操作，开销高于标记删除。它会获取索引的全局独占锁，因此会等待进行中的搜索，并在 槽位交换与删除完成前阻止新的搜索。应尽可能批量传入 id，避免在延迟敏感路径上执行物理删除。

BruteForce 默认使用 block_memory_io 存储向量。每个成功的物理删除批次之后，逻辑大小会收缩到 存活条目数，并释放末尾完整的内存块；最后一个未填满的块会保留。可选额外信息存储也遵循相同的块粒度 回收行为。为避免反复复制整张标签表，标签表会在存活条目数不超过当前容量一半时回收其底层分配。 之后 GetMemoryUsage() 会反映紧凑后的索引。它衡量的是索引分配量，不保证进程分配器会立即把内存归还 操作系统，也不保证 RSS 立即下降。

索引能力

BruteForce 声明的能力标志如下（参见 BruteForce::InitFeatures， src/algorithm/brute_force.cpp）：

BruteForce 不支持 的能力包括：SUPPORT_UPDATE_ID_CONCURRENT、SUPPORT_EXPORT_MODEL。

适用场景

• 召回基准。 为近似索引计算 ground truth（eval_performance 工具就是这么做的）。
• 小规模语料。 几百到几十万条向量，全量扫描成本可接受，且无需做参数调优。
• 强召回需求。 完全不能容忍近似误差的业务。
• 小规模量化实验。 在同一条线性扫描流水线上对比不同 base_quantization_type 的效果， 排除图结构 / 倒排表带来的干扰。

如果数据规模更大，请优先选择 HGraph（延迟敏感、高召回）或 IVF（吞吐量优先、内存友好）。

参考

• 创建索引
• k-近邻搜索
• 范围搜索
• 属性过滤（混合搜索）
• 性能评估工具

量化

向量量化是 VSAG 中权衡内存与召回的核心手段。每种索引类型都通过一个 基础量化器（由 base_quantization_type 配置）存储向量，并可以额外保留 一个精确量化器用于重排（precise_quantization_type + use_reorder: true）。本章介绍每一种受支持的量化器：它做什么、接受哪些 JSON 参数、是否 需要训练、支持哪些度量、以及何时选用它。

存储与搜索流水线

                  +---------------------+
   原始向量 ----->|  可选变换           |   (TQ 链：pca / rom / fht / mrle)
                  +----------+----------+
                             |
                             v
                  +---------------------+
                  |   基础量化器        |   fp32 / fp16 / bf16 /
                  |                     |   sq8 / sq4 / sq8_uniform /
                  |                     |   sq4_uniform / pq / pqfs /
                  |                     |   rabitq
                  +----------+----------+
                             |
                             v
                   +-------------------+
                   |   索引存储        |   (HGraph / IVF / Pyramid /
                   |                   |    BruteForce / SINDI)
                   +---------+---------+
                             |
                             v
                    图 / 倒排链路游走
                             |
             +---------------+-----------------+
             |                                 |
    use_reorder: false                use_reorder: true
             |                                 |
             v                                 v
        top-K 结果                  +---------------------+
                                    | 精确量化器          |  重排
                                    | (默认 fp32；        |
                                    |  fp16/bf16/sq8 可)  |
                                    +----------+----------+
                                               |
                                               v
                                          top-K 结果

use_reorder 与 precise_quantization_type 并非某一具体量化器专属——只要 索引支持重排，它们就生效（见 HGraph、IVF、 Pyramid）。

支持的量化器一览

src/datacell/flatten_interface.cpp 的工厂会根据 JSON 中的 type 字段分派到具体量化器。

int8 与 sparse 不作为通用的 base_quantization_type 暴露：

• int8 在使用 dtype: "int8" 时被自动选用，并非一种压缩模式。
• sparse 为 SINDI 的倒排链表服务，密集索引不可 直接选择。

训练需求

上表中标记为是的量化器实现了 NEED_TRAIN 标志，必须先调用 Build （在输入向量上内部完成训练）或显式 Train 之后再 Add。完整生命周期见 索引构建与训练。

对 HGraph 而言，训练数据就是传给 Build 的基础向量；对 IVF 而言，先训练 聚类中心，再把残差喂给所配置的基础量化器。

度量兼容性

本章所列量化器全部支持三种稠密度量（l2 / ip / cosine）。对 cosine， 索引会在量化前对向量做归一化，因此底层量化器看不到原始模长。一些实践 要点：

• pq / pqfs 在每个子空间上做距离查表；当 pq_dim 非常小（≤ 4）， 在 ip / cosine 上比 l2 更容易受各向异性影响。
• rabitq 在输入向量去相关的情况下效果最好——要么开启 rabitq_use_fht / rabitq_pca_dim，要么用 tq 链路如 "pca, rom, rabitq" 包一层。

量化器选择

一份实用的决策树：

1. 需要精确距离或精确重排存储？ 用 fp32。
2. 只想内存减半且召回基本无损？ 用 fp16（若数据动态范围大，例如未 归一化的嵌入，则用 bf16）。
3. 想要约 4× 的内存节省并愿意启用重排？ 用 sq8（在 l2 / ip 上 想要更高 SIMD 吞吐可用 sq8_uniform）。
4. 内存紧张、可在重排前承受更大召回损失？ 用 sq4_uniform。
5. 高维向量，希望基于码本做强压缩？ 用 pq，平台支持 SIMD 路径时用 pqfs。
6. 追求最强压缩（1 比特）并能承担重排代价？ 用 rabitq，最好搭配 rabitq_use_fht: true 或 tq 链路。

对上述任何一种有损量化器，将 use_reorder: true 配合 precise_quantization_type: "fp32" 是恢复召回的标准做法，代价是额外内存； 具体行为参考 HGraph 参数表。

量化在何处暴露

并非每种索引都将所有参数都暴露为外部 key。当前情况：

• HGraph 暴露最完整的集合：base_quantization_type、 precise_quantization_type、use_reorder、base_pq_dim、 rabitq_pca_dim、rabitq_bits_per_dim_query、 rabitq_bits_per_dim_base、rabitq_bits_per_dim_precise、 rabitq_error_rate、rabitq_use_fht、sq4_uniform_trunc_rate、tq_chain （见 src/algorithm/hgraph.cpp）。
• IVF 暴露 base_quantization_type、base_pq_dim、通用重排相关 key， 以及 rabitq_pca_dim、rabitq_bits_per_dim_query、 rabitq_bits_per_dim_base、rabitq_version、rabitq_error_rate、 rabitq_use_fht 这些 RabitQ 调参 key。
• Pyramid 暴露 base_quantization_type、base_pq_dim、通用重排相关 key， 以及 RabitQ 的 PCA、底库/查询位数和 FHT 相关 key。
• BruteForce 暴露 base_quantization_type 与通用重排相关 key；部分可调项 （如 tq_chain）目前在内部接好但未作为外部 key 暴露。

每种索引的完整参数列表见对应索引页。

本章内容

• FP32（基线）
• 半精度浮点（FP16 / BF16）
• 标量量化（SQ4 / SQ8）
• Uniform 标量量化（SQ4 / SQ8 Uniform）
• 乘积量化（PQ）
• PQ FastScan
• RaBitQ
• RaBitQ x+y Split
• 量化变换（TQ）

FP32（基线）

fp32 把每个坐标按 32 位 IEEE-754 浮点存储——与输入向量布局一致。它是 VSAG 中唯一完全无损的选项，作为所有其他量化器对比的参考基线。

实现：src/quantization/fp32_quantizer.cpp，参数文件 fp32_quantizer_parameter.cpp。

何时使用

• 重排 / 精确存储。 当 use_reorder: true 时， precise_quantization_type: "fp32" 是默认的精确存储；图上游走使用便宜 的基础量化器，对 top-K 候选再用 fp32 精确重打分。
• 参考 / 基准真值。 用 base_quantization_type: "fp32" 构建索引能拿 到该索引类型可达的最高召回，是其他量化器对比的标准基线 （docs/docs/en/src/resources/eval.md）。
• 小规模数据集，内存不是瓶颈时。
• BruteForce 原始向量取回。 仅当 base_quantization_type 为 fp32 且度量允许时，SUPPORT_GET_RAW_VECTOR_BY_IDS 才会被广播 （src/index/brute_force.cpp）。

内存代价

仅码本身的开销为每向量 4 × dim 字节。当 fp32 作为某个基础量化器之上的 精确存储时，每向量代价为 base 码 + 4 × dim。

参数

fp32 没有量化器专属的 JSON 参数。

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "fp32",
        "max_degree": 32,
        "ef_construction": 300
    }
}

训练

不需要。fp32 不设置 NEED_TRAIN。

度量兼容性

l2、ip、cosine——全部支持，无特殊处理。

相关页面

• 量化总览
• HGraph 索引 —— 见 precise_quantization_type
• 内存管理

半精度浮点（FP16 / BF16）

fp16 与 bf16 把每个坐标用 16 位而非 32 位存储，把码内存减半且近似 无损。它们没有量化器专属的 JSON 参数；二者的唯一差异是浮点格式自身的 位布局。

实现：src/quantization/scalar_quantization/half_precision_quantizer.cpp， 类型特征在 half_precision_traits.h。 可运行示例：examples/cpp/321_index_fp16_hgraph.cpp。

FP16 与 BF16 一览

实践含义：

• fp16 保留更多尾数位——对取值大致在 [-1, 1] 的归一化嵌入精度更 好。是 cosine 归一化向量的标准选择。
• bf16 保留与 fp32 一致的指数范围——对原始、未归一化的特征（如 加权和、累加器式嵌入）更安全。相对 fp16，在接近零的取值上损失一些 精度。

不确定时：归一化嵌入选 fp16，未归一化或范围较宽的数据选 bf16。

何时使用

• 在 fp32 基线之上作为“即插即用“的内存优化。在标准基准（SIFT、GIST、 Glove、句向量）上召回损失通常低于 1%。
• 作为精确重排存储，体积仅为 fp32 的一半： precise_quantization_type: "fp16" 或 "bf16" 配合 use_reorder: true。
• 高维浮点向量，32 位存储成为瓶颈时。

内存代价

仅码本身每向量 2 × dim 字节。

参数

fp16 与 bf16 均没有量化器专属 JSON 参数。

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 768,
    "index_param": {
        "base_quantization_type": "fp16",
        "max_degree": 32,
        "ef_construction": 300
    }
}

将 "fp16" 替换为 "bf16" 即可切换格式。输入 dtype 仍是 "float32"： 量化器会在运行时转换。

训练

不需要。fp16 与 bf16 均不设置 NEED_TRAIN。

度量兼容性

l2、ip、cosine——全部支持。cosine 通过先归一化输入再以 16 位精度 存储实现。

何时不要使用

• 当你还需要一个内存更激进的基础量化器（如 sq8 或 pq）——它们已经 把存储压到远低于 2 字节/维。
• 当你需要精确距离（用 fp32）。

相关页面

• 量化总览
• HGraph 索引 —— precise_quantization_type 表
• 内存管理

标量量化（SQ4 / SQ8）

sq8 与 sq4 是逐维标量量化器：每个坐标按训练得到的逐维 [min, max] 范围，从 float32 映射到 8 位（sq8）或 4 位（sq4）整数。它们共享同 一份实现，仅以位宽参数化，位于 src/quantization/scalar_quantization/scalar_quantizer.cpp 与 scalar_quantizer_parameter.h。

如果想要 SIMD 更友好、使用全局 [min, max] 的变种，见 Uniform 标量量化。

SQ4 与 SQ8 一览

训练得到的是逐维 min/max，重尾分布的坐标可能浪费码位。如果数据各 向异性强，可考虑改用 Uniform 标量量化 或先旋转的 量化变换 链路，例如 "rom, sq8_uniform"。

内存代价（仅码）

• sq8：每向量 dim 字节。
• sq4：每向量 ceil(dim / 2) 字节。

此外还有一份小型逐维范围表（8 × dim 字节，所有向量摊销）。

参数

目前 sq8 与 sq4 均无量化器专属 JSON 参数 （scalar_quantizer_parameter.h:36-58）。位宽仅由 type 字符串决定。

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 32,
        "ef_construction": 300,
        "use_reorder": true,
        "precise_quantization_type": "fp32"
    }
}

将 "sq8" 替换为 "sq4" 即得到 4 位码。

训练

设置了 NEED_TRAIN。训练从输入向量样本中收集逐维 min / max。 Build(base) 会内部完成训练；对需要显式 Train 的索引（如部分 IVF 流程）， 请在 Add 之前调用。详见 索引构建与训练。

度量兼容性

l2、ip、cosine——全部支持。距离通过把整数码解码回逐维缩放浮点后 计算。

sq8 与 sq4 如何选

• sq8：图索引（HGraph、Pyramid）追求约 4× 内存压缩时的默认选择。 召回损失通常很小，use_reorder 经常可选，但搭配 precise_quantization_type: "fp32" 启用重排是最稳妥的配置。
• sq4：内存紧张且能承担精确重排存储时选用。几乎总是要配合 use_reorder: true。
• 如果数据大致维度同质，改选 sq*_uniform；uniform 变种具有更高的 SIMD 吞吐。
• 对重尾 / 各向异性数据，更推荐前置旋转的 量化变换 链路。

相关页面

• Uniform 标量量化（SQ4 / SQ8 Uniform）
• 量化变换
• 量化总览

标量量化 Uniform（Scalar Quantization Uniform：SQ4 / SQ8 Uniform）

sq8_uniform 与 sq4_uniform 与 sq8 / sq4 类似，是标量量化 器，但它们学习的是全局唯一的 [min, max] 范围，对所有维度都使用同一 份缩放参数。这一权衡——逐维自适应能力略弱，但解码路径更简单——换来了 显著更快的 SIMD 距离计算（l2 与 ip），并保持更紧凑的码布局。

实现：src/quantization/scalar_quantization/sq8_uniform_quantizer.cpp、 src/quantization/scalar_quantization/sq4_uniform_quantizer.cpp。

为什么快：距离计算停留在整数域

这是在条件允许时优先选用 sq*_uniform 而非 sq* 的核心原因。由于每个 维度共享同一对 (min, max)，仿射解码 x = min + code · (max - min) / (2^b - 1) 对所有坐标都使用相同的 scale 与 offset。这在热路径上带来三点收益：

• query 用同一份全局 (min, max) 只编码一次，存入 uint8（或打包的 半字节）缓冲，见 ProcessQueryImpl （src/quantization/scalar_quantization/sq8_uniform_quantizer.cpp:179）。
• base 向量的 code 从不解码回 fp32。kernel SQ8UniformComputeCodesIP(uint8_t* q, uint8_t* x, dim) / SQ4UniformComputeCodesIP(...) 把两个操作数都按原始整数 code 读入， 在 uint8 / 打包半字节通道上直接用 AVX-512 / AMX（ARM 上为 NEON）做 点积，一次处理一个 cache line。内层循环里没有任何逐元素的 fp 反量化。
• 共享的 scale 与 offset 在整数累加完成之后对每对向量只补偿一次， 即可还原 fp 距离。某些度量需要的额外项（每向量的 norm 或 sum）也在 循环外加上，参见 sq8_uniform_quantizer.cpp:200 的 trailing metadata 说明以及 SQ8UniformComputeCodesIPBatch 批量 kernel。

而在逐维的 sq* 量化器里，每个坐标都有自己的 (min_i, max_i)，kernel 要么在循环内乘以逐维 scale 表，要么先把至少一边的操作数解码回 fp。 省掉这一步，就是 uniform 变种在同等召回下显著更快的根本原因。

何时使用

• HGraph / IVF / Pyramid 的热路径。 当瓶颈在基础量化器距离计算时， 在相近召回下，sq8_uniform / sq4_uniform 几乎总是比对应的非 uniform 变种更快。
• 维度间取值范围相近的数据。 归一化嵌入（cosine），或已通过 量化变换 链路（如 "rom, sq8_uniform" 或 "fht, sq8_uniform"）旋转过的向量，都是理想 输入。
• 作为 tq 链路的末端量化器。 最常见的链路是 "pca, rom, sq8_uniform"，参考示例 501。

SQ4 uniform 与 SQ8 uniform 对比

参数

sq8_uniform 没有量化器专属的 JSON 参数。

在 HGraph 上，sq4_uniform_trunc_rate 作为顶层 key 暴露，并被映射到 嵌套的量化参数中（src/algorithm/hgraph.cpp:409-416）。

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq4_uniform",
        "sq4_uniform_trunc_rate": 0.05,
        "max_degree": 32,
        "ef_construction": 300,
        "use_reorder": true,
        "precise_quantization_type": "fp32"
    }
}

若需 8 位变种，把 "base_quantization_type" 设为 "sq8_uniform" 并去掉 trunc_rate key 即可。

训练

设置了 NEED_TRAIN。训练在所有维度上估计单一的 [min, max] （sq4_uniform 时可附加截断）。Build 会内部完成训练。

度量兼容性

l2、ip、cosine——全部支持。cosine 会先归一化再量化，这也使得 uniform 缩放在该度量下接近最优。

uniform 与非 uniform 之间如何选

• 数据已归一化（cosine 或预归一化 l2）→ 选 uniform。
• 数据各维度取值范围差异极大（如混合特征块）→ 先尝试非 uniform 的 sq*，或在旋转变换后再用 uniform（"rom, sq*_uniform"）。
• 吞吐比最后一点点召回更重要 → uniform。

相关页面

• 标量量化（SQ4 / SQ8）
• 量化变换
• 量化总览

乘积量化（PQ）

乘积量化把一个向量切成 pq_dim 个等长的子向量，每个子向量独立地按 含 2^pq_bits 个中心的小型码本进行量化。最终存储的码为每向量 pq_dim × pq_bits 比特——比 fp32 小数量级。查询时的距离计算通过每查询 预先计算的查找表（LUT）完成。

实现：src/quantization/product_quantization/product_quantizer.cpp， 参数文件 product_quantizer_parameter.cpp。

何时使用

• 高维浮点向量（≥ 256 维），且 sq8 仍嫌过大。
• 内存紧张、精度可接受的工作负载，需要相对 fp32 约 16× 压缩。
• 配合 use_reorder: true 与一个小型 fp16/fp32 精确存储，PQ 是大规模 场景下“压缩图索引“的标准配方。

如需在 pq_bits = 4 时获得更高的 SIMD 吞吐，见 PQ FastScan。

内存代价（仅码）

每向量 ceil(pq_dim × pq_bits / 8) 字节，外加一份只存一次的小型码本 （pq_dim × 2^pq_bits × subspace_dim × 4 字节）。以典型配置 （pq_dim = 32、pq_bits = 8、dim = 128）为例：

• 码大小 = 32 × 8 / 8 = 32 字节/向量（对比 fp32 的 128 × 4 = 512 → 小 16×）。

参数

在 HGraph 上，这些以顶层 key base_pq_dim 与 pq_bits 暴露 （src/algorithm/hgraph.cpp:465-472）。

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "pq",
        "base_pq_dim": 32,
        "max_degree": 32,
        "ef_construction": 300,
        "use_reorder": true,
        "precise_quantization_type": "fp16"
    }
}

训练

设置了 NEED_TRAIN。训练在每个子空间上跑 k-means 来学习 2^pq_bits 个 中心；这通常是所有内建量化器中最贵的训练步骤。每个子空间使用至少 256 × 2^pq_bits 个训练样本，码本会更稳定；Build(base) 会自动从输入 采样。

度量兼容性

l2、ip、cosine——全部支持。查询时距离通过每子空间的 LUT 计算： l2 使用查询子向量与每个中心的 L2 平方；ip 使用点积。cosine 在预 归一化向量上等价于 ip。

实践要点

• pq_dim 应整除 dim。常用比例是 dim/4 或 dim/8。
• 极小的 pq_dim（如 dim/16）能得到非常紧凑的码，但召回会迅速下降； 务必配合重排。
• 对各向异性数据，在 PQ 前接一层旋转变换能显著提升召回：用 量化变换 链路如 "rom, pq"。

相关页面

• PQ FastScan
• 量化变换
• HGraph 索引
• 量化总览

PQ FastScan

pqfs 是 乘积量化 的一个 SIMD 加速变种：将 pq_bits 固定为 4， 并采用专为 AVX-2 / AVX-512 “FastScan” 查表内核设计的内存布局。代价是仅 支持 4 位，但能带来显著更高的距离计算吞吐。

实现：src/quantization/product_quantization/pq_fastscan_quantizer.cpp， 参数文件 pq_fastscan_quantizer_parameter.cpp。

何时使用

• 平台有 AVX-2（最好还有 AVX-512）；FastScan 内核正是选用 pqfs 而非 pq 的主要理由。
• 关注的不只是内存，还有搜索吞吐。
• 4 位子空间码本（每子向量 16 个中心）能满足召回目标——通常配合重排即 可。

如果平台不具备所需的 SIMD 宽度，请回退到普通 pq。

内存代价（仅码）

每向量 ceil(pq_dim / 2) = (pq_dim + 1) / 2 字节——奇数和偶数 pq_dim 都支持（src/quantization/product_quantization/pq_fastscan_quantizer.cpp:41）。 码本：pq_dim × 16 × subspace_dim × 4 字节——因为每子空间只有 16 个中心， 比 8 位 pq 的码本小很多。

参数

在 HGraph 上以 base_pq_dim 暴露（src/algorithm/hgraph.cpp:465-472）。

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "pqfs",
        "base_pq_dim": 32,
        "max_degree": 32,
        "ef_construction": 300,
        "use_reorder": true,
        "precise_quantization_type": "fp16"
    }
}

训练

设置了 NEED_TRAIN。在每子空间训练 16 中心码本；比 pq 的 256 中心训练 更便宜。

度量兼容性

l2、ip、cosine——覆盖与 pq 一致。LUT 布局因度量而异，但由量化器 透明处理。

实践要点

• pq_dim 最好是内核预期 SIMD 批宽的倍数（实现在 AVX-512 上内部使用 32）。拿不准时，选 pq_dim ∈ {32, 64, 96, 128}。
• 相对 pq 的优势是相同召回下的吞吐，而非内存（4 位码本身就小，但 pq 设 pq_bits = 4 同样能匹配大小）。
• 想最大化召回恢复，配合 use_reorder: true 与 fp16 或 fp32 精确 存储。

相关页面

• 乘积量化（PQ）
• HGraph 索引
• 量化变换
• 量化总览

RaBitQ

rabitq 是 VSAG 的二值 / 低比特量化器。默认模式下每个坐标用 1 比特 编码，给出所有内建量化器中最高的压缩率。在 HGraph 和 Pyramid 上，x+y split 模式把 底库码拆成 x 个过滤 bit 和 y 个 supplement bit：图遍历只使用 filter code， 重排 / full-distance 阶段只额外读取 supplement bits。

实现：src/quantization/rabitq_quantization/rabitq_quantizer.cpp， 参数文件 rabitq_quantizer_parameter.cpp。 split 的完整存储布局、lower bound 公式和 IO 模式见 RaBitQ x+y Split。

何时使用

• 最强压缩。 1 比特码是稠密向量可能的最小存储。
• 高维嵌入——旋转 + 二值化后仍能保留足够近邻搜索所需的几何信息。
• 配合精确重排存储（fp16 / fp32）——标准做法就是 “RaBitQ + 重排”， 因为 1 比特距离本身噪声较大。

为获得最佳精度，请同时启用 rabitq_use_fht: true，或者用 量化变换 链路如 "pca, rom, rabitq" 包一层。

内存代价（仅码）

• rabitq_bits_per_dim_base = 1：每向量 ceil(dim / 8) 字节。dim = 768 时为 96 字节（对比 fp32 的 3072 → 小 32×）。
• HGraph 或 Pyramid 上 rabitq_bits_per_dim_base = x 且 rabitq_bits_per_dim_precise = y：split 模式约存储 (x + y) * dim / 8 字节的 RaBitQ code。例如 3+5 约为每向量 dim 字节。

参数

启用 fast_encode_rabitq 后，多 bit RaBitQ 先进行 LVQ 初始化，再执行固定轮数的 坐标微调，把码字选择复杂度从约 O(2^B * dim * log(dim)) 降到 O(rounds * dim)，且不改变编码布局和查询估计器。实现参考 SAQ 中的 CAQ；在新数据集上评估质量与速度 权衡时可关闭该参数使用精确编码。两个参数仅影响构建，不影响已保存索引的加载 兼容性。VSAG 采用 clean-room 实现，不依赖采用 Apache-2.0 许可证的 SAQ 参考仓库。

各索引页会把 RaBitQ 设置暴露为 index_param 顶层 key：HGraph 暴露 rabitq_pca_dim、rabitq_bits_per_dim_query、rabitq_bits_per_dim_base、 rabitq_bits_per_dim_precise、rabitq_error_rate、rabitq_use_fht；IVF 暴露 rabitq_pca_dim、rabitq_bits_per_dim_query、 rabitq_bits_per_dim_base、rabitq_version、rabitq_error_rate、 rabitq_use_fht；Pyramid 为底层量化器暴露 PCA、底库/查询位数、split precise 位数、误差倍率和 FHT 相关 key。其中 rabitq_use_fht 是索引层对量化器内部 use_fht key 的别名，会由索引层重写。

fast_encode_rabitq 和 fast_encode_rabitq_rounds 同时适用于 HGraph、IVF 和 Pyramid，并会传播给 base 与 precise RaBitQ 量化器。

对于启用 split RaBitQ 和 fast_encode_rabitq=true 的普通首次 HGraph 构建时，HGraph 会先并行把所有向量编码为逐维一个无符号字节的 scalar code，同时保存标准 RaBitQ metadata，并在独立数组中为每个 向量保存 8 字节 code sum。编码完成后才启动构图任务，使用 scalar SIMD 计算 code-code 距离。raw inner-product 内核不感知配置的 x+y 总位数， 量化器仍会应用对应的量化范围和中心值。构图完成后，scalar code 只执行 一次 bit-plane pack，并写入最终 filter 与 supplement 存储，不会重新执行 PCA、ROM/FHT 或 RaBitQ 量化。scalar record 与 code-sum 数组都会在 Build 返回前释放。总位数为 8 时，scalar 与 packed payload 大小相同； 总位数更低时会以额外构建内存换取更快的构图距离计算。

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 768,
    "index_param": {
        "base_quantization_type": "rabitq",
        "rabitq_use_fht": true,
        "rabitq_pca_dim": 0,
        "rabitq_bits_per_dim_base": 1,
        "rabitq_bits_per_dim_query": 32,
        "max_degree": 32,
        "ef_construction": 300,
        "use_reorder": true,
        "precise_quantization_type": "fp32"
    }
}

切换到高精度的 x+y split 模式：把 base 和 precise 量化都设置为 RaBitQ， 并提供 rabitq_bits_per_dim_precise。HGraph 和 Pyramid 会自动选择 split datacell。 下面例子中，图遍历使用 x = 3 个 filter bits，重排只读取 y = 5 个 supplement bits：

{
    "base_quantization_type": "rabitq",
    "precise_quantization_type": "rabitq",
    "rabitq_bits_per_dim_base": 3,
    "rabitq_bits_per_dim_precise": 5,
    "rabitq_use_fht": true
}

训练

设置了 NEED_TRAIN。训练学习让 1 比特编码均衡的旋转与逐维统计。可选的 FHT 旋转是固定的（无需学习），因此不增加训练代价；PCA 预处理（`pca_dim

0`）会训练一个投影矩阵。

度量兼容性

l2、ip、cosine——全部支持。二值距离内核是对 XOR 后的码字做 popcount； 对 ip / cosine，实现还会追踪一份残差范数，使内积估计无偏。

实践要点

• 始终启用重排，除非你已经验证 1 比特召回在你的数据上可接受。 use_reorder: true + precise_quantization_type: "fp32" 是稳妥默认。
• 先旋转。 对未归一化数据，设 rabitq_use_fht: true，或在 tq 链路 中包含 rom / fht。
• 精度优先时用 split 模式。 HGraph/Pyramid x+y split 保留 x bit 快速 过滤路径，再添加 y 个 supplement bits 用于重排；相对纯 1 比特，使用 更多总 bit 时召回明显更高。

相关页面

• 量化变换
• HGraph 索引
• RaBitQ x+y Split
• 量化总览

RaBitQ x+y Split

RaBitQ x+y split 是 HGraph 和 Pyramid 面向低比特底库码的存储与搜索模式。每条向量拆成 两条记录：

• 图遍历和 lower-bound 过滤只读取 x 个 filter bits。
• 只有进入重排的候选才读取 y 个 supplement bits。
• 最终重排距离使用完整的 x+y bits。

这种布局缩小了图遍历的热数据，同时保留更高精度的 RaBitQ 距离用于最终排序。 它也支持把 filter record 留在内存中，把访问频率更低的 supplement record 放到磁盘。

启用 split 模式

当 base 和 precise 的量化类型都为 rabitq，并且配置了 rabitq_bits_per_dim_precise 时，HGraph 和 Pyramid 自动选择 split 模式：

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 960,
    "index_param": {
        "base_quantization_type": "rabitq",
        "precise_quantization_type": "rabitq",
        "use_reorder": true,
        "rabitq_bits_per_dim_query": 32,
        "rabitq_bits_per_dim_base": 3,
        "rabitq_bits_per_dim_precise": 5,
        "rabitq_error_rate": 1.9,
        "max_degree": 64,
        "ef_construction": 400
    }
}

相关参数如下：

参数约束为：

1 <= x <= 8
1 <= y <= 8
x + y <= 8

如果不配置 rabitq_bits_per_dim_precise，HGraph 和 Pyramid 使用 standard RaBitQ 路径， 不会创建 split storage。

使用以下搜索参数启用 filter/lower-bound 搜索路径：

{
    "hgraph": {
        "ef_search": 200,
        "parallelism": 4,
        "rabitq_one_bit_search": true,
        "rabitq_error_rate": 1.9
    }
}

外部搜索参数仍命名为 rabitq_one_bit_search，但对 split 索引，它会使用 rabitq_bits_per_dim_base 配置的全部 x 个 filter bits。 hgraph.rabitq_error_rate 可以为单次搜索覆盖索引默认值。record 中保存的是乘倍率前的 几何误差尺度，因此 sweep 这个搜索参数不需要重建索引。

搜索流程

split 搜索分为四个阶段：

1. query 只做一次变换和归一化；对支持的 filter bit 数，还会为每个 query 构建一次 byte lookup table。
2. 图遍历只读取 filter record，为每个访问到的向量计算 x-bit 距离估计和 保守的 lower bound。
3. 重排先丢弃 lower bound 不可能进入结果集的候选，只为剩余候选读取 y-bit supplement record。
4. 最终距离把 filter contribution 与 supplement contribution 合成为 x+y-bit RaBitQ 估计。

因此，图搜索不会为每个访问到的向量都计算 x+y 距离并放入搜索堆。图遍历由 低成本的 x-bit 距离驱动，更精确的距离只在候选重排阶段计算。

编码和 bit-plane

定义：

d       = 变换后的维度
x       = 每维 filter bit 数
y       = 每维 supplement bit 数
B       = x + y
P       = ceil(d / 8)，一个 bit-plane 的字节数
q_i     = 变换并归一化后的 query 坐标
u_i     = 无符号 B-bit 底库码，0 <= u_i < 2^B

完整 code 的中心化表示为：

c_B = (2^B - 1) / 2
z_i = u_i - c_B
N_B = sqrt(sum_i z_i^2)

PackIntoPlanes 把 u_i 的每一个逻辑 bit 存成独立 bit-plane。filter 和 supplement 的划分为：

f_i = floor(u_i / 2^y)    # 高 x bits
s_i = u_i mod 2^y         # 低 y bits
u_i = 2^y * f_i + s_i

物理布局让高位 filter planes 连续存储：

filter record:     logical B-1, B-2, ..., B-x
supplement record: logical 0, 1, ..., y-1

因此图遍历只需扫描 x * P 字节的 plane payload；重排只额外读取 y * P 字节的 plane payload，不计元数据和对齐。

Datacell 布局

RaBitQSplitDataCell 内部维护两个 RaBitQSplitCodeStorage。

Filter record

x_bit_cell_ 中的 filter record 包含：

x 个高位 bit-plane
base norm
x > 1 时的 filter-code norm
可选 MRQ residual norm
IP/cosine 使用的可选 raw norm
lower-bound error
filter approximation error

每条向量的 filter plane payload 为：

FilterPlanesSize = x * ceil(d / 8)

filter record 是图遍历的热数据。只要 x-bit 估计有效，图搜索和预取都不需要 访问 supplement record。

Supplement record

supplement_cell_ 中的 supplement record 包含：

y 个低位 bit-plane
full-code norm
full-code approximation error
当前 metric 和 transform 所需的其他元数据

每条向量的 supplement plane payload 为：

SupplementPlanesSize = y * ceil(d / 8)

完整 code 的 payload 约为每条向量 (x+y) * d / 8 字节，此外还有对齐后的 norm、error 和可选 transform 元数据。

X-bit filter 距离和 lower bound

第 i 维 filter code 为 f_i，取值范围 [0, 2^x - 1]。定义：

c_x   = (2^x - 1) / 2
N_x   = sqrt(sum_i (f_i - c_x)^2)
S_x   = sum_i q_i * f_i
Q_sum = sum_i q_i
rho_x = (S_x - c_x * Q_sum) / N_x

构建索引时，RaBitQ 保存 filter approximation error 的绝对值 E_x，并计算 几何误差尺度：

E_safe    = clamp(abs(E_x), 1e-5, 1)
epsilon_x = sqrt(max(0, 1 - E_safe^2) / max(1, d - 1))

修正后的 filter 内积估计为：

rho_hat_x = rho_x / abs(E_x)

对 L2，设 base norm 为 N_o、query norm 为 N_q，x-bit 距离和 lower bound 为：

D_x = N_o^2 + N_q^2 - 2 * N_o * N_q * rho_hat_x

LB = D_x
     - 2 * N_o * N_q * rabitq_error_rate * epsilon_x / abs(E_x)

实现还会从 LB 中减去一个很小的浮点保护量。IP 和 cosine 会按各自的 metric 换算误差项。

lower bound 只用于安全地排除候选。D_x 是图遍历距离，最终排序使用完整的 x+y 距离。

Query lookup table 和 SIMD

当 x = 2 或 x = 3 时，query computer 会构建 FastScan 风格的 byte lookup table。每一行对应八个 query 坐标，并包含 256 个表项：

LUT[block][byte_value]
    = byte_value 在该 8-D block 中置位位置对应的 q_i 之和

随后每个 filter plane 的每个字节只需要查表一次，不必逐坐标解码八次。不同 filter plane 再按二进制权重合成为 S_x。

AVX2 和 AVX512 kernel 会同时 gather 多个 LUT 表项，并提供 batch-of-four 路径； scalar 实现作为可移植 fallback。关键入口为：

• RaBitQFloatMultiBitIPByLookup
• RaBitQFloatMultiBitIPBatch4ByLookup
• RaBitQFloatBuildByteIPLookupTable

不在专用范围内的 x-bit 宽度仍由通用 bit-plane 计算路径支持。

Reorder 只扫描 y 个 supplement bits

完整无符号 code 满足：

sum_i q_i * u_i
    = 2^y * sum_i q_i * f_i
      + sum_i q_i * s_i

对使用 x-bit lookup filter 的 L2 搜索，HGraph 和 Pyramid 会把之前计算的 filter distance 作为 hint 传给 reorder。ComputeDistWithSplitCodeAndFilterDist 从 hint 恢复第一项， 只从 y 个 supplement planes 计算第二项：

full contribution = shifted filter contribution + supplement contribution

因此 3+5 索引会复用 3-bit filter 结果，每个重排候选只扫描 5 个新的 bit-plane。 如果 hint 不存在或不能使用，代码会回退到 ComputeDistWithSplitCode，直接从两个 split records 计算相同的最终距离。

内存、磁盘和混合 IO

如果没有单独配置 supplement IO，两个 record 使用相同的 base IO 类型。

两个 record 都在内存

{
    "base_io_type": "block_memory_io"
}

两个 record 都在磁盘

{
    "base_io_type": "async_io",
    "base_file_path": "/data/hgraph_rabitq_split"
}

VSAG 会为 filter 和 supplement record 创建不同的 backing path。

Filter 在内存，supplement 在磁盘

{
    "base_io_type": "block_memory_io",
    "base_supplement_io_type": "async_io",
    "base_file_path": "/data/hgraph_rabitq_split"
}

当前支持的 mixed-IO 组合把 x_bit_cell_ 保存在 block memory，把 supplement_cell_ 放在 async IO。批量重排时，filter record 通过直接指针读取， MultiRead 只拉取 supplement records。可以显式设置 base_supplement_file_path；否则 VSAG 根据 base_file_path 生成 supplement path。

序列化和加载

使用标准的索引级序列化接口即可，业务侧不需要分别持久化两个 record。

std::ofstream out("/path/to/index.bin", std::ios::binary);
auto serialized = index->Serialize(out);

auto loaded = vsag::Factory::CreateIndex("hgraph", index_params).value();
std::ifstream in("/path/to/index.bin", std::ios::binary);
auto deserialized = loaded->Deserialize(in);

split datacell 按以下顺序序列化：

1. datacell 基础状态和 supplement IO type。
2. filter storage。
3. supplement storage。
4. RaBitQ quantizer 状态。

创建目标索引时必须使用与序列化索引兼容的参数，尤其是 dim、metric_type、 x/y bit 数和 query bits。修改编码参数需要重建索引；只调整搜索参数 hgraph.rabitq_error_rate 不需要。

实现位置

使用注意

• split storage 当前可用于 HGraph 和 Pyramid，并且要求 fp32 query code。Pyramid 的 split 索引默认启用 one-bit split 搜索路径；如需强制使用普通搜索路径，可以在 pyramid 搜索参数下传 rabitq_one_bit_search: false。
• 支持 l2、ip 和 cosine；利用 filter hint 的 reorder 快速路径当前针对 L2。
• 除非已经验证仅靠 x-bit 遍历距离能满足召回要求，否则应保持 use_reorder: true。
• 修改 x、y、metric 或 transform 参数后必须重建索引；在搜索参数中覆盖 hgraph.rabitq_error_rate 不需要重建。
• RaBitQ 通用说明见 RaBitQ，完整 HGraph 参数见 HGraph 索引和 Pyramid 索引。

量化变换（Quantization Transform）

变换量化器（base_quantization_type: "tq"）在最终量化器之前串联一个或多个向量变换。 变换会重塑向量分布，让后续量化器能更准确、更紧凑地编码 —— 例如把向量旋转一下，让能量分散 到各个维度（RaBitQ / SQ 受益最大），或者先用 PCA 降维再存储。

可运行示例：examples/cpp/501_quantization_transform.cpp。

为什么需要变换层

纯量化器直接压缩向量。对低比特量化器（如 sq4、sq*_uniform、rabitq），编码精度严重 依赖向量坐标的分布：长尾或各向异性的维度会浪费 code bit。变换层可以缓解这个问题：

• 随机旋转（rom、fht）让坐标去相关，均匀/标量量化器在每个轴上工作得更好。
• PCA（pca）在保留主要方差的同时降低维度 —— code 大小按比例缩小。
• MRLE（mrle）是为 L2/IP 搜索设计的距离可恢复低秩编码。

变换后的输出再喂给一个标准量化器（fp32、sq8、sq8_uniform、rabitq ……），由后者 真正存储 code。整条链被称为 tq（Transform Quantizer）。

快速上手

tq 已作为对外可配置的量化类型暴露给 HGraph 和 Pyramid。两者都会把 tq_chain 与降维参数映射到 base_codes.quantization_params。MRLE + RaBitQ x+y split 组合在两个索引中均可用，并自动从 base split datacell 重排。IVF、BruteForce 与 WARP 目前仍未通过外部参数映射暴露 tq_chain。

std::string params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "tq",
        "tq_chain": "pca, rom, sq8_uniform",
        "rabitq_pca_dim": 64,
        "max_degree": 32,
        "ef_construction": 300,
        "use_reorder": true,
        "precise_quantization_type": "fp32"
    }
})";

vsag::Resource resource(vsag::Engine::CreateDefaultAllocator(), nullptr);
vsag::Engine engine(&resource);
auto index = engine.CreateIndex("hgraph", params).value();
index->Build(base);
auto result = index->KnnSearch(query, topk, search_params).value();

上面的例子里，base 向量先从 128 维降到 64 维（pca），随后做随机旋转（rom），最后用 sq8_uniform 量化。开启了 reorder，HGraph 同时保留一份 fp32 精确副本，对图搜索返回的 top 候选做精排（include/vsag/index.h；存储影响见 内存管理）。

tq_chain 语法

tq_chain 是一个以逗号分隔的字符串：一个或多个变换名，最后跟一个唯一的量化器名。 token 两侧的空白会被自动 trim （src/quantization/transform_quantization/transform_quantizer_parameter.cpp:53-74）。

"<变换1>, <变换2>, ..., <量化器>"

示例：

约束（transform_quantizer_parameter.cpp:33-45）：

• 链至少包含 1 个变换 + 1 个量化器（长度 ≥ 2）。空串或单 token 会抛 INVALID_ARGUMENT。
• 最后一个 token 必须是 TQ flatten 路径能够 dispatch 的量化器 —— fp32、sq8、 sq8_uniform、sq4、sq4_uniform、bf16、fp16、pq、pqfs、rabitq 之一 （src/datacell/flatten_interface.cpp:126-164）。TransformQuantizerParameter 解析层会 额外接受 sparse、int8、tq，但 flatten 工厂没有针对 int8/tq 的分发分支，并且当 is_transform_quantizer=true 时显式拒绝 sparse （src/datacell/flatten_interface.cpp:166），因此这三个不能用作 TQ 末端，否则会在构建索引时 以 “unsupported quantization type” 失败。
• RaBitQ x+y split 存储仅支持精确链 "mrle, rabitq"。split datacell 复用末端 RaBitQ 编码器，并保留 RaBitQ 内部的 FHT/ROM 随机旋转；其他带变换的 split 链会被拒绝。
• 未识别的变换名会抛 INVALID_ARGUMENT: invalid transformer name （transform_quantizer.h:225-227）。

支持的变换

src/quantization/transform_quantization/transform_quantizer.h:192-227 的工厂当前识别 4 个变换名：

说明：

• mrle 必须位于首位由 transform_quantizer.h:155-159 强制；mrle_dim ≤ input_dim 由 transform_quantizer.h:217-220 强制。
• header 中声明的其它字符串（residual、normalize）未接入工厂，会被拒绝。

变换参数

变换 JSON 由 VectorTransformerParameter::FromJson 解析 （src/impl/transform/vector_transformer_parameter.cpp:22-35）：

HGraph 顶层映射

使用 HGraph 时，顶层快捷键会被映射到嵌套的量化器参数中：

• tq_chain → base_codes.quantization_params.tq_chain
• rabitq_pca_dim → base_codes.quantization_params.pca_dim
• mrle_dim → base_codes.quantization_params.mrle_dim

rabitq_pca_dim 这个名字早于 Transform Quantizer 引入；当链中包含 pca 时，它实际 驱动的是 pca 变换的输出维（与 RaBitQ 无关）。如果链以 rabitq 结尾且未使用 pca，则同一个键会配置 RaBitQ 自身的 PCA 预处理 （src/quantization/rabitq_quantization/rabitq_quantizer_parameter.cpp:30）。

mrle_dim 接受 [0, dim] 内的整数；0 表示输入维度。它在 tq_chain 包含 mrle 时生效，且 mrle 必须保持为链中的第一个变换。

Reorder 与精确码存储

变换链在设计上一定有信息损失（旋转无损，但 pca / sq*_uniform / rabitq 有损）。 把 tq 与 reorder 组合使用 —— 即额外保留一份精确（通常是 fp32）副本，对 top 候选 做精排 —— 可以以较小的内存成本恢复精度：

• use_reorder: true 会让 HGraph 额外维护一份 flatten 存储，称为精确码存储 （src/algorithm/hgraph.cpp:76-79）。
• precise_quantization_type 决定精确码使用的量化器（默认 fp32；若想用内存换精度， 也可以设为 fp16 / bf16 / sq8）。
• 搜索时先用低成本的 tq base codes 走图，得到的 top-K 候选再用精确码重新打分 （hgraph.cpp:978-981 及附近调用）。

use_reorder 与 precise_quantization_type 并非 tq 专属 —— 当 base_quantization_type 是 sq8、pq、rabitq 等时同样适用。完整的逐索引参数表见 HGraph 索引。

链该怎么选

经验法则：

请在自有数据上 benchmark —— tq 的激进程度与 use_reorder 的取舍最终取决于数据分布、 目标召回率以及内存预算。

兼容性与合并

两个 tq 配置只有在链长度、每一步变换名、最终量化器都完全一致时才被视为兼容 （src/quantization/transform_quantization/transform_quantizer_parameter.cpp:99-117）。 这一点对序列化往返以及未来的合并/克隆操作至关重要 —— 准备合在一起的索引，应保持 chain 字符串稳定。

chain 字符串一致只是必要条件，并不充分。 tq_chain token 列表并不编码变换器参数 （例如 pca_dim / mrle_dim，它们作为兄弟 JSON 键单独读取，见 src/quantization/transform_quantization/transform_quantizer.h:200-216），也不编码末端量化器 的内部参数（例如 pq 子空间数、rabitq 旋转种子等）。这些参数会改变实际 code 的维度与 布局，因此两个构建要真正可合并/可克隆，必须保持整套 transform + quantizer 参数一致， 不能只对齐 chain 字符串。

相关页面

• HGraph 索引 —— base_quantization_type、use_reorder、 precise_quantization_type 等参数说明。
• 内存管理 —— base + precise 存储的内存开销。

代码目录结构

VSAG 项目代码处于快速迭代中，目录组织并不完美，这里仅对当前目录的功能划分做简要介绍。

项目结构

• .circleci/：CircleCI 配置文件；
• .github/：GitHub 配置文件，包括 CI、Issue 模版、代码 Owner 等；
• cmake/：CMake 工具函数，例如检测编译平台的指令集支持；
• docker/：构建 CI 的 Dockerfile 以及用于二进制分发的 Dockerfile；
• docs/：设计文档、用户文档（含本站点源）和博客文章；
• examples/：C++、Python、TypeScript 的示例代码；
• extern/：第三方库，以 CMake 的方式从 GitHub 下载和集成；
• include/：公开头文件，对外稳定 API 都位于此目录；
• python/：pyvsag 打包和安装工具；
• python_bindings/：基于 pybind11 的 Python 绑定实现；
• typescript/：Node.js / TypeScript 绑定及对应 npm 包源代码；
• scripts/：一些有用的工具脚本，例如安装依赖、计算代码覆盖率等；
• src/：核心源代码和单元测试（*_test.cpp）；
• tests/：功能测试用例；
• tools/：相关工具，包括索引性能测试和兼容性检查工具。

核心源代码

• src/*.cpp：各种公共功能代码实现，包括内存分配器、线程池等；
• src/algorithm/：索引算法目录；
• src/data_cell/：data cell 是数据的逻辑单元，索引算法依赖于 data cell；
• src/impl/：一些功能和算子的实现，例如图结构增强、k-means 聚类等；
• src/index/：索引层实现，和 algorithm 目录相互配合；
• src/io/：数据 IO 实现，包括基于内存访问数据和基于磁盘访问数据的方法；
• src/quantization/：量化方法，当前支持 SQ4/SQ8、PQ、RaBitQ 等量化方式；
• src/simd/：指令集加速模块，根据运行平台自动选择最快的距离计算方法；
• src/utils/：工具函数目录。

C++ 编码指南

VSAG 以 Google C++ 风格指南 为基础，并针对 代码格式、命名和静态检查制定了项目规则。仓库根目录下的配置文件是这些规则的准确定义：

• .clang-format 定义自动格式化规则；
• .clang-tidy 定义命名与静态检查规则。

VSAG 严格要求使用 clang-format 15 和 clang-tidy 15。其他版本可能产生不同的格式化 结果或诊断信息，无法通过 CI。

代码组织

• 公开 API 放在 include/vsag/，实现代码放在 src/；
• C++ 源文件使用 .cpp 后缀，不使用 .cc；
• 除非文件有明确的特殊要求，代码应放在 vsag 命名空间中；
• 除非明确计划进行破坏性变更，否则应保持 API 兼容；
• 修改公开 API 时，应添加或更新 Doxygen 注释；
• 新代码优先使用 uint64_t 而不是 size_t，避免 macOS 兼容性问题；
• 除非修改目标明确涉及第三方依赖，否则不要修改 extern/；
• 所有提交的文本文件都应以换行符结尾。

格式化规则

格式化配置以 Google 风格为基础，并应用以下 VSAG 规则：

例如，clang-format 15 会将类声明格式化为：

class Example {
public:
    Result<DatasetPtr>
    Build(const DatasetPtr& base, const std::string& parameters);

private:
    void
    reset_state();

    DatasetPtr dataset_;
};

100 列限制只适用于 C++ 源文件和头文件，不要求 Markdown 或其他非 C++ 文本遵循这一行宽。

命名规则

.clang-tidy 中的 readability-identifier-naming 会检查以下命名：

make lint 还会运行 scripts/linters/check-struct-names.py，检查所有已被 Git 跟踪的项目 C/C++ 文件中的具名结构体，包括 clang-tidy 常规检查范围之外的文件。因此，新建的具名结构体都必须使用 CamelCase。

对于没有项目专用规则的对象，请遵循 Google C++ 风格以及所在模块的现有约定。

选择 class 还是 struct

当类型是被动、值语义的数据载体时，使用 struct：

• 主要用途是将一组相关数据组织在一起；
• 数据成员有意保持公开，调用方可以彼此独立地修改它们；
• 不需要保护对象不变量，也不需要隐藏内部表示；
• 不负责需要受控访问或生命周期管理的资源。

例如 Binary、SparseVector 和 MultiVector。struct 仍然可以包含成员默认值、构造函数或简单的 辅助函数。是否存在成员函数并不是选择 class 的决定因素，关键在于该类型是否仍是透明的数据值。

当类型表示行为或必须控制自身状态时，使用 class：

• 通过公开方法维护对象不变量；
• 使用私有或受保护成员隐藏实现细节；
• 持有或管理需要控制生命周期的资源；
• 提供行为接口或多态接口，尤其是包含虚函数的接口。

例如 BinarySet、Dataset、Filter 和 Index。新建接口和多态基类时，优先使用 class。

无法确定时，可以判断调用方是否应当以任意顺序直接修改每一个数据成员。如果允许，使用 struct；如果 类型必须校验、协调或限制这些修改，使用 class。不要仅仅为了省略 public: 而使用 struct，也不要 为了支持聚合初始化而暴露可变的实现细节。

类和结构体都使用 CamelCase。除非有意进行 API 变更，否则应保留公开类型当前使用的形式，不要把 class 与 struct 之间的转换作为纯风格清理。

静态检查

所有已启用的 clang-tidy 诊断都按错误处理。当前配置启用了以下检查组：

• bugprone-*：发现可能的逻辑缺陷和可疑写法；
• clang-analyzer-*：进行路径敏感的正确性和生命周期分析；
• clang-diagnostic-*：通过 clang-tidy 报告编译器诊断；
• modernize-*：检查项目支持的现代 C++ 写法；
• openmp-*：检查 OpenMP 使用的正确性；
• performance-*：发现不必要的复制和低效操作；
• readability-*：检查可维护性和命名一致性。

部分检查会与 VSAG 的底层、高性能代码冲突，或者在当前代码库中产生过多噪声，因此被明确禁用：

禁用检查并不意味着可以忽略它所关注的问题。在能够提升可读性的情况下，仍应使用含义明确的参数名和 具名常量。

抑制诊断

应优先修复诊断指出的问题。如果诊断属于误报，或者相关写法是兼容性或性能所必需的，应使用范围最小的 抑制，并说明这样做安全的原因：

// NOLINTNEXTLINE(performance-no-int-to-ptr): platform API 将该句柄存储为整数。
auto* handle = reinterpret_cast<Handle*>(raw_handle);

在 NOLINT、NOLINTNEXTLINE 或范围严格受控的 NOLINTBEGIN/NOLINTEND 中写出具体检查名。 除非无法采用更小的范围，否则不要使用不带检查名的 NOLINT 或对整个文件禁用检查。

运行检查

首先安装指定版本的工具：

# Ubuntu 或 Debian
sudo apt-get install clang-format-15 clang-tidy-15 clang-tools-15

# macOS
brew install llvm@15

格式化所有项目 C++ 文件并检查修改：

make fmt
git diff --check

clang-tidy 需要 build-release/ 中的编译数据库，因此应先完成发布模式构建：

make release
make lint

默认 lint 目标以 src/ 下的生产环境 .cpp 文件作为 clang-tidy 入口，并排除 *_test.cpp；同时还会 运行覆盖整个仓库的结构体命名检查。测试和其他目录不会在该命令中作为独立的 clang-tidy 入口。

make fix-lint 会直接应用 clang-tidy 建议的修改，可能产生较大范围的变更。请在干净或已安全备份的 工作区中使用，检查完整 diff，然后重新运行格式化、静态检查和相关测试：

make fix-lint
make fmt
make lint
make test

提交修改前

• 使用 clang-format 15 格式化所有修改过的 C++ 文件；
• 使用 clang-tidy 15 检查修改过的生产环境源码；
• 确认命名符合上述规则，尤其是结构体使用 CamelCase；
• 确保每个 NOLINT 都指定具体检查，并说明原因；
• 新功能包含测试，bug 修复包含回归测试；
• 保持 C++ 库的单元测试覆盖率不低于 90%；
• 运行 git diff --check 并检查完整 diff。

新索引接入检查清单

新增 VSAG 索引实现时使用这份检查清单。第一版应保持范围可控：先让索引能通过公开 factory 创建，支持它声明的生命周期方法；只有在行为已经实现并经过测试后，再开启对应的 feature flag。

必做项

• 选择公开索引名称和类型。

  • 如果新索引需要公开名称常量，请在 include/vsag/constants.h 或 src/inner_string_params.h 中添加。
  • 当调用方需要通过 Index::GetIndexType() 区分该索引时，在 include/vsag/index.h 中添加 IndexType 枚举值。
  • 保持公开名称稳定。src/factory/index_registry.cpp 会在查找前把 factory 名称 归一化为小写。

• 在公开 Index API 背后实现索引。

  • 对新的内存索引，优先沿用 src/index/index_impl.h 中现有的 IndexImpl<T> 模式： 在 src/algorithm/<name>/ 下实现一个 InnerIndexInterface 子类 T。
  • 实现 static CheckAndMappingExternalParam(const JsonType&, const IndexCommonParam&)， 让 IndexImpl<T> 能校验外部 JSON 并构造内部参数对象。
  • 按内部索引契约实现 GetName()、GetIndexType()、GetNumElements()、Add()、 KnnSearch()、Serialize(StreamWriter&) 和 Deserialize(StreamReader&)；索引支持 Build() 时再实现它。InnerIndexInterface::Add() 是纯虚函数，因此每个子类都必须重写， 即使索引只支持 Build()；不支持时应抛出 UNSUPPORTED_INDEX_OPERATION，且不要开启对应 的 feature flag。
  • 对不支持的操作保留基类默认行为，不要把未实现能力声明为已支持。

• 接入 factory 和 engine 创建路径。

  • 在 src/factory/index_creators.cpp 中添加 creator。
  • 在 register_all_index_creators() 中注册。
  • 对共享字段使用 src/index_common_param.cpp 中的 IndexCommonParam::CheckAndCreate()：dtype、metric_type、dim、可选 repr、 可选 extra_info_size、allocator、thread pool，以及旧序列化格式兼容信息。
  • 在 src/factory/factory_test.cpp 或实现附近的专项测试中，覆盖可接受名称、非法参数 和不支持的参数形态。

• 添加构建系统接入。

  • 添加 src/algorithm/<name>/CMakeLists.txt，并从 src/algorithm/CMakeLists.txt 引入。
  • 将新源码加入最近的现有 target，不要创建平行构建路径。
  • 文件后缀保持 .cpp；除非变更本身涉及第三方依赖，否则不要修改 extern/。

• 定义并校验索引参数。

  • 当索引有自己的 schema 时，把实现参数放在 <name>_parameter.{h,cpp} 中。
  • 为序列化/重建参数校验实现 JSON 解析、ToJson() 和 CheckCompatibility()。
  • 对非法维度、metric/data type 组合、缺失的必需配置块和未知模式，通过已有的 CHECK_ARGUMENT / VsagException 流程返回 ErrorType::INVALID_ARGUMENT。
  • 如果参数对用户可见，更新 docs/docs/{en,zh}/src/resources/index_parameters.md 和对应 索引文档。

• 明确实现生命周期行为。

  • 决定索引是否支持 Train()、Build()、ContinueBuild()、build 后 Add()、空索引 Add()。
  • 决定是否支持 Remove()、UpdateId()、UpdateVector()、UpdateAttribute() 和 UpdateExtraInfo()。
  • 对每一种支持的 mutation，测试空数据集、重复 ID（如适用）、缺失 ID、不可变索引行为以及 mutation 后的搜索正确性。
  • 保持 InitFeatures() 与已经实现的操作一致。

• 实现搜索行为和结果打包。

  • 支持该索引要求的公开 KnnSearch() 重载，包括声明支持时的 BitsetPtr、 std::function<bool(int64_t)> 和 FilterPtr 过滤路径。
  • 如果索引支持新的 request 路径，实现 SearchWithRequest()。
  • 一致地返回 Dataset 字段：ID、距离、num_elements、结果维度和可选结果统计信息。
  • 按 HGraph 等现有索引使用的嵌套索引名约定解析搜索参数。

• 保持序列化兼容。

  • 同时实现 Serialize(StreamWriter&) 和 Deserialize(StreamReader&)；基类 InnerIndexInterface 会把它们适配到 BinarySet、ReaderSet 和 stream。
  • 保存足够的元数据以拒绝不兼容二进制，包括参数兼容性，以及存在 extra info 时的 extra_info_size。
  • 当索引同时支持 BinarySet 和 ReaderSet 时，添加两条路径的 round-trip 测试。
  • 如果既有索引的二进制格式发生变化，更新兼容性测试并记录迁移路径。

• 在声明 feature 前补齐测试。

  • 单元测试应覆盖参数解析、build/add/search、序列化、feature flag、已实现的内存估算以及 错误路径。
  • tests/ 下的功能测试应覆盖用户能通过 Factory::CreateIndex() 触达的公开 API 行为。
  • 保持 src/ 和 include/ 的 C++ 单元测试覆盖率不低于项目阈值。

可选适配点

仅当新索引确实实现对应行为时才添加这些能力。实现后，在 InitFeatures() 中开启匹配的 IndexFeature，并添加专项测试。

• Extra info（extra_info / extrainfo）。

  • 通过 IndexCommonParam 解析 extra_info_size。
  • 保存来自 Dataset::GetExtraInfos() 的定长逐向量 payload，并在 Build()、Add() 和 UpdateExtraInfo() 中校验 Dataset::GetExtraInfoSize()。
  • 实现 GetExtraInfoByIds()，并在支持该 feature 时填充搜索结果中的 extra info。
  • 如果索引支持 extra-info 过滤，记录并测试会切换到 Filter::CheckValid(const char*) 的 搜索参数。
  • 参考 docs/docs/zh/src/advanced/extra_info.md 和 examples/cpp/320_feature_extra_info.cpp。

• 统计与分析。

  • 为能帮助运维理解索引的静态结构数据实现 GetStats()。
  • 只有在需要基于 query 分析时，才实现 AnalyzeIndexBySearch(const SearchRequest&)。
  • 当 search-time 指标有价值时，通过 Dataset::Statistics() 附带结果统计。
  • 保持工具输出兼容 tools/analyze_index 和 docs/docs/zh/src/resources/analyze_index.md。

• 范围搜索。

  • 必须重写 InnerIndexInterface 要求的纯虚主重载 RangeSearch(..., const FilterPtr&, ...)，即使算法不支持范围搜索；不支持时应抛出 UNSUPPORTED_INDEX_OPERATION，且不要开启对应的 feature flag。
  • 只有当算法能遵守 radius 语义和 limited_size 时，才实现其他 RangeSearch() 重载。
  • 测试不限量、限量、带过滤和空结果场景。
  • 参考 docs/docs/zh/src/advanced/range_search.md。

• 过滤器与属性。

  • 只有当各路径已接入搜索时，才支持 BitsetPtr、std::function<bool(int64_t)> 或 FilterPtr。
  • 如果支持属性过滤，实现属性存储/更新路径，并记录可接受的属性 schema。
  • 测试 bitset invalidation 语义和 Filter::CheckValid() keep 语义之间的差异。

• Allocator、resource 和线程集成。

  • 使用 IndexCommonParam::allocator_ 或派生的 allocator-aware 组件分配长期结构。
  • 当 build/search 工作并行化时，使用 Resource thread pool。
  • 确认自定义 allocator 和自定义 thread-pool 示例仍准确描述行为。
  • 只有在 add/search/delete/update 交互已测试后，才标记并发相关 feature。

• 内存和自省 API。

  • 当索引能报告有意义数字时，实现 EstimateMemory()、EstimateBuildMemory()、 GetMemoryUsage() 和 GetMemoryUsageDetail()。
  • 只有在底层存储支持时，才实现 GetMinAndMaxId()、CheckIdExist()、ExportIDs()、 GetVectorByIds()、GetDataByIds()、GetIndexDetailInfos() 或 GetDetailDataByName()。

• 模型导出、clone、merge、tune 和 cache 导入/导出。

  • 当索引可以在不错误共享可变存储的情况下复制时，实现 Clone() 和 ExportModel()。
  • 只有在参数兼容性、ID 重映射和删除语义清晰时，才实现 Merge()。
  • 只有带有明确参数解析和测试时，才实现 Tune()、ExportCache() 和 ImportCache()。

• 绑定、示例、benchmark 和文档。

  • Python 绑定通常只在公开 API surface 变化时需要更新；当前 pyvsag 用户通过名称和 JSON 参数创建索引。
  • 当索引引入新的用户工作流时，在 examples/cpp/ 下添加 C++ 示例。
  • 如果行为可从 pyvsag 触达，在 tests/python/ 下添加 Python 示例/测试。
  • 当 reviewer 需要可重复性能数据时，在 benchs/ 下添加 benchmark YAML。
  • 对用户可见的索引或参数，在 docs/docs/{en,zh}/src/ 下添加英文和中文网站文档。

Review Checklist

• Factory::CreateIndex() 和 Engine::CreateIndex() 能按文档名称创建索引。
• CheckFeature() 只对已实现且已测试的行为返回 true。
• 不支持的操作通过现有 wrapper 返回 UNSUPPORTED_INDEX_OPERATION。
• 序列化 round trip 保留索引声明支持的 ID、向量或压缩码、参数、删除状态、属性和 extra info。
• 每个支持的生命周期转换后，搜索结果仍然有效。
• 文档列出用户可见参数、支持的 metric/data type 和不支持的操作。
• 已运行实际验证：变更代码对应的单元/功能测试，以及文档-only 变更需要的格式检查或 git diff --check。

编译构建

VSAG 是一个 C++ 项目，使用 CMake 构建。项目源码使用 C++17 标准编写，请确保你使用的编译器支持 C++17 的语法。我们建议你使用 GCC 9.4.0 或者 Clang 13.0.0 以后的版本，因为这些版本在我们的开发中工作良好。

支持的平台包括 Ubuntu 20.04+、CentOS 7+，以及 Apple Silicon 上的 macOS 14+。 macOS 使用 Xcode Command Line Tools 提供的 Apple Clang 和 Homebrew 依赖；当前支持范围是 arm64 核心 C++ 构建，预编译 C++ 包与 Python wheel 仍以 Linux 为主。首次构建前运行：

./scripts/deps/install_deps.sh

脚本会自动选择 Linux 发行版或 macOS 对应的依赖安装流程。

如果需要启用 Linux io_uring 后端，请安装 liburing，并在直接配置 CMake 时添加 -DENABLE_LIBURING=ON。默认值为 OFF；在非 Linux 平台或未找到 liburing 时， 请求 uring_io 的配置会打印一次性告警并回退到 buffer_io。

在 CMake 配置中，有许多参数和编译目标。为了方便使用，我们将常用的编译目标（或命令）写到了 Makefile 中，使用 Unix Makefiles 进行管理，已避免记忆各种配置或者从命令行输入大段参数。这些编译目标（或命令）可以通过在项目根目录运行 make help 查看：

Usage: make <target>

Targets:
help:                    ## Show the help.
##
## ================ development ================
debug:                   ## Build vsag with debug options.
dev:                     ## Build full developer configuration.
test:                    ## Build and run unit tests.
asan:                    ## Build with AddressSanitizer option.
test_asan: asan          ## Run unit tests with AddressSanitizer option.
tsan:                    ## Build with ThreadSanitizer option.
test_tsan: tsan          ## Run unit tests with ThreadSanitizer option.
clean:                   ## Clear build/ directory.
##
## ================ integration ================
fmt:                     ## Format codes.
cov:                     ## Build unit tests with code coverage enabled.
lint:                    ## Check coding styles defined in `.clang-tidy`.
fix-lint:                ## Fix coding style issues in-place via clang-apply-replacements, use it be careful!!!
test_parallel:           ## Run all tests parallel (used in CI).
test_asan_parallel: asan ## Run unit tests parallel with AddressSanitizer option.
test_tsan_parallel: tsan ## Run unit tests parallel with ThreadSanitizer option.
##
## ================ distribution ================
release:                 ## Build vsag with release options.
dist-pre-cxx11-abi:      ## Build vsag with distribution options.
dist-cxx11-abi:          ## Build vsag with distribution options.
dist-libcxx:             ## Build vsag using libc++.
pyvsag:                  ## Build a specific Python version wheel. Usage: make pyvsag PY_VERSION=3.10
pyvsag-all:              ## Build wheels for all supported versions. Usage: make pyvsag-all
clean-release:           ## Clear build-release/ directory.
install:                 ## Build and install the release version of vsag.

编译 VSAG 库

make debug 是我们开发中最常用的命令，它会以开发模式编译整个项目，禁用大多数优化（-O0）并生成调试信息（-g）。该目标默认关闭测试、示例、工具和 Python 绑定；如需同时启用它们，可使用 make dev。

在默认设置下，开发模式的编译产物会生成在 ./build/ 目录中。可以通过如下命令运行单元测试：

./build/tests/unittests

以及通过如下命令运行功能测试：

./build/tests/functests

运行测试用例

除了上面提到的方法——编译后手动运行测试用例，VSAG 还支持用一条命令完成编译和运行所有测试：

make test

在我们的开发工作流中，代码修改完成后需要使用上述命令通过所有测试后，才会提交到 GitHub 仓库中。

内存和多线程测试

VSAG 是一个索引库，有大量的内存分配和并行计算的代码。我们依赖 AddressSanitizer 和 ThreadSanitizer 来检查发现内存和多线程的问题。当你在开发过程中遇到可疑的内存问题或者多线程问题，可以使用 make test_asan 或者 make test_tsan 来帮助问题发现。

清除编译工作区

当你在调试第三方库引入，或者 CMake options 时，可能会遇到明明修改了 cmake 文件却没有变化的问题，不妨试试 make clean 指令。它会清除掉 build/ 目录的所有内容，然后你就可以像刚下载的新项目一样从头编译了。

格式化代码

我们使用 clang-format 工具来保持代码风格的统一，对应的配置文件路径是 vsag/.clang-format。

make fmt 命令会自动将 VSAG 的源代码格式化。这个命令需要你的环境中安装有 clang-format。GitHub CI 会在每一个 Pull Request 中运行代码风格检查，以保证合并进主分支的代码风格一致。

代码覆盖率统计

make cov 会使用 coverage 参数来编译 VSAG 项目，使得测试用例运行后能够得到代码覆盖率统计文件。

静态代码分析

VSAG 使用 clang-tidy 工具来实现静态代码分析，旨在提前暴露一些编程规范上的问题，对应的配置文件路径是 vsag/.clang-tidy。

使用 make lint 可以在本地执行静态代码分析任务。同样地，可以使用 make fix-lint 来自动完成代码修复。

需要注意的是，fix-lint 命令会在源文件上直接修改，请确定你希望这样做！

编译发布模式

在生产环境中，我们需要使用发布模式的 VSAG 库。在此模式下，编译器会尽可能优化代码生成，以实现更好的运行性能。使用以下命令生成发布模式的 VSAG 库：

make release

为了和开发模式的产物区分开，发布模式的产物默认生成在 ./build-release/ 目录中。

如果你需要分发预编译产物，可使用以下目标以控制 ABI：

• make dist-pre-cxx11-abi：使用 -D_GLIBCXX_USE_CXX11_ABI=0 构建（pre-C++11 ABI）；
• make dist-cxx11-abi：使用 -D_GLIBCXX_USE_CXX11_ABI=1 构建（C++11 ABI）；
• make dist-libcxx：使用 libc++ 代替 libstdc++ 构建。

编译 pyvsag 包

pyvsag 是 VSAG 的 Python 版本。通过 pip install pyvsag 下载安装的 wheel 包就是通过 make pyvsag 命令构建出来的。

默认会使用 PY_VERSION=3.10，你可以显式指定目标 Python 版本：

make pyvsag PY_VERSION=3.11

或者一次构建所有受支持版本的 wheel：

make pyvsag-all

环境变量

在 Makefile 文件的开始可以看到一些 VSAG 编译系统定义的环境变量。这些变量可以通过命令行运行 export 命令，或者在 .bashrc / .zshrc 等 shell 配置文件中设置来修改。

环境变量说明如下：

• CMAKE_GENERATOR：CMake 内部使用什么来编译项目，默认是 "Unix Makefiles"，其他可选值请参考 CMake Generators；
• CMAKE_INSTALL_PREFIX：安装路径，即运行 make install 后头文件和库文件会被安装到哪里，一般不需要修改；
• COMPILE_JOBS：编译并行度，默认是 6 并行编译，建议设置成你的 CPU 核数以提高编译速度；
• DEBUG_BUILD_DIR：开发模式产物目录，非必要不修改；
• RELEASE_BUILD_DIR：发布模式产物目录，非必要不修改；
• VSAG_ENABLE_INTEL_MKL：是否启用 Intel MKL 作为 BLAS 后端，默认 OFF；关闭时使用 OpenBLAS；
• VSAG_ENABLE_LIBAIO：是否启用 libaio，默认 ON。

离线 / 内网环境构建

VSAG 会在配置 / 构建阶段下载第三方库。在离线或网络受限的环境中，可以设置按依赖的 VSAG_THIRDPARTY_* 环境变量，从本地路径或内网镜像（内网 HTTP 服务、OSS 存储桶等）获取每个 压缩包。完整的变量列表与示例见离线 / 内网环境构建。

发布流程

如果要在 GitHub 上手动发布 Release，请到 GitHub Actions 页面运行 Build and Publish Release 工作流，并填写以下参数：

• branch：要发布的分支、tag 或 commit SHA
• tag_name：新的发布标签，例如 v1.0.0
• prerelease：是否标记为预发布版本

如果你想在本地手动执行同样的打包流程，可以运行：

COMPILE_JOBS=6 bash ./scripts/release/dist.sh

如果机器内存足够，可以适当调大 COMPILE_JOBS；默认值会比较保守，以避免 CI 里再次触发 内存不足。

离线 / 内网环境构建

VSAG 在 CMake 配置 / 构建阶段会下载一批第三方库（通过 ExternalProject_Add 与 FetchContent）。在没有外网访问、或网络较慢 / 受限的机器上，这些下载可能失败或 超时。本文介绍如何把每个依赖指向本地路径或内网镜像（内网 HTTP 服务、对象 存储、Artifactory 等），从而在完全离线的环境中完成编译。

第三方下载的解析顺序

对每一个需要下载的依赖，VSAG 会构造一个候选 URL 列表，由 CMake 按顺序依次尝试， 命中第一个成功的即停止。以 antlr4 为代表 （extern/antlr4/antlr4.cmake）：

set (antlr4_urls
    https://github.com/antlr/antlr4/archive/refs/tags/4.13.2.tar.gz
)
vsag_resolve_thirdparty_override (ANTLR4 4.13.2 antlr4_urls)

ExternalProject_Add (antlr4
    URL ${antlr4_urls}
    URL_HASH MD5=3b75610fc8a827119258cba09a068be5
    ...)

因此解析顺序为：

1. 当前分支确切依赖标识符对应的固定版本变量（pinned variable） VSAG_THIRDPARTY_<LIB>_<PIN_SUFFIX>。
2. 未带版本的 VSAG_THIRDPARTY_<LIB>，作为已弃用的兼容兜底。如果两者都设置，固定版本变量优先。
3. 权威的上游 URL（一个或多个，来自 GitHub / 项目发布页）。

VSAG 不提供项目控制的压缩包镜像。如需使用本地或内网镜像，请设置固定版本变量（推荐）， 或临时使用已弃用的旧变量。

只会读取当前分支确切 pin 对应的固定版本变量。其他版本的变量可以一直保留在环境中，它们会被 忽略，因此同一个 CI 镜像或 shell 配置可以安全地支持多个 VSAG 分支。

固定版本变量命名

后缀由确切的固定标识符生成：

• 数字版本会去掉一个开头的 v/V，以及紧挨数字之前的依赖名装饰；ASCII 字母转为大写， 其他字符的连续段替换为一个下划线。因此 10.2.1 和 v10.2.1 得到 10_2_1， hdf5_1.14.4 得到 1_14_4，yaml-cpp-0.9.0 得到 0_9_0。
• 完整提交哈希得到 COMMIT_<12_HEX>，例如 VSAG_THIRDPARTY_CPUINFO_COMMIT_CA678952A9A8。
• 其他标签或 ref 得到 TAG_<NORMALIZED>_H<12_HEX>。十六进制部分是对大小写敏感的确切 标识符计算 SHA-256 后的大写前缀，所以规范化后相同的不同拼写仍可区分。
• 同一依赖的两个 pin 若在 12 个十六进制字符处冲突，两边会确定性地逐字符扩展。如果完整哈希 或摘要仍无法区分，配置会失败，而不会接受有歧义的名称。

开始前的关键事项

• 取值可以是本地路径，也可以是 URL。 支持绝对文件路径 （/data/deps/fmt-10.2.1.tar.gz）、file:// URL，或任意 http(s):// URL—— 包括内网 HTTP 服务或对象存储。
• 依然会校验压缩包哈希。 每个依赖都声明了 URL_HASH（MD5 或 SHA256）。你镜像 / 本地的压缩包必须与上游压缩包逐字节一致，否则 CMake 会因哈希不匹配而中止。最稳妥的 做法是把上游原始文件下载一次，原封不动地重新托管。
• 覆盖项在配置阶段读取。 如果你在上一次配置之后修改了变量，请重新执行 CMake 配置或 先运行 make clean，新值才会生效。
• 请使用非空值，否则就不要设置。 CMake 把“已 export 但为空”的变量视为已定义，因此 export VSAG_THIRDPARTY_FMT_10_2_1= 会把一个空项 prepend 到 URL 列表里，导致下载失败。若要停用 某个覆盖项，请 unset 它，而不要把它设为空字符串。
• 每个依赖相互独立。 没有单一的全局镜像变量；每个需要的依赖各自设置一个固定版本变量。 你只需为本次构建实际拉取的依赖设置变量（见 我需要哪些依赖？）。
• 日志中的确认信息。 CMake 会报告依赖、pin、选中的来源类别与变量，以及兜底 / 弃用行为。 由于 URL 可能包含凭据，日志不会打印变量值。

环境变量

每个依赖确切的上游 URL 以及期望的 URL_HASH，其唯一权威来源是对应的 extern/<lib>/<lib>.cmake 文件。镜像时（尤其是版本升级后）请以该文件为准。

此处未列出的（不下载，因此无需覆盖）：Intel MKL（通过 find_path 在主机上查找）。

我需要哪些依赖？

你只需镜像本次构建实际会下载的依赖：

• 核心库（make debug / make release）：JSON、ANTLR4、 OPENBLAS、CPUINFO、FMT、THREAD_POOL、TSL、ROARINGBITMAP。 其中两个是条件依赖：当 BLAS 由 Intel MKL（x86_64 且 ENABLE_INTEL_MKL=ON）或系统 OpenBLAS 提供时，OPENBLAS 不会下载；当找到系统 fmt 时，FMT 会被跳过。
• + 测试（make test，ENABLE_TESTS=ON）：另加 CATCH2。
• + 工具（ENABLE_TOOLS=ON 且 ENABLE_CXX11_ABI=ON）：另加 HDF5、 ARGPARSE、YAML_CPP、TABULATE、HTTPLIB——仅当两个选项同时开启时才会下载 （见 cmake/VSAGThirdParty.cmake）。
• + Python wheel（make pyvsag）：另加 PYBIND11。

示例

A. 内网 HTTP 服务或对象存储（推荐）

将上游压缩包原封不动地重新托管到内网地址，再让每个变量指向它。用一个基础 URL 的 shell 变量可以让配置更简洁：

# 内网镜像，逐字节提供上游压缩包
export VSAG_MIRROR=https://mirror.corp.example.com/vsag-thirdparty

export VSAG_THIRDPARTY_JSON_3_11_3=$VSAG_MIRROR/v3.11.3.tar.gz
export VSAG_THIRDPARTY_ANTLR4_4_13_2=$VSAG_MIRROR/antlr4-4.13.2.tar.gz
export VSAG_THIRDPARTY_OPENBLAS_0_3_24=$VSAG_MIRROR/OpenBLAS-0.3.24.tar.gz
export VSAG_THIRDPARTY_CPUINFO_COMMIT_CA678952A9A8=$VSAG_MIRROR/cpuinfo-ca678952.tar.gz
export VSAG_THIRDPARTY_FMT_10_2_1=$VSAG_MIRROR/fmt-10.2.1.tar.gz
export VSAG_THIRDPARTY_THREAD_POOL_COMMIT_3507796E172D=$VSAG_MIRROR/thread_pool-3507796e.tar.gz
export VSAG_THIRDPARTY_TSL_1_4_0=$VSAG_MIRROR/robin-map-1.4.0.tar.gz
export VSAG_THIRDPARTY_ROARINGBITMAP_3_0_1=$VSAG_MIRROR/CRoaring-3.0.1.tar.gz

make release

对象存储端点的用法完全相同：使用其网络可达的对象 URL 即可。

B. 预先下载的本地文件（完全离线）

在完全没有网络的机器上，先把压缩包拷贝到本机（例如 /data/vsag-deps），再让变量指向本地 文件：

export VSAG_THIRDPARTY_JSON_3_11_3=/data/vsag-deps/v3.11.3.tar.gz
export VSAG_THIRDPARTY_ANTLR4_4_13_2=/data/vsag-deps/antlr4-4.13.2.tar.gz
export VSAG_THIRDPARTY_OPENBLAS_0_3_24=/data/vsag-deps/OpenBLAS-0.3.24.tar.gz
export VSAG_THIRDPARTY_CPUINFO_COMMIT_CA678952A9A8=/data/vsag-deps/cpuinfo-ca678952.tar.gz
export VSAG_THIRDPARTY_FMT_10_2_1=/data/vsag-deps/fmt-10.2.1.tar.gz
export VSAG_THIRDPARTY_THREAD_POOL_COMMIT_3507796E172D=/data/vsag-deps/thread_pool-3507796e.tar.gz
export VSAG_THIRDPARTY_TSL_1_4_0=/data/vsag-deps/robin-map-1.4.0.tar.gz
export VSAG_THIRDPARTY_ROARINGBITMAP_3_0_1=/data/vsag-deps/CRoaring-3.0.1.tar.gz

make release

使用 file:// URL（export VSAG_THIRDPARTY_FMT_10_2_1=file:///data/vsag-deps/fmt-10.2.1.tar.gz） 同样有效。

C. 只覆盖单个依赖

如果只有某一个下载不稳定，只覆盖它即可，其余继续使用默认地址：

export VSAG_THIRDPARTY_OPENBLAS_0_3_24=https://mirror.example.com/OpenBLAS-0.3.24.tar.gz
make release

D. 同时保留多个分支的 pin

这些变量可以共存。后续各发布分支独立回移后，切换分支时会自动选择该分支自己的 pin， 无需修改环境：

export VSAG_THIRDPARTY_OPENBLAS_0_3_23=/data/vsag-deps/OpenBLAS-0.3.23.tar.gz
export VSAG_THIRDPARTY_OPENBLAS_0_3_24=/data/vsag-deps/OpenBLAS-0.3.24.tar.gz
export VSAG_THIRDPARTY_YAML_CPP_0_8_0=/data/vsag-deps/yaml-cpp-0.8.0.tar.gz
export VSAG_THIRDPARTY_YAML_CPP_0_9_0=/data/vsag-deps/yaml-cpp-0.9.0.tar.gz

git switch main   # 选择 OpenBLAS 0.3.24 与 yaml-cpp 0.9.0
make release

备选方案：复用系统库

对于主机上已安装的依赖，你可以直接跳过下载，而不必镜像。设置 VSAG_USE_SYSTEM_DEPS=ON（或按依赖设置 VSAG_USE_SYSTEM_<DEP>=ON）。当前支持系统复用的 依赖列表见 DEVELOPMENT.md。

常见问题

• 哈希不匹配 / 出现 “HASH mismatch” 错误 —— 你镜像或本地的压缩包与上游文件不是逐字节 一致。请重新下载确切的上游压缩包并原样托管，或在 extern/<lib>/<lib>.cmake 中核对期望的 URL_HASH。
• 覆盖项似乎未生效 —— 确认变量是在运行 make / cmake 的同一个 shell 中 export 的， 然后重新执行配置（或 make clean），因为取值是在 CMake 配置阶段读取的。确认配置输出中的 Third-party override 诊断包含预期的 pin 与变量。
• 仍然在访问网络 —— 多半是漏掉了本次构建会拉取的某个依赖。请对照 我需要哪些依赖？ 与你启用的选项（ENABLE_TESTS、ENABLE_TOOLS、 Python 绑定）逐项核对。

版本可用性

固定版本变量目前在 main 上实现；1.0、0.18、0.17 与 0.16 的回移需要独立完成， 因为每个分支拥有自己的 pin。已弃用的未带版本覆盖仍保持兼容。它最初由 #1606 在 main 引入，并通过 #2308 回移到发布线。内置 URL 兜底与 复用系统库的行为不变。

运行测试

VSAG 采用 Catch2 作为测试框架，测试分为两类：

• 单元测试：与源码同目录，位于 src/ 下，聚焦单个类/函数的行为。
• 功能测试：位于 tests/ 目录，覆盖跨模块、端到端的索引行为。典型用例包括 test_hgraph.cpp、test_ivf.cpp、test_pyramid.cpp、test_sindi.cpp、 test_brute_force.cpp、test_memleak.cpp 等。

构建并运行全部测试

make test 会以 Debug 配置重新编译（启用 ENABLE_TESTS=ON）并运行单元与功能测试：

make test

说明：

1. 运行 src/ 下的单元测试；
2. 运行 tests/ 下的功能测试；
3. make test 并未开启覆盖率（ENABLE_COVERAGE=ON）。需要覆盖率报告时请使用 make cov：该目标仅完成带覆盖率插桩的编译，随后需要手动运行测试二进制以生成报告。

仅运行单个测试二进制

构建完成后，可直接运行单个测试：

./build-debug/tests/functional_tests "[hgraph]"
./build-debug/tests/functional_tests "[hgraph][concurrent]"

Catch2 支持按名字、tag、通配符等方式筛选用例，详见 --help。

覆盖率

贡献时应保持 src/ 与 include/ 下代码的行覆盖率不低于 90%。在本地执行：

make cov
# 然后运行测试二进制以采集覆盖率，例如：
./build-debug/tests/functional_tests

报告会输出到 build-debug/coverage/ 下，可用浏览器打开 index.html 查看未覆盖的分支。

内存泄漏与多线程

• test_memleak.cpp：基于 AddressSanitizer / LeakSanitizer，对索引的构造/销毁路径进行验证。
• test_index/test_index_concurrent.cpp：对声明了相应 feature flag 的在维护索引， 验证共享的并发添加与搜索行为。

Python 测试

tests/python/ 包含 pyvsag 的 pytest 用例。构建好 pyvsag 后：

make pyvsag PY_VERSION=3.10
cd tests/python && pytest -q

参考

• 功能测试源代码目录：tests/
• 脚本入口：Makefile 中的 test、cov、asan 目标

贡献到 VSAG

首先，感谢你愿意花时间为 VSAG 做贡献！正是像你一样的贡献者帮助 VSAG 项目变得更好。🎉

如果你是第一次参与开源项目，我们非常推荐你跟着 这个项目 了解开源贡献的基本流程。

以下是为 VSAG 做贡献你可能需要知道的，了解这些有助于你更加轻松地为此项目做出贡献。

我可以做哪些贡献

1. 【报告错误】要报告 bug 或者文档问题，请创建 bug issue 并提供问题的详细信息。如果你认为该问题需要被优先关注，请在问题评论中 @ VSAG开发组。

2. 【提议新功能】要提议新功能，请创建 feature request issue。描述预期的功能，并与 VSAG 开发组和社区讨论设计和实现。一旦 VSAG 开发组同意该计划，就可以按照 贡献流程 来实施它。

3. 【开发功能或者修复错误】要开发未实现的功能或者修复错误，请遵循 贡献流程 。如果你需要关于这个问题的更多背景信息，可以在该问题上发表评论并 @VSAG开发组。

我该如何贡献

贡献代码

如果你有任何改进 VSAG 项目的地方，请创建你的 pull request！记得在你的 pull request 中引用相关 issue，如果有的话。

贡献流程

我们使用 GitHub Flow 来协作开发 VSAG 项目。了解 GitHub Flow 可以帮助你更快地参与到 VSAG 的社区开发中。

1. 在 GitHub 上 fork 一个 VSAG 仓库。
2. 使用 git clone git@github.com:<yourname>/vsag.git 命令将你的 fork 仓库下载到本地计算机。
3. 使用 git checkout -b my-topic-branch 创建分支。
4. 在本地进行修改，通过本地检查，创建提交并使用 git push --set-upstream origin my-topic-branch 推送到 GitHub。
5. 访问 GitHub 网站并创建 pull request。

如果你已有本地仓库，请在开始之前对其进行更新，以最大程度减少产生合并冲突的可能性。

git remote add upstream git@github.com:antgroup/vsag.git
git checkout main
git pull upstream main
git checkout -b my-topic-branch

一些准则

在创建 pull request 前，请确保你的修改通过了本地测试，并且符合 VSAG 编码风格。

• 在提交新功能时，pull request 需要包含功能测试，以证明你的代码是正常工作的，还可以避免未来的修改意外地破坏了这个功能。
• 在修复 bug 时，需要添加触发 bug 的测试用例，因为 bug 的存在通常表明测试覆盖不足。
• 在 VSAG 中修改代码时，要保持 API 的兼容性。
• 不要在 VSAG 的公开头文件（include/ 目录）中引用内部头文件（src/ 目录）。
• 当你向 VSAG 项目贡献新功能时，维护成本（默认情况下）会转移给 VSAG 开发组。这意味着我们要考虑贡献的好处和维护的成本。

签署 DCO（Developer Certificate of Origin）

对于本项目的所有贡献必须同意并附带 Developer Certificate of Origin（后简称 DCO） 的确认。对 DCO 的确认和同意必须包含在每一个 Commit Message 中，并采用 Signed-off-by: {{Full Name}} <{{email address}}>（不带 {}）的形式。如果贡献者不能或不愿意同意 DCO，其贡献将不会被接收。

贡献者可以通过在 Commit Message 中添加如下 Signed-off-by 行来签署 DCO：

This is my commit message

Signed-off-by: Random J Developer <random@developer.example.org>

Git 还有一个 -s 命令行选项，可以在提交时自动附加 Signed-off-by 行：

git commit -s -m "This is my commit message"

对于借助 AI Coding Agent（如 OpenCode、Claude Code、Codex 等）完成的贡献，仅由人类贡献者 签署 DCO；AI Agent 不得添加自己的 Signed-off-by trailer，因为只有人类才能合法地证明 DCO。每一位人类贡献者仍按常规各自添加自己的 Signed-off-by: trailer。除签名外，请按 Linux 内核 AI Coding Assistants 规范 使用 Assisted-by: trailer 标注 AI 协助，格式为 Assisted-by: AgentName:ModelVersion。 在 trailer 顺序上，请将人类的 Signed-off-by: 放在前面，Assisted-by: 放在其后，例如：

Signed-off-by: Random J Developer <random@developer.example.org>
Assisted-by: OpenCode:claude-opus-4.7

人类提交者需对 AI 生成的修改进行审阅、确保许可证合规，并对该贡献承担全部责任。

Commit 信息与 PR 标签

• Commit 信息请遵循 Conventional Commits，常用前缀包括 feat:、fix:、docs:、chore:、refactor:、test:、ci: 等；
• 如果该 commit 无需触发 CI，请将 [skip ci] 放在 commit subject 的开头，例如 [skip ci] docs: fix typo in README；
• 每一个 PR 都必须至少包含以下两类 label（由 Mergify 强制校验，否则无法合并）：
  • kind/*：变更类型，可选值为 kind/bug、kind/feature、kind/improvement、kind/documentation；
  • version/*：目标版本，例如 version/1.0、version/0.18。

编码风格

修改 C++ 代码前，请阅读 C++ 编码指南。其中说明了 VSAG 要求的 clang-format 15 和 clang-tidy 15 规则、命名约定、诊断抑制方式以及本地检查命令。

本地测试

VSAG 项目使用 Makefile 提供了方便运行所有测试的命令，请执行并确认所有测试通过：

make test

索引构建与训练

VSAG 把索引构建拆成三个阶段：

1. Train —— 在样本数据上拟合内部量化器 / 分区器。
2. Add —— 用训练好的编码器把向量插入索引。
3. Build —— 一站式包装：在同一份数据上先 Train 再 Add。

绝大多数用户只需要调用 Build。下面两种情况值得单独说明：

• Train + 增量 Add。 当语料规模大或者数据是分批到达时，可以先用代表性样本训练，再通过 Add 流式追加（无需重建索引）。参考 examples/cpp/311_feature_train.cpp。
• ODescent。 HGraph / Pyramid 的另一种构图算法，采用批量迭代精修而非逐条插入。参考 examples/cpp/312_feature_odescent.cpp。

Train API

tl::expected<void, Error> Index::Train(const DatasetPtr& data);

声明位置 include/vsag/index.h。在（通常是抽样的）数据集上训练索引，但不写入这些 向量。返回 tl::expected<void, Error>，使用 .has_value() 判断成功与否。

具备实质训练逻辑的索引：HGraph、IVF、BruteForce、WARP、Pyramid。对它们 来说，Build(data) 会先训练再写入向量 —— 默认 NSW 构图模式下相当于 Train(data) 之后再 Add(data)，而当 HGraph / Pyramid 配置 graph_type: "odescent" 时，写入阶段会走 ODescent 的批量构图路径，而不是逐条 Add（见 src/algorithm/ 下的 HGraph::build_by_odescent / Pyramid::Build）。

何时需要单独调用 Train

• 基础量化器需要训练。能力标志 IndexFeature::NEED_TRAIN 在 HGraph 与 IVF 中可靠反映这一点：HGraph 当 base_quantization_type 不是 fp32 / fp16 / bf16 时设置（src/algorithm/hgraph.cpp:1803）；IVF 始终设置 （src/algorithm/ivf.cpp:316），因为其聚类中心必须训练。Pyramid 目前在 InitFeatures() 中不会设置 NEED_TRAIN，即使其内部 HGraph 量化器需要训练，因此请勿依赖 HasFeature(NEED_TRAIN) 来判断 Pyramid —— 当你选用需要训练的 base_quantization_type 时请显式调用 Train。fp32 / fp16 / bf16 不需要训练（即使调用了 Train 也是无副作用的 空操作）。
• 希望分多批次写入向量，而不是一次性通过 Build 写完。
• 希望导出已训练的模型供其他索引实例复用（通过 ExportModel）。

用法：训练一次，流式追加

auto params = R"({
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "max_degree": 32,
        "ef_construction": 100,
        "base_quantization_type": "sq8"
    }
})";
auto index_result = vsag::Factory::CreateIndex("hgraph", params);
if (!index_result.has_value()) {
    std::cerr << "Create index failed: " << index_result.error().message << std::endl;
    return -1;
}
auto index = index_result.value();

// 第 1 步 —— 在全量（或代表性样本）上训练。
auto train_result = index->Train(base);
if (!train_result.has_value()) {
    std::cerr << "Train failed: " << train_result.error().message << std::endl;
    return -1;
}

// 第 2 步 —— 逐条或小批量追加向量。
for (int64_t i = 0; i < num_vectors; ++i) {
    auto one = vsag::Dataset::Make();
    one->NumElements(1)
       ->Dim(dim)
       ->Ids(ids + i)
       ->Float32Vectors(vectors + i * dim)
       ->Owner(false);
    auto add_result = index->Add(one);
    if (!add_result.has_value()) { /* handle */ }
}

完整示例见 examples/cpp/311_feature_train.cpp。

Train / Build / Add 三者对比

ODescent：另一种构图算法

HGraph 与 Pyramid 默认使用 NSW 风格 构图 —— 每条向量逐条插入，在插入时通过搜索找到邻居 并建边（graph_type: "nsw"）。ODescent（“Optimized NN-Descent”）是另一种实现：先在 完整数据集上初始化一张随机 k-NN 图，然后通过若干轮采样候选交换迭代精修边。

在大批量构建场景下，ODescent 通常能在召回率相当的情况下显著降低构图开销，因为精修循环可以 在数据维度上整齐并行，避免了逐条插入时的单点搜索。

ODescent 的实现位于 src/impl/odescent/odescent_graph_builder.{h,cpp}，目前被 HGraph、Pyramid（构图路径）使用。

在 HGraph 中启用 ODescent

在 HGraph 的 index_param 中加入 graph_type: "odescent"：

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 26,
        "ef_construction": 100,
        "graph_type": "odescent",
        "graph_iter_turn": 10,
        "neighbor_sample_rate": 0.3,
        "alpha": 1.2
    }
}

然后正常调用 Build(data) 即可，无需其他 API 调整。完整示例见 examples/cpp/312_feature_odescent.cpp。

ODescent 构图参数

下列键放在 index_param 中，与常规 HGraph 参数并列：

max_degree 沿用 HGraph 顶层配置，无需在 ODescent 这里重复指定；图的上层会自动使用 max_degree / 2。

ODescent vs NSW 如何选择

• 选 ODescent：已经有完整数据集，并希望充分利用多核机器加速构图。批量精修比逐条插入的 并行度更高。
• 选 NSW（默认）：需要增量构建索引，或希望构图阶段内存占用尽量小，又或者尚未观察到构图 耗时的瓶颈。

两种算法构出的图在查询期完全等价，所有搜索参数（ef_search、pq_rerank 等）保持不变。

参考

• 创建索引
• HGraph 索引参数
• Pyramid 索引参数
• 索引参数参考

HGraph 构建缓存

HGraph 可以从一次构建中导出图邻居信息，并在下一次 Build() 前导入。向量通过稳定的 字符串 Source ID 匹配，因此未变化的数据可以从旧图 warm-start，新数据或已变化数据 仍走正常的 refine 流程。

该流程适用于周期性快照构建，例如每天从大部分重叠的语料重建索引。它是构建加速器， 不是索引序列化格式；可搜索索引仍应使用普通序列化接口持久化。

使用条件

• 索引类型必须是 HGraph。
• 流程中的每个 base Dataset 都必须设置 Dataset::SourceID。
• 希望跨构建匹配的逻辑记录必须使用稳定且唯一的 Source ID。
• 在调用 Build() 前，把缓存导入全新、为空且兼容的 HGraph。
• 两次构建的维度、度量和存储/量化参数应保持兼容。

不同快照中的 Dataset::Ids 数字 label 可以变化；缓存使用对应的 SourceID 字符串匹配。

首次构建并导出缓存

构建源索引时，为每个向量提供一个 Source ID：

std::vector<std::string> source_ids = load_stable_source_ids();

auto base = vsag::Dataset::Make();
base->NumElements(count)
    ->Dim(dim)
    ->Ids(ids.data())
    ->Float32Vectors(vectors.data())
    ->SourceID(source_ids.data())
    ->Owner(false);

auto index = vsag::Factory::CreateIndex("hgraph", build_params).value();
index->Build(base).value();

std::ofstream cache_out("hgraph.cache", std::ios::binary);
index->ExportCache(cache_out).value();

在 Build() 执行期间要保持 std::string 数组有效。缓存包含后续构建使用的 Source ID 到邻居信息映射，本身不可直接用于搜索。

Warm-start 下一次构建

创建空的兼容 HGraph，导入旧缓存，再构建新快照：

auto next_index = vsag::Factory::CreateIndex("hgraph", build_params).value();

std::ifstream cache_in("hgraph.cache", std::ios::binary);
next_index->ImportCache(cache_in).value();

auto next_base = vsag::Dataset::Make();
next_base->NumElements(next_count)
    ->Dim(dim)
    ->Ids(next_ids.data())
    ->Float32Vectors(next_vectors.data())
    ->SourceID(next_source_ids.data())
    ->Owner(false);

next_index->Build(next_base).value();

调用 ImportCache() 后，Build() 会自动进入缓存辅助路径。两个快照中都存在的 Source ID 使用缓存邻居 warm-start；未匹配记录作为 cache miss 走正常构建 refine。 缓存辅助 Build() 未设置 Dataset::SourceID 时会返回参数错误。

随索引持久化 Source ID

HGraph 默认不会在序列化中写入 Source ID 元数据。如果反序列化后的索引还需要 调用 ExportCache()，请在 index_param 中设置 persist_source_id: true：

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 32,
        "ef_construction": 400,
        "persist_source_id": true
    }
}

该选项会给序列化索引增加 Source ID 元数据。如果缓存始终从首次内存构建中导出， 恢复后的索引不需要 Source ID 映射，则无需开启。

度量缓存复用

warm-start 构建完成后调用 GetStats()，检查：

如果上一次构建没有使用导入缓存，统计会输出 skipped_reason。其他 HGraph 指标见索引分析。

限制与运维建议

• 必须先 Import 再 Build()；缓存辅助构建要求索引为空。
• 构建缓存依赖兼容的 HGraph 配置；参数发生不兼容变化后应重新生成。
• deduplicate_storage: true 不能与缓存辅助构建组合。
• 生产使用前，应和完整重建对比召回率与构建时间。
• 检查文件流是否成功打开，并处理 API 返回值。缓存文件与可搜索的序列化索引相互独立， 应和生成它的快照一起版本化，或通过原子方式替换。

API 签名见 Index 缓存接口，Source ID 字段见 Dataset。

范围搜索

除了 k-近邻搜索（KnnSearch），VSAG 还支持范围搜索（RangeSearch）：返回所有与查询向量距离 小于或等于指定半径的结果。该接口适用于阈值过滤、去重、近似召回等场景。

基本用法

#include <vsag/vsag.h>

// 1. 构造索引（以 HGraph 为例）
auto index = vsag::Factory::CreateIndex("hgraph", hgraph_build_params).value();
index->Build(dataset);

// 2. 准备查询
auto query = vsag::Dataset::Make();
query->NumElements(1)->Dim(dim)->Float32Vectors(query_vec)->Owner(false);

// 3. 范围搜索
float radius = 0.5f;
auto result = index->RangeSearch(query, radius, search_params);
if (result.has_value()) {
    auto ids = result.value()->GetIds();
    auto dists = result.value()->GetDistances();
    int64_t n = result.value()->GetDim();
    // ...
}

完整示例参见 examples/cpp/302_feature_range_search.cpp。

limited_size 参数

RangeSearch 支持通过 limited_size 限制返回结果的最大数量：

// 返回最多 100 条满足半径条件的结果
auto result = index->RangeSearch(query, radius, search_params, /*limited_size=*/100);

• limited_size = -1（默认）：返回所有满足条件的结果（不限）。
• limited_size > 0：在满足半径条件的候选中返回最多这么多条。
• limited_size = 0：非法取值，实现中会显式拒绝 （CHECK_ARGUMENT(limited_size != 0, ...)）。

与 Filter 组合

RangeSearch 的签名与 KnnSearch 一致，同样支持传入过滤器（见 examples/cpp/301_feature_filter.cpp）。 过滤器在搜索过程中即时生效，而不是事后过滤，效率更高。

支持情况

注意事项

• 距离度量（内积 / L2 / 余弦）会影响 radius 的语义。请与索引创建时的 metric_type 保持一致。
• 当 radius 过大时结果集可能巨大，建议配合 limited_size 使用。
• 对于图类索引（HGraph），RangeSearch 的 ef 等运行期参数与 KnnSearch 共享含义。

按 ID 计算距离

除了 KnnSearch 和 RangeSearch，VSAG 还提供了在已建好索引的向量上按 ID 计算距离的 接口，可用于对外部候选集进行重排、召回核验，或在 VSAG 之上构建自定义检索流水线。

接口分为两种形式：

• CalcDistanceById — 单个 ID，返回单个距离值。
• CalcDistancesById — 一批 ID，返回一个包含距离数组的 DatasetPtr。

每种形式都有两个重载：一个接收 const float*（稠密向量），另一个接收 DatasetPtr （稠密或稀疏均可）。

迁移说明。 CalDistanceById 是批量接口的历史拼写。为兼容已有代码，1.1 迁移窗口内 仍保留该弃用别名；新代码应使用 CalcDistancesById。两者语义完全相同。详情参见 issue #2068。

接口概览

// 单个 ID，稠密浮点指针
tl::expected<float, Error>
CalcDistanceById(const float* vector,
                 int64_t id,
                 bool calculate_precise_distance = true) const;

// 单个 ID，DatasetPtr（稠密或稀疏）
tl::expected<float, Error>
CalcDistanceById(const DatasetPtr& vector,
                 int64_t id,
                 bool calculate_precise_distance = true) const;

// 批量 ID，稠密浮点指针
tl::expected<DatasetPtr, Error>
CalcDistancesById(const float* query,
                const int64_t* ids,
                int64_t count,
                bool calculate_precise_distance = true,
                int64_t topk = -1) const;

// 批量 ID，DatasetPtr（稠密或稀疏）
tl::expected<DatasetPtr, Error>
CalcDistancesById(const DatasetPtr& query,
                const int64_t* ids,
                int64_t count,
                bool calculate_precise_distance = true,
                int64_t topk = -1) const;

对于 NumElements() > 1 的 DatasetPtr 查询，请先检查 SUPPORT_BATCH_CALC_DISTANCE_BY_ID。count 表示每个 query 的 ID 数，ids 需要包含 NumElements() * count 个 row-major ID，返回距离使用相同布局。当 topk > 0 时， 每个 query 返回按距离升序排列的 min(topk, count) 个结果，并同时返回对应 ID。

声明位于 include/vsag/index.h。

calculate_precise_distance

• true（默认）：尽量使用高精度向量表示（如完整 float32）来计算距离。当索引仅保留 量化编码时，获取精确值可能开销更大。
• false：可以使用索引内存中已有的量化 / 近似表示，速度更快但距离是近似值。

返回值含义

• 单 ID 重载返回 float 距离值。
• topk == -1 时，裸指针批量重载返回一行 count 个距离；DatasetPtr 重载返回 NumElements() 行、每行 count 个距离。两者都保持输入顺序，且不返回 ID。
• topk > 0 时，批量重载每个 query 返回按距离升序排列的最小 min(topk, count) 个 距离，GetIds() 包含对应 ID。无效 ID（距离为 -1）排在有效距离之后，仅在有效 ID 不足时才出现在结果中。
• 距离的语义由建索引时设置的 metric_type（IP / L2 / cosine）决定，参见 度量语义。

基本用法

#include <vsag/vsag.h>

// 1. 构建 HGraph 索引
auto index = engine.CreateIndex("hgraph", hgraph_build_parameters).value();
index->Build(base);

// 2. 单 ID 距离
auto d = index->CalcDistanceById(query_vector.data(), /*id=*/42);
if (d.has_value()) {
    std::cout << "distance to id 42 = " << d.value() << std::endl;
}

// 3. 批量 ID 距离
std::vector<int64_t> ids = { 1, 2, 3, 4, 5 };
auto result = index->CalcDistancesById(query_vector.data(), ids.data(), ids.size());
if (result.has_value()) {
    const float* dists = result.value()->GetDistances();
    for (size_t i = 0; i < ids.size(); ++i) {
        if (dists[i] == -1.0f) {
            std::cout << ids[i] << " -> 无效 ID" << std::endl;
        } else {
            std::cout << ids[i] << " -> " << dists[i] << std::endl;
        }
    }
}

多查询

当索引公布 SUPPORT_BATCH_CALC_DISTANCE_BY_ID 能力时，DatasetPtr 批量重载可以一次接收 多个 query。候选 ID 和输出都采用 row-major 布局。对于 LazyHGraph，调用会委托给当前生效的 内部索引；即使 wrapper 公布了该能力，实际支持也可能在 phase 切换后改变，因此仍需处理返回错误：

// 两个稠密 query，每个 query 三个候选 ID。
auto queries = vsag::Dataset::Make()
                   ->NumElements(2)
                   ->Dim(dim)
                   ->Float32Vectors(query_vectors.data())
                   ->Owner(false);
std::vector<int64_t> candidate_ids = {
    10, 11, 12,  // query 0 的候选
    20, 21, 22   // query 1 的候选
};

if (index->CheckFeature(vsag::SUPPORT_BATCH_CALC_DISTANCE_BY_ID)) {
    auto result = index->CalDistanceById(queries, candidate_ids.data(), 3, true, /*topk=*/2);
    if (result.has_value()) {
        auto batch = result.value();
        // batch 的 NumElements() == 2，Dim() == 2。
        for (int64_t q = 0; q < batch->GetNumElements(); ++q) {
            for (int64_t j = 0; j < batch->GetDim(); ++j) {
                const int64_t offset = q * batch->GetDim() + j;
                std::cout << batch->GetIds()[offset] << ": "
                          << batch->GetDistances()[offset] << '\n';
            }
        }
    }
}

topk == -1 时，GetDim() 等于 count，位置 q * count + j 对应输入 ID ids[q * count + j]。topk 为正数时，行跨度为 GetDim()；每行先放最近的有效候选， 只有有效 ID 少于 topk 时才会在行尾保留无效 ID。

可运行的完整示例见 examples/cpp/306_feature_calculate_distance_by_id.cpp。

稀疏向量

对于 SINDI 等稀疏向量索引，const float* 重载不适用。需要通过 SparseVectors(...) 把查询 封装为 DatasetPtr，并调用 DatasetPtr 重载：

auto query = vsag::Dataset::Make();
query->NumElements(1)->SparseVectors(&sparse_query)->Owner(false);

auto d = index->CalcDistanceById(query, /*id=*/42);

支持矩阵

对于未实现某重载的索引，调用会返回 UNSUPPORTED_INDEX_OPERATION 错误。

注意事项

• 稠密重载中，查询向量的维度必须与索引维度一致。
• 批量重载存在默认实现：循环调用单 ID 接口；部分索引会重写以做批量优化。
• 与 VSAG 其他只读接口一样，这些方法可以与 KnnSearch 等只读操作并发调用。

带过滤的搜索

带过滤的搜索（Filtered Search）允许在 KnnSearch 或 RangeSearch 中只保留满足应用自定义条件 的向量。当底层索引算法支持时，VSAG 会在图遍历过程中应用该谓词，从而避免“先取 top-k 再丢弃” 所带来的召回率损失与额外延迟。

本文介绍三种基于 id 的过滤 API：

• 位图过滤（Bitset filter）：以向量 id 作为下标的紧凑位数组。
• 函数回调过滤（Function callback）：std::function<bool(int64_t)>。
• Filter 对象：继承自 vsag::Filter 的子类，除了判定逻辑之外还可以向算法暴露 有效占比、分布等提示信息。

如果谓词是结构化字段上的 SQL 风格表达式，请阅读 属性过滤（混合搜索）；如果是基于每条向量的不透明字节负载在图内过滤， 请阅读 Extra Info（附加信息）。

真值约定

三种 API 关于「这个 id 是否被排除」的语义并不一致，混用前请仔细对照下表。

位图与 std::function 两种重载在内部都会被包装为 BlackListFilter （见 src/impl/filter/black_list_filter.cpp）：位被置上、或回调返回 true，都表示该 id 被排除。Filter::CheckValid 则相反——返回 true 表示保留。如果你已经维护了一份 「删除 id 位图」，最自然的方式是位图过滤；如果是任意谓词逻辑、并且能提供有效占比等提示， Filter 对象会更合适。

位图过滤

vsag::Bitset（include/vsag/bitset.h）是按序号下标的可增长位数组。

auto invalid = vsag::Bitset::Make();
for (int64_t i = 0; i < num_vectors; ++i) {
    if (ids[i] % 2 == 0) {
        invalid->Set(ids[i]);    // 偶数 id 被排除
    }
}

auto search_params = R"({ "hgraph": { "ef_search": 100 } })";
auto result = index->KnnSearch(query, /*topk=*/10, search_params, invalid).value();

位图按向量 id 索引，但查询时 id 会被掩码到低 32 位 （bit_index = id & ROW_ID_MASK，ROW_ID_MASK = 0xFFFFFFFFLL，见 src/impl/filter/black_list_filter.cpp）。低 32 位相同的两个 id 会在位图中冲突，因此使用 位图过滤时请把 id 控制在 [0, 2^32)，否则改用 Filter 对象。位图按 id 索引而非按插入 顺序；如果应用层会复用 id，请自行处理一致性。

函数回调过滤

直接使用 lambda 或 std::function<bool(int64_t)> 即可。回调返回 true 表示该 id 被 排除（内部会被包装成 BlackListFilter）：

// 排除偶数 id：返回 true 即被过滤掉。
std::function<bool(int64_t)> drop_even = [](int64_t id) { return id % 2 == 0; };
auto result = index->KnnSearch(query, 10, search_params, drop_even).value();

适合写少量自定义逻辑而不需要继承类的场景。如果你更习惯「返回 true 表示保留」的写法， 请改用 Filter 对象。

Filter 对象

最完整的 API 是 vsag::Filter（include/vsag/filter.h）。当算法可以利用谓词的额外提示 （如有效占比）时，建议继承它：

class MyFilter : public vsag::Filter {
public:
    bool CheckValid(int64_t id) const override {
        return id % 2 == 1;
    }

    // 谓词通过率的近似估计；搜索算法据此调整候选缓冲区大小，
    // 估计准确可同时改善延迟与召回率。
    float ValidRatio() const override { return 0.5F; }

    // 通过的 id 是否在向量空间中聚集。
    // NONE 表示「无关」；如果谓词与向量位置相关（例如地理标签），用 RELATED_TO_VECTOR。
    Distribution FilterDistribution() const override { return Distribution::NONE; }
};

auto filter = std::make_shared<MyFilter>();
auto result = index->KnnSearch(query, 10, search_params, filter).value();

主要方法：

ValidRatio 估计错误不会导致结果错误，但偏大会增大延迟、偏小会拉低召回率。

重载列表

KnnSearch 与 RangeSearch 都提供四种过滤形态（include/vsag/index.h）：

// KnnSearch
index->KnnSearch(query, topk, params);                                    // 不过滤
index->KnnSearch(query, topk, params, BitsetPtr invalid);
index->KnnSearch(query, topk, params, std::function<bool(int64_t)> f);
index->KnnSearch(query, topk, params, FilterPtr filter);

// RangeSearch
index->RangeSearch(query, radius, params, limited_size);                  // 不过滤
index->RangeSearch(query, radius, params, BitsetPtr invalid, limited_size);
index->RangeSearch(query, radius, params, std::function<bool(int64_t)> f, limited_size);
index->RangeSearch(query, radius, params, FilterPtr filter, limited_size);

limited_size 是 RangeSearch 返回结果的最大数量：

• limited_size < 0：不限制（默认 -1）。
• limited_size == 0：API 会显式拒绝（CHECK_ARGUMENT(limited_size != 0, ...)）， 「不限制」请传 -1。
• limited_size > 0：限定结果列表最多这么多条。

也支持迭代式过滤搜索：

vsag::IteratorContext* ctx = nullptr;
index->KnnSearch(query, topk, params, filter, ctx, /*is_last_search=*/false);
// 用同一个 ctx 反复调用；最后一次调用时把 is_last_search 置为 true 以释放上下文。

索引支持矩阵

所有索引类型都接受位图、函数与 FilterPtr 三种形式——内部会把位图与 lambda 自动包装成 FilterPtr。下表中的列对应每个索引登记的能力标志（见 include/vsag/index_features.h），运行时 CheckFeature 返回的也是这些。

基于 id 的过滤可在运行时通过 index->CheckFeature(vsag::SUPPORT_KNN_SEARCH_WITH_ID_FILTER)、 SUPPORT_RANGE_SEARCH_WITH_ID_FILTER、SUPPORT_KNN_ITERATOR_FILTER_SEARCH 查询。 SUPPORT_KNN_SEARCH_WITH_EX_FILTER 与本文无关，它对应的是基于 extra_info 字节负载的 过滤，详见 Extra Info。

性能要点

• 谓词越严格（ValidRatio 越小），搜索需要扩展的候选越多。对图索引而言，谓词非常严格时 应同步增大 ef_search，否则当通过率低于约 1% 时召回率会显著下降。
• HGraph 还提供选择率感知的暴搜回退：在搜索参数里设置 brute_force_threshold（例如 0.01–0.05），当 Filter::ValidRatio() 足够 小时，HGraph 会自动跳过图遍历，对通过过滤的 id 做一次精确暴扫。当谓词非常 严格时，这通常比一味把 ef_search 调到很大更划算。详见 HGraph 索引文档 以及示例 322_feature_hgraph_brute_force_threshold.cpp。
• 位图过滤最快，因为 Test() 只是一次位查询。Filter 对象内若有重逻辑，需注意它会被 调用很多次。
• RangeSearch 在过滤通过率较高、范围较宽时建议设定一个合理的 limited_size，避免结果 集无界增长。
• 与 属性过滤 组合时，使用 SearchRequest 即可，所有启用的过滤项 会按逻辑 AND 连接。

通过 SearchRequest 组合过滤

SearchRequest（include/vsag/search_request.h）是 SearchWithRequest 的统一入口， 可同时携带位图、Filter 对象与属性表达式，所有启用的过滤项按 AND 连接：

vsag::SearchRequest req;
req.query_                = query;
req.mode_                 = vsag::SearchMode::KNN_SEARCH;
req.topk_                 = 10;
req.params_str_           = R"({ "hgraph": { "ef_search": 200 } })";
req.enable_filter_        = true;
req.filter_               = std::make_shared<MyFilter>();
req.enable_bitset_filter_ = true;
req.bitset_filter_        = invalid;
auto result = index->SearchWithRequest(req).value();

attribute_filter_str_ 字段的语法见 属性过滤。

示例

• C++：examples/cpp/301_feature_filter.cpp ——同时演示三种过滤方式。
• C++：examples/cpp/320_feature_extra_info.cpp ——基于 CheckValid(const char*) 字节负载重载的图内过滤。

Python 状态

过滤 API 暂未暴露到 Python；examples/python/todo_examples/301_feature_filter.py 是一个空占位文件。当前请使用 C++ API 进行带过滤的搜索。

迭代式搜索

VSAG 支持迭代式搜索（Iterator Search）：调用方无需一次性请求 top-k，而是可以分多次、增量地 拉取结果，VSAG 在调用之间保留内部搜索状态。后续调用会从上一次结束的位置继续，返回不重叠的 新结果。

适用场景：

• 上层应用有外部 rerank 或后过滤逻辑，需要边拉取边判断，直到攒够通过条件的结果。
• 结果消费是惰性 / 流式的（如分页 UI、服务器端游标）。
• 最终需要的 k 不确定，需按需扩展。

工作原理

迭代式搜索依赖一个生命周期较长的 IteratorContext 对象，其中保存：

• 当前的候选堆与已访问位图；
• 在底层图 / 倒排链上的游标。

首次调用时，如果传入的指针为 nullptr，索引会在内部创建一个 IteratorContext；后续调用复用它， 搜索因此可以“继续“而不是“重新开始“。调用方完成后需要自行 delete 这个 IteratorContext—— 迭代器持有的内部状态由 delete 释放。

is_last_search 标记是可选的：当置为 true 时，索引会把上下文里仍缓存的候选（“discard heap” 中尚未对外返回的部分）作为该次调用的结果一次性输出。如果你需要这部分尾部候选，就发起一次 is_last_search=true 的调用；如果不需要，直接 delete 上下文即可，无需“收尾调用“。注意返回结果 仍会被 k 截断，想拿到全部尾部候选时需要把 k 设得足够大。

基本用法（SearchParam API）

#include <vsag/vsag.h>

// 1. 构造索引（以 HGraph 为例）
auto index = vsag::Factory::CreateIndex("hgraph", hgraph_build_params).value();
index->Build(dataset);

// 2. 准备查询
auto query = vsag::Dataset::Make();
query->NumElements(1)->Dim(dim)->Float32Vectors(query_vec)->Owner(false);

// 3. 以迭代模式配置 SearchParam
nlohmann::json search_parameters = {
    {"hgraph", {{"ef_search", 100}}},
};
std::string param_str = search_parameters.dump();

vsag::SearchParam search_param(
    /*iter_filter_flag=*/true,   // 开启迭代模式
    param_str,
    /*filter=*/nullptr,
    /*allocator=*/&allocator,
    /*iter_ctx=*/nullptr,        // 首次调用：内部自动创建上下文
    /*last_search_flag=*/false);

// 4. 第一页
auto page1 = index->KnnSearch(query, /*k=*/10, search_param).value();

// 5. 后续页：上下文延续，结果与 page1 不重叠
auto page2 = index->KnnSearch(query, /*k=*/10, search_param).value();

// 6. （可选）取出上下文中仍缓存的候选；如果不需要，可跳过本步，
//    清理只依赖第 7 步的 delete。
search_param.is_last_search = true;
auto page3 = index->KnnSearch(query, /*k=*/10, search_param).value();

// 7. 由调用方销毁上下文——这才是真正释放资源的地方。
delete search_param.iter_ctx;

参考示例：examples/cpp/313_feature_search_allocator.cpp、 examples/cpp/314_feature_hgraph_search_allocator.cpp。

另一种写法：显式传入 IteratorContext

更底层的 KnnSearch 重载允许直接传入 IteratorContext*&，VSAG 自身的测试用例 tests/test_index/test_index_search.cpp 即采用这种形式连续调用：

vsag::IteratorContext* iter_ctx = nullptr;

auto r1 = index->KnnSearch(query, k1, param_str, filter, iter_ctx, /*is_last_search=*/false);
auto r2 = index->KnnSearch(query, k2, param_str, filter, iter_ctx, /*is_last_search=*/false);
auto r3 = index->KnnSearch(query, k3, param_str, filter, iter_ctx, /*is_last_search=*/false);

delete iter_ctx;

每次调用都会推进 iter_ctx；多次结果的并集就是按距离顺序、不重叠的延续序列。如果还想取出 上下文中仍缓存的尾部候选，可以在最后再加一次 is_last_search=true 的调用。

SearchRequest API。 SearchRequest 中定义了 enable_iterator_search_ / p_iter_ctx_ / is_last_search_ 三个字段，但仓库内当前的 SearchWithRequest 实现尚未 读取这些字段，无法通过 SearchWithRequest 触发迭代式搜索。在这部分接入完成之前，请使用 上面两种 KnnSearch 形式。

与过滤器组合

迭代式搜索可以与常规过滤器（label filter、attribute filter、bitset filter）组合，典型场景是 “持续迭代直到外部检查通过的结果攒够”：

size_t needed = 50;
std::vector<int64_t> kept;
vsag::IteratorContext* ctx = nullptr;

while (kept.size() < needed) {
    auto page = index->KnnSearch(query, 32, param_str, filter, ctx, /*is_last_search=*/false);
    if (!page.has_value() || page.value()->GetDim() == 0) break;

    for (int64_t i = 0; i < page.value()->GetDim(); ++i) {
        if (external_check(page.value()->GetIds()[i])) {
            kept.push_back(page.value()->GetIds()[i]);
        }
    }
}

// 释放迭代器内部状态；不需要"收尾调用"，
// 仅当还想取出上下文里仍缓存的候选时，再加一次 is_last_search=true 的调用。
delete ctx;

HGraph 图索引在迭代模式下还支持一个额外的运行期参数 skip_ratio，用于控制延续搜索时跳过已探索区域 的力度，详见 examples/cpp/314_feature_hgraph_search_allocator.cpp。

支持情况

通过 Index::CheckFeature 查询 SUPPORT_KNN_ITERATOR_FILTER_SEARCH 是否被支持：

使用前请在运行时通过 index->CheckFeature(vsag::SUPPORT_KNN_ITERATOR_FILTER_SEARCH) 检查，后续版本 中支持范围可能会扩大。

注意事项

• 所有权。 IteratorContext 由调用方持有，忘记 delete 会泄漏内部搜索状态（堆、已访问位图、 allocator 临时分配）。资源释放完全依赖 delete，与 is_last_search 无关。
• 最后一次调用是可选的。 is_last_search = true 不是清理步骤，唯一作用是让索引把上下文里 仍缓存的候选作为该次调用的结果输出（仍受 k 截断）。仅当你需要这些尾部候选时再发起这次调用， 并把 k 设得足够大以避免截断。
• 参数一致性。 同一个上下文复用期间，不要更换查询向量、距离度量或过滤器——只有保持逻辑上的 同一次查询，迭代结果才有意义。
• 每次调用的 k。 k 只作用于单次调用；多次结果互不重叠，每次最多增加 k 条（不足则表示 索引候选已耗尽）。
• 线程安全。 单个 IteratorContext 不能在多线程间并发使用；不同查询应各自持有独立上下文。