Zvec 架构深度解析：阿里开源轻量级进程内向量数据库

架构层次说明：

• 用户层：Python/Node.js 提供的 API 接口
• 绑定层：Pybind11/N-API 实现 Python 到 C++ 的桥接
• 数据库层：Collection 管理 Schema、Segment、ID 映射等
• 核心索引框架：抽象的索引接口和实现
• Proxima 引擎：实际的向量搜索算法实现
• 存储层：RocksDB 处理结构化数据，MMap 处理向量索引

三、核心索引框架详解

3.1 索引类型与选择策略

Zvec 提供三种索引类型，根据数据规模自动选择最优算法：

核心代码实现 (src/include/zvec/core/interface/index.h)：

class Index {
public:
    virtual int Add(const VectorData &vector, uint32_t doc_id);
    virtual int Search(const VectorData &query, SearchParams *, SearchResult *);
    virtual int Train();
    virtual int Open(const std::string &file_path, StorageOptions);
};

// 三种索引类型实现
class FlatIndex : public Index {};
// 暴力搜索
class IVFIndex : public Index {};
// 倒排文件索引
class HNSWIndex : public Index {};
// 层次导航小世界图

3.2 IndexHolder 系统：模板化的数据管理

IndexHolder 是一个精心设计的模板系统，用于在索引构建和搜索期间管理向量数据。

三个设计维度

1. 迭代模式：
   • OnePass*Holder：单次遍历，迭代时消耗数据（使用 std::list）
   • MultiPass*Holder：支持多次遍历（使用 std::vector）
   • RandomAccessIndexHolder：O(1) 随机访问
2. 数据类型：
   • NumericalIndexHolder：FP16, FP32, FP64, INT8, INT16
   • BinaryIndexHolder：Binary32, Binary64
   • SparseIndexHolder：稀疏向量（indices + values）
   • HybridIndexHolder：稠密 + 稀疏组合
3. 元素大小计算：
   • element_size() 返回 dimension * sizeof(type)
   • 二进制向量使用 (dim + 7) / 8 * sizeof(T) 公式

内存管理策略

OnePass holders 使用 std::list<std::pair<key, vector>>：

• 元素在迭代时被消费
• 迭代器在前进时擦除元素
• 数据随处理释放内存

MultiPass holders 使用 std::vector<std::pair<key, vector>>：

• 支持多次迭代
• 迭代器仅前进
• 内存保留直到 holder 销毁

稀疏与混合向量支持

struct SparseVector {
    uint32_t count;
    const void* indices; // uint32_t*
    const void* values; // 类型特定*
};

struct HybridVector {
    // 组合稠密和稀疏向量
    // 支持混合搜索策略
};

设计决策表

模板特化模式

3.3 查询参数系统

class HnswQueryParams : public QueryParams {
    int ef_; // 探索因子
    float radius_; // 搜索半径
    bool is_linear_; // 是否使用线性扫描
    bool is_using_refiner_; // 是否使用精炼器
};

class IVFQueryParams : public QueryParams {
    int nprobe_; // 探测的簇数量
    float scale_factor_; // 缩放因子
};

四、数据库层架构

4.1 CollectionImpl 结构

class CollectionImpl : public Collection {
    // 路径管理
    std::string path_;
    bool destroyed_{false};
    // Schema 和选项
    CollectionSchema::Ptr schema_;
    CollectionOptions options_;
    mutable std::shared_mutex schema_handle_mtx_;
    // 分片管理
    std::atomic<SegmentID> segment_id_allocator_;
    std::atomic<SegmentID> tmp_segment_id_allocator_;
    Segment::Ptr writing_segment_;
    SegmentManager::Ptr segment_manager_;
    // 版本管理
    VersionManager::Ptr version_manager_;
    // 并发控制
    mutable std::shared_mutex write_mtx_;
    // 文件锁和元数据
    ailego::File lock_file_;
    IDMap::Ptr id_map_;
    DeleteStore::Ptr delete_store_;
    sqlengine::SQLEngine::Ptr sql_engine_;
};

4.2 写入模式

enum class WriteMode : uint8_t {
    UNDEFINED = 0,
    INSERT, // 仅插入新文档
    UPDATE, // 更新现有文档
    UPSERT, // 更新或插入
};

4.3 分片管理策略

Writing Segment：用于写入的活动分片

• 任意时刻仅使用单个分片
• 当达到 max_doc_count_per_segment（1000 万）时自动切换

Segment Manager：管理所有非写入分片

• 按 doc_id 范围排序分片
• 高效的范围查询

ID 分配：分片 ID 的原子分配

SegmentID allocate_segment_id() {
    return segment_id_allocator_.fetch_add(1);
}

4.4 并发策略

Schema 操作：std::shared_mutex schema_handle_mtx_

