Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

VSAG 1.0 版本日志

v1.0.0 于项目启动三周年当天（2026 年 7 月 12 日）发布。

版本概览

VSAG 1.0 是项目首个长期支持（LTS）大版本。截至该版本发布时， 公开的 0.x 历史包含从 v0.11 到 v0.18 的 81 个版本标签。 v1.0.0 汇总了这一阶段的主线成果，覆盖稠密向量、稀疏向量、结构化过滤、 层级检索和多向量检索。

v1.0.0 官方 Release 收录了 v0.18.0 以来的 375 项变化： 48 项新增功能、134 项改进、105 项缺陷修复和 88 项其他变化。 v0.11.0...v1.0.0 主线对比包含 1,252 个提交。

本文仅描述 v1.0.0 标签中可用的 API 与功能。

主要能力

索引体系

下图按职责展示 VSAG 1.0 的索引体系：Pyramid 和 LazyHGraph 提供组合与自适应能力， 下层展示 BruteForce、HGraph、IVF、SINDI 和 SIMQ 五个核心索引族。

组合与自适应索引：

  • 分区索引 Pyramid：支持将同一条向量加入多个 Pyramid 路径， 并按指定路径限定检索范围，适合多租户与层级检索 （PR #2226）。
  • 自伸缩图索引 LazyHGraph：在数据量较小时使用精确 BruteForce， 达到可配置阈值后转换为 HGraph，适合持续增长但初始规模较小的集合 （PR #2151）。

核心索引族：

  • 暴力搜索索引 BruteForce：支持单向量和多向量精确检索，是精确检索基线，也是小规模集合的精确检索选项。
  • 图索引 HGraph：面向高召回、低延迟的稠密向量检索。从最初的 HGraph 实现发展至今， 已支持量化、过滤、范围与迭代检索、更新、标记/强制删除、缓存导入导出、 诊断和内存+磁盘配置。
  • 空间划分索引 IVF：面向大规模数据、批量查询和大 top-k 场景，支持量化、 重排、属性过滤、并行构建/检索和磁盘分桶存储。参见最初的 IVF PR。
  • 稀疏向量索引 SINDI：面向 BM25 风格和学习型稀疏表示， 支持词项 ID 重映射、索引分析、不可变读取、FP16 稀疏值、词项列表压缩和 低内存不可变构建。
  • 多向量索引 SIMQ：面向 ColBERT 等 late-interaction 多向量检索， 先在聚类级别生成候选，再用精确 MaxSim 重排，以平衡召回率和延迟 （PR #2357）。

各索引的参数与使用说明参见索引。

量化、数据类型与硬件加速

VSAG 1.0 提供多种输入格式、量化方法、向量变换与硬件加速路径：

  • FP32、INT8、FP16、BF16 稠密输入，以及稀疏与多向量数据集； FP16/BF16 可直接输入（PR #1731）；
  • SQ4/SQ8 及对应的均匀量化变体；
  • Product Quantization 和 PQ FastScan （PR #626、 PR #691）；
  • RaBitQ、扩展位宽与 x+y split 的基础/重排布局、FHT/PCA 变换和专用 SIMD 内核；
  • Transform Quantizer 链与 MRL-E 降维；
  • x86_64 上的 SSE、AVX、AVX2、AVX-512 和部分 AMX 内核，以及 ARM NEON、SVE；
  • SQ8U 内积和 KMeans BF16 GEMM 的 AMX 加速 （PR #2032）。

支持组合与调参建议参见量化。

