🚀 快速入门 | 🏠 首页 | 📚 文档 | 📊 基准测试 | 🔎 DeepWiki | 🎮 Discord | 🐦 X（Twitter）

Zvec 是一个开源的进程内向量数据库——轻量级、极速响应，专为直接嵌入应用程序而设计。它基于 Proxima（阿里巴巴久经考验的向量搜索引擎）构建，只需极少的配置即可提供生产级别的低延迟、可扩展的相似性搜索能力。

💫 核心特性

• 极速响应：可在毫秒级内搜索数十亿条向量。
• 简单易用：安装后几秒钟即可开始搜索。无需服务器、无需配置、无需繁琐操作。
• 稠密与稀疏向量支持：同时支持稠密和稀疏嵌入，并原生支持在单次调用中进行多向量查询。
• 混合搜索：将语义相似度与结构化过滤器结合，获得精准的结果。
• 随处运行：作为进程内库，Zvec 可以在任何运行代码的地方使用——笔记本、服务器、命令行工具，甚至边缘设备。

📦 安装

Python

要求：Python 3.10 - 3.14

pip install zvec

Node.js

npm install @zvec/zvec

✅ 支持平台

• Linux (x86_64, ARM64)
• macOS (ARM64)

🛠️ 从源码构建

如果您希望从源码构建 Zvec，请参阅 从源码构建 指南。

⚡ 一分钟示例

import zvec

# 定义集合模式
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
)

# 结果：按相关性排序的 {'id': str, 'score': float, ...} 列表
print(results)

📈 大规模性能表现

Zvec 提供卓越的速度和效率，非常适合高负载的生产环境。

有关详细的基准测试方法、配置及完整结果，请参阅我们的 基准测试文档。

🤝 加入我们的社区

❤️ 贡献

我们欢迎并感谢社区的贡献！无论您是修复 bug、添加新功能，还是改进文档，您的帮助都能让 Zvec 更加完善，惠及所有人。

请查看我们的 贡献指南，开始参与吧！

Zvec 快速上手指南

Zvec 是一款由阿里巴巴开源的轻量级、进程内向量数据库。它基于阿里生产级向量搜索引擎 Proxima 构建，无需部署独立服务器，可直接嵌入应用程序中，提供毫秒级的低延迟相似性搜索能力。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：
  • Linux (支持 x86_64, ARM64 架构)
  • macOS (支持 ARM64 架构)
• 语言版本（任选其一）：
  • Python: 3.10 ~ 3.14
  • Node.js: 最新稳定版

安装步骤

根据您的开发语言选择对应的安装命令。

Python 用户

使用 pip 进行安装：

pip install zvec

Node.js 用户

使用 npm 进行安装：

npm install @zvec/zvec

提示：如果下载速度较慢，可尝试配置国内镜像源（如阿里云或清华大学镜像源）加速安装。

• Python: pip install zvec -i https://mirrors.aliyun.com/pypi/simple/
• Node.js: npm config set registry https://registry.npmmirror.com

基本使用

以下是一个完整的 Python 示例，演示如何在 1 分钟内完成从创建集合、插入数据到向量检索的全过程。

import zvec

# 1. 定义集合 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]}),
])

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

# 5. 输出结果 (按相关性排序)
print(results)

代码说明：

• 无需服务器：数据直接以文件形式存储在本地路径。
• 自动管理：create_and_open 会自动处理文件的创建与加载。
• 即时检索：插入后即可立即进行高精度的向量查询。