• 多读单写
• Schema 变更很少发生

写入操作：std::shared_mutex write_mtx_

• 防止集合的并发写入

分段读取：无锁

• 允许分片的并发读取

五、存储与持久化架构

5.1 文件组织结构

collection_root/
├── _CollectionLock # 进程锁文件
├── meta/ # 元数据
│   ├── schema.pb # 集合 schema
│   ├── config.pb # 选项配置
│   └── version.pb # 版本信息
├── segments/ # 数据分片
│   ├── segment_00001/
│   │   ├── meta.pb # 分片元数据
│   │   ├── data/ # 原始向量数据
│   │   ├── indexes/ # 向量索引
│   │   │   ├── flat/
│   │   │   ├── ivf/
│   │   │   └── hnsw/
│   │   ├── forward/ # 标量字段
│   │   │   └── rocksdb/
│   │   └── sql.db # SQL 引擎数据库
│   └── ...
├── writing_segment/ # 活动写入分片
├── id_map/ # PK → DocID 映射
├── delete_store/ # 删除墓碑标记
└── version_manager/ # 版本跟踪 

5.2 存储层组件

IndexStorage (src/include/zvec/core/framework/index_storage.h)：

struct MemoryBlock {
    enum MemoryBlockType {
        MBT_MMAP = 1, // 内存映射文件
        MBT_BUFFERPOOL = 2 // 内存池缓冲区
    };
    // 支持零拷贝访问
    const void* data;
    BufferHandle buffer_handle_;
};

class IndexStorage {
    // 段管理
    virtual int open(const std::string &path, bool create) = 0;
    virtual int append(const std::string &id, size_t size) = 0;
    virtual Segment::Pointer get(const std::string &id) = 0;
};

RocksDB 集成：

• 文档索引：ID 到文档位置的映射
• 字段索引：结构化字段的倒排索引
• 元数据存储：集合配置和状态

5.3 MMap 优化

// 内存映射文件，零拷贝访问
class MMapFile {
    int fd_;
    void* mapped_data_;
    size_t size_;
    int map(const std::string &path, size_t size, int prot, int flags);
    int unmap();
};

优势：

• 零拷贝读取
• 操作系统级页面缓存
• 支持超大文件（超过内存）

六、Python 绑定架构

6.1 绑定模块结构

PYBIND11_MODULE(_zvec, m){
    ZVecPyTyping::Initialize(m); // 类型定义
    ZVecPyParams::Initialize(m); // 参数绑定
    ZVecPySchemas::Initialize(m); // Schema 绑定
    ZVecPyConfig::Initialize(m); // 配置绑定
    ZVecPyDoc::Initialize(m); // 文档绑定
    ZVecPyCollection::Initialize(m); // 集合绑定
}

6.2 错误处理机制

C++ Status → Python Exception：

void throw_if_error(const Status &status) {
    switch(status.code()) {
        case StatusCode::NOT_FOUND: throw py::key_error(status.message());
        case StatusCode::INVALID_ARGUMENT: throw py::value_error(status.message());
        default: throw std::runtime_error(status.message());
    }
}

6.3 结果解包

template<typename T>
T unwrap_expected(const tl::expected<T, Status>& exp) {
    if(exp.has_value()) { return exp.value(); }
    throw_if_error(exp.error());
}

6.4 Python API 示例

import zvec

# 定义 Schema
schema = zvec.CollectionSchema(
    name="example",
    vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 4)
)

# 创建并打开集合
collection = zvec.create_and_open(path="./zvec_example", schema=schema)

# 插入文档
collection.insert([
    zvec.Doc(id="doc_1", vectors={"embedding": [0.1, 0.2, 0.3, 0.4]}),
    zvec.Doc(id="doc_2", vectors={"embedding": [0.2, 0.3, 0.4, 0.1]}),
])

# 向量搜索
results = collection.query(
    zvec.VectorQuery("embedding", vector=[0.4, 0.3, 0.3, 0.1]),
    topk=10
)

七、性能优化技术

7.1 向量化计算

// SIMD 优化的批量计算
namespace math_batch {
    // 批量点积计算
    void dot_product_simd(const float* a, const float* b, size_t n, float* result);
    // 批量 L2 距离计算
    void l2_distance_simd(const float* a, const float* b, size_t n, float* result);
}

7.2 内存池管理

class BufferManager {
    // 预分配内存池
    void* allocate(size_t size);
    // 回收内存到池中
    void deallocate(void* ptr);
    // 批量分配，减少系统调用
    std::vector<void*> batch_allocate(size_t size, size_t count);
};

7.3 压缩与位图

• LZ4 压缩：极致快的压缩/解压
• CRoaring 位图：高效的集合运算
• SparseHash：Google 的稀疏哈希表