检索、过滤与索引管理

  • 基础检索： KnnSearch 提供 KNN 查询，RangeSearch 提供可限制结果数量的范围查询。
  • 统一请求接口： SearchRequest 与 Index::SearchWithRequest 使用一个请求对象选择 KNN 或范围检索，并传递索引专用 JSON 参数、受支持的过滤条件和诊断输入。v1.0 中 HGraph、IVF 和 BruteForce 实现了该接口，可用字段因索引而异。
  • 过滤： 支持 ID 回调/FilterPtr、bitset 和 SQL 风格属性表达式。HGraph、IVF 和 BruteForce 支持基于属性倒排索引的结构化过滤；HGraph 还支持迭代过滤，并可在有效数据比例不高于 hgraph.brute_force_threshold 时切换到暴力检索。
  • 训练与模型复用： Train、Clone、ExportModel 和 Tune 分别用于独立训练、索引深拷贝、训练模型导出和索引调优。
  • 数据维护与读取： 支持批量删除、标记/强制删除、ID/向量/属性更新、Source ID、extra_info、索引详情读取和 CalcDistanceById。
  • 漏召回诊断： SearchRequest::expected_labels_ 可在 HGraph、IVF 和 BruteForce 中分析目标向量未被召回的原因，推理报告随结果 Dataset 返回（PR #1838）。
  • 统计与容量规划： 检索、I/O、内存和索引专用统计用于观测运行状态；内存估算、索引内省和分析工具用于容量评估与问题定位。

具体支持范围因索引而异；可通过 Index::CheckFeature(IndexFeature) 查询其中已声明的能力。

序列化与兼容性

VSAG 1.0 并行维护两套序列化接口：既有 Serialize/Deserialize 接口继续维护， 用于保持现有接入的兼容性；新的流式序列化接口 采用头部先行（header-first）、仅需顺序读取的格式，并扩展以下能力：

  • SerializeStreaming 先写元数据，再写带类型的 TLV 数据块；
  • DeserializeStreaming 将数据恢复到已创建、为空且兼容的索引对象；
  • Index::Load 读取元数据、创建对应索引，并应用受支持的存储放置策略；
  • BruteForce、HGraph、IVF、可变 SINDI 和 Pyramid 已支持 v1.0 流式序列化； 不可变 SINDI 运行态在 v1.0 中暂不支持。

两套接口会并行保留，但两种格式不兼容，文件必须使用对应的接口读取。 既有用户可继续使用原接口；新接入建议优先使用流式序列化接口。 格式和数据块版本细节参见 新序列化格式。

跨版本索引测试样本和兼容性检查工具 可用于重复验证旧索引的升级过程。

平台、绑定与工具

  • VSAG 核心 C++ 库支持 Linux 和 macOS，主要研发和完整验证链路以 Linux 为主。 Linux x86_64 与 AArch64 均通过 CI，macOS 当前验证 arm64 构建 （源码构建、 PR CI）。 预编译 C++ 发布包目前仅面向 Linux x86_64。
  • Python 绑定的包名为 pyvsag；v1.0.0 声明支持 CPython 3.6-3.14，并为这一版本范围配置了 wheel 构建。 Python 构建已迁移到原生 CMake 集成 （PR #1599）； 绑定还支持更多索引操作、FP16/BF16 输入、稀疏向量和稀疏 HDF5 辅助工具。
  • VSAG 新增 C API 与 Node.js/TypeScript 绑定，并提供 快速入门示例。各语言绑定独立发布，使用时请确认对应包版本。
  • 构建支持系统级 OpenBLAS/fmt、自定义依赖下载镜像和可安装的 CMake 包配置。
  • eval_performance 支持稠密、稀疏和多向量数据集；analyze_index、 check_compatibility、visualize_index 和 HTTP 监控服务补齐了分析、兼容性验证、 序列化检查与监控工具。

稳定性与验证

功能与回归测试覆盖内存分配、泄漏与内存不足路径，以及多线程下的构建、写入、 检索、更新、删除和析构。CI 通过 ASan 持续检查内存安全，并通过 TSan 检查数据竞争； 兼容性测试样本用于验证历史索引的升级路径。

从 v0.18 升级的兼容性说明

