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（稀疏）等；
• 灵活的过滤与混合搜索：支持 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 程序中使用。VSAG 核心库使用 C++ 编写，由于依赖的部分第三方库是 Linux 特有的，当前 VSAG 仅支持在 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 从源代码构建，支持 x86_64 和 aarch64 架构的 Linux 环境，包括在 Apple Silicon 上运行的 Linux 容器。

构建依赖：

• 操作系统：
  • Ubuntu 20.04 或更高版本
  • 或 CentOS 7 或更高版本
• 编译器：
  • GCC 9.4.0 或更高版本
  • 或 Clang 13.0.0 或更高版本
• 构建工具：
  • CMake 3.18.0 或更高版本
  • clang-format 15（精确版本，用于代码格式化）
  • clang-tidy 15（精确版本，用于静态检查）
• 其他依赖项：
  • gfortran
  • openmp
  • libaio
  • Python 3.6+
  • curl

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

# Debian / Ubuntu
./scripts/deps/install_deps_ubuntu.sh

# CentOS / AliOS
./scripts/deps/install_deps_centos.sh

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_ 为功能特性）。

通用的构建参数

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

• 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 个结果，这些结果按照最近邻和查询向量的距离升序排序。输出的结果类似于：

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

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 开始。

与 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、pyramid）。LazyHGraph 转换到 graph 阶段后也使用 hgraph 搜索参数。具体参数定义在各索引页面内给出，也可查阅 索引参数 进行总览。

索引参数

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

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

通用参数

所有索引在构建时都需要提供以下顶层字段：

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}}

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 支持按 tag 组织多棵子图：

{
    "pyramid": {
        "tag_dim": 1,
        "max_degree": 24,
        "ef_construction": 300
    }
}

SINDI（稀疏向量）

{
    "sindi": {
        "top_k": 32,
        "doc_prune_ratio": 0.1
    }
}

运行期参数

除构建参数外，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 下。下表列出最常用的配置项；完整列表请见 索引参数。

向量存储去重

同时设置 support_duplicate: true 和 deduplicate_storage: true 后，重复向量会共享 同一个物理编码槽位，但仍保留各自的标签。该选项目前仅支持使用 graph_type: "nsw" 的 稠密向量 HGraph 索引；独立的 HNSW 索引以及 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 弥补召回。

如果你的业务偏向粗粒度分桶（每次查询只扫部分桶）或严重受 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();

构建参数

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

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 压缩词项权重以进一步节省内存。
3. 打分。 检索时，SINDI 遍历查询向量的非零项，按窗口访问对应的倒排表，使用大小为 n_candidate 的大顶堆聚合得分，最后取 top-k。启用 use_reorder 时，候选会在正排 存储上重打分。默认正排存储保留 fp32 值；设置 rerank_type: "dmq8" 时使用压缩的 DMQ 正排以降低重排内存。

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

快速开始

#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 要按词表大小估计，这是使用时最常见的坑。

检索参数

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

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, "query_prune_ratio": 0.1}})").value();

何时选择 SINDI

• 使用 BM25、SPLADE、uniCOIL 等学习稀疏编码器的稀疏检索场景。
• 稠密 + 稀疏的混合检索管线：SINDI 负责稀疏一路，HGraph / IVF 负责稠密 embedding。
• 稀疏语料的内存受限部署：use_quantization: true 大致能把倒排内存减半，略损召回； use_reorder: true 以正排内存换召回，rerank_type: "dmq8" 可降低这部分正排开销。

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 上限的风险。

标记删除

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

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

相关文档

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

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、memory_io、 block_memory_io、buffer_io、mmap_io、reader_io
• base_file_path — 默认值为占位符，使用磁盘类型（async_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();

何时选择 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();

构建参数

构建参数放在 index_param 下。

检索参数

检索参数放在 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。