八、核心依赖库分析

九、数据流详解

9.1 插入流程

流程关键点：

1. 写锁保护：使用 std::shared_mutex 确保写入串行化
2. 自动分片：达到 1000 万文档自动创建新分片
3. ID 分配：IDMap 提供 PK → DocID 映射
4. 混合存储：向量数据 → VectorStorage，标量数据 → RocksDB
5. 版本控制：每次写入更新版本信息

Python API ↓ Pybind11 包装器 (throw_if_error) ↓ Collection::Insert() ↓ CollectionImpl::write_impl(INSERT) ↓ 
1. 获取写锁 (std::shared_mutex) 
2. 检查分片容量 
3. 如需要切换到新分片 
4. 分配文档 ID (IDMap) 
5. 写入向量数据 (VectorSegment) 
6. 写入标量数据 (RocksDB) 
7. 更新分片元数据 
8. 释放写锁 ↓ 
返回 WriteResults ↓ Python WriteResults 对象 

9.2 查询流程

Python VectorQuery ↓ Pybind11 包装器 ↓ Collection::Query() ↓ CollectionImpl::Query() ↓ 
1. 解析查询参数 
2. 识别相关分片 
3. 查询每个分片索引 - HNSWIndex::Search() - 或 IVFIndex::Search() - 或 FlatIndex::Search() 
4. 应用过滤器（如果有） 
5. 合并和排序结果 
6. 精炼 top-K 结果（如果配置） ↓ 
返回 DocPtrList ↓ Python Doc 对象列表 

十、与服务器型向量数据库对比

十一、架构亮点总结

11.1 设计优势

1. 进程内设计
   • 无网络开销
   • 共享内存访问
   • 零配置启动
2. 模块化架构
   • 索引类型可插拔
   • 存储引擎可替换
   • 语言绑定可扩展
3. 性能优化
   • SIMD 向量化计算
   • 内存池管理
   • MMap 零拷贝 I/O
4. 类型安全
   • 编译时类型检查
   • Schema 验证
   • 明确的向量类型

11.2 技术亮点

• 混合向量搜索: 同时支持稠密和稀疏向量
• 多语言绑定: Python + Node.js，易于扩展
• 持久化设计: MMap + RocksDB 双重存储
• 分片架构: 自动分片，水平扩展
• Proxima 基因: 继承 Alibaba 生产级引擎

十二、适用场景

Zvec 的架构设计使其特别适合以下场景：

1. RAG 应用: 文档检索 + 向量相似度
2. 推荐系统: 实时物品召回
3. 语义搜索: 自然语言查询
4. 图像检索: 多模态向量搜索
5. 边缘计算: 嵌入式设备上的向量搜索
6. 实时应用: 需要极低延迟的场景
7. 轻量级部署: 无法运行独立服务的环境

十三、代码位置参考

十四、部署与安装说明

注意：由于 Zvec 的 PyPI 包尚未发布，实际安装需关注官方动态。

14.1 安装现状

根据 README 文档，Zvec 声称支持 Python 3.10-3.12 版本，可通过 pip install zvec 安装。但实际尝试中发现：

1. PyPI 包未发布：pip install zvec 返回 'No matching distribution found'
2. 源码构建问题：尝试从源码构建时，遇到以下问题：
   • 部分第三方依赖缺少 CMakeLists.txt（thirdparty/googletest、thirdparty/gflags）
   • 需要 scikit-build-core 构建系统
   • 构建配置较复杂

建议：关注 GitHub Releases 获取预构建包，或等待 PyPI 正式发布。

14.2 源码构建步骤

# 激活 Python 环境
source ~/miniforge3/bin/activate py311

# 克隆仓库
git clone https://github.com/alibaba/zvec.git
cd zvec

# 初始化 Git Submodules
git submodule update --init --recursive

# 配置构建
mkdir -p test_build && cd test_build
cmake -S .. -B . -DCMAKE_BUILD_PYTHON_BINDINGS=OFF

# 构建
make -j4

14.3 潜在问题与解决

1. PyPI 包不存在：等待官方发布或使用 GitHub Releases
2. Git Submodules 未初始化：运行 git submodule update --init --recursive
3. CMake 配置失败：指定完整编译器，确保子模块已初始化
4. 缺少构建依赖：需要更多依赖调整，建议查看 CI/CD 配置

十五、总结

Zvec 是一个设计精良的向量数据库，其核心优势在于：

• ✅ 轻量级: 进程内运行，零依赖
• ✅ 高性能: 基于 Proxima，毫秒级搜索
• ✅ 易用性: 简单 API，快速上手
• ✅ 灵活性: 模块化设计，易于定制
• ✅ 类型安全: 模板系统保证编译时检查

GitHub: https://github.com/alibaba/zvec
文档: https://zvec.org