zvec

志士惜日短，愁人知夜长。——傅玄

Zvec：轻量、极速、可嵌入的向量数据库，用起来就是“爽”

当你在做 RAG、语义检索或个性化推荐时，常常会纠结：要不要起一个向量数据库服务、怎么部署、如何兼顾性能和易用性。Zvec 给出了一个非常优雅的答案——把向量库做成“在进程内使用”的开发者友好形态，直接嵌入到你的应用里，不需要额外的服务进程，也没有复杂配置。它由阿里巴巴开源，底层基于成熟的 Proxima 向量检索引擎，开箱即用却又具备生产级的低延迟与可扩展性。

官方一句话描述：A lightweight, lightning-fast, in-process vector database。

主页与文档：

• Home: https://zvec.org/en/
• Quickstart: https://zvec.org/en/docs/quickstart/
• Docs: https://zvec.org/en/docs/
• Benchmarks: https://zvec.org/en/docs/benchmarks/

许可证：Apache 2.0

---

为什么是 Zvec？

把向量数据库做成一个“在进程内的库”，意味着：

• 无需独立服务与网络通信，调用成本与时延都更低。
• 使用门槛极低，在脚本、微服务、Notebook、命令行工具甚至边缘设备都能落地。
• 部署与运维简化，尤其适合单机或嵌入式场景。

Zvec 将这一形态做到“能打能跑”：既轻量，又“闪电般快速”。如果你在做下面这些事情，Zvec 非常契合：

• RAG 场景的本地向量检索
• 个性化推荐、相似内容发现
• ANN（近似最近邻）搜索实验与小规模生产
• 在边缘或资源受限环境部署语义搜索能力

---

核心特性一览

根据官方 README 的特性列表，Zvec提供：

• Blazing Fast：毫秒级检索“亿级”向量规模（官方定位为“搜索数十亿向量在毫秒级内完成”）。
• Simple, Just Works：安装后即可用，几乎没有额外配置成本。
• Dense + Sparse Vectors：同时支持稠密与稀疏向量，原生支持“一次调用里多向量查询”的能力。
• Hybrid Search：可将语义相似度与结构化过滤结合，提升检索精准度。
• Runs Anywhere：作为进程内库，能在 Notebook、服务端、CLI、边缘设备等“代码所在的地方”运行。

背书：构建于阿里巴巴的 Proxima，长期在内部真实业务中打磨和验证。

---

安装与平台支持

Python（要求 Python 3.10-3.12）：

pip install zvec

Node.js：

npm install @zvec/zvec

支持平台：

• Linux（x86_64、ARM64）
• macOS（ARM64）

如果你更喜欢从源码构建，官方文档提供了构建指南。

---

一分钟上手：Python 代码示例

下面这段来自官方 README 的“快速示例”，演示了如何：

• 定义集合与向量字段
• 创建并打开集合
• 插入文档
• 基于向量相似度进行查询

import zvec

# Define collection schema
schema = zvec.CollectionSchema(
    name="example",
    vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 4),
)

# Create collection
collection = zvec.create_and_open(path="./zvec_example", schema=schema)

# Insert documents
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]}),
])

# Search by vector similarity
results = collection.query(
    zvec.VectorQuery("embedding", vector=[0.4, 0.3, 0.3, 0.1]),
    topk=10
)

# Results: list of {'id': str, 'score': float, ...}, sorted by relevance
print(results)

这个示例非常直观：像操作本地库一样操作集合，插入数据后直接发起向量查询，得到按相关度排序的检索结果。

---

性能与基准：如何跑官方 Bench

官方 README 给出性能图与 Bench 文档链接；仓库中也包含配套的基准脚本与配置，帮助你复现实验。以下片段来自 tools/core/README.md，展示了构建与查询的典型配置。

构建配置（Builder 部分）：

BuilderCommon:
    BuilderClass: HnswStreamer
    BuildFile: /tmp/cohere/cohere_large_10m_zvec/cohere_train_vector_10m.zvec.vecs
    NeedTrain: true 
    TrainFile: /tmp/cohere/cohere_large_10m_zvec/cohere_train_vector_10m.zvec.vecs
    DumpPath:  /home/zvec/bench/config/cohere_train_vector_10m.dump.index
    IndexPath: /home/zvec/bench/config/cohere_train_vector_10m.index

    ConverterName: CosineInt8Converter
    MetricName: Cosine

    ThreadCount: 16

BuilderParams: 
    proxima.general.builder.thread_count: !!int 16
    proxima.hnsw.builder.thread_count: !!int 16

查询配置（Searcher 部分）：

SearcherCommon:
    SearcherClass: HnswStreamer
    IndexPath: /home/zvec/bench/config/cohere_train_vector_10m.index
    TopK: 1,10,50,100 
    QueryFile: /tmp/cohere/cohere_large_10m_zvec/cohere_test_vector_1000.new.txt
    QueryType: float 
    QueryFirstSep: ";" 
    QuerySecondSep: " "
    GroundTruthFile: /tmp/cohere/cohere_large_10m_zvec/neighbors.txt
    RecallThreadCount: 1
    BenchThreadCount: 16 
    BenchIterCount: 1000000000 
    CompareById: true

SearcherParams: 
    proxima.hnsw.streamer.ef: !!int 250

执行步骤（节选）：

• 构建索引：local_build_original ./build.yaml
• 召回评测：recall_original ./search.yaml
• 压测评测：bench_original ./search.yaml

完整的实验流程与数据准备、容器镜像等说明，请参考同目录 README 与官方 Bench 文档。

---

典型使用场景与实践建议

• RAG 与问答系统：将检索前置到本地，减少外部依赖与网络时延，快速迭代原型或轻量生产。
• 嵌入式应用：在 CLI 工具、桌面应用、边缘设备中直接加载与查询向量。
• 个性化推荐与去重：利用相似度检索快速发现相似内容或候选集合。
• 混合检索：在语义相似度基础上，叠加结构化过滤，兼顾相关性与可控性。

实践建议：

• 初期直接使用 Python 包即可快速体验。
• 如果追求极致性能，建议参考官方 Bench 配置与构建流程。
• 保持向量数据的维度、类型与度量一致，便于指数构建与查询优化。
• 结合你现有的业务数据结构，评估 Hybrid Search 的过滤字段设计。

---

社区与参与

• Discord: https://discord.gg/rKddFBBu9z
• X (Twitter): https://x.com/zvec_ai
• 贡献指南：仓库内提供 CONTRIBUTING.md
• 话题标签：ann-search、embedded-database、rag、vector-search、vectordb

Zvec 欢迎社区贡献，包含修复问题、功能提案与文档改进。

---

总结

Zvec 把“向量数据库”这件事做到了真正的工程实用主义：不折腾部署、不牺牲性能、API 简洁明确。对于追求低延迟、易集成、可快速迭代的团队与个人开发者，它几乎是理想选择。先在本地把检索跑起来，再按需扩展到更大的数据量与更复杂的查询场景——这正是 Zvec 设计的初衷与价值。

如果你也在探索把语义检索能力落到真实应用里，不妨从上面的“一分钟示例”开始，感受一下“在进程内”的速度与顺滑。