{
    "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);

检索指定层级

通过检索参数中的 "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();

序列化与反序列化

多层级索引的序列化和反序列化完全透明。序列化格式包含所有层级名称及其图结构：

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

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

相关文档

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

BruteForce

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

• 源码：src/algorithm/brute_force.{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。

构建参数

最简配置只需要三个顶层字段（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 声明的能力标志如下（参见 BruteForce::InitFeatures， src/algorithm/brute_force.cpp）：

BruteForce 不支持 的能力包括：SUPPORT_UPDATE_VECTOR_CONCURRENT、 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 上，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。 HGraph 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 上 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、底库/查询位数和 FHT 相关 key。其中 rabitq_use_fht 是索引层对量化器内部 use_fht key 的别名，会由索引层重写。

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

{
    "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 会自动选择 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 x+y split 保留 x bit 快速 过滤路径，再添加 y 个 supplement bits 用于重排；相对纯 1 比特，使用 更多总 bit 时召回明显更高。

相关页面

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

RaBitQ x+y Split

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

• 图遍历和 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 自动选择 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 使用 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 估计。

因此，HGraph 不会为每个访问到的向量都计算 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 会把之前计算的 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 功能，并且要求 fp32 query code。
• 支持 l2、ip 和 cosine；利用 filter hint 的 reorder 快速路径当前针对 L2。
• 除非已经验证仅靠 x-bit 遍历距离能满足召回要求，否则应保持 use_reorder: true。
• 修改 x、y、metric 或 transform 参数后必须重建索引；在搜索参数中覆盖 hgraph.rabitq_error_rate 不需要重建。
• RaBitQ 通用说明见 RaBitQ，完整 HGraph 参数见 HGraph 索引。

量化变换（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 真正暴露了它。HGraph 通过外部参数映射把 顶层键 tq_chain 和 rabitq_pca_dim 写到嵌套的 base_codes.quantization_params （src/algorithm/hgraph.cpp:370-385）。IVF、BruteForce、Pyramid、WARP 虽然在内部 JSON 模板中 也会渲染 tq_chain 字段，但它们的外部参数映射里都没有 tq_chain（或其它 TQ 参数）。 CheckAndMappingExternalParam 遇到未映射的外部键会直接抛 invalid config param （src/utils/util_functions.cpp:50-53），因此在这些索引的 index_param JSON 中传 tq_chain 会在构建时报错。在非 HGraph 索引上启用 TQ 目前需要在代码侧补一条外部映射。

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” 失败。
• 未识别的变换名会抛 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 时，两个顶层快捷键会被映射到嵌套的量化器参数中 （src/algorithm/hgraph.cpp:370-385）：

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

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

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 都位于此目录；
• mockimpl/：接口的 Mock 实现，可以用于简单的接口测试；
• 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/：工具函数目录。

新索引接入检查清单

新增 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、feedback 和 cache 导入/导出。

  • 当索引可以在不错误共享可变存储的情况下复制时，实现 Clone() 和 ExportModel()。
  • 只有在参数兼容性、ID 重映射和删除语义清晰时，才实现 Merge()。
  • 只有带有明确参数解析和测试时，才实现 Tune()、Feedback()、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 以后的版本，因为这些版本在我们的开发中工作良好。

在 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 绑定与 mockimpl；如需同时启用它们，可使用 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 服务、OSS 存储桶、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   # 1. 上游
    https://vsagcache.oss-rg-china-mainland.aliyuncs.com/antlr4/v4.13.2.tar.gz  # 2. 项目镜像
)
if (DEFINED ENV{VSAG_THIRDPARTY_ANTLR4})
    message (STATUS "Using local path for antlr4: $ENV{VSAG_THIRDPARTY_ANTLR4}")
    list (PREPEND antlr4_urls "$ENV{VSAG_THIRDPARTY_ANTLR4}")   # 0. 你的覆盖项（最先尝试）
endif ()

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

因此解析顺序为：

1. VSAG_THIRDPARTY_<LIB> —— 你设置的覆盖项（如果该环境变量已设置为非空值）。最先尝试。
2. 上游 URL（GitHub / 项目发布页）。
3. 项目维护的 阿里云 OSS 镜像 （vsagcache.oss-rg-china-mainland.aliyuncs.com）。该兜底地址始终存在，在中国大陆 / 弱网环境下很有帮助，但不可由用户配置——若要使用纯内网镜像，请使用环境变量。

可用版本： VSAG_THIRDPARTY_* 覆盖能力在 main 分支以及 0.15、0.16、 0.17、0.18 发布线上均可用——详见版本可用性。

开始前的关键事项

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

环境变量

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

此处未列出的（不下载，因此无需覆盖）：Intel MKL（通过 find_path 在主机上查找）与 DiskANN（以源码内置于 extern/diskann/）。

我需要哪些依赖？

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

• 核心库（make debug / make release）：JSON、ANTLR4、BOOST、 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 服务或 OSS 存储桶（推荐）

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

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

export VSAG_THIRDPARTY_JSON=$VSAG_MIRROR/v3.11.3.tar.gz
export VSAG_THIRDPARTY_ANTLR4=$VSAG_MIRROR/antlr4-4.13.2.tar.gz
export VSAG_THIRDPARTY_BOOST=$VSAG_MIRROR/boost_1_67_0.tar.gz
export VSAG_THIRDPARTY_OPENBLAS=$VSAG_MIRROR/OpenBLAS-0.3.23.tar.gz
export VSAG_THIRDPARTY_CPUINFO=$VSAG_MIRROR/cpuinfo-ca678952.tar.gz
export VSAG_THIRDPARTY_FMT=$VSAG_MIRROR/fmt-10.2.1.tar.gz
export VSAG_THIRDPARTY_THREAD_POOL=$VSAG_MIRROR/thread_pool-3507796e.tar.gz
export VSAG_THIRDPARTY_TSL=$VSAG_MIRROR/robin-map-1.4.0.tar.gz
export VSAG_THIRDPARTY_ROARINGBITMAP=$VSAG_MIRROR/CRoaring-3.0.1.tar.gz

make release

OSS / S3 存储桶用法完全相同——直接使用其公网（或网络可达）的对象 URL，例如 https://my-bucket.oss-cn-hangzhou.aliyuncs.com/vsag/OpenBLAS-0.3.23.tar.gz。

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

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

export VSAG_THIRDPARTY_JSON=/data/vsag-deps/v3.11.3.tar.gz
export VSAG_THIRDPARTY_ANTLR4=/data/vsag-deps/antlr4-4.13.2.tar.gz
export VSAG_THIRDPARTY_BOOST=/data/vsag-deps/boost_1_67_0.tar.gz
export VSAG_THIRDPARTY_OPENBLAS=/data/vsag-deps/OpenBLAS-0.3.23.tar.gz
export VSAG_THIRDPARTY_CPUINFO=/data/vsag-deps/cpuinfo-ca678952.tar.gz
export VSAG_THIRDPARTY_FMT=/data/vsag-deps/fmt-10.2.1.tar.gz
export VSAG_THIRDPARTY_THREAD_POOL=/data/vsag-deps/thread_pool-3507796e.tar.gz
export VSAG_THIRDPARTY_TSL=/data/vsag-deps/robin-map-1.4.0.tar.gz
export VSAG_THIRDPARTY_ROARINGBITMAP=/data/vsag-deps/CRoaring-3.0.1.tar.gz

make release

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

C. 只覆盖单个依赖

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

export VSAG_THIRDPARTY_OPENBLAS=https://mirror.corp.example.com/OpenBLAS-0.3.23.tar.gz
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 配置阶段读取的。确认配置输出中出现 -- Using local path for <lib>: <你的取值> 这一行。
• 仍然在访问网络 —— 多半是漏掉了本次构建会拉取的某个依赖。请对照 我需要哪些依赖？ 与你启用的选项（ENABLE_TESTS、ENABLE_TOOLS、 Python 绑定）逐项核对。

版本可用性

按依赖配置的 VSAG_THIRDPARTY_* 覆盖能力在 main 开发线以及 0.15、0.16、0.17、 0.18 发布线上均可用，因此本地路径与内网镜像覆盖在所有这些分支上的行为完全一致。该能力最初由 #1606 在 main 引入，并已合入各发布线（跟踪于 #2308）。内置的“上游 + 阿里云 OSS 镜像”兜底在 每条线上依然保留；若你不想镜像某个依赖，也仍可使用复用系统库。

运行测试

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

• 单元测试：与源码同目录，位于 src/ 下，聚焦单个类/函数的行为。
• 功能测试：位于 tests/ 目录，覆盖跨模块、端到端的索引行为。典型用例包括 test_hnsw.cpp、 test_hgraph.cpp、test_diskann.cpp、test_ivf.cpp、test_pyramid.cpp、test_sindi.cpp、 test_brute_force.cpp、test_multi_thread.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 "[hnsw][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_multi_thread.cpp：验证并发 Build / KnnSearch / RangeSearch 下的正确性。

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。

编码风格

VSAG 项目编码风格基于 Google C++ 风格指南 做了一些修改，包括缩进、命名规则、行宽等，具体可以参考以下两个配置文件：

• clang-format：https://github.com/antgroup/vsag/blob/main/.clang-format
• clang-tidy：https://github.com/antgroup/vsag/blob/main/.clang-tidy

clang-tidy 是一个静态代码分析的工具，配置文件中不仅定义了函数/变量的命名标准，定义了一些编码风格的检查，例如 Magic Number 使用的检查等。

VSAG 项目通过 Makefile 提供了格式化代码的命令，需要安装 clang-format 和 clang-tidy。

运行命令可以直接格式化代码：

make fmt

运行命令会静态代码检查，需要根据提示手动修复：

make lint

本地测试

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 索引参数
• 索引参数参考

范围搜索

除了 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，返回单个距离值。
• CalDistanceById — 一批 ID，返回一个包含距离数组的 DatasetPtr。

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

关于命名的说明。 批量接口目前拼作 CalDistanceById（Calc 少了一个 c）。 这是批量重载最初加入时遗留的拼写笔误，两个名字并不表示语义差异，区别仅在于 单个 vs. 批量。出于向后兼容当前仍保留这一拼写，预计未来某个版本会将其 标记为弃用（deprecated），并改用拼写正确的新名（建议为 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>
CalDistanceById(const float* query,
                const int64_t* ids,
                int64_t count,
                bool calculate_precise_distance = true) const;

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

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

calculate_precise_distance

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

返回值含义

• 单 ID 重载返回 float 距离值。
• 批量重载返回 DatasetPtr，其 GetDistances() 数组长度为 count，与输入 ids 一一 对应。值为 -1 表示对应的 ID 无效（如该 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->CalDistanceById(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;
        }
    }
}

可运行的完整示例见 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 不能在多线程间并发使用；不同查询应各自持有独立上下文。

属性过滤（混合搜索）

属性过滤（Attribute Filter），又称混合搜索（Hybrid Search）或带结构化谓词的近邻搜索， 让 KnnSearch / RangeSearch 只返回结构化标签满足某个 SQL 风格表达式的向量。相比 带过滤的搜索 中基于 id 的过滤方式，它能直接表达类似下面的谓词：

category = "electronics" AND price <= 1000 AND multi_in(tag, "promo|new", "|")

而无需写回调代码。VSAG 在向量索引旁额外构建一份属性倒排索引；表达式只解析一次，并在图遍历 过程中完成判定，从而尽早剪除不可能满足条件的候选。

本文中的“混合搜索”指的是向量 + 结构化属性的混合检索，而非存储布局上的混合。

何时选择哪种过滤 API

三者可以同时放进同一个 SearchRequest，按 AND 组合。

索引支持情况

启用 use_attribute_filter 后，BruteForce 暂不支持 Remove（如需删除请重建索引）。

属性数据模型

属性按向量定义，组织成 AttributeSet（include/vsag/attribute.h）。每个属性包含：

• 名称（字符串）；
• 值类型（AttrValueType 枚举）；
• 值列表——所有字段都是多值字段，因此 IN 风格的成员判定能自然适用于标签类字段。

支持的值类型：