VSAG 1.0 是大版本升级，包含源码级 API 变化。升级前请重点检查：

  1. Remove 返回删除数量并支持批量操作。 v0.18 的 tl::expected<bool, Error> Remove(int64_t) 调整为 tl::expected<uint32_t, Error>，并增加批量重载和显式删除模式 （PR #1551）。 v1.0 最终提供 RemoveMode::MARK_REMOVE 和 RemoveMode::FORCE_REMOVE； HGraph 强制删除由 PR #1810实现。
  2. 不支持的操作通常改为返回错误。 许多返回 tl::expected 的默认方法不再抛出 std::runtime_error，而是返回带 ErrorType::UNSUPPORTED_INDEX_OPERATION 的 tl::unexpected （PR #2141）。调用 .value() 前 应先检查 tl::expected 返回值。
  3. 内存统计接口签名发生变化。 GetMemoryUsage 使用 uint64_t， GetMemoryUsageDetail 返回 std::unordered_map<std::string, uint64_t>， GetEstimateBuildMemory 更名为 EstimateBuildMemory （PR #2388）。
  4. 检索接口可以渐进迁移。 新接入优先使用 SearchRequest 和 SearchWithRequest，既有检索重载在 v1.0 中仍然保留。
  5. 不要混用两套序列化格式。 旧格式输出必须使用旧反序列化接口； 流式序列化输出必须使用 DeserializeStreaming 或 Index::Load。
  6. SINDI 自动选择堆插入策略。 旧的 use_term_lists_heap_insert 检索参数 会被忽略。SINDI 根据 doc_prune_ratio 和 query_prune_ratio 推导策略；依赖 强制指定旧路径的配置需要调整。
  7. Intel MKL 改为显式开启。 默认值为 OFF。通过 Makefile 构建时设置 VSAG_ENABLE_INTEL_MKL=ON，直接使用 CMake 时设置 -DENABLE_INTEL_MKL=ON。

对于持久化索引，建议在测试环境验证明确的源版本与目标版本组合。 序列化兼容性可能因索引类型、功能开关和格式家族而异。

从 v0.x 走向 1.0

v0.11.0 是 VSAG 开源后的首个正式发布版本。此前的版本号仅用于内部迭代，未作为 GitHub Release 对外发布，因此本节从 v0.11 开始回顾。

基础建设：v0.11-v0.14

  • v0.11，2024 年 9 月： 建立 HNSW/DiskANN、C++/Python、预过滤、余弦距离、锁和序列化的初始基线。
  • v0.12，2024 年 12 月： 引入 DataCell、I/O 与图抽象、HGraph、SQ4/SQ8/INT8、Engine/Factory 和 pyvsag 打包。
  • v0.13，2025 年 2 月： 新增 BruteForce，并扩展 Pyramid、内存估算、IndexFeature、过滤提示和 eval_performance。
  • v0.14，2025 年 4 月： 引入 IVF、FP16/BF16、RaBitQ、异步/缓冲 I/O、稀疏数据、HGraph extra_info、迭代过滤与系统化兼容性检查。

生产能力扩展：v0.15-v0.18

  • v0.15，2025 年 6 月： 新增 Train/Clone/ExportModel、PQ/PQ FastScan、属性表达式、压缩图、HGraph 合并/标记删除，以及带兼容性 CI 的既有格式自描述序列化。
  • v0.16，2025 年 8 月： 新增 mmap HGraph、SINDI、并行 IVF、属性更新、原始向量读取和参数兼容性检查，并 通过长期补丁线持续解决 ABI、并发和旧索引兼容问题。
  • v0.17，2025 年 10 月： 扩展 SearchRequest 以覆盖主要检索场景，并增加检索超时、 更广泛的 extra_info、Transform Quantizer、HGraph 单查询并行、 数据导出与更完整的 SINDI 生命周期和统计能力。
  • v0.18，2026 年 1 月： 新增 C API、自动构建 Python wheel、稀疏 Python 绑定、磁盘 IVF、索引详情/检索/I/O 统计、MRL-E 与 HGraph 调优、扩展 RaBitQ，并继续完善 SINDI 和 Pyramid。

完整提交历史参见 v0.11.0…v1.0.0 对比。

v1.0 补丁版本

  • v1.0.0 （2026 年 7 月 12 日）：首个长期支持大版本。

后续 v1.0.x 补丁版本会追加到本节。 完整 PR 清单和各版本贡献者名单继续维护在 GitHub Releases。

致谢

VSAG 1.0 是蚂蚁集团 VSAG 团队与开源社区共同贡献的成果。 感谢所有参与算法设计、功能实现、问题反馈、代码评审、 测试改进和文档建设的贡献者。

完整名单参见贡献者页面和 官方 Release。