ZVec 是阿里巴巴开源的一款轻量级、高性能、进程内向量数据库。它支持密集和稀疏向量、全文搜索（FTS）以及混合搜索，并提供了丰富的多语言SDK。

以下是一份详细的部署与使用教程，涵盖了从安装到运行的各个环节。

📋 部署前准备

ZVec 以进程内库（in-process library）的形式运行，无需单独部署服务器，因此准备工作的核心是确定你的编程语言和开发环境。

  1. 支持的语言：ZVec 提供官方 SDK 的语言包括 Python、Node.js、Go、Rust 和 Dart/Flutter。
  2. 支持的操作系统与架构：
    • Linux: x86_64 和 ARM64 (支持 glibc 和 musl，如 Alpine Linux)
    • macOS: ARM64 (Apple Silicon)
    • Windows: x86_64
  3. Python 特别注意: 需要 64位 Python 3.10 至 3.14 版本。

📦 第二步：安装 SDK

根据你的项目使用的编程语言，选择对应的包管理器进行安装。

Python

1
pip install zvec

Node.js

1
npm install @zvec/zvec

Rust

1
cargo add zvec-rust

Go
从源码或官方发布的预编译二进制文件引入，具体参考官方文档。

Dart/Flutter

1
flutter pub add zvec

⚡ 第三步：一分钟快速上手 (Python 示例)

安装完成后，你可以通过一个简单的Python示例来验证安装并了解基本用法。

  1. 创建或打开一个 Python 文件 (例如 zvec_demo.py)。

  2. 编写以下代码：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    import zvec

    # 1. 定义集合（Collection）的模式（Schema）
    schema = zvec.CollectionSchema(
        name="example",  # 集合名称
        vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 4),  # 向量字段：名称、类型、维度
    )

    # 2. 创建并打开集合（数据将持久化到 ./zvec_example 目录）
    collection = zvec.create_and_open(path="./zvec_example", schema=schema)

    # 3. 插入一些文档（包含向量）
    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]}),
        zvec.Doc(id="doc_3", vectors={"embedding": [0.9, 0.8, 0.7, 0.6]}),
    ])

    # 4. 执行向量相似性搜索
    query_vector = [0.4, 0.3, 0.3, 0.1]
    results = collection.query(
        zvec.Query(field_name="embedding", vector=query_vector),
        topk=2  # 返回最相似的2个结果
    )

    # 5. 打印结果
    print("搜索结果（按相似度降序）:")
    for res in results:
        print(f"ID: {res['id']}, 得分 (相似度): {res['score']:.4f}")

  3. 运行代码:

    1
    python zvec_demo.py

    如果一切正常，你将看到类似如下的输出，doc_2 和 doc_1 与查询向量更相似：

    1
    2
    3
    搜索结果（按相似度降序）:
    ID: doc_2, 得分 (相似度): 0.9999
    ID: doc_1, 得分 (相似度): 0.7999

🔍 第四步：探索高级功能

ZVec 的核心能力远不止基础向量搜索，你可以根据自己的需求逐步探索：

  1. 全文搜索 (FTS): 支持对字符串字段进行关键词查询。你可以在 Schema 中定义全文索引字段，然后使用 Query 的 text 参数进行搜索。
  2. 混合搜索 (Hybrid Search): 结合向量相似度和全文/过滤条件进行查询。例如，先通过向量找到语义相近的文档，再用关键词或过滤器（如时间、类别）进行精确筛选。这通过在 Query 中组合 vector 和 filter 等参数实现。
  3. 持久化与并发: ZVec 默认使用预写日志 (WAL) 保证数据持久化。它支持多进程并发读取同一个集合，但写入操作需要单进程独占。
  4. zvec-grep (zg): 这是一个集成了 ripgrep、BM25 和向量搜索的统一命令行搜索工具，非常适合在代码或文档库中进行本地优先的搜索。

🛠️ 第五步：从源码构建 (高级)

如果你需要定制编译或为不支持的平台构建，可以参考以下步骤（以Linux/macOS为例）：

  1. 克隆仓库

    1
    2
    git clone https://github.com/alibaba/zvec.git
    cd zvec

  2. 构建
    项目使用 CMake。你需要安装 CMake 和 C++ 编译器。

    1
    2
    3
    mkdir build && cd build
    cmake .. -DCMAKE_BUILD_TYPE=Release
    make -j$(nproc)

  3. 运行测试 (可选)

    1
    make test

    构建产物（库文件和头文件）会生成在 build/ 目录下。具体构建选项（如启用特定指令集）请查阅官方 Building from Source Guide（目前链接在README中指向文档，具体内容需查看仓库）。

🧪 第六步：验证与下一步

  • 运行示例代码: 确保你的第一个程序成功运行，这是验证安装和基础环境的最快方式。
  • 查阅官方文档: 项目的 GitHub 仓库提供了丰富的 文档 链接，包括 Benchmarks (性能基准)、DeepWiki (深入的技术细节) 等，可以帮助你深入了解其内部机制和最佳实践。
  • 使用可视化工具: 官方提供了 Zvec Studio，一个用于浏览数据和调试查询的可视化工具，无需编写代码即可体验。

❗ 常见问题

  • Python 安装失败: 请确认你的 Python 版本是 3.10-3.14 且为 64 位架构。可以运行 python -c "import struct; print(struct.calcsize('P') * 8)" 检查位数。
  • 性能调优: 对于生产环境，建议根据数据规模和内存/磁盘情况选择合适的索引类型（如 HNSW、DiskANN、IVF-RaBitQ 等）。新版本的索引（如 IVF-RaBitQ）支持运行时 AVX2/AVX512 自动调度，能充分利用 CPU 性能。
  • 数据持久化: 确保在创建集合时指定了有效的 path，ZVec 会将数据持久化到该目录。

至此，你已经成功部署并运行了 ZVec。建议从 Python 示例开始，快速验证核心流程，然后根据你的应用场景（如RAG系统、推荐引擎、语义搜索等），深入学习其索引优化和混合查询功能。