enum AttrValueType {
    INT8 = 5,  INT16 = 7,  INT32 = 1,  INT64  = 3,
    UINT8 = 6, UINT16 = 8, UINT32 = 2, UINT64 = 4,
    STRING = 9,
};

字段的 (名称, 类型) 在首次构建/插入时被锁定；后续插入必须保持一致。

构造一个 AttributeSet

auto* category = new vsag::AttributeValue<std::string>();
category->name_ = "category";
category->GetValue() = { "electronics" };

auto* tags = new vsag::AttributeValue<std::string>();
tags->name_ = "tag";
tags->GetValue() = { "promo", "new" };       // 多值字段

auto* price = new vsag::AttributeValue<int32_t>();
price->name_ = "price";
price->GetValue() = { 899 };

vsag::AttributeSet set;
set.attrs_ = { category, tags, price };

Attribute* 的生命周期取决于承载该 AttributeSet 的 Dataset 的 Owner(...) 标志：

• Owner(true)（默认）：DatasetImpl 析构时会 delete 每个 Attribute* 并 delete[] AttributeSet 数组，调用方不要再自行释放。
• Owner(false)（下文示例所用）：调用方保留所有权，需在 Build / Add 返回后自行释放 Attribute*（以及若为堆分配的 AttributeSet 数组）。

同一个 dataset 请只选一种策略，避免双重释放或泄漏。

构建支持属性过滤的索引

把 index_param.use_attribute_filter 设为 true，可选地在 attr_params 下调整属性 倒排索引参数。

std::string build_params = R"(
{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "index_param": {
        "use_attribute_filter": true,
        "attr_params": {
            "has_buckets": false
        }
    }
}
)";
auto index = vsag::Factory::CreateIndex("hgraph", build_params).value();

has_buckets 控制倒排索引中倒排链的存储布局，不同索引的默认值不同：

如果没有性能数据明确指向需要修改，建议保留默认值。

在 Build / Add 时附加属性

Dataset::AttributeSets 接收一个长度等于向量数的 AttributeSet 数组 （include/vsag/dataset.h）：

std::vector<vsag::AttributeSet> sets(num_vectors);
for (int64_t i = 0; i < num_vectors; ++i) {
    sets[i] = build_attrs_for_row(i);
}

auto base = vsag::Dataset::Make();
base->NumElements(num_vectors)
    ->Dim(dim)
    ->Ids(ids)
    ->Float32Vectors(vectors)
    ->AttributeSets(sets.data())
    ->Owner(false);

index->Build(base);     // 或 index->Add(base)

通过 SearchRequest 查询

属性过滤目前仅通过 SearchWithRequest 暴露 （include/vsag/search_request.h）：

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_attribute_filter_  = true;
req.attribute_filter_str_     =
    "category = \"electronics\" AND price <= 1000 "
    "AND multi_in(tag, \"promo|new\", \"|\")";

auto result = index->SearchWithRequest(req).value();
for (int64_t i = 0; i < result->GetDim(); ++i) {
    std::cout << result->GetIds()[i] << " " << result->GetDistances()[i] << "\n";
}

可同时启用 enable_filter_（提供 FilterPtr）和 enable_bitset_filter_（提供 BitsetPtr）， 所有启用的过滤项按逻辑 AND组合。

过滤表达式语法

文法定义见 src/attr/grammar/FC.g4。语法虽然紧凑，但已经能覆盖结构化过滤的常见需求。

逻辑运算符

NOT 仅支持前缀写法 !(...)。

比较运算符

数值字段：=、!=、>、<、>=、<=。 字符串字段：仅 = 和 !=。

数值比较的左侧可以包含算术运算（+ - * /）：

(price - discount) <= 100

列表成员判定

提供两种写法。它们使用同一组关键字（IN 与 NOT_IN，含下方别名），但参数形态不同。

方括号中缀形式——配合字面量列表使用：

id IN [1, 2, 3, 4]
category NOT_IN ["electronics", "clothing"]

列表元素必须是 INTEGER 字面量或双引号字符串；文法不接受单引号。

函数式竖线形式——上游已经把候选值拼接成字符串时使用。第二个参数必须是单个用 | 分隔的字符串字面量，第三个（可选）参数是分隔符，必须为 "|"：

multi_in(category, "electronics|clothing", "|")
multi_notin(uid, "1961|8669|9090", "|")

函数形式不接受方括号列表（multi_in(field, [...]) 是文法错误）；中缀形式也不接受 竖线分隔字符串。

两种形式的别名：IN / in / MULTI_IN / multi_in， NOT_IN / not_in / NOTIN / notin / MULTI_NOTIN / multi_notin。

对多值字段而言，只要其中任一个值出现在列表中，成员谓词即为真。

字面量

标识符匹配 [a-zA-Z_][a-zA-Z0-9_]*，可以含 .（即 namespace.field 视为同一个标识符）。

注释以 # 开头，到行尾。

示例

# 等值
category = "electronics"

# 数值范围 + 多值字段
price >= 100 AND price <= 1000 AND tag IN ["promo", "new"]

# 取反
!(status = "archived") AND multi_notin(region, "us-east|us-west", "|")

# 比较左侧的算术运算
(end_ts - start_ts) > 3600 AND charge_type = 5

更新属性

调用 index->UpdateAttribute(id, new_attrs)（或同时传入旧属性的重载，可让倒排索引更新更高效）：

vsag::AttributeSet new_attrs = build_new_attrs();
auto status = index->UpdateAttribute(/*id=*/123, new_attrs);

向量本身不会改变，只更新倒排索引，后续搜索立即可见新属性值。

性能要点

• 属性倒排索引的内存占用大致与「字段平均值数量 × 向量数」成正比；字符串字段还要额外占用 与「不同值数量」成正比的字典空间。
• 谓词越严格，候选越早被剪除，搜索越快；不严格的谓词大致等于无过滤搜索的成本加一个常数开销。
• 对图索引，谓词非常严格时应同步增大 ef_search，否则可能因存活候选不足而无法收敛。
• 优先使用 multi_in / IN，避免冗长的 OR 链——倒排索引可以一次扫描完成成员判定。

测试用例参考

最完整的使用示例在测试套件中：

• tests/test_index.cpp 中的 TestIndex::TestWithAttr：构建属性、用 SearchRequest 查询， 以及 UpdateAttribute 后再次查询。
• tests/fixtures/data/vector_generator.cpp 中的 generate_attributes：演示如何按程序化方式 构造混合类型的 AttributeSet* 数组。
• src/attr/expression_visitor_test.cpp：穷举式的语法用例，可作为 DSL 的参考实现。

Python 状态

属性 / 混合搜索 API 目前仅 C++ 可用，pyvsag 暂未提供绑定， examples/python/todo_examples/301_feature_filter.py 是一个空占位文件。

序列化格式

VSAG 索引可通过现有序列化接口进行序列化与反序列化，便于持久化、跨进程共享及分布式部署。

本文介绍 Serialize 和 Deserialize 使用的现有序列化格式。后续引入的 header-first 流式格式见 新序列化格式。两种格式互不兼容。

三种接口

1. BinarySet / ReaderSet

最灵活的方式，把索引拆分为多个命名二进制段。适合用户自己管理存储介质（例如对象存储、KV、分片上传）。

// 保存
vsag::BinarySet bs = index->Serialize().value();
for (const auto& key : bs.GetKeys()) {
    auto binary = bs.Get(key);
    // 写入存储介质
}

// 加载
vsag::BinarySet bs_loaded;
// 从介质中读取每个 key 对应的 Binary 放入 bs_loaded
auto empty = vsag::Factory::CreateIndex("hgraph", build_params).value();
empty->Deserialize(bs_loaded);

ReaderSet 与 BinarySet 类似，但通过用户自定义的 Reader 按需读取，避免一次性加载全部数据， 常用于内存受限或部分反序列化场景。

2. 文件流（std::ostream / std::istream）

最简单的方式，将索引整体写入文件或内存流：

std::ofstream out("index.bin", std::ios::binary);
index->Serialize(out);

