alibaba/zvec · 上手攻略

• 仓库：alibaba/zvec
• 链接：https://github.com/alibaba/zvec
• 分类：ai / vector-database
• 作者：Tom
• 更新：2026-07-19

一、是什么

Zvec 是阿里巴巴通义实验室开源的进程内（in-process）向量数据库，定位为"向量数据库领域的 SQLite"——直接以内嵌库的方式运行在你的应用程序中，无需部署独立的数据库服务进程。它基于阿里生产级 Proxima 向量检索引擎，支持稠密向量 + 稀疏向量 + 全文检索（FTS）混合检索，并内置 WAL 持久化、多进程并发读取等企业级特性。

当前版本（截至 2026-07）： v0.5.0（2026 年 6 月 12 日发布）

核心能力： - 毫秒级检索数十亿级向量 - 纯本地运行，零服务器依赖 - 稠密向量 + 稀疏向量 + 多向量查询 - 原生全文检索（FTS，v0.5.0 新增） - 混合检索：向量 + 全文 + 标量过滤 + RRF 重排 - WAL 预写日志持久化 - 多进程并发读，单进程独占写 - DiskANN 磁盘索引（降低大规模数据内存占用） - 官方多语言 SDK：Python / Node.js / Go / Rust / Dart

二、快速安装

Python SDK（推荐）

pip install zvec

要求： 64 位 Python 3.10–3.14

Node.js SDK

npm install @zvec/zvec

其他语言

# Go
go get github.com/zvec-ai/zvec-go

# Rust
cargo add zvec

# Dart/Flutter
flutter pub add zvec

预编译二进制（系统级）

支持平台：Linux (x86_64, ARM64)、macOS (ARM64)、Windows (x86_64)。从源码构建请参考官方文档。

三、核心用法

3.1 Python 最简示例

import zvec

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

# 创建并打开 collection
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.Query(field_name="embedding", vector=[0.4, 0.3, 0.3, 0.1]),
    topk=10
)

print(results)  # [{'id': 'doc_2', 'score': 0.99, ...}, ...]

3.2 全文检索（FTS，v0.5.0 新增）

# 为字符串字段附加 FTS 索引
schema = zvec.CollectionSchema(
    name="docs",
    vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 1536),
)
collection = zvec.create_and_open(path="./docs_db", schema=schema)

# 插入含文本的文档
collection.insert([
    zvec.Doc(id="doc_1", text={"content": "Python machine learning tutorial"}),
])

# 全文检索（自然语言或结构化表达式）
results = collection.query(
    zvec.Query(field_name="content", text="machine learning", topk=5)
)

3.3 混合检索（向量 + 全文 + 过滤）

# 在单次查询中融合向量语义、全文检索和标量过滤
results = collection.query(
    zvec.Query(
        field_name="embedding",
        vector=[0.1, 0.2, 0.3, 0.4],
        text="Python tutorial",       # 全文检索条件
        filter={"category": "ml"},     # 标量过滤
    ),
    topk=10,
    fusion="rrf"  # RRF（Rerank）融合
)

四、向量索引类型

Zvec 支持从内存到磁盘的多种索引类型（具体选型请参考官方文档），包括：

• HNSW：内存索引，高检索精度，适合中小规模数据集
• DiskANN：磁盘索引，适合大规模数据，大幅降低内存占用（v0.5.0 新增）

五、适用场景

• ✅ 本地 RAG：在笔记本、边缘设备上运行 RAG Pipeline，无需额外部署
• ✅ 应用内向量检索：应用本身需要向量搜索能力（如推荐系统、内容检索）
• ✅ 多租户 SaaS：每个租户一个本地 Zvec 实例，数据完全隔离
• ✅ 原型验证：在 Notebook 中快速验证向量检索 idea，无需搭建 Milvus/Qdrant
• ✅ 嵌入式 AI：手机、IoT 设备上的本地向量检索
• ❌ 超大规模（>10 亿向量）+ 多节点分布 → 建议用 Milvus / Zilliz Cloud
• ❌ 需要图形化管理界面 → 建议用 Zvec Studio 或 Qdrant Console

六、坑与注意

1. Python 版本限制：仅支持 64 位 Python 3.10–3.14，3.9 及以下不兼容。
2. 写入独占：写入操作是单进程独占模式，多进程并发写入场景需要应用层协调（如用锁或进程队列）。
3. Windows 支持有限：仅支持 x86_64 架构，Windows ARM64 版本未提供。
4. v0.5.0 为最新主要版本：FTS 和 DiskANN 功能较新，生产使用前建议充分测试。
5. benchmark 数据来自 Alibaba 内部：Reddit 讨论中提到的"2倍于 Zilliz Cloud"性能数据来自官方评测，实际生产环境表现可能因数据分布而异。

七、与同类对比

八、性能参考

官方 benchmark（VectorDBBench，Cohere 10M 数据集）： - 超过 8,000 QPS - 官方称是 Zilliz Cloud（彼时榜单第一）的 2 倍以上 - Index 构建时间显著低于竞品

⚠️ 注意：上述数据来自 Zvec 官方评测，实际效果请自行验证。

九、一句话结论

Zvec 是本地/边缘 RAG 场景的最优选择之一——进程内运行、零配置、WAL 持久化、多语言 SDK 开箱即用，适合需要将向量检索嵌入应用本身、不想额外部署服务的团队；大规模云端检索仍建议用 Milvus/Qdrant。

推荐资源： - 官网：https://zvec.org - 快速开始：https://zvec.org/en/docs/db/quickstart/ - 官方文档：https://zvec.org/en/docs/db/ - 性能报告：https://zvec.org/en/docs/db/benchmarks/ - Zvec Studio（可视化工具）：https://github.com/zvec-ai/zvec-studio - Discord 社区：https://discord.gg/rKddFBBu9z