std::ifstream in("index.bin", std::ios::binary);
empty->Deserialize(in);

3. 自定义写函数（WriteFuncType）

对于流式/分块写入的后端，可传入写回调：

index->Serialize([&](const void* buf, uint64_t offset, uint64_t size) {
    // 将 [buf, buf+size) 写入 offset 位置
});

注意事项

• Deserialize 要求目标索引为空索引，并且参数配置与序列化时一致（如 dim、metric_type）。
• Serialize/Deserialize 保留现有 footer-based 格式。新的 SerializeStreaming 格式是 header-first 格式，需要用 DeserializeStreaming 或 Load 读取。
• 跨大版本升级时请关注 版本日志 中的兼容性说明。
• 示例参考：examples/cpp/318_feature_tune.cpp、examples/cpp/401_persistent_kv.cpp、 examples/cpp/402_persistent_streaming.cpp。

新序列化格式

新的序列化格式面向大索引产物和 forward-only 读取场景。它的设计目标是：

• 让文件从头部开始就是自描述的，读取端无需先 seek 到文件尾部，就能识别 magic、版本、metadata 和 block manifest。
• 将索引内容拆分成带类型的 TLV block，便于工具检查各部分大小，也便于未来 reader 跳过未知的 non-critical block。
• 为完整恢复（DeserializeStreaming）和带策略加载（Load）提供统一的流式入口。
• 提供稳定、可检查的布局，便于调试和运维工具进行可视化。

新的序列化格式与之前的 Serialize/Deserialize 格式不兼容。SerializeStreaming 写出的文件 必须用 DeserializeStreaming 或 Load 读取；Serialize 写出的文件必须用 Deserialize 读取。

使用模型

序列化和反序列化是索引产物的存储、传输路径。SerializeStreaming 将已经构建好的索引写成自描述文件， DeserializeStreaming 在调用方已经知道要创建哪种索引对象时，恢复完整的内存索引。Index::Load 才是 提供搜索服务的加载路径：它从文件 metadata 中创建索引对象，并返回可以直接用于搜索的 IndexPtr。

流式序列化

SerializeStreaming、DeserializeStreaming 和 Load 读写 forward-only 的索引文件。该格式面向 较大的索引产物：读取端不需要先 seek 到文件尾部解析 footer，就能从文件头拿到格式版本和 block 清单。 当前 BruteForce、HGraph、IVF、SINDI 和 Pyramid 已实现该路径。

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

{
    std::ofstream out("hgraph.streaming", std::ios::binary);
    index->SerializeStreaming(out).value();
}

auto restored = vsag::Factory::CreateIndex("hgraph", build_params).value();
{
    std::ifstream in("hgraph.streaming", std::ios::binary);
    restored->DeserializeStreaming(in).value();
}

vsag::IndexPtr loaded;
{
    std::ifstream in("hgraph.streaming", std::ios::binary);
    loaded = vsag::Index::Load(in, "{}").value();
}

Static Load

Index::Load 是新 streaming 格式的带策略加载入口。它和 DeserializeStreaming 的区别是：调用方不需要 先创建一个空索引对象。Load 会先读取 streaming metadata，识别序列化文件中的索引类型和 basic_info["index_param"]，在内部创建匹配的索引对象，然后按照 load parameters 加载后续 TLV body blocks。

std::ifstream in("hgraph.streaming", std::ios::binary);
vsag::LoadParameters load_parameters(R"({"base_io_type":"block_memory_io"})");
auto loaded = vsag::Index::Load(in, load_parameters).value();

返回值是可直接使用的 IndexPtr，因此它是把索引加载起来并提供搜索服务时优先使用的路径。load parameters 用来控制已支持 block 的加载策略；参数对象既可以从 JSON 字符串构造，也可以通过 SetReader 携带 reader 对象。不支持的策略会返回错误，不会静默 fallback。当前该 API 支持 streaming BruteForce、HGraph、IVF、SINDI 和 Pyramid 索引。其中 BruteForce 支持有限的 block placement 策略； HGraph 支持通过 precise_reader 将 high_precision_codes 绑定到外部 reader；IVF、SINDI 和 Pyramid 目前会把写出的 streaming blocks 加载到内存。

文件布局

流式文件由固定头部和一组 TLV block 构成：

magic("vsagstm0")
format_version
metadata_length
metadata_json
metadata_checksum
block_header + block_payload
block_header + block_payload
...
section_end

metadata JSON 中保存索引名称、基础索引信息和 block manifest；构建参数保存在 basic_info["index_param"] 中。manifest 描述预期的 block tag、block version，以及该 block 是否 critical。未知 critical block 会导致反序列化失败；未知 non-critical block 可以被兼容 reader 跳过。

TLV Block 版本兼容

format_version 描述 streaming 文件整体结构，例如固定头、metadata 布局和 TLV framing。当某个 block payload 的二进制语义发生不兼容变化时，不应直接升级整体格式，而应升级对应 TLV block 的 block_version。例如 HGraph 的 base_codes payload 如果因为 basic_flatten_codes 实现变化而无法被旧 reader 正确解析，就需要升级 base_codes block version。

每个可独立演进的 block 都需要区分两类版本信息：

• 当前写出版本：当前代码序列化该 block 时写入的 block_version。
• 支持读取版本：当前代码能读取的该 block 版本集合或版本范围。

reader 读取 TLV header 后，先检查 tag + block_version 是否被当前代码支持：

• 支持的版本按对应 block reader 继续解析 payload。
• 不支持的 critical block 直接返回错误，避免旧代码误读新格式。
• 不支持的 non-critical block 使用 value_len 跳过 payload，并继续读取后续 block。

因此，后续如果某个 block 从 v1 升级到 v2，不能只把当前写出版本改成 v2，还需要同步维护该 block 的支持读取版本。如果新代码仍保留 v1 reader，则 supported versions 应包含 v1 和 v2，这样 v2 代码仍可读取 v1 索引；如果不再支持 v1，则应显式从 supported versions 中移除，并让读取旧 critical block 失败。

metadata 中的 block manifest 用来让工具和 reader 在读取 body 前知道预期 block 版本；真正解析 body 时， TLV header 中的 block_version 仍是每个 payload 的权威版本。

BruteForce Blocks

BruteForce 按顺序写入以下 streaming blocks：

DeserializeStreaming 会恢复完整的内存 BruteForce 索引。Load 当前要求 base_codes 加载到内存中； 必需的 BruteForce codes 不支持 reader-based 加载。

HGraph Blocks

HGraph 按顺序写入以下 streaming blocks：

DeserializeStreaming 会恢复完整的内存索引。Load 默认把 HGraph blocks 加载到内存中；如果 load parameters 中设置 precise_io_type，可以覆盖 precise_codes 的 IO 类型。如果同时提供 precise_reader，并且该 reader 大小与 high_precision_codes payload 大小一致，Load 会校验该外部 reader 的 payload checksum，然后将 reorder codes 绑定到该 reader。

IVF Blocks

IVF 按顺序写入以下 streaming blocks：

DeserializeStreaming 会恢复完整的内存 IVF 索引。Index::Load 可以直接从 streaming metadata 创建 IVF 索引对象，当前会把写出的 IVF blocks 都加载到内存中。

SINDI Blocks

SINDI 按顺序写入以下 streaming blocks：

DeserializeStreaming 会恢复完整的内存 SINDI 索引。Index::Load 可以直接从 streaming metadata 创建 SINDI 索引对象，当前会把写出的 SINDI blocks 都加载到内存中。immutable SINDI runtime 暂不支持 该 streaming 序列化路径。

Pyramid Blocks

Pyramid 按顺序写入以下 streaming blocks：

DeserializeStreaming 会恢复完整的内存 Pyramid 索引。Index::Load 可以直接从 streaming metadata 创建 Pyramid 索引对象，当前会把写出的 Pyramid blocks 都加载到内存中。

可视化流式索引

构建工具后，传入 streaming index 文件：

cmake --build build --target visualize_index
build/tools/visualize_index/visualize_index \
  --index_path /tmp/vsag-hgraph-streaming.index \
  --html /tmp/vsag-hgraph-streaming.html

CLI 输出包含按真实字节比例展示的 raw horizontal layout，以及高密度的 logical-block layout。HTML 输出会把相关的小 segment 聚合展示，例如 TLV header 与 payload，并在表格中保留精确 segment 明细。

streaming serialization 和 Index::Load 的可运行示例见 examples/cpp/403_persistent_streaming_load.cpp。

内存管理

VSAG 在关键路径上大量使用自定义 Allocator 与 Resource，允许用户：

• 接入业务侧已有的内存池；
• 对索引内存占用进行度量与上限控制；
• 在多进程 / NUMA 环境下精细分配内存来源。

自定义 Allocator

class MyAllocator : public vsag::Allocator {
public:
    std::string Name() override { return "my_allocator"; }
    void* Allocate(size_t size) override;
    void Deallocate(void* p) override;
    void* Reallocate(void* p, size_t size) override;
    // ...
};

auto allocator = std::make_shared<MyAllocator>();
auto resource = std::make_shared<vsag::Resource>(allocator, /*thread_pool=*/nullptr);
auto engine = vsag::Engine(resource);

auto index = engine.CreateIndex("hgraph", build_params).value();

完整示例参见 examples/cpp/201_custom_allocator.cpp。

搜索路径上的临时 Allocator

KnnSearch / RangeSearch 支持为单次搜索注入临时 Allocator，用于在线程局部的 arena 中分配工作区， 避免与全局堆竞争：

vsag::SearchParam search_param;
search_param.allocator = thread_local_allocator.get();
auto result = index->KnnSearch(query, k, search_param);

示例：examples/cpp/313_feature_search_allocator.cpp、examples/cpp/314_feature_hgraph_search_allocator.cpp。

估算与查询内存占用

EstimateMemory(data_num)

Index::EstimateMemory(data_num) 返回索引在插入 data_num 条向量后预期占用的字节数。它仅基于 构建参数（dim、量化方式、max_degree 等）推算，不会分配任何向量存储，因此可以在空索引上安全 调用，是入库前评估节点规格的推荐方式：

if (index->CheckFeature(vsag::SUPPORT_ESTIMATE_MEMORY)) {
    uint64_t estimated = index->EstimateMemory(1'000'000);  // 字节
}

完整示例：examples/cpp/308_feature_estimate_memory.cpp。

EstimateBuildMemory(num_elements)

Index::EstimateBuildMemory(num_elements) 返回构建 num_elements 条向量的索引时构建过程中 所需的预估内存（字节数）。与 EstimateMemory（估算最终索引的稳态大小）不同，该接口考虑了构建 过程中仅临时存在的缓冲区与中间数据结构。构建期间的峰值内存通常高于构建完成后的内存占用：

uint64_t peak = index->EstimateBuildMemory(1000000);  // 字节

目前仅 DiskANN 提供了有效实现，其他索引类型默认抛出异常。

GetMemoryUsage()

Index::GetMemoryUsage() 返回索引当前占用的字节数：

uint64_t bytes = index->GetMemoryUsage();

特性：

• 所有索引类型均实现了该方法，但只有通过 CheckFeature 公布 vsag::SUPPORT_GET_MEMORY_USAGE 的索引才保证返回有意义的数值。HGraph、IVF、BruteForce、Pyramid、WARP 均声明了该能力 （见 src/algorithm/{hgraph,ivf,brute_force,pyramid,warp}.cpp）；SINDI 出于 接口纯虚函数的要求实现了该方法，但当前未设置该 feature flag，请仅把返回值视为参考信息。
• 线程安全；可与搜索并发轮询。
• 延迟在微秒量级 —— 适合生产环境的实时内存监控。
• 统计的是索引自身占用的内存（向量、图、量化器状态）。该值通常小于操作系统层面观察到的 RSS： RSS 还包含 allocator 的开销、临时 scratch buffer、以及索引外部持有的数据（例如用户自有的输入 向量缓冲）。SINDI 索引尤其建议在构建完成之后调用 GetMemoryUsage() 才能拿到具有代表性的 数值。

可运行示例：examples/cpp/319_feature_get_memory_usage.cpp，其中包含一个辅助函数将接口值与进程 驻留内存进行对照。

GetMemoryUsageDetail()

Index::GetMemoryUsageDetail() 返回索引当前内存占用按组件的细分：

std::unordered_map<std::string, uint64_t> detail = index->GetMemoryUsageDetail();
for (const auto& [component, bytes] : detail) {
    std::cout << component << ": " << bytes << " bytes\n";
}

返回的 map 的 key 为组件名，value 为对应内存字节数。该接口有助于了解索引内部的内存分布。

目前仅 HGraph 提供了有效实现，返回的组件包括 basic_flatten_codes、bottom_graph、 route_graph、neighbors_mutex、pool、label_table、high_precise_codes、 extra_infos 和 raw_vector。SINDI 返回空 map，其他索引类型默认抛出异常。

能力标志

两个标志均可通过 index->CheckFeature(...) 查询 —— 参见 索引自省。

线程池

Resource 也接受用户提供的 ThreadPool，与 Allocator 配合可完全托管并行度与资源归属。见 examples/cpp/203_custom_thread_pool.cpp。

注意事项

• 自定义 Allocator 必须是线程安全的。
• Allocator 生命周期必须覆盖所有引用它的索引与结果对象。
• 若未显式指定，VSAG 会创建一个默认的基于 malloc 的 allocator。

搜索路径 Allocator

VSAG 提供一个与索引自身 allocator 解耦的 per-call Allocator 注入点，适合：

• 把单次查询的内存与索引长期持有的堆隔离开；
• 在高并发在线场景下，每个线程绑一个 thread-local arena，彼此之间没有原子争用；
• 独立于索引地核算或限制每次查询的内存占用。

这个 Allocator 通过两个入口暴露：SearchRequest::search_allocator_（推荐）和旧版 SearchParam::allocator。但具体有多少搜索路径真正消费这个 allocator，取决于索引与入口的实现。 目前只有 HGraph::SearchWithRequest 把 search_allocator_ 端到端贯通了（既用于临时缓冲，也用 于结果 Dataset）；其它 SearchWithRequest 实现（IVF / BruteForce / WARP）只在部分临时 状态上使用 search_allocator_，结果 Dataset 仍由索引自身的 allocator 分配。详见下文 与索引 Allocator 的关系。

适用范围。 Allocator 注入目前只通过 KnnSearch（SearchParam 重载）和 SearchWithRequest 暴露。RangeSearch 没有携带 Allocator 的重载； SearchRequest::search_allocator_ 也不会被 range-search 路径读取。

推荐 API —— SearchRequest::search_allocator_

#include "vsag/search_request.h"

vsag::SearchRequest req;
req.query_ = query;
req.mode_ = vsag::SearchMode::KNN_SEARCH;
req.topk_ = 10;
req.params_str_ = R"({"hgraph":{"ef_search":100}})";
req.search_allocator_ = thread_local_allocator.get();  // 可选，可为 nullptr

auto result = index->SearchWithRequest(req).value();

SearchRequest（include/vsag/search_request.h）是当前未废弃、推荐用来驱动单次搜索的入口。 search_allocator_ 字段是可选的，留空时索引会回退到它所属 Resource 上的 allocator。

可用性。 Index::SearchWithRequest 默认实现会返回 不支持 错误。目前只有 HGraph、 IVF、BruteForce、WARP 实现了它（src/algorithm/{hgraph,ivf,brute_force,warp}.cpp）。对于 尚未 override 的索引（HNSW、DiskANN、SINDI、Pyramid），请使用下文的旧版 SearchParam 路径。

旧版 API —— SearchParam::allocator（已弃用）

#include "vsag/search_param.h"

nlohmann::json search_params = {{"hgraph", {{"ef_search", 100}}}};
std::string param_str = search_params.dump();

vsag::SearchParam search_param(/*iter_filter=*/false,
                               param_str,
                               /*filter=*/nullptr,
                               /*allocator=*/thread_local_allocator.get());
auto result = index->KnnSearch(query, /*k=*/10, search_param).value();

SearchParam 在 include/vsag/search_param.h 中以文档注释的形式标注为已弃用 （“Use SearchRequest instead”），仅为源码兼容保留。注意当前只是注释层面的弃用 —— struct 本身并没有 C++ [[deprecated]] 属性，编译器不会发出弃用告警；但新代码如果所用索引已支持 SearchRequest/SearchWithRequest，仍应优先使用该路径。 examples/cpp/314_feature_hgraph_search_allocator.cpp（HGraph）展示了旧版形式。

结果所有权

结果 Dataset 的所有权契约取决于具体实现 SearchWithRequest 的索引：

• HGraph 是目前唯一把 request.search_allocator_ 贯通到 create_fast_dataset 的索引 （见 src/algorithm/hgraph.cpp 中 ctx.alloc = request.search_allocator_）。其结果 Dataset 被标记为 Owner(true, allocator)，析构时会自动用该 allocator 释放 ids / distances。
• IVF / BruteForce / WARP 当前用 create_fast_dataset(..., allocator_) 构造结果，即索引 自身的 allocator（src/algorithm/ivf/ivf.cpp、src/algorithm/bruteforce/bruteforce.cpp； WARP 使用 BruteForce 的 WARP 模式实现）。这些路径上 request.search_allocator_ 只会被部分 临时缓冲读取，结果缓冲仍由索引 allocator 持有。在这些索引上请把结果 Dataset 的生命周期 视为绑定到索引 allocator。

实际意义：

• 不要手动 Deallocate 结果缓冲。 让 Dataset 离开作用域即可；同时手动 Deallocate(...) 与析构器释放会触发双重释放，属于未定义行为。
• 持有结果的那个 allocator 必须比结果 Dataset 活得更久。 HGraph 上是 per-search allocator；IVF / BruteForce / WARP 上是索引 allocator（索引活着它就活着）。
• examples/cpp/314_feature_hgraph_search_allocator.cpp 目前显式地 Deallocate。 这是早期 API 迭代遗留的写法；针对当前 owner-tracking 行为的新代码应改为依赖 Dataset 析构器。

最简单的安全模式是「一线程一 allocator，批与批之间 reset」：

ArenaAllocator arena;       // thread-local，足以容纳一批

for (const auto& q : batch) {
    vsag::SearchRequest req;
    req.query_ = q;
    req.topk_ = topk;
    req.params_str_ = params;
    req.search_allocator_ = &arena;
    auto result = index->SearchWithRequest(req).value();
    consume(result);
    // result Dataset 在这里析构；arena 通过自己的 Deallocate 释放 ids/distances。
}
arena.reset();              // 一次性回收本批所有 per-query 缓冲

与索引 Allocator 的关系

设置 per-search Allocator 不会影响索引的永久数据结构。它只是收窄了某一次搜索调用所触碰内存的 生命周期 —— 且仅限于索引/入口实际消费它的那部分（详见各行说明）。

约束

• allocator 只有在跨线程共享时才必须线程安全；thread-local arena 不需要内部同步。
• allocator 的生命周期必须超过它产生的每一个结果 Dataset。
• Reallocate(nullptr, size) 必须等价于 Allocate(size)。VSAG 的内部容器依赖该契约。

可运行示例

• examples/cpp/314_feature_hgraph_search_allocator.cpp —— HGraph（sq8）+ 自定义 allocator。

参见 内存管理 了解索引级 Allocator / Resource 的设置，以及 过滤搜索 了解如何在 SearchRequest 中同时使用 per-search Allocator 与 自定义过滤器。

索引自省

VSAG 提供三类自省 API，让调用方可以发现某个索引的能力、对已有向量计算距离，以及读出关于已构建 索引的结构化信息，而无需重新执行一次搜索：

• CheckFeature(IndexFeature) —— 运行时能力探测。
• CalDistanceById(...) —— 计算 query 到已存入向量 id 的距离。
• GetIndexDetailInfos() / GetDetailDataByName(...) —— 读取索引各项结构化详情数据。

这些 API 均为只读操作，可与搜索并发调用。

能力探测 —— CheckFeature

当底层索引实现公布了某项能力时，index->CheckFeature(vsag::SUPPORT_*) 返回 true。当代码路径 持有一个具体类型未知的 IndexPtr（例如用户配置注入、多态存储）时，应使用此 API：

if (index->CheckFeature(vsag::SUPPORT_ESTIMATE_MEMORY)) {
    uint64_t est = index->EstimateMemory(100'000);
}

if (not index->CheckFeature(vsag::SUPPORT_DELETE_BY_ID)) {
    // 跳过 / 通过另一个索引以 remove + re-add 方式回退。
}

能力标志几乎覆盖了库中所有可选接口：build / add / 序列化变体、各种并发组合、度量类型、属性 过滤、extra-info 过滤、Clone、ExportModel、Tune 等。完整枚举见 include/vsag/index_features.h。

可运行示例：examples/cpp/307_feature_check_features.cpp。

到已有 id 的距离 —— CalDistanceById

CalDistanceById 计算 query 与索引中已存在的一个或多个向量之间的距离，无需执行一次 搜索。它适用于 re-rank、A/B 评估、ground-truth 校验，或对已知候选集合做成对距离计算。

提供两个重载：

// 稠密向量索引（HGraph、BruteForce、IVF）
auto r = index->CalDistanceById(query_ptr, ids, count, /*calculate_precise_distance=*/true);

// 稀疏向量索引（SINDI）—— 用 Dataset 封装查询
auto query_ds = vsag::Dataset::Make();
query_ds->NumElements(1)->SparseVectors(/* ... */);
auto r = index->CalDistanceById(query_ds, ids, count, /*calculate_precise_distance=*/true);

结果 Dataset 中 GetDistances() 持有 count 个距离。若某个 id 无效（不在索引中），对应位置 返回 -1.0F。

calculate_precise_distance

末尾的 bool 参数在精度与延迟之间做取舍：

可运行示例：examples/cpp/306_feature_calculate_distance_by_id.cpp。

详情数据 —— GetIndexDetailInfos / GetDetailDataByName

GetIndexDetailInfos() 返回一组 IndexDetailInfo 记录，描述索引可对外暴露的每一项命名结构化 数据。每条记录包含 name、description 和一个 type 枚举，后者用于选择 DetailData 上的 合适访问器。

是否支持取决于索引类型 —— 这两个 API 没有专门的 SUPPORT_* flag。Index 基类默认抛 std::runtime_error("Index doesn't support ...")（GetIndexDetailInfos 与 GetDetailDataByName，见 include/vsag/index.h:658,674）；HGraph / IVF / BruteForce / Pyramid / SINDI / WARP 通过 InnerIndexInterface 提供了实现。调用时请始终处理 tl::expected 的 error 分支。

auto infos = index->GetIndexDetailInfos().value();
for (const auto& info : infos) {
    std::cout << info.name << " : " << info.description << '\n';
}

知道哪些项可用后，调用 GetDetailDataByName(name, info) 获取对应类型的数据：

vsag::IndexDetailInfo info;
auto detail = index->GetDetailDataByName(vsag::INDEX_DETAIL_NAME_NUM_ELEMENTS, info).value();
int64_t n = detail->GetDataScalarInt64();

detail = index->GetDetailDataByName(vsag::INDEX_DETAIL_NAME_LABEL_TABLE, info).value();
auto table = detail->GetData2DArrayInt64();   // [row][col] int64 矩阵

detail = index->GetDetailDataByName(vsag::INDEX_DETAIL_DATA_TYPE, info).value();
std::string dt = detail->GetDataScalarString();

数据类型

info.type 决定 DetailData 上哪一个访问器有效：

include/vsag/index_detail_info.h 中以常量形式给出的标准详情名：

具体索引可能额外暴露其他名称；运行期通过 GetIndexDetailInfos() 遍历即可发现。可运行示例： examples/cpp/317_feature_get_detail_data.cpp。

注意事项与限制

• CheckFeature 是常数时间复杂度。相比对不支持的调用做 try / catch，应优先使用它。
• CalDistanceById 要求底层索引保留足够信息以重新计算距离。对于纯量化索引（不保留原始向量）， 即使传入 calculate_precise_distance = true，也可能返回量化距离。
• GetIndexDetailInfos 与 GetDetailDataByName 是只读快照。返回的数值反映调用瞬间的索引状态， 并发修改可能使其失效。

可扩展性

VSAG 暴露了一组稳定的 C++ 扩展点，方便应用接入自有基础设施而无需 fork 库本身。 本页梳理 哪些可以扩展、哪些不可以，并给出可运行示例的链接。

公开扩展点

这五个都是抽象基类。每个至少声明一个必须实现的纯虚方法；部分还声明了带默认实现的非纯虚方法 （例如 Filter::CheckValid(const char*)、Filter::ValidRatio()、 Filter::FilterDistribution()、Filter::GetValidIds()，以及 Reader::MultiRead()），只在需 要自定义行为时才需要 override。实现必须的方法、用 std::shared_ptr 包装（或在 API 要求时 直接传裸指针），然后交给 VSAG 即可。

把扩展接入索引

主要有两条接入路径。

1. 通过 Engine 注入按索引生效的资源

vsag::Engine（vsag/engine.h）是绑定自定义 Allocator 与 ThreadPool 的 推荐方式，绑定后由它创建的每个索引都会共享这些资源：

auto allocator   = std::make_shared<MyAllocator>();
auto thread_pool = std::make_shared<MyThreadPool>();
vsag::Resource resource(allocator, thread_pool);
vsag::Engine engine(&resource);

auto index = engine.CreateIndex("hgraph", parameters).value();
// ... 使用索引 ...
engine.Shutdown();

Engine(Resource*) 接收的是 non-owning 裸指针（见 include/vsag/engine.h:38-42）：调用者必须保证 Resource（连同它持有的 allocator 与 thread pool）的生命周期长于 engine 以及 engine 创建的所有索引。 Engine::Shutdown() 释放 engine 内部资源，但不会销毁外部的 Resource。 Resource 提供两个构造器（include/vsag/resource.h:45,59-60）：既可以传裸 Allocator* / ThreadPool*（生命周期由调用者管理），也可以传 shared_ptr 重载，让 Resource 共享所有权。完整的所有权模型见 内存管理， 把 allocator 收敛到单次搜索调用的用法见 搜索路径 Allocator。

如果只是想快速跑通，Engine::CreateDefaultAllocator() 与 Engine::CreateThreadPool(num_threads) 会返回开箱即用的实现。

2. 通过 Factory::CreateIndex 传裸 allocator

vsag::Factory::CreateIndex(name, params, allocator)（vsag/factory.h）接受 一个可选的 Allocator*。这条路径不接受线程池，新代码建议改用 Engine。

Filter

实现 vsag::Filter，通过 SearchRequest::filter_（或已弃用的 SearchParam::filter）传入 FilterPtr 即可。使用 SearchRequest 时，必须 同时把 enable_filter_ 设为 true，filter 才会真正生效 （见 include/vsag/search_request.h:113,123）。只有 CheckValid(int64_t id) 是必须实现的，其他都是可选的优化钩子：

• CheckValid(const char* data)：基于向量 extra info 过滤。
• ValidRatio()：向规划器提示选择度。
• FilterDistribution()：返回 NONE（默认）或 RELATED_TO_VECTOR，声明有效 id 的分布是否与向量在底层存储中的位置相关 （见 include/vsag/filter.h:27-30）。
• GetValidIds(...)：对于选择度极低的过滤器，提供预先计算好的有效 id 列表。

可运行示例：examples/cpp/301_feature_filter.cpp。过滤接入的细节见 过滤搜索。

Reader / ReaderSet

Index::Deserialize(const ReaderSet&)（include/vsag/index.h:810）允许通过 per-stream 的 Reader 从任意存储后端（本地文件、对象存储、远程文件系统…） 反序列化索引。至少实现 Read、AsyncRead、Size 三个方法；MultiRead 是 可选的，当底层支持批量 IO 时能显著提升吞吐。vsag::Factory::CreateLocalFileReader 是本地文件的参考实现。

可运行示例：examples/cpp/102_index_diskann.cpp（DiskANN 的反序列化基于 ReaderSet）。完整的序列化/反序列化矩阵见 序列化。

Logger

VSAG 使用全局唯一的 logger，通过 Options 单例配置：

class MyLogger : public vsag::Logger { /* 实现 Trace/Debug/Info/... */ };
static MyLogger my_logger;
vsag::Options::Instance().set_logger(&my_logger);

logger 指针的所有权 不 归 VSAG —— 必须在所有 VSAG 调用期间保持其存活。 传入 nullptr 则回退到内置 logger。

可运行示例：examples/cpp/202_custom_logger.cpp。

通过 Options 进行全局调参

vsag::Options::Instance()（vsag/options.h）是进程级单例，承载与具体索引 无关的设置：

这些 option 对进程内所有索引生效，建议启动时设置一次。它们 不会 覆盖 HGraph 的 build_thread_count 等具体索引参数。

哪些 不 提供公开扩展接口

以下能力目前 没有 稳定的公开扩展接口：

• 量化器（Quantizer）。 具体量化类型（SQ8、PQ、RaBitQ…）通过索引参数选择， 不支持用户代码继承扩展。
• 距离计算器 / 距离类型。 每个索引的可选 metric 固定为 l2、ip、 cosine。
• 索引内部的 DataCell / IO / 存储后端。 这些都是实现细节。若需要自定义 IO，请在反序列化边界使用 Reader 接口。

如果你的场景需要上述任一能力，请提 issue 描述使用场景。

关于 vsag::ext

vsag/vsag_ext.h 提供了一组基于 handle 的精简 API（IndexHandler、 DatasetHandler、BitsetHandler ……），用于 语言绑定 / FFI，并不是面向最终用户的扩展层。 C++ 应用应直接使用标准的 vsag::Index API。

相关示例

• examples/cpp/201_custom_allocator.cpp
• examples/cpp/202_custom_logger.cpp
• examples/cpp/203_custom_thread_pool.cpp
• examples/cpp/301_feature_filter.cpp
• examples/cpp/102_index_diskann.cpp

图索引增强

图类索引在“困难查询“（与真实近邻连通性较弱）下可能出现召回率下降。 VSAG 通过 Conjugate Graph（共轭图）机制对这类查询进行在线/离线修补，在几乎不增加索引体积的 情况下显著改善尾部召回。

启用共轭图

构建时开启：

{
    "hnsw": {
        "max_degree": 32,
        "ef_construction": 400,
        "use_conjugate_graph": true
    }
}

搜索时通过搜索参数 JSON 中的 use_conjugate_graph_search 字段控制是否启用 （KnnSearch 并不存在额外的布尔参数重载）：

std::string search_param_json = R"({
    "hnsw": {
        "ef_search": 100,
        "use_conjugate_graph_search": true
    }
})";
auto result = index->KnnSearch(query, k, search_param_json);

工作原理

共轭图由原图在训练数据上的“失败路径“反向构建而成，在搜索时作为补充的候选边参与贪心扩展。 它相当于对主图的一层轻量索引补丁，典型体积 < 主图 10%。

示例

examples/cpp/304_feature_enhance_graph.cpp 给出了从构建、训练到对比召回率的完整流程。

适用场景

• 数据分布存在稀疏簇或离群点；
• 对 P99 召回敏感的在线场景；
• 希望在不重建索引的前提下小幅提升召回。

注意事项

• 启用后构建时间会略有增加。
• 共轭图数据会随索引一并序列化。
• 与 Tune 可以叠加使用，分别作用于路由质量与运行期参数。

Extra Info（附加信息）

extra_info 是与每条向量一同存放在索引内部的、定长的不透明字节负载。它允许把少量与向量配对的 非向量元数据（例如时间戳、类目 id、权限标签、应用自定义字段）直接保存在向量旁边，从而：

• 通过向量 id 直接获取元数据，无需额外的 KV 存储。
• 在不重新插入向量的前提下，原地更新某条向量对应的元数据。
• 在搜索过程中基于元数据过滤候选，而不是事后再过滤搜索结果。

VSAG 把该负载视为原始字节流，其内存布局、序列化与解释完全由用户自行决定。

索引支持情况

各索引支持的操作如下：

• HGraph：支持 Build/Add 时存入、GetExtraInfoByIds、UpdateExtraInfo、 use_extra_info_filter，以及在搜索结果中返回 extra info。
• LazyHGraph：两个阶段都支持与 HGraph 相同的能力。flat 阶段由 BruteForce 提供能力， 转换后 graph 阶段由 HGraph 提供能力。
• BruteForce：支持 Build/Add 时存入、GetExtraInfoByIds、UpdateExtraInfo、 use_extra_info_filter，以及在搜索结果中返回 extra info。
• IVF 和 SINDI：支持 Build/Add 时存入 extra info，但不提供获取、更新、 extra-info 过滤或在搜索结果中返回 extra info。

当 extra_info_size > 0 时，HGraph、LazyHGraph 和 BruteForce 会注册相关能力标志位。 运行时可通过 index->CheckFeature(...) 进行检查。

启用 Extra Info

在创建索引的参数中，添加顶层整型字段 extra_info_size，其值为每条向量预留的字节数。索引一旦 建立，该大小即被固定，并随索引一同序列化。

{
    "dtype": "float32",
    "metric_type": "l2",
    "dim": 128,
    "extra_info_size": 12,
    "index_param": {
        "base_quantization_type": "sq8",
        "max_degree": 26,
        "ef_construction": 100
    }
}

LazyHGraph 也使用顶层 extra_info_size；LazyHGraph 自身参数仍放在 lazy_hgraph 对象中：

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

未设置 extra_info_size 或将其设为 0 即表示禁用该特性。

在 Build / Add 时提供 Extra Info

通过 Dataset 的链式接口绑定字节缓冲区。该缓冲区必须连续，第 i 条向量的负载位于 i * extra_info_size 字节偏移处。

auto base = vsag::Dataset::Make();
base->NumElements(num_vectors)
    ->Dim(dim)
    ->Ids(ids.data())
    ->Float32Vectors(vectors.data())
    ->ExtraInfos(extra_infos.data())   // 总长度 num_vectors * extra_info_size 字节
    ->ExtraInfoSize(extra_info_size)   // 必须与索引的 extra_info_size 完全一致
    ->Owner(false);

index->Build(base);   // 或 index->Add(base)

ExtraInfoSize 必须和索引创建时的 extra_info_size 完全相等，否则调用会被拒绝。

获取 Extra Info

在搜索结果中获取

当 extra_info_size > 0 时，支持该能力的索引会在结果 Dataset 中填入每个返回 id 对应的 字节负载：

auto result = index->KnnSearch(query, k, search_params).value();
const char* infos = result->GetExtraInfos();
auto info_size = result->GetExtraInfoSize();

请使用 info_size 计算返回缓冲区中的偏移。

通过 ID 批量获取（GetExtraInfoByIds）

调用方需要预先分配 count * extra_info_size 字节的缓冲区：

if (index->CheckFeature(vsag::SUPPORT_GET_EXTRA_INFO_BY_ID)) {
    std::vector<char> out(count * extra_info_size);
    index->GetExtraInfoByIds(ids, count, out.data());
}

若该能力未开启，调用会返回 UNSUPPORTED_INDEX_OPERATION。

原地更新 Extra Info

无需触碰向量本身，即可更新单条向量的负载：

if (index->CheckFeature(vsag::SUPPORT_UPDATE_EXTRA_INFO_CONCURRENT)) {
    auto upd = vsag::Dataset::Make();
    upd->NumElements(1)
       ->Ids(&id)
       ->ExtraInfos(buffer.data())
       ->ExtraInfoSize(extra_info_size)
       ->Owner(false);
    index->UpdateExtraInfo(upd);
}

数据集必须只包含一条记录，且大小必须匹配。

基于 Extra Info 过滤

在过滤命中率较低的场景下，事后过滤会浪费大量计算。HGraph 与 LazyHGraph 可以在图遍历过程中 对每个候选向量直接调用用户定义的过滤器并传入其 extra_info 字节，从而让被过滤掉的候选不进入 结果集。LazyHGraph 在转换前也支持同样的字节负载过滤，此时 flat 阶段会执行精确扫描。

1. 重写 vsag::Filter 中接收字节缓冲区的版本：

   class CategoryFilter : public vsag::Filter {
   public:
       CategoryFilter(uint32_t lo, uint32_t hi) : lo_(lo), hi_(hi) {}
       bool CheckValid(int64_t /*id*/) const override { return true; }
       bool CheckValid(const char* data) const override {
           uint32_t category_id;
           std::memcpy(&category_id, data, sizeof(category_id));
           return category_id >= lo_ && category_id <= hi_;
       }
       float ValidRatio() const override { return 0.5F; }
   private:
       uint32_t lo_, hi_;
   };
   

2. 在搜索参数中的 hgraph 块开启 use_extra_info_filter，并把过滤器传入 KnnSearch：

   std::string search_params = R"({
       "hgraph": {
           "ef_search": 100,
           "use_extra_info_filter": true
       }
   })";
   auto filter = std::make_shared<CategoryFilter>(3, 7);
   auto result = index->KnnSearch(query, k, search_params, filter).value();
   

use_extra_info_filter 为 true 时，搜索路径会调用 CheckValid(const char*) 而不是 CheckValid(int64_t)。可使用 index->CheckFeature(vsag::SUPPORT_KNN_SEARCH_WITH_EX_FILTER) 进行能力检查。

LazyHGraph 说明

• 创建 LazyHGraph 索引时必须配置 extra_info_size；该字段不放在 lazy_hgraph 或 hgraph 对象内部。
• flat 阶段写入的 extra info 会在转换时迁移到内部 HGraph。
• GetExtraInfoByIds、UpdateExtraInfo、搜索结果返回 extra info，以及 use_extra_info_filter 在转换前后都可用。
• 序列化 LazyHGraph 时会保留当前阶段和已存储的 extra info。

能力标志

• vsag::SUPPORT_GET_EXTRA_INFO_BY_ID：支持 GetExtraInfoByIds。
• vsag::SUPPORT_UPDATE_EXTRA_INFO_CONCURRENT：支持线程安全的 UpdateExtraInfo。
• vsag::SUPPORT_KNN_SEARCH_WITH_EX_FILTER：搜索时支持 use_extra_info_filter。

注意事项与限制

• 负载是不透明的字节流，序列化/反序列化由用户负责，库内部仅按偏移复制。
• extra_info_size 在 Build 时即被固定，并写入序列化后的索引。
• 存储开销为 extra_info_size * num_elements 字节；支持该存储统计的索引会将其计入 EstimateMemory。
• 请尽量保持负载紧凑，因为 extra-info 过滤时会读取该负载。
• 该特性目前仅提供 C++ 接口，未提供 Python 绑定。

示例

完整的可运行示例位于 examples/cpp/320_feature_extra_info.cpp，演示了在 HGraph 上启用 extra_info、按 id 获取、extra-info 过滤搜索以及原地更新等用法。

索引生命周期管理

索引构建完成后，VSAG 提供一组用于原地修改索引或从已有索引派生新索引的操作。本页文档化完整的 生命周期接口：

• Remove —— 按 id 删除向量。
• UpdateVector / UpdateId —— 修改已有向量或重命名其 id。
• Clone —— 对已有索引进行深拷贝。
• ExportModel —— 将训练好的模型导出为空索引以复用。

每个操作均为可选项，仅当底层索引通过 index->CheckFeature(...) 公布对应能力标志时才可用。

